Annotation of src/usr.bin/mandoc/manuals.7, Revision 1.1
1.1 ! kristaps 1: .\" $Id: manuals.7,v 1.11 2009/04/03 13:17:26 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: .\"
! 19: .Dd $Mdocdate$
! 20: .Dt manuals 7
! 21: .Os
! 22: .\" SECTION
! 23: .Sh NAME
! 24: .Nm Writing UNIX Documentation
! 25: .Nd a guide to writing UNIX manuals
! 26: .\" SECTION
! 27: .Sh DESCRIPTION
! 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.
! 34: .Pp
! 35: This document serves as a tutorial to writing
! 36: .Ux
! 37: documentation
! 38: .Pq Dq manuals .
! 39: .\" SECTION
! 40: .Sh COMPOSITION
! 41: First, copy over the manual template from
! 42: .Pa /usr/share/misc/mdoc.template
! 43: into your source directory.
! 44: .Pp
! 45: .Dl % cp /usr/share/misc/mdoc.template \.
! 46: .Pp
! 47: .Em \&Do not
! 48: start afresh or by copying another manual unless you know exactly what
! 49: you're doing! If the template doesn't exist, bug your administrator.
! 50: .\" SUBSECTION
! 51: .Ss Section Numbering
! 52: Find an appropriate section for your manual. There may exist multiple
! 53: manual names per section, so be specific:
! 54: .Pp
! 55: .\" LIST
! 56: .Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact
! 57: .It Em Section
! 58: .Em Description
! 59: .It 1
! 60: operator utilities
! 61: .It 2
! 62: system calls
! 63: .It 3, 3p, 3f
! 64: programming libraries (C, Perl, Fortran)
! 65: .It 5
! 66: file and wire protocol formats
! 67: .It 6
! 68: games
! 69: .It 7
! 70: tutorials, documents and papers
! 71: .It 8
! 72: administrator utilities
! 73: .It 9
! 74: in-kernel routines
! 75: .El
! 76: .Pp
! 77: If your manual falls into multiple categories, choose the most
! 78: widely-used or, better, re-consider the topic of your manual to be more
! 79: specific. You can list all manuals per section by invoking
! 80: .Xr apropos 1 ,
! 81: then provide the
! 82: .Fl s
! 83: flag to
! 84: .Xr man 1
! 85: to see the specific section manual (section 1, in this example):
! 86: .\" DISPLAY
! 87: .Bd -literal -offset indent
! 88: % apropos myname
! 89: myname (1) - utility description
! 90: myname (3) - library description
! 91: % man \-s 1 myname
! 92: .Ed
! 93: .\" SUBSECTION
! 94: .Ss Naming
! 95: Name your component. Be terse, erring on the side of clarity. Look for
! 96: other manuals by that same name before committing:
! 97: .Pp
! 98: .Dl % apropos myname
! 99: .Pp
! 100: Manual files are named
! 101: .Pa myname.mysection ,
! 102: such as
! 103: .Pa manuals.7
! 104: for this document. Rename the template file:
! 105: .Pp
! 106: .Dl % mv mdoc.template myname.mysection
! 107: .\" SUBSECTION
! 108: .Ss Input Language
! 109: Manuals should
! 110: .Em always
! 111: be written in the
! 112: .Xr mdoc 7
! 113: formatting language.
! 114: .Pp
! 115: There exist other documentation-specific languages, such as the
! 116: historical
! 117: .Xr man 7
! 118: package of
! 119: .Xr roff 7 ;
! 120: newer languages such as DocBook or texinfo; or even ad-hoc conventions
! 121: such as README files.
! 122: .Em Avoid these formats .
! 123: .Pp
! 124: There are two canonical references for writing mdoc. Read them.
! 125: .Pp
! 126: .\" LIST
! 127: .Bl -tag -width XXXXXXXXXXXXXXXX -offset indent -compact
! 128: .It Xr mdoc 7
! 129: formal language reference
! 130: .It Xr mdoc.samples 7
! 131: macro reference
! 132: .El
! 133: .Pp
! 134: Open the template you've copied into
! 135: .Pa myname.mysection
! 136: and begin editing.
! 137: .\" SUBSECTION
! 138: .Ss Development Tools
! 139: While writing, make sure that your manual is correctly structured:
! 140: .Pp
! 141: .Dl % mandoc \-Tlint \-Wall name.1
! 142: .Pp
! 143: You may spell-check your work as follows:
! 144: .Pp
! 145: .Dl % deroff name.1 | spell
! 146: .Pp
! 147: If
! 148: .Xr ispell 1
! 149: is installed, it has a special mode for manuals:
! 150: .Pp
! 151: .Dl % ispell \-n name.1
! 152: .Pp
! 153: Use
! 154: .Xr cvs 1
! 155: or
! 156: .Xr rcs 1
! 157: to version-control your work. If you wish the last check-in to effect
! 158: your document's date, use the following RCS tag for the date macro:
! 159: .Pp
! 160: .Dl \&.Dd $Mdocdate$
! 161: .\" SUBSECTION
! 162: .Ss Viewing
! 163: mdoc documents may be paged to your terminal with
! 164: .Xr mandoc 1 .
! 165: If you plan on distributing your work to systems without this tool,
! 166: check it against
! 167: .Xr groff 1 :
! 168: .Bd -literal -offset indent
! 169: % mandoc \-Wall name.1 2>&1 | less
! 170: % groff -mandoc name.1 2>&1 | less
! 171: .Ed
! 172: .\" SUBSECTION
! 173: .Ss Automation
! 174: Consider adding your mdoc documents to
! 175: .Xr make 1
! 176: Makefiles in order to automatically check your input:
! 177: .Bd -literal -offset indent
! 178: \&.SUFFIXES: .1 .in
! 179:
! 180: \&.in.1:
! 181: mandoc -Wall,error -Tlint $<
! 182: cp -f $< $@
! 183: .Ed
! 184: .\" SUBSECTION
! 185: .Ss Licensing
! 186: Your manual must have a license. It should be listed at the start of
! 187: your document, just as in source code.
! 188: .\" SECTION
! 189: .Sh BEST PRACTICES
! 190: The
! 191: .Xr mdoc 7
! 192: and
! 193: .Xr mdoc.samples 7
! 194: files are indispensable in guiding composition. In this section, we
! 195: introduce some
! 196: .Ux
! 197: manual best practices:
! 198: .\" SUBSECTION
! 199: .Ss Language
! 200: .Bl -enum
! 201: .It
! 202: Use clear, concise language. Favour simplicity.
! 203: .It
! 204: Write your manual in non-idiomatic English. Don't worry about
! 205: Commonwealth or American spellings \(em just correct ones.
! 206: .It
! 207: Spell-check your manual, keeping in mind short-letter terms (
! 208: .Xr iwi 4
! 209: vs.
! 210: .Xr iwn 4 ) .
! 211: .It
! 212: If you absolutely must use special characters (diacritics, mathematical
! 213: symbols and so on), use the escapes dictated in
! 214: .Xr mdoc 7 .
! 215: .El
! 216: .\" SUBSECTION
! 217: .Ss Style
! 218: The structure of the mdoc language makes it very hard to have any
! 219: particular format style. Keep your lines under 72 characters in length.
! 220: If you must have long option lines, use
! 221: .Sq \&Oo/Oc .
! 222: The same goes for function prototypes.
! 223: .Em \&Do not
! 224: use
! 225: .Sq \&Xo/Xc .
! 226: Find another way to structure your line.
! 227: .\" SUBSECTION
! 228: .Ss References
! 229: Other components may be referenced with the
! 230: .Sq \&Xr
! 231: and
! 232: .Sq \&Sx
! 233: macros. Make sure that these exist. If you intend to distribute your
! 234: manual, make sure
! 235: .Sq \&Xr
! 236: references are valid across systems (within reason). If you cross-link with
! 237: .Sq \&Sx ,
! 238: make sure that the section reference exists.
! 239: .\" SUBSECTION
! 240: .Ss Citations
! 241: Cite your work. If your system references standards documents or other
! 242: publications, please use the
! 243: .Sq \&Rs/Re
! 244: block macros.
! 245: .\" SUBSECTION
! 246: .Ss Formatting
! 247: .Em Don't style your manual .
! 248: Give it meaningful content. The front-end will worry about formatting
! 249: and style.
! 250: .\" SECTION
! 251: .Sh MAINTENANCE
! 252: As your component changes and bugs are fixed, your manual may become out
! 253: of date. You may be tempted to use tools like Doxygen to automate the
! 254: development of your manuals. Don't.
! 255: .Pp
! 256: .Em Manuals are part of a system component :
! 257: if you modify your code or specifications, modify the documentation.
![[BACK]](/icons/back.gif){kind=icon}
Return to manuals.7 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / mandoc