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

Diff for /mandoc/mdoc.7 between version 1.72 and 1.73

version 1.72, 2009/11/02 06:22:45 version 1.73, 2009/11/02 11:39:40
Line 363  The sections in a
Line 363  The sections in a
 .Nm  .Nm
 document are conventionally ordered as they appear above.  Sections  document are conventionally ordered as they appear above.  Sections
 should be composed as follows:  should be composed as follows:
 .Bl -tag -width Ds -offset Ds  .Bl -ohang -offset Ds
 .It NAME  .It Em NAME
 Must contain at least one  The name(s) and a short description of the documented material.  The
   syntax for this as follows:
   .Bd -literal -offset indent
   \&.Nm name0
   \&.Nm name1
   \&.Nm name2
   \&.Nd a short description
   .Ed
   .Pp
   The
 .Sx \&Nm  .Sx \&Nm
 followed by  macro(s) must precede the
 .Sx \&Nd .  .Sx \&Nd
 The name needs re-stating since one  macro.
 .Nm  .
 documents can be used for more than one utility or function, such as  .It Em LIBRARY
 .Xr grep 1  The name of the library containing the documented material, which is
 also being referenced as  assumed to be a function in a section 2 or 3 manual.  The syntax for
 .Xr egrep 1  this is as follows:
 and  .Bd -literal -offset indent
 .Xr fgrep 1 .  \&.Lb libarm
 .It LIBRARY  .Ed
 .It SYNOPSIS  .Pp
 .It DESCRIPTION  See
 .It IMPLEMENTATION NOTES  .Sx \&Lb
 .It EXIT STATUS  for details.
 .It RETURN VALUES  .
 .It ENVIRONMENT  .It Em SYNOPSIS
 .It FILES  Documents the utility invocation syntax, function call syntax, or device
 .It EXAMPLES  configuration.
 .It DIAGNOSTICS  .Pp
 .It ERRORS  For the first, utilities (sections 1, 6, and 8), this is
 .It SEE ALSO  generally structured as follows:
 .It STANDARDS  .Bd -literal -offset indent
 .It HISTORY  \&.Nm foo
 .It AUTHORS  \&.Op Fl v
 .It CAVEATS  \&.Op Fl o Ar file
 .It BUGS  \&.Op Ar
 .It SECURITY CONSIDERATIONS  \&.Nm bar
   \&.Op Fl v
   \&.Op Fl o Ar file
   \&.Op Ar
   .Ed
   .Pp
   For the second, function calls (sections 2, 3, 9):
   .Bd -literal -offset indent
   \&.Vt extern const char *global;
   \&.In header.h
   \&.Ft "char *"
   \&.Fn foo "const char *src"
   \&.Ft "char *"
   \&.Fn bar "const char *src"
   .Ed
   .Pp
   And for the third, configurations (section 4):
   .Bd -literal -offset indent
   \&.Cd \*qit* at isa? port 0x2e\*q
   \&.Cd \*qit* at isa? port 0x4e\*q
   .Ed
   .Pp
   Manuals not in these sections generally don't need a
   .Em SYNOPSIS .
   .
   .It Em DESCRIPTION
   This expands upon the brief, one-line description in
   .Em NAME .
   It usually contains a break-down of the options (if documenting a
   command), such as:
   .Bd -literal -offset indent
   The arguments are as follows:
   \&.Bl \-tag \-width Ds
   \&.It Fl v
   Print verbose information.
   \&.El
   .Ed
   Manuals not documenting a command won't include the above fragment.
   .
   .It Em IMPLEMENTATION NOTES
   Implementation-specific notes should be kept here.  This is useful when
   implementing standard functions that may have side effects or notable
   algorithmic implications.
   .
   .It Em EXIT STATUS
   Command exit status for section 1, 6, and 8 manuals.  This section is
   the dual of
   .Em RETURN VALUES ,
   which is used for functions.  Historically, this information was
   described in
   .Em DIAGNOSTICS ,
   a practise that is now discouraged.
   .Pp
   See
   .Sx \&Ex .
   .
   .It Em RETURN VALUES
   This section is the dual of
   .Em EXIT STATUS ,
   which is used for commands.  It documents the return values of functions
   in sections 2, 3, and 9.
   .Pp
   See
   .Sx \&Rv .
   .
   .It Em ENVIRONMENT
   Documents any usages of environment variables, e.g.,
   .Xr environ 7 .
   .Pp
   See
   .Sx \&Ev .
   .
   .It Em FILES
   Documents files used.  It's helpful to document both the file and a
   short description of how the file is used (created, modified, etc.).
   .Pp
   See
   .Sx \&Pa .
   .
   .It Em EXAMPLES
   Example usages.  This often contains snippets of well-formed,
   well-tested invocations.  Make doubly sure that your examples work
   properly!
   .
   .It Em DIAGNOSTICS
   Documents error conditions.  This is most useful in section 4 manuals.
   Historically, this section was used in place of
   .Em EXIT STATUS
   for manuals in sections 1, 6, and 8; however, this practise is
   discouraged.
   .Pp
   See
   .Sx \&Bl No \-diag .
   .
   .It Em ERRORS
   Documents error handling in sections 2, 3, and 9.
   .Pp
   See
   .Sx \&Er .
   .
   .It Em SEE ALSO
   References other manuals with related topics.  This section should exist
   for most manuals.  Cross-references should conventionally be ordered
   first by section, then alphabetically.
   .Pp
   See
   .Sx \&Xr .
   .
   .It Em STANDARDS
   References any standards implemented or used.  If not adhering to any
   standards, the
   .Em HISTORY
   section should be used instead.
   .Pp
   See
   .Sx \&St .
   .
   .It Em HISTORY
   The history of any manual without a
   .Em STANDARDS
   section should be described in this section.
   .
   .It Em AUTHORS
   Credits to authors, if applicable, should appear in this section.
   Authors should generally be noted by both name and an e-mail address.
   .Pp
   See
   .Sx \&An .
   .
   .It Em CAVEATS
   Explanations of common misuses and misunderstandings should be explained
   in this section.
   .
   .It Em BUGS
   Extant bugs should be described in this section.
   .
   .It Em SECURITY CONSIDERATIONS
   Documents any security precautions that operators should consider.
   .
 .El  .El
 .  .
 .  .
Legend:
Removed from v.1.72  
changed lines
  Added in v.1.73
CVSweb