version 1.4, 2009/03/22 14:35:16 |
version 1.5, 2009/03/22 19:01:11 |
|
|
If you add something to your operating system, whether it's a new file |
If you add something to your operating system, whether it's a new file |
format or directory structure or device driver, it needs documentation. |
format or directory structure or device driver, it needs documentation. |
.\" SECTION |
.\" SECTION |
.Sh CLASSIFICATION |
.Sh COMPOSITION |
Classify your system component. In |
Prepare your composition environment by copying over the manual template |
.Ux , |
from |
each component has a manual section , which categorises the component's |
.Pa /usr/share/misc/mdoc.template . |
function. The section of a manual is usually listed in parenthesis next |
.Em \&Do not |
to the component name, such as |
start afresh or by copying another manual unless you know exactly what |
.Xr ps 1 , |
you're doing! |
section 1. You can query a manual explicitly by its section: |
.\" SUBSECTION |
.Bd -literal -offset XXXX |
.Ss Section Numbering |
% man \-s 1 ps |
Find an appropriate section for your manual. There may exist multiple |
% apropos ps |
manual names per section, so be specific. A table of all available |
.Ed |
manual sections follows: |
.Pp |
.Pp |
The following table lists classifications and the applicable manual |
.\" LIST |
sections: |
|
.Pp |
|
.Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact |
.Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact |
.It Em Section |
.It Em Section |
.Em Description |
.Em Description |
Line 62 administrator utilities |
|
Line 60 administrator utilities |
|
in-kernel routines |
in-kernel routines |
.El |
.El |
.Pp |
.Pp |
Some examples in regular name/section form: |
If your manual falls into multiple categories, choose the most |
.Pp |
widely-used or, better, re-consider the topic of your manual to be more |
.\" LIST |
specific. You can list all manuals per section by invoking |
.Bl -tag -width "File-formatX" -offset indent -compact |
.Xr apropos 1 , |
.It Em Manual |
then provide the |
.Em Description |
.Fl s |
.It Xr dc 4 |
flag to |
DEC/Intel 10/100 Ethernet device |
.Xr man 1 |
.It Xr usermod 8 |
to see the specific section manual (section 1, in this example): |
modify user login information |
.\" DISPLAY |
.It Xr cc 1 |
.Bd -literal -offset indent |
the C compiler |
% apropos myname |
.It Xr fortune 6 |
myname (1) - some description here |
print a random adage |
% man \-s 1 myname |
.It Xr open 2 |
.Ed |
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 by copying over the manual template |
|
from |
|
.Pa /usr/share/misc/mdoc.template . |
|
.Em \&Do not |
|
start afresh or by copying another manual unless you know exactly what |
|
you're doing! |
|
.\" SUBSECTION |
.\" 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. You may |
.Xr man 1 . |
want to look for 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. |
|
|
.Xr roff 7 ; |
.Xr roff 7 ; |
newer languages such as DocBook, texinfo or schema-driven XML; or even |
newer languages such as DocBook, texinfo or schema-driven XML; or even |
ad-hoc conventions such as README files. |
ad-hoc conventions 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 |
Historical formats fail to capture a manual's semantic content, instead |
only modelling its style. Newer methods requires special, |
only modelling its style. Newer methods requires special, |
system-specific tools and may change or become obsolete over the |
system-specific tools and may change or become obsolete over the |
life-time of your component. |
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 |
|
|
\&.in.1: |
\&.in.1: |
mandoc -Wall,error -Tlint $< |
mandoc -Wall,error -Tlint $< |
cp -f $< $@ |
cp -f $< $@ |
|
|
\&.1.html: |
\&.1.html: |
mandoc -Thtml $< >$@ |
mandoc -Thtml $< >$@ |
|
|
\&.1.txt: |
\&.1.txt: |
mandoc -Tascii $< | col -b >$@ |
mandoc -Tascii $< | col -b >$@ |
.Ed |
.Ed |
Line 238 symbols and so on), use the escapes dictated in |
|
Line 212 symbols and so on), use the escapes dictated in |
|
.\" SUBSECTION |
.\" 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 266 lists), assume that your output device is a fixed-widt |
|
Line 240 lists), assume that your output device is a fixed-widt |
|
You may assume that the width calculated by the string literal |
You may assume that the width calculated by the string literal |
.Qq Fl o Ar outfile |
.Qq Fl o Ar outfile |
will be covered by the \-width argument. |
will be covered by the \-width argument. |
|
.\" SECTION |
|
.Sh MAINTENANCE |
|
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 |
|
smooth the development of your manuals. Don't. Source documentation is |
|
different from a component manual. |