Annotation of mandoc/manuals.7, Revision 1.4
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 ,
1.4 ! kristaps 31: each component has a manual section , which categorises the component's
! 32: function. The section of a manual is usually listed in parenthesis next
! 33: to the component name, such as
1.2 kristaps 34: .Xr ps 1 ,
35: section 1. You can query a manual explicitly by its section:
1.4 ! kristaps 36: .Bd -literal -offset XXXX
! 37: % man \-s 1 ps
! 38: % apropos ps
! 39: .Ed
1.2 kristaps 40: .Pp
1.3 kristaps 41: The following table lists classifications and the applicable manual
42: sections:
1.2 kristaps 43: .Pp
44: .Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact
45: .It Em Section
46: .Em Description
47: .It 1
48: operator utilities
1.3 kristaps 49: .It 2
50: system calls
51: .It 3, 3p, 3f
52: programming libraries (C, Perl, Fortran)
53: .It 5
54: file and wire protocol formats
55: .It 6
56: games
57: .It 7
58: tutorials, documents and papers
1.2 kristaps 59: .It 8
60: administrator utilities
1.3 kristaps 61: .It 9
62: in-kernel routines
1.2 kristaps 63: .El
64: .Pp
1.3 kristaps 65: Some examples in regular name/section form:
1.2 kristaps 66: .Pp
67: .\" LIST
1.3 kristaps 68: .Bl -tag -width "File-formatX" -offset indent -compact
1.2 kristaps 69: .It Em Manual
70: .Em Description
1.3 kristaps 71: .It Xr dc 4
72: DEC/Intel 10/100 Ethernet device
1.2 kristaps 73: .It Xr usermod 8
74: modify user login information
75: .It Xr cc 1
76: the C compiler
77: .It Xr fortune 6
78: print a random adage
79: .It Xr open 2
80: open or create a file for reading or writing
81: .It Xr isspace 3
82: whitespace character test
83: .It Xr Pod::Man 3p
84: convert POD data to formatted roff
85: .It Xr tsleep 9
86: process context sleep
87: .It Xr passwd 5
88: format of the password file
89: .It Xr symlink 7
90: symbolic link handling
91: .El
92: .\" SECTION
93: .Sh COMPOSITION
1.4 ! kristaps 94: Prepare your composition environment by copying over the manual template
! 95: from
! 96: .Pa /usr/share/misc/mdoc.template .
! 97: .Em \&Do not
! 98: start afresh or by copying another manual unless you know exactly what
! 99: you're doing!
1.2 kristaps 100: .\" SUBSECTION
101: .Ss Naming
102: Your component will need a name by which to query its contents via
103: .Xr man 1 .
104: Keep it simple. You may want to look for other manuals by that same
105: name before committing:
106: .Pp
107: .Dl % apropos myname
108: .Pp
109: Conventionally, manual files are named
110: .Pa myname.section ,
111: such as
112: .Pa manuals.7
113: for this document.
114: .\" SUBSECTION
115: .Ss Input Language
116: Manuals should
117: .Em always
118: be written in the
119: .Xr mdoc 7
120: formatting language.
121: .Pp
122: There exist other documentation-specific languages, such as the
123: historical
124: .Xr me 7 ,
125: .Xr ms 7
126: and
127: .Xr man 7
128: packages of
129: .Xr roff 7 ;
130: newer languages such as DocBook, texinfo or schema-driven XML; or even
131: ad-hoc conventions such as README files.
132: .Em Stay away from these methods!
133: Historical formats fail to capture a manual's semantic content, instead
134: only modelling its style. Newer methods requires special,
135: system-specific tools and may change or become obsolete over the
136: life-time of your component.
137: .Pp
138: There are two canonical references for writing mdoc manuals:
139: .Pp
140: .\" LIST
141: .Bl -tag -width XXXXXXXXXXXXXXXX -offset indent -compact
142: .It Xr mdoc 7
143: formal language reference
144: .It Xr mdoc.samples 7
145: macro reference
146: .El
147: .Pp
1.4 ! kristaps 148: Open the template you've copied into
! 149: .Pa name.section
! 150: and begin editing.
1.2 kristaps 151: .\" SUBSECTION
152: .Ss Development Tools
153: While writing, make sure that your manual is correctly structured:
154: .Pp
155: .Dl % mandoc \-Tlint \-Wall name.1
156: .Pp
157: You may spell-check your work as follows:
158: .Pp
159: .Dl % deroff name.1 | spell
160: .Dl % ispell \-n name.1
161: .Pp
162: Use
163: .Xr cvs 1
164: or, if not available,
165: .Xr rcs 1
166: to version-control your work. If you wish the last check-in to effect
167: your document's date, use the following RCS tag for the date macro:
168: .Pp
169: .Dl \&.Dd $Mdocdate$
170: .\" SUBSECTION
171: .Ss Viewing
172: mdoc documents may be paged to your terminal with traditional
173: tools such as
174: .Xr nroff 1 ,
175: .Xr groff 1 ,
176: or with newer, more powerful tools such as
177: .Xr mandoc 1 :
178: .\" DISPLAY
179: .Bd -literal -offset indent
180: % nroff \-mandoc name.1 | less
181: % groff \-Tascii \-mandoc name.1 | less
182: % mandoc name.1 | less
183: .Ed
184: .Pp
185: Other output formats are also supported:
186: .\" DISPLAY
187: .Bd -literal -offset indent
188: % groff \-Tps \-mandoc name.1 | less
189: % mandoc \-Thtml name.1 | less
190: .Ed
191: .\" SUBSECTION
192: .Ss Automation
193: Consider adding your mdoc documents to
194: .Xr make 1
195: Makefiles in order to automatically check your input and generate
196: output:
197: .Bd -literal -offset indent
198: \&.SUFFIXES: .html .txt .1 .in
1.1 kristaps 199:
1.2 kristaps 200: \&.in.1:
201: mandoc -Wall,error -Tlint $<
202: cp -f $< $@
1.1 kristaps 203:
1.2 kristaps 204: \&.1.html:
205: mandoc -Thtml $< >$@
1.1 kristaps 206:
1.2 kristaps 207: \&.1.txt:
208: mandoc -Tascii $< | col -b >$@
209: .Ed
210: .\" SECTION
211: .Sh BEST PRACTICES
212: The
213: .Xr mdoc 7
214: and
215: .Xr mdoc.samples 7
1.4 ! kristaps 216: files are indispensable in guiding composition. In this section, we
1.2 kristaps 217: introduce some
218: .Ux
219: manual best practices:
220: .\" SUBSECTION
221: .Ss Language
222: .Bl -enum
223: .It
224: Use clear, concise language. Favour simplicity.
225: .It
226: Write your manual in non-idiomatic English. Don't worry about
227: Commonwealth or American spellings \(em just correct ones.
228: .It
229: Spell-check your manual, keeping in mind short-letter terms (
230: .Xr iwi 4
231: vs.
232: .Xr iwn 4 ) .
233: .It
234: If you absolutely must use special characters (diacritics, mathematical
235: symbols and so on), use the escapes dictated in
236: .Xr mdoc 7 .
237: .El
238: .\" SUBSECTION
239: .Ss References
240: Other components may be referenced with the
241: .Sq \&Xr ,
242: and
243: .Sq \&Sx
244: macros. Make sure that these exist. If you intend to distribute your
245: manual, make sure
246: .Sq \&Xr
247: references are valid across systems (within reason). If you cross-link with
248: .Sq \&Sx ,
249: make sure that the section reference exists.
250: .\" SUBSECTION
251: .Ss Citations
252: Cite your work. If your system references standards documents or other
253: publications, please use the
254: .Sq \&Rs/Re
255: block macros.
256: .\" SUBSECTION
1.3 kristaps 257: .Ss Formatting
258: Let the front-ends worry about formatting for you, but if you must think
259: about formatting (at times necessary, especially for tagged and columnar
260: lists), assume that your output device is a fixed-width terminal window:
261: .Bd -literal -offset indent
262: \&.Bl \-tag \-width "-o outfile"
263: \&.It \&Fl \&Ar outfile
264: .Ed
265: .Pp
266: You may assume that the width calculated by the string literal
267: .Qq Fl o Ar outfile
1.4 ! kristaps 268: will be covered by the \-width argument.
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