| 1 | .\" $Id: manuals.7,v 1.19 2009/07/27 19:43:02 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 November 11, 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 ENVIRONMENT |
| 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 Development Tools |
| 107 | While writing, make sure that your manual is correctly structured: |
| 108 | .Pp |
| 109 | .Dl % mandoc \-Tlint \-Wall \-fstrict name.1 |
| 110 | .Pp |
| 111 | The quick-fix feature of |
| 112 | .Xr vim 1 |
| 113 | is useful for checking over many manuals: |
| 114 | .Bd -literal -offset indent |
| 115 | % mandoc \-Wall \-fstrict \-Tlint \-fign-errors \e |
| 116 | ./path/to/manuals/* 2>&1 > /tmp/mandoc.errs |
| 117 | % vim -q /tmp/mandoc.errs |
| 118 | .Ed |
| 119 | .Pp |
| 120 | You may spell-check your work as follows: |
| 121 | .Pp |
| 122 | .Dl % deroff name.1 | spell |
| 123 | .Pp |
| 124 | If |
| 125 | .Xr ispell 1 |
| 126 | is installed, it has a special mode for manuals: |
| 127 | .Pp |
| 128 | .Dl % ispell \-n name.1 |
| 129 | .Pp |
| 130 | Use |
| 131 | .Xr cvs 1 |
| 132 | or |
| 133 | .Xr rcs 1 |
| 134 | to version-control your work. If you wish the last check-in to effect |
| 135 | your document's date, use the following RCS tag for the date macro: |
| 136 | .Pp |
| 137 | .Dl \&.Dd $Mdocdate$ |
| 138 | .\" SUBSECTION |
| 139 | .Ss Viewing |
| 140 | mdoc documents may be paged to your terminal with |
| 141 | .Xr mandoc 1 . |
| 142 | If you plan on distributing your work to systems without this tool, |
| 143 | check it against |
| 144 | .Xr groff 1 : |
| 145 | .Bd -literal -offset indent |
| 146 | % mandoc \-Wall name.1 2>&1 | less |
| 147 | % groff -mandoc name.1 2>&1 | less |
| 148 | .Ed |
| 149 | .\" SUBSECTION |
| 150 | .Ss Automation |
| 151 | Consider adding your mdoc documents to |
| 152 | .Xr make 1 |
| 153 | Makefiles in order to automatically check your input: |
| 154 | .Bd -literal -offset indent |
| 155 | \&.SUFFIXES: .1 .in |
| 156 | |
| 157 | \&.in.1: |
| 158 | mandoc -Wall,error -Tlint $< |
| 159 | cp -f $< $@ |
| 160 | .Ed |
| 161 | .\" SUBSECTION |
| 162 | .Ss Licensing |
| 163 | Your manual must have a license. It should be listed at the start of |
| 164 | your document, just as in source code. |
| 165 | .\" SECTION |
| 166 | .Sh COMPOSITION |
| 167 | Manuals should |
| 168 | .Em always |
| 169 | be written in the |
| 170 | .Xr mdoc 7 |
| 171 | formatting language. |
| 172 | .\" PARAGRAPH |
| 173 | .Pp |
| 174 | Open the template you've copied into |
| 175 | .Pa myname.mysection |
| 176 | and begin editing. |
| 177 | .\" SUBSECTION |
| 178 | .Ss Language |
| 179 | .Bl -enum |
| 180 | .It |
| 181 | Use clear, concise language. Favour simplicity. |
| 182 | .It |
| 183 | Write your manual in non-idiomatic English. Don't worry about |
| 184 | Commonwealth or American spellings \(em just correct ones. |
| 185 | .It |
| 186 | Spell-check your manual, keeping in mind short-letter terms ( |
| 187 | .Xr iwi 4 |
| 188 | vs. |
| 189 | .Xr iwn 4 ) . |
| 190 | .It |
| 191 | If you absolutely must use special characters (diacritics, mathematical |
| 192 | symbols and so on), use the escapes dictated in |
| 193 | .Xr mdoc 7 . |
| 194 | .El |
| 195 | .\" SUBSECTION |
| 196 | .Ss Style |
| 197 | The structure of the mdoc language makes it very hard to have any |
| 198 | particular format style. Keep your lines under 72 characters in length. |
| 199 | If you must have long option lines, use |
| 200 | .Sq \&Oo/Oc . |
| 201 | The same goes for function prototypes. |
| 202 | .Em \&Do not |
| 203 | use |
| 204 | .Sq \&Xo/Xc . |
| 205 | Find another way to structure your line. |
| 206 | .\" SUBSECTION |
| 207 | .Ss References |
| 208 | Other components may be referenced with the |
| 209 | .Sq \&Xr |
| 210 | and |
| 211 | .Sq \&Sx |
| 212 | macros. Make sure that these exist. If you intend to distribute your |
| 213 | manual, make sure |
| 214 | .Sq \&Xr |
| 215 | references are valid across systems (within reason). If you cross-link with |
| 216 | .Sq \&Sx , |
| 217 | make sure that the section reference exists. |
| 218 | .\" SUBSECTION |
| 219 | .Ss Citations |
| 220 | Cite your work. If your system references standards documents or other |
| 221 | publications, please use the |
| 222 | .Sq \&Rs/Re |
| 223 | block macros. |
| 224 | .\" SUBSECTION |
| 225 | .Ss Formatting |
| 226 | .Em Don't style your manual . |
| 227 | Give it meaningful content. The front-end will worry about formatting |
| 228 | and style. |
| 229 | .\" SECTION |
| 230 | .Sh MAINTENANCE |
| 231 | As your component changes and bugs are fixed, your manual may become out |
| 232 | of date. You may be tempted to use tools like Doxygen to automate the |
| 233 | development of your manuals. Don't. |
| 234 | .Pp |
| 235 | .Em Manuals are part of a system component : |
| 236 | if you modify your code or specifications, modify the documentation. |