===================================================================
RCS file: /cvs/mandoc/man.7,v
retrieving revision 1.40
retrieving revision 1.43
diff -u -p -r1.40 -r1.43
--- mandoc/man.7	2009/10/24 05:45:04	1.40
+++ mandoc/man.7	2009/11/02 06:22:45	1.43
@@ -1,4 +1,4 @@
-.\"	$Id: man.7,v 1.40 2009/10/24 05:45:04 kristaps Exp $
+.\"	$Id: man.7,v 1.43 2009/11/02 06:22:45 kristaps Exp $
 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
 .\"
@@ -14,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: October 24 2009 $
+.Dd $Mdocdate: November 2 2009 $
 .Dt MAN 7
 .Os
 .
@@ -119,8 +119,25 @@ from input.  These are later re-added, if applicable, 
 utility such as
 .Xr mandoc 1 .
 .
+.Ss Dates
+The
+.Sx \&TH
+macro is the only
+.Nm
+macro that requires a date.  The form for this date is the ISO-8601
+standard
+.Cm YYYY-MM-DD .
+.
 .Ss Scaling Widths
 Many macros support scaled widths for their arguments, such as
+stipulating a two-inch list indentation with the following:
+.Bd -literal -offset indent
+\&.Bl -tag -width 2i
+.Ed
+.
+.
+.Ss Scaling Widths
+Many macros support scaled widths for their arguments, such as
 stipulating a two-inch paragraph indentation with the following:
 .Bd -literal -offset indent
 \&.HP 2i
@@ -202,7 +219,7 @@ Beyond
 at least one macro or text node must appear in the document.  Documents
 are generally structured as follows:
 .Bd -literal -offset indent
-\&.TH FOO 1 "13 Aug 2009"
+\&.TH FOO 1 2009-10-10
 \&.
 \&.SH NAME
 \efBfoo\efR \e(en a description goes here
@@ -229,7 +246,7 @@ 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
@@ -237,8 +254,130 @@ 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
 Macros are one to three three characters in length and begin with a
 control character ,
@@ -492,26 +631,29 @@ subsequent sub-section, section, or end of file.  The 
 left-margin width is re-set to the default.
 .Ss \&TH
 Sets the title of the manual page with the following syntax:
-.Bd -literal -offset indent
-\&.TH title section [date [source [volume]]]
-.Ed
-.
 .Pp
-At least the 
-.Va title
-and
-.Va section
+.D1 \. Ns Sx \&TH No Cm title msec Op Cm date Op Cm src Op Cm vol
+.Pp
+At least the upper-case document title
+.Cm title
+and numeric manual section
+.Cm msec
 arguments must be provided.  The
-.Va date
-argument should be formatted as
-.Qq %b [%d] %Y
-format, described in
-.Xr strptime 3 .
-The
-.Va source
+.Cm date
+argument should be formatted as described in
+.Sx Dates :
+if it does not conform, the current date is used instead.  The
+.Cm src
 string specifies the organisation providing the utility.  The
-.Va volume
-replaces the default rendered volume as dictated by the manual section.
+.Cm vol
+string replaces the default rendered volume, which is dictated by the
+manual section.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.TH CVS 5 "1992-02-12" GNU
+.Ed
+.
 .Ss \&TP
 Begin a paragraph where the head, if exceeding the indentation width, is
 followed by a newline; if not, the body follows on the same line after a