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 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).
Note that NET-2 BSD 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.
PREAMBLE
The first command in a man page should be
.TH title section date source manual,
where:
title The title of the man page (e.g., MAN).
section The section number the man page should be
placed in (e.g., 7).
date The date of the last revision-remember to
change this every time a change is made to the
man page, since this is the most general way of
doing version control.
source The source of the command.
For binaries, use something like: GNU, NET-2,
SLS Distribution,
For system calls, use the version of the kernel
that you are currently looking at: Linux
0.99.11.
For library calls, use the source of the
function: GNU, BSD 4.3, Linux DLL 4.4.1.
manual The title of the manual (e.g., Linux
Programmer's Manual).
The manual sections are traditionally defined as follows:
1 Commands
Those commands that can be executed by the user
from within a shell.
2 System calls
Those functions which must be performed by the
kernel.
3 Library calls
Most of the libc functions, such as sort(3))
4 Special files
Files found in /dev)
5 File formats and conventions
The format for /etc/passwd and other human-
readable files.
6 Games
7 Macro packages and conventions
A description of the standard file system lay-
out, this man page, and other things.
8 System management commands
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
Although there are many arbitrary conventions for man pages
in the UNIX world, the existence of several hundred Linux-
specific man pages defines our standards:
For functions, the arguments are always specified using
italics, even in the SYNOPSIS section, where the rest
of the function is specified in bold:
int myfunction(int argc, char **argv));
Filenames are always in italics (e.g.,
/usr/include/stdio.h), except in the SYNOPSIS section,
where included files are in bold (e.g., #include
<stdio.h>).
Special macros, which are usually in upper case, are in
bold (e.g., MAXINT).
When enumerating a list of error codes, the codes are
in bold (this list usually uses the .TP macro).
Any reference to another man page (or to the subject of
the current man page) is in bold. If the manual sec-
tion number is given, it is given in roman, without any
spaces (e.g., man(7)).
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. Argu-
ments are delimited by spaces. Double quotes can be used to
specify an argument which contains spaces. All of the argu-
ments 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 fol-
lows 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)