💾 Archived View for tilde.pink › ~bencollver › effman.gmi captured on 2022-07-16 at 15:30:43. Gemini links have been rewritten to link to archived content
⬅️ Previous capture (2022-06-03)
-=-=-=-=-=-=-
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:
There are several reasons that manpages are still an essential part of UNIXafter over 30 years:
Most UNIXsystems include the following manpage-related utilities:
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:
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:
Even if you can ignore these problems, printed output has its own challenges:
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:
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:
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