- 1 Overview
- 2 Content of a man page
- 3 Formatting
- 4 Generating man pages
- 5 Writing a man page in reStructured text
Most of the "rules" for writing a well formatted manpage are picked up by osmosis; by reading existing manpages and looking at the diffs committed by more experienced manpage authors.
Content of a man page
The following sections can be found in a lot of man pages:
- The name of the command or function, followed by a one-line description of what it does.
- In the case of a command, you get a formal description of how to run it and what command line options it takes. For program functions, a list of the parameters the function takes and which header file contains its definition.
- A textual description of the functioning of the command or function.
- Some examples of common usage.
- SEE ALSO
- A list of related commands or functions.
The following sections appear with varying frequency:
- Discussion of a command's options.
- EXIT STATUS
- EXIT CODE
- KNOWN BUGS
- System V replacement of the BUGS section.
- REPORTING BUGS
The default/historical formatting used for man pages is troff.
ack ack ack
ack ack ack
Generating man pages
help2man takes reasonably formatted output from a command's --help and generates a man page.
The POD format is Perl's method to embed documentation within the Perl source code. POD = "Plain Old Documentation". The pod2man utility can be used to generate man pages from POD documentation.
- troff formatted man page
rst = "reStructured text"
Doxygen is capable of generating man pages.
Converts flat ASCII text to man page format.
Converts from various markup formats to various other formats. Among the output formats is "groff man page", the most important input is reStructured text.
Writing a man page in reStructured text
This chapter contains notes about things that one should keep in mind when writing a man page using RST (reStructured text) markup. I made these notes while experimenting with pandoc 0.46, so your mileage may vary if you use a different generator such as rst2man, or a newer version of pandoc.
- Quick Reference
Generate + view a man page on the fly
pandoc -s -f rst -t man <input-file | iconv -f utf-8 -tlatin1 | groff -mandoc -Tlatin1 | less
Discussion of options:
- pandoc assumes that the input file is in UTF-8; if it is not, iconv can be used for conversion on input
- pandoc outputs UTF-8; iconv can be used to convert to latin1 which is used in the example by groff; if groff is run with -Tutf8 the result is not as satisfying
Use the following markup for section names:
The SYNOPSIS section
The synopsis often contains multiple lines to show how a program may be invoked in very different, mutually exclusive ways. For instance:
SYNOPSIS cp [OPTION]... [-T] SOURCE DEST cp [OPTION]... SOURCE... DIRECTORY cp [OPTION]... -t DIRECTORY SOURCE...
The problem here is that if the RST source contains multiple lines without intervening empty lines, these lines count as belonging to the same paragraph and in the generated man page will become concatenated instead of remaining on separate lines.
One solution is to put empty lines between each program invocation line. The generated man page will display program invocation lines as separate paragraphs with separating empty lines in between. This does not look good.
Another solution is to use a literal block ("::"). In the generated man page, the invocation lines are kept nicely together, but unfortunately the block is indented too much and is not aligned to the blocks of the other sections (NAME, DESCRIPTION, etc.). This also does not look good.
The final, and best, solution is to use line blocks, i.e. lines that begin with a vertical bar ("|"). The example above would be marked up as follows:
SYNOPSIS ======== | cp [OPTION]... [-T] SOURCE DEST | cp [OPTION]... SOURCE... DIRECTORY | cp [OPTION]... -t DIRECTORY SOURCE...
The OPTIONS section
RST recognizes option lists as a separate type of list (as compared to bullet lists, enumerated lists, etc.). Option lists consist of lists of program options (e.g. "-f", "--file") and are therefore ideally suited for the OPTIONS section of a man page.
- the usual stuff about short and long options applies
- option arguments can be listed normally (e.g. "-f FILE"), or with enclosing angle-brackets (e.g. "-f <FILE>")
- multiple option synonyms sharing a single description must be separated with comma (e.g. "-f FILE, --file FILE")
- for proper formatting on the generated man page, option and description must be listed on separate lines and the description must be indented; this opposes the RST documentation, where it merely says that option and description must be separated by 2 or more spaces
OPTIONS ======= -V, --version Print the version number. -h, --help Show a short usage summary.
Referring to options and option arguments
Program options and option arguments that do not appear within an option list are not automatically marked up in a special way. They must be marked up with "strong emphasis" (i.e. enclosing "**"). For instance:
Additional sources for the input are: a file (**--file**) or the command line (**--batch**). Note that [...]
Referring to sections
References to section names are not automatically marked up in a special way. They must be marked up with "strong emphasis" (i.e. enclosing "**"). For instance:
See **ALGORITHMS** below.
Also note that, opposed to the RST documentation, section headers are not automatically made available as link targets. I was unable to link to section headers, for instance by saying "ALGORITHMS_", but was forced to create an explicit internal hyperlink target.
Referring to the program name
The program name is not automatically marked up in a special way. It must be marked up with "strong emphasis" (i.e. enclosing "**"). For instance:
In the first synopsis form, the **cp** utility copies [...]
It seems as if pandoc does not parse RST tables at all! I was unable to mark up even a simple table and to generate HTML from that...
- Bullets in bullet lists appear as some kind of code (<B7>). This rendering makes bullet lists quite unusable for man pages.
- Enumerated lists and definition lists work just fine. List entries are separated by an empty line, as if they were separate paragraphs. Depending on the circumstances, this may or may not be what one wants, but I do not know a way around that.
- Field lists are not recognized by pandoc
- Option lists work as described further up in the chapter about the OPTIONS section