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