mirror of https://github.com/mkerrisk/man-pages
571 lines
15 KiB
Groff
571 lines
15 KiB
Groff
.\" (C) Copyright 1992-1999 Rickard E. Faith and David A. Wheeler
|
|
.\" (faith@cs.unc.edu and dwheeler@ida.org)
|
|
.\"
|
|
.\" %%%LICENSE_START(VERBATIM)
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
.\" preserved on all copies.
|
|
.\"
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
.\" permission notice identical to this one.
|
|
.\"
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
.\" have taken the same level of care in the production of this manual,
|
|
.\" which is licensed free of charge, as they might when working
|
|
.\" professionally.
|
|
.\"
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
.\" %%%LICENSE_END
|
|
.\"
|
|
.\" Modified Sun Jul 25 11:06:05 1993 by Rik Faith (faith@cs.unc.edu)
|
|
.\" Modified Sat Jun 8 00:39:52 1996 by aeb
|
|
.\" Modified Wed Jun 16 23:00:00 1999 by David A. Wheeler (dwheeler@ida.org)
|
|
.\" Modified Thu Jul 15 12:43:28 1999 by aeb
|
|
.\" Modified Sun Jan 6 18:26:25 2002 by Martin Schulze <joey@infodrom.org>
|
|
.\" Modified Tue Jul 27 20:12:02 2004 by Colin Watson <cjwatson@debian.org>
|
|
.\" 2007-05-30, mtk: various rewrites and moved much text to new man-pages.7.
|
|
.\"
|
|
.TH MAN 7 2012-08-05 "Linux" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
man \- macros to format man pages
|
|
.SH SYNOPSIS
|
|
.B groff \-Tascii \-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 an.tmac"
|
|
macro package (often called the
|
|
.B 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
|
|
.BR mdoc (7)).
|
|
.PP
|
|
Note that NET-2 BSD mdoc 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.
|
|
.PP
|
|
For conventions that should be employed when writing man pages
|
|
for the Linux \fIman-pages\fP package, see
|
|
.BR man-pages (7).
|
|
.SS Title line
|
|
The first command in a man page (after comment lines,
|
|
that is, lines that start with \fB.\\"\fP) should be
|
|
.RS
|
|
.sp
|
|
.B \&.TH
|
|
.I "title section date source manual"
|
|
.sp
|
|
.RE
|
|
For details of the arguments that should be supplied to the \fBTH\fP
|
|
command, see
|
|
.BR man-pages (7).
|
|
.PP
|
|
Note that BSD mdoc-formatted pages begin with the
|
|
.B Dd
|
|
command, not the
|
|
.B TH
|
|
command.
|
|
.SS Sections
|
|
Sections are started with
|
|
.B \&.SH
|
|
followed by the heading name.
|
|
.\" The following doesn't seem to be required (see Debian bug 411303),
|
|
.\" If the name contains spaces and appears
|
|
.\" on the same line as
|
|
.\" .BR \&.SH ,
|
|
.\" then place the heading in double quotes.
|
|
|
|
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:
|
|
.RS
|
|
.sp
|
|
\&.SH NAME
|
|
.br
|
|
item \\- description
|
|
.sp
|
|
.RE
|
|
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
|
|
.BR mandb (8)
|
|
program to create a database of short descriptions for the
|
|
.BR whatis (1)
|
|
and
|
|
.BR apropos (1)
|
|
commands.
|
|
(See
|
|
.BR lexgrog (1)
|
|
for further details on the syntax of the NAME section.)
|
|
.PP
|
|
For a list of other sections that might appear in a manual page, see
|
|
.BR man-pages (7).
|
|
.SS Fonts
|
|
The commands to select the type face are:
|
|
.TP 4
|
|
.B \&.B
|
|
Bold
|
|
.TP
|
|
.B \&.BI
|
|
Bold alternating with italics
|
|
(especially useful for function specifications)
|
|
.TP
|
|
.B \&.BR
|
|
Bold alternating with Roman
|
|
(especially useful for referring to other
|
|
manual pages)
|
|
.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 (useful for acronyms)
|
|
.LP
|
|
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
|
|
.B \&.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.
|
|
.SS Other macros and strings
|
|
.PP
|
|
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 i
|
|
below;
|
|
macros may omit
|
|
.I 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:
|
|
.SS Normal paragraphs
|
|
.TP 9m
|
|
.B \&.LP
|
|
Same as
|
|
.B \&.PP
|
|
(begin a new paragraph).
|
|
.TP
|
|
.B \&.P
|
|
Same as
|
|
.B \&.PP
|
|
(begin a new paragraph).
|
|
.TP
|
|
.B \&.PP
|
|
Begin a new paragraph and reset prevailing indent.
|
|
.SS Relative margin indent
|
|
.TP 9m
|
|
.BI \&.RS " i"
|
|
Start relative margin indent: moves the left margin
|
|
.I i
|
|
to the right (if
|
|
.I i
|
|
is omitted, the prevailing indent value is used).
|
|
A new prevailing indent is set to 0.5 inches.
|
|
As a result, all following paragraph(s) will be
|
|
indented until the corresponding
|
|
.BR \&.RE .
|
|
.TP
|
|
.B \&.RE
|
|
End relative margin indent and
|
|
restores the previous value of the prevailing indent.
|
|
.SS Indented paragraph macros
|
|
.TP 9m
|
|
.BI \&.HP " i"
|
|
Begin paragraph with a hanging indent
|
|
(the first line of the paragraph is at the left margin of
|
|
normal paragraphs, and the rest of the paragraph's lines are indented).
|
|
.TP
|
|
.BI \&.IP " x i"
|
|
Indented paragraph with optional hanging tag.
|
|
If the tag
|
|
.I x
|
|
is omitted, the entire following paragraph is indented by
|
|
.IR i .
|
|
If the tag
|
|
.I x
|
|
is provided, it is hung at the left margin
|
|
before the following indented paragraph
|
|
(this is just like
|
|
.B \&.TP
|
|
except the tag is included with the command instead of being on the
|
|
following line).
|
|
If the tag is too long, the text after the tag will be moved down to the
|
|
next line (text will not be lost or garbled).
|
|
For bulleted lists, use this macro with \e(bu (bullet) or \e(em (em dash)
|
|
as the tag, and for numbered lists, use the number or letter followed by
|
|
a period as the tag;
|
|
this simplifies translation to other formats.
|
|
.TP
|
|
.BI \&.TP " i"
|
|
Begin paragraph with hanging tag.
|
|
The tag is given on the next line, but
|
|
its results are like those of the
|
|
.B \&.IP
|
|
command.
|
|
.SS Hypertext link macros
|
|
(Feature supported with
|
|
.B groff
|
|
only.)
|
|
In order to use hypertext link macros, it is necessary to load the
|
|
.B www.tmac
|
|
macro package.
|
|
Use the request
|
|
.B .mso www.tmac
|
|
to do this.
|
|
.TP 9m
|
|
.BI \&.URL " url link trailer"
|
|
Inserts a hypertext link to the URI (URL)
|
|
.IR url ,
|
|
with
|
|
.I link
|
|
as the text of the link.
|
|
The
|
|
.I trailer
|
|
will be printed immediately afterward.
|
|
When generating HTML this should translate into the HTML command
|
|
\fB<A HREF="\fP\fIurl\fP\fB">\fIlink\fP\fB</A>\fP\fItrailer\fP.
|
|
.\" The following is a kludge to get a paragraph into the listing.
|
|
.TP
|
|
.B " "
|
|
This and other related macros are new, and
|
|
many tools won't do anything with them, but
|
|
since many tools (including troff) will simply ignore undefined macros
|
|
(or at worst insert their text) these are safe to insert.
|
|
.\" The following is a kludge to get a paragraph into the listing.
|
|
.TP
|
|
.B " "
|
|
It can be useful to define your own
|
|
.B URL
|
|
macro in manual pages for the benefit of those viewing it with a roff
|
|
viewer other than
|
|
.BR groff .
|
|
That way, the URL, link text, and trailer text (if any) are still visible.
|
|
.\" The following is a kludge to get a paragraph into the listing.
|
|
.TP
|
|
.B " "
|
|
Here's an example:
|
|
.RS 1.5i
|
|
\&.de URL
|
|
.br
|
|
\\\\$2 \\(laURL: \\\\$1 \\(ra\\\\$3
|
|
.br
|
|
\&..
|
|
.br
|
|
\&.if \\n[.g] .mso www.tmac
|
|
.br
|
|
\&.TH
|
|
.I ...
|
|
.br
|
|
.I (later in the page)
|
|
.br
|
|
This software comes from the
|
|
.br
|
|
\&.URL "http://www.gnu.org/" "GNU Project" " of the"
|
|
.br
|
|
\&.URL "http://www.fsf.org/" "Free Software Foundation" .
|
|
.RE
|
|
.\" The following is a kludge to get a paragraph into the listing.
|
|
.TP
|
|
.B " "
|
|
In the above, if
|
|
.B groff
|
|
is being used, the
|
|
.B www.tmac
|
|
macro package's definition of the URL macro will supersede the locally
|
|
defined one.
|
|
.PP
|
|
A number of other link macros are available.
|
|
See
|
|
.BR groff_www (7)
|
|
for more details.
|
|
.SS Miscellaneous macros
|
|
.TP 9m
|
|
.B \&.DT
|
|
Reset tabs to default tab values (every 0.5 inches);
|
|
does not cause a break.
|
|
.TP
|
|
.BI \&.PD " d"
|
|
Set inter-paragraph vertical distance to d
|
|
(if omitted, d=0.4v);
|
|
does not cause a break.
|
|
.TP
|
|
.BI \&.SS " t"
|
|
Subheading
|
|
.I t
|
|
(like
|
|
.BR \&.SH ,
|
|
but used for a subsection inside a section).
|
|
.SS Predefined strings
|
|
The
|
|
.B man
|
|
package has the following predefined strings:
|
|
.IP \e*R
|
|
Registration Symbol: \*R
|
|
.IP \e*S
|
|
Change to default font size
|
|
.IP \e*(Tm
|
|
Trademark Symbol: \*(Tm
|
|
.IP \e*(lq
|
|
Left angled double quote: \*(lq
|
|
.IP \e*(rq
|
|
Right angled double quote: \*(rq
|
|
.SS Safe subset
|
|
Although technically
|
|
.B man
|
|
is a troff macro package, in reality a large number of other tools
|
|
process man page files that don't implement all of troff's abilities.
|
|
Thus, it's best to avoid some of troff's more exotic abilities
|
|
where possible to permit these other tools to work correctly.
|
|
Avoid using the various troff preprocessors
|
|
(if you must, go ahead and use
|
|
.BR tbl (1),
|
|
but try to use the
|
|
.B IP
|
|
and
|
|
.B TP
|
|
commands instead for two-column tables).
|
|
Avoid using computations; most other tools can't process them.
|
|
Use simple commands that are easy to translate to other formats.
|
|
The following troff macros are believed to be safe (though in many cases
|
|
they will be ignored by translators):
|
|
.BR \e" ,
|
|
.BR . ,
|
|
.BR ad ,
|
|
.BR bp ,
|
|
.BR br ,
|
|
.BR ce ,
|
|
.BR de ,
|
|
.BR ds ,
|
|
.BR el ,
|
|
.BR ie ,
|
|
.BR if ,
|
|
.BR fi ,
|
|
.BR ft ,
|
|
.BR hy ,
|
|
.BR ig ,
|
|
.BR in ,
|
|
.BR na ,
|
|
.BR ne ,
|
|
.BR nf ,
|
|
.BR nh ,
|
|
.BR ps ,
|
|
.BR so ,
|
|
.BR sp ,
|
|
.BR ti ,
|
|
.BR tr .
|
|
.PP
|
|
You may also use many troff escape sequences (those sequences beginning
|
|
with \e).
|
|
When you need to include the backslash character as normal text,
|
|
use \ee.
|
|
Other sequences you may use, where x or xx are any characters and N
|
|
is any digit, include:
|
|
.BR \e' ,
|
|
.BR \e` ,
|
|
.BR \e- ,
|
|
.BR \e. ,
|
|
.BR \e" ,
|
|
.BR \e% ,
|
|
.BR \e*x ,
|
|
.BR \e*(xx ,
|
|
.BR \e(xx ,
|
|
.BR \e$N ,
|
|
.BR \enx ,
|
|
.BR \en(xx ,
|
|
.BR \efx ,
|
|
and
|
|
.BR \ef(xx .
|
|
Avoid using the escape sequences for drawing graphics.
|
|
.PP
|
|
Do not use the optional parameter for
|
|
.B bp
|
|
(break page).
|
|
Use only positive values for
|
|
.B sp
|
|
(vertical space).
|
|
Don't define a macro
|
|
.RB ( de )
|
|
with the same name as a macro in this or the
|
|
mdoc macro package with a different meaning; it's likely that
|
|
such redefinitions will be ignored.
|
|
Every positive indent
|
|
.RB ( in )
|
|
should be paired with a matching negative indent
|
|
(although you should be using the
|
|
.B RS
|
|
and
|
|
.B RE
|
|
macros instead).
|
|
The condition test
|
|
.RB ( if,ie )
|
|
should only have \(aqt\(aq or \(aqn\(aq as the condition.
|
|
Only translations
|
|
.RB ( tr )
|
|
that can be ignored should be used.
|
|
Font changes
|
|
.RB ( ft
|
|
and the \fB\ef\fP escape sequence)
|
|
should only have the values 1, 2, 3, 4, R, I, B, P, or CW
|
|
(the ft command may also have no parameters).
|
|
.PP
|
|
If you use capabilities beyond these, check the
|
|
results carefully on several tools.
|
|
Once you've confirmed that the additional capability is safe,
|
|
let the maintainer of this
|
|
document know about the safe command or sequence
|
|
that should be added to this list.
|
|
.SH FILES
|
|
.IR /usr/share/groff/ [*/] tmac/an.tmac
|
|
.br
|
|
.I /usr/man/whatis
|
|
.SH NOTES
|
|
.PP
|
|
By all means include full URLs (or URIs) in the text itself;
|
|
some tools such as
|
|
.BR man2html (1)
|
|
can automatically turn them into hypertext links.
|
|
You can also use the new
|
|
.B URL
|
|
macro to identify links to related information.
|
|
If you include URLs, use the full URL
|
|
(e.g.,
|
|
.UR http://www.kernelnotes.org
|
|
.UE )
|
|
to ensure that tools can automatically find the URLs.
|
|
.PP
|
|
Tools processing these files should open the file and examine the first
|
|
nonwhitespace character.
|
|
A period (.) or single quote (') at the beginning
|
|
of a line indicates a troff-based file (such as man or mdoc).
|
|
A left angle bracket (<) indicates an SGML/XML-based
|
|
file (such as HTML or Docbook).
|
|
Anything else suggests simple ASCII
|
|
text (e.g., a "catman" result).
|
|
.PP
|
|
Many man pages begin with \fB\'\e"\fP followed by a
|
|
space and a list of characters,
|
|
indicating how the page is to be preprocessed.
|
|
For portability's sake to non-troff translators we recommend
|
|
that you avoid using anything other than
|
|
.BR tbl (1),
|
|
and Linux can detect that automatically.
|
|
However, you might want to include this information so your man page
|
|
can be handled by other (less capable) systems.
|
|
Here are the definitions of the preprocessors invoked by these characters:
|
|
.TP 3
|
|
.B e
|
|
eqn(1)
|
|
.TP
|
|
.B g
|
|
grap(1)
|
|
.TP
|
|
.B p
|
|
pic(1)
|
|
.TP
|
|
.B r
|
|
refer(1)
|
|
.TP
|
|
.B t
|
|
tbl(1)
|
|
.TP
|
|
.B v
|
|
vgrind(1)
|
|
.SH BUGS
|
|
.PP
|
|
Most of the macros describe formatting (e.g., font type and spacing) instead
|
|
of marking semantic content (e.g., this text is a reference to another page),
|
|
compared to formats like mdoc and DocBook (even HTML has more semantic
|
|
markings).
|
|
This situation makes it harder to vary the
|
|
.B man
|
|
format for different media,
|
|
to make the formatting consistent for a given media, and to automatically
|
|
insert cross-references.
|
|
By sticking to the safe subset described above, it should be easier to
|
|
automate transitioning to a different reference page format in the future.
|
|
.LP
|
|
The Sun macro
|
|
.B TX
|
|
is not implemented.
|
|
.\" .SH AUTHORS
|
|
.\" .IP \(em 3m
|
|
.\" James Clark (jjc@jclark.com) wrote the implementation of the macro package.
|
|
.\" .IP \(em
|
|
.\" Rickard E. Faith (faith@cs.unc.edu) wrote the initial version of
|
|
.\" this manual page.
|
|
.\" .IP \(em
|
|
.\" Jens Schweikhardt (schweikh@noc.fdn.de) wrote the Linux Man-Page Mini-HOWTO
|
|
.\" (which influenced this manual page).
|
|
.\" .IP \(em
|
|
.\" David A. Wheeler (dwheeler@ida.org) heavily modified this
|
|
.\" manual page, such as adding detailed information on sections and macros.
|
|
.SH SEE ALSO
|
|
.BR apropos (1),
|
|
.BR groff (1),
|
|
.BR lexgrog (1),
|
|
.BR man (1),
|
|
.BR man2html (1),
|
|
.BR whatis (1),
|
|
.BR groff_man (7),
|
|
.BR groff_www (7),
|
|
.BR man-pages (7),
|
|
.BR mdoc (7),
|
|
.BR mdoc.samples (7)
|