[Go to CFHT Home Page] Man Pages
Back to Software Index  BORDER=0Manpage Top Level
    MAN(7) manual page Table of Contents

Name

man - macros to format man pages

Synopsis

groff -Tascii -man file ...

groff -Tps -man file ...

man [section] title

Description

This manual page explains the groff an.tmac macro package (often called the man macro package). This macro package should be used by developers when writing or porting man pages for Linux. It is fairly compatible with other versions of this macro package, so porting man pages should not be a major problem (exceptions include the NET-2 BSD release, which uses a totally different macro package called mdoc; see mdoc(7) ).

Note that NET-2 BSD mdoc man pages can be used with groff simply by specifying the -mdoc option instead of the -man option. Using the -mandoc option is, however, recommended, since this will automatically detect which macro package is in use.

For conventions that should be employed when writing man pages for the Linux man-pages package, see man-pages(7) .

Title line

The first command in a man page (after comment lines, that is, lines that start with .\") should be

.TH title section date source manual

For details of the arguments that should be supplied to the TH command, see man-pages(7) .

Note that BSD mdoc-formatted pages begin with the Dd command, not the TH command.

Sections

Sections are started with .SH followed by the heading name.

The only mandatory heading is NAME, which should be the first section and be followed on the next line by a one-line description of the program:

.SH NAME
item \- description

It is extremely important that this format is followed, and that there is a backslash before the single dash which follows the item name. This syntax is used by the mandb(8) program to create a database of short descriptions for the whatis(1) and apropos(1) commands. (See lexgrog(1) for further details on the syntax of the NAME section.)

For a list of other sections that might appear in a manual page, see man-pages(7) .

Fonts

The commands to select the type face are:

Traditionally, each command can have up to six arguments, but the GNU implementation removes this limitation (you might still want to limit yourself to 6 arguments for portability’s sake). Arguments are delimited by spaces. Double quotes can be used to specify an argument which contains spaces. All of the arguments will be printed next to each other without intervening spaces, so that the .BR command can be used to specify a word in bold followed by a mark of punctuation in Roman. If no arguments are given, the command is applied to the following line of text.

Other macros and strings

Below are other relevant macros and predefined strings. Unless noted otherwise, all macros cause a break (end the current line of text). Many of these macros set or use the "prevailing indent." The "prevailing indent" value is set by any macro with the parameter i below; macros may omit i in which case the current prevailing indent will be used. As a result, successive indented paragraphs can use the same indent without respecifying the indent value. A normal (nonindented) paragraph resets the prevailing indent value to its default value (0.5 inches). By default a given indent is measured in ens; try to use ens or ems as units for indents, since these will automatically adjust to font size changes. The other key macro definitions are:

Normal paragraphs

Relative margin indent

Indented paragraph macros

Hypertext link macros

(Feature supported with groff only.) In order to use hypertext link macros, it is necessary to load the www.tmac macro package. Use the request .mso www.tmac to do this.