manuals.7

   1 .Dd $Mdocdate: March 22 2009 $
   2 .Dt manuals 7
   3 .Os
   4 .\" SECTION
   5 .Sh NAME
   6 .Nm Writing UNIX Documentation
   7 .Nd a guide to writing UNIX manuals
   8 .\" SECTION
   9 .Sh DESCRIPTION
  10 .Em A utility without good documentation is of no utility at all .
  11 .\" PARAGRAPH
  12 .Pp
  13 A system component's documentation describes the utility of that
  14 component, whether it's a device driver, an executable or, most
  15 importantly, a game.  Although there are plenty of documents available
  16 on how to read
  17 .Ux
  18 documents, or where to find them, few focus on composition.
  19 .\" PARAGRAPH
  20 .Pp
  21 This document serves as a tutorial to writing
  22 .Ux
  23 documentation
  24 .Pq Dq manuals .
  25 If you add something to your operating system, whether it's a new file
  26 format or directory structure or device driver, it needs documentation.
  27 .\" SECTION
  28 .Sh CLASSIFICATION
  29 Classify your system component.  In
  30 .Ux ,
  31 each component has a manual section , which categorises the component's
  32 function.  The section of a manual is usually listed in parenthesis next
  33 to the component name, such as
  34 .Xr ps 1 ,
  35 section 1.  You can query a manual explicitly by its section:
  36 .Bd -literal -offset XXXX
  37 % man \-s 1 ps
  38 % apropos ps
  39 .Ed
  40 .Pp
  41 The following table lists classifications and the applicable manual
  42 sections:
  43 .Pp
  44 .Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact
  45 .It Em Section
  46 .Em Description
  47 .It 1
  48 operator utilities
  49 .It 2
  50 system calls
  51 .It 3, 3p, 3f
  52 programming libraries (C, Perl, Fortran)
  53 .It 5
  54 file and wire protocol formats
  55 .It 6
  56 games
  57 .It 7
  58 tutorials, documents and papers
  59 .It 8
  60 administrator utilities
  61 .It 9
  62 in-kernel routines
  63 .El
  64 .Pp
  65 Some examples in regular name/section form:
  66 .Pp
  67 .\" LIST
  68 .Bl -tag -width "File-formatX" -offset indent -compact
  69 .It Em Manual
  70 .Em Description
  71 .It Xr dc 4
  72 DEC/Intel 10/100 Ethernet device
  73 .It Xr usermod 8
  74 modify user login information
  75 .It Xr cc 1
  76 the C compiler
  77 .It Xr fortune 6
  78 print a random adage
  79 .It Xr open 2
  80 open or create a file for reading or writing
  81 .It Xr isspace 3
  82 whitespace character test
  83 .It Xr Pod::Man 3p
  84 convert POD data to formatted roff
  85 .It Xr tsleep 9
  86 process context sleep
  87 .It Xr passwd 5
  88 format of the password file
  89 .It Xr symlink 7
  90 symbolic link handling
  91 .El
  92 .\" SECTION
  93 .Sh COMPOSITION
  94 Prepare your composition environment by copying over the manual template
  95 from
  96 .Pa /usr/share/misc/mdoc.template .
  97 .Em \&Do not
  98 start afresh or by copying another manual unless you know exactly what
  99 you're doing!
 100 .\" SUBSECTION
 101 .Ss Naming
 102 Your component will need a name by which to query its contents via
 103 .Xr man 1 .
 104 Keep it simple.  You may want to look for other manuals by that same
 105 name before committing:
 106 .Pp
 107 .Dl % apropos myname
 108 .Pp
 109 Conventionally, manual files are named
 110 .Pa myname.section ,
 111 such as
 112 .Pa manuals.7
 113 for this document.
 114 .\" SUBSECTION
 115 .Ss Input Language
 116 Manuals should
 117 .Em always
 118 be written in the
 119 .Xr mdoc 7
 120 formatting language.
 121 .Pp
 122 There exist other documentation-specific languages, such as the
 123 historical
 124 .Xr me 7 ,
 125 .Xr ms 7
 126 and
 127 .Xr man 7
 128 packages of
 129 .Xr roff 7 ;
 130 newer languages such as DocBook, texinfo or schema-driven XML; or even
 131 ad-hoc conventions such as README files.
 132 .Em Stay away from these methods!
 133 Historical formats fail to capture a manual's semantic content, instead
 134 only modelling its style.  Newer methods requires special,
 135 system-specific tools and may change or become obsolete over the
 136 life-time of your component.
 137 .Pp
 138 There are two canonical references for writing mdoc manuals:
 139 .Pp
 140 .\" LIST
 141 .Bl -tag -width XXXXXXXXXXXXXXXX -offset indent -compact
 142 .It Xr mdoc 7
 143 formal language reference
 144 .It Xr mdoc.samples 7
 145 macro reference
 146 .El
 147 .Pp
 148 Open the template you've copied into
 149 .Pa name.section
 150 and begin editing.
 151 .\" SUBSECTION
 152 .Ss Development Tools
 153 While writing, make sure that your manual is correctly structured:
 154 .Pp
 155 .Dl % mandoc \-Tlint \-Wall name.1
 156 .Pp
 157 You may spell-check your work as follows:
 158 .Pp
 159 .Dl % deroff name.1 | spell
 160 .Dl % ispell \-n name.1
 161 .Pp
 162 Use
 163 .Xr cvs 1
 164 or, if not available,
 165 .Xr rcs 1
 166 to version-control your work.  If you wish the last check-in to effect
 167 your document's date, use the following RCS tag for the date macro:
 168 .Pp
 169 .Dl \&.Dd $Mdocdate: March 22 2009 $
 170 .\" SUBSECTION
 171 .Ss Viewing
 172 mdoc documents may be paged to your terminal with traditional
 173 tools such as
 174 .Xr nroff 1 ,
 175 .Xr groff 1 ,
 176 or with newer, more powerful tools such as
 177 .Xr mandoc 1 :
 178 .\" DISPLAY
 179 .Bd -literal -offset indent
 180 % nroff \-mandoc name.1 | less
 181 % groff \-Tascii \-mandoc name.1 | less
 182 % mandoc name.1 | less
 183 .Ed
 184 .Pp
 185 Other output formats are also supported:
 186 .\" DISPLAY
 187 .Bd -literal -offset indent
 188 % groff \-Tps \-mandoc name.1 | less
 189 % mandoc \-Thtml name.1 | less
 190 .Ed
 191 .\" SUBSECTION
 192 .Ss Automation
 193 Consider adding your mdoc documents to
 194 .Xr make 1
 195 Makefiles in order to automatically check your input and generate
 196 output:
 197 .Bd -literal -offset indent
 198 \&.SUFFIXES: .html .txt .1 .in
 199
 200 \&.in.1:
 201         mandoc -Wall,error -Tlint $<
 202         cp -f $< $@
 203
 204 \&.1.html:
 205         mandoc -Thtml $< >$@
 206
 207 \&.1.txt:
 208         mandoc -Tascii $< | col -b >$@
 209 .Ed
 210 .\" SECTION
 211 .Sh BEST PRACTICES
 212 The
 213 .Xr mdoc 7
 214 and
 215 .Xr mdoc.samples 7
 216 files are indispensable in guiding composition.  In this section, we
 217 introduce some
 218 .Ux
 219 manual best practices:
 220 .\" SUBSECTION
 221 .Ss Language
 222 .Bl -enum
 223 .It
 224 Use clear, concise language.  Favour simplicity.
 225 .It
 226 Write your manual in non-idiomatic English.  Don't worry about
 227 Commonwealth or American spellings \(em just correct ones.
 228 .It
 229 Spell-check your manual, keeping in mind short-letter terms (
 230 .Xr iwi 4
 231 vs.
 232 .Xr iwn 4 ) .
 233 .It
 234 If you absolutely must use special characters (diacritics, mathematical
 235 symbols and so on), use the escapes dictated in
 236 .Xr mdoc 7 .
 237 .El
 238 .\" SUBSECTION
 239 .Ss References
 240 Other components may be referenced with the
 241 .Sq \&Xr ,
 242 and
 243 .Sq \&Sx
 244 macros.  Make sure that these exist.  If you intend to distribute your
 245 manual, make sure
 246 .Sq \&Xr
 247 references are valid across systems (within reason).  If you cross-link with
 248 .Sq \&Sx ,
 249 make sure that the section reference exists.
 250 .\" SUBSECTION
 251 .Ss Citations
 252 Cite your work.  If your system references standards documents or other
 253 publications, please use the
 254 .Sq \&Rs/Re
 255 block macros.
 256 .\" SUBSECTION
 257 .Ss Formatting
 258 Let the front-ends worry about formatting for you, but if you must think
 259 about formatting (at times necessary, especially for tagged and columnar
 260 lists), assume that your output device is a fixed-width terminal window:
 261 .Bd -literal -offset indent
 262 \&.Bl \-tag \-width "-o outfile"
 263 \&.It \&Fl \&Ar outfile
 264 .Ed
 265 .Pp
 266 You may assume that the width calculated by the string literal
 267 .Qq Fl o Ar outfile
 268 will be covered by the \-width argument.