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

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

version 1.2, 2009/03/22 14:09:38 version 1.4, 2009/03/22 14:35:16
Line 28  format or directory structure or device driver, it nee
Line 28  format or directory structure or device driver, it nee
 .Sh CLASSIFICATION  .Sh CLASSIFICATION
 Classify your system component.  In  Classify your system component.  In
 .Ux ,  .Ux ,
 each component has a  each component has a manual section , which categorises the component's
 .Dq manual section ,  function.  The section of a manual is usually listed in parenthesis next
 which categorises the component's function.  The section of a manual is  to the component name, such as
 usually listed in parenthesis next to the component name, such as  
 .Xr ps 1 ,  .Xr ps 1 ,
 section 1.  You can query a manual explicitly by its section:  section 1.  You can query a manual explicitly by its section:
   .Bd -literal -offset XXXX
   % man \-s 1 ps
   % apropos ps
   .Ed
 .Pp  .Pp
 .Dl % man \-s 1 ps  The following table lists classifications and the applicable manual
   sections:
 .Pp  .Pp
 The following table lists broad classifications and the applicable  
 manual sections:  
 .Pp  
 .\" LIST  
 .Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact  .Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact
 .It Em Category  
 .Em Section(s)  
 .It Device  
 4  
 .It Executable  
 1, 6, 8  
 .It Function  
 2, 3, 9  
 .It File-format  
 5  
 .It Other  
 7  
 .El  
 .\" SUBSECTION  
 .Ss Devices  
 Consists of hardware (and pseudo-) device driver documentation.  Drivers  
 are unilaterally classified in section 4.  
 .Em Note :  
 these manuals are necessarily system- and architecture-specific.  
 .Pp  
 Example:  
 .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  
 .El  
 .\" SUBSECTION  
 .Ss Executables  
 Executables consist of runnable binaries.  They're further classified by  
 operator utility:  
 .Pp  
 .\" LIST  
 .Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact  
 .It Em Section  .It Em Section
 .Em Description  .Em Description
 .It 1  .It 1
 operator utilities  operator utilities
 .It 8  .It 2
 administrator utilities  system calls
   .It 3, 3p, 3f
   programming libraries (C, Perl, Fortran)
   .It 5
   file and wire protocol formats
 .It 6  .It 6
 games  games
   .It 7
   tutorials, documents and papers
   .It 8
   administrator utilities
   .It 9
   in-kernel routines
 .El  .El
 .Pp  .Pp
 Examples:  Some examples in regular name/section form:
 .Pp  .Pp
 .\" LIST  .\" LIST
 .Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact  .Bl -tag -width "File-formatX" -offset indent -compact
 .It Em Manual  .It Em Manual
 .Em Description  .Em Description
   .It Xr dc 4
   DEC/Intel 10/100 Ethernet device
 .It Xr usermod 8  .It Xr usermod 8
 modify user login information  modify user login information
 .It Xr cc 1  .It Xr cc 1
 the C compiler  the C compiler
 .It Xr fortune 6  .It Xr fortune 6
 print a random adage  print a random adage
 .El  
 .\" SUBSECTION  
 .Ss Functions  
 Function documentation describes programme source code, whether in the  
 form of libraries, modules or standalone sources.  They're further  
 classified by context:  
 .Pp  
 .\" LIST  
 .Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact  
 .It Em Section  
 .Em Description  
 .It 2  
 system calls  
 .It 3, 3p, 3f  
 programming libraries (C, Perl, Fortran)  
 .It 9  
 in-kernel routines  
 .El  
 .Pp  
 .Em Note :  
 section 2 and 9 manuals are necessarily system- and often  
 architecture-specific.  Examples:  
 .Pp  
 .\" LIST  
 .Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact  
 .It Em Manual  
 .Em Description  
 .It Xr open 2  .It Xr open 2
 open or create a file for reading or writing  open or create a file for reading or writing
 .It Xr isspace 3  .It Xr isspace 3
Line 135  whitespace character test
Line 84  whitespace character test
 convert POD data to formatted roff  convert POD data to formatted roff
 .It Xr tsleep 9  .It Xr tsleep 9
 process context sleep  process context sleep
 .El  
 .\" SUBSECTION  
 .Ss File-formats  
 A file format usually describes the format of on-disc binary or text  
 data, although it can also be used to describe wire protocols (this is  
 usually best left to RFC).  These manuals are unilaterally classified in  
 section 5.  
 .Pp  
 Example:  
 .Pp  
 .\" LIST  
 .Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact  
 .It Em Manual  
 .Em Description  
 .It Xr passwd 5  .It Xr passwd 5
 format of the password file  format of the password file
 .El  
 .\" SUBSECTION  
 .Ss Other  
 Documents with no other classification are relegated to section 7.  This  
 constitutes reference tutorials (such as this document) and other  
 miscellaneous information.  
 .Pp  
 Examples:  
 .Pp  
 .\" LIST  
 .Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact  
 .It Em Manual  
 .Em Description  
 .It Xr ascii 7  
 ASCII character sets  
 .It Xr symlink 7  .It Xr symlink 7
 symbolic link handling  symbolic link handling
 .El  .El
 .\" SECTION  .\" SECTION
 .Sh COMPOSITION  .Sh COMPOSITION
 Prepare your composition environment.  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  Your component will need a name by which to query its contents via
Line 220  formal language reference
Line 145  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 242  to version-control your work.  If you wish the last ch
Line 167  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 289  The
Line 213  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 330  publications, please use the
Line 254  publications, please use the
 .Sq \&Rs/Re  .Sq \&Rs/Re
 block macros.  block macros.
 .\" SUBSECTION  .\" SUBSECTION
 .Ss Types and Prototypes  .Ss Formatting
 If writing section 3 manuals, make sure that you correctly annotate your  Let the front-ends worry about formatting for you, but if you must think
 variables and functions.  This guarantees that cross-referncing between  about formatting (at times necessary, especially for tagged and columnar
 function names and their prototypes works properly.  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 be covered by the \-width argument.
Legend:
Removed from v.1.2  
changed lines
  Added in v.1.4
CVSweb