version 1.8, 2009/03/23 09:42:43 |
version 1.11, 2009/04/03 13:17:26 |
|
|
.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 COMPOSITION |
.Sh COMPOSITION |
Prepare your composition environment by copying over the manual template |
First, copy over the manual template from |
from |
.Pa /usr/share/misc/mdoc.template |
.Pa /usr/share/misc/mdoc.template . |
into your source directory. |
.Pp |
.Pp |
If this file doesn't exist, bug your administrator. |
.Dl % cp /usr/share/misc/mdoc.template \. |
|
.Pp |
.Em \&Do not |
.Em \&Do not |
start afresh or by copying another manual unless you know exactly what |
start afresh or by copying another manual unless you know exactly what |
you're doing! |
you're doing! If the template doesn't exist, bug your administrator. |
.\" SUBSECTION |
.\" SUBSECTION |
.Ss Section Numbering |
.Ss Section Numbering |
Find an appropriate section for your manual. There may exist multiple |
Find an appropriate section for your manual. There may exist multiple |
manual names per section, so be specific. A table of all available |
manual names per section, so be specific: |
manual sections follows: |
|
.Pp |
.Pp |
.\" LIST |
.\" LIST |
.Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact |
.Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact |
Line 98 myname (3) - library description |
|
Line 92 myname (3) - library description |
|
.Ed |
.Ed |
.\" SUBSECTION |
.\" SUBSECTION |
.Ss Naming |
.Ss Naming |
Name your component. Be terse, erring on the side of clarity. You may |
Name your component. Be terse, erring on the side of clarity. Look for |
want to look for other manuals by that same name before committing: |
other manuals by that same name before committing: |
.Pp |
.Pp |
.Dl % apropos myname |
.Dl % apropos myname |
.Pp |
.Pp |
Line 107 Manual files are named |
|
Line 101 Manual files are named |
|
.Pa myname.mysection , |
.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 118 formatting language. |
|
Line 114 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 Avoid these formats . |
.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. Read them. |
There are two canonical references for writing mdoc. Read them. |
.Pp |
.Pp |
|
|
.El |
.El |
.Pp |
.Pp |
Open the template you've copied into |
Open the template you've copied into |
.Pa name.section |
.Pa myname.mysection |
and begin editing. |
and begin editing. |
.\" SUBSECTION |
.\" SUBSECTION |
.Ss Development Tools |
.Ss Development Tools |
Line 154 While writing, make sure that your manual is correctly |
|
Line 143 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 |
|
If using version control, the first line in your manual should be a |
|
comment with the |
|
.Li $Id$ |
|
rcs tag. |
|
.\" 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 |
.\" SUBSECTION |
.Ss Licensing |
.Ss Licensing |
Line 245 The structure of the mdoc language makes it very hard |
|
Line 219 The structure of the mdoc language makes it very hard |
|
particular format style. Keep your lines under 72 characters in length. |
particular format style. Keep your lines under 72 characters in length. |
If you must have long option lines, use |
If you must have long option lines, use |
.Sq \&Oo/Oc . |
.Sq \&Oo/Oc . |
|
The same goes for function prototypes. |
.Em \&Do not |
.Em \&Do not |
use |
use |
.Sq \&Xo/Xc ; |
.Sq \&Xo/Xc . |
instead, either fine another way to write long lines, or, at the |
Find another way to structure your line. |
absolute worst, use CPP-style newline escapes. |
|
.\" SUBSECTION |
.\" SUBSECTION |
.Ss References |
.Ss References |
Other components may be referenced with the |
Other components may be referenced with the |
Line 270 publications, please use the |
|
Line 244 publications, please use the |
|
block macros. |
block macros. |
.\" SUBSECTION |
.\" SUBSECTION |
.Ss Formatting |
.Ss Formatting |
.Em Don't style your manual. |
.Em Don't style your manual . |
Give it meaningful content. The front-end will worry about formatting |
Give it meaningful content. The front-end will worry about formatting |
and style. |
and style. |
.\" SECTION |
.\" SECTION |
.Sh MAINTENANCE |
.Sh MAINTENANCE |
As your component changes and bugs are fixed, your manual may become out |
As your component changes and bugs are fixed, your manual may become out |
of date. You may be tempted to use automation tools like Doxygen to |
of date. You may be tempted to use tools like Doxygen to automate the |
smooth the development of your manuals. Don't. Source documentation is |
development of your manuals. Don't. |
different from a component manual. |
.Pp |
|
.Em Manuals are part of a system component : |
|
if you modify your code or specifications, modify the documentation. |