sync docs to agree on section header (.Sh) order for man pages. This also

matches order used by NetBSD, though we don't use all their sections.

Order is:

NAME
SYNOPSIS
DESCRIPTION
RETURN VALUES
ENVIRONMENT
FILES
EXAMPLES
DIAGNOSTICS
ERRORS
SEE ALSO
STANDARDS
HISTORY
AUTHORS
CAVEATS
BUGS

ok krw@ millert@

3 files changed, 43 insertions, 40 deletions

diff --git a/share/man/man7/mdoc.7 b/share/man/man7/mdoc.7
index 0a0d7741214..4917511ea2b 100644
--- a/share/man/man7/mdoc.7
+++ b/share/man/man7/mdoc.7
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: mdoc.7,v 1.25 2003/04/13 11:06:21 jmc Exp $
+.\"	$OpenBSD: mdoc.7,v 1.26 2003/05/29 08:46:22 jmc Exp $
 .\"
 .\" Copyright (c) 1991, 1993
 .\"	The Regents of the University of California.  All rights reserved.
@@ -102,33 +102,31 @@ All
 macros must be given an argument.
 .It Ar DESCRIPTION
 General description, including any options, operands, or other parameters.
-.It Ar EXAMPLES
-Examples and suggestions.
 .It Ar RETURN VALUES
 Sections two and three function calls.
-.It Ar ERRORS
-Sections two and three error and signal handling.
-.It Ar DIAGNOSTICS
-Section four device interface diagnostics.
 .It Ar ENVIRONMENT
 Describe environment variables.
 .It Ar FILES
 Files associated with the subject, with short descriptions.
+.It Ar EXAMPLES
+Examples and suggestions.
+.It Ar DIAGNOSTICS
+Section four device interface diagnostics.
+.It Ar ERRORS
+Sections two and three error and signal handling.
 .It Ar SEE ALSO
 Cross references and citations.
-.It Ar COMPATIBILITY
-Compatibility issues, i.e., deprecated options or parameters.
 .It Ar STANDARDS
 Conformance to standards if applicable.
-.It Ar AUTHORS
-Credit to the person or persons who wrote the code and/or documentation.
 .It Ar HISTORY
 A brief history of the subject, including where support first appeared.
-.It Ar BUGS
-Gotchas and caveats.
+.It Ar AUTHORS
+Credit to the person or persons who wrote the code and/or documentation.
 .It Ar CAVEATS
 Explanations of common misuses, i.e., security considerations for certain
 library functions.
+.It Ar BUGS
+Gotchas and caveats.
 .It Ar other
 Customized headers may be added at the author's discretion.
 .El
diff --git a/share/man/man7/mdoc.samples.7 b/share/man/man7/mdoc.samples.7
index 7cf9e09a247..06f2eb5d18e 100644
--- a/share/man/man7/mdoc.samples.7
+++ b/share/man/man7/mdoc.samples.7
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: mdoc.samples.7,v 1.40 2003/04/13 11:06:21 jmc Exp $
+.\"	$OpenBSD: mdoc.samples.7,v 1.41 2003/05/29 08:46:22 jmc Exp $
 .\"	$NetBSD: mdoc.samples.7,v 1.5 1996/04/03 20:17:34 jtc Exp $
 .\"
 .\" Copyright (c) 1990, 1993
@@ -474,6 +474,7 @@ template found in the file
 \&.\e" .Sh STANDARDS
 \&.\e" .Sh HISTORY
 \&.\e" .Sh AUTHORS
+\&.\e" .Sh CAVEATS
 \&.\e" .Sh BUGS
 .Ed
 .Pp
@@ -2060,19 +2061,14 @@ to maintain consistency.
 They are listed in the order
 in which they would be used.
 .Bl -tag -width SYNOPSIS
+.It Li \&.Sh RETURN VALUES
+Sections 2 and 3 function return values.
 .It Li \&.Sh ENVIRONMENT
 The
 .Sx ENVIRONMENT
 section should reveal any related
 environment
 variables and clues to their behavior and/or usage.
-.It Li \&.Sh EXAMPLES
-There are several ways to create examples.
-See
-the
-.Sx EXAMPLES
-section below
-for details.
 .It Li \&.Sh FILES
 Files which are used or created by the man page subject
 should be listed via the
@@ -2080,6 +2076,21 @@ should be listed via the
 macro in the
 .Sx FILES
 section.
+.It Li \&.Sh EXAMPLES
+There are several ways to create examples.
+See
+the
+.Sx EXAMPLES
+section below
+for details.
+.It Li \&.Sh DIAGNOSTICS
+Diagnostics from a command should be placed in this section.
+.It Li \&.Sh ERRORS
+Specific error handling, especially from library functions
+(man page sections 2 and 3) should go here.
+The
+.Ql \&.Er
+macro is used to specify an errno.
 .It Li \&.Sh SEE ALSO
 References to other material on the man page topic and
 cross references to other relevant man pages should
@@ -2121,14 +2132,9 @@ Any command which does not adhere to any specific standards
 should be outlined historically in this section.
 .It Li \&.Sh AUTHORS
 Credits, if need be, should be placed here.
-.It Li \&.Sh DIAGNOSTICS
-Diagnostics from a command should be placed in this section.
-.It Li \&.Sh ERRORS
-Specific error handling, especially from library functions
-(man page sections 2 and 3) should go here.
-The
-.Ql \&.Er
-macro is used to specify an errno.
+.It Li \&.Sh CAVEATS
+Explanations of common misuses, e.g. security considerations
+for certain library functions.
 .It Li \&.Sh BUGS
 Blatant problems with the topic go here...
 .El
@@ -2948,8 +2954,8 @@ manual macro package
 template for writing a man page
 .El
 .Sh SEE ALSO
-.Xr man 1 ,
 .Xr groff 1 ,
+.Xr man 1 ,
 .Xr nroff 1 ,
 .Xr troff 1 ,
 .Xr mdoc 7
diff --git a/share/misc/mdoc.template b/share/misc/mdoc.template
index b4fd352c126..918f7faa9eb 100644
--- a/share/misc/mdoc.template
+++ b/share/misc/mdoc.template
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: mdoc.template,v 1.6 2001/02/03 08:22:44 niklas Exp $
+.\"	$OpenBSD: mdoc.template,v 1.7 2003/05/29 08:46:22 jmc Exp $
 .\"
 .\" The following requests are required for all man pages.
 .Dd Month DD, YYYY
@@ -6,7 +6,7 @@
 .Os
 .Sh NAME
 .Nm program
-.Nd one line about what it does 
+.Nd one line about what it does
 .Sh SYNOPSIS
 .\" For a program:  program [-abc] file ...
 .Nm program
@@ -17,21 +17,20 @@ The
 .Nm
 utility processes files ...
 .\" The following requests should be uncommented and used where appropriate.
-.\" .Sh EXAMPLES
 .\" This next request is for sections 2 and 3 function return values only.
 .\" .Sh RETURN VALUES
-.\" The next request is for sections 2 and 3 error and signal handling only.
-.\" .Sh ERRORS
-.\" This next request is for section 4 only.
-.\" .Sh DIAGNOSTICS
 .\" This next request is for sections 1, 6, 7 & 8 only.
 .\" .Sh ENVIRONMENT
 .\" .Sh FILES
+.\" .Sh EXAMPLES
+.\" This next request is for section 4 only.
+.\" .Sh DIAGNOSTICS
+.\" The next request is for sections 2 and 3 error and signal handling only.
+.\" .Sh ERRORS
 .\" .Sh SEE ALSO
 .\" .Xr foobar 1
-.\" .Sh COMPATIBILITY
 .\" .Sh STANDARDS
-.\" .Sh AUTHORS
 .\" .Sh HISTORY
-.\" .Sh BUGS
+.\" .Sh AUTHORS
 .\" .Sh CAVEATS
+.\" .Sh BUGS