version 1.3, 2009/03/22 14:28:08 |
version 1.4, 2009/03/22 14:35:16 |
Line 28 format or directory structure or device driver, it nee |
|
Line 28 format or directory structure or device driver, it nee |
|
.Sh CLASSIFICATION |
.Sh CLASSIFICATION |
Classify your system component. In |
Classify your system component. In |
.Ux , |
.Ux , |
each component has a |
each component has a manual section , which categorises the component's |
.Dq manual section , |
function. The section of a manual is usually listed in parenthesis next |
which categorises the component's function. The section of a manual is |
to the component name, such as |
usually listed in parenthesis next to the component name, such as |
|
.Xr ps 1 , |
.Xr ps 1 , |
section 1. You can query a manual explicitly by its section: |
section 1. You can query a manual explicitly by its section: |
|
.Bd -literal -offset XXXX |
|
% man \-s 1 ps |
|
% apropos ps |
|
.Ed |
.Pp |
.Pp |
.Dl % man \-s 1 ps |
|
.Pp |
|
The following table lists classifications and the applicable manual |
The following table lists classifications and the applicable manual |
sections: |
sections: |
.Pp |
.Pp |
Line 90 symbolic link handling |
|
Line 91 symbolic link handling |
|
.El |
.El |
.\" SECTION |
.\" SECTION |
.Sh COMPOSITION |
.Sh COMPOSITION |
Prepare your composition environment. |
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 |
Your component will need a name by which to query its contents via |
Line 139 formal language reference |
|
Line 145 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 name.section |
.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 161 to version-control your work. If you wish the last ch |
|
Line 167 to version-control your work. If you wish the last ch |
|
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 traditional |
|
|
.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 260 lists), assume that your output device is a fixed-widt |
|
Line 265 lists), assume that your output device is a fixed-widt |
|
.Pp |
.Pp |
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 |
will be covered by the \-width argument. |