💾 Archived View for tilde.pink › ~bencollver › effman.gmi captured on 2022-03-01 at 15:38:50. Gemini links have been rewritten to link to archived content
-=-=-=-=-=-=-
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.
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
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.
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:
standards) and the limits of human short-term memory allowed for
little more.
included in a manpage--that is, glossaries, tutorials,
bibliographies, and similar information became part of the
miscellaneous papers and (perhaps) referred to as needed.
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.
There are several reasons that manpages are still an essential part
of UNIXafter over 30 years:
UNIX,manpages are the most likely to be installed and nearly always
installed.
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.
document format that can be displayed on a text screen, printed, or
converted to HTMLwithout a great deal of work or conversion
glitches.
search facility like apropos that indexes a library of documents.
In addition, the directories used for storing manuals vary wildly
from system to system.
Most UNIXsystems include the following manpage-related utilities:
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.
Formats manpages using the man macro package. Groff supports
output to text, PostScript, HTML,and several non-PostScript
printers.
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.
Builds the manpage search database.
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:
provides an HTMLoutput "device" for generating HTMLfrom manpage
source.
displaying manpages. They recognize references to other manpages
and convert them to links.
output in a graphical interface.
conversion from manpage format to HTMLor even DocBook.
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:
read once the manpage exceeds a certain length (the exact length is
debatable, but is probably less than 10 printed pages).
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:
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).
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.
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.
Keep these hints and tips in mind when writing effective manpages.
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.
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.
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.
One or two brief examples can serve to illuminate a procedure that
might otherwise be difficult to explain.
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.
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.
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.
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.
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:
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.
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.
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.
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:
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.
the table is very long.
Again, the groff_ms(7) manpage in version 1.18.1 or later versions of
groff provides examples.
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.
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.
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:
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.
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.
V0.5, first public draft.
V0.6, extensive changes based on voluminous feedback from the grofflist.
V1.0, first common release.
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.
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.
Source: https://web.archive.org/web/20191230171657/http://home.windstream.net/kollar/groff/effman.html