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

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

version 1.4, 2009/03/22 14:35:16 version 1.5, 2009/03/22 19:01:11
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 manual section , which categorises the component's  .Pa /usr/share/misc/mdoc.template .
 function.  The section of a manual is usually listed in parenthesis next  .Em \&Do not
 to the component name, such as  start afresh or by copying another manual unless you know exactly what
 .Xr ps 1 ,  you're doing!
 section 1.  You can query a manual explicitly by its section:  .\" SUBSECTION
 .Bd -literal -offset XXXX  .Ss Section Numbering
 % man \-s 1 ps  Find an appropriate section for your manual.  There may exist multiple
 % apropos ps  manual names per section, so be specific.  A table of all available
 .Ed  manual sections follows:
 .Pp  .Pp
 The following table lists classifications and the applicable manual  .\" LIST
 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 62  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 by copying over the manual template  
 from  
 .Pa /usr/share/misc/mdoc.template .  
 .Em \&Do not  
 start afresh or by copying another manual unless you know exactly what  
 you're doing!  
 .\" 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 129  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 200  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 238  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 266  lists), assume that your output device is a fixed-widt
Line 240  lists), assume that your output device is a fixed-widt
 You may assume that the width calculated by the string literal  You may assume that the width calculated by the string literal
 .Qq Fl o Ar outfile  .Qq Fl o Ar outfile
 will be covered by the \-width argument.  will be covered by the \-width argument.
   .\" SECTION
   .Sh MAINTENANCE
   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
   smooth the development of your manuals.  Don't.  Source documentation is
   different from a component manual.
Legend:
Removed from v.1.4  
changed lines
  Added in v.1.5
CVSweb