version 1.7, 2009/03/22 21:19:34 |
version 1.9, 2009/03/24 10:59:50 |
|
|
|
.\" $Id$ |
|
.\" |
|
.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org> |
|
.\" |
|
.\" Permission to use, copy, modify, and distribute this software for any |
|
.\" purpose with or without fee is hereby granted, provided that the |
|
.\" above copyright notice and this permission notice appear in all |
|
.\" copies. |
|
.\" |
|
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL |
|
.\" WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED |
|
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE |
|
.\" AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL |
|
.\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR |
|
.\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER |
|
.\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR |
|
.\" PERFORMANCE OF THIS SOFTWARE. |
|
.\" |
.Dd $Mdocdate$ |
.Dd $Mdocdate$ |
.Dt manuals 7 |
.Dt manuals 7 |
.Os |
.Os |
Line 29 format or directory structure or device driver, it nee |
|
Line 47 format or directory structure or device driver, it nee |
|
Prepare your composition environment by copying over the manual template |
Prepare your composition environment by copying over the manual template |
from |
from |
.Pa /usr/share/misc/mdoc.template . |
.Pa /usr/share/misc/mdoc.template . |
|
.Pp |
|
If this file doesn't exist, bug your administrator. |
.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! |
Line 98 formatting language. |
|
Line 118 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, texinfo or schema-driven XML; or even |
ad-hoc conventions such as README files. |
ad-hoc conventions such as README files. |
Line 144 to version-control your work. If you wish the last ch |
|
Line 161 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 |
|
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 traditional |
|
|
\&.1.txt: |
\&.1.txt: |
mandoc -Tascii $< | col -b >$@ |
mandoc -Tascii $< | col -b >$@ |
.Ed |
.Ed |
|
.\" SUBSECTION |
|
.Ss Licensing |
|
Your manual must have a license. It should be listed at the start of |
|
your document, just as in source code. |
.\" SECTION |
.\" SECTION |
.Sh BEST PRACTICES |
.Sh BEST PRACTICES |
The |
The |
Line 210 If you absolutely must use special characters (diacrit |
|
Line 236 If you absolutely must use special characters (diacrit |
|
symbols and so on), use the escapes dictated in |
symbols and so on), use the escapes dictated in |
.Xr mdoc 7 . |
.Xr mdoc 7 . |
.El |
.El |
|
.\" SUBSECTION |
|
.Ss Style |
|
The structure of the mdoc language makes it very hard to have any |
|
particular format style. Keep your lines under 72 characters in length. |
|
If you must have long option lines, use |
|
.Sq \&Oo/Oc . |
|
.Em \&Do not |
|
use |
|
.Sq \&Xo/Xc ; |
|
instead, either fine another way to write long lines, or, at the |
|
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 |