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

Annotation of mandoc/manuals.7, Revision 1.6

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

CVSweb