WritingManPages

From HerzbubeWiki
Jump to: navigation, search

Overview

This page contains information how one should go about writing a man page. If you don't know what a "man page" is, I recommend reading the Wikipedia article. As someone else puts it nicely:

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

Typical sections

The following sections can be found in a lot of man pages:

NAME 
The name of the command or function, followed by a one-line description of what it does.
SYNOPSIS 
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.
DESCRIPTION 
A textual description of the functioning of the command or function.
EXAMPLES 
Some examples of common usage.
SEE ALSO 
A list of related commands or functions.


Other sections

The following sections appear with varying frequency:

OPTIONS 
Discussion of a command's options.
EXIT STATUS 
xxx
EXIT CODE 
xxx
ENVIRONMENT 
xxx
KNOWN BUGS 
xxx
BUGS 
xxx
CAVEATS 
System V replacement of the BUGS section.
FILES 
xxx
AUTHOR 
xxx
REPORTING BUGS 
xxx
HISTORY 
xxx
COPYRIGHT 
xxx
NOTES 
xxx
LICENSE 
xxx


Formatting

troff

The default/historical formatting used for man pages is troff.

ack ack ack


nroff

ack ack ack


Generating man pages

help2man

help2man takes reasonably formatted output from a command's --help and generates a man page.

http://www.gnu.org/software/help2man/


pod2man

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.

Links:


latex2man

http://ctan.tug.org/tex-archive/support/latex2man/latex2man.html

Input:

  • LaTeX

Output:

  • troff formatted man page
  • HTML
  • TexInfo
  • LaTeX


rst2man

rst = "reStructured text"

http://docutils.sourceforge.net/sandbox/manpage-writer/rst2man.txt


docbook2X

http://docbook2x.sourceforge.net/


Doxygen

Doxygen is capable of generating man pages.

http://www.stack.nl/~dimitri/doxygen/starting.html


txt2man

Converts flat ASCII text to man page format.

http://mvertes.free.fr/


pandoc

Converts from various markup formats to various other formats. Among the output formats is "groff man page", the most important input is reStructured text.

http://johnmacfarlane.net/pandoc/


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.

RST Resources:

Primer 
http://docutils.sourceforge.net/docs/user/rst/quickstart.html
Quick Reference 
http://docutils.sourceforge.net/docs/user/rst/quickref.html


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


Sections

Use the following markup for section names: 

NAME
====


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

Example: 

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 [...]


Tables

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...


Lists

  • 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
Retrieved from "https://wiki.herzbube.ch/index.php?title=WritingManPages&oldid=5625"