Annotation of mandoc/manuals.7, Revision 1.18
1.18 ! kristaps 1: .\" $Id: manuals.7,v 1.17 2009/07/20 13:45:11 kristaps Exp $
1.8 kristaps 2: .\"
1.14 kristaps 3: .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
1.8 kristaps 4: .\"
5: .\" Permission to use, copy, modify, and distribute this software for any
1.13 kristaps 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.8 kristaps 8: .\"
1.13 kristaps 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.17 kristaps 16: .\"
1.1 kristaps 17: .Dd $Mdocdate$
1.12 kristaps 18: .Dt MANUALS 7
1.1 kristaps 19: .Os
1.2 kristaps 20: .\" SECTION
1.1 kristaps 21: .Sh NAME
1.2 kristaps 22: .Nm Writing UNIX Documentation
23: .Nd a guide to writing UNIX manuals
24: .\" SECTION
1.1 kristaps 25: .Sh DESCRIPTION
1.2 kristaps 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
1.17 kristaps 31: importantly, a game.
1.2 kristaps 32: .Pp
1.17 kristaps 33: This document serves as a tutorial to writing
34: .Ux
1.2 kristaps 35: documentation
36: .Pq Dq manuals .
37: .\" SECTION
1.16 kristaps 38: .Sh ENVIRONMENT
1.17 kristaps 39: First, copy over the manual template from
1.11 kristaps 40: .Pa /usr/share/misc/mdoc.template
41: into your source directory.
42: .Pp
43: .Dl % cp /usr/share/misc/mdoc.template \.
1.8 kristaps 44: .Pp
1.5 kristaps 45: .Em \&Do not
46: start afresh or by copying another manual unless you know exactly what
1.11 kristaps 47: you're doing! If the template doesn't exist, bug your administrator.
1.5 kristaps 48: .\" SUBSECTION
49: .Ss Section Numbering
50: Find an appropriate section for your manual. There may exist multiple
1.10 kristaps 51: manual names per section, so be specific:
1.2 kristaps 52: .Pp
1.5 kristaps 53: .\" LIST
1.2 kristaps 54: .Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact
55: .It Em Section
56: .Em Description
57: .It 1
58: operator utilities
1.3 kristaps 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
1.17 kristaps 69: .It 8
1.2 kristaps 70: administrator utilities
1.3 kristaps 71: .It 9
72: in-kernel routines
1.2 kristaps 73: .El
74: .Pp
1.5 kristaps 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
1.7 kristaps 87: myname (1) - utility description
88: myname (3) - library description
1.5 kristaps 89: % man \-s 1 myname
90: .Ed
1.2 kristaps 91: .\" SUBSECTION
92: .Ss Naming
1.10 kristaps 93: Name your component. Be terse, erring on the side of clarity. Look for
94: other manuals by that same name before committing:
1.2 kristaps 95: .Pp
96: .Dl % apropos myname
97: .Pp
1.17 kristaps 98: Manual files are named
1.5 kristaps 99: .Pa myname.mysection ,
1.2 kristaps 100: such as
101: .Pa manuals.7
1.11 kristaps 102: for this document. Rename the template file:
103: .Pp
104: .Dl % mv mdoc.template myname.mysection
1.2 kristaps 105: .\" SUBSECTION
106: .Ss Development Tools
107: While writing, make sure that your manual is correctly structured:
108: .Pp
1.18 ! kristaps 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: `find /usr/src \-name \e*\e.[1-9]` 2>&1 | \e
! 117: sed 's!^mandoc: !!' > /tmp/mandoc.errs
! 118: % vim -q /tmp/mandoc.errs
! 119: .Ed
1.2 kristaps 120: .Pp
121: You may spell-check your work as follows:
122: .Pp
123: .Dl % deroff name.1 | spell
1.11 kristaps 124: .Pp
1.17 kristaps 125: If
1.11 kristaps 126: .Xr ispell 1
127: is installed, it has a special mode for manuals:
128: .Pp
1.2 kristaps 129: .Dl % ispell \-n name.1
130: .Pp
1.17 kristaps 131: Use
1.2 kristaps 132: .Xr cvs 1
1.10 kristaps 133: or
1.2 kristaps 134: .Xr rcs 1
135: to version-control your work. If you wish the last check-in to effect
136: your document's date, use the following RCS tag for the date macro:
137: .Pp
138: .Dl \&.Dd $Mdocdate$
139: .\" SUBSECTION
140: .Ss Viewing
1.17 kristaps 141: mdoc documents may be paged to your terminal with
1.10 kristaps 142: .Xr mandoc 1 .
143: If you plan on distributing your work to systems without this tool,
144: check it against
145: .Xr groff 1 :
1.2 kristaps 146: .Bd -literal -offset indent
1.10 kristaps 147: % mandoc \-Wall name.1 2>&1 | less
148: % groff -mandoc name.1 2>&1 | less
1.2 kristaps 149: .Ed
150: .\" SUBSECTION
151: .Ss Automation
1.17 kristaps 152: Consider adding your mdoc documents to
1.2 kristaps 153: .Xr make 1
1.10 kristaps 154: Makefiles in order to automatically check your input:
1.2 kristaps 155: .Bd -literal -offset indent
1.10 kristaps 156: \&.SUFFIXES: .1 .in
1.1 kristaps 157:
1.2 kristaps 158: \&.in.1:
159: mandoc -Wall,error -Tlint $<
160: cp -f $< $@
161: .Ed
1.8 kristaps 162: .\" SUBSECTION
163: .Ss Licensing
164: Your manual must have a license. It should be listed at the start of
165: your document, just as in source code.
1.2 kristaps 166: .\" SECTION
1.16 kristaps 167: .Sh COMPOSITION
1.17 kristaps 168: Manuals should
169: .Em always
1.16 kristaps 170: be written in the
1.2 kristaps 171: .Xr mdoc 7
1.16 kristaps 172: formatting language.
173: .\" PARAGRAPH
174: .Pp
175: Open the template you've copied into
176: .Pa myname.mysection
177: and begin editing.
1.2 kristaps 178: .\" SUBSECTION
179: .Ss Language
1.17 kristaps 180: .Bl -enum
1.2 kristaps 181: .It
182: Use clear, concise language. Favour simplicity.
183: .It
184: Write your manual in non-idiomatic English. Don't worry about
185: Commonwealth or American spellings \(em just correct ones.
186: .It
187: Spell-check your manual, keeping in mind short-letter terms (
188: .Xr iwi 4
189: vs.
190: .Xr iwn 4 ) .
191: .It
192: If you absolutely must use special characters (diacritics, mathematical
193: symbols and so on), use the escapes dictated in
194: .Xr mdoc 7 .
195: .El
196: .\" SUBSECTION
1.8 kristaps 197: .Ss Style
198: The structure of the mdoc language makes it very hard to have any
199: particular format style. Keep your lines under 72 characters in length.
1.17 kristaps 200: If you must have long option lines, use
1.8 kristaps 201: .Sq \&Oo/Oc .
1.10 kristaps 202: The same goes for function prototypes.
1.8 kristaps 203: .Em \&Do not
1.17 kristaps 204: use
1.10 kristaps 205: .Sq \&Xo/Xc .
206: Find another way to structure your line.
1.8 kristaps 207: .\" SUBSECTION
1.17 kristaps 208: .Ss References
1.2 kristaps 209: Other components may be referenced with the
1.5 kristaps 210: .Sq \&Xr
1.2 kristaps 211: and
212: .Sq \&Sx
213: macros. Make sure that these exist. If you intend to distribute your
214: manual, make sure
215: .Sq \&Xr
216: references are valid across systems (within reason). If you cross-link with
217: .Sq \&Sx ,
218: make sure that the section reference exists.
219: .\" SUBSECTION
220: .Ss Citations
221: Cite your work. If your system references standards documents or other
222: publications, please use the
223: .Sq \&Rs/Re
224: block macros.
225: .\" SUBSECTION
1.3 kristaps 226: .Ss Formatting
1.10 kristaps 227: .Em Don't style your manual .
1.6 kristaps 228: Give it meaningful content. The front-end will worry about formatting
229: and style.
1.5 kristaps 230: .\" SECTION
231: .Sh MAINTENANCE
232: As your component changes and bugs are fixed, your manual may become out
1.11 kristaps 233: of date. You may be tempted to use tools like Doxygen to automate the
234: development of your manuals. Don't.
235: .Pp
236: .Em Manuals are part of a system component :
237: 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