===================================================================
RCS file: /cvs/mandoc/mdoc.7,v
retrieving revision 1.232
retrieving revision 1.234
diff -u -p -r1.232 -r1.234
--- mandoc/mdoc.7	2014/07/13 10:24:40	1.232
+++ mandoc/mdoc.7	2014/08/08 16:38:06	1.234
@@ -1,4 +1,4 @@
-.\"	$Id: mdoc.7,v 1.232 2014/07/13 10:24:40 schwarze Exp $
+.\"	$Id: mdoc.7,v 1.234 2014/08/08 16:38:06 schwarze Exp $
 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2010, 2011, 2013 Ingo Schwarze <schwarze@openbsd.org>
@@ -15,7 +15,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: July 13 2014 $
+.Dd $Mdocdate: August 8 2014 $
 .Dt MDOC 7
 .Os
 .Sh NAME
@@ -468,7 +468,7 @@ in the alphabetical
 .It Sx \&Pf Ta prefix, no following horizontal space (one argument)
 .It Sx \&Ns Ta roman font, no preceding horizontal space (no arguments)
 .It Sx \&Ap Ta apostrophe without surrounding whitespace (no arguments)
-.It Sx \&Sm Ta switch horizontal spacing mode: Cm on | off
+.It Sx \&Sm Ta switch horizontal spacing mode: Op Cm on | off
 .It Sx \&Bk , \&Ek Ta keep block: Fl words
 .It Sx \&br Ta force output line break in text mode (no arguments)
 .It Sx \&sp Ta force vertical space: Op Ar height
@@ -1195,7 +1195,7 @@ Close a
 block.
 Does not have any tail arguments.
 .Ss \&Dd
-Document date.
+Document date for display in the page footer.
 This is the mandatory first macro of any
 .Nm
 manual.
@@ -1224,8 +1224,11 @@ the special string
 .Dq $\&Mdocdate$
 can be given as an argument.
 .It
-A few alternative date formats are accepted as well
-and converted to the standard form.
+The traditional, purely numeric
+.Xr man 7
+format
+.Ar year Ns \(en Ns Ar month Ns \(en Ns Ar day
+is accepted, too.
 .It
 If a date string cannot be parsed, it is used verbatim.
 .It
@@ -1285,30 +1288,26 @@ See also
 and
 .Sx \&Do .
 .Ss \&Dt
-Document title.
+Document title for display in the page header.
 This is the mandatory second macro of any
 .Nm
 file.
 Its syntax is as follows:
 .Bd -ragged -offset indent
 .Pf \. Sx \&Dt
-.Oo
-.Ar title
-.Oo
+.Ar TITLE
 .Ar section
-.Op Ar volume
-.Op Ar arch
-.Oc
-.Oc
+.Op Ar volume | arch
 .Ed
 .Pp
 Its arguments are as follows:
-.Bl -tag -width Ds -offset Ds
-.It Ar title
+.Bl -tag -width section -offset 2n
+.It Ar TITLE
 The document's title (name), defaulting to
-.Dq UNKNOWN
+.Dq UNTITLED
 if unspecified.
-It should be capitalised.
+To achieve a uniform appearance of page header lines,
+it should by convention be all caps.
 .It Ar section
 The manual section.
 This may be one of
@@ -1346,8 +1345,7 @@ or
 .Cm paper
 .Pq paper .
 It should correspond to the manual's filename suffix and defaults to
-.Cm 1
-if unspecified.
+the empty string if unspecified.
 .It Ar volume
 This overrides the volume inferred from
 .Ar section .
@@ -2110,7 +2108,7 @@ Examples:
 See also
 .Sx \&Oo .
 .Ss \&Os
-Document operating system version.
+Operating system version for display in the page footer.
 This is the mandatory third macro of
 any
 .Nm
@@ -2337,7 +2335,7 @@ and
 Switches the spacing mode for output generated from macros.
 Its syntax is as follows:
 .Pp
-.D1 Pf \. Sx \&Sm Cm on | off
+.D1 Pf \. Sx \&Sm Op Cm on | off
 .Pp
 By default, spacing is
 .Cm on .
@@ -2346,6 +2344,11 @@ When switched
 no white space is inserted between macro arguments and between the
 output generated from adjacent macros, but text lines
 still get normal spacing between words and sentences.
+.Pp
+When called without an argument, the
+.Sx \&Sm
+macro toggles the spacing mode.
+Using this is not recommended because it makes the code harder to read.
 .Ss \&So
 Multi-line version of
 .Sx \&Sq .
@@ -3024,7 +3027,7 @@ then the macro accepts an arbitrary number of argument
 .It Sx \&Pf  Ta    Yes      Ta    Yes      Ta    1
 .It Sx \&Pp  Ta    \&No     Ta    \&No     Ta    0
 .It Sx \&Rv  Ta    \&No     Ta    \&No     Ta    n
-.It Sx \&Sm  Ta    \&No     Ta    \&No     Ta    1
+.It Sx \&Sm  Ta    \&No     Ta    \&No     Ta    <2
 .It Sx \&St  Ta    \&No     Ta    Yes      Ta    1
 .It Sx \&Sx  Ta    Yes      Ta    Yes      Ta    >0
 .It Sx \&Sy  Ta    Yes      Ta    Yes      Ta    >0