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
  32 .Dq manual section ,
  33 which categorises the component's function.  The section of a manual is
  34 usually listed in parenthesis next to the component name, such as
  35 .Xr ps 1 ,
  36 section 1.  You can query a manual explicitly by its section:
  37 .Pp
  38 .Dl % man \-s 1 ps
  39 .Pp
  40 The following table lists broad classifications and the applicable
  41 manual sections:
  42 .Pp
  43 .\" LIST
  44 .Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact
  45 .It Em Category
  46 .Em Section(s)
  47 .It Device
  48 4
  49 .It Executable
  50 1, 6, 8
  51 .It Function
  52 2, 3, 9
  53 .It File-format
  54 5
  55 .It Other
  56 7
  57 .El
  58 .\" SUBSECTION
  59 .Ss Devices
  60 Consists of hardware (and pseudo-) device driver documentation.  Drivers
  61 are unilaterally classified in section 4.
  62 .Em Note :
  63 these manuals are necessarily system- and architecture-specific.
  64 .Pp
  65 Example:
  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 .El
  74 .\" SUBSECTION
  75 .Ss Executables
  76 Executables consist of runnable binaries.  They're further classified by
  77 operator utility:
  78 .Pp
  79 .\" LIST
  80 .Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact
  81 .It Em Section
  82 .Em Description
  83 .It 1
  84 operator utilities
  85 .It 8
  86 administrator utilities
  87 .It 6
  88 games
  89 .El
  90 .Pp
  91 Examples:
  92 .Pp
  93 .\" LIST
  94 .Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact
  95 .It Em Manual
  96 .Em Description
  97 .It Xr usermod 8
  98 modify user login information
  99 .It Xr cc 1
 100 the C compiler
 101 .It Xr fortune 6
 102 print a random adage
 103 .El
 104 .\" SUBSECTION
 105 .Ss Functions
 106 Function documentation describes programme source code, whether in the
 107 form of libraries, modules or standalone sources.  They're further
 108 classified by context:
 109 .Pp
 110 .\" LIST
 111 .Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact
 112 .It Em Section
 113 .Em Description
 114 .It 2
 115 system calls
 116 .It 3, 3p, 3f
 117 programming libraries (C, Perl, Fortran)
 118 .It 9
 119 in-kernel routines
 120 .El
 121 .Pp
 122 .Em Note :
 123 section 2 and 9 manuals are necessarily system- and often
 124 architecture-specific.  Examples:
 125 .Pp
 126 .\" LIST
 127 .Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact
 128 .It Em Manual
 129 .Em Description
 130 .It Xr open 2
 131 open or create a file for reading or writing
 132 .It Xr isspace 3
 133 whitespace character test
 134 .It Xr Pod::Man 3p
 135 convert POD data to formatted roff
 136 .It Xr tsleep 9
 137 process context sleep
 138 .El
 139 .\" SUBSECTION
 140 .Ss File-formats
 141 A file format usually describes the format of on-disc binary or text
 142 data, although it can also be used to describe wire protocols (this is
 143 usually best left to RFC).  These manuals are unilaterally classified in
 144 section 5.
 145 .Pp
 146 Example:
 147 .Pp
 148 .\" LIST
 149 .Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact
 150 .It Em Manual
 151 .Em Description
 152 .It Xr passwd 5
 153 format of the password file
 154 .El
 155 .\" SUBSECTION
 156 .Ss Other
 157 Documents with no other classification are relegated to section 7.  This
 158 constitutes reference tutorials (such as this document) and other
 159 miscellaneous information.
 160 .Pp
 161 Examples:
 162 .Pp
 163 .\" LIST
 164 .Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact
 165 .It Em Manual
 166 .Em Description
 167 .It Xr ascii 7
 168 ASCII character sets
 169 .It Xr symlink 7
 170 symbolic link handling
 171 .El
 172 .\" SECTION
 173 .Sh COMPOSITION
 174 Prepare your composition environment.
 175 .\" SUBSECTION
 176 .Ss Naming
 177 Your component will need a name by which to query its contents via
 178 .Xr man 1 .
 179 Keep it simple.  You may want to look for other manuals by that same
 180 name before committing:
 181 .Pp
 182 .Dl % apropos myname
 183 .Pp
 184 Conventionally, manual files are named
 185 .Pa myname.section ,
 186 such as
 187 .Pa manuals.7
 188 for this document.
 189 .\" SUBSECTION
 190 .Ss Input Language
 191 Manuals should
 192 .Em always
 193 be written in the
 194 .Xr mdoc 7
 195 formatting language.
 196 .Pp
 197 There exist other documentation-specific languages, such as the
 198 historical
 199 .Xr me 7 ,
 200 .Xr ms 7
 201 and
 202 .Xr man 7
 203 packages of
 204 .Xr roff 7 ;
 205 newer languages such as DocBook, texinfo or schema-driven XML; or even
 206 ad-hoc conventions such as README files.
 207 .Em Stay away from these methods!
 208 Historical formats fail to capture a manual's semantic content, instead
 209 only modelling its style.  Newer methods requires special,
 210 system-specific tools and may change or become obsolete over the
 211 life-time of your component.
 212 .Pp
 213 There are two canonical references for writing mdoc manuals:
 214 .Pp
 215 .\" LIST
 216 .Bl -tag -width XXXXXXXXXXXXXXXX -offset indent -compact
 217 .It Xr mdoc 7
 218 formal language reference
 219 .It Xr mdoc.samples 7
 220 macro reference
 221 .El
 222 .Pp
 223 Don't merely copy existing manuals!  Most systems distribute an mdoc
 224 template to help you get started in
 225 .Pa /usr/share/misc/mdoc.template .
 226 .\" SUBSECTION
 227 .Ss Development Tools
 228 While writing, make sure that your manual is correctly structured:
 229 .Pp
 230 .Dl % mandoc \-Tlint \-Wall name.1
 231 .Pp
 232 You may spell-check your work as follows:
 233 .Pp
 234 .Dl % deroff name.1 | spell
 235 .Dl % ispell \-n name.1
 236 .Pp
 237 Use
 238 .Xr cvs 1
 239 or, if not available,
 240 .Xr rcs 1
 241 to version-control your work.  If you wish the last check-in to effect
 242 your document's date, use the following RCS tag for the date macro:
 243 .Pp
 244 .Dl \&.Dd $Mdocdate: March 22 2009 $
 245 .Pp
 246 .\" SUBSECTION
 247 .Ss Viewing
 248 mdoc documents may be paged to your terminal with traditional
 249 tools such as
 250 .Xr nroff 1 ,
 251 .Xr groff 1 ,
 252 or with newer, more powerful tools such as
 253 .Xr mandoc 1 :
 254 .\" DISPLAY
 255 .Bd -literal -offset indent
 256 % nroff \-mandoc name.1 | less
 257 % groff \-Tascii \-mandoc name.1 | less
 258 % mandoc name.1 | less
 259 .Ed
 260 .Pp
 261 Other output formats are also supported:
 262 .\" DISPLAY
 263 .Bd -literal -offset indent
 264 % groff \-Tps \-mandoc name.1 | less
 265 % mandoc \-Thtml name.1 | less
 266 .Ed
 267 .\" SUBSECTION
 268 .Ss Automation
 269 Consider adding your mdoc documents to
 270 .Xr make 1
 271 Makefiles in order to automatically check your input and generate
 272 output:
 273 .Bd -literal -offset indent
 274 \&.SUFFIXES: .html .txt .1 .in
 275
 276 \&.in.1:
 277         mandoc -Wall,error -Tlint $<
 278         cp -f $< $@
 279
 280 \&.1.html:
 281         mandoc -Thtml $< >$@
 282
 283 \&.1.txt:
 284         mandoc -Tascii $< | col -b >$@
 285 .Ed
 286 .\" SECTION
 287 .Sh BEST PRACTICES
 288 The
 289 .Xr mdoc 7
 290 and
 291 .Xr mdoc.samples 7
 292 files will be indispensable in guiding composition.  In this section, we
 293 introduce some
 294 .Ux
 295 manual best practices:
 296 .\" SUBSECTION
 297 .Ss Language
 298 .Bl -enum
 299 .It
 300 Use clear, concise language.  Favour simplicity.
 301 .It
 302 Write your manual in non-idiomatic English.  Don't worry about
 303 Commonwealth or American spellings \(em just correct ones.
 304 .It
 305 Spell-check your manual, keeping in mind short-letter terms (
 306 .Xr iwi 4
 307 vs.
 308 .Xr iwn 4 ) .
 309 .It
 310 If you absolutely must use special characters (diacritics, mathematical
 311 symbols and so on), use the escapes dictated in
 312 .Xr mdoc 7 .
 313 .El
 314 .\" SUBSECTION
 315 .Ss References
 316 Other components may be referenced with the
 317 .Sq \&Xr ,
 318 and
 319 .Sq \&Sx
 320 macros.  Make sure that these exist.  If you intend to distribute your
 321 manual, make sure
 322 .Sq \&Xr
 323 references are valid across systems (within reason).  If you cross-link with
 324 .Sq \&Sx ,
 325 make sure that the section reference exists.
 326 .\" SUBSECTION
 327 .Ss Citations
 328 Cite your work.  If your system references standards documents or other
 329 publications, please use the
 330 .Sq \&Rs/Re
 331 block macros.
 332 .\" SUBSECTION
 333 .Ss Types and Prototypes
 334 If writing section 3 manuals, make sure that you correctly annotate your
 335 variables and functions.  This guarantees that cross-referncing between
 336 function names and their prototypes works properly.