version 1.10, 2009/03/26 23:01:26 |
version 1.14, 2009/06/10 20:18:43 |
|
|
.\" $Id$ |
.\" $Id$ |
.\" |
.\" |
.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org> |
.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se> |
.\" |
.\" |
.\" Permission to use, copy, modify, and distribute this software for any |
.\" Permission to use, copy, modify, and distribute this software for any |
.\" purpose with or without fee is hereby granted, provided that the |
.\" purpose with or without fee is hereby granted, provided that the above |
.\" above copyright notice and this permission notice appear in all |
.\" copyright notice and this permission notice appear in all copies. |
.\" copies. |
|
.\" |
.\" |
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL |
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES |
.\" WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED |
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF |
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE |
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR |
.\" AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL |
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES |
.\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR |
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN |
.\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER |
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF |
.\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR |
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. |
.\" PERFORMANCE OF THIS SOFTWARE. |
|
.\" |
.\" |
.Dd $Mdocdate$ |
.Dd $Mdocdate$ |
.Dt manuals 7 |
.Dt MANUALS 7 |
.Os |
.Os |
.\" SECTION |
.\" SECTION |
.Sh NAME |
.Sh NAME |
|
|
.Pq Dq manuals . |
.Pq Dq manuals . |
.\" 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 |
Line 100 Manual files are named |
|
Line 99 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 |
|
|
.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 140 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 |
|
|
.\" 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. |