version 1.2, 2009/03/22 14:09:38 |
version 1.14, 2009/06/10 20:18:43 |
|
|
|
.\" $Id$ |
|
.\" |
|
.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se> |
|
.\" |
|
.\" Permission to use, copy, modify, and distribute this software for any |
|
.\" purpose with or without fee is hereby granted, provided that the above |
|
.\" copyright notice and this permission notice appear in all copies. |
|
.\" |
|
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES |
|
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF |
|
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR |
|
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES |
|
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN |
|
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF |
|
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. |
|
.\" |
.Dd $Mdocdate$ |
.Dd $Mdocdate$ |
.Dt manuals 7 |
.Dt MANUALS 7 |
.Os |
.Os |
.\" SECTION |
.\" SECTION |
.Sh NAME |
.Sh NAME |
|
|
.Pp |
.Pp |
A system component's documentation describes the utility of that |
A system component's documentation describes the utility of that |
component, whether it's a device driver, an executable or, most |
component, whether it's a device driver, an executable or, most |
importantly, a game. Although there are plenty of documents available |
importantly, a game. |
on how to read |
|
.Ux |
|
documents, or where to find them, few focus on composition. |
|
.\" PARAGRAPH |
|
.Pp |
.Pp |
This document serves as a tutorial to writing |
This document serves as a tutorial to writing |
.Ux |
.Ux |
documentation |
documentation |
.Pq Dq manuals . |
.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 |
.\" SECTION |
.Sh CLASSIFICATION |
.Sh COMPOSITION |
Classify your system component. In |
First, copy over the manual template from |
.Ux , |
.Pa /usr/share/misc/mdoc.template |
each component has a |
into your source directory. |
.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 |
.Pp |
.Dl % man \-s 1 ps |
.Dl % cp /usr/share/misc/mdoc.template \. |
.Pp |
.Pp |
The following table lists broad classifications and the applicable |
.Em \&Do not |
manual sections: |
start afresh or by copying another manual unless you know exactly what |
.Pp |
you're doing! If the template doesn't exist, bug your administrator. |
.\" LIST |
|
.Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact |
|
.It Em Category |
|
.Em Section(s) |
|
.It Device |
|
4 |
|
.It Executable |
|
1, 6, 8 |
|
.It Function |
|
2, 3, 9 |
|
.It File-format |
|
5 |
|
.It Other |
|
7 |
|
.El |
|
.\" SUBSECTION |
.\" SUBSECTION |
.Ss Devices |
.Ss Section Numbering |
Consists of hardware (and pseudo-) device driver documentation. Drivers |
Find an appropriate section for your manual. There may exist multiple |
are unilaterally classified in section 4. |
manual names per section, so be specific: |
.Em Note : |
|
these manuals are necessarily system- and architecture-specific. |
|
.Pp |
.Pp |
Example: |
|
.Pp |
|
.\" LIST |
.\" LIST |
.Bl -tag -width "File-formatX" -offset indent -compact |
|
.It Em Manual |
|
.Em Description |
|
.It Xr dc 4 |
|
DEC/Intel 10/100 Ethernet device |
|
.El |
|
.\" SUBSECTION |
|
.Ss Executables |
|
Executables consist of runnable binaries. They're further classified by |
|
operator utility: |
|
.Pp |
|
.\" LIST |
|
.Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact |
.Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact |
.It Em Section |
.It Em Section |
.Em Description |
.Em Description |
.It 1 |
.It 1 |
operator utilities |
operator utilities |
.It 8 |
|
administrator utilities |
|
.It 6 |
|
games |
|
.El |
|
.Pp |
|
Examples: |
|
.Pp |
|
.\" LIST |
|
.Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact |
|
.It Em Manual |
|
.Em Description |
|
.It Xr usermod 8 |
|
modify user login information |
|
.It Xr cc 1 |
|
the C compiler |
|
.It Xr fortune 6 |
|
print a random adage |
|
.El |
|
.\" SUBSECTION |
|
.Ss Functions |
|
Function documentation describes programme source code, whether in the |
|
form of libraries, modules or standalone sources. They're further |
|
classified by context: |
|
.Pp |
|
.\" LIST |
|
.Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact |
|
.It Em Section |
|
.Em Description |
|
.It 2 |
.It 2 |
system calls |
system calls |
.It 3, 3p, 3f |
.It 3, 3p, 3f |
programming libraries (C, Perl, Fortran) |
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 |
.It 9 |
in-kernel routines |
in-kernel routines |
.El |
.El |
.Pp |
.Pp |
.Em Note : |
If your manual falls into multiple categories, choose the most |
section 2 and 9 manuals are necessarily system- and often |
widely-used or, better, re-consider the topic of your manual to be more |
architecture-specific. Examples: |
specific. You can list all manuals per section by invoking |
.Pp |
.Xr apropos 1 , |
.\" LIST |
then provide the |
.Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact |
.Fl s |
.It Em Manual |
flag to |
.Em Description |
.Xr man 1 |
.It Xr open 2 |
to see the specific section manual (section 1, in this example): |
open or create a file for reading or writing |
.\" DISPLAY |
.It Xr isspace 3 |
.Bd -literal -offset indent |
whitespace character test |
% apropos myname |
.It Xr Pod::Man 3p |
myname (1) - utility description |
convert POD data to formatted roff |
myname (3) - library description |
.It Xr tsleep 9 |
% man \-s 1 myname |
process context sleep |
.Ed |
.El |
|
.\" SUBSECTION |
.\" SUBSECTION |
.Ss File-formats |
|
A file format usually describes the format of on-disc binary or text |
|
data, although it can also be used to describe wire protocols (this is |
|
usually best left to RFC). These manuals are unilaterally classified in |
|
section 5. |
|
.Pp |
|
Example: |
|
.Pp |
|
.\" LIST |
|
.Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact |
|
.It Em Manual |
|
.Em Description |
|
.It Xr passwd 5 |
|
format of the password file |
|
.El |
|
.\" SUBSECTION |
|
.Ss Other |
|
Documents with no other classification are relegated to section 7. This |
|
constitutes reference tutorials (such as this document) and other |
|
miscellaneous information. |
|
.Pp |
|
Examples: |
|
.Pp |
|
.\" LIST |
|
.Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact |
|
.It Em Manual |
|
.Em Description |
|
.It Xr ascii 7 |
|
ASCII character sets |
|
.It Xr symlink 7 |
|
symbolic link handling |
|
.El |
|
.\" SECTION |
|
.Sh COMPOSITION |
|
Prepare your composition environment. |
|
.\" SUBSECTION |
|
.Ss Naming |
.Ss Naming |
Your component will need a name by which to query its contents via |
Name your component. Be terse, erring on the side of clarity. Look for |
.Xr man 1 . |
other manuals by that same name before committing: |
Keep it simple. You may want to look for other manuals by that same |
|
name before committing: |
|
.Pp |
.Pp |
.Dl % apropos myname |
.Dl % apropos myname |
.Pp |
.Pp |
Conventionally, manual files are named |
Manual files are named |
.Pa myname.section , |
.Pa myname.mysection , |
such as |
such as |
.Pa manuals.7 |
.Pa manuals.7 |
for this document. |
for this document. Rename the template file: |
|
.Pp |
|
.Dl % mv mdoc.template myname.mysection |
.\" SUBSECTION |
.\" SUBSECTION |
.Ss Input Language |
.Ss Input Language |
Manuals should |
Manuals should |
Line 196 formatting language. |
|
Line 112 formatting language. |
|
.Pp |
.Pp |
There exist other documentation-specific languages, such as the |
There exist other documentation-specific languages, such as the |
historical |
historical |
.Xr me 7 , |
|
.Xr ms 7 |
|
and |
|
.Xr man 7 |
.Xr man 7 |
packages of |
package of |
.Xr roff 7 ; |
.Xr roff 7 ; |
newer languages such as DocBook, texinfo or schema-driven XML; or even |
newer languages such as DocBook or texinfo; or even ad-hoc conventions |
ad-hoc conventions such as README files. |
such as README files. |
.Em Stay away from these methods! |
.Em Avoid these formats . |
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 |
.Pp |
There are two canonical references for writing mdoc manuals: |
There are two canonical references for writing mdoc. Read them. |
.Pp |
.Pp |
.\" LIST |
.\" LIST |
.Bl -tag -width XXXXXXXXXXXXXXXX -offset indent -compact |
.Bl -tag -width XXXXXXXXXXXXXXXX -offset indent -compact |
Line 220 formal language reference |
|
Line 129 formal language reference |
|
macro reference |
macro reference |
.El |
.El |
.Pp |
.Pp |
Don't merely copy existing manuals! Most systems distribute an mdoc |
Open the template you've copied into |
template to help you get started in |
.Pa myname.mysection |
.Pa /usr/share/misc/mdoc.template . |
and begin editing. |
.\" SUBSECTION |
.\" SUBSECTION |
.Ss Development Tools |
.Ss Development Tools |
While writing, make sure that your manual is correctly structured: |
While writing, make sure that your manual is correctly structured: |
Line 232 While writing, make sure that your manual is correctly |
|
Line 141 While writing, make sure that your manual is correctly |
|
You may spell-check your work as follows: |
You may spell-check your work as follows: |
.Pp |
.Pp |
.Dl % deroff name.1 | spell |
.Dl % deroff name.1 | spell |
|
.Pp |
|
If |
|
.Xr ispell 1 |
|
is installed, it has a special mode for manuals: |
|
.Pp |
.Dl % ispell \-n name.1 |
.Dl % ispell \-n name.1 |
.Pp |
.Pp |
Use |
Use |
.Xr cvs 1 |
.Xr cvs 1 |
or, if not available, |
or |
.Xr rcs 1 |
.Xr rcs 1 |
to version-control your work. If you wish the last check-in to effect |
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: |
your document's date, use the following RCS tag for the date macro: |
.Pp |
.Pp |
.Dl \&.Dd $Mdocdate$ |
.Dl \&.Dd $Mdocdate$ |
.Pp |
|
.\" SUBSECTION |
.\" SUBSECTION |
.Ss Viewing |
.Ss Viewing |
mdoc documents may be paged to your terminal with traditional |
mdoc documents may be paged to your terminal with |
tools such as |
.Xr mandoc 1 . |
.Xr nroff 1 , |
If you plan on distributing your work to systems without this tool, |
.Xr groff 1 , |
check it against |
or with newer, more powerful tools such as |
.Xr groff 1 : |
.Xr mandoc 1 : |
|
.\" DISPLAY |
|
.Bd -literal -offset indent |
.Bd -literal -offset indent |
% nroff \-mandoc name.1 | less |
% mandoc \-Wall name.1 2>&1 | less |
% groff \-Tascii \-mandoc name.1 | less |
% groff -mandoc name.1 2>&1 | less |
% mandoc name.1 | less |
|
.Ed |
.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 |
.\" SUBSECTION |
.Ss Automation |
.Ss Automation |
Consider adding your mdoc documents to |
Consider adding your mdoc documents to |
.Xr make 1 |
.Xr make 1 |
Makefiles in order to automatically check your input and generate |
Makefiles in order to automatically check your input: |
output: |
|
.Bd -literal -offset indent |
.Bd -literal -offset indent |
\&.SUFFIXES: .html .txt .1 .in |
\&.SUFFIXES: .1 .in |
|
|
\&.in.1: |
\&.in.1: |
mandoc -Wall,error -Tlint $< |
mandoc -Wall,error -Tlint $< |
cp -f $< $@ |
cp -f $< $@ |
|
|
\&.1.html: |
|
mandoc -Thtml $< >$@ |
|
|
|
\&.1.txt: |
|
mandoc -Tascii $< | col -b >$@ |
|
.Ed |
.Ed |
|
.\" SUBSECTION |
|
.Ss Licensing |
|
Your manual must have a license. It should be listed at the start of |
|
your document, just as in source code. |
.\" SECTION |
.\" SECTION |
.Sh BEST PRACTICES |
.Sh BEST PRACTICES |
The |
The |
.Xr mdoc 7 |
.Xr mdoc 7 |
and |
and |
.Xr mdoc.samples 7 |
.Xr mdoc.samples 7 |
files will be indispensable in guiding composition. In this section, we |
files are indispensable in guiding composition. In this section, we |
introduce some |
introduce some |
.Ux |
.Ux |
manual best practices: |
manual best practices: |
Line 312 symbols and so on), use the escapes dictated in |
|
Line 212 symbols and so on), use the escapes dictated in |
|
.Xr mdoc 7 . |
.Xr mdoc 7 . |
.El |
.El |
.\" SUBSECTION |
.\" SUBSECTION |
|
.Ss Style |
|
The structure of the mdoc language makes it very hard to have any |
|
particular format style. Keep your lines under 72 characters in length. |
|
If you must have long option lines, use |
|
.Sq \&Oo/Oc . |
|
The same goes for function prototypes. |
|
.Em \&Do not |
|
use |
|
.Sq \&Xo/Xc . |
|
Find another way to structure your line. |
|
.\" SUBSECTION |
.Ss References |
.Ss References |
Other components may be referenced with the |
Other components may be referenced with the |
.Sq \&Xr , |
.Sq \&Xr |
and |
and |
.Sq \&Sx |
.Sq \&Sx |
macros. Make sure that these exist. If you intend to distribute your |
macros. Make sure that these exist. If you intend to distribute your |
Line 330 publications, please use the |
|
Line 241 publications, please use the |
|
.Sq \&Rs/Re |
.Sq \&Rs/Re |
block macros. |
block macros. |
.\" SUBSECTION |
.\" SUBSECTION |
.Ss Types and Prototypes |
.Ss Formatting |
If writing section 3 manuals, make sure that you correctly annotate your |
.Em Don't style your manual . |
variables and functions. This guarantees that cross-referncing between |
Give it meaningful content. The front-end will worry about formatting |
function names and their prototypes works properly. |
and style. |
|
.\" SECTION |
|
.Sh MAINTENANCE |
|
As your component changes and bugs are fixed, your manual may become out |
|
of date. You may be tempted to use tools like Doxygen to automate the |
|
development of your manuals. Don't. |
|
.Pp |
|
.Em Manuals are part of a system component : |
|
if you modify your code or specifications, modify the documentation. |