Annotation of mandoc/manuals.7, Revision 1.9
1.9 ! kristaps 1: .\" $Id: manuals.7,v 1.8 2009/03/23 09:42:43 kristaps Exp $
1.8 kristaps 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: .\"
1.1 kristaps 19: .Dd $Mdocdate$
1.2 kristaps 20: .Dt manuals 7
1.1 kristaps 21: .Os
1.2 kristaps 22: .\" SECTION
1.1 kristaps 23: .Sh NAME
1.2 kristaps 24: .Nm Writing UNIX Documentation
25: .Nd a guide to writing UNIX manuals
26: .\" SECTION
1.1 kristaps 27: .Sh DESCRIPTION
1.2 kristaps 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
1.5 kristaps 46: .Sh COMPOSITION
47: Prepare your composition environment by copying over the manual template
48: from
49: .Pa /usr/share/misc/mdoc.template .
1.8 kristaps 50: .Pp
51: If this file doesn't exist, bug your administrator.
1.5 kristaps 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:
1.2 kristaps 60: .Pp
1.5 kristaps 61: .\" LIST
1.2 kristaps 62: .Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact
63: .It Em Section
64: .Em Description
65: .It 1
66: operator utilities
1.3 kristaps 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
1.2 kristaps 77: .It 8
78: administrator utilities
1.3 kristaps 79: .It 9
80: in-kernel routines
1.2 kristaps 81: .El
82: .Pp
1.5 kristaps 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
1.7 kristaps 95: myname (1) - utility description
96: myname (3) - library description
1.5 kristaps 97: % man \-s 1 myname
98: .Ed
1.2 kristaps 99: .\" SUBSECTION
100: .Ss Naming
1.5 kristaps 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:
1.2 kristaps 103: .Pp
104: .Dl % apropos myname
105: .Pp
1.5 kristaps 106: Manual files are named
107: .Pa myname.mysection ,
1.2 kristaps 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 man 7
1.9 ! kristaps 122: package of
1.2 kristaps 123: .Xr roff 7 ;
124: newer languages such as DocBook, texinfo or schema-driven XML; or even
125: ad-hoc conventions such as README files.
1.5 kristaps 126: .Em Avoid these formats .
1.2 kristaps 127: Historical formats fail to capture a manual's semantic content, instead
128: only modelling its style. Newer methods requires special,
129: system-specific tools and may change or become obsolete over the
130: life-time of your component.
131: .Pp
1.5 kristaps 132: There are two canonical references for writing mdoc. Read them.
1.2 kristaps 133: .Pp
134: .\" LIST
135: .Bl -tag -width XXXXXXXXXXXXXXXX -offset indent -compact
136: .It Xr mdoc 7
137: formal language reference
138: .It Xr mdoc.samples 7
139: macro reference
140: .El
141: .Pp
1.4 kristaps 142: Open the template you've copied into
143: .Pa name.section
144: and begin editing.
1.2 kristaps 145: .\" SUBSECTION
146: .Ss Development Tools
147: While writing, make sure that your manual is correctly structured:
148: .Pp
149: .Dl % mandoc \-Tlint \-Wall name.1
150: .Pp
151: You may spell-check your work as follows:
152: .Pp
153: .Dl % deroff name.1 | spell
154: .Dl % ispell \-n name.1
155: .Pp
156: Use
157: .Xr cvs 1
158: or, if not available,
159: .Xr rcs 1
160: to version-control your work. If you wish the last check-in to effect
161: your document's date, use the following RCS tag for the date macro:
162: .Pp
163: .Dl \&.Dd $Mdocdate$
1.8 kristaps 164: .Pp
165: If using version control, the first line in your manual should be a
166: comment with the
1.9 ! kristaps 167: .Li $Id: manuals.7,v 1.8 2009/03/23 09:42:43 kristaps Exp $
1.8 kristaps 168: rcs tag.
1.2 kristaps 169: .\" SUBSECTION
170: .Ss Viewing
171: mdoc documents may be paged to your terminal with traditional
172: tools such as
173: .Xr nroff 1 ,
174: .Xr groff 1 ,
175: or with newer, more powerful tools such as
176: .Xr mandoc 1 :
177: .\" DISPLAY
178: .Bd -literal -offset indent
179: % nroff \-mandoc name.1 | less
180: % groff \-Tascii \-mandoc name.1 | less
181: % mandoc name.1 | less
182: .Ed
183: .Pp
184: Other output formats are also supported:
185: .\" DISPLAY
186: .Bd -literal -offset indent
187: % groff \-Tps \-mandoc name.1 | less
188: % mandoc \-Thtml name.1 | less
189: .Ed
190: .\" SUBSECTION
191: .Ss Automation
192: Consider adding your mdoc documents to
193: .Xr make 1
194: Makefiles in order to automatically check your input and generate
195: output:
196: .Bd -literal -offset indent
197: \&.SUFFIXES: .html .txt .1 .in
1.1 kristaps 198:
1.2 kristaps 199: \&.in.1:
200: mandoc -Wall,error -Tlint $<
201: cp -f $< $@
202: \&.1.html:
203: mandoc -Thtml $< >$@
204: \&.1.txt:
205: mandoc -Tascii $< | col -b >$@
206: .Ed
1.8 kristaps 207: .\" SUBSECTION
208: .Ss Licensing
209: Your manual must have a license. It should be listed at the start of
210: your document, just as in source code.
1.2 kristaps 211: .\" SECTION
212: .Sh BEST PRACTICES
213: The
214: .Xr mdoc 7
215: and
216: .Xr mdoc.samples 7
1.4 kristaps 217: files are indispensable in guiding composition. In this section, we
1.2 kristaps 218: introduce some
219: .Ux
220: manual best practices:
221: .\" SUBSECTION
222: .Ss Language
223: .Bl -enum
224: .It
225: Use clear, concise language. Favour simplicity.
226: .It
227: Write your manual in non-idiomatic English. Don't worry about
228: Commonwealth or American spellings \(em just correct ones.
229: .It
230: Spell-check your manual, keeping in mind short-letter terms (
231: .Xr iwi 4
232: vs.
233: .Xr iwn 4 ) .
234: .It
235: If you absolutely must use special characters (diacritics, mathematical
236: symbols and so on), use the escapes dictated in
237: .Xr mdoc 7 .
238: .El
239: .\" SUBSECTION
1.8 kristaps 240: .Ss Style
241: The structure of the mdoc language makes it very hard to have any
242: particular format style. Keep your lines under 72 characters in length.
243: If you must have long option lines, use
244: .Sq \&Oo/Oc .
245: .Em \&Do not
246: use
247: .Sq \&Xo/Xc ;
248: instead, either fine another way to write long lines, or, at the
249: absolute worst, use CPP-style newline escapes.
250: .\" SUBSECTION
1.2 kristaps 251: .Ss References
252: Other components may be referenced with the
1.5 kristaps 253: .Sq \&Xr
1.2 kristaps 254: and
255: .Sq \&Sx
256: macros. Make sure that these exist. If you intend to distribute your
257: manual, make sure
258: .Sq \&Xr
259: references are valid across systems (within reason). If you cross-link with
260: .Sq \&Sx ,
261: make sure that the section reference exists.
262: .\" SUBSECTION
263: .Ss Citations
264: Cite your work. If your system references standards documents or other
265: publications, please use the
266: .Sq \&Rs/Re
267: block macros.
268: .\" SUBSECTION
1.3 kristaps 269: .Ss Formatting
1.7 kristaps 270: .Em Don't style your manual.
1.6 kristaps 271: Give it meaningful content. The front-end will worry about formatting
272: and style.
1.5 kristaps 273: .\" SECTION
274: .Sh MAINTENANCE
275: As your component changes and bugs are fixed, your manual may become out
276: of date. You may be tempted to use automation tools like Doxygen to
277: smooth the development of your manuals. Don't. Source documentation is
1.6 kristaps 278: different from a component manual.
CVSweb
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to manuals.7 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [cvsweb.bsd.lv] / mandoc