-.Dd $Mdocdate: March 22 2009 $
-.Dt "Writing Unix Documentation" paper
+.\" $Id: manuals.7,v 1.19 2009/07/27 19:43:02 kristaps Exp $
+.\"
+.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
+.\"
+.\" 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: July 27 2009 $
+.Dt MANUALS 7
.Os
+.\" SECTION
.Sh NAME
-.Nm Writing Unix Documentation
-.Nd a guide to writing Unix manuals
+.Nm Writing UNIX Documentation
+.Nd a guide to writing UNIX manuals
+.\" SECTION
.Sh DESCRIPTION
- <h1>
- Writing Unix Documentation
- </h1>
+.Em A utility without good documentation is of no utility at all .
+.\" PARAGRAPH
+.Pp
+A system component's documentation describes the utility of that
+component, whether it's a device driver, an executable or, most
+importantly, a game.
+.Pp
+This document serves as a tutorial to writing
+.Ux
+documentation
+.Pq Dq manuals .
+.\" SECTION
+.Sh ENVIRONMENT
+First, copy over the manual template from
+.Pa /usr/share/misc/mdoc.template
+into your source directory.
+.Pp
+.Dl % cp /usr/share/misc/mdoc.template \.
+.Pp
+.Em \&Do not
+start afresh or by copying another manual unless you know exactly what
+you're doing! If the template doesn't exist, bug your administrator.
+.\" SUBSECTION
+.Ss Section Numbering
+Find an appropriate section for your manual. There may exist multiple
+manual names per section, so be specific:
+.Pp
+.\" LIST
+.Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact
+.It Em Section
+.Em Description
+.It 1
+operator utilities
+.It 2
+system calls
+.It 3, 3p, 3f
+programming libraries (C, Perl, Fortran)
+.It 5
+file and wire protocol formats
+.It 6
+games
+.It 7
+tutorials, documents and papers
+.It 8
+administrator utilities
+.It 9
+in-kernel routines
+.El
+.Pp
+If your manual falls into multiple categories, choose the most
+widely-used or, better, re-consider the topic of your manual to be more
+specific. You can list all manuals per section by invoking
+.Xr apropos 1 ,
+then provide the
+.Fl s
+flag to
+.Xr man 1
+to see the specific section manual (section 1, in this example):
+.\" DISPLAY
+.Bd -literal -offset indent
+% apropos myname
+myname (1) - utility description
+myname (3) - library description
+% man \-s 1 myname
+.Ed
+.\" SUBSECTION
+.Ss Naming
+Name your component. Be terse, erring on the side of clarity. Look for
+other manuals by that same name before committing:
+.Pp
+.Dl % apropos myname
+.Pp
+Manual files are named
+.Pa myname.mysection ,
+such as
+.Pa manuals.7
+for this document. Rename the template file:
+.Pp
+.Dl % mv mdoc.template myname.mysection
+.\" SUBSECTION
+.Ss Development Tools
+While writing, make sure that your manual is correctly structured:
+.Pp
+.Dl % mandoc \-Tlint \-Wall \-fstrict name.1
+.Pp
+The quick-fix feature of
+.Xr vim 1
+is useful for checking over many manuals:
+.Bd -literal -offset indent
+% mandoc \-Wall \-fstrict \-Tlint \-fign-errors \e
+ ./path/to/manuals/* 2>&1 > /tmp/mandoc.errs
+% vim -q /tmp/mandoc.errs
+.Ed
+.Pp
+You may spell-check your work as follows:
+.Pp
+.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
+.Pp
+Use
+.Xr cvs 1
+or
+.Xr rcs 1
+to version-control your work. If you wish the last check-in to effect
+your document's date, use the following RCS tag for the date macro:
+.Pp
+.Dl \&.Dd $Mdocdate: July 27 2009 $
+.\" SUBSECTION
+.Ss Viewing
+mdoc documents may be paged to your terminal with
+.Xr mandoc 1 .
+If you plan on distributing your work to systems without this tool,
+check it against
+.Xr groff 1 :
+.Bd -literal -offset indent
+% mandoc \-Wall name.1 2>&1 | less
+% groff -mandoc name.1 2>&1 | less
+.Ed
+.\" SUBSECTION
+.Ss Automation
+Consider adding your mdoc documents to
+.Xr make 1
+Makefiles in order to automatically check your input:
+.Bd -literal -offset indent
+\&.SUFFIXES: .1 .in
- <p>
- <span class="attn">A utility without documentation is of no utility at all.</span>
- </p>
-
- <p>
- A system component's documentation describes the utility of that component, whether it's a device
- driver, an executable or, most importantly, a game. Although there are plenty of documents available on
- how to <i>read</i> Unix documents, or where to find them, few focus on how to <i>write</i> them.
- </p>
-
- <p>
- This document serves as a reference guide to writing Unix 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.
- </p>
- </td>
- </tr>
- <tr>
- <td>
- <div class="foot">
- Copyright © 2009 Kristaps Džonsons, $Date: 2009/03/22 08:52:27 $
- </div>
- </td>
- </tr>
- </tbody>
- </table>
- </body>
-</html>
+\&.in.1:
+ mandoc -Wall,error -Tlint $<
+ cp -f $< $@
+.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 COMPOSITION
+Manuals should
+.Em always
+be written in the
+.Xr mdoc 7
+formatting language.
+.\" PARAGRAPH
+.Pp
+Open the template you've copied into
+.Pa myname.mysection
+and begin editing.
+.\" SUBSECTION
+.Ss Language
+.Bl -enum
+.It
+Use clear, concise language. Favour simplicity.
+.It
+Write your manual in non-idiomatic English. Don't worry about
+Commonwealth or American spellings \(em just correct ones.
+.It
+Spell-check your manual, keeping in mind short-letter terms (
+.Xr iwi 4
+vs.
+.Xr iwn 4 ) .
+.It
+If you absolutely must use special characters (diacritics, mathematical
+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 .
+The same goes for function prototypes.
+.Em \&Do not
+use
+.Sq \&Xo/Xc .
+Find another way to structure your line.
+.\" SUBSECTION
+.Ss References
+Other components may be referenced with the
+.Sq \&Xr
+and
+.Sq \&Sx
+macros. Make sure that these exist. If you intend to distribute your
+manual, make sure
+.Sq \&Xr
+references are valid across systems (within reason). If you cross-link with
+.Sq \&Sx ,
+make sure that the section reference exists.
+.\" SUBSECTION
+.Ss Citations
+Cite your work. If your system references standards documents or other
+publications, please use the
+.Sq \&Rs/Re
+block macros.
+.\" SUBSECTION
+.Ss Formatting
+.Em Don't style your manual .
+Give it meaningful content. The front-end will worry about formatting
+and style.
+.\" SECTION
+.Sh MAINTENANCE
+As your component changes and bugs are fixed, your manual may become out
+of date. You may be tempted to use tools like Doxygen to automate the
+development of your manuals. Don't.
+.Pp
+.Em Manuals are part of a system component :
+if you modify your code or specifications, modify the documentation.
git.ckatri.com / mandoc.git / blobdiff