===================================================================
RCS file: /cvs/mandoc/man.7,v
retrieving revision 1.97
retrieving revision 1.102
diff -u -p -r1.97 -r1.102
--- mandoc/man.7	2011/01/25 00:40:14	1.97
+++ mandoc/man.7	2011/07/08 09:35:06	1.102
@@ -1,4 +1,4 @@
-.\"	$Id: man.7,v 1.97 2011/01/25 00:40:14 schwarze Exp $
+.\"	$Id: man.7,v 1.102 2011/07/08 09:35:06 kristaps Exp $
 .\"
 .\" Copyright (c) 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv>
 .\"
@@ -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: January 25 2011 $
+.Dd $Mdocdate: July 8 2011 $
 .Dt MAN 7
 .Os
 .Sh NAME
@@ -118,15 +118,6 @@ rendered as an empty line.
 .Pp
 In macro lines, whitespace delimits arguments and is discarded.
 If arguments are quoted, whitespace within the quotes is retained.
-.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 paragraph indentation with the following:
@@ -214,16 +205,20 @@ appears as the first macro.
 Beyond
 .Sx \&TH ,
 at least one macro or text node must appear in the document.
-Documents are generally structured as follows:
+.Pp
+The following is a well-formed skeleton
+.Nm
+file for a utility
+.Qq progname :
 .Bd -literal -offset indent
-\&.TH FOO 1 2009-10-10
+\&.TH PROGNAME 1 2009-10-10
 \&.SH NAME
-\efBfoo\efR \e(en a description goes here
+\efBprogname\efR \e(en a description goes here
 \&.\e\*q .SH LIBRARY
 \&.\e\*q For sections 2 & 3 only.
 \&.\e\*q Not used in OpenBSD.
 \&.SH SYNOPSIS
-\efBfoo\efR [\efB\e-options\efR] arguments...
+\efBprogname\efR [\efB\e-options\efR] arguments...
 \&.SH DESCRIPTION
 The \efBfoo\efR utility processes files...
 \&.\e\*q .SH IMPLEMENTATION NOTES
@@ -712,6 +707,9 @@ and
 .Ss \&RE
 Explicitly close out the scope of a prior
 .Sx \&RS .
+The default left margin is restored to the state of the original
+.Sx \&RS
+invocation.
 .Ss \&RI
 Text is rendered alternately in roman (the default font) and italics.
 Whitespace between arguments is omitted in output.
@@ -728,13 +726,10 @@ See also
 and
 .Sx \&IR .
 .Ss \&RS
-Begin a part setting the left margin.
-The left margin controls the offset, following an initial indentation,
-to un-indented text such as that of
-.Sx \&PP .
+Temporarily reset the default left margin.
 This has the following syntax:
 .Bd -filled -offset indent
-.Pf \. Sx \&Rs
+.Pf \. Sx \&RS
 .Op Cm width
 .Ed
 .Pp
@@ -743,6 +738,9 @@ The
 argument must conform to
 .Sx Scaling Widths .
 If not specified, the saved or default width is used.
+.Pp
+See also
+.Sx \&RE .
 .Ss \&SB
 Text is rendered in small size (one point smaller than the default font)
 bold face.
@@ -763,26 +761,27 @@ The paragraph left-margin width is reset to the defaul
 Sets the title of the manual page with the following syntax:
 .Bd -filled -offset indent
 .Pf \. Sx \&TH
-.Cm title section
-.Op Cm date Op Cm source Op Cm volume
+.Ar title section date
+.Op Ar source Op Ar volume
 .Ed
 .Pp
-At least the upper-case document
-.Cm title
-and the manual
-.Cm section
-arguments must be provided.
-The
-.Cm date
-argument should be formatted as described in
-.Sx Dates ,
-but will be printed verbatim if it is not.
-If the date is not specified, the current date is used.
-The
-.Cm source
+Conventionally, the document
+.Ar title
+is given in all caps.
+The recommended
+.Ar date
+format is
+.Sy YYYY-MM-DD
+as specified in the ISO-8601 standard;
+if the argument does not conform, it is printed verbatim.
+If the
+.Ar date
+is empty or not specified, the current date is used.
+The optional
+.Ar source
 string specifies the organisation providing the utility.
 The
-.Cm volume
+.Ar volume
 string replaces the default rendered volume, which is dictated by the
 manual section.
 .Pp
@@ -849,6 +848,10 @@ Begin literal mode: all subsequent free-form lines hav
 line boundaries preserved.
 May be ended by
 .Sx \&fi .
+Literal mode is implicitly ended by
+.Sx \&SH
+or
+.Sx \&SS .
 .Ss \&sp
 Insert vertical spaces into output with the following syntax:
 .Bd -filled -offset indent
@@ -919,6 +922,7 @@ In GNU troff, this would result in strange behaviour.
 .Sh SEE ALSO
 .Xr man 1 ,
 .Xr mandoc 1 ,
+.Xr eqn 7 ,
 .Xr mandoc_char 7 ,
 .Xr mdoc 7 ,
 .Xr roff 7 ,