Annotation of src/usr.bin/mandoc/manuals.7, Revision 1.2
1.2 ! schwarze 1: .\" $Id: manuals.7,v 1.14 2009/06/10 20:18:43 kristaps Exp $
1.1 kristaps 2: .\"
1.2 ! schwarze 3: .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
1.1 kristaps 4: .\"
5: .\" Permission to use, copy, modify, and distribute this software for any
1.2 ! schwarze 6: .\" purpose with or without fee is hereby granted, provided that the above
! 7: .\" copyright notice and this permission notice appear in all copies.
1.1 kristaps 8: .\"
1.2 ! schwarze 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.
1.1 kristaps 16: .\"
17: .Dd $Mdocdate$
1.2 ! schwarze 18: .Dt MANUALS 7
1.1 kristaps 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$
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.