As
you should have seen when you did the preview question for this
section, man pages have standard sections. Below is the set of standard
sections. Note that there is nothing that requires these sections be
named as indicated - it is only a convention.

section name

contents

format

NAME

terse description using keywords

one line (no line breaks). This line forms the entry in the whatis database

SYNOPSIS

terse syntax including options

one
or more lines of syntax. Be specific. This section
is the most sought-after as it is used to jar the memory.

DESCRIPTION

complete description

as many paragraphs as you like

OPTIONS

description of each option

some pages have the options documented in the DESCRIPTION section. Options may be a subsection instead.

EXAMPLES

examples

may or may not appear. extremely helpful if options may interact.

BUGS

gotchas

yes, document bugs if a user could stumble on one. These are often things that the program just can't handle for some reason.

SEE ALSO

list of references to other man pages

make sure these are in the correct format including section, e.g., chown(1)

RETURN VALUE

documents return value

FILES

documentation of files associated with command

Updating man pages

nroff,
even with man macros, is ugly. Since this documentation language is
essentially dead, no one learns how to write man pages anymore. In fact,
many systems have their man pages generated from another documentation
language. On linux, some man pages are generated by help2man, which
creates a simple man page for program xxx by running xxx --help
and massaging the output into a man page. All of this is because noone
wants to learn nroff or to have to deal with maintaining man pages.

Having
said this, man pages are the help format used on Unix systems, and
previous efforts to force users to change to other tools, such as info,
have met with resistance. Every object released for command-line use on
Unix should have a man page.

This contradiction (dead language but
must use it sporadically) can be resolved by realizing that nroff, though
ugly, is very simple, and there are examples of the documentation of every
flavor of command or function readily available. This, coupled with the standardized structure
of a man page, makes it easy to

find an existing man page whose structure is similar to what you want

copy it

modify the copy and rename it

Thus
said, there are still a few things that you should know about nroff
-man to write (hack) documentation successfully. We will cover enough
to get you by. But let's start by listing the different formatting
structures commonly used in man pages

certain sections have
simple unique format and contents. The formatting directives for these
are in every man page - only the content needs modification. Examples:
the NAME and SEE ALSO sections. The SYNOPSIS section is similar,
although a bit of knowledge about font change directives helps here.

most man pages document options. The formatting of options is consistent between man pages; only the number of options changes.

Both
nroff and man macros formatting directives are indicated by a period in the
first column followed by one or two letters. nroff formatting directives are lower-case, while man
macros are upper-case. Formatting directives may have arguments, or may
be alone on a line. There are only a few nroff formatting directives
that are useful. We will discuss some of the man macros later.

.brbreak line. In modern word-processors, a hard return indicates
the end of the paragraph. Not so in nroff - paragraphs continue (and
text from lines continues to fill) until a line break directive
followed by a space directive (.sp) (if space is requested between
paragraphs.)

.spX space X vertically. X is a number
followed by units. Common units are in (inches), cm (centimeters), pt
(points). The default is characters. For example,

.sp .5in

leaves one-half inch of whitespace

.inX indent X. Again, X has units attached. To return to the
previous level of indentation, the directive .in (without an argument)
can be used.

font changes

man pages are displayed in a
single typeface - whatever the current system typeface is. However, man
pages often switch between the normal font of that face (the Roman font), the
italic font, and the bold font for emphasis. Note that the italic
font and the bold font may be rendered several ways depending on the
platform. For example, hills renders bold as reverse video, whereas
linux actually uses bold. The italic font may also be rendered as
underlined.

The man macros have several directives to alternate
fonts or to display some text in one of these fonts. The standard nroff
syntax for embedding font changes in text can, however, be very useful.
This consists of \fX where X is the font desired: R (roman), I
(italic), B (bold). X can also be P for previous. Let's look at a
simple example where the font is assumed to be the Roman font at the
beginning:

This is \fIan example\fP of \fBalternating \fIfonts\fR for \fIemphasis\fP.

is rendered

This is anexample of alternatingfonts for emphasis.

on linux.

man macros

For a more complete discussion of man macros, and of man page format in general, see man(7)

Before
we give a short table of the man macros most commonly seen in simple
man pages, let's look at the man macros for changing font:

.B stuff ...

.Istuff ...

These
two directives simply output the remainder of the line in bold (.B) or
italic. stuff ... is embedded in the current line and paragraph. In
other words, no break is implied.

Our previous example could be written using these macros as

This is.I an exampleof .B alternating.I fontsfor .I emphasis

The
above example is not exactly the same. It is missing the period at the
end of the sentence. This is because you would like the period to not
be in italics, but there is no way to do this with the .I/.B macros
(since it should not be separated from the word emphasis by a space and
a period at the beginning of the line will be interpreted as an nroff
command!)

There are several other man macros for alternating font
within a word (without using a space between the pieces). The macros
are .XY where X and Y are one of R, B or I. The interpretation is that
the words on the remainder of the line should be in the indicated
alternating fonts and the result glued together without spaces. Thus

.IR hello there charlie how are you

is rendered

hellotherecharliehowareyou

Similarly,

.BI hello there charlie how are you

is rendered

hellotherecharliehowareyou

Note: if we wanted spaces to separate each word above, we would have to use a 'trick'. Here it is:

.BI hello \0there \0charlie \0how \0are \0you

This is rendered

hellothere charlie how areyou

It's nice to know about charlie, but let's look at something more pertinent. The code

.RB { \-f | \-p | \-q }

is rendered

{-f|-p|-q}

(For some reason, the hyphen is always escaped, but it seems to work without it as well. Maybe it is platform-dependent.)

As
discussed in the previous page, the man macros are added via the -man
option to nroff. (On linux currently, another set of macros, the -mandoc
set is used.) In order to display as expected, the output must be paged
using less, and the man page must begin with the .TH macro below.

macro

format

meaning

.TH

.TH name section

used for the heading and, for some reason, required to get any of the other man macros to work!

.SH

.SH sectionname

name of section

.SS

.SS subsectionname

name of subsection. Subsection names are indented a few characters.

.PP

.PP

begin new paragraph

.RS

.RS i

begin relative margin indent of size i. If i is omitted, the default .5in is used

.TP

.TP i

begin
paragraph with hanging tag of length i. If i is omitted, the last .TP i
value is used. The hanging tag is the entire next line.

.RE

.RE

end relative margin indent

.IP

.IP

indented
paragraph. If the current paragraph is indented, start another one. If
the current paragraph is not indented, indent the next one.

The Options section of a man page is the most complicated section. It is
simply an RS/RE block with one or more TP's in between.

The
only surprising construct here are the escaped characters. \| doesn't
seem to do anything. As we saw previously, \0 places a space between
dirname and ... when they are processed. (Otherwise they would be
joined together.)

Let's look at the section that has to do with options. First, the rendered page:

Optionsmkdir recognizes the following command-line options:

-ttag Create a tag file in the directory with the name tag.

-p Intermediate directories are created as necessary.
Otherwise, the full path prefix of dirname must already
exist. mkdir requires write permission in the parent
directory.

If the -m option is used, the directory specified bydirname (excluding directories in the pathname prefix)
is created with the permissions specified by mode.

Only LINK_MAX subdirectories can be created (see limits(5)).

Now
the source code. In the code below, note the RS/RE block for the
options. This produces the indentation (up to the start of the tag
text) that starts after mkdir and continues to Only. The options are
each begun with a TP to start an indented paragraph with a hanging tag.
The first TP indicates how long the tag can be. The line following the
TP is the option text. Within an option, an IP starts a new paragraph
at the same level.

.SS Options.B mkdirrecognizes the following command-line options:.RS.TP 9.BI -t \0tagCreate a tag file in the directory with the name.IR tag ..TP.B -pIntermediate directories are created as necessary.Otherwise, the full path prefix of.I dirnamemust already exist..B mkdirrequires write permission in the parent directory..IPIf the.B -moption is used, the directory specified by.I dirname(excluding directories in the pathname prefix)is created with the permissions specified by.IR mode ..RE.PPOnly.B LINK_MAXsubdirectories can be created (see.IR limits (5)).

Preview question: There are many unknown repositories for other kinds of documentation on Linux systems. Check out the /usr/doc tree.