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

Diff for /mandoc/Attic/manuals.7 between version 1.5 and 1.10

version 1.5, 2009/03/22 19:01:11 version 1.10, 2009/03/26 23:01:26
Line 1 
Line 1 
   .\" $Id$
   .\"
   .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org>
   .\"
   .\" Permission to use, copy, modify, and distribute this software for any
   .\" purpose with or without fee is hereby granted, provided that the
   .\" above copyright notice and this permission notice appear in all
   .\" copies.
   .\"
   .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
   .\" WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
   .\" WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
   .\" AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
   .\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
   .\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
   .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
   .\" PERFORMANCE OF THIS SOFTWARE.
   .\"
 .Dd $Mdocdate$  .Dd $Mdocdate$
 .Dt manuals 7  .Dt manuals 7
 .Os  .Os
Line 12 
Line 30 
 .Pp  .Pp
 A system component's documentation describes the utility of that  A system component's documentation describes the utility of that
 component, whether it's a device driver, an executable or, most  component, whether it's a device driver, an executable or, most
 importantly, a game.  Although there are plenty of documents available  importantly, a game.
 on how to read  
 .Ux  
 documents, or where to find them, few focus on composition.  
 .\" PARAGRAPH  
 .Pp  .Pp
 This document serves as a tutorial to writing  This document serves as a tutorial to writing
 .Ux  .Ux
 documentation  documentation
 .Pq Dq manuals .  .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  .\" SECTION
 .Sh COMPOSITION  .Sh COMPOSITION
 Prepare your composition environment by copying over the manual template  Prepare your composition environment by copying over the manual template
 from  from
 .Pa /usr/share/misc/mdoc.template .  .Pa /usr/share/misc/mdoc.template .
   .Pp
   If this file doesn't exist, bug your administrator.
 .Em \&Do not  .Em \&Do not
 start afresh or by copying another manual unless you know exactly what  start afresh or by copying another manual unless you know exactly what
 you're doing!  you're doing!
 .\" SUBSECTION  .\" SUBSECTION
 .Ss Section Numbering  .Ss Section Numbering
 Find an appropriate section for your manual.  There may exist multiple  Find an appropriate section for your manual.  There may exist multiple
 manual names per section, so be specific.  A table of all available  manual names per section, so be specific:
 manual sections follows:  
 .Pp  .Pp
 .\" LIST  .\" LIST
 .Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact  .Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact
Line 72  to see the specific section manual (section 1, in this
Line 85  to see the specific section manual (section 1, in this
 .\" DISPLAY  .\" DISPLAY
 .Bd -literal -offset indent  .Bd -literal -offset indent
 % apropos myname  % apropos myname
 myname (1) - some description here  myname (1) - utility description
   myname (3) - library description
 % man \-s 1 myname  % man \-s 1 myname
 .Ed  .Ed
 .\" SUBSECTION  .\" SUBSECTION
 .Ss Naming  .Ss Naming
 Name your component.  Be terse, erring on the side of clarity.  You may  Name your component.  Be terse, erring on the side of clarity.  Look for
 want to look for other manuals by that same name before committing:  other manuals by that same name before committing:
 .Pp  .Pp
 .Dl % apropos myname  .Dl % apropos myname
 .Pp  .Pp
Line 97  formatting language.
Line 111  formatting language.
 .Pp  .Pp
 There exist other documentation-specific languages, such as the  There exist other documentation-specific languages, such as the
 historical  historical
 .Xr me 7 ,  
 .Xr ms 7  
 and  
 .Xr man 7  .Xr man 7
 packages of  package of
 .Xr roff 7 ;  .Xr roff 7 ;
 newer languages such as DocBook, texinfo or schema-driven XML; or even  newer languages such as DocBook or texinfo; or even ad-hoc conventions
 ad-hoc conventions such as README files.  such as README files.
 .Em Avoid these formats .  .Em Avoid these formats .
 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  .Pp
 There are two canonical references for writing mdoc.  Read them.  There are two canonical references for writing mdoc.  Read them.
 .Pp  .Pp
Line 137  You may spell-check your work as follows:
Line 144  You may spell-check your work as follows:
 .Pp  .Pp
 Use  Use
 .Xr cvs 1  .Xr cvs 1
 or, if not available,  or
 .Xr rcs 1  .Xr rcs 1
 to version-control your work.  If you wish the last check-in to effect  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:  your document's date, use the following RCS tag for the date macro:
Line 145  your document's date, use the following RCS tag for th
Line 152  your document's date, use the following RCS tag for th
 .Dl \&.Dd $Mdocdate$  .Dl \&.Dd $Mdocdate$
 .\" SUBSECTION  .\" SUBSECTION
 .Ss Viewing  .Ss Viewing
 mdoc documents may be paged to your terminal with traditional  mdoc documents may be paged to your terminal with
 tools such as  .Xr mandoc 1 .
 .Xr nroff 1 ,  If you plan on distributing your work to systems without this tool,
 .Xr groff 1 ,  check it against
 or with newer, more powerful tools such as  .Xr groff 1 :
 .Xr mandoc 1 :  
 .\" DISPLAY  
 .Bd -literal -offset indent  .Bd -literal -offset indent
 % nroff \-mandoc name.1 | less  % mandoc \-Wall name.1 2>&1 | less
 % groff \-Tascii \-mandoc name.1 | less  % groff -mandoc name.1 2>&1 | less
 % mandoc name.1 | less  
 .Ed  .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  .\" SUBSECTION
 .Ss Automation  .Ss Automation
 Consider adding your mdoc documents to  Consider adding your mdoc documents to
 .Xr make 1  .Xr make 1
 Makefiles in order to automatically check your input and generate  Makefiles in order to automatically check your input:
 output:  
 .Bd -literal -offset indent  .Bd -literal -offset indent
 \&.SUFFIXES: .html .txt .1 .in  \&.SUFFIXES: .1 .in
   
 \&.in.1:  \&.in.1:
         mandoc -Wall,error -Tlint $<          mandoc -Wall,error -Tlint $<
         cp -f $< $@          cp -f $< $@
 \&.1.html:  
         mandoc -Thtml $< >$@  
 \&.1.txt:  
         mandoc -Tascii $< | col -b >$@  
 .Ed  .Ed
   .\" SUBSECTION
   .Ss Licensing
   Your manual must have a license.  It should be listed at the start of
   your document, just as in source code.
 .\" SECTION  .\" SECTION
 .Sh BEST PRACTICES  .Sh BEST PRACTICES
 The  The
Line 210  symbols and so on), use the escapes dictated in
Line 206  symbols and so on), use the escapes dictated in
 .Xr mdoc 7 .  .Xr mdoc 7 .
 .El  .El
 .\" SUBSECTION  .\" SUBSECTION
   .Ss Style
   The structure of the mdoc language makes it very hard to have any
   particular format style.  Keep your lines under 72 characters in length.
   If you must have long option lines, use
   .Sq \&Oo/Oc .
   The same goes for function prototypes.
   .Em \&Do not
   use
   .Sq \&Xo/Xc .
   Find another way to structure your line.
   .\" SUBSECTION
 .Ss References  .Ss References
 Other components may be referenced with the  Other components may be referenced with the
 .Sq \&Xr  .Sq \&Xr
Line 229  publications, please use the
Line 236  publications, please use the
 block macros.  block macros.
 .\" SUBSECTION  .\" SUBSECTION
 .Ss Formatting  .Ss Formatting
 Let the front-ends worry about formatting for you, but if you must think  .Em Don't style your manual .
 about formatting (at times necessary, especially for tagged and columnar  Give it meaningful content.  The front-end will worry about formatting
 lists), assume that your output device is a fixed-width terminal window:  and style.
 .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 be covered by the \-width argument.  
 .\" SECTION  .\" SECTION
 .Sh MAINTENANCE  .Sh MAINTENANCE
 As your component changes and bugs are fixed, your manual may become out  As your component changes and bugs are fixed, your manual may become out
 of date.  You may be tempted to use automation tools like Doxygen to  of date.  You may be tempted to use automation tools like Doxygen to
 smooth the development of your manuals.  Don't.  Source documentation is  smooth the development of your manuals.  Don't.  Source documentation is
 different from a component manual.  different from a component manual.
Legend:
Removed from v.1.5  
changed lines
  Added in v.1.10
CVSweb