.Dd $Mdocdate: March 22 2009 $ .Dt manuals 7 .Os .\" SECTION .Sh NAME .Nm Writing UNIX Documentation .Nd a guide to writing UNIX manuals .\" SECTION .Sh DESCRIPTION .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. Although there are plenty of documents available on how to read .Ux documents, or where to find them, few focus on composition. .\" PARAGRAPH .Pp This document serves as a tutorial to writing .Ux documentation .Pq Dq manuals . 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 Classify your system component. In .Ux , each component has a .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 .Pp The following table lists broad classifications and the applicable manual sections: .Pp .\" LIST .Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact .It Em Category .Em Section(s) .It Device 4 .It Executable 1, 6, 8 .It Function 2, 3, 9 .It File-format 5 .It Other 7 .El .\" SUBSECTION .Ss Devices Consists of hardware (and pseudo-) device driver documentation. Drivers are unilaterally classified in section 4. .Em Note : these manuals are necessarily system- and architecture-specific. .Pp Example: .Pp .\" LIST .Bl -tag -width "File-formatX" -offset indent -compact .It Em Manual .Em Description .It Xr dc 4 DEC/Intel 10/100 Ethernet device .El .\" SUBSECTION .Ss Executables Executables consist of runnable binaries. They're further classified by operator utility: .Pp .\" LIST .Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact .It Em Section .Em Description .It 1 operator utilities .It 8 administrator utilities .It 6 games .El .Pp Examples: .Pp .\" LIST .Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact .It Em Manual .Em Description .It Xr usermod 8 modify user login information .It Xr cc 1 the C compiler .It Xr fortune 6 print a random adage .El .\" SUBSECTION .Ss Functions Function documentation describes programme source code, whether in the form of libraries, modules or standalone sources. They're further classified by context: .Pp .\" LIST .Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact .It Em Section .Em Description .It 2 system calls .It 3, 3p, 3f programming libraries (C, Perl, Fortran) .It 9 in-kernel routines .El .Pp .Em Note : section 2 and 9 manuals are necessarily system- and often architecture-specific. Examples: .Pp .\" LIST .Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact .It Em Manual .Em Description .It Xr open 2 open or create a file for reading or writing .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 .El .\" SUBSECTION .Ss File-formats A file format usually describes the format of on-disc binary or text data, although it can also be used to describe wire protocols (this is usually best left to RFC). These manuals are unilaterally classified in section 5. .Pp Example: .Pp .\" LIST .Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact .It Em Manual .Em Description .It Xr passwd 5 format of the password file .El .\" SUBSECTION .Ss Other Documents with no other classification are relegated to section 7. This constitutes reference tutorials (such as this document) and other miscellaneous information. .Pp Examples: .Pp .\" LIST .Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact .It Em Manual .Em Description .It Xr ascii 7 ASCII character sets .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 .Xr man 1 . 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 .Pa myname.section , such as .Pa manuals.7 for this document. .\" 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 me 7 , .Xr ms 7 and .Xr man 7 packages 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! 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: .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 Don't merely copy existing manuals! Most systems distribute an mdoc template to help you get started in .Pa /usr/share/misc/mdoc.template . .\" 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 .Dl % ispell \-n name.1 .Pp Use .Xr cvs 1 or, if not available, .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: March 22 2009 $ .Pp .\" SUBSECTION .Ss Viewing mdoc documents may be paged to your terminal with traditional tools such as .Xr nroff 1 , .Xr groff 1 , or with newer, more powerful tools such as .Xr mandoc 1 : .\" DISPLAY .Bd -literal -offset indent % nroff \-mandoc name.1 | less % groff \-Tascii \-mandoc name.1 | less % mandoc name.1 | less .Ed .Pp Other output formats are also supported: .\" DISPLAY .Bd -literal -offset indent % groff \-Tps \-mandoc name.1 | less % mandoc \-Thtml name.1 | less .Ed .\" SUBSECTION .Ss Automation Consider adding your mdoc documents to .Xr make 1 Makefiles in order to automatically check your input and generate output: .Bd -literal -offset indent \&.SUFFIXES: .html .txt .1 .in \&.in.1: mandoc -Wall,error -Tlint $< cp -f $< $@ \&.1.html: mandoc -Thtml $< >$@ \&.1.txt: mandoc -Tascii $< | col -b >$@ .Ed .\" SECTION .Sh BEST PRACTICES The .Xr mdoc 7 and .Xr mdoc.samples 7 files will be 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 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 Types and Prototypes If writing section 3 manuals, make sure that you correctly annotate your variables and functions. This guarantees that cross-referncing between function names and their prototypes works properly.