Annotation of mandoc/manuals.7, Revision 1.8
1.8 ! kristaps 1: .\" $Id: mdoc.7,v 1.13 2009/03/22 08:52:27 kristaps Exp $
! 2: .\"
! 3: .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org>
! 4: .\"
! 5: .\" Permission to use, copy, modify, and distribute this software for any
! 6: .\" purpose with or without fee is hereby granted, provided that the
! 7: .\" above copyright notice and this permission notice appear in all
! 8: .\" copies.
! 9: .\"
! 10: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
! 11: .\" WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
! 12: .\" WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
! 13: .\" AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
! 14: .\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
! 15: .\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
! 16: .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
! 17: .\" PERFORMANCE OF THIS SOFTWARE.
! 18: .\"
1.1 kristaps 19: .Dd $Mdocdate$
1.2 kristaps 20: .Dt manuals 7
1.1 kristaps 21: .Os
1.2 kristaps 22: .\" SECTION
1.1 kristaps 23: .Sh NAME
1.2 kristaps 24: .Nm Writing UNIX Documentation
25: .Nd a guide to writing UNIX manuals
26: .\" SECTION
1.1 kristaps 27: .Sh DESCRIPTION
1.2 kristaps 28: .Em A utility without good documentation is of no utility at all .
29: .\" PARAGRAPH
30: .Pp
31: A system component's documentation describes the utility of that
32: component, whether it's a device driver, an executable or, most
33: importantly, a game. Although there are plenty of documents available
34: on how to read
35: .Ux
36: documents, or where to find them, few focus on composition.
37: .\" PARAGRAPH
38: .Pp
39: This document serves as a tutorial to writing
40: .Ux
41: documentation
42: .Pq Dq manuals .
43: If you add something to your operating system, whether it's a new file
44: format or directory structure or device driver, it needs documentation.
45: .\" SECTION
1.5 kristaps 46: .Sh COMPOSITION
47: Prepare your composition environment by copying over the manual template
48: from
49: .Pa /usr/share/misc/mdoc.template .
1.8 ! kristaps 50: .Pp
! 51: If this file doesn't exist, bug your administrator.
1.5 kristaps 52: .Em \&Do not
53: start afresh or by copying another manual unless you know exactly what
54: you're doing!
55: .\" SUBSECTION
56: .Ss Section Numbering
57: Find an appropriate section for your manual. There may exist multiple
58: manual names per section, so be specific. A table of all available
59: manual sections follows:
1.2 kristaps 60: .Pp
1.5 kristaps 61: .\" LIST
1.2 kristaps 62: .Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact
63: .It Em Section
64: .Em Description
65: .It 1
66: operator utilities
1.3 kristaps 67: .It 2
68: system calls
69: .It 3, 3p, 3f
70: programming libraries (C, Perl, Fortran)
71: .It 5
72: file and wire protocol formats
73: .It 6
74: games
75: .It 7
76: tutorials, documents and papers
1.2 kristaps 77: .It 8
78: administrator utilities
1.3 kristaps 79: .It 9
80: in-kernel routines
1.2 kristaps 81: .El
82: .Pp
1.5 kristaps 83: If your manual falls into multiple categories, choose the most
84: widely-used or, better, re-consider the topic of your manual to be more
85: specific. You can list all manuals per section by invoking
86: .Xr apropos 1 ,
87: then provide the
88: .Fl s
89: flag to
90: .Xr man 1
91: to see the specific section manual (section 1, in this example):
92: .\" DISPLAY
93: .Bd -literal -offset indent
94: % apropos myname
1.7 kristaps 95: myname (1) - utility description
96: myname (3) - library description
1.5 kristaps 97: % man \-s 1 myname
98: .Ed
1.2 kristaps 99: .\" SUBSECTION
100: .Ss Naming
1.5 kristaps 101: Name your component. Be terse, erring on the side of clarity. You may
102: want to look for other manuals by that same name before committing:
1.2 kristaps 103: .Pp
104: .Dl % apropos myname
105: .Pp
1.5 kristaps 106: Manual files are named
107: .Pa myname.mysection ,
1.2 kristaps 108: such as
109: .Pa manuals.7
110: for this document.
111: .\" SUBSECTION
112: .Ss Input Language
113: Manuals should
114: .Em always
115: be written in the
116: .Xr mdoc 7
117: formatting language.
118: .Pp
119: There exist other documentation-specific languages, such as the
120: historical
121: .Xr me 7 ,
122: .Xr ms 7
123: and
124: .Xr man 7
125: packages of
126: .Xr roff 7 ;
127: newer languages such as DocBook, texinfo or schema-driven XML; or even
128: ad-hoc conventions such as README files.
1.5 kristaps 129: .Em Avoid these formats .
1.2 kristaps 130: Historical formats fail to capture a manual's semantic content, instead
131: only modelling its style. Newer methods requires special,
132: system-specific tools and may change or become obsolete over the
133: life-time of your component.
134: .Pp
1.5 kristaps 135: There are two canonical references for writing mdoc. Read them.
1.2 kristaps 136: .Pp
137: .\" LIST
138: .Bl -tag -width XXXXXXXXXXXXXXXX -offset indent -compact
139: .It Xr mdoc 7
140: formal language reference
141: .It Xr mdoc.samples 7
142: macro reference
143: .El
144: .Pp
1.4 kristaps 145: Open the template you've copied into
146: .Pa name.section
147: and begin editing.
1.2 kristaps 148: .\" SUBSECTION
149: .Ss Development Tools
150: While writing, make sure that your manual is correctly structured:
151: .Pp
152: .Dl % mandoc \-Tlint \-Wall name.1
153: .Pp
154: You may spell-check your work as follows:
155: .Pp
156: .Dl % deroff name.1 | spell
157: .Dl % ispell \-n name.1
158: .Pp
159: Use
160: .Xr cvs 1
161: or, if not available,
162: .Xr rcs 1
163: to version-control your work. If you wish the last check-in to effect
164: your document's date, use the following RCS tag for the date macro:
165: .Pp
166: .Dl \&.Dd $Mdocdate$
1.8 ! kristaps 167: .Pp
! 168: If using version control, the first line in your manual should be a
! 169: comment with the
! 170: .Li $Id$
! 171: rcs tag.
1.2 kristaps 172: .\" SUBSECTION
173: .Ss Viewing
174: mdoc documents may be paged to your terminal with traditional
175: tools such as
176: .Xr nroff 1 ,
177: .Xr groff 1 ,
178: or with newer, more powerful tools such as
179: .Xr mandoc 1 :
180: .\" DISPLAY
181: .Bd -literal -offset indent
182: % nroff \-mandoc name.1 | less
183: % groff \-Tascii \-mandoc name.1 | less
184: % mandoc name.1 | less
185: .Ed
186: .Pp
187: Other output formats are also supported:
188: .\" DISPLAY
189: .Bd -literal -offset indent
190: % groff \-Tps \-mandoc name.1 | less
191: % mandoc \-Thtml name.1 | less
192: .Ed
193: .\" SUBSECTION
194: .Ss Automation
195: Consider adding your mdoc documents to
196: .Xr make 1
197: Makefiles in order to automatically check your input and generate
198: output:
199: .Bd -literal -offset indent
200: \&.SUFFIXES: .html .txt .1 .in
1.1 kristaps 201:
1.2 kristaps 202: \&.in.1:
203: mandoc -Wall,error -Tlint $<
204: cp -f $< $@
205: \&.1.html:
206: mandoc -Thtml $< >$@
207: \&.1.txt:
208: mandoc -Tascii $< | col -b >$@
209: .Ed
1.8 ! kristaps 210: .\" SUBSECTION
! 211: .Ss Licensing
! 212: Your manual must have a license. It should be listed at the start of
! 213: your document, just as in source code.
1.2 kristaps 214: .\" SECTION
215: .Sh BEST PRACTICES
216: The
217: .Xr mdoc 7
218: and
219: .Xr mdoc.samples 7
1.4 kristaps 220: files are indispensable in guiding composition. In this section, we
1.2 kristaps 221: introduce some
222: .Ux
223: manual best practices:
224: .\" SUBSECTION
225: .Ss Language
226: .Bl -enum
227: .It
228: Use clear, concise language. Favour simplicity.
229: .It
230: Write your manual in non-idiomatic English. Don't worry about
231: Commonwealth or American spellings \(em just correct ones.
232: .It
233: Spell-check your manual, keeping in mind short-letter terms (
234: .Xr iwi 4
235: vs.
236: .Xr iwn 4 ) .
237: .It
238: If you absolutely must use special characters (diacritics, mathematical
239: symbols and so on), use the escapes dictated in
240: .Xr mdoc 7 .
241: .El
242: .\" SUBSECTION
1.8 ! kristaps 243: .Ss Style
! 244: The structure of the mdoc language makes it very hard to have any
! 245: particular format style. Keep your lines under 72 characters in length.
! 246: If you must have long option lines, use
! 247: .Sq \&Oo/Oc .
! 248: .Em \&Do not
! 249: use
! 250: .Sq \&Xo/Xc ;
! 251: instead, either fine another way to write long lines, or, at the
! 252: absolute worst, use CPP-style newline escapes.
! 253: .\" SUBSECTION
1.2 kristaps 254: .Ss References
255: Other components may be referenced with the
1.5 kristaps 256: .Sq \&Xr
1.2 kristaps 257: and
258: .Sq \&Sx
259: macros. Make sure that these exist. If you intend to distribute your
260: manual, make sure
261: .Sq \&Xr
262: references are valid across systems (within reason). If you cross-link with
263: .Sq \&Sx ,
264: make sure that the section reference exists.
265: .\" SUBSECTION
266: .Ss Citations
267: Cite your work. If your system references standards documents or other
268: publications, please use the
269: .Sq \&Rs/Re
270: block macros.
271: .\" SUBSECTION
1.3 kristaps 272: .Ss Formatting
1.7 kristaps 273: .Em Don't style your manual.
1.6 kristaps 274: Give it meaningful content. The front-end will worry about formatting
275: and style.
1.5 kristaps 276: .\" SECTION
277: .Sh MAINTENANCE
278: As your component changes and bugs are fixed, your manual may become out
279: of date. You may be tempted to use automation tools like Doxygen to
280: smooth the development of your manuals. Don't. Source documentation is
1.6 kristaps 281: 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