Annotation of mandoc/manuals.7, Revision 1.2
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
! 40: The following table lists broad classifications and the applicable
! 41: manual sections:
! 42: .Pp
! 43: .\" LIST
! 44: .Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact
! 45: .It Em Category
! 46: .Em Section(s)
! 47: .It Device
! 48: 4
! 49: .It Executable
! 50: 1, 6, 8
! 51: .It Function
! 52: 2, 3, 9
! 53: .It File-format
! 54: 5
! 55: .It Other
! 56: 7
! 57: .El
! 58: .\" SUBSECTION
! 59: .Ss Devices
! 60: Consists of hardware (and pseudo-) device driver documentation. Drivers
! 61: are unilaterally classified in section 4.
! 62: .Em Note :
! 63: these manuals are necessarily system- and architecture-specific.
! 64: .Pp
! 65: Example:
! 66: .Pp
! 67: .\" LIST
! 68: .Bl -tag -width "File-formatX" -offset indent -compact
! 69: .It Em Manual
! 70: .Em Description
! 71: .It Xr dc 4
! 72: DEC/Intel 10/100 Ethernet device
! 73: .El
! 74: .\" SUBSECTION
! 75: .Ss Executables
! 76: Executables consist of runnable binaries. They're further classified by
! 77: operator utility:
! 78: .Pp
! 79: .\" LIST
! 80: .Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact
! 81: .It Em Section
! 82: .Em Description
! 83: .It 1
! 84: operator utilities
! 85: .It 8
! 86: administrator utilities
! 87: .It 6
! 88: games
! 89: .El
! 90: .Pp
! 91: Examples:
! 92: .Pp
! 93: .\" LIST
! 94: .Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact
! 95: .It Em Manual
! 96: .Em Description
! 97: .It Xr usermod 8
! 98: modify user login information
! 99: .It Xr cc 1
! 100: the C compiler
! 101: .It Xr fortune 6
! 102: print a random adage
! 103: .El
! 104: .\" SUBSECTION
! 105: .Ss Functions
! 106: Function documentation describes programme source code, whether in the
! 107: form of libraries, modules or standalone sources. They're further
! 108: classified by context:
! 109: .Pp
! 110: .\" LIST
! 111: .Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact
! 112: .It Em Section
! 113: .Em Description
! 114: .It 2
! 115: system calls
! 116: .It 3, 3p, 3f
! 117: programming libraries (C, Perl, Fortran)
! 118: .It 9
! 119: in-kernel routines
! 120: .El
! 121: .Pp
! 122: .Em Note :
! 123: section 2 and 9 manuals are necessarily system- and often
! 124: architecture-specific. Examples:
! 125: .Pp
! 126: .\" LIST
! 127: .Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact
! 128: .It Em Manual
! 129: .Em Description
! 130: .It Xr open 2
! 131: open or create a file for reading or writing
! 132: .It Xr isspace 3
! 133: whitespace character test
! 134: .It Xr Pod::Man 3p
! 135: convert POD data to formatted roff
! 136: .It Xr tsleep 9
! 137: process context sleep
! 138: .El
! 139: .\" SUBSECTION
! 140: .Ss File-formats
! 141: A file format usually describes the format of on-disc binary or text
! 142: data, although it can also be used to describe wire protocols (this is
! 143: usually best left to RFC). These manuals are unilaterally classified in
! 144: section 5.
! 145: .Pp
! 146: Example:
! 147: .Pp
! 148: .\" LIST
! 149: .Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact
! 150: .It Em Manual
! 151: .Em Description
! 152: .It Xr passwd 5
! 153: format of the password file
! 154: .El
! 155: .\" SUBSECTION
! 156: .Ss Other
! 157: Documents with no other classification are relegated to section 7. This
! 158: constitutes reference tutorials (such as this document) and other
! 159: miscellaneous information.
! 160: .Pp
! 161: Examples:
! 162: .Pp
! 163: .\" LIST
! 164: .Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact
! 165: .It Em Manual
! 166: .Em Description
! 167: .It Xr ascii 7
! 168: ASCII character sets
! 169: .It Xr symlink 7
! 170: symbolic link handling
! 171: .El
! 172: .\" SECTION
! 173: .Sh COMPOSITION
! 174: Prepare your composition environment.
! 175: .\" SUBSECTION
! 176: .Ss Naming
! 177: Your component will need a name by which to query its contents via
! 178: .Xr man 1 .
! 179: Keep it simple. You may want to look for other manuals by that same
! 180: name before committing:
! 181: .Pp
! 182: .Dl % apropos myname
! 183: .Pp
! 184: Conventionally, manual files are named
! 185: .Pa myname.section ,
! 186: such as
! 187: .Pa manuals.7
! 188: for this document.
! 189: .\" SUBSECTION
! 190: .Ss Input Language
! 191: Manuals should
! 192: .Em always
! 193: be written in the
! 194: .Xr mdoc 7
! 195: formatting language.
! 196: .Pp
! 197: There exist other documentation-specific languages, such as the
! 198: historical
! 199: .Xr me 7 ,
! 200: .Xr ms 7
! 201: and
! 202: .Xr man 7
! 203: packages of
! 204: .Xr roff 7 ;
! 205: newer languages such as DocBook, texinfo or schema-driven XML; or even
! 206: ad-hoc conventions such as README files.
! 207: .Em Stay away from these methods!
! 208: Historical formats fail to capture a manual's semantic content, instead
! 209: only modelling its style. Newer methods requires special,
! 210: system-specific tools and may change or become obsolete over the
! 211: life-time of your component.
! 212: .Pp
! 213: There are two canonical references for writing mdoc manuals:
! 214: .Pp
! 215: .\" LIST
! 216: .Bl -tag -width XXXXXXXXXXXXXXXX -offset indent -compact
! 217: .It Xr mdoc 7
! 218: formal language reference
! 219: .It Xr mdoc.samples 7
! 220: macro reference
! 221: .El
! 222: .Pp
! 223: Don't merely copy existing manuals! Most systems distribute an mdoc
! 224: template to help you get started in
! 225: .Pa /usr/share/misc/mdoc.template .
! 226: .\" SUBSECTION
! 227: .Ss Development Tools
! 228: While writing, make sure that your manual is correctly structured:
! 229: .Pp
! 230: .Dl % mandoc \-Tlint \-Wall name.1
! 231: .Pp
! 232: You may spell-check your work as follows:
! 233: .Pp
! 234: .Dl % deroff name.1 | spell
! 235: .Dl % ispell \-n name.1
! 236: .Pp
! 237: Use
! 238: .Xr cvs 1
! 239: or, if not available,
! 240: .Xr rcs 1
! 241: to version-control your work. If you wish the last check-in to effect
! 242: your document's date, use the following RCS tag for the date macro:
! 243: .Pp
! 244: .Dl \&.Dd $Mdocdate$
! 245: .Pp
! 246: .\" SUBSECTION
! 247: .Ss Viewing
! 248: mdoc documents may be paged to your terminal with traditional
! 249: tools such as
! 250: .Xr nroff 1 ,
! 251: .Xr groff 1 ,
! 252: or with newer, more powerful tools such as
! 253: .Xr mandoc 1 :
! 254: .\" DISPLAY
! 255: .Bd -literal -offset indent
! 256: % nroff \-mandoc name.1 | less
! 257: % groff \-Tascii \-mandoc name.1 | less
! 258: % mandoc name.1 | less
! 259: .Ed
! 260: .Pp
! 261: Other output formats are also supported:
! 262: .\" DISPLAY
! 263: .Bd -literal -offset indent
! 264: % groff \-Tps \-mandoc name.1 | less
! 265: % mandoc \-Thtml name.1 | less
! 266: .Ed
! 267: .\" SUBSECTION
! 268: .Ss Automation
! 269: Consider adding your mdoc documents to
! 270: .Xr make 1
! 271: Makefiles in order to automatically check your input and generate
! 272: output:
! 273: .Bd -literal -offset indent
! 274: \&.SUFFIXES: .html .txt .1 .in
1.1 kristaps 275:
1.2 ! kristaps 276: \&.in.1:
! 277: mandoc -Wall,error -Tlint $<
! 278: cp -f $< $@
1.1 kristaps 279:
1.2 ! kristaps 280: \&.1.html:
! 281: mandoc -Thtml $< >$@
1.1 kristaps 282:
1.2 ! kristaps 283: \&.1.txt:
! 284: mandoc -Tascii $< | col -b >$@
! 285: .Ed
! 286: .\" SECTION
! 287: .Sh BEST PRACTICES
! 288: The
! 289: .Xr mdoc 7
! 290: and
! 291: .Xr mdoc.samples 7
! 292: files will be indispensable in guiding composition. In this section, we
! 293: introduce some
! 294: .Ux
! 295: manual best practices:
! 296: .\" SUBSECTION
! 297: .Ss Language
! 298: .Bl -enum
! 299: .It
! 300: Use clear, concise language. Favour simplicity.
! 301: .It
! 302: Write your manual in non-idiomatic English. Don't worry about
! 303: Commonwealth or American spellings \(em just correct ones.
! 304: .It
! 305: Spell-check your manual, keeping in mind short-letter terms (
! 306: .Xr iwi 4
! 307: vs.
! 308: .Xr iwn 4 ) .
! 309: .It
! 310: If you absolutely must use special characters (diacritics, mathematical
! 311: symbols and so on), use the escapes dictated in
! 312: .Xr mdoc 7 .
! 313: .El
! 314: .\" SUBSECTION
! 315: .Ss References
! 316: Other components may be referenced with the
! 317: .Sq \&Xr ,
! 318: and
! 319: .Sq \&Sx
! 320: macros. Make sure that these exist. If you intend to distribute your
! 321: manual, make sure
! 322: .Sq \&Xr
! 323: references are valid across systems (within reason). If you cross-link with
! 324: .Sq \&Sx ,
! 325: make sure that the section reference exists.
! 326: .\" SUBSECTION
! 327: .Ss Citations
! 328: Cite your work. If your system references standards documents or other
! 329: publications, please use the
! 330: .Sq \&Rs/Re
! 331: block macros.
! 332: .\" SUBSECTION
! 333: .Ss Types and Prototypes
! 334: If writing section 3 manuals, make sure that you correctly annotate your
! 335: variables and functions. This guarantees that cross-referncing between
! 336: function names and their prototypes works properly.
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