https://bugzilla.redhat.com/show_bug.cgi?id=2016693 --- Comment #11 from Ben Beasley <code@xxxxxxxxxxxxxxxxxx> --- Created attachment 1838179 --> https://bugzilla.redhat.com/attachment.cgi?id=1838179&action=edit Simple man page Here’s how I wrote a man page: First, I got the --help output. Either: > $ curl -O https://pagure.io/python-glymur/raw/main/f/python-glymur-0.9.4-7.fc36.src.rpm > $ mock -r fedora-rawhide-x86_64 --rebuild python-glymur-0.9.4-7.fc36.src.rpm > $ mock -r fedora-rawhide-x86_64 -i /var/lib/mock/fedora-rawhide-x86_64/result/python3-glymur-0.9.4-7.fc36.noarch.rpm > $ mock -r fedora-rawhide-x86_64 --chroot -- jp2dump --help | tee jp2dump.txt (The -- in the last command tells mock to stop parsing options, so that --help is treated as part of the command to run in the chroot rather than as an option to mock. In this case I could have quoted 'jp2dump --help' instead.) Or: > $ python3 -m venv _e, w > $ . _e/bin/activate > (_e) $ pip install glymur > (_e) $ glymur --help | tee jp2dump.txt > (_e) $ deactivate > $ rm -rf _e Now, I translate manually to groff_man(7) format (https://man7.org/linux/man-pages/man7/groff_man.7.html, or “man groff_man”). Sometimes you’ll also see groff_mdoc(7) format, which has semantic macros that let you write the man page at a higher level. This is a nice idea, but the tradeoff is that the macro language is much larger than groff, so I find the learning curve for understanding and working with these man pages is higher, and it’s (again, in my opinion) harder to handle situations that weren’t foreseen in the design of the macros. I prefer the simpler groff format even if it requires more manual formatting. See also groff_man_style(7) (https://man7.org/linux/man-pages/man7/groff_man_style.7.html) and also man-pages(7) (https://man7.org/linux/man-pages/man7/man-pages.7.html), which describes the conventional structure of man pages. The man page starts with a title heading macro: > .TH title section [footer-middle] [footer-inside] [header-middle] In this case, we want section 1 for user commands, so a reasonable first line of our “jp2dump.1” looks like: > .TH JP2DUMP "1" "October 2021" "" "User Commands" Now we need a NAME section with the command name and a very short description. After consulting the --help output > usage: jp2dump [-h] [-x] [-s] [-c LEVEL] filename > > Print JPEG2000 metadata. we can write > .SH NAME > .B jp2dump > \(en print JPEG2000 metadata I like having an em dash instead of a hyphen-minus, and having a bold command name. However, this would have been fine too: > .SH NAME > jp2dump \- print JPEG2000 metadata The difference between - and \- is that the latter is non-breaking (it is not used as a breakpoint in automatic line wrapping). Now we need a SYNOPSIS. That starts like: > .SH SYNOPSIS > .B jp2dump > .RB [ \-h ] The last line is using an alternating format macro. Tokens alternate between plain (”Roman”) and bold formats, and whitespace in the line is collapsed, so we would have to backslash-escape any actual spaces. (As with the hyphen-minus, that would also keeps the space from being used for line breaking.) It’s also possible to use inline formatting directives, which would look like: > [\fB\-h\fR] We could also mix the two formatting approaches. Now we write the rest of the options in the synopsis: > .RB [ \-c ] > .RB [ \-s ] > .RB [ \-c\ \fILEVEL ] > .I filename Normally a DESCRIPTION section would come next, but we don’t have anything else to say about the command, so we move straight on to OPTIONS. Here I’ve chosen to mirror the structure of the help output using subsections (.SS). We use a tagged paragraph (.TP) for each option. > .SH OPTIONS > .SS "POSITIONAL ARGUMENTS" > .TP > .I filename > .SS "OPTIONAL ARGUMENTS" > .TP > .BR \-h ,\ \-\-help > show a help message and exit > .TP > .BR \-x ,\ \-\-noxml > suppress xml (default: > .BR False ) > .TP > .BR \-s ,\ \-\-short > only print box id, offset, and length (default: > .BR False ) > .TP > .BR \-c\ \fILEVEL ,\ \-\-codestream\ \fILEVEL > Level of codestream information. > .B 0 > suppresses all details, > .B 1 > prints the main header, > .B 2 > prints the full codestream. > (default: > .BR 1 ) This is just more of the same, copying the --help output nearly verbatim, with added macro directives for structure and legibility. I’ve followed common convention by making placeholder names italic (underlined in a terminal) and literal options and parameter values bold. One quirk of man pages is that, for correct formatting, there should always be a line break after the period at the end of any sentence. This shows up in the description for -c/--codestream. Finally, let’s cross-reference the similar command offered by OpenJPEG: > .SH "SEE ALSO" > .BR j2k_dump (1) I can test my man page with > man ./jp2dump.1 Looks good! ----- To add the man page to the package, add it as an additional source: > # Written by hand for Fedora in groff_man(7) format based on --help output > Source1: jp2dump.1 You’ll have to commit it to the dist-git repository. Then you can add to %prep: > cp -p '%{SOURCE1}' . to %install: > install -t '%{buildroot}%{_mandir}/man1' -d -p -m 0644 jp2dump.1 and to %files: > %{_mandir}/man1/jp2dump.1* Note the wildcard, which allows the man page compression format to change from gz to something else in the future. If you liked, I suppose you could drop the “cp” in %prep and install directly from the source file: > install -t '%{buildroot}%{_mandir}/man1' -d -p -m 0644 '%{SOURCE1}' ----- There is also a program “help2man” that can be used to automatically generate man pages from --help output during the RPM build. Its output is sometimes usable, although—where feasible—a hand-written man page is almost always nicer. -- You are receiving this mail because: You are always notified about changes to this product and component You are on the CC list for the bug. https://bugzilla.redhat.com/show_bug.cgi?id=2016693 _______________________________________________ package-review mailing list -- package-review@xxxxxxxxxxxxxxxxxxxxxxx To unsubscribe send an email to package-review-leave@xxxxxxxxxxxxxxxxxxxxxxx Fedora Code of Conduct: https://docs.fedoraproject.org/en-US/project/code-of-conduct/ List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines List Archives: https://lists.fedoraproject.org/archives/list/package-review@xxxxxxxxxxxxxxxxxxxxxxx Do not reply to spam on the list, report it: https://pagure.io/fedora-infrastructure
