Annotation of mandoc/manuals.7, Revision 1.3
1.1 kristaps 1: .Dd $Mdocdate$
1.2 kristaps 2: .Dt manuals 7
1.1 kristaps 3: .Os
1.2 kristaps 4: .\" SECTION
1.1 kristaps 5: .Sh NAME
1.2 kristaps 6: .Nm Writing UNIX Documentation
7: .Nd a guide to writing UNIX manuals
8: .\" SECTION
1.1 kristaps 9: .Sh DESCRIPTION
1.2 kristaps 10: .Em A utility without good documentation is of no utility at all .
11: .\" PARAGRAPH
12: .Pp
13: A system component's documentation describes the utility of that
14: component, whether it's a device driver, an executable or, most
15: importantly, a game. Although there are plenty of documents available
16: on how to read
17: .Ux
18: documents, or where to find them, few focus on composition.
19: .\" PARAGRAPH
20: .Pp
21: This document serves as a tutorial to writing
22: .Ux
23: documentation
24: .Pq Dq manuals .
25: If you add something to your operating system, whether it's a new file
26: format or directory structure or device driver, it needs documentation.
27: .\" SECTION
28: .Sh CLASSIFICATION
29: Classify your system component. In
30: .Ux ,
31: each component has a
32: .Dq manual section ,
33: which categorises the component's function. The section of a manual is
34: usually listed in parenthesis next to the component name, such as
35: .Xr ps 1 ,
36: section 1. You can query a manual explicitly by its section:
37: .Pp
38: .Dl % man \-s 1 ps
39: .Pp
1.3 ! kristaps 40: The following table lists classifications and the applicable manual
! 41: sections:
1.2 kristaps 42: .Pp
43: .Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact
44: .It Em Section
45: .Em Description
46: .It 1
47: operator utilities
1.3 ! kristaps 48: .It 2
! 49: system calls
! 50: .It 3, 3p, 3f
! 51: programming libraries (C, Perl, Fortran)
! 52: .It 5
! 53: file and wire protocol formats
! 54: .It 6
! 55: games
! 56: .It 7
! 57: tutorials, documents and papers
1.2 kristaps 58: .It 8
59: administrator utilities
1.3 ! kristaps 60: .It 9
! 61: in-kernel routines
1.2 kristaps 62: .El
63: .Pp
1.3 ! kristaps 64: Some examples in regular name/section form:
1.2 kristaps 65: .Pp
66: .\" LIST
1.3 ! kristaps 67: .Bl -tag -width "File-formatX" -offset indent -compact
1.2 kristaps 68: .It Em Manual
69: .Em Description
1.3 ! kristaps 70: .It Xr dc 4
! 71: DEC/Intel 10/100 Ethernet device
1.2 kristaps 72: .It Xr usermod 8
73: modify user login information
74: .It Xr cc 1
75: the C compiler
76: .It Xr fortune 6
77: print a random adage
78: .It Xr open 2
79: open or create a file for reading or writing
80: .It Xr isspace 3
81: whitespace character test
82: .It Xr Pod::Man 3p
83: convert POD data to formatted roff
84: .It Xr tsleep 9
85: process context sleep
86: .It Xr passwd 5
87: format of the password file
88: .It Xr symlink 7
89: symbolic link handling
90: .El
91: .\" SECTION
92: .Sh COMPOSITION
93: Prepare your composition environment.
94: .\" SUBSECTION
95: .Ss Naming
96: Your component will need a name by which to query its contents via
97: .Xr man 1 .
98: Keep it simple. You may want to look for other manuals by that same
99: name before committing:
100: .Pp
101: .Dl % apropos myname
102: .Pp
103: Conventionally, manual files are named
104: .Pa myname.section ,
105: such as
106: .Pa manuals.7
107: for this document.
108: .\" SUBSECTION
109: .Ss Input Language
110: Manuals should
111: .Em always
112: be written in the
113: .Xr mdoc 7
114: formatting language.
115: .Pp
116: There exist other documentation-specific languages, such as the
117: historical
118: .Xr me 7 ,
119: .Xr ms 7
120: and
121: .Xr man 7
122: packages of
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.
126: .Em Stay away from these methods!
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
132: There are two canonical references for writing mdoc manuals:
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
142: Don't merely copy existing manuals! Most systems distribute an mdoc
143: template to help you get started in
144: .Pa /usr/share/misc/mdoc.template .
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$
164: .Pp
165: .\" SUBSECTION
166: .Ss Viewing
167: mdoc documents may be paged to your terminal with traditional
168: tools such as
169: .Xr nroff 1 ,
170: .Xr groff 1 ,
171: or with newer, more powerful tools such as
172: .Xr mandoc 1 :
173: .\" DISPLAY
174: .Bd -literal -offset indent
175: % nroff \-mandoc name.1 | less
176: % groff \-Tascii \-mandoc name.1 | less
177: % mandoc name.1 | less
178: .Ed
179: .Pp
180: Other output formats are also supported:
181: .\" DISPLAY
182: .Bd -literal -offset indent
183: % groff \-Tps \-mandoc name.1 | less
184: % mandoc \-Thtml name.1 | less
185: .Ed
186: .\" SUBSECTION
187: .Ss Automation
188: Consider adding your mdoc documents to
189: .Xr make 1
190: Makefiles in order to automatically check your input and generate
191: output:
192: .Bd -literal -offset indent
193: \&.SUFFIXES: .html .txt .1 .in
1.1 kristaps 194:
1.2 kristaps 195: \&.in.1:
196: mandoc -Wall,error -Tlint $<
197: cp -f $< $@
1.1 kristaps 198:
1.2 kristaps 199: \&.1.html:
200: mandoc -Thtml $< >$@
1.1 kristaps 201:
1.2 kristaps 202: \&.1.txt:
203: mandoc -Tascii $< | col -b >$@
204: .Ed
205: .\" SECTION
206: .Sh BEST PRACTICES
207: The
208: .Xr mdoc 7
209: and
210: .Xr mdoc.samples 7
211: files will be indispensable in guiding composition. In this section, we
212: introduce some
213: .Ux
214: manual best practices:
215: .\" SUBSECTION
216: .Ss Language
217: .Bl -enum
218: .It
219: Use clear, concise language. Favour simplicity.
220: .It
221: Write your manual in non-idiomatic English. Don't worry about
222: Commonwealth or American spellings \(em just correct ones.
223: .It
224: Spell-check your manual, keeping in mind short-letter terms (
225: .Xr iwi 4
226: vs.
227: .Xr iwn 4 ) .
228: .It
229: If you absolutely must use special characters (diacritics, mathematical
230: symbols and so on), use the escapes dictated in
231: .Xr mdoc 7 .
232: .El
233: .\" SUBSECTION
234: .Ss References
235: Other components may be referenced with the
236: .Sq \&Xr ,
237: and
238: .Sq \&Sx
239: macros. Make sure that these exist. If you intend to distribute your
240: manual, make sure
241: .Sq \&Xr
242: references are valid across systems (within reason). If you cross-link with
243: .Sq \&Sx ,
244: make sure that the section reference exists.
245: .\" SUBSECTION
246: .Ss Citations
247: Cite your work. If your system references standards documents or other
248: publications, please use the
249: .Sq \&Rs/Re
250: block macros.
251: .\" SUBSECTION
1.3 ! kristaps 252: .Ss Formatting
! 253: Let the front-ends worry about formatting for you, but if you must think
! 254: about formatting (at times necessary, especially for tagged and columnar
! 255: lists), assume that your output device is a fixed-width terminal window:
! 256: .Bd -literal -offset indent
! 257: \&.Bl \-tag \-width "-o outfile"
! 258: \&.It \&Fl \&Ar outfile
! 259: .Ed
! 260: .Pp
! 261: You may assume that the width calculated by the string literal
! 262: .Qq Fl o Ar outfile
! 263: will
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