=================================================================== RCS file: /cvs/mandoc/Attic/manuals.7,v retrieving revision 1.1 retrieving revision 1.13 diff -u -p -r1.1 -r1.13 --- mandoc/Attic/manuals.7 2009/03/22 08:52:27 1.1 +++ mandoc/Attic/manuals.7 2009/04/12 19:45:26 1.13 @@ -1,39 +1,255 @@ -.Dd $Mdocdate: March 22 2009 $ -.Dt "Writing Unix Documentation" paper +.\" $Id: manuals.7,v 1.13 2009/04/12 19:45:26 kristaps Exp $ +.\" +.\" Copyright (c) 2009 Kristaps Dzonsons +.\" +.\" 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: April 12 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 -

- Writing Unix Documentation -

+.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 COMPOSITION +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 Input Language +Manuals should +.Em always +be written in the +.Xr mdoc 7 +formatting language. +.Pp +There exist other documentation-specific languages, such as the +historical +.Xr man 7 +package of +.Xr roff 7 ; +newer languages such as DocBook or texinfo; or even ad-hoc conventions +such as README files. +.Em Avoid these formats . +.Pp +There are two canonical references for writing mdoc. Read them. +.Pp +.\" LIST +.Bl -tag -width XXXXXXXXXXXXXXXX -offset indent -compact +.It Xr mdoc 7 +formal language reference +.It Xr mdoc.samples 7 +macro reference +.El +.Pp +Open the template you've copied into +.Pa myname.mysection +and begin editing. +.\" SUBSECTION +.Ss Development Tools +While writing, make sure that your manual is correctly structured: +.Pp +.Dl % mandoc \-Tlint \-Wall name.1 +.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: April 12 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 -

- A utility without documentation is of no utility at all. -

- -

- 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 read Unix documents, or where to find them, few focus on how to write them. -

- -

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

- - - - -
- Copyright © 2009 Kristaps Džonsons, $Date: 2009/03/22 08:52:27 $ -
- - - - - - +\&.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 BEST PRACTICES +The +.Xr mdoc 7 +and +.Xr mdoc.samples 7 +files are indispensable in guiding composition. In this section, we +introduce some +.Ux +manual best practices: +.\" 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.