===================================================================
RCS file: /cvs/mandoc/man.7,v
retrieving revision 1.51
retrieving revision 1.56
diff -u -p -r1.51 -r1.56
--- mandoc/man.7	2009/11/12 08:00:21	1.51
+++ mandoc/man.7	2010/03/22 05:59:32	1.56
@@ -1,4 +1,4 @@
-.\"	$Id: man.7,v 1.51 2009/11/12 08:00:21 kristaps Exp $
+.\"	$Id: man.7,v 1.56 2010/03/22 05:59:32 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: November 12 2009 $
+.Dd $Mdocdate: March 22 2010 $
 .Dt MAN 7
 .Os
 .
@@ -67,15 +67,7 @@ line termination.
 Blank lines are acceptable; where found, the output will assert a
 vertical space.
 .
-.Pp
-The
-.Sq \ec
-escape is common in historical
-.Nm
-documents; if encountered at the end of a word, it ensures that the
-subsequent word isn't off-set by whitespace.
 .
-.
 .Ss Comments
 Text following a
 .Sq \e\*" ,
@@ -110,7 +102,7 @@ and
 Terms may be text-decorated using the
 .Sq \ef
 escape followed by an indicator: B (bold), I, (italic), R (Roman), or P
-(revert to previous mode):  
+(revert to previous mode):
 .Pp
 .D1 \efBbold\efR \efIitalic\efP
 .Pp
@@ -118,6 +110,9 @@ A numerical representation 3, 2, or 1 (bold, italic, a
 respectively) may be used instead.  A text decoration is only valid, if
 specified in free-form text, until the next macro invocation; if
 specified within a macro, it's only valid until the macro closes scope.
+Note that macros like
+.Sx \&BR
+open and close a font scope with each argument.
 .Pp
 Text may also be sized with the
 .Sq \es
@@ -144,8 +139,7 @@ Both
 .Sq \es
 and
 .Sq \ef
-attributes are forgotten when exiting a subsequent (or current) macro
-invocation.
+attributes are forgotten when entering or exiting a macro block.
 .
 .
 .Ss Whitespace
@@ -301,7 +295,7 @@ the C library, this may be as follows:
 .D1 Standard C Library (libc, -lc)
 .It Em SYNOPSIS
 Documents the utility invocation syntax, function call syntax, or device
-configuration. 
+configuration.
 .Pp
 For the first, utilities (sections 1, 6, and 8), this is
 generally structured as follows:
@@ -316,10 +310,10 @@ And for the third, configurations (section 4):
 .Pp
 .D1 \&.B name* at cardbus ? function ?
 .Pp
-Manuals not in these sections generally don't need a 
+Manuals not in these sections generally don't need a
 .Em SYNOPSIS .
 .It Em DESCRIPTION
-This expands upon the brief, one-line description in 
+This expands upon the brief, one-line description in
 .Em NAME .
 It usually contains a break-down of the options (if documenting a
 command).
@@ -367,7 +361,7 @@ 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.  
+for most manuals.
 .Pp
 .D1 \&.BR bar \&( 1 \&),
 .Pp
@@ -429,8 +423,8 @@ subsequent lines until closed by another block macro.
 .Ss Line Macros
 Line macros are generally scoped to the current line, with the body
 consisting of zero or more arguments.  If a macro is scoped to the next
-line and the line arguments are empty, the next line is used instead,
-else the general syntax is used.  Thus:
+line and the line arguments are empty, the next line, which must be
+text, is used instead.  Thus:
 .Bd -literal -offset indent
 \&.I
 foo
@@ -439,9 +433,15 @@ foo
 .Pp
 is equivalent to
 .Sq \&.I foo .
-If next-line macros are invoked consecutively, only the last is used; in
-other words, if a next-line macro is preceded by a block macro, it is
-ignored.
+If next-line macros are invoked consecutively, only the last is used.
+If a next-line macro is followed by a non-next-line macro, an error is
+raised (unless in the case of
+.Sx \&br ,
+.Sx \&sp ,
+or
+.Sx \&na ) .
+.Pp
+The syntax is as follows:
 .Bd -literal -offset indent
 \&.YO \(lBbody...\(rB
 \(lBbody...\(rB
@@ -494,8 +494,10 @@ macros should not be used.  They're included for compa
 .Ss Block Macros
 Block macros are comprised of a head and body.  Like for in-line macros,
 the head is scoped to the current line and, in one circumstance, the
-next line; the body is scoped to subsequent lines and is closed out by a
-subsequent block macro invocation.
+next line (the next-line stipulations for line macros apply here as
+well).
+.Pp
+The syntax is as follows:
 .Bd -literal -offset indent
 \&.YO \(lBhead...\(rB
 \(lBhead...\(rB
@@ -510,7 +512,7 @@ sub-section, closed by a section or
 .Sx \&SS ;
 part, closed by a section, sub-section, or
 .Sx \&RE ;
-or paragraph, closed by a section, sub-section, part, 
+or paragraph, closed by a section, sub-section, part,
 .Sx \&HP ,
 .Sx \&IP ,
 .Sx \&LP ,
@@ -569,13 +571,13 @@ and
 .
 .
 .Ss \&BI
-Text is rendered alternately in bold face and italic.  Thus, 
+Text is rendered alternately in bold face and italic.  Thus,
 .Sq .BI this word and that
 causes
 .Sq this
 and
 .Sq and
-to render in bold face, while 
+to render in bold face, while
 .Sq word
 and
 .Sq that
@@ -825,7 +827,7 @@ The
 .Cm width
 argument must conform to
 .Sx Scaling Widths .
-If not specified, the saved or default width is used. 
+If not specified, the saved or default width is used.
 .
 .
 .Ss \&SB
@@ -966,7 +968,7 @@ Insert vertical spaces into output with the following 
 .Op Cm height
 .Ed
 .Pp
-Insert 
+Insert
 .Cm height
 spaces, which must conform to
 .Sx Scaling Widths .