(TXT) View source
# Writing Effective Manual Pages
Larry Kollar
Manual pages (or manpages) are an important, if not essential, part
of UNIXsoftware documentation. This document discusses the
challenges and benefits of this time-tested documentation format, and
provides hints and tips for creating documents that are readable and
display well under a variety of conditions.
This document is not about the mechanics of the man or mdoc macro
packages; see the Writing Manpages HOWTO for a good tutorial.
(HTM) Writing Manpages HOWTO
# Table of contents
1. Background
1.1. Common Conventions
1.2. Why Manpages are Still Relevant in the 21st Century
1.3. Software Related to Manpages
2. One Source, Myriad Outputs
2.1. Challenges
3. General Hints and Tips
3.1. Content is King
3.1.1. Start at the Top
3.1.2. Make the Synopsis Useful
3.1.3. Include Examples
3.2. Avoid Raw groff Markup
3.3. Short as Possible, Long as Necessary
3.3.1. Separate Manpages by Section
3.3.2. Separate Manpages by Function
3.3.3. Full and Short Versions
3.4. Use Subsections Where Necessary
3.5. Use Tables Sparingly
3.6. Use Other Preprocessors Even More Sparingly
4. Conditional Pagination
5. Testing
6. Conclusion
7. Miscellany
7.1. History
7.2. Acknowledgments
7.3. Legalese
# 1. Background
The earliest manpages extant as of mid-2004 are from UNIX3rd Edition,
dated February 1973. [1]
> [1] Barring the existence of an as-yet undiscovered tape in a
> dusty storage room somewhere, the manpages are all that survives of
> UNIX3rd Edition.
They may be found at the TUHS archive.
In those days, UNIXdocumentation consisted primarily of the manpages
collected into a printed book, using a permuted or KWIC (Key Word In
Context) index to provide both table of contents and index. A few
articles from the Bell System Technical Journal (BSTJ) and
miscellaneous papers rounded out the collection. However, since
manpages were also stored on the system's disk drive, they also
provided a rudimentary "help" system.
# 1.1. Common Conventions
The storage constraints of early UNIXsystems, as well as display
constraints (the typical display was a 24−line "dumb terminal"),
led to a set of manpage conventions that has largely survived to the
present day:
* A manpage should be short and complete. Tiny displays (by
today's standards) and the limits of human short-term memory
allowed for little more.
* Information only peripherally related to the subject was not
included in a manpage--that is, glossaries, tutorials,
bibliographies, and similar information became part of the
miscellaneous papers and (perhaps) referred to as needed.
* A manpage should describe any bugs or other limitations that a
user might see under normal circumstances. In some circles, this
is called the "Principle of Least Surprise." This requirement made
for more satisfied users--and often led to better programs, as
developers might prefer fixing bugs to admitting their existence.
# 1.2. Why Manpages are Still Relevant in the 21st Century
There are several reasons that manpages are still an essential part
of UNIXafter over 30 years:
* Of all the different documentation systems available on
UNIX,manpages are the most likely to be installed and nearly always
installed.
* Long-time users expect manpages to be available. A program that
is missing a manpage, or has a manpage that simply points the
reader to an info or off-site HTMLdocument, is considered highly
annoying. HTMLand info documents are not universally unwelcome,
but should be considered supplementary rather than replacements.
* The manpage format is still the only lightweight, widespread
document format that can be displayed on a text screen, printed, or
converted to HTMLwithout a great deal of work or conversion
glitches.
* While a well-written manual can supplement a manpage, there is no
search facility like apropos that indexes a library of documents.
In addition, the directories used for storing manuals vary wildly
from system to system.
# 1.3. Software Related to Manpages
Most UNIXsystems include the following manpage-related utilities:
* man - Displays manpages on a terminal or text console, formatting
the manpage using nroff when necessary. Some versions of man can
also typeset manpages using troff.
* groff - Formats manpages using the man macro package. Groff
supports output to text, PostScript, HTML,and several
non-PostScript printers.
* apropos and whatis - Displays a list of manpages with the
specified keywords (which can be regular expressions). Whatis
matches only on complete words, while apropos supports partial-word
searches.
* makewhatis - Builds the manpage search database.
# 2. One Source, Myriad Outputs
The man macro package is an early method of single sourcing, a
documentation technique that allows writers and publishers to publish
documents in multiple formats--printed and on-line--without changing
the document source code. [2]
> [2] In terms of longevity and number of documents produced, it is
> easily the most successful single-sourcing technique as well.
For example, typing man ls at a shell prompt immediately shows the
documentation for the ls command. The man command formats the manpage
source and displays it in the shell window. [3]
> [3] Many systems cache the formatted manpage, allowing man to
> skip the formatting step after the first request.
Using the -t option (as in man -t ls | lpr) on some systems typesets
the manpage source for a PostScript printer. Thus, manpages provide
source for both on-line help and typeset documents.
A variety of other methods are available for displaying manpages,
again without changing the manpage source:
* The groff typesetting system, the de facto replacement for troff,
provides an HTMLoutput "device" for generating HTMLfrom manpage
source.
* Several UNIXbrowsers support URLs such as man:ls for reading and
displaying manpages. They recognize references to other manpages
and convert them to links.
* Applications such as xman or TkMan simulate (to a point) printed
output in a graphical interface.
* A variety of scripts are available from the Internet for direct
conversion from manpage format to HTMLor even DocBook.
# 2.1. Challenges
While having several major output formats to choose from is a great
advantage, there are several challenges to writing a manpage that
works well in all circumstances:
* Text-only output (as produced by the man command) is difficult to
read once the manpage exceeds a certain length (the exact length is
debatable, but is probably less than 10 printed pages).
* While there are no specific prohibitions against using groff
preprocessor output (including tbl, eqn, and pic) in a manpage, the
output may not be useful in many situations. The xman command in
particular has trouble displaying tables.
Even if you can ignore these problems, printed output has its own
challenges:
* Standard paper sizes differ depending on locale (for example,
8.5x11 inch in North America vs. A4 in most other countries).
Printing to a bound book introduces even more page sizes, including
paperback pocket reference and 7x9 inch format (used by O'Reilly
and many other publishers).
* You cannot assume even basic typesetting parameters, such as
typeface (font) or point size, are constant. For example, the
command groff -man -fBM -rS11 foo.n | lpr prints the manpage using
the Bookman Medium typeface in 11 point type.
* Many people have printers that do not support PostScript.
* People may alter man.local to change the default manpage layout.
Fortunately, groff can handle all but the most oddball layouts on its
own with a minimum of help. Indeed, the best way to get good output
usually is to simply allow groff to handle things. The trick is to
guide rather than force the typesetting process.
# 3. General Hints and Tips
Keep these hints and tips in mind when writing effective manpages.
# 3.1. Content is King
An effective manpage contains the information necessary for readers
to make best use of the program. While the types and order of
content expected stem from long-standing convention, there are
several places where a little thought and work can make a big
difference.
# 3.1.1. Start at the Top
The first body text in any manpage--that is, the line following the
.SH Name line--is the name of the manpage and a brief description of
its subject. The makewhatis program uses this text to build a search
index; whatis and apropos read the index.
Therefore, consider carefully the content of this line: it must be a
short, clear description of the subject; and it must provide hooks
for searching. Think about what keywords that readers would give to
apropos to find your manpage, work them into the description, and
make it all fit on one line.
# 3.1.2. Make the Synopsis Useful
If there are several ways to use your program, list each way
separately in the Synopsis section of your manpage. For example, the
BSD version of cp(1) shows separate commands for file-to-file and
file-to-directory copies. Not only is it easier on the reader, it is
easier to write than trying to compress two ideas into a single line.
# 3.1.3. Include Examples
One or two brief examples can serve to illuminate a procedure that
might otherwise be difficult to explain.
# 3.2. Avoid Raw groff Markup
Sometimes, you may be tempted to use raw groff requests or inlines to
make the output look a little better. While man can deal with them
(since it uses groff to do the formatting), readers may run into
problems when using a man-enabled browser to display the document.
Translation programs may have a hard time dealing with raw markup as
well. As mentioned earlier, attempting to force groff to do
something in a particular way can have unintended effects.
In nearly all cases, the man macros provide proper formatting,
eliminating the need for typographical bon mots. For example, format
a reference to another manpage using the macro .IR ls (1) rather than
using inline font changes like \fIls\fR(1). Similarly, use the .TP
macro rather than .in and .ti requests to format list items. See
groff_man(7) for a complete list of available formatting macros.
There are several exceptions to the rule, described in sections
following.
# 3.3. Short as Possible, Long as Necessary
In 1973, meeting the "short and complete" requirement was fairly
simple: the two largest manpages in the UNIX3rd Edition archive are
ed(1) and sh(1). If printed on a typesetter, ed(1) may have run 5
pages and sh(1) would have run about 4 pages. Nowadays, it is not
uncommon for manpages to run dozens of pages (see the bash(1) manpage
for an example).
As mentioned earlier, readers can easily lose their place in long,
unfamiliar manpages when using the man command. However, many
long-time UNIXusers expect to find any reference information about a
command in its manpage and get annoyed if items are missing.
Balancing these needs when an application gets complex can be
difficult.
There are several possible ways to provide manpages that work for
most people. Some of these methods are conventional, some are not.
# 3.3.1. Separate Manpages by Section
For example, your foo program might use a particular file format.
Instead of discussing the program and the file format in the same
manpage, create a foo(1) manpage describing the program, and a foo(5)
manpage describing the file format. [4]
> [4] The actual section number may vary. Linux and BSD use
> section 5 to describe file formats, while traditional UNIX uses
> section 4. A later version may cover this topic more thoroughly.
# 3.3.2. Separate Manpages by Function
Some writers split large manpages to cover separate functions; perl
(over)uses this method. If you use this approach, limit it to no
more than two or three manpages.
# 3.3.3. Full and Short Versions
A seldom-used but potentially effective method involves creating both
full and short versions of the manpage. The common pitfalls to using
this method are:
* Maintaining two completely separate manpages is extra effort and
can result in diverging information if not handled properly. One
way to avoid this problem is to use nroff and make to create two
manpages from a common base document as shown below.
* Using the short version as the default. As mentioned earlier,
experienced UNIXusers expect manpages to cover everything. Make
the full version the default manpage and mention the short version
near the beginning.
The following is an example of a master manpage that can be processed
to create full and short versions.
.cc @
@ec |
@nf
@ie rSHORT .TH foo_short 1
@el .TH foo 1
.SH Name
foo −the canonical example
.SH Synopsis
.B foo
.RB [ -b ]
.RB [ -a ]
.RB [ -r ]
@if !rSHORT |{|
.RB [ -q ]
.RB [ -x ]
.RB [ -z ]
@|}
.RI [ file ...]
.SH Description
The
.B foo
program reads a file and processes it.
@ie rSHORT |{|
This document is a quick reference,
describing only basic features; see
.IR foo (1)
for a complete description.
.|}
@el |{|
For a quick reference to
.BR foo ,
see
.IR foo_short (1).
@|}
.P
And so it goes...
An example Makefile fragment that creates the manpages would resemble
the following:
manpages: foo.n foo_short.n
foo.n: foo_master.n
nroff -Tlatin1 foo_master.n | sed -e '/^$/d' > foo.n
foo_short.n: foo_master.n
nroff -Tlatin1 -nSHORT=1 foo_master.n |\
sed -e '/^$/d' > foo_short.n
The sed command in the pipeline removes blank lines from the nroff
output.
# 3.4. Use Subsections Where Necessary
In some cases, there may not be any way to minimize your document.
One way to make such a manpage easier to follow is to organize it
into subsections and use the .SS macro to add subheadings. See the
groff_ms(7) manpage in version 1.18.1 or later versions of groff for
an example.
# 3.5. Use Tables Sparingly
Tables are useful for organizing data, but wider tables do not
display well on a text screen due to line-wrapping. For HTML output,
groff currently converts tables to PNG images.
Keep the following in mind when creating tables for manpages:
* You can usually replace two-column tables with the .TP macro.
* Avoid over-using vertical lines to separate columns (specified by
the allbox option or as a vertical bar in the column specification
section). Vertical lines use a great deal of space in a
text-formatted table.
* Horizontal lines may be useful to organize groups of table rows,
if the table is very long.
Again, the groff_ms(7) manpage in version 1.18.1 or later versions of
groff provides examples.
# 3.6. Use Other Preprocessors Even More Sparingly
Besides tbl, the two most common preprocessors are pic (to generate
line drawings) and eqn (to format equations). While they work with
printed output, programs like xman are known to have problems with at
least some instances of pictures or equations. In addition, neither
do very well on text displays (nroff, man). If you must use them at
all, make them conditional.
There are a handful of other preprocessors, either part of the groff
distribution or compatible with it (gremlin, grap, and others).
However, these preprocessors have the same limitations as do eqn and
pic. Some systems may not even have them installed. Avoid using
these preprocessors at all unless absolutely necessary.
# 4. Conditional Pagination
The .ne request is convenient for creating conditional pagination,
and is indeed one of the few low-level requests that can be used
without problems in manpages. The simplest form is a construct like
.ne 6, which forces a page break if less than six lines (or 6v)
separate the current vertical position from the beginning of the
footer. [5]
> [5] Actually, from the vertical position to the next trap, but
> for manpages they should be the same.
If there is more distance available than what you require, the
request has no effect.
You can also specify an absolute distance like .ne 1i, but in most
cases specifying the number of lines works better since line height
changes with the point size.
# 5. Testing
All the different combinations of font, point size, page size, and
output media can add up to dozens--if not hundreds--of possibilities.
However, you should at least try the following four methods:
* nroff -man foo.man | less (normal on-screen version)
* groff -man foo.man | lpr (normal printed version)
* groff -man -rS12 foo.man | lpr ("large print" version)
* groff -man -Thtml foo.man > foo.html (HTMLversion)
Don't forget to add preprocessor options, if necessary. Naturally,
you can replace the pipelines for the printed versions with a
redirect and check the PostScript output with gv or some other online
viewer.
You should also test your manpage under conditions that you could
reasonably expect your audience to see. For example, if your
software is aimed toward KDE users, test the manpage with Konqueror.
If the pagination and output look correct for these, you may want to
try variations on font and point size; try different page sizes if
time allows. If you can reasonably test different printer outputs
such as -Tlj4 or -Tlbp, by all means test them.
# 6. Conclusion
Technical writing, even--or especially--for short documents like
manpages, is both art and science. The goal is to provide needed
information without overwhelming your audience. By carefully
controlling document content, you can create more useful manpages
with a minimum of extra effort.
# 7. Miscellany
# 7.1. History
* 26 Apr 2004
V0.5, first public draft.
* 20 May 2004
V0.6, extensive changes based on voluminous feedback from the
grofflist.
* 7 June 2004
V1.0, first common release.
# 7.2. Acknowledgments
Thanks to the many people on the groff list who provided feedback and
encouragement, including Meg McRoberts, Alejandro López-Valencia,
Pete Phillips, Clarke Echols, and others.
# 7.3. Legalese
Copyright ©2004 by Larry Kollar. Copying and distribution of this
paper are allowed under the terms of either the GNU Free
Documentation License (FDL) or the Creative Commons Attribution
License.
(HTM) Source