.FP lucidasans
.de wa
.tm \\n(.F:\\n(.c: \\$1 \\$2 \\$3 \\$4 \\$5 
..
.de IR
.wa .IR macro
..
.de BR
.wa .BR macro
..
.de RB
.wa .RB macro
..
.de RI
.wa .RI macro
..
.de L
.wa .L macro
..
.de LR
.wa .LR macro
..
.de RL
.wa .RL macro
..
.de B
.wa .B macro
..
.de MM
.\" not quite .SM
\\$3\s-1\\$1\s+1\\$2
..
.nr Z \w'\f(CW 'u/4u
.de MA
.\" \\$1 is a macro name, without the leading dot
.\" put in the dot, but not taking up the full character width
\&\\$3\f(CW\h'-\nZu'.\h'-\nZu'\&\\$1\fP\^\\$2
..
.de TA
.sp 0.4v
.ne 4v
.\" tagged paragraph for section description
\h'2.5n'\fB\\$1\fP
.RS
..
.de TE
.RE
..
.TL
How to Write a Plan 9 Manual Page
.AU
Geoff Collyer
Russ Cox
(following Henry Spencer)
.AI
.CW geoff@collyer.net
.CW rsc@swtch.com
.LP
This document is an introduction to writing a Plan 9 manual page
using the
.I troff
manual page macros.
It does not cover every last detail; 
judgement and good taste are still necessary for writing readable
documentation, especially
when striving for clarity in the extremely concise format encouraged
by Plan 9.
This document is derived originally from a similar document written for
Unix by Henry Spencer.
.LP
Manual pages are stored as
.I troff
source files.
The manual ``page'' is a single file even if the printed form is several pages long.
The formatting macros are documented in
.I man (6).
This document is a more detailed explanation of them,
with examples of their usage.
.LP
This document first describes the low-level text formatting
and then discusses higher-level manual page considerations.
.SH
Fonts
.LP
Manual pages make fairly heavy use of
.I italic
and
.CW fixed-width
fonts.
There are standard macros for switching fonts.
All of them change the font of a small piece of text;
the text is either the arguments to the macro
(up to 6 words or strings in quotes) or,
if no argument is given, the next text line.
None of these macros break the current line,
so they may be used anywhere in text.
.LP
.MA I ,
.MA B
and
.MA L
provide italic, fixed-width (formerly bold),
and literal (fixed-width with single quotes around it in 
.I nroff )
text.
While the
.MA B
macro uses fixed-width font, the
.CW B
font (selected using
.CW \efB )
is still bold.
The fixed-width font is named 
.CW L
(for literal).
Explicit font changes using
.CW \ef
are eschewed in favor of the macros when possible.
.LP
Situations often arise where it is necessary to have one part of a word
in one font and another part in another.
For these situations, there are several macros which
merge the words from their text input into a single word,
alternating from one font to another from word to word.
For example,
.MA IR
alternates between italic and roman.
.MA BR ,
.MA IB ,
.MA IR ,
.MA RB ,
and
.MA RI 
exhaust the remaining combinations of roman, 
fixed-width, and italic.
There are also
.MA L ,
.MA LR
and
.MA RL
macros.
.LP
For example, 
.LP
.P1
\&.I Snprint
is like
\&.IR sprint ,
but will not place more than
\&.I len
bytes in
\&.IR s .
.P2
.IP
.I Snprint
is like
.I sprint ,
but will not place more than
.I len
bytes in
.I s .
.LP
.P1
The numeric verbs
\&.BR d ,
\&.BR o ,
\&.BR b ,
\&.BR x ,
and
\&.B X
format their arguments in decimal.
.P2
.IP
The numeric verbs
.CW d ,
.CW o ,
.CW b ,
.CW x ,
and
.CW X
format their arguments in decimal.
.LP
.P1
\&.I Utflen
returns the number of runes that are represented by the
\&.SM UTF
string
\&.IR s .
.P2
.IP
.I Utflen
returns the number of runes that
are represented by the
.SM UTF
string
.I s .
.LP
The
.MA SM
macro emits its arguments in smaller text
and is the usual method for typesetting all-capital names
such as
.SM UTF ,
.SM ASCII ,
and
.SM NUL .
.SH
Typing Conventions
.LP
Quotation marks are written using pairs of left and right quotes
(``) ('') rather than the double quotes (").
There are three reasons for this.
First, the double quotes are often used to enclose macro arguments;
there is no way to put them inside such arguments.
Second,
output on devices like laser printers
looks much better that way.
Third, the paired-quotes convention
.I is
the correct English
usage.
.LP
The hyphen, the dash, and the minus sign
are three different characters, even though most 
keyboards only have one key for all three.
The hyphen is simply
.CW - ,
the dash is
.CW \e- ,
and the minus sign is
.CW \e(em .
In the fixed-width font, there is no distinction between
.CW -
and
.CW \e-
and thus no need to use the latter.
.SH
Paragraphs
.LP
Text sections are normally a sequence of paragraphs.
Simple paragraphs are separated by
.MA PP ,
which outputs a small vertical space, checks that enough paper remains
on the page for a few more lines, and resets indents and the like.
The appearance of paragraphs produced by
.MA PP
is similar to that
of the paragraphs you are now reading.
It is not necessary to use
.CW .PP
to begin a new paragraph
after a subheader
.MA SH ). (
.LP
A ``tagged'' paragraph is one indented an extra amount and
preceded by a short
.I tag
in the space of the indent.
Tagged paragraphs are commonly used to discuss a list
of items, such as files or command line options.
Each tag is an item.
.LP
The
.MA TP
macro begins a tagged paragraph;
the first line after it is the tag, and subsequent lines
are the paragraph text.
An optional argument to the
.MA TP
macro sets the amount of the indent.
Setting the indent this way sets the default for future
.MA TP
invocations.
The
.MA PP
macro
resets the indent to its default setting.
.LP
Explicit indent lengths are rarely used.  Instead, the
.MA TF
macro
sets the 
.MA TP
indent to the width of its argument plus two spaces
in the fixed-width font.
This is useful when the paragraph tags are file names,
control messages, or other text formatted in fixed-width font.
.LP
A sequence of
.MA TP
paragraphs must end with a
.MA PD
request to
restore the usual interparagraph spacing.
For example:
.P1
\&.TF /adm/users
\&.TP
\&.B /adm/users
The user names known to the file server
\&.TP
\&.B /sys/games/lib/fortunes
Pithy comments
\&.PD
.P2
.IP
.nr W \w'\f(CW/adm/users  \fP'u
.CW /adm/users
.sp -1
.in +\nWu
The user names known to the file server
.sp .4v
.in -\nWu
.CW /sys/games/lib/fortunes
.sp .2v
.in +\nWu
Pithy comments
.sp .4v
.in 0
.LP
The
.CW .IP
macro behaves identically to 
.CW .TP ,
except that its first argument is the
tag and its second (optional) argument is the indent distance.
.SH
Title Heading
.LP
A manual page consists of a title heading, several subheadings,
and indented text paragraphs.
.LP
The title heading is defined by the
.CW .TH
macro, which takes two arguments:
.P1
\&\f(CW.TH\fR \fIname\fR \fIsection\fR
.P2
.I Name
and
.I section
are the name of the manual page and the section number
in which it appears.
.I Name
and
.I section
appear in the top corners of all manual pages.
.P1
\&.TH TROFF 1
\&.TH QSORT 2
\&.TH MAN 6
.P2
.LP
The
.MA TH
line
must be the first in the file.
.LP
The
.I name
argument to the
.MA TH
is usually the name of
the entity (program, function, library, etc.) being described.
Sometimes a manual page describes several entities;  in such cases,
the one used as the argument to
.MA TH
is the first one in the \s-1NAME\s+1
list (to be discussed in a moment).
A manual page which is not associated with any particular program,
function, etc.,
is named by what it describes, preferably
one short word (e.g.,
.I booting (8)).
.LP
The
.I section
in the
.MA TH
is the manual section number.
The Plan 9 manual has eight sections:
.IP
.ta \w'Section 9       'u
Section 1	General publicly accessible commands
.br
Section 2	Library functions, including system calls
.br
Section 3	Kernel devices (accessed via 
.I bind )
.br
Section 4	File services (accessed via
.I mount )
.br
Section 5	The Plan 9 file protocol, 9P
.br
Section 6	File formats
.br
Section 7	Databases and database access programs
.br
Section 8	Things related to administering Plan 9
.LP
A more detailed explanation of these chapters can be found in
the manual itself, specifically the
.I intro
manual page in each section.
.LP
The manual page source is stored in the file
\f(CW/sys/man/\fIsection\fP/\fIname\fP.
.SH
Page Sections
.LP
The sections in a manual page always appear in the following order:
.IP
.MM NAME
.br
.MM SYNOPSIS
.br
.MM DESCRIPTION
.br
.MM EXAMPLE 
(or 
.MM EXAMPLES )
.br
.MM FILES
.br
.MM SOURCE
.br
.MM "SEE ALSO
.br
.MM DIAGNOSTICS
.br
.MM BUGS
.LP
Not every section is needed for every manual page.
The Plan 9 manual intentionally omits many sections now common on 
modern Unix systems, 
such as
.MM AUTHOR ,
.MM HISTORY ,
.MM COPYRIGHT ,
and
.MM "REPORTING BUGS" .
.LP
A section heading is given, and a section begun, by a
.MA SH
macro with the heading as its argument.
The header is printed at the left margin;
the section is indented
a short distance.
.LP
.TA NAME
The
.MM NAME
section is present in every manual page.
It lists the exact names of the things discussed in the entry
followed by a short description.
If there is more than one name,
the first should be the one which best evokes visions of the whole list,
since that will also be the name of the manual entry as a whole.
(This criterion is admittedly a bit vague.)
.LP
The name(s) (separated by commas) are followed by a minus sign
.CW \e- ) (
and then the description.
Keep the description brief, less than a line.
Avoid font changes, special symbols, and cryptic buzzwords.
(The
.MM NAME
section is used by other programs, such as the one
which prepares the indices for the manual,
and those programs do not parse arbitrary
.I troff
input.)
Examples
(troff source, not printed output):
.P1
awk \e- pattern-directed scanning and processing language
bind, mount, unmount \e- change name space
calendar \e- print upcoming events
cmp \e- compare two files
.P2
.TE
.TA SYNOPSIS
.LP
Next, on most manual pages, is the 
.MM SYNOPSIS
section.
This is absent only in manual entries not discussing
identifiable programs, functions, etc., but rather
general concepts like booting.
The rule is: if there is any conceivable way to
.CW type
it, the synopsis section should say how.
.LP
Command synopses use the following notations:
.RS
.LP
.CW Fixed-width
text is literal, to be typed just as is appears.
.LP
.I Italic
text is a placeholder, indicating a place where an argument
such as a number or file name is to be typed.
.LP
Square brackets [\ ] around something mean that it is optional.
.LP
A pipe symbol
.CW |
between two things indicate that only one should be used.
.LP
An ellipsis ``...'' means that the previous thing can be repeated.
.RE
.LP
Because they are set in fixed-width font, command options
are typeset with a simple hyphen rather than the minus
that would be necessary in variable-width fonts.
.LP
By convention, options without arguments are listed first
in a single bracketing,
followed by the options taking arguments.
Both should usually be alphabetized.
.LP
For example:
.P1
\&.B hget
[
\&.B -dhv
] [
\&.B -o
\&.I ofile
] [
\&.B -p
\&.I body
] [
\&.B -x
\&.I netmntpt
]
\&.I url
.P2
.IP
.CW hget
[
.CW -dhv
] [
.CW -o
.I ofile
] [
.CW -p
.I body
] [
.CW -x
.I netmntpt
]
.I url
.LP
The same sort of conventions apply to \s-1SYNOPSIS\s0 sections for
things other than commands, although such sections tend
to use fixed-width text exclusively, since there is seldom
much choice about how to call a function.
If a manual entry describes more than one program, function, etc.,
the synopses are separated by a paragraph breaks (\c
.MA PP ).
.ne 12
.LP
Synopses in section 2 begin with the 
.CW #include
lines that must be used to load the given prototypes:
.P1
\&.B #include <u.h>
\&.br
\&.B #include <libc.h>
\&.PP
\&.B
int	runetochar(char *s, Rune *r)
\&.PP
\&.B
int	chartorune(Rune *r, char *s)
.P2
.ne 6
.IP
.CW "#include <u.h>
.br
.CW "#include <libc.h>
.IP
.CW
int	runetochar(char *s, Rune *r)
.IP
.CW
int	chartorune(Rune *r, char *s)
.TE
.TA DESCRIPTION
.LP
The
.MM DESCRIPTION
section is next and is present in all manual pages.
It is typically several paragraphs of narrative text
describing the details of what goes on.
It is helpful if the first paragraph is a capsule summary of
what the program (function, etc.) does and what its inputs and outputs are.
.LP
Within narrative text in a manual entry, the basic rules are those
of good English:  clarity and conciseness.
Paragraphs should be short.
Tables, lists, etc. should be used whenever they make something clearer.
Use the active voice.
Omit needless words.
For further guidance, see
.I "The Elements of Style"
by Strunk & White.
.LP
Frequently a narrative has cause to name programs, variables, macros,
etc., and to reproduce pieces of the \s-1SYNOPSIS\s0 section.
.LP
Pieces of the \s-1SYNOPSIS\s0 are reproduced as they occurred,
complete with font changes;
the same applies to any place where a similar notation is useful in
expanding on what is meant by something mentioned in the synopsis.
.LP
There is one exception to this:
names of programs, functions, files, and variables,
even the ones described in the synopsis,
are treated like foreign words: they are written in italics.
Such names are capitalized when they occur at the beginning of a sentence.
The ``italics'' rule applies even to name-and-chapter manual references in
the text:
within a
.MM DESCRIPTION
section, the proper way to refer to the
manual entry for, say, the mail program, is
.I mail (1).
.LP
References to programs or functions documented on pages with different names
should give the page reference as a parenthetical, as in:
.P1
The type of compression is inferred from the file name extension:
\&.I bzip2
(see
\&.IR gzip (1))
for
\&.BR .tar.bz ,
\&.BR .tbz ,
\&.BR .tar.bz2 ,
and
\&.BR .tbz2 .
.P2
.LP
The exact reference to
.I gzip (1),
as compared with a reference to the
non-existent page
.I bzip2 (1),
creates a valid hyperlink in the HTML version of the manual.
.LP
Constants,
.I troff
macros, file names,
and shell environment variables are generally written in fixed-width font.
.TE
.TA EXAMPLE
.LP
An
.MM EXAMPLE
section can be helpful when something
(especially some common usage) is tricky or non-obvious.
.LP
Avoid verbosity:  one of the major virtues of the \s-1UNIX\s0 and Plan 9
manual style is its compactness.
If there is more than one example, name the section
.MM EXAMPLES .
.TE
.TA FILES
.LP
The
.MM FILES
section
gives the names of the files which are built into the program.
The names are generally given one to a line,
with a comment following indicating what the file's significance is.
The list is often formatted using tagged paragraphs, discussed above.
.TE
.TA SOURCE
.LP
The
.MM SOURCE
section names the source files (or directory) providing each command or function.
.P1
\&.SH SOURCE
\&.B /sys/src/9/port/devcons.c
.P2
.TE
.TA "SEE ALSO
.LP
The
.MM "SEE ALSO
section gives pointers to related information, usually other manual pages
but sometimes external documents as well.
Manual page references are formatted in italics, as discussed above.
A list of references should be separated by commas.
.P1
\&.SH SEE ALSO
\&.IR ed (1),
\&.IR sed (1),
\&.IR grep (1),
\&.IR rio (1),
\&.IR regexp (6)
\&.PP
Rob Pike,
``The text editor sam''.
.P2
.TE
.TA DIAGNOSTICS
.LP
The
.MM DIAGNOSTICS
section explains diagnostics such as
the exit status of commands or the return value 
of functions.
If the diagnostics are considered to be sufficiently explained
in the description, this section is omitted.
.P1
\&.SH DIAGNOSTICS
If
\&.I echo
draws an error while writing to standard output, 
the exit status is
\&.LR "write error" .
Otherwise the exit status is empty.
.P2
.P1
\&.SH DIAGNOSTICS
\&.I Abs
and
\&.I labs
return
the most negative integer or long 
when the true result is unrepresentable.
.P2
.TE
.TA BUGS
.LP
The
.MM BUGS
section briefly lists shortcomings or other ``gotchas'' that the
user should be aware of when using the program.
This is the place to mention things which are unsatisfactory or tricky
about the program, even if it is not clear that they are bugs.
Mentioning something in a
.MM BUGS
section does not imply a commitment to fix it.
.P1
\&.SH BUGS
\&.I Bundle
will not create directories and is 
unsatisfactory for non-text files.
\&.PP
Beware of gift horses.
.P2
.TE
.LP
In general, if in doubt as to how to format something, it is better to
look for an existing manual page and imitate it than to invent
a new and unique style.
Standardization of style is a strong aid to
readability.
.SH
Formatting the Manual
.LP
Once a manual page has been installed, it can be displayed with
.I man (1).
By default, 
.I man
prints the manual page as text.
The 
.CW -P
option instructs
.I man
to typeset the manual page and display it in
.I page (1),
the PostScript viewer.
.LP
Before the manual page is installed, it can be displayed by
invoking 
.I troff 
directly:
.P1
troff -man file | page
nroff -man file
troff -man file | lp
.P2
.SH
Complete Examples
.LP
The appendices show the source and final typeset versions of
.I src (1)
and
.I pipe (2)
as reference examples.
The entire manual is a good source of further examples.