===================================================================
RCS file: /cvs/mandoc/man.7,v
retrieving revision 1.32
retrieving revision 1.35
diff -u -p -r1.32 -r1.35
--- mandoc/man.7	2009/08/20 12:08:40	1.32
+++ mandoc/man.7	2009/08/21 12:12:12	1.35
@@ -1,4 +1,4 @@
-.\"	$Id: man.7,v 1.32 2009/08/20 12:08:40 kristaps Exp $
+.\"	$Id: man.7,v 1.35 2009/08/21 12:12:12 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: August 20 2009 $
+.Dd $Mdocdate: August 21 2009 $
 .Dt MAN 7
 .Os
 .
@@ -139,18 +139,27 @@ are generally structured as follows:
 \&.
 \&.SH NAME
 \efBfoo\efR \e(en a description goes here
+\&.\e\*q The next is for sections 2 & 3 only.
+\&.\e\*q .SH LIBRARY
 \&.
 \&.SH SYNOPSIS
 \efBfoo\efR [\efB\e-options\efR] arguments...
 \&.
 \&.SH DESCRIPTION
-The \efBfoo\efR utility does...
+The \efBfoo\efR utility processes files...
 \&.
+\&.\e\*q .SH IMPLEMENTATION NOTES
+\&.\e\*q The next is for sections 1 & 8 only.
+\&.\e\*q .SH EXIT STATUS
+\&.\e\*q The next is for sections 2, 3, & 9 only.
 \&.\e\*q .SH RETURN VALUES
+\&.\e\*q The next is for sections 1, 6, 7, & 8 only.
 \&.\e\*q .SH ENVIRONMENT
 \&.\e\*q .SH FILES
 \&.\e\*q .SH EXAMPLES
+\&.\e\*q The next is for sections 1, 4, 6, 7, & 8 only.
 \&.\e\*q .SH DIAGNOSTICS
+\&.\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)
@@ -159,6 +168,7 @@ The \efBfoo\efR utility does...
 \&.\e\*q .SH AUTHORS
 \&.\e\*q .SH CAVEATS
 \&.\e\*q .SH BUGS
+\&.\e\*q .SH SECURITY CONSIDERATIONS
 .Ed
 .
 .
@@ -195,18 +205,14 @@ foo
 .Pp
 is equivalent to
 .Sq \&.I foo .
-.\" PARAGRAPH
-Consecutive next-line scope invocations are disallowed.
+If next-line macros are invoked consecutively, only the last is used.
+If a next-line macro is proceded by a block macro, it is ignored.
 .Bd -literal -offset indent
 \&.YO \(lBbody...\(rB
 \(lBbody...\(rB
 .Ed
 .
 .Pp
-It is considered an error when next-line scope is open at the end of
-file.
-.
-.Pp
 .Bl -column -compact -offset indent "MacroX" "ArgumentsX" "ScopeXXXXX"
 .It Em Macro Ta Em Arguments Ta Em Scope
 .It    B     Ta    n         Ta    next-line
@@ -278,10 +284,6 @@ or
 No closure refers to an explicit block closing macro.
 .
 .Pp
-It is considered an error when part or next-line scope is open at the
-end of file.
-.
-.Pp
 .Bl -column "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" -compact -offset indent
 .It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope
 .It   HP     Ta    <2        Ta    current    Ta    paragraph
@@ -291,8 +293,8 @@ end of file.
 .It   PP     Ta    0         Ta    current    Ta    paragraph
 .It   RE     Ta    0         Ta    current    Ta    none
 .It   RS     Ta    1         Ta    current    Ta    part
-.It   SH     Ta    >0        Ta    current    Ta    section
-.It   SS     Ta    >0        Ta    current    Ta    sub-section
+.It   SH     Ta    >0        Ta    next-line  Ta    section
+.It   SS     Ta    >0        Ta    next-line  Ta    sub-section
 .It   TP     Ta    n         Ta    next-line  Ta    paragraph
 .El
 .