The definitive documentation system for every Unix is manpages. (Much GNU software is documented fully in info pages instead, but manpages are so foundational that even those packages generally provide some sort of manpage.) What is a manpage, then?
A manpage is a text file, marked up with nroff commands, specifically using the man macro package. (Well, technically, using the tmac.an standard macro package -- t/nroff takes a -m option to specify which tmac.* macro package to use. Thus, man uses nroff -man.) A simple manpage (in this case, the yes(1) manpage from FreeBSD) looks something like this:
.Dd June 6, 1993 .Dt YES 1 .Os BSD 4 .Sh NAME .Nm yes .Nd be repetitively affirmative .Sh SYNOPSIS .Nm .Op Ar expletive .Sh DESCRIPTION .Nm Yes outputs .Ar expletive , or, by default, .Dq y , forever. .Sh HISTORY The .Nm command appeared in .At 32v .
This collection of difficult-to-read nroff commands, when formatted by nroff via the man command on my FreeBSD machine, looks something like this:
YES(1) FreeBSD General Commands Manual YES(1) NAME yes - be repetitively affirmative SYNOPSIS yes [expletive] DESCRIPTION Yes outputs expletive, or, by default, "y", forever. HISTORY The yes command appeared in Version 32V AT&T UNIX. 4th Berkeley Distribution June 6, 1993 1
The various nroff/man macros allow you to define things such as the name of the command, the short description of what it does, the list of arguments, and so forth, and formats it all into the standard look of a manpage. To write your own manpages, take a look at existing manpages for examples, and read the man(1) and man(7) manpages.
-- DJPH
Copyright © 2003 O'Reilly & Associates. All rights reserved.