manuals.7

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