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