this diff does two things (usually a bad sign):

- note which section headings (.Sh) are not used by openbsd
- move the description of the section heading to under the heading, rather
than before it: a much more logical way to read

diffs mailed upstream...

3 files changed, 28 insertions, 20 deletions

diff --git a/share/man/man7/man.7 b/share/man/man7/man.7
index a1ef07600d1..61f7450f553 100644
--- a/share/man/man7/man.7
+++ b/share/man/man7/man.7
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: man.7,v 1.7 2010/08/22 11:39:18 schwarze Exp $
+.\"	$OpenBSD: man.7,v 1.8 2010/08/31 17:51:31 jmc 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: August 22 2010 $
+.Dd $Mdocdate: August 31 2010 $
 .Dt MAN 7
 .Os
 .Sh NAME
@@ -221,23 +221,25 @@ Documents are generally structured as follows:
 \efBfoo\efR \e(en a description goes here
 \&.\e\*q The next is for sections 2 & 3 only.
 \&.\e\*q .SH LIBRARY
+\&.\e\*q Not used in OpenBSD.
 \&.SH SYNOPSIS
 \efBfoo\efR [\efB\e-options\efR] arguments...
 \&.SH DESCRIPTION
 The \efBfoo\efR utility processes files...
 \&.\e\*q .SH IMPLEMENTATION NOTES
-\&.\e\*q The next is for sections 2, 3, & 9 only.
+\&.\e\*q Not used in OpenBSD.
 \&.\e\*q .SH RETURN VALUES
-\&.\e\*q The next is for sections 1, 6, 7, & 8 only.
+\&.\e\*q For sections 2, 3, & 9 only.
 \&.\e\*q .SH ENVIRONMENT
+\&.\e\*q For sections 1, 6, 7, & 8 only.
 \&.\e\*q .SH FILES
-\&.\e\*q The next is for sections 1 & 8 only.
 \&.\e\*q .SH EXIT STATUS
+\&.\e\*q For sections 1 & 8 only.
 \&.\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 For sections 1, 4, 6, 7, & 8 only.
 \&.\e\*q .SH ERRORS
+\&.\e\*q For sections 2, 3, & 9 only.
 \&.\e\*q .SH SEE ALSO
 \&.\e\*q .BR foo ( 1 )
 \&.\e\*q .SH STANDARDS
@@ -246,6 +248,7 @@ The \efBfoo\efR utility processes files...
 \&.\e\*q .SH CAVEATS
 \&.\e\*q .SH BUGS
 \&.\e\*q .SH SECURITY CONSIDERATIONS
+\&.\e\*q Not used in OpenBSD.
 .Ed
 .Pp
 The sections in a
diff --git a/share/man/man7/mdoc.7 b/share/man/man7/mdoc.7
index 74203068844..7324fbf2d91 100644
--- a/share/man/man7/mdoc.7
+++ b/share/man/man7/mdoc.7
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: mdoc.7,v 1.49 2010/08/22 11:39:18 schwarze Exp $
+.\"	$OpenBSD: mdoc.7,v 1.50 2010/08/31 17:51:31 jmc Exp $
 .\"
 .\" Copyright (c) 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2010 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: August 22 2010 $
+.Dd $Mdocdate: August 31 2010 $
 .Dt MDOC 7
 .Os
 .Sh NAME
@@ -331,8 +331,9 @@ file:
 \&.Sh NAME
 \&.Nm foo
 \&.Nd a description goes here
-\&.\e\*q The next is for sections 2, 3, & 9 only.
 \&.\e\*q .Sh LIBRARY
+\&.\e\*q For sections 2, 3, & 9 only.
+\&.\e\*q Not used in OpenBSD.
 \&.Sh SYNOPSIS
 \&.Nm foo
 \&.Op Fl options
@@ -342,18 +343,19 @@ The
 \&.Nm
 utility processes files ...
 \&.\e\*q .Sh IMPLEMENTATION NOTES
-\&.\e\*q The next is for sections 2, 3, & 9 only.
+\&.\e\*q Not used in OpenBSD.
 \&.\e\*q .Sh RETURN VALUES
-\&.\e\*q The next is for sections 1, 6, 7, & 8 only.
+\&.\e\*q For sections 2, 3, & 9 only.
 \&.\e\*q .Sh ENVIRONMENT
+\&.\e\*q For sections 1, 6, 7, & 8 only.
 \&.\e\*q .Sh FILES
-\&.\e\*q The next is for sections 1, 6 & 8 only.
 \&.\e\*q .Sh EXIT STATUS
+\&.\e\*q For sections 1 & 8 only.
 \&.\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 For sections 1, 4, 6, 7, & 8 only.
 \&.\e\*q .Sh ERRORS
+\&.\e\*q For sections 2, 3, & 9 only.
 \&.\e\*q .Sh SEE ALSO
 \&.\e\*q .Xr foobar 1
 \&.\e\*q .Sh STANDARDS
@@ -362,6 +364,7 @@ utility processes files ...
 \&.\e\*q .Sh CAVEATS
 \&.\e\*q .Sh BUGS
 \&.\e\*q .Sh SECURITY CONSIDERATIONS
+\&.\e\*q Not used in OpenBSD.
 .Ed
 .Pp
 The sections in an
diff --git a/share/misc/mdoc.template b/share/misc/mdoc.template
index 05abf74ebc9..f22478a16b6 100644
--- a/share/misc/mdoc.template
+++ b/share/misc/mdoc.template
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: mdoc.template,v 1.10 2007/05/31 22:10:19 jmc Exp $
+.\"	$OpenBSD: mdoc.template,v 1.11 2010/08/31 17:51:31 jmc Exp $
 .\"
 .\" The following requests are required for all man pages.
 .\"
@@ -19,16 +19,18 @@ The
 .Nm
 utility processes files ...
 .\" The following requests should be uncommented and used where appropriate.
-.\" This next request is for sections 2, 3, and 9 function return values only.
 .\" .Sh RETURN VALUES
-.\" This next request is for sections 1, 6, 7 & 8 only.
+.\" For sections 2, 3, and 9 function return values only.
 .\" .Sh ENVIRONMENT
+.\" For sections 1, 6, 7 & 8 only.
 .\" .Sh FILES
+.\" .Sh EXIT STATUS
+.\" For sections 1 & 8 only.
 .\" .Sh EXAMPLES
-.\" This next request is for sections 1, 4, 6, and 8 only.
 .\" .Sh DIAGNOSTICS
-.\" The next request is for sections 2, 3, and 9 error and signal handling only.
+.\" For sections 1, 4, 6, 7, and 8 only.
 .\" .Sh ERRORS
+.\" For sections 2, 3, and 9 error and signal handling only.
 .\" .Sh SEE ALSO
 .\" .Xr foobar 1
 .\" .Sh STANDARDS