Format and Modification of a man Page

Sections of a man page

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.

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.

Otherwise, sections simply contain paragraphs, possibly with font changes. 

nroff Formatting Directives

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.

.br  break 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.)

.sp X  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

.in X  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:

is rendered

This is an example of alternating fonts 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 ...

.I stuff ...

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

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:

This is rendered

hello there charlie how are you

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.)

Let's rewrite our example above using our new alternating fonts macros, and introduce an extra trick:

This is
.IR "an example" \0of
.B alternating
.IR types \0for \0emphasis .

Important man macros

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.

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. 

Let's look at a simple man page section and get our feet wet:

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:

   Options
       mkdir recognizes the following command-line options:

              -t tag   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  by
                       dirname  (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. 

Author: Greg Boyd.