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

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

version 1.3, 2009/03/22 14:28:08 version 1.6, 2009/03/22 20:55:18
Line 25  documentation
Line 25  documentation
 If you add something to your operating system, whether it's a new file  If you add something to your operating system, whether it's a new file
 format or directory structure or device driver, it needs documentation.  format or directory structure or device driver, it needs documentation.
 .\" SECTION  .\" SECTION
 .Sh CLASSIFICATION  .Sh COMPOSITION
 Classify your system component.  In  Prepare your composition environment by copying over the manual template
 .Ux ,  from
 each component has a  .Pa /usr/share/misc/mdoc.template .
 .Dq manual section ,  .Em \&Do not
 which categorises the component's function.  The section of a manual is  start afresh or by copying another manual unless you know exactly what
 usually listed in parenthesis next to the component name, such as  you're doing!
 .Xr ps 1 ,  .\" SUBSECTION
 section 1.  You can query a manual explicitly by its section:  .Ss Section Numbering
   Find an appropriate section for your manual.  There may exist multiple
   manual names per section, so be specific.  A table of all available
   manual sections follows:
 .Pp  .Pp
 .Dl % man \-s 1 ps  .\" LIST
 .Pp  
 The following table lists classifications and the applicable manual  
 sections:  
 .Pp  
 .Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact  .Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact
 .It Em Section  .It Em Section
 .Em Description  .Em Description
Line 61  administrator utilities
Line 60  administrator utilities
 in-kernel routines  in-kernel routines
 .El  .El
 .Pp  .Pp
 Some examples in regular name/section form:  If your manual falls into multiple categories, choose the most
 .Pp  widely-used or, better, re-consider the topic of your manual to be more
 .\" LIST  specific.  You can list all manuals per section by invoking
 .Bl -tag -width "File-formatX" -offset indent -compact  .Xr apropos 1 ,
 .It Em Manual  then provide the
 .Em Description  .Fl s
 .It Xr dc 4  flag to
 DEC/Intel 10/100 Ethernet device  .Xr man 1
 .It Xr usermod 8  to see the specific section manual (section 1, in this example):
 modify user login information  .\" DISPLAY
 .It Xr cc 1  .Bd -literal -offset indent
 the C compiler  % apropos myname
 .It Xr fortune 6  myname (1) - some description here
 print a random adage  % man \-s 1 myname
 .It Xr open 2  .Ed
 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  .\" SUBSECTION
 .Ss Naming  .Ss Naming
 Your component will need a name by which to query its contents via  Name your component.  Be terse, erring on the side of clarity.  You may
 .Xr man 1 .  want to look for other manuals by that same name before committing:
 Keep it simple.  You may want to look for other manuals by that same  
 name before committing:  
 .Pp  .Pp
 .Dl % apropos myname  .Dl % apropos myname
 .Pp  .Pp
 Conventionally, manual files are named  Manual files are named
 .Pa myname.section ,  .Pa myname.mysection ,
 such as  such as
 .Pa manuals.7  .Pa manuals.7
 for this document.  for this document.
Line 123  packages of 
Line 105  packages of 
 .Xr roff 7 ;  .Xr roff 7 ;
 newer languages such as DocBook, texinfo or schema-driven XML; or even  newer languages such as DocBook, texinfo or schema-driven XML; or even
 ad-hoc conventions such as README files.  ad-hoc conventions such as README files.
 .Em Stay away from these methods!  .Em Avoid these formats .
 Historical formats fail to capture a manual's semantic content, instead  Historical formats fail to capture a manual's semantic content, instead
 only modelling its style.  Newer methods requires special,  only modelling its style.  Newer methods requires special,
 system-specific tools and may change or become obsolete over the  system-specific tools and may change or become obsolete over the
 life-time of your component.  life-time of your component.
 .Pp  .Pp
 There are two canonical references for writing mdoc manuals:  There are two canonical references for writing mdoc.  Read them.
 .Pp  .Pp
 .\" LIST  .\" LIST
 .Bl -tag -width XXXXXXXXXXXXXXXX -offset indent -compact  .Bl -tag -width XXXXXXXXXXXXXXXX -offset indent -compact
Line 139  formal language reference
Line 121  formal language reference
 macro reference  macro reference
 .El  .El
 .Pp  .Pp
 Don't merely copy existing manuals!  Most systems distribute an mdoc  Open the template you've copied into
 template to help you get started in  .Pa name.section
 .Pa /usr/share/misc/mdoc.template .  and begin editing.
 .\" SUBSECTION  .\" SUBSECTION
 .Ss Development Tools  .Ss Development Tools
 While writing, make sure that your manual is correctly structured:  While writing, make sure that your manual is correctly structured:
Line 161  to version-control your work.  If you wish the last ch
Line 143  to version-control your work.  If you wish the last ch
 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  
 .\" 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 traditional
Line 195  output:
Line 176  output:
 \&.in.1:  \&.in.1:
         mandoc -Wall,error -Tlint $<          mandoc -Wall,error -Tlint $<
         cp -f $< $@          cp -f $< $@
   
 \&.1.html:  \&.1.html:
         mandoc -Thtml $< >$@          mandoc -Thtml $< >$@
   
 \&.1.txt:  \&.1.txt:
         mandoc -Tascii $< | col -b >$@          mandoc -Tascii $< | col -b >$@
 .Ed  .Ed
Line 208  The
Line 187  The
 .Xr mdoc 7  .Xr mdoc 7
 and  and
 .Xr mdoc.samples 7  .Xr mdoc.samples 7
 files will be indispensable in guiding composition.  In this section, we  files are indispensable in guiding composition.  In this section, we
 introduce some  introduce some
 .Ux  .Ux
 manual best practices:  manual best practices:
Line 233  symbols and so on), use the escapes dictated in
Line 212  symbols and so on), use the escapes dictated in
 .\" SUBSECTION  .\" SUBSECTION
 .Ss References  .Ss References
 Other components may be referenced with the  Other components may be referenced with the
 .Sq \&Xr ,  .Sq \&Xr
 and  and
 .Sq \&Sx  .Sq \&Sx
 macros.  Make sure that these exist.  If you intend to distribute your  macros.  Make sure that these exist.  If you intend to distribute your
Line 250  publications, please use the
Line 229  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  .\" SECTION
 \&.Bl \-tag \-width "-o outfile"  .Sh MAINTENANCE
 \&.It \&Fl \&Ar outfile  As your component changes and bugs are fixed, your manual may become out
 .Ed  of date.  You may be tempted to use automation tools like Doxygen to
 .Pp  smooth the development of your manuals.  Don't.  Source documentation is
 You may assume that the width calculated by the string literal  different from a component manual.
 .Qq Fl o Ar outfile  
 will  
Legend:
Removed from v.1.3  
changed lines
  Added in v.1.6
CVSweb