.Dd $Mdocdate: March 22 2009 $
.Dt manuals 7
.Os
.\" SECTION
.Sh NAME
.Nm Writing UNIX Documentation
.Nd a guide to writing UNIX manuals
.\" SECTION
.Sh DESCRIPTION
.Em A utility without good documentation is of no utility at all .
.\" PARAGRAPH
.Pp
A system component's documentation describes the utility of that
component, whether it's a device driver, an executable or, most
importantly, a game.  Although there are plenty of documents available
on how to read 
.Ux 
documents, or where to find them, few focus on composition.
.\" PARAGRAPH
.Pp
This document serves as a tutorial to writing 
.Ux 
documentation
.Pq Dq manuals .
If you add something to your operating system, whether it's a new file
format or directory structure or device driver, it needs documentation.
.\" SECTION
.Sh CLASSIFICATION
Classify your system component.  In
.Ux ,
each component has a 
.Dq manual section ,
which categorises the component's function.  The section of a manual is
usually listed in parenthesis next to the component name, such as
.Xr ps 1 ,
section 1.  You can query a manual explicitly by its section:
.Pp
.Dl % man \-s 1 ps
.Pp
The following table lists classifications and the applicable manual
sections:
.Pp
.Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact
.It Em Section
.Em Description
.It 1
operator utilities
.It 2
system calls
.It 3, 3p, 3f
programming libraries (C, Perl, Fortran)
.It 5
file and wire protocol formats
.It 6
games
.It 7
tutorials, documents and papers
.It 8 
administrator utilities
.It 9
in-kernel routines
.El
.Pp
Some examples in regular name/section form:
.Pp
.\" LIST
.Bl -tag -width "File-formatX" -offset indent -compact
.It Em Manual
.Em Description
.It Xr dc 4
DEC/Intel 10/100 Ethernet device
.It Xr usermod 8
modify user login information
.It Xr cc 1
the C compiler
.It Xr fortune 6
print a random adage
.It Xr open 2
open or create a file for reading or writing
.It Xr isspace 3
whitespace character test
.It Xr Pod::Man 3p
convert POD data to formatted roff
.It Xr tsleep 9
process context sleep
.It Xr passwd 5
format of the password file
.It Xr symlink 7
symbolic link handling
.El
.\" SECTION
.Sh COMPOSITION
Prepare your composition environment.  
.\" SUBSECTION
.Ss Naming
Your component will need a name by which to query its contents via
.Xr man 1 .
Keep it simple.  You may want to look for other manuals by that same
name before committing:
.Pp
.Dl % apropos myname
.Pp
Conventionally, manual files are named 
.Pa myname.section ,
such as
.Pa manuals.7
for this document.
.\" SUBSECTION
.Ss Input Language
Manuals should 
.Em always 
be written in the
.Xr mdoc 7
formatting language.
.Pp
There exist other documentation-specific languages, such as the
historical
.Xr me 7 ,
.Xr ms 7
and
.Xr man 7
packages of 
.Xr roff 7 ;
newer languages such as DocBook, texinfo or schema-driven XML; or even
ad-hoc conventions such as README files.  
.Em Stay away from these methods!
Historical formats fail to capture a manual's semantic content, instead
only modelling its style.  Newer methods requires special,
system-specific tools and may change or become obsolete over the
life-time of your component.
.Pp
There are two canonical references for writing mdoc manuals:
.Pp
.\" LIST
.Bl -tag -width XXXXXXXXXXXXXXXX -offset indent -compact
.It Xr mdoc 7
formal language reference
.It Xr mdoc.samples 7
macro reference
.El
.Pp
Don't merely copy existing manuals!  Most systems distribute an mdoc
template to help you get started in
.Pa /usr/share/misc/mdoc.template .
.\" SUBSECTION
.Ss Development Tools
While writing, make sure that your manual is correctly structured:
.Pp
.Dl % mandoc \-Tlint \-Wall name.1
.Pp
You may spell-check your work as follows:
.Pp
.Dl % deroff name.1 | spell
.Dl % ispell \-n name.1
.Pp
Use 
.Xr cvs 1
or, if not available,
.Xr rcs 1
to version-control your work.  If you wish the last check-in to effect
your document's date, use the following RCS tag for the date macro:
.Pp
.Dl \&.Dd $Mdocdate: March 22 2009 $
.Pp
.\" SUBSECTION
.Ss Viewing
mdoc documents may be paged to your terminal with traditional 
tools such as
.Xr nroff 1 ,
.Xr groff 1 ,
or with newer, more powerful tools such as
.Xr mandoc 1 :
.\" DISPLAY
.Bd -literal -offset indent
% nroff \-mandoc name.1 | less
% groff \-Tascii \-mandoc name.1 | less
% mandoc name.1 | less
.Ed
.Pp
Other output formats are also supported:
.\" DISPLAY
.Bd -literal -offset indent
% groff \-Tps \-mandoc name.1 | less
% mandoc \-Thtml name.1 | less
.Ed
.\" SUBSECTION
.Ss Automation
Consider adding your mdoc documents to 
.Xr make 1
Makefiles in order to automatically check your input and generate
output:
.Bd -literal -offset indent
\&.SUFFIXES: .html .txt .1 .in

\&.in.1:
	mandoc -Wall,error -Tlint $<
	cp -f $< $@

\&.1.html:
	mandoc -Thtml $< >$@

\&.1.txt:
	mandoc -Tascii $< | col -b >$@
.Ed
.\" SECTION
.Sh BEST PRACTICES
The
.Xr mdoc 7
and 
.Xr mdoc.samples 7
files will be indispensable in guiding composition.  In this section, we
introduce some 
.Ux
manual best practices:
.\" SUBSECTION
.Ss Language
.Bl -enum 
.It
Use clear, concise language.  Favour simplicity.
.It
Write your manual in non-idiomatic English.  Don't worry about
Commonwealth or American spellings \(em just correct ones.
.It
Spell-check your manual, keeping in mind short-letter terms (
.Xr iwi 4
vs.
.Xr iwn 4 ) .
.It
If you absolutely must use special characters (diacritics, mathematical
symbols and so on), use the escapes dictated in
.Xr mdoc 7 .
.El
.\" SUBSECTION
.Ss References 
Other components may be referenced with the
.Sq \&Xr ,
and
.Sq \&Sx
macros.  Make sure that these exist.  If you intend to distribute your
manual, make sure
.Sq \&Xr
references are valid across systems (within reason).  If you cross-link with
.Sq \&Sx ,
make sure that the section reference exists.
.\" SUBSECTION
.Ss Citations
Cite your work.  If your system references standards documents or other
publications, please use the
.Sq \&Rs/Re
block macros.
.\" SUBSECTION
.Ss Formatting
Let the front-ends worry about formatting for you, but if you must think
about formatting (at times necessary, especially for tagged and columnar
lists), assume that your output device is a fixed-width terminal window:
.Bd -literal -offset indent
\&.Bl \-tag \-width "-o outfile"
\&.It \&Fl \&Ar outfile
.Ed
.Pp
You may assume that the width calculated by the string literal 
.Qq Fl o Ar outfile
will