version 1.16, 2009/07/16 22:16:44 |
version 1.17, 2009/07/20 13:45:11 |
|
|
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN |
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN |
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF |
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF |
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. |
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. |
.\" |
.\" |
.Dd $Mdocdate$ |
.Dd $Mdocdate$ |
.Dt MANUALS 7 |
.Dt MANUALS 7 |
.Os |
.Os |
|
|
.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. |
importantly, a game. |
.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 . |
.\" SECTION |
.\" SECTION |
.Sh ENVIRONMENT |
.Sh ENVIRONMENT |
First, copy over the manual template from |
First, copy over the manual template from |
.Pa /usr/share/misc/mdoc.template |
.Pa /usr/share/misc/mdoc.template |
into your source directory. |
into your source directory. |
.Pp |
.Pp |
Line 66 file and wire protocol formats |
|
Line 66 file and wire protocol formats |
|
games |
games |
.It 7 |
.It 7 |
tutorials, documents and papers |
tutorials, documents and papers |
.It 8 |
.It 8 |
administrator utilities |
administrator utilities |
.It 9 |
.It 9 |
in-kernel routines |
in-kernel routines |
Line 95 other manuals by that same name before committing: |
|
Line 95 other manuals by that same name before committing: |
|
.Pp |
.Pp |
.Dl % apropos myname |
.Dl % apropos myname |
.Pp |
.Pp |
Manual files are named |
Manual files are named |
.Pa myname.mysection , |
.Pa myname.mysection , |
such as |
such as |
.Pa manuals.7 |
.Pa manuals.7 |
Line 112 You may spell-check your work as follows: |
|
Line 112 You may spell-check your work as follows: |
|
.Pp |
.Pp |
.Dl % deroff name.1 | spell |
.Dl % deroff name.1 | spell |
.Pp |
.Pp |
If |
If |
.Xr ispell 1 |
.Xr ispell 1 |
is installed, it has a special mode for manuals: |
is installed, it has a special mode for manuals: |
.Pp |
.Pp |
.Dl % ispell \-n name.1 |
.Dl % ispell \-n name.1 |
.Pp |
.Pp |
Use |
Use |
.Xr cvs 1 |
.Xr cvs 1 |
or |
or |
.Xr rcs 1 |
.Xr rcs 1 |
Line 128 your document's date, use the following RCS tag for th |
|
Line 128 your document's date, use the following RCS tag for th |
|
.Dl \&.Dd $Mdocdate$ |
.Dl \&.Dd $Mdocdate$ |
.\" SUBSECTION |
.\" SUBSECTION |
.Ss Viewing |
.Ss Viewing |
mdoc documents may be paged to your terminal with |
mdoc documents may be paged to your terminal with |
.Xr mandoc 1 . |
.Xr mandoc 1 . |
If you plan on distributing your work to systems without this tool, |
If you plan on distributing your work to systems without this tool, |
check it against |
check it against |
Line 139 check it against |
|
Line 139 check it against |
|
.Ed |
.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: |
Makefiles in order to automatically check your input: |
.Bd -literal -offset indent |
.Bd -literal -offset indent |
Line 155 Your manual must have a license. It should be listed |
|
Line 155 Your manual must have a license. It should be listed |
|
your document, just as in source code. |
your document, just as in source code. |
.\" SECTION |
.\" SECTION |
.Sh COMPOSITION |
.Sh COMPOSITION |
Manuals should |
Manuals should |
.Em always |
.Em always |
be written in the |
be written in the |
.Xr mdoc 7 |
.Xr mdoc 7 |
formatting language. |
formatting language. |
Line 167 Open the template you've copied into |
|
Line 167 Open the template you've copied into |
|
and begin editing. |
and begin editing. |
.\" SUBSECTION |
.\" SUBSECTION |
.Ss Language |
.Ss Language |
.Bl -enum |
.Bl -enum |
.It |
.It |
Use clear, concise language. Favour simplicity. |
Use clear, concise language. Favour simplicity. |
.It |
.It |
Line 187 symbols and so on), use the escapes dictated in |
|
Line 187 symbols and so on), use the escapes dictated in |
|
.Ss Style |
.Ss Style |
The structure of the mdoc language makes it very hard to have any |
The structure of the mdoc language makes it very hard to have any |
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. |
The same goes for function prototypes. |
.Em \&Do not |
.Em \&Do not |
use |
use |
.Sq \&Xo/Xc . |
.Sq \&Xo/Xc . |
Find another way to structure your line. |
Find another way to structure your line. |
.\" 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 |