I now introduce a case study of a real-world manual, in particular the echo utility from OpenBSD. The original file may be viewed on-line at src/bin/echo/echo.1, file version 1.20. I choose this mainly because of its simplicity.
These initial comments are automatically created by the source-control system cvs, which fills in information about the last editor. I'll talk about revision control and those funny dollar-sign enclosures in Part 3. These particular comments indicate that the file was initially imported from NetBSD in 1995, where it was last edited by cgd (a system name, not the user's real name). It was last edited in OpenBSD, its current form, by jmc in 2010.
If you're keeping your manual under source control, it's usually a good idea to begin your file with a similar line.
A tab character separates the comment marker from the text. Again, this will be covered later in this book — don't worry if it looks strange.
This long comment is the license and copyright of the source file. Of course, our use of this source file is compatible with the license, as may be read from the text itself!
This comment is of historical note. The @(#) sequence was inserted by the sccs utility (Source Code Control System). Although this utility is part of POSIX.1-2008, it has mostly been replaced by cvs. You'll probably never encounter this string in your own manuals, so it's safe to disregard.
At this point the manual content itself begins.
This indicates that the manual's title is ECHO in category 1 (utilities) for the current installed operating system. The $Mdocdate$ enclosure is similar to that as defined at the top of the file with $OpenBSD$.
This documents a single command, the echo command, which does as mentioned.
The command accepts a single optional flag, n, and an arbitrary number of optional arguments string. Note that re-stating the command name for the Nm is superfluous in this case.
The DESCRIPTION opens with a brief explanation of the utility and its output. The strange set of backslash-escaped characters \ \& is required to make the doubly-nested macros Pq and Sq (parenthesise and single-quote, respectively) correctly enclose a single space.
This follows the standard form of documenting flags and arguments as a term/definition list. Each one — in this case only one — is documented in alphabetical order.
Notes the standard exit sequence. Note that the argument to Ex is superfluous, as only one command is listed for the manual.
Although these weren't cited in other sections of the manual, the author felt it necessary to link to them. This is probably because both csh and ksh include internal implementations of a function by the same name.
This last section fully describes the utility's conformance to the POSIX standard, which is very important to those writing portable utilities. The St macro expands into the relevant standard's full name, IEEE Std 1003.1-2008 (“POSIX.1”). For a full list of standards, consult your local documentation for the macro.
| Contents | Next | Home | History |
Last edited by $Author: kristaps $ on $Date: 2011/11/05 00:39:38 $. Copyright © 2011, Kristaps Dzonsons. CC BY-SA.