228 lines
4.9 KiB
Groff
228 lines
4.9 KiB
Groff
.\" 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
|
|
.TH MAN 7 "17 November 1992" "" "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).
|
|
.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
|
|
.I title
|
|
is the title of the man page (e.g.,
|
|
.IR MAN ),
|
|
.TP
|
|
.I section
|
|
is the section number the man page should be placed in (e.g.,
|
|
.IR 7 ),
|
|
.TP
|
|
.I date
|
|
is the date of the last revision,
|
|
.TP
|
|
.I source
|
|
is related to the source of the command (e.g.,
|
|
.IR GNU ", " NET-2 ", " "SLS Distribution" ", etc.),"
|
|
and
|
|
.TP
|
|
.I manual
|
|
is the title of the manual (e.g.,
|
|
.IR "Linux Programmer's Manual" ).
|
|
.RE
|
|
.PP
|
|
The manual sections are traditionally defined as follows:
|
|
.RS
|
|
.TP
|
|
1
|
|
Commands (e.g., those commands that can be executed by the user from within
|
|
a shell)
|
|
.TP
|
|
2
|
|
System calls (e.g., those functions which must be performed by the kernel)
|
|
.TP
|
|
3
|
|
Library calls (e.g., most of the
|
|
.I libc
|
|
functions, such as
|
|
.IR sort(3) )
|
|
.TP
|
|
4
|
|
Special files (e.g., files found in
|
|
.IR /dev )
|
|
.TP
|
|
5
|
|
File formats and conventions (e.g., the format for
|
|
.IR /etc/passwd )
|
|
.TP
|
|
6
|
|
Games
|
|
.TP
|
|
7
|
|
Macro packages and conventions (e.g., a description of the standard file
|
|
system layout, and this man page)
|
|
.TP
|
|
8
|
|
System management commands (e.g., commands like
|
|
.IR mount (8),
|
|
which only
|
|
.I root
|
|
can execute)
|
|
.TP
|
|
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
|
|
In some conventions, command names and options are in
|
|
.BR "bold face" ,
|
|
file names and variable names are in
|
|
.IR "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:
|
|
.TP
|
|
.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)
|