mandoc/man.7 - diff

Return to man.7 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/man.7 between version 1.40 and 1.42

-version 1.40, 2009/10/24 05:45:04
+version 1.42, 2009/10/31 08:37:26
 Line 229  The \efBfoo\efR utility processes files...
 Line 229  The \efBfoo\efR utility processes files...
 Line 229  The \efBfoo\efR utility processes files...
  \&.\e\*q The next is for sections 2, 3, & 9 only.
  \&.\e\*q .SH ERRORS
  \&.\e\*q .SH SEE ALSO
- \&.\e\*q \efBbar\efR(1)
+ \&.\e\*q .BR foo ( 1 )
  \&.\e\*q .SH STANDARDS
  \&.\e\*q .SH HISTORY
  \&.\e\*q .SH AUTHORS
 Line 237  The \efBfoo\efR utility processes files...
 Line 237  The \efBfoo\efR utility processes files...
 Line 237  The \efBfoo\efR utility processes files...
  \&.\e\*q .SH BUGS
  \&.\e\*q .SH SECURITY CONSIDERATIONS
  .Ed
+ .Pp
+ The sections in a
+ .Nm
+ document are conventionally ordered as they appear above.  Sections
+ should be composed as follows:
+ .Bl -ohang -offset indent
+ .It Em NAME
+ The name(s) and a short description of the documented material.  The
+ syntax for this is generally as follows:
+ .Pp
+ .D1 \efBname\efR \e(en description
+ .It Em LIBRARY
+ The name of the library containing the documented material, which is
+ assumed to be a function in a section 2 or 3 manual.  For functions in
+ the C library, this may be as follows:
+ .Pp
+ .D1 Standard C Library (libc, -lc)
+ .It Em SYNOPSIS
+ Documents the utility invocation syntax, function call syntax, or device
+ configuration.
+ .Pp
+ For the first, utilities (sections 1, 6, and 8), this is
+ generally structured as follows:
+ .Pp
+ .D1 \efBname\efR [-\efBab\efR] [-\efBc\efR\efIarg\efR] \efBpath\efR...
+ .Pp
+ For the second, function calls (sections 2, 3, 9):
+ .Pp
+ .D1 \. Ns Sx \&B No char *name(char *\efIarg\efR);
+ .Pp
+ And for the third, configurations (section 4):
+ .Pp
+ .D1 \. Ns Sx \&B No name* at cardbus ? function ?
+ .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).
+ .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.
+ .
+ .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.
+ .
+ .It Em ENVIRONMENT
+ Documents any usages of environment variables, e.g.,
+ .Xr environ 7 .
+ .
+ .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.).
+ .
+ .It Em EXAMPLES
+ Example usages.  This often contains snippets of well-formed,
+ well-tested invocations.  Make doubly sure that your examples work
+ properly!  Assume that users will skip to this section and use your
+ example verbatim.
+ .
+ .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.
+ .
+ .It Em ERRORS
+ Documents error handling in sections 2, 3, and 9.
+ .
+ .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
+ .D1 \. Ns Sx \&BR No bar \&( 1 \&),
+ .D1 \. Ns Sx \&BR No foo \&( 1 \&),
+ .D1 \. Ns Sx \&BR No baz \&( 2 \&).
+ .
+ .It Em STANDARDS
+ References any standards implemented or used, such as
+ .Pp
+ .D1 IEEE Std 1003.2 (\e(lqPOSIX.2\e(rq)
+ .Pp
+ If not adhering to any standards, the
+ .Em HISTORY
+ section should be used.
+ .
+ .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.
+ .
+ .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
  .
  .
  .Sh MACRO SYNTAX

CVSweb