.\" Copyright 1992 Rickard E. Faith (faith@cs.unc.edu)
.\" May be distributed under the GNU General Public License
.\" See section COPYING for conditions for redistribution
.\" Modified Sun Jul 25 11:06:05 1993 by Rik Faith (faith@cs.unc.edu)
.TH MAN 7 "25 July 1993" "Linux" "Linux Programmer's Manual"
.SH NAME
man \- macros to format man pages
.SH SYNOPSIS
.B groff \-Tacsii \-man
.I file
\&...
.LP
.B groff \-Tps \-man
.I file
\&...
.LP
.B man
.RI [ section ]
.I title
.SH DESCRIPTION
This manual page explains the
.B "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
.B groff
simply by specifying the
.B \-mdoc
option instead of the
.B \-man
option.  Using the
.B \-mandoc
option is, however, recommended, since this will automatically detect which
macro package is in use.
.SH PREAMBLE
The first command in a man page should be
.RS
.sp
.B \&.TH
.IR "title section date source manual" ,
.sp
.RE
where:
.RS
.TP 0.8i
.I title
The title of the man page (e.g.,
.IR MAN ).
.TP
.I section
The section number the man page should be placed in (e.g.,
.IR 7 ).
.TP
.I date
The date of the last revision\(emremember to change this every time a
change is made to the man page, since this is the most general way of doing
version control.
.TP
.I source
The source of the command.
.sp
For binaries, use something like:
.IR GNU ", " NET-2 ", " "SLS Distribution" ", " "MCC Distribution" .
.sp
For system calls, use the version of the kernel that you are currently
looking at:
.IR "Linux 0.99.11" .
.sp
For library calls, use the source of the function:
.IR GNU ", " "BSD 4.3" ", " "Linux DLL 4.4.1" .
.TP
.I manual
The title of the manual (e.g.,
.IR "Linux Programmer's Manual" ).
.RE
.PP
The manual sections are traditionally defined as follows:
.RS
.TP 0.8i
.B 1 Commands
Those commands that can be executed by the user from within
a shell.
.TP
.B 2 System calls
Those functions which must be performed by the kernel.
.TP
.B 3 Library calls
Most of the
.I libc
functions, such as
.BR sort (3))
.TP
.B 4 Special files
Files found in
.IR /dev )
.TP
.B 5 File formats and conventions
The format for
.I /etc/passwd
and other human-readable files.
.TP
.B 6 Games
.TP
.B 7 Macro packages and conventions
A description of the standard file system
layout, this man page, and other things.
.TP
.B 8 System management commands
Commands like
.BR mount (8),
which only
.I root
can execute.
.TP
.B 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)
.RE
.SH FONTS
Although there are many arbitrary conventions for man pages in the UNIX
world, the existence of severl hundred Linux-specific man pages defines our
standards:
.IP
For functions, the arguments are always specified using italics,
.IR "even in the SYNOPSIS section" ,
where the rest of the function is specified in bold:
.RS
.BI "int myfunction(int " argc ", char **" argv );
.RE
.IP
Filenames are always in italics (e.g.,
.IR "/usr/include/stdio.h" ),
except in the SYNOPSIS section, where included files are in bold (e.g.,
.BR "#include <stdio.h>" ).
.IP
Special macros, which are usually in upper case, are in bold (e.g.,
.BR MAXINT ).
.IP
When enumerating a list of error codes, the codes are in bold (this list
usually uses the
.B \&.TP
macro).
.IP
Any reference to another man page (or to the subject of the current man
page) in in bold.  If the manual section number is given, it is given in
roman, without any spaces (e.g.,
.BR man (7)).

The commands to select the type face are given below:
.TP 0.8i
.B \&.B
Bold
.TP
.B \&.BI
Bold alternating with italics
.TP
.B \&.BR
Bold alternating with Roman
.TP
.B \&.I
Italics
.TP
.B \&.IB
Italics alternating with bold
.TP
.B \&.IR
Italics alternating with Roman
.TP
.B \&.RB
Roman alternating with bold
.TP
.B \&.RI
Roman alternating with italics
.TP
.B \&.SB
Small alternating with bold
.TP
.B \&.SM
Small
.LP
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
.B \&.BR
command can be used to specify a word in bold followed by a mark of
punctuation in Roman.
.SH SECTIONS
Sections are started with
.B \&.SH
followed by the heading name.  If the name contains spaces and appears
on the same line as
.BR \&.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
.IR NAME ,
which should be followed on the next line by a one line description of the
program:
.RS
.sp
\&.SH NAME
.br
chess \\- the game of chess
.sp
.RE
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
.BR makewhatis (8)
program to create a database of short command descriptions for the
.BR whatis (1)
and
.BR apropos (1)
commands.
.SH "OTHER MACROS"
Other macros include the following:
.TP
.B \&.DT
Default tabs
.TP
.B \&.HP
Begin hanging indent
.TP
.B \&.IP
Begin paragraph with hanging tag.  This is the same as
.BR \&.TP ,
except the tag is given on the same line, not on the following line.
.TP
.B \&.LP
Same as
.B \&.PP
.TP
.B \&.PD
Set interparagraph distance to argument
.TP
.B \&.PP
Begin a new paragraph
.TP
.B \&.RE
End relative indent (indented paragraph)
.TP
.B \&.RS
Start relative indent (indented paragraph)
.TP
.B \&.SS
Subheading (like
.BR \&.SH ,
but used for a subsection)
.TP
.B \&.TP
Begin paragraph with hanging tag.  The tag is given on the next line.  This
command is similar to
.B \&.IP
.LP
.SH FILES
.I /usr/local/lib/groff/tmac/tmac.an
.br
.I /usr/man/whatis
.SH SEE ALSO
.BR groff (1),
.BR man (1),
.BR whatis (1),
.BR apropos (1),
.BR makewhatis (8)