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

Diff for /mandoc/Attic/manuals.7 between version 1.1 and 1.3

version 1.1, 2009/03/22 08:52:27 version 1.3, 2009/03/22 14:28:08
Line 1 
Line 1 
 .Dd $Mdocdate$  .Dd $Mdocdate$
 .Dt "Writing Unix Documentation" paper  .Dt manuals 7
 .Os  .Os
   .\" SECTION
 .Sh NAME  .Sh NAME
 .Nm Writing Unix Documentation  .Nm Writing UNIX Documentation
 .Nd a guide to writing Unix manuals  .Nd a guide to writing UNIX manuals
   .\" SECTION
 .Sh DESCRIPTION  .Sh DESCRIPTION
                                         <h1>  .Em A utility without good documentation is of no utility at all .
                                         Writing Unix Documentation  .\" PARAGRAPH
                                         </h1>  .Pp
   A system component's documentation describes the utility of that
   component, whether it's a device driver, an executable or, most
   importantly, a game.  Although there are plenty of documents available
   on how to read
   .Ux
   documents, or where to find them, few focus on composition.
   .\" PARAGRAPH
   .Pp
   This document serves as a tutorial to writing
   .Ux
   documentation
   .Pq Dq manuals .
   If you add something to your operating system, whether it's a new file
   format or directory structure or device driver, it needs documentation.
   .\" SECTION
   .Sh CLASSIFICATION
   Classify your system component.  In
   .Ux ,
   each component has a
   .Dq manual section ,
   which categorises the component's function.  The section of a manual is
   usually listed in parenthesis next to the component name, such as
   .Xr ps 1 ,
   section 1.  You can query a manual explicitly by its section:
   .Pp
   .Dl % man \-s 1 ps
   .Pp
   The following table lists classifications and the applicable manual
   sections:
   .Pp
   .Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact
   .It Em Section
   .Em Description
   .It 1
   operator utilities
   .It 2
   system calls
   .It 3, 3p, 3f
   programming libraries (C, Perl, Fortran)
   .It 5
   file and wire protocol formats
   .It 6
   games
   .It 7
   tutorials, documents and papers
   .It 8
   administrator utilities
   .It 9
   in-kernel routines
   .El
   .Pp
   Some examples in regular name/section form:
   .Pp
   .\" LIST
   .Bl -tag -width "File-formatX" -offset indent -compact
   .It Em Manual
   .Em Description
   .It Xr dc 4
   DEC/Intel 10/100 Ethernet device
   .It Xr usermod 8
   modify user login information
   .It Xr cc 1
   the C compiler
   .It Xr fortune 6
   print a random adage
   .It Xr open 2
   open or create a file for reading or writing
   .It Xr isspace 3
   whitespace character test
   .It Xr Pod::Man 3p
   convert POD data to formatted roff
   .It Xr tsleep 9
   process context sleep
   .It Xr passwd 5
   format of the password file
   .It Xr symlink 7
   symbolic link handling
   .El
   .\" SECTION
   .Sh COMPOSITION
   Prepare your composition environment.
   .\" SUBSECTION
   .Ss Naming
   Your component will need a name by which to query its contents via
   .Xr man 1 .
   Keep it simple.  You may want to look for other manuals by that same
   name before committing:
   .Pp
   .Dl % apropos myname
   .Pp
   Conventionally, manual files are named
   .Pa myname.section ,
   such as
   .Pa manuals.7
   for this document.
   .\" SUBSECTION
   .Ss Input Language
   Manuals should
   .Em always
   be written in the
   .Xr mdoc 7
   formatting language.
   .Pp
   There exist other documentation-specific languages, such as the
   historical
   .Xr me 7 ,
   .Xr ms 7
   and
   .Xr man 7
   packages of
   .Xr roff 7 ;
   newer languages such as DocBook, texinfo or schema-driven XML; or even
   ad-hoc conventions such as README files.
   .Em Stay away from these methods!
   Historical formats fail to capture a manual's semantic content, instead
   only modelling its style.  Newer methods requires special,
   system-specific tools and may change or become obsolete over the
   life-time of your component.
   .Pp
   There are two canonical references for writing mdoc manuals:
   .Pp
   .\" LIST
   .Bl -tag -width XXXXXXXXXXXXXXXX -offset indent -compact
   .It Xr mdoc 7
   formal language reference
   .It Xr mdoc.samples 7
   macro reference
   .El
   .Pp
   Don't merely copy existing manuals!  Most systems distribute an mdoc
   template to help you get started in
   .Pa /usr/share/misc/mdoc.template .
   .\" SUBSECTION
   .Ss Development Tools
   While writing, make sure that your manual is correctly structured:
   .Pp
   .Dl % mandoc \-Tlint \-Wall name.1
   .Pp
   You may spell-check your work as follows:
   .Pp
   .Dl % deroff name.1 | spell
   .Dl % ispell \-n name.1
   .Pp
   Use
   .Xr cvs 1
   or, if not available,
   .Xr rcs 1
   to version-control your work.  If you wish the last check-in to effect
   your document's date, use the following RCS tag for the date macro:
   .Pp
   .Dl \&.Dd $Mdocdate$
   .Pp
   .\" SUBSECTION
   .Ss Viewing
   mdoc documents may be paged to your terminal with traditional
   tools such as
   .Xr nroff 1 ,
   .Xr groff 1 ,
   or with newer, more powerful tools such as
   .Xr mandoc 1 :
   .\" DISPLAY
   .Bd -literal -offset indent
   % nroff \-mandoc name.1 | less
   % groff \-Tascii \-mandoc name.1 | less
   % mandoc name.1 | less
   .Ed
   .Pp
   Other output formats are also supported:
   .\" DISPLAY
   .Bd -literal -offset indent
   % groff \-Tps \-mandoc name.1 | less
   % mandoc \-Thtml name.1 | less
   .Ed
   .\" SUBSECTION
   .Ss Automation
   Consider adding your mdoc documents to
   .Xr make 1
   Makefiles in order to automatically check your input and generate
   output:
   .Bd -literal -offset indent
   \&.SUFFIXES: .html .txt .1 .in
   
                                         <p>  \&.in.1:
                                         <span class="attn">A utility without documentation is of no utility at all.</span>          mandoc -Wall,error -Tlint $<
                                         </p>          cp -f $< $@
   
                                         <p>  \&.1.html:
                                         A system component's documentation describes the utility of that component, whether it's a device          mandoc -Thtml $< >$@
                                         driver, an executable or, most importantly, a game.  Although there are plenty of documents available on  
                                         how to <i>read</i> Unix documents, or where to find them, few focus on how to <i>write</i> them.  
                                         </p>  
   
                                         <p>  \&.1.txt:
                                         This document serves as a reference guide to writing Unix documentation.  If you add something to your          mandoc -Tascii $< | col -b >$@
                                         operating system, whether it's a new file format or directory structure or device driver, it needs  .Ed
                                         documentation.  .\" SECTION
                                         </p>  .Sh BEST PRACTICES
                                 </td>  The
                         </tr>  .Xr mdoc 7
                         <tr>  and
                                 <td>  .Xr mdoc.samples 7
                                         <div class="foot">  files will be indispensable in guiding composition.  In this section, we
                                                 Copyright &#169; 2009 Kristaps D&#382;onsons, $Date$  introduce some
                                         </div>  .Ux
                                 </td>  manual best practices:
                         </tr>  .\" SUBSECTION
                 </tbody>  .Ss Language
         </table>  .Bl -enum
         </body>  .It
 </html>  Use clear, concise language.  Favour simplicity.
   .It
   Write your manual in non-idiomatic English.  Don't worry about
   Commonwealth or American spellings \(em just correct ones.
   .It
   Spell-check your manual, keeping in mind short-letter terms (
   .Xr iwi 4
   vs.
   .Xr iwn 4 ) .
   .It
   If you absolutely must use special characters (diacritics, mathematical
   symbols and so on), use the escapes dictated in
   .Xr mdoc 7 .
   .El
   .\" SUBSECTION
   .Ss References
   Other components may be referenced with the
   .Sq \&Xr ,
   and
   .Sq \&Sx
   macros.  Make sure that these exist.  If you intend to distribute your
   manual, make sure
   .Sq \&Xr
   references are valid across systems (within reason).  If you cross-link with
   .Sq \&Sx ,
   make sure that the section reference exists.
   .\" SUBSECTION
   .Ss Citations
   Cite your work.  If your system references standards documents or other
   publications, please use the
   .Sq \&Rs/Re
   block macros.
   .\" SUBSECTION
   .Ss Formatting
   Let the front-ends worry about formatting for you, but if you must think
   about formatting (at times necessary, especially for tagged and columnar
   lists), assume that your output device is a fixed-width terminal window:
   .Bd -literal -offset indent
   \&.Bl \-tag \-width "-o outfile"
   \&.It \&Fl \&Ar outfile
   .Ed
   .Pp
   You may assume that the width calculated by the string literal
   .Qq Fl o Ar outfile
   will
Legend:
Removed from v.1.1  
changed lines
  Added in v.1.3
CVSweb