[BACK]Return to manuals.7 CVS log [TXT][DIR] Up to [cvsweb.bsd.lv] / mandoc

Annotation of mandoc/manuals.7, Revision 1.19

1.19    ! kristaps    1: .\"    $Id: manuals.7,v 1.18 2009/07/27 13:10:08 kristaps Exp $
1.8       kristaps    2: .\"
1.14      kristaps    3: .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
1.8       kristaps    4: .\"
                      5: .\" Permission to use, copy, modify, and distribute this software for any
1.13      kristaps    6: .\" purpose with or without fee is hereby granted, provided that the above
                      7: .\" copyright notice and this permission notice appear in all copies.
1.8       kristaps    8: .\"
1.13      kristaps    9: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
                     10: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
                     11: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
                     12: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
                     13: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
                     14: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
                     15: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
1.17      kristaps   16: .\"
1.1       kristaps   17: .Dd $Mdocdate$
1.12      kristaps   18: .Dt MANUALS 7
1.1       kristaps   19: .Os
1.2       kristaps   20: .\" SECTION
1.1       kristaps   21: .Sh NAME
1.2       kristaps   22: .Nm Writing UNIX Documentation
                     23: .Nd a guide to writing UNIX manuals
                     24: .\" SECTION
1.1       kristaps   25: .Sh DESCRIPTION
1.2       kristaps   26: .Em A utility without good documentation is of no utility at all .
                     27: .\" PARAGRAPH
                     28: .Pp
                     29: A system component's documentation describes the utility of that
                     30: component, whether it's a device driver, an executable or, most
1.17      kristaps   31: importantly, a game.
1.2       kristaps   32: .Pp
1.17      kristaps   33: This document serves as a tutorial to writing
                     34: .Ux
1.2       kristaps   35: documentation
                     36: .Pq Dq manuals .
                     37: .\" SECTION
1.16      kristaps   38: .Sh ENVIRONMENT
1.17      kristaps   39: First, copy over the manual template from
1.11      kristaps   40: .Pa /usr/share/misc/mdoc.template
                     41: into your source directory.
                     42: .Pp
                     43: .Dl % cp /usr/share/misc/mdoc.template \.
1.8       kristaps   44: .Pp
1.5       kristaps   45: .Em \&Do not
                     46: start afresh or by copying another manual unless you know exactly what
1.11      kristaps   47: you're doing!  If the template doesn't exist, bug your administrator.
1.5       kristaps   48: .\" SUBSECTION
                     49: .Ss Section Numbering
                     50: Find an appropriate section for your manual.  There may exist multiple
1.10      kristaps   51: manual names per section, so be specific:
1.2       kristaps   52: .Pp
1.5       kristaps   53: .\" LIST
1.2       kristaps   54: .Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact
                     55: .It Em Section
                     56: .Em Description
                     57: .It 1
                     58: operator utilities
1.3       kristaps   59: .It 2
                     60: system calls
                     61: .It 3, 3p, 3f
                     62: programming libraries (C, Perl, Fortran)
                     63: .It 5
                     64: file and wire protocol formats
                     65: .It 6
                     66: games
                     67: .It 7
                     68: tutorials, documents and papers
1.17      kristaps   69: .It 8
1.2       kristaps   70: administrator utilities
1.3       kristaps   71: .It 9
                     72: in-kernel routines
1.2       kristaps   73: .El
                     74: .Pp
1.5       kristaps   75: If your manual falls into multiple categories, choose the most
                     76: widely-used or, better, re-consider the topic of your manual to be more
                     77: specific.  You can list all manuals per section by invoking
                     78: .Xr apropos 1 ,
                     79: then provide the
                     80: .Fl s
                     81: flag to
                     82: .Xr man 1
                     83: to see the specific section manual (section 1, in this example):
                     84: .\" DISPLAY
                     85: .Bd -literal -offset indent
                     86: % apropos myname
1.7       kristaps   87: myname (1) - utility description
                     88: myname (3) - library description
1.5       kristaps   89: % man \-s 1 myname
                     90: .Ed
1.2       kristaps   91: .\" SUBSECTION
                     92: .Ss Naming
1.10      kristaps   93: Name your component.  Be terse, erring on the side of clarity.  Look for
                     94: other manuals by that same name before committing:
1.2       kristaps   95: .Pp
                     96: .Dl % apropos myname
                     97: .Pp
1.17      kristaps   98: Manual files are named
1.5       kristaps   99: .Pa myname.mysection ,
1.2       kristaps  100: such as
                    101: .Pa manuals.7
1.11      kristaps  102: for this document.  Rename the template file:
                    103: .Pp
                    104: .Dl % mv mdoc.template myname.mysection
1.2       kristaps  105: .\" SUBSECTION
                    106: .Ss Development Tools
                    107: While writing, make sure that your manual is correctly structured:
                    108: .Pp
1.18      kristaps  109: .Dl % mandoc \-Tlint \-Wall \-fstrict name.1
                    110: .Pp
                    111: The quick-fix feature of
                    112: .Xr vim 1
                    113: is useful for checking over many manuals:
                    114: .Bd -literal -offset indent
                    115: % mandoc \-Wall \-fstrict \-Tlint \-fign-errors \e
1.19    ! kristaps  116:   ./path/to/manuals/* 2>&1 > /tmp/mandoc.errs
1.18      kristaps  117: % vim -q /tmp/mandoc.errs
                    118: .Ed
1.2       kristaps  119: .Pp
                    120: You may spell-check your work as follows:
                    121: .Pp
                    122: .Dl % deroff name.1 | spell
1.11      kristaps  123: .Pp
1.17      kristaps  124: If
1.11      kristaps  125: .Xr ispell 1
                    126: is installed, it has a special mode for manuals:
                    127: .Pp
1.2       kristaps  128: .Dl % ispell \-n name.1
                    129: .Pp
1.17      kristaps  130: Use
1.2       kristaps  131: .Xr cvs 1
1.10      kristaps  132: or
1.2       kristaps  133: .Xr rcs 1
                    134: to version-control your work.  If you wish the last check-in to effect
                    135: your document's date, use the following RCS tag for the date macro:
                    136: .Pp
                    137: .Dl \&.Dd $Mdocdate$
                    138: .\" SUBSECTION
                    139: .Ss Viewing
1.17      kristaps  140: mdoc documents may be paged to your terminal with
1.10      kristaps  141: .Xr mandoc 1 .
                    142: If you plan on distributing your work to systems without this tool,
                    143: check it against
                    144: .Xr groff 1 :
1.2       kristaps  145: .Bd -literal -offset indent
1.10      kristaps  146: % mandoc \-Wall name.1 2>&1 | less
                    147: % groff -mandoc name.1 2>&1 | less
1.2       kristaps  148: .Ed
                    149: .\" SUBSECTION
                    150: .Ss Automation
1.17      kristaps  151: Consider adding your mdoc documents to
1.2       kristaps  152: .Xr make 1
1.10      kristaps  153: Makefiles in order to automatically check your input:
1.2       kristaps  154: .Bd -literal -offset indent
1.10      kristaps  155: \&.SUFFIXES: .1 .in
1.1       kristaps  156:
1.2       kristaps  157: \&.in.1:
                    158:        mandoc -Wall,error -Tlint $<
                    159:        cp -f $< $@
                    160: .Ed
1.8       kristaps  161: .\" SUBSECTION
                    162: .Ss Licensing
                    163: Your manual must have a license.  It should be listed at the start of
                    164: your document, just as in source code.
1.2       kristaps  165: .\" SECTION
1.16      kristaps  166: .Sh COMPOSITION
1.17      kristaps  167: Manuals should
                    168: .Em always
1.16      kristaps  169: be written in the
1.2       kristaps  170: .Xr mdoc 7
1.16      kristaps  171: formatting language.
                    172: .\" PARAGRAPH
                    173: .Pp
                    174: Open the template you've copied into
                    175: .Pa myname.mysection
                    176: and begin editing.
1.2       kristaps  177: .\" SUBSECTION
                    178: .Ss Language
1.17      kristaps  179: .Bl -enum
1.2       kristaps  180: .It
                    181: Use clear, concise language.  Favour simplicity.
                    182: .It
                    183: Write your manual in non-idiomatic English.  Don't worry about
                    184: Commonwealth or American spellings \(em just correct ones.
                    185: .It
                    186: Spell-check your manual, keeping in mind short-letter terms (
                    187: .Xr iwi 4
                    188: vs.
                    189: .Xr iwn 4 ) .
                    190: .It
                    191: If you absolutely must use special characters (diacritics, mathematical
                    192: symbols and so on), use the escapes dictated in
                    193: .Xr mdoc 7 .
                    194: .El
                    195: .\" SUBSECTION
1.8       kristaps  196: .Ss Style
                    197: The structure of the mdoc language makes it very hard to have any
                    198: particular format style.  Keep your lines under 72 characters in length.
1.17      kristaps  199: If you must have long option lines, use
1.8       kristaps  200: .Sq \&Oo/Oc .
1.10      kristaps  201: The same goes for function prototypes.
1.8       kristaps  202: .Em \&Do not
1.17      kristaps  203: use
1.10      kristaps  204: .Sq \&Xo/Xc .
                    205: Find another way to structure your line.
1.8       kristaps  206: .\" SUBSECTION
1.17      kristaps  207: .Ss References
1.2       kristaps  208: Other components may be referenced with the
1.5       kristaps  209: .Sq \&Xr
1.2       kristaps  210: and
                    211: .Sq \&Sx
                    212: macros.  Make sure that these exist.  If you intend to distribute your
                    213: manual, make sure
                    214: .Sq \&Xr
                    215: references are valid across systems (within reason).  If you cross-link with
                    216: .Sq \&Sx ,
                    217: make sure that the section reference exists.
                    218: .\" SUBSECTION
                    219: .Ss Citations
                    220: Cite your work.  If your system references standards documents or other
                    221: publications, please use the
                    222: .Sq \&Rs/Re
                    223: block macros.
                    224: .\" SUBSECTION
1.3       kristaps  225: .Ss Formatting
1.10      kristaps  226: .Em Don't style your manual .
1.6       kristaps  227: Give it meaningful content.  The front-end will worry about formatting
                    228: and style.
1.5       kristaps  229: .\" SECTION
                    230: .Sh MAINTENANCE
                    231: As your component changes and bugs are fixed, your manual may become out
1.11      kristaps  232: of date.  You may be tempted to use tools like Doxygen to automate the
                    233: development of your manuals.  Don't.
                    234: .Pp
                    235: .Em Manuals are part of a system component :
                    236: if you modify your code or specifications, modify the documentation.

CVSweb