mdoc.samples - tutorial sampler for writing OpenBSD manuals
with -mdoc
nroff -TNAME -mandoc file
A tutorial sampler for writing OpenBSD manual pages with the
-mdoc macro
package, a content-based and domain-based formatting package
for
troff(1). Its predecessor, the -man package (see man(7))
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 domain.
The general text domain is defined as macros which perform
tasks such as
quoting or emphasizing pieces of text. The manual domain is
defined as
macros that are a subset of the day to day informal language
used to describe
commands, routines and related OpenBSD files. Macros
in the manual
domain handle command names, command line arguments and
options, 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.
Since a tutorial document is normally read when a person desires to use
the material immediately, the assumption has been made that
the user of
this document may be impatient. 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 (a warning).
Escaping Special Characters.
Dashes and Hyphens.
2. THE ANATOMY OF A MAN PAGE
A manual page template.
3. TITLE MACROS
4. INTRODUCTION TO MANUAL AND GENERAL TEXT DOMAINS
What's in a name....
General Syntax.
5. MANUAL DOMAIN
Addresses.
Arguments.
Authors.
Command Modifier.
Configuration Declarations (section four
only).
Defined Variables.
Environment Variables.
Errno (section two only).
Exit Values.
Flags.
Functions (library routines).
Function Argument.
Function Declaration.
Function Types.
Interactive Commands.
Includes.
Literals.
Names.
Options.
Pathnames.
Return Values.
Standards.
Variables.
Cross References.
6. GENERAL TEXT DOMAIN
AT&T Macro.
BSD Macro.
BSDI Macro.
OpenBSD/FreeBSD/NetBSD Macros.
UNIX Macro.
Emphasis Macro.
Font mode.
Enclosure and Quoting Macros
Angle Bracket Quote/Enclosure.
Bracket Quote/Enclosure.
Double Quote macro/Enclosure.
Enclose String macro.
Parenthesis Quote/Enclosure.
Quoted Literal macro/Enclosure.
Straight Double Quote macro/Enclosure.
Single Quote macro/Enclosure.
No-Op or Normal Text Macro.
No Space Macro.
Prefix Macro.
Section Cross References.
Space Mode Macro.
Symbolic Macro.
Mathematical Symbols.
References and Citations.
Trade Names (or Acronyms and Type Names).
Extended Arguments.
Miscellaneous Macros.
7. PAGE STRUCTURE DOMAIN
Section Headers.
Paragraphs and Line Spacing.
Keeps.
Displays.
Lists and Columns.
8. PREDEFINED STRINGS
9. DIAGNOSTICS
10. FORMATTING WITH GROFF, TROFF AND NROFF
11. FILES
12. SEE ALSO
13. BUGS
The -mdoc package attempts to simplify the process of writing a man page.
Theoretically, one should not have to learn the dirty details of troff(1)
to use -mdoc; however, there are a few limitations which are
unavoidable
and best gotten out of the way. And, too, be forewarned,
this package is
not fast.
Macro Usage [Toc] [Back]
As in troff(1), a macro is called by placing a `.' (dot
character) at the
beginning of a line followed by the two-character name for
the macro.
Arguments may follow the macro separated by spaces. It is
the dot character
at the beginning of the line which causes troff(1) to
interpret the
next two characters as a macro name. To place a `.' (dot
character) at
the beginning of a 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, troff(1) macros accept up to nine arguments; any
extra arguments
are ignored. Most macros in -mdoc accept nine arguments and, in
limited cases, arguments may be continued or extended on the
next line
(see Extended Arguments). A few macros handle quoted arguments (see
Passing Space Characters in an Argument below).
Most of the -mdoc general text domain and manual domain
macros are special
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 executed
or called when it is processed. In this case the argument, although
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 two-character 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 and in the companion
quick reference
manual mdoc(7). 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 [Toc] [Back]
Sometimes it is desirable to give as one argument a string
containing one
or more blank space characters. This may be necessary to
defeat the nine
argument limit or to specify arguments to macros which expect particular
arrangement of items in the argument list. 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 parenthesized
parameter
list, each parameter is guaranteed to be at minimum a twoword string.
For example, int foo.
There are two possible ways to pass an argument which contains an embedded
space. Implementation note: Unfortunately, the most
convenient way
of passing spaces in between quotes by reassigning individual arguments
before parsing was fairly expensive speed wise and space
wise to implement
in all the macros for AT&T troff(1). It is not expensive for
groff(1) but for the sake of portability, has been limited
to the following
macros which need it the most:
Bl Begin list (for the width specifier).
Cd Configuration declaration (section 4 SYNOPSIS).
Em Emphasized text.
Fn Functions (sections two and four).
It List items.
Li Literal text.
Sy Symbolic text.
%B Book titles.
%J Journal names.
%O Optional notes for a reference.
%R Report title (in a reference).
%T Title of article in a book or journal.
One way of passing a string containing blank spaces is to
use the hard or
unpaddable space character ` ', that is, a blank space preceded 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
printable character and cannot split the string into blank
or newline
separated pieces as one would expect. The method is useful
for strings
which are not expected to overlap a line boundary.
fetch(char *str) is created by `.Fn fetch char *str'
fetch(char *str) can also be created by `.Fn fetch
"char *str"'
If the `' or quotes were omitted, `.Fn' would see three arguments and
the result would be:
fetch(char, *str)
For an example of what happens when the parameter list overlaps a newline
boundary, see the BUGS section.
Trailing Blank Space Characters [Toc] [Back]
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 `' escape character. For example,
`string '.
Escaping Special Characters [Toc] [Back]
Special characters like the newline character `0, are handled by replacing
the `' with `\' (e.g., `\n') to preserve the backslash.
Dashes and Hyphens [Toc] [Back]
In typography there are three types of dashes of various
width: the hyphen
(-), the en-dash (-), and the em-dash (--). Hyphens
are used for
adjectives; to separate the two parts of a compound word; or
to separate
a word across two successive lines of text. The hyphen does
not need to
be escaped:
blue-eyed
lorry-driver
The en-dash is used to separate the two elements of a range,
or can be
used the same way as colons, semi-colons or parentheses. It
is also used
as the mathematical minus symbol. It should be escaped with
the `'
character:
pp. 95-97.
Go away - or else!
-2
Note: hyphens and en-dashes will look identical under normal
ASCII output.
Other formats, such as PostScript, render them correctly, with differing
widths.
The em-dash is used to mark a parenthesis -- like this -- or
an interruption.
It should be written as
--
THE ANATOMY OF A MAN PAGE [Toc] [Back] The body of a man page is easily constructed from a basic
template found
in the file /usr/share/misc/mdoc.template.
.
.Dd Month DD, YYYY
.Dt NAME SECTION#
.Os
.Sh NAME
.Nm program
.Nd one line about what it does
.Sh SYNOPSIS
.
.Nm program
.Op Fl abc
.Ar
.Sh DESCRIPTION
The
.Nm
utility processes files ...
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
The first items in the template are the macros (.Dd, .Dt,
.Os); the document
date, the man page title (in upper case) along with the
section of
the manual the page belongs in, and the operating system the
man page or
subject source is developed or modified for. These macros
identify the
page, and are discussed below in TITLE MACROS.
The remaining items in the template are section headers
(.Sh); of which
NAME, SYNOPSIS and DESCRIPTION are mandatory. The headers
are discussed
in PAGE STRUCTURE DOMAIN, after presentation of MANUAL
DOMAIN. Several
content macros are used to demonstrate page layout macros;
reading about
content macros before page layout macros is recommended.
The title macros are the first portion of the page structure
domain, but
are presented first and separate 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 the headers and footers only.
.Dd month day, year
The date should be written formally:
January 25, 1989
.Dt DOCUMENT_TITLE section# [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'. The following section
numbers are
defined:
1 General commands (tools and utilities)
2 System calls and error numbers
3 Libraries
3p perl(1) programmer's reference guide
4 Device drivers
5 File formats
6 Games
7 Miscellaneous
8 System maintenance and operation commands
9 Kernel internals
The volume title is optional; if specified, it
should be one of
the following:
AMD OpenBSD Ancestral Manual Documents
IND OpenBSD Manual Master Index
KM OpenBSD Kernel Manual
LOCAL OpenBSD Local Manual
PRM OpenBSD Programmer's Manual
PS1 OpenBSD Programmer's Supplementary
Documents
SMM OpenBSD System Manager's Manual
URM OpenBSD Reference Manual
USD OpenBSD User's Supplementary Documents
The default volume labeling is URM for sections 1,
6, and 7; SMM
for section 8; PRM for sections 2, 3, 4, and 5; KM
for section 9.
If the third argument to `.Dt' is instead a machine
architecture,
it will be displayed, surrounded by parentheses,
next to the volume
title. This is useful for pages specific only
to a particular
architecture. The architectures currently defined are:
alpha, amd64, amiga, arc, arm32, atari, cats,
hp300,
hppa, i386, luna88k, mac68k, macppc, mvme68k,
mvme88k,
mvmeppc, pc532, pegasos, pmax, sgi, sparc,
sparc64,
sun3, tahoe, vax, x68k
.Os operating_system release#
The name of the operating system should be a common
acronym,
e.g., OpenBSD or ATT. The release should be the
standard release
nomenclature for the system specified, e.g., 4.3,
4.3+Tahoe, V.3,
V.4. Unrecognized arguments are displayed as given
in the page
footer. For instance, a typical footer might be:
.Os OpenBSD 3.4
or for a locally produced set
.Os "CS Department"
The OpenBSD default, `.Os' without an argument, is
defined as
OpenBSD <latest release#> in the site specific file
/usr/share/tmac/mdoc/doc-common. It really should
default to
LOCAL. Note, if the `.Os' macro is not present, the
bottom left
corner of the page will be ugly.
INTRODUCTION TO MANUAL AND GENERAL TEXT DOMAINS [Toc] [Back] What's in a name...
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 description
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(1) command is:
.Va argument1 argument2 ... argument9
The `.Va' is a macro command or request, and anything following it is an
argument 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 arguments. The macros which
formatted the
above example:
.Nm filter
.Op Fl flag
.Ar infile outfile
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 [-eiknqrstv] [-D variable] [-d flags] [-f
makefile]
[-I directory] [-j max_jobs] [variable=value]
[target ...]
Here one might talk about the command make and qualify the
argument
makefile, as an argument to the flag -f, or discuss the optional file
operand target. In the verbal context, such detail can prevent confusion;
however, the -mdoc package does not have a macro for
an argument to
a flag. Instead the `Ar' argument macro is used for an
operand or file
argument like target as well as an argument to a flag like
variable. The
make command line was produced from:
.Nm make
.Op Fl eiknqrstv
.Op Fl D Ar variable
.Op Fl d Ar flags
.Op Fl f Ar makefile
.Bk -words
.Op Fl I Ar directory
.Ek
.Op Fl j Ar max_jobs
.Op Ar variable=value
.Op Ar target ...
The `.Bk' and `.Ek' macros are explained in Keeps.
General Syntax [Toc] [Back]
The manual domain and general text domain macros share a
similar syntax
with a few minor deviations: `.Ar', `.Fl', `.Nm', and `.Pa'
differ only
when called without arguments; `.Fn' and `.Xr' impose an order on their
argument lists and the `.Op' and `.Fn' macros have nesting
limitations.
All content macros are capable of recognizing and properly
handling punctuation,
provided each punctuation character 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 everything is output
in the font
used by `.Ar'. If the punctuation is separated by a leading
whitespace:
.Ar sptr , ptr ) ,
The result is:
sptr, ptr),
The punctuation is now recognized and is output in the default font distinguishing
it from the argument strings. To remove the
special meaning
from a punctuation character escape it with `'. The following punctuation
characters are recognised by -mdoc:
{ . , ; : ? ! ( ) [ ]}
Troff is limited as a macro language, and has difficulty
when presented
with a string containing a member of the mathematical, logical or quotation
set:
{+ - / * % < > <= >= = == & ` ' "}
The problem is that troff(1) 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'.
Address Macro
The address macro identifies an address construct of the
form addr1[,addr2[,addr3]].
Usage: .Ad address ... { . , ; : ? ! ( ) [ ]}
.Ad addr1 addr1
.Ad addr1 . addr1.
.Ad addr1 , file2 addr1, file2
.Ad f1 , f2 , f3 : f1, f2, f3:
.Ad addr ) ) , addr)),
It is an error to call `.Ad' without arguments. `.Ad' is
callable by
other macros and is parsed.
Argument Macro [Toc] [Back]
The `.Ar' argument macro may be used whenever a command line
argument is
referenced.
Usage: .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)),
If `.Ar' is called without arguments, `file ...' is assumed.
The `.Ar'
macro is parsed and is callable.
Author Name [Toc] [Back]
The `.An' macro is used to specify the name of the author of
the utility,
or the name of the author of the man page.
Usage: .An author ... { . , ; : ? ! ( ) [ ]}
.An John Smith John Smith
.An John Smith , John Smith,
.An John Smith Aq [email protected]ress
John Smith <[email protected]ress>
The `.An' macro is parsed, but is not callable.
Command Modifier [Toc] [Back]
The command modifier is identical to the `.Fl' (flag) command with the
exception that the `.Cm' macro does not assert a dash in
front of every
argument. Traditionally, flags are marked by the preceding
dash; some
commands or subsets of commands do not use them. Command
modifiers may
also be specified in conjunction with interactive commands
such as editor
commands. See Flags.
Configuration Declaration (section four only) [Toc] [Back]
The `.Cd' macro is used to demonstrate a config(8) declaration for a device
interface in a section four manual. This macro accepts
quoted arguments
(double quotes only).
device le0 at scode? produced by: `.Cd device le0 at
scode?'.
Defined Variables [Toc] [Back]
A variable which is defined in an include file is specified
by the macro
`.Dv'.
Usage: .Dv defined_variable ... { . , ; : ? ! ( ) [ ]}
.Dv MAXHOSTNAMELEN MAXHOSTNAMELEN
.Dv TIOCGPGRP ) TIOCGPGRP)
It is an error to call `.Dv' without arguments. `.Dv' is
parsed and is
callable.
Environment Variables [Toc] [Back]
The `.Ev' macro specifies an environment variable.
Usage: .Ev argument ... { . , ; : ? ! ( ) [ ]}
.Ev DISPLAY DISPLAY
.Ev PATH . PATH.
.Ev PRINTER ) ) , PRINTER)),
It is an error to call `.Ev' without arguments. The `.Ev'
macro is
parsed and is callable.
Errno (section two only) [Toc] [Back]
The `.Er' errno macro specifies the error return value for
section two
library routines. The third example below shows `.Er' used
with the
`.Bq' general text domain macro, as it would be used in a
section two
manual page.
Usage: .Er ERRNOTYPE ... { . , ; : ? ! ( ) [ ]}
.Er ENOENT ENOENT
.Er ENOENT ) ; ENOENT);
.Bq Er ENOTDIR [ENOTDIR]
It is an error to call `.Er' without arguments. The `.Er'
macro is
parsed and is callable.
Exit Values (sections one, six, and eight only)
The `.Ex' macro displays a standardised text concerning the
exit values
of applications. The `.Ex' macro does not call other macros
and is not
callable by other macros. The `-std' flag is purely for
compatibility
purposes, and must be included.
Usage: .Ex [-std] utility
For example, `.Ex -std cat' produces:
The cat utility exits 0 on success, and >0 if an error occurs.
Flags [Toc] [Back]
The `.Fl' macro handles command line flags. It prepends a
dash, `-', to
the flag. For interactive command flags, which are not
prepended with a
dash, the `.Cm' (command modifier) macro is identical, but
without the
dash.
Usage: .Fl argument ... { . , ; : ? ! ( ) [ ]}
.Fl -
.Fl cfv -cfv
.Fl cfv . -cfv.
.Fl s v t -s -v -t
.Fl - , --,
.Fl xyz ) , -xyz),
The `.Fl' macro without any arguments results in a dash representing
stdin/stdout. Note that giving `.Fl' a single dash will result in two
dashes. The `.Fl' macro is parsed and is callable.
Functions (library routines) [Toc] [Back]
The `.Fn' macro is modeled on ANSI C conventions.
Usage: .Fn [type] function [[type] parameters ... { . , ; :
? ! ( ) [ ]}]
.Fn getchar getchar()
.Fn strlen ) , strlen()),
.Fn "int align" "const * char *sptrs", int align(const *
char *sptrs),
It is an error to call `.Fn' without any arguments. The
`.Fn' macro is
parsed and is callable. Note that any call to another macro
signals the
end of the `.Fn' call (it will close-parenthesis at that
point).
For functions that have more than eight parameters (and this
is rare),
the macros `.Fo' (function open) and `.Fc' (function close)
may be used
with `.Fa' (function argument) to get around the limitation.
For example:
.Ft int
.Fo res_mkquery
.Fa "int op"
.Fa "char *dname"
.Fa "int class"
.Fa "int type"
.Fa "char *data"
.Fa "int datalen"
.Fa "struct rrec *newrr"
.Fa "char *buf"
.Fa "int buflen"
.Fc
Produces:
int res_mkquery(int op, char *dname, int class, int
type,
char *data, int datalen, struct rrec *newrr, char
*buf, int buflen)
The `.Fo' and `.Fc' macros are parsed and are callable. In
the SYNOPSIS
section, the function will always begin at the beginning of
line. If
there is more than one function presented in the SYNOPSIS
section and a
function type has not been given, a line break will occur,
leaving a nice
vertical space between the current function name and the one
prior. At
the moment, `.Fn' does not check its word boundaries against
troff(1)
line lengths and may split across a newline ungracefully.
This will be
fixed in the near future.
Function Argument [Toc] [Back]
The `.Fa' macro is used to refer to function arguments (parameters) outside
of the SYNOPSIS section of the manual or inside the
SYNOPSIS section
should a parameter list be too long for the `.Fn' macro and
the enclosure
macros `.Fo' and `.Fc' must be used. `.Fa' may also be used
to refer to
structure members.
Usage: .Fa function_argument ... { . , ; : ? ! ( ) [
]}
.Fa d_namlen ) ) , d_namlen)),
.Fa iov_len iov_len
It is an error to call `.Fa' without arguments. `.Fa' is
parsed and is
callable.
Function Declaration [Toc] [Back]
The `.Fd' macro is used in the SYNOPSIS section with section
two, three,
and nine functions. The `.Fd' macro does not call other
macros and is
not callable by other macros.
Usage: .Fd include_file (or defined variable)
In the SYNOPSIS section a `.Fd' request causes a line break
if a function
has already been presented and a break has not occurred.
This leaves a
nice vertical space in between the previous function call
and the declaration
for the next function.
Function Type [Toc] [Back]
This macro is intended for the SYNOPSIS section. It may be
used anywhere
else in the man page without problems, but in the SYNOPSIS
section it
causes a line break after its use. Its main purpose is to
present the
function type in kernel normal form of a section two or
three man page by
forcing the function name to appear on the next line.
Usage: .Ft type ... { . , ; : ? ! ( ) [ ]}
.Ft struct stat struct stat
The `.Ft' request is not callable by other macros.
Interactive Commands [Toc] [Back]
The `.Ic' macro designates an interactive or internal command.
Usage: .Ic command ... { . , ; : ? ! ( ) [ ]}
.Ic :wq :wq
.Ic do while {...} do while {...}
.Ic setenv , unsetenv setenv, unsetenv
It is an error to call `.Ic' without arguments. The `.Ic'
macro is
parsed and is callable.
Includes [Toc] [Back]
The `.In' macro is used in the SYNOPSIS section with section
two, three,
and nine header files. The `.In' macro does not call other
macros and is
not callable by other macros.
Usage: .In include_file
.In stdio.h #include <stdio.h>
In the SYNOPSIS section a `.In' request causes a line break
if a function
has already been presented and a break has not occurred.
This leaves a
nice vertical space in between the previous function call
and the declaration
for the include file.
Literals [Toc] [Back]
The `.Li' literal macro may be used for special characters,
variable constants,
anything which should be displayed as it would be
typed.
Usage: .Li argument ... { . , ; : ? ! ( ) [ ]}
.Li \n
.Li M1 M2 M3 ; M1 M2 M3;
.Li cntrl-D ) , cntrl-D),
.Li 1024 ... 1024 ...
The `.Li' macro is parsed and is callable.
Name Macro [Toc] [Back]
The `.Nm' macro is used for the document title or subject
name. It has
the peculiarity of remembering the first argument it was
called with,
which should always be the subject name of the page. When
called without
arguments, `.Nm' regurgitates this initial name for the sole
purpose of
making less work for the author. However, `.Nm' should
always be given
an argument when used in the SYNOPSIS section.
Note: a section two or three document function name is addressed with
`.Nm' in the NAME section, and with `.Fn' in the SYNOPSIS
and remaining
sections. For interactive commands, such as the `while'
command keyword
in csh(1), the `.Ic' macro should be used. While `.Ic' is
nearly identical
to `.Nm', it can not recall the first argument it was
invoked with.
Usage: .Nm argument ... { . , ; : ? ! ( ) [ ]}
.Nm mdoc.samples mdoc.samples
.Nm mdoc.samples
.Nm . mdoc.samples.
.Nm -mdoc -mdoc
.Nm foo ) ) , foo)),
The `.Nm' macro is parsed and is callable.
Options [Toc] [Back]
The `.Op' macro places option brackets around any remaining
arguments on
the command line, and places any trailing punctuation outside the brackets.
The macros `.Oc' and `.Oo' may be used across one or
more lines.
Usage: .Op options ... { . , ; : ? ! ( ) [ ]}
.Op []
.Op Fl k [-k]
.Op Fl k ) . [-k]).
.Op Fl k Ar kookfile [-k kookfile]
.Op Fl k Ar kookfile , [-k kookfile],
.Op Ar objfil Op Ar corfil [objfil [corfil]]
.Op Fl c Ar objfil Op Ar corfil , [-c objfil
[corfil]],
.Op word1 word2 [word1 word2]
The `.Oc' and `.Oo' macros:
.Oo
.Op Fl k Ar kilobytes
.Op Fl i Ar interval
.Op Fl c Ar count
.Oc
Produce: [[-k kilobytes] [-i interval] [-c count]]
The macros `.Op', `.Oc' and `.Oo' are parsed and are
callable.
Pathnames [Toc] [Back]
The `.Pa' macro formats path or file names.
Usage: .Pa pathname { . , ; : ? ! ( ) [ ]}
.Pa /usr/share /usr/share
.Pa /tmp/fooXXXXX ) . /tmp/fooXXXXX).
The `.Pa' macro is parsed and is callable.
Return Values (sections two and three only) [Toc] [Back]
The `.Rv' macro displays a standardised text concerning the
return values
of functions. The `.Rv' macro does not call other macros
and is not
callable by other macros. The `-std' flag is purely for
compatibility
purposes, and must be included.
Usage: .Rv [-std] function
For example, `.Rv -std open' produces:
The open() function returns the value 0 if successful; otherwise the value
-1 is returned and the global variable errno is set to
indicate the
error.
Standards [Toc] [Back]
The `.St' macro replaces standard abbreviature with its formal name.
Usage: .St abbreviature
Available pairs for ``Abbreviature/Formal Name'' are:
-p1003.1-88 IEEE Std 1003.1-1988 (``POSIX'')
-p1003.1-90 IEEE Std 1003.1-1990 (``POSIX'')
-p1003.1-96 ISO/IEC 9945-1:1996 (``POSIX'')
-p1003.1-2001 IEEE Std 1003.1-2001 (``POSIX'')
-p1003.1-2003 IEEE Std 1003.1-2003 (``POSIX'')
-p1003.1 IEEE Std 1003.1 (``POSIX'')
-p1003.1b IEEE Std 1003.1b (``POSIX'')
-p1003.1b-93 IEEE Std 1003.1b-1993 (``POSIX'')
-p1003.1c-95 IEEE Std 1003.1c-1995 (``POSIX'')
-p1003.1g-2000 IEEE Std 1003.1g-2000 (``POSIX'')
-p1003.2-92 IEEE Std 1003.2-1992 (``POSIX.2'')
-p1387.2-95 IEEE Std 1387.2-1995 (``POSIX.7.2'')
-p1003.2 IEEE Std 1003.2 (``POSIX.2'')
-p1387.2 IEEE Std 1387.2 (``POSIX.7.2'')
-isoC-90 ISO/IEC 9899:1990 (``ISO C90'')
-isoC-amd1 ISO/IEC 9899/AMD1:1995 (``ISO C90'')
-isoC-tcor1 ISO/IEC 9899/TCOR1:1994 (``ISO C90'')
-isoC-tcor2 ISO/IEC 9899/TCOR2:1995 (``ISO C90'')
-isoC-99 ISO/IEC 9899:1999 (``ISO C99'')
-ansiC ANSI X3.159-1989 (``ANSI C'')
-ansiC-89 ANSI X3.159-1989 (``ANSI C'')
-ansiC-99 ANSI/ISO/IEC 9899-1999 (``ANSI C99'')
-ieee754 IEEE Std 754-1985
-iso8802-3 ISO 8802-3: 1989
-xpg3 X/Open Portability Guide Issue 3
(``XPG3'')
-xpg4 X/Open Portability Guide Issue 4
(``XPG4'')
-xpg4.2 X/Open Portability Guide Issue 4.2
(``XPG4.2'')
-xpg4.3 X/Open Portability Guide Issue 4.3
(``XPG4.3'')
-xbd5 X/Open System Interface Definitions
Issue 5
(``XBD5'')
-xcu5 X/Open Commands and Utilities Issue 5
(``XCU5'')
-xsh5 X/Open System Interfaces and Headers
Issue 5
(``XSH5'')
-xns5 X/Open Networking Services Issue 5
(``XNS5'')
-xns5.2d2.0 X/Open Networking Services Issue 5.2
Draft 2.0
(``XNS5.2D2.0'')
-xcurses4.2 X/Open Curses Issue 4 Version 2
(``XCURSES4.2'')
-susv2 Version 2 of the Single UNIX Specification
-susv3 Version 3 of the Single UNIX Specification
-svid4 System V Interface Definition, Fourth
Edition
(``SVID4'')
Variable Types [Toc] [Back]
The `.Vt' macro may be used whenever a type is referenced.
In the
SYNOPSIS section, it causes a line break (useful for oldstyle variable
declarations).
Usage: .Vt <type> ... { . , ; : ? ! ( ) [ ]}
.Vt extern char *optarg; extern char *optarg;
.Vt FILE * FILE *
It is an error to call `.Vt' without any arguments. The
`.Vt' macro is
parsed and is callable.
Variables [Toc] [Back]
Generic variable reference:
Usage: .Va variable ... { . , ; : ? ! ( ) [ ]}
.Va count count
.Va settimer, settimer,
.Va int *prt ) : int *prt):
.Va char s ] ) ) , char s])),
It is an error to call `.Va' without any arguments. The
`.Va' macro is
parsed and is callable.
Manual Page Cross References [Toc] [Back]
The `.Xr' macro expects the first argument to be a manual
page name, and
the second argument, if it exists, to be either a section
number or punctuation.
Any remaining arguments are assumed to be punctuation.
Usage: .Xr man_page [1,...,9] { . , ; : ? ! ( ) [ ]}
.Xr mdoc mdoc
.Xr mdoc , mdoc,
.Xr mdoc 7 mdoc(7)
.Xr mdoc 7 ) ) , mdoc(7))),
The `.Xr' macro is parsed and is callable. It is an error
to call `.Xr'
without any arguments.
AT&T Macro
Usage: .At [v6 | v7 | 32v | V.1 | V.4] ...
.At AT&T UNIX
.At v6 Version 6 AT&T UNIX
The `.At' macro is not parsed and not callable. It accepts
at most two
arguments. It cannot currently handle punctuation.
BSD Macro [Toc] [Back]
Usage: .Bx [Version/release] ... { . , ; : ? ! ( ) [
]}
.Bx BSD
.Bx 4.3 . 4.3BSD.
The `.Bx' macro is parsed, but is not callable.
BSDI Macro [Toc] [Back]
Usage: .Bsx [Version/release] ... { . , ; : ? ! ( ) [
]}
.Bsx BSDI BSD/OS
.Bsx 3.0 . BSDI BSD/OS 3.0.
The `.Bsx' macro is parsed, but is not callable.
OpenBSD/FreeBSD/NetBSD Macros
Usage: .Ox [Version/release] ... { . , ; : ? ! ( ) [
]}
.Ox OpenBSD
.Ox 2.7 . OpenBSD 2.7.
Usage: .Fx [Version/release] ... { . , ; : ? ! ( ) [
]}
.Fx FreeBSD
.Fx 4.0 . FreeBSD 4.0.
Usage: .Nx [Version/release] ... { . , ; : ? ! ( ) [
]}
.Nx NetBSD
.Nx 1.5 . NetBSD 1.5.
The `.Ox', `.Fx', and `.Nx' macros are not parsed and are
not callable.
UNIX Macro [Toc] [Back]
Usage: .Ux ... { . , ; : ? ! ( ) [ ]}
.Ux UNIX
The `.Ux' macro is parsed, but is not callable.
Emphasis Macro [Toc] [Back]
Text may be stressed or emphasized with the `.Em' macro.
The usual font
for emphasis is italic.
Usage: .Em argument ... { . , ; : ? ! ( ) [ ]}
.Em does not does not
.Em exceed 1024 . exceed 1024.
.Em vide infra ) ) , vide infra)),
The `.Em' macro is parsed and is callable. It is an error
to call `.Em'
without arguments.
Font Mode [Toc] [Back]
The `.Bf' font mode must end with the `.Ef' macro (which
takes no arguments).
Font modes may be nested within other font modes.
Usage: .Bf font mode
Font mode must be one of the following:
Em | -emphasis Same as if the `.Em' macro was used
for the entire
block of text.
Li | -literal Same as if the `.Li' macro was used
for the entire
block of text.
Sy | -symbolic Same as if the `.Sy' macro was used
for the entire
block of text.
Enclosure and Quoting Macros [Toc] [Back]
The concept of enclosure is similar to quoting. The object
being to enclose
one or more strings between a pair of characters like
quotes or
parentheses. The terms quoting and enclosure are used interchangeably
throughout this document. Most of the one line enclosure
macros end in
small letter `q' to give a hint of quoting, but there are a
few irregularities.
For each enclosure macro there is also a pair of
open and
close macros which end in small letters `o' and `c' respectively. These
can be used across one or more lines of text and while they
have nesting
limitations, the one line quote macros can be used inside of
them.
Quote Close Open Function
Result
.Aq .Ac .Ao Angle Bracket Enclosure
<string>
.Bq .Bc .Bo Bracket Enclosure
[string]
.Dq .Dc .Do Double Quote
``string''
.Ec .Eo Enclose String (in XX)
XXstringXX
.Pq .Pc .Po Parenthesis Enclosure
(string)
.Ql Quoted Literal
`st' or string
.Qq .Qc .Qo Straight Double Quote
"string"
.Sq .Sc .So Single Quote
`string'
Except for the irregular macros noted below, all of the
quoting macros
are parsed and callable. All handle punctuation properly,
as long as it
is presented one character at a time and separated by
spaces. The quoting
macros examine opening and closing punctuation to determine whether
it comes before or after the enclosing string. This makes
some nesting
possible.
.Eo, .Ec These macros expect the first argument to be the
opening and
closing strings respectively.
.Ql The quoted literal macro behaves differently for
troff(1) than
nroff(1). If formatted with nroff(1), a quoted
literal is always
quoted. If formatted with troff(1), an item
is only quoted
if the width of the item is less than three
constant width
characters. This is to make short strings more
visible where
the font change to literal (constant width) is
less noticeable.
Examples of quoting:
.Aq <>
.Aq Ar ctype.h ) , <ctype.h>),
.Bq []
.Bq Em Greek , French . [Greek, French].
.Dq ``''
.Dq string abc . ``string abc''.
.Dq '^[A-Z]' ``'^[A-Z]'''
.Ql man mdoc `man mdoc'
.Qq ""
.Qq string ) , "string"),
.Qq string Ns ), "string),"
.Sq `'
.Sq string `string'
For a good example of nested enclosure macros, see the `.Op'
option
macro. It was created from the same underlying enclosure
macros as those
presented in the list above. The `.Xo' and `.Xc' extended
argument list
macros were also built from the same underlying routines and
are a good
example of -mdoc macro usage at its worst.
No-Op or Normal Text Macro [Toc] [Back]
The macro `.No' is a hack for words in a macro command line
which should
not be formatted and follows the conventional syntax for
content macros.
No Space Macro [Toc] [Back]
The `.Ns' macro eliminates unwanted spaces in between macro
requests. It
is useful for old style argument lists where there is no
space between
the flag and argument:
.Op Fl I Ns Ar directory produces [-Idirectory]
Note: the `.Ns' macro always invokes the `.No' macro after
eliminating
the space unless another macro name follows it. The macro
`.Ns' is
parsed and is callable.
Prefix Macro [Toc] [Back]
The `.Pf' macro eliminates unwanted spaces between its first
and second
arguments.
.Pf ( Fa name2 produces (name2
The prefix macro is not callable, but it is parsed.
Section Cross References [Toc] [Back]
The `.Sx' macro designates a reference to a section header
within the
same document. It is parsed and is callable.
.Sx FILES FILES
Space Mode Macro [Toc] [Back]
The `.Sm' macro turns spacing on or off. It is especially
useful in situations
where the `.Ns' macro may be too clumsy to use. An
argument of
either -on or -off must be specified, to turn spacing on or
off, respectively.
Usage: .Sm -on | -off
See Extended Arguments (below) for example usage.
Symbolic Macro [Toc] [Back]
The symbolic emphasis macro is generally a boldface macro in
either the
symbolic sense or the traditional English usage.
Usage: .Sy symbol ... { . , ; : ? ! ( ) [ ]}
.Sy Important Notice Important Notice
The `.Sy' macro is parsed and is callable. Arguments to
`.Sy' may be
quoted.
Mathematical Symbols [Toc] [Back]
Use this macro for mathematical symbols.
Usage: .Ms mathematical symbol ... { . , ; : ? ! ( ) [
]}
.Ms sigma sigma
The `.Ms' macro is parsed, but is not callable.
References and Citations [Toc] [Back]
The following macros make a modest attempt to handle references. At
best, the macros make it convenient to manually drop in a
subset of
refer(1) style references.
.Rs Reference Start. Causes a line break and begins collection
of reference information until the reference
end macro is
read.
.Re Reference End. The reference is printed.
.%A Reference author name, one name per invocation.
.%B Book title.
.%D Date.
.%I Issuer/Publisher Name.
.%J Journal name.
.%N Issue number.
.%O Optional information.
.%P Page number.
.%Q Corporate or Foreign Author.
.%R Report name.
.%T Title of article.
.%V Volume(s).
The macros beginning with `%' are not callable, and are
parsed only for
the trade name macro which returns to its caller. (And not
very predictably
at the moment either.) The purpose is to allow
trade names to
be pretty printed in troff(1)/ditroff output.
Trade
|
