mandoc/manuals.7 - diff

Return to manuals.7 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/Attic/manuals.7 between version 1.3 and 1.9

version 1.3, 2009/03/22 14:28:08

version 1.9, 2009/03/24 10:59:50

Line 1

.\" $Id$

.\"

.\" 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$

.Dt manuals 7

.Os

Line 25 documentation

Line 43 documentation

If you add something to your operating system, whether it's a new file

format or directory structure or device driver, it needs documentation.

.\" 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

.Pa /usr/share/misc/mdoc.template .

.Dq manual section ,

which categorises the component's function. The section of a manual is

usually listed in parenthesis next to the component name, such as

.Xr ps 1 ,

section 1. You can query a manual explicitly by its section:

.Pp

.Dl % man \-s 1 ps

If this file doesn't exist, bug your administrator.

.Em \&Do not

start afresh or by copying another manual unless you know exactly what

you're doing!

.\" SUBSECTION

.Ss Section Numbering

Find an appropriate section for your manual. There may exist multiple

manual names per section, so be specific. A table of all available

manual sections follows:

.Pp

The following table lists classifications and the applicable manual

.\" LIST

sections:

.Pp

.Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact

.It Em Section

.Em Description

Line 61 administrator utilities

Line 80 administrator utilities

in-kernel routines

.El

.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) - utility description

print a random adage

myname (3) - library description

.It Xr open 2

% man \-s 1 myname

open or create a file for reading or writing

.Ed

.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.

.\" SUBSECTION

.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

.Dl % apropos myname

.Pp

Conventionally, manual files are named

Manual files are named

.Pa myname.section ,

.Pa myname.mysection ,

such as

.Pa manuals.7

for this document.

Line 115 formatting language.

Line 118 formatting language.

.Pp

There exist other documentation-specific languages, such as the

historical

.Xr me 7 ,

.Xr ms 7

and

.Xr man 7

packages of

package of

.Xr roff 7 ;

newer languages such as DocBook, texinfo or schema-driven XML; or even

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

only modelling its style. Newer methods requires special,

system-specific tools and may change or become obsolete over the

life-time of your component.

.Pp

There are two canonical references for writing mdoc manuals:

There are two canonical references for writing mdoc. Read them.

.Pp

.\" LIST

.Bl -tag -width XXXXXXXXXXXXXXXX -offset indent -compact

Line 139 formal language reference

macro reference

.El

.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

.Ss Development Tools

While writing, make sure that your manual is correctly structured:

Line 162 your document's date, use the following RCS tag for th

.Pp

.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

.Ss Viewing

mdoc documents may be paged to your terminal with traditional

Line 195 output:

Line 199 output:

\&.in.1:

mandoc -Wall,error -Tlint $<

cp -f $< $@

\&.1.html:

mandoc -Thtml $< >$@

\&.1.txt:

mandoc -Tascii $< | col -b >$@

.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

.Sh BEST PRACTICES

The

.Xr mdoc 7

and

.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

.Ux

manual best practices:

Line 231 symbols and so on), use the escapes dictated in

Line 237 symbols and so on), use the escapes dictated in

.Xr mdoc 7 .

.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

.Ss References

Other components may be referenced with the

.Sq \&Xr ,

.Sq \&Xr

and

.Sq \&Sx

macros. Make sure that these exist. If you intend to distribute your

Line 250 publications, please use the

Line 267 publications, please use the

block macros.

.\" SUBSECTION

.Ss Formatting

Let the front-ends worry about formatting for you, but if you must think

.Em Don't style your manual.

about formatting (at times necessary, especially for tagged and columnar

Give it meaningful content. The front-end will worry about formatting

lists), assume that your output device is a fixed-width terminal window:

and style.

.Bd -literal -offset indent

.\" SECTION

\&.Bl \-tag \-width "-o outfile"

.Sh MAINTENANCE

\&.It \&Fl \&Ar outfile

As your component changes and bugs are fixed, your manual may become out

.Ed

of date. You may be tempted to use automation tools like Doxygen to

.Pp

smooth the development of your manuals. Don't. Source documentation is

You may assume that the width calculated by the string literal

different from a component manual.

.Qq Fl o Ar outfile

will

CVSweb