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