groff -mdoc file ...
DESCRIPTION
A complete reference for writing UNIX manual pages with the -mdoc macro
package; a content-based and domain-based formatting package for GNU
troff(1). Its predecessor, the -man(7) package, addressed page layout
leaving the manipulation of fonts and other typesetting details to the
individual author. In -mdoc, page layout macros make up the page
structure domain which consists of macros for titles, section headers,
displays and lists - essentially items which affect the physical position
of text on a formatted page. In addition to the page structure domain,
there are two more domains, the manual domain and the general text do
main. The general text domain is defined as macros which perform tasks
such as quoting or emphasizing pieces of text. The manual domain is de
fined as macros that are a subset of the day to day informal language
used to describe commands, routines and related UNIX files. Macros in
the manual domain handle command names, command line arguments and op
tions, function names, function parameters, pathnames, variables, cross
references to other manual pages, and so on. These domain items have
value for both the author and the future user of the manual page. It is
hoped the consistency gained across the manual set will provide easier
translation to future documentation tools.
Throughout the UNIX manual pages, a manual entry is simply referred to as
a man page, regardless of actual length and without sexist intention.
GETTING STARTED
The material presented in the remainder of this document is outlined as
follows:
1. TROFF IDIOSYNCRASIES
Macro Usage
Passing Space Characters in an Argument
Trailing Blank Space Characters
Escaping Special Characters
Other Possible Pitfalls
2. A MANUAL PAGE TEMPLATE
3. CONVENTIONS
4. TITLE MACROS
5. INTRODUCTION OF MANUAL AND GENERAL TEXT DOMAINS
What's in a Name...
General Syntax
6. MANUAL DOMAIN
Addresses
Author Name
Arguments
Configuration Declarations (Section Four Only)
Command Modifiers
Defined Variables
Errno's
Environment Variables
Literals
Names
Options
Pathnames
Standards
Variable Types
Variables
Manual Page Cross References
7. GENERAL TEXT DOMAIN
AT&T Macro
BSD Macro
NetBSD Macro
FreeBSD Macro
OpenBSD Macro
BSD/OS Macro
UNIX Macro
Emphasis Macro
Font Mode
Enclosure and Quoting Macros
No-Op or Normal Text Macro
No-Space Macro
Section Cross References
Symbolics
Mathematical Symbols
References and Citations
Trade Names (or Acronyms and Type Names)
Extended Arguments
8. PAGE STRUCTURE DOMAIN
Section Headers
Subsection Headers
Paragraphs and Line Spacing
Keeps
Examples and Displays
Lists and Columns
9. MISCELLANEOUS MACROS
10. PREDEFINED STRINGS
11. DIAGNOSTICS
12. FORMATTING WITH GROFF, TROFF, AND NROFF
13. FILES
14. SEE ALSO
15. BUGS
TROFF IDIOSYNCRASIES
The -mdoc package attempts to simplify the process of writing a man page.
Theoretically, one should not have to learn the dirty details of GNU
troff(1) to use -mdoc; however, there are a few limitations which are un
avoidable and best gotten out of the way. And, too, be forewarned, this
more) characters as a macro name. A single starting dot followed by
nothing is ignored. To place a `.' (dot character) at the beginning of
an input line in some context other than a macro invocation, precede the
`.' (dot) with the `\&' escape sequence. The `\&' translates literally
to a zero-width space, and is never displayed in the output.
In general, GNU troff(1) macros accept an unlimited number of arguments
(contrary to other versions of troff which can't handle more than nine
arguments). In limited cases, arguments may be continued or extended on
the next line (See Extended Arguments below). Almost all macros handle
quoted arguments (see Passing Space Characters in an Argument below).
Most of the -mdoc general text domain and manual domain macros are spe
cial in that their argument lists are parsed for callable macro names.
This means an argument on the argument list which matches a general text
or manual domain macro name and is determined to be callable will be exe
cuted or called when it is processed. In this case the argument, al
though the name of a macro, is not preceded by a `.' (dot). It is in
this manner that many macros are nested; for example the option macro,
`.Op', may call the flag and argument macros, `Fl' and `Ar', to specify
an optional flag with an argument:
[-s bytes]
is produced by `.Op Fl s Ar bytes'
To prevent a string from being interpreted as a macro name, precede the
string with the escape sequence `\&':
[Fl s Ar bytes]
is produced by `.Op \&Fl s \&Ar bytes'
Here the strings `Fl' and `Ar' are not interpreted as macros. Macros
whose argument lists are parsed for callable arguments are referred to as
parsed and macros which may be called from an argument list are referred
to as callable throughout this document. This is a technical faux pas as
almost all of the macros in -mdoc are parsed, but as it was cumbersome to
constantly refer to macros as being callable and being able to call other
macros, the term parsed has been used.
Passing Space Characters in an Argument
Sometimes it is desirable to give as an argument a string containing one
or more blank space characters. This may be necessary to specify argu
ments to macros which expect particular arrangement of items in the argu
ment list. Additionally, it makes -mdoc working faster. For example,
the function macro `.Fn' expects the first argument to be the name of a
function and any remaining arguments to be function parameters. As
ANSI C stipulates the declaration of function parameters in the parenthe
sized parameter list, each parameter is guaranteed to be at minimum a two
word string. For example, int foo.
There are two possible ways to pass an argument which contains an embed
ded space. One way of passing a string containing blank spaces is to use
the hard or unpaddable space character `\ ', that is, a blank space pre
ceded by the escape character `\'. This method may be used with any macro
but has the side effect of interfering with the adjustment of text over
the length of a line. Troff sees the hard space as if it were any other
is created by `.Fn fetch char\ *str'
fetch(char *str)
can also be created by `.Fn fetch "char *str"'
If the `\' before the space resp. the double quotes were omitted,
`.Fn' would see three arguments, and the result would be:
fetch(char, *str)
Trailing Blank Space Characters
Troff can be confused by blank space characters at the end of a
line. It is a wise preventive measure to globally remove all
blank spaces from <blank-space><end-of-line> character sequences.
Should the need arise to force a blank character at the end of a
line, it may be forced with an unpaddable space and the `\&' es
cape character. For example, `string\ \&'.
Escaping Special Characters
Special characters like the newline character `\n' are handled by
replacing the `\' with `\e' (e.g. `\en') to preserve the back
slash.
Other Possible Pitfalls
A warning is emitted when an empty input line is found outside of
displays (see below). Use `.sp' instead. (Well, it is even bet
ter to use -mdoc macros to avoid the usage of low-level com
mands.)
Leading spaces will cause a break and are output directly. Avoid
this behaviour if possible. Similarly, do not use more than one
space character between words in an ordinary text line; contrary
to other text formatters, they are not replaced with a single
space.
You can't pass `"' directly as an argument. Use `\*[q]' (or
`\*q') instead.
By default, troff(1) inserts two space characters after a punctu
ation mark closing a sentence; characters like `)' or `'' are
treated transparently, not influencing the sentence-ending be
haviour. To change this, insert `\&' before or after the dot:
The
.Ql .
character.
.Pp
The
.Ql \&.
character.
.Pp
.No test .
test
.Pp
.No test.
test
test. test
As can be seen in the first and third line, -mdoc handles punctu
ation characters specially in macro arguments. This will be ex
plained in section General Syntax below. In the same way, you
have to protect trailing full stops of abbreviations with a
trailing zero-width space: `e.g.\&'.
A comment in the source file of a man page can be either started
with `.\"' on a single line, `\"' after some input, or `\#' any
where (the latter is a GNU troff(1) extension); the rest of such
a line is ignored.
A MANUAL PAGE TEMPLATE
The body of a man page is easily constructed from a basic template:
.\" The following requests are required for all man pages.
.Dd Month day, year
.Os [OPERATING_SYSTEM] [version/release]
.Dt DOCUMENT_TITLE [section number] [architecture/volume]
.Sh NAME
.Nm name
.Nd one line description of name
.\" This next request is for sections 2 and 3 only.
.\" .Sh LIBRARY
.Sh SYNOPSIS
.Sh DESCRIPTION
.\" The following requests should be uncommented and
.\" used where appropriate.
.\" .Sh IMPLEMENTATION NOTES
.\" This next request is for sections 2, 3 and 9 function
.\" return values only.
.\" .Sh RETURN VALUES
.\" This next request is for sections 1, 6, 7 and 8 only.
.\" .Sh ENVIRONMENT
.\" .Sh FILES
.\" .Sh EXAMPLES
.\" This next request is for sections 1, 6, 7, 8 and 9 only
.\" (command return values (to shell) and
.\" fprintf/stderr type diagnostics).
.\" .Sh DIAGNOSTICS
.\" .Sh COMPATIBILITY
.\" This next request is for sections 2, 3 and 9 error
.\" and signal handling only.
.\" .Sh ERRORS
.\" .Sh SEE ALSO
.\" .Sh STANDARDS
.\" .Sh HISTORY
.\" .Sh AUTHORS
.\" .Sh BUGS
The first items in the template are the macros `.Dd', `.Os', and `.Dt';
the document date, the operating system the man page or subject source is
developed or modified for, and the man page title (in upper case) along
with the section of the manual the page belongs in. These macros identi
fy the page and are discussed below in TITLE MACROS.
brackets. An ellipsis (`...') represents zero or more additional argu
ments. Alternative values for a parameter are separated with `|'. If
there are alternative values for a mandatory parameter, braces are used
(together with `|') to enclose the value set. Meta-variables are speci
fied within angles.
Example:
.Xx <foo> [-test1 [-test2 | -test3]] ...
Except stated explicitly, all macros are parsed and callable.
Most macros have a default width value which can be used to specify a la
bel width (-width) or offset (-offset) for the `.Bl' and `.Bd' macros.
It is recommended not to use this rather obscure feature to avoid depen
dencies on local modifications of the -mdoc package.
TITLE MACROS
The title macros are part of the page structure domain but are presented
first and separately for someone who wishes to start writing a man page
yesterday. Three header macros designate the document title or manual
page title, the operating system, and the date of authorship. These
macros are called once at the very beginning of the document and are used
to construct headers and footers only.
.Dt [<document title>] [<section number>] [<volume>]
The document title is the subject of the man page and must be in
CAPITALS due to troff limitations. If omitted, `UNTITLED' is
used. The section number may be a number in the range 1, ..., 9
or `unass', `draft', or `paper'. If it is specified, and no vol
ume name is given, a default volume name is used.
Under , the following sections are defined:
1
2
3
4
5
6
7
8
9
A volume name may be arbitrary or one of the following:
USD
PS1
AMD
SMM
URM
PRM
KM
IND
LOCAL
CON
luna68k, m68k mmeye, mvme68k, news68k, newsmips, next68k
powerpc, prep, sgimips, sh3, sparc x68k
In the following examples, the left (which is identical to the
right) and the middle part of the manual page header strings are
shown.
.Dt FOO 7
`FOO(7)' `System Reference Manual'
.Dt FOO 2 mac68k
`FOO(2)' `System Programmer's Manual (mac68k
Architecture)'
.Dt FOO "" bar
`FOO' `bar'
Local, OS-specific additions might be found in the file
mdoc.local; look for strings named `volume-ds-XXX' (for the for
mer type) and `volume-as-XXX' (for the latter type); `XXX' then
denotes the keyword to be used with the `.Dt' macro.
This macro is neither callable nor parsed.
.Os [<operating system>] [<release>]
If the first parameter is empty, the default `' is used. This
may be overridden in the local configuration file, mdoc.local. In
general, the name of the operating system should be the common
acronym, e.g. BSD or ATT. The release should be the standard re
lease nomenclature for the system specified. In the following
table, the possible second arguments for some predefined operat
ing systems are listed. Similar to `.Dt', local additions might
be defined in mdoc.local; look for strings named `operating-
system-XXX-YYY', where `XXX' is the acronym for the operating
system and `YYY' the release ID.
ATT
7th, 7, III, 3, V, V.2, V.3, V.4
BSD
3, 4, 4.1, 4.2, 4.3, 4.3t, 4.3T, 4.3r, 4.3R, 4.4
NetBSD
0.8, 0.8a, 0.9, 0.9a, 1.0, 1.0a, 1.1, 1.2, 1.2a, 1.2b,
1.2c, 1.2d, 1.2e, 1.3, 1.3a, 1.4, 1.5
FreeBSD
1.0, 1.1, 1.1.5, 1.1.5.1, 2.0, 2.0.5, 2.1, 2.1.5, 2.1.6,
2.1.7, 2.2, 2.2.1, 2.2.2, 2.2.5, 2.2.6, 2.2.7, 2.2.8,
3.0, 3.1, 3.2, 3.3, 3.4, 3.5, 4.0, 4.1, 4.2, 5.0
For ATT, an unknown second parameter will be replaced with the
string UNIX; for the other predefined acronyms it will be ignored
and a warning message emitted. Unrecognized arguments are dis
played as given in the page footer. For instance, a typical
footer might be:
.Os BSD 4.3
This macro is neither callable nor parsed.
.Dd [<month> <day>, <year>]
If `Dd' has no arguments, `Epoch' is used for the date string.
If it has exactly three arguments, they are concatenated, sepa
rated with unbreakable space:
.Dd January 25, 2001
Otherwise, the current date is used, ignoring the parameters.
This macro is neither callable nor parsed.
INTRODUCTION OF MANUAL AND GENERAL TEXT DOMAINS
What's in a Name Ns ...
The manual domain macro names are derived from the day to day informal
language used to describe commands, subroutines and related files.
Slightly different variations of this language are used to describe the
three different aspects of writing a man page. First, there is the de
scription of -mdoc macro request usage. Second is the description of a
UNIX command with -mdoc macros, and third, the description of a command
to a user in the verbal sense; that is, discussion of a command in the
text of a man page.
In the first case, troff(1) macros are themselves a type of command; the
general syntax for a troff command is:
.Xx argument1 argument2 ...
`.Xx' is a macro command or request, and anything following it are argu
ments to be processed. In the second case, the description of a UNIX
command using the content macros is a bit more involved; a typical
SYNOPSIS command line might be displayed as:
filter [-flag] <infile><outfile>
Here, filter is the command name and the bracketed string -flag is a flag
argument designated as optional by the option brackets. In -mdoc terms,
<infile> and <outfile> are called meta arguments; in this example, the
user has to replace the meta expressions given in angle brackets with re
al file names. Note that in this document meta arguments are used to de
scribe -mdoc commands; in most man pages, meta variables are not specifi
cally written with angle brackets. The macros which formatted the above
example:
.Nm filter
.Op Fl flag
.Ao Ar infile Ac Ao Ar outfile Ac
In the third case, discussion of commands and command syntax includes
both examples above, but may add more detail. The arguments <infile> and
<outfile> from the example above might be referred to as operands or file
arguments. Some command line argument lists are quite long:
make
.Nm make
.Op Fl eiknqrstv
.Op Fl D Ar variable
.Op Fl d Ar flags
.Op Fl f Ar makefile
.Op Fl I Ar directory
.Op Fl j Ar max_jobs
.Op Ar variable Ns = Ns Ar value
.Bk
.Op Ar target ...
.Ek
The `.Bk' and `.Ek' macros are explained in Keeps.
General Syntax
The manual domain and general text domain macros share a similar syntax
with a few minor deviations; most notably, `.Ar', `.Fl', `.Nm', and `.Pa'
differ only when called without arguments; and `.Fn' and `.Xr' impose an
order on their argument lists. All content macros are capable of recog
nizing and properly handling punctuation, provided each punctuation char
acter is separated by a leading space. If a request is given:
.Ar sptr, ptr),
The result is:
sptr, ptr),
The punctuation is not recognized and all is output in the font used by
`.Ar'. If the punctuation is separated by a leading white space:
.Ar sptr , ptr ) ,
The result is:
sptr, ptr),
The punctuation is now recognized and output in the default font distin
guishing it from the argument strings. To remove the special meaning
from a punctuation character escape it with `\&'.
Troff is limited as a macro language, and has difficulty when presented
with a string containing a member of the mathematical, logical or quota
tion set:
{+,-,/,*,%,<,>,<=,>=,=,==,&,`,',"}
The problem is that troff may assume it is supposed to actually perform
the operation or evaluation suggested by the characters. To prevent the
accidental evaluation of these characters, escape them with `\&'. Typical
syntax is shown in the first content macro displayed below, `.Ad'.
MANUAL DOMAIN
Addresses
The address macro identifies an address construct.
.Ad f1
, f2
, f3
:
f1,
f2,
f3:
.Ad
ad
dr
)
)
,
addr)),
The
de
fault
width
is
12n.
Author
Name
The
`.An'
macro
is
used
to
spec
ify
the
name
of
the
au
thor
of
the
item
being
docu
ment
ed,
or
the
name
of
the
au
thor
of
the
...
.An
"Joe
Au
thor"
Joe
Author
.An
"Joe
Au
thor"
,
Joe
Author,
.An
"Joe
Au
thor"
Aq
no
body@FreeB
SD.org
Joe
Author
<nobody@FreeBSD.org>
.An
"Joe
Au
thor"
)
)
,
Joe
Author)),
The
de
fault
width
is
12n.
In
the
AUTHORS
sec
tion,
the
`.An'
re
quest
caus
ap
pear
on
its
own
line.
If
this
is
not
de
sir
able,
.An -nosplit
call
will
turn
this
off.
To
turn
split
ting
back
on,
write
.An -split
Argu
ments
The
.Ar
argu
ment
macro
may
be
used
when
ever
an
argu
ment
is
ref
er
enced.
If
called
with
out
.Ar
[<argument>]
...
.Ar
file ...
.Ar
file1
file1
.Ar
file1
.
file1.
.Ar
file1
file2
file1
file2
.Ar
f1
f2
f3
:
f1
f2
f3:
.Ar
file
)
)
,
file)),
The
de
fault
width
is
12n.
Config
ura
tion
Dec
lara
tion
(Sec
tion
Four
Only)
The
`.Cd'
macro
is
for a
de
vice
in
ter
face
in a
sec
tion
four
manu
al.
Usage:
.Cd
<argument>
...
.Cd
"de
vice
le0
at
scode?"
device
le0
at
scode?
In
the
SYNOPSIS
sec
tion
a
`.Cd'
re
quest
caus
es a
line
break
be
fore
and
after
its
argu
ments
are
print
ed.
The
de
fault
com
mand
modi
fier
is
iden
tical
to
the
`.Fl'
(flag)
com
mand
with
the
ex
cep
tion
that
the
`.Cm'
macro
does
not
as
sert
a
dash
in
front
of
every
argu
ment.
Tra
di
tion
ally
flags
are
marked
by
the
pre
ced
ing
dash,
how
ever,
some
com
mands
or
sub
sets
of
may
also
be
spec
ified
in
con
junc
tion
with
in
ter
ac
tive
com
mands
such
as
edi
tor
com
mands.
See
Flags.
The
de
fault
width
is
10n.
Defined
Vari
ables
A
vari
able
(or
con
stant)
which
is
de
fined
in an
in
clude
file
is
spec
ified
by
the
MAX
HOST
NAME
LEN
MAXHOSTNAMELEN
.Dv
TI
OCGP
GRP
)
TIOCGPGRP)
The
de
fault
width
is
12n.
Errno's
The
`.Er'
errno
macro
spec
ifies
the
error
re
turn
value
for
sec
tion
2, 3,
and 9
li
brary
rou
tines.
The
sec
ond
exam
ple
below
shows
`.Er'
used
with
the
`.Bq'
gen
eral
tion
two
manu
al
page.
Usage:
.Er
<errno
type>
...
.Er
ENOENT
ENOENT
.Er
ENOENT
)
;
ENOENT);
.Bq
Er
ENOT
DIR
[ENOTDIR]
The
de
fault
width
is
17n.
Envi
ron
ment
Vari
ables
The
`.Ev'
macro
spec
ifies
an
envi
ron
ment
vari
able.
Usage:
.Ev
<argument>
...
PATH.
.Ev
PRINT
ER
)
)
,
PRINTER)),
The
de
fault
width
is
15n.
Flags
The
`.Fl'
macro
han
dles
com
mand
line
flags.
It
prepends
a
dash,
`-',
to
the
flag.
For
in
ter
ac
tive
com
mand
flags,
which
are
not
prepend
ed
with
a
dash,
the
`.Cm'
(com
mand
the
dash.
Usage:
.Fl
<argument>
...
.Fl
-
.Fl
cfv
-cfv
.Fl
cfv
.
-cfv.
.Cm
cfv
.
cfv.
.Fl
s
v
t
-s
-v
-t
.Fl
-
,
--,
.Fl
xyz
)
,
-xyz),
.Fl
|
|
The
`.Fl'
macro
with
out
any
argu
ments
re
sults
in a
dash
rep
re
sent
gle
dash
will
re
sult
in
two
dash
es.
The
de
fault
width
is
12n.
Func
tion
Dec
lara
tions
The
`.Fd'
macro
is
used
in
the
SYNOPSIS
sec
tion
with
sec
tion
two
or
three
func
tions.
It is
nei
ther
callable
nor
parsed.
Usage:
.Fd
<argument>
...
.Fd
"#in
tion
a
`.Fd'
re
quest
caus
es a
line
break
if a
func
tion
has
al
ready
been
pre
sent
ed
and a
break
has
not
oc
curred.
This
leaves
a
nice
ver
tical
space
in
be
tween
the
pre
vious
func
tion
call
and
the
dec
lara
tion
for
the
next
func
tion.
The
`.In'
(#include
state
ple.
It
spec
ifies
the
C head
er
file
as
being
in
clud
ed in
a
C pro
gram.
It
also
caus
es a
line
break,
and
is
nei
ther
callable
nor
parsed.
Usage:
.In
<header
file>
.In
stdio.h
Func
tion
Types
This
macro
is
in
tend
ed
for
the
SYNOPSIS
sec
tion.
It
may
out
prob
lems,
but
its
main
pur
pose
is to
pre
sent
the
func
tion
type
in
ker
nel
nor
mal
form
for
the
SYNOPSIS
of
sec
tions
two
and
three
(it
caus
es a
line
break,
al
low
ing
the
func
tion
name
to
ap
pear
on
the
next
line).
Usage:
.Ft
<type>
...
.Ft
tines)
The
`.Fn'
macro
is
mod
eled
on
ANSI C
con
ven
tions.
Man(1) output converted with
man2html