manuals.7

   1 .\"     $Id: manuals.7,v 1.14 2009/06/10 20:18:43 kristaps Exp $
   2 .\"
   3 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
   4 .\"
   5 .\" Permission to use, copy, modify, and distribute this software for any
   6 .\" purpose with or without fee is hereby granted, provided that the above
   7 .\" copyright notice and this permission notice appear in all copies.
   8 .\"
   9 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  10 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  11 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  12 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  13 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  14 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  15 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  16 .\"
  17 .Dd $Mdocdate: June 10 2009 $
  18 .Dt MANUALS 7
  19 .Os
  20 .\" SECTION
  21 .Sh NAME
  22 .Nm Writing UNIX Documentation
  23 .Nd a guide to writing UNIX manuals
  24 .\" SECTION
  25 .Sh DESCRIPTION
  26 .Em A utility without good documentation is of no utility at all .
  27 .\" PARAGRAPH
  28 .Pp
  29 A system component's documentation describes the utility of that
  30 component, whether it's a device driver, an executable or, most
  31 importantly, a game.
  32 .Pp
  33 This document serves as a tutorial to writing
  34 .Ux
  35 documentation
  36 .Pq Dq manuals .
  37 .\" SECTION
  38 .Sh COMPOSITION
  39 First, copy over the manual template from
  40 .Pa /usr/share/misc/mdoc.template
  41 into your source directory.
  42 .Pp
  43 .Dl % cp /usr/share/misc/mdoc.template \.
  44 .Pp
  45 .Em \&Do not
  46 start afresh or by copying another manual unless you know exactly what
  47 you're doing!  If the template doesn't exist, bug your administrator.
  48 .\" SUBSECTION
  49 .Ss Section Numbering
  50 Find an appropriate section for your manual.  There may exist multiple
  51 manual names per section, so be specific:
  52 .Pp
  53 .\" LIST
  54 .Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact
  55 .It Em Section
  56 .Em Description
  57 .It 1
  58 operator utilities
  59 .It 2
  60 system calls
  61 .It 3, 3p, 3f
  62 programming libraries (C, Perl, Fortran)
  63 .It 5
  64 file and wire protocol formats
  65 .It 6
  66 games
  67 .It 7
  68 tutorials, documents and papers
  69 .It 8
  70 administrator utilities
  71 .It 9
  72 in-kernel routines
  73 .El
  74 .Pp
  75 If your manual falls into multiple categories, choose the most
  76 widely-used or, better, re-consider the topic of your manual to be more
  77 specific.  You can list all manuals per section by invoking
  78 .Xr apropos 1 ,
  79 then provide the
  80 .Fl s
  81 flag to
  82 .Xr man 1
  83 to see the specific section manual (section 1, in this example):
  84 .\" DISPLAY
  85 .Bd -literal -offset indent
  86 % apropos myname
  87 myname (1) - utility description
  88 myname (3) - library description
  89 % man \-s 1 myname
  90 .Ed
  91 .\" SUBSECTION
  92 .Ss Naming
  93 Name your component.  Be terse, erring on the side of clarity.  Look for
  94 other manuals by that same name before committing:
  95 .Pp
  96 .Dl % apropos myname
  97 .Pp
  98 Manual files are named
  99 .Pa myname.mysection ,
 100 such as
 101 .Pa manuals.7
 102 for this document.  Rename the template file:
 103 .Pp
 104 .Dl % mv mdoc.template myname.mysection
 105 .\" SUBSECTION
 106 .Ss Input Language
 107 Manuals should
 108 .Em always
 109 be written in the
 110 .Xr mdoc 7
 111 formatting language.
 112 .Pp
 113 There exist other documentation-specific languages, such as the
 114 historical
 115 .Xr man 7
 116 package of
 117 .Xr roff 7 ;
 118 newer languages such as DocBook or texinfo; or even ad-hoc conventions
 119 such as README files.
 120 .Em Avoid these formats .
 121 .Pp
 122 There are two canonical references for writing mdoc.  Read them.
 123 .Pp
 124 .\" LIST
 125 .Bl -tag -width XXXXXXXXXXXXXXXX -offset indent -compact
 126 .It Xr mdoc 7
 127 formal language reference
 128 .It Xr mdoc.samples 7
 129 macro reference
 130 .El
 131 .Pp
 132 Open the template you've copied into
 133 .Pa myname.mysection
 134 and begin editing.
 135 .\" SUBSECTION
 136 .Ss Development Tools
 137 While writing, make sure that your manual is correctly structured:
 138 .Pp
 139 .Dl % mandoc \-Tlint \-Wall name.1
 140 .Pp
 141 You may spell-check your work as follows:
 142 .Pp
 143 .Dl % deroff name.1 | spell
 144 .Pp
 145 If
 146 .Xr ispell 1
 147 is installed, it has a special mode for manuals:
 148 .Pp
 149 .Dl % ispell \-n name.1
 150 .Pp
 151 Use
 152 .Xr cvs 1
 153 or
 154 .Xr rcs 1
 155 to version-control your work.  If you wish the last check-in to effect
 156 your document's date, use the following RCS tag for the date macro:
 157 .Pp
 158 .Dl \&.Dd $Mdocdate: June 10 2009 $
 159 .\" SUBSECTION
 160 .Ss Viewing
 161 mdoc documents may be paged to your terminal with
 162 .Xr mandoc 1 .
 163 If you plan on distributing your work to systems without this tool,
 164 check it against
 165 .Xr groff 1 :
 166 .Bd -literal -offset indent
 167 % mandoc \-Wall name.1 2>&1 | less
 168 % groff -mandoc name.1 2>&1 | less
 169 .Ed
 170 .\" SUBSECTION
 171 .Ss Automation
 172 Consider adding your mdoc documents to
 173 .Xr make 1
 174 Makefiles in order to automatically check your input:
 175 .Bd -literal -offset indent
 176 \&.SUFFIXES: .1 .in
 177
 178 \&.in.1:
 179         mandoc -Wall,error -Tlint $<
 180         cp -f $< $@
 181 .Ed
 182 .\" SUBSECTION
 183 .Ss Licensing
 184 Your manual must have a license.  It should be listed at the start of
 185 your document, just as in source code.
 186 .\" SECTION
 187 .Sh BEST PRACTICES
 188 The
 189 .Xr mdoc 7
 190 and
 191 .Xr mdoc.samples 7
 192 files are indispensable in guiding composition.  In this section, we
 193 introduce some
 194 .Ux
 195 manual best practices:
 196 .\" SUBSECTION
 197 .Ss Language
 198 .Bl -enum
 199 .It
 200 Use clear, concise language.  Favour simplicity.
 201 .It
 202 Write your manual in non-idiomatic English.  Don't worry about
 203 Commonwealth or American spellings \(em just correct ones.
 204 .It
 205 Spell-check your manual, keeping in mind short-letter terms (
 206 .Xr iwi 4
 207 vs.
 208 .Xr iwn 4 ) .
 209 .It
 210 If you absolutely must use special characters (diacritics, mathematical
 211 symbols and so on), use the escapes dictated in
 212 .Xr mdoc 7 .
 213 .El
 214 .\" SUBSECTION
 215 .Ss Style
 216 The structure of the mdoc language makes it very hard to have any
 217 particular format style.  Keep your lines under 72 characters in length.
 218 If you must have long option lines, use
 219 .Sq \&Oo/Oc .
 220 The same goes for function prototypes.
 221 .Em \&Do not
 222 use
 223 .Sq \&Xo/Xc .
 224 Find another way to structure your line.
 225 .\" SUBSECTION
 226 .Ss References
 227 Other components may be referenced with the
 228 .Sq \&Xr
 229 and
 230 .Sq \&Sx
 231 macros.  Make sure that these exist.  If you intend to distribute your
 232 manual, make sure
 233 .Sq \&Xr
 234 references are valid across systems (within reason).  If you cross-link with
 235 .Sq \&Sx ,
 236 make sure that the section reference exists.
 237 .\" SUBSECTION
 238 .Ss Citations
 239 Cite your work.  If your system references standards documents or other
 240 publications, please use the
 241 .Sq \&Rs/Re
 242 block macros.
 243 .\" SUBSECTION
 244 .Ss Formatting
 245 .Em Don't style your manual .
 246 Give it meaningful content.  The front-end will worry about formatting
 247 and style.
 248 .\" SECTION
 249 .Sh MAINTENANCE
 250 As your component changes and bugs are fixed, your manual may become out
 251 of date.  You may be tempted to use tools like Doxygen to automate the
 252 development of your manuals.  Don't.
 253 .Pp
 254 .Em Manuals are part of a system component :
 255 if you modify your code or specifications, modify the documentation.