Annotation of mandoc/manuals.7, Revision 1.7
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
1.7 ! kristaps 75: myname (1) - utility description
! 76: myname (3) - library description
1.5 kristaps 77: % man \-s 1 myname
78: .Ed
1.2 kristaps 79: .\" SUBSECTION
80: .Ss Naming
1.5 kristaps 81: Name your component. Be terse, erring on the side of clarity. You may
82: want to look for other manuals by that same name before committing:
1.2 kristaps 83: .Pp
84: .Dl % apropos myname
85: .Pp
1.5 kristaps 86: Manual files are named
87: .Pa myname.mysection ,
1.2 kristaps 88: such as
89: .Pa manuals.7
90: for this document.
91: .\" SUBSECTION
92: .Ss Input Language
93: Manuals should
94: .Em always
95: be written in the
96: .Xr mdoc 7
97: formatting language.
98: .Pp
99: There exist other documentation-specific languages, such as the
100: historical
101: .Xr me 7 ,
102: .Xr ms 7
103: and
104: .Xr man 7
105: packages of
106: .Xr roff 7 ;
107: newer languages such as DocBook, texinfo or schema-driven XML; or even
108: ad-hoc conventions such as README files.
1.5 kristaps 109: .Em Avoid these formats .
1.2 kristaps 110: Historical formats fail to capture a manual's semantic content, instead
111: only modelling its style. Newer methods requires special,
112: system-specific tools and may change or become obsolete over the
113: life-time of your component.
114: .Pp
1.5 kristaps 115: There are two canonical references for writing mdoc. Read them.
1.2 kristaps 116: .Pp
117: .\" LIST
118: .Bl -tag -width XXXXXXXXXXXXXXXX -offset indent -compact
119: .It Xr mdoc 7
120: formal language reference
121: .It Xr mdoc.samples 7
122: macro reference
123: .El
124: .Pp
1.4 kristaps 125: Open the template you've copied into
126: .Pa name.section
127: and begin editing.
1.2 kristaps 128: .\" SUBSECTION
129: .Ss Development Tools
130: While writing, make sure that your manual is correctly structured:
131: .Pp
132: .Dl % mandoc \-Tlint \-Wall name.1
133: .Pp
134: You may spell-check your work as follows:
135: .Pp
136: .Dl % deroff name.1 | spell
137: .Dl % ispell \-n name.1
138: .Pp
139: Use
140: .Xr cvs 1
141: or, if not available,
142: .Xr rcs 1
143: to version-control your work. If you wish the last check-in to effect
144: your document's date, use the following RCS tag for the date macro:
145: .Pp
146: .Dl \&.Dd $Mdocdate$
147: .\" SUBSECTION
148: .Ss Viewing
149: mdoc documents may be paged to your terminal with traditional
150: tools such as
151: .Xr nroff 1 ,
152: .Xr groff 1 ,
153: or with newer, more powerful tools such as
154: .Xr mandoc 1 :
155: .\" DISPLAY
156: .Bd -literal -offset indent
157: % nroff \-mandoc name.1 | less
158: % groff \-Tascii \-mandoc name.1 | less
159: % mandoc name.1 | less
160: .Ed
161: .Pp
162: Other output formats are also supported:
163: .\" DISPLAY
164: .Bd -literal -offset indent
165: % groff \-Tps \-mandoc name.1 | less
166: % mandoc \-Thtml name.1 | less
167: .Ed
168: .\" SUBSECTION
169: .Ss Automation
170: Consider adding your mdoc documents to
171: .Xr make 1
172: Makefiles in order to automatically check your input and generate
173: output:
174: .Bd -literal -offset indent
175: \&.SUFFIXES: .html .txt .1 .in
1.1 kristaps 176:
1.2 kristaps 177: \&.in.1:
178: mandoc -Wall,error -Tlint $<
179: cp -f $< $@
180: \&.1.html:
181: mandoc -Thtml $< >$@
182: \&.1.txt:
183: mandoc -Tascii $< | col -b >$@
184: .Ed
185: .\" SECTION
186: .Sh BEST PRACTICES
187: The
188: .Xr mdoc 7
189: and
190: .Xr mdoc.samples 7
1.4 kristaps 191: files are indispensable in guiding composition. In this section, we
1.2 kristaps 192: introduce some
193: .Ux
194: manual best practices:
195: .\" SUBSECTION
196: .Ss Language
197: .Bl -enum
198: .It
199: Use clear, concise language. Favour simplicity.
200: .It
201: Write your manual in non-idiomatic English. Don't worry about
202: Commonwealth or American spellings \(em just correct ones.
203: .It
204: Spell-check your manual, keeping in mind short-letter terms (
205: .Xr iwi 4
206: vs.
207: .Xr iwn 4 ) .
208: .It
209: If you absolutely must use special characters (diacritics, mathematical
210: symbols and so on), use the escapes dictated in
211: .Xr mdoc 7 .
212: .El
213: .\" SUBSECTION
214: .Ss References
215: Other components may be referenced with the
1.5 kristaps 216: .Sq \&Xr
1.2 kristaps 217: and
218: .Sq \&Sx
219: macros. Make sure that these exist. If you intend to distribute your
220: manual, make sure
221: .Sq \&Xr
222: references are valid across systems (within reason). If you cross-link with
223: .Sq \&Sx ,
224: make sure that the section reference exists.
225: .\" SUBSECTION
226: .Ss Citations
227: Cite your work. If your system references standards documents or other
228: publications, please use the
229: .Sq \&Rs/Re
230: block macros.
231: .\" SUBSECTION
1.3 kristaps 232: .Ss Formatting
1.7 ! kristaps 233: .Em Don't style your manual.
1.6 kristaps 234: Give it meaningful content. The front-end will worry about formatting
235: and style.
1.5 kristaps 236: .\" SECTION
237: .Sh MAINTENANCE
238: As your component changes and bugs are fixed, your manual may become out
239: of date. You may be tempted to use automation tools like Doxygen to
240: smooth the development of your manuals. Don't. Source documentation is
1.6 kristaps 241: 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