b3f565bde2a7772aa55b91d45e10248ea8121e6e
[dragonfly.git] / usr.bin / mandoc / manuals.7
1 .\"     $Id: manuals.7,v 1.5 2009/08/22 16:32:22 schwarze 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: July 26 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: July 26 2009 $
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.