sections in this module City College of San Francisco - CS260A
Unix/Linux System Administration

Module: The Unix Manual
module list

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.

section namecontentsformat
NAMEterse description using keywordsone line (no line breaks). This line forms the entry in the whatis database
SYNOPSISterse syntax including optionsone or more lines of syntax. Be specific. This section is the most sought-after as it is used to jar the memory.
DESCRIPTIONcomplete descriptionas many paragraphs as you like
OPTIONSdescription of each optionsome pages have the options documented in the DESCRIPTION section. Options may be a subsection instead.
EXAMPLESexamplesmay or may not appear. extremely helpful if options may interact.
BUGSgotchasyes, document bugs if a user could stumble on one. These are often things that the program just can't handle for some reason.
SEE ALSOlist of references to other man pagesmake sure these are in the correct format including section, e.g., chown(1)
RETURN VALUEdocuments return value 
FILESdocumentation 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

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

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:

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

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

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



.BI hello there charlie how are you

is rendered


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

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


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

.TH.TH name sectionused for the heading and, for some reason, required to get any of the other man macros to work!
.SH.SH sectionnamename of section
.SS.SS subsectionnamename of subsection. Subsection names are indented a few characters.
.PP.PPbegin new paragraph
.RS.RS ibegin relative margin indent of size i. If i is omitted, the default .5in is used
.TP.TP ibegin 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.REend relative margin indent
.IP.IPindented 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. 

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

man sourcerendered result
.TH mkdir 1
mkdir \- make a directory
.B mkdir
.RB [ -p ]
.RB [ -m
.IR mode\| ]
.RB [ -t
.IR tag ]
.IR dirname \0...
mkdir(1)                                    mkdir(1)

       mkdir - make a directory

       mkdir [-p] [-m mode] [-t tag] dirname ...


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:

       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

                       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. 

.SS Options
.B mkdir
recognizes the following command-line options:
.TP 9
.BI -t \0tag
Create a tag file in the directory with the name
.IR tag .
.B -p
Intermediate directories are created as necessary.
Otherwise, the full path prefix of
.I dirname
must already exist.
.B mkdir
requires write permission in the parent directory.
If the
.B -m
option is used, the directory specified by
.I dirname
(excluding directories in the pathname prefix)
is created with the permissions specified by
.IR mode .
subdirectories 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.

Prev This page was made entirely with free software on linux:  

Author: Greg Boyd.

Document made with Nvu