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

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

version 1.9, 2009/03/24 10:59:50 version 1.10, 2009/03/26 23:01:26
Line 30 
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
Line 55  you're doing!
Line 49  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 98  myname (3) - library description
Line 91  myname (3) - library description
 .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 121  historical
Line 114  historical
 .Xr man 7  .Xr man 7
 package 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 155  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:
 .Pp  .Pp
 .Dl \&.Dd $Mdocdate$  .Dl \&.Dd $Mdocdate$
 .Pp  
 If using version control, the first line in your manual should be a  
 comment with the  
 .Li $Id$  
 rcs tag.  
 .\" 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  .\" SUBSECTION
 .Ss Licensing  .Ss Licensing
Line 242  The structure of the mdoc language makes it very hard 
Line 211  The structure of the mdoc language makes it very hard 
 particular format style.  Keep your lines under 72 characters in length.  particular format style.  Keep your lines under 72 characters in length.
 If you must have long option lines, use  If you must have long option lines, use
 .Sq \&Oo/Oc .  .Sq \&Oo/Oc .
   The same goes for function prototypes.
 .Em \&Do not  .Em \&Do not
 use  use
 .Sq \&Xo/Xc ;  .Sq \&Xo/Xc .
 instead, either fine another way to write long lines, or, at the  Find another way to structure your line.
 absolute worst, use CPP-style newline escapes.  
 .\" SUBSECTION  .\" SUBSECTION
 .Ss References  .Ss References
 Other components may be referenced with the  Other components may be referenced with the
Line 267  publications, please use the
Line 236  publications, please use the
 block macros.  block macros.
 .\" SUBSECTION  .\" SUBSECTION
 .Ss Formatting  .Ss Formatting
 .Em Don't style your manual.  .Em Don't style your manual .
 Give it meaningful content.  The front-end will worry about formatting  Give it meaningful content.  The front-end will worry about formatting
 and style.  and style.
 .\" SECTION  .\" SECTION
Legend:
Removed from v.1.9  
changed lines
  Added in v.1.10
CVSweb