MAN(7)

NAME
man - macros to format man pages

SYNOPSIS
groff -Tacsii -man file ...

groff -Tps -man file ...

man [section] title

DESCRIPTION
This manual page explains the groff tmac.an 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).

PREAMBLE
The first command in a man page should be

    .TH title section date source manual,

where:

    title
        is the title of the man page (e.g., MAN),

    section
        is the section number the man page should be placed in (e.g., 7),

    date
        is the date of the last revision,

    source
        is related to the source of the command (e.g., GNU, NET-2, ABC Distribution, etc.), and

    manual
        is the title of the manual (e.g., Linux Programmer's Manual).

The manual sections are traditionally defined as follows:

    1   Commands (e.g., those commands that can be executed by the user from within a shell)

    2   System calls (e.g., those functions which must be performed by the kernel)

    3   Library calls (e.g., most of the libc functions, such as sort(3))

    4   Special files (e.g., files found in /dev)

    5   File formats and conventions (e.g., the format for /etc/passwd)

    6   Games

    7   Macro packages and conventions (e.g., a description of the standard file system layout, and this man page)

    8   System management commands (e.g., commands like mount(8), which only root can execute)

    9   Kernel routines (this is a non-standard manual section and is included because the source code to the Linux kernel is freely available under the GNU Public License and many people are working on changes to the kernel)

FONTS
In some conventions, command names and options are in bold face, file names and variable names are in italics, and the rest of the text is in Roman. Other conventions reverse the use of bold and italics. In general, you should try to make your usage consistent throughout a document. The commands to select the type face are given below:

.B  Bold

.BI Bold alternating with italics

.BR Bold alternating with Roman

.I  Italics

.IB Italics alternating with bold

.IR Italics alternating with Roman

.RB Roman alternating with bold

.RI Roman alternating with italics

.SB Small alternating with bold

.SM Small

Traditionally, each command can have up to six arguments, but the GNU version seems to remove this limitation. 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.

SECTIONS
Sections are started with .SH followed by the heading name. If the name contains spaces and appears on the same line as .SH, then place the heading in double quotes. Traditional headings include: NAME, SYNOPSIS, DESCRIPTION, OPTIONS, FILES, SEE ALSO, DIAGNOSTICS, BUGS, and AUTHOR. The only required heading is NAME, which should be followed on the next line by a one line description of the program:

    .SH NAME
    chess \- the game of chess

It is extremely important that this format is followed, and that there is a backslash before the single dash which follows the command name. This syntax is used by the makewhatis(8) program to create a database of short command descriptions for the whatis(1) and apropos(1) commands.

OTHER MACROS
Other macros include the following:

.DT Default tabs

.HP Begin hanging indent

.IP Begin paragraph with hanging tag. This is the same as .TP, except the tag is given on the same line, not on the following line.

.LP Same as .PP

.PD Set interparagraph distance to argument

.PP Begin a new paragraph

.RE End relative indent (indented paragraph)

.RS Start relative indent (indented paragraph)

.SS Subheading (like .SH, but used for a subsection)

.TP Begin paragraph with hanging tag. The tag is given on the next line. This command is similar to .IP

FILES
/usr/local/lib/groff/tmac/tmac.an
/usr/man/whatis

SEE ALSO
groff(1), man(1), whatis(1), apropos(1), makewhatis(8)