manuals.7

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