Fix up mdoc section header descriptions to more accurately reflect how

man pages should be laid out in OpenBSD.

2 files changed, 30 insertions, 26 deletions

diff --git a/share/man/man7/mdoc.7 b/share/man/man7/mdoc.7
index eb4a45f71c8..4d6278cbca6 100644
--- a/share/man/man7/mdoc.7
+++ b/share/man/man7/mdoc.7
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: mdoc.7,v 1.16 2000/09/11 01:36:53 aaron Exp $
+.\"	$OpenBSD: mdoc.7,v 1.17 2000/11/08 20:50:59 aaron Exp $
 .\"
 .\" Copyright (c) 1991, 1993
 .\"	The Regents of the University of California.  All rights reserved.
@@ -87,7 +87,7 @@ Section Headers.
 Valid headers, in the order of presentation:
 .Bl -tag -width "RETURN VALUES" -compact
 .It Ar NAME
-Name section, should include the
+Name section. Should include the
 .Ql \&.Nm
 or
 .Ql \&.Fn
@@ -96,34 +96,38 @@ and the
 macros.
 .It Ar SYNOPSIS
 Usage.
+All
+.Ql \&.Nm
+macros must be given an argument.
 .It Ar DESCRIPTION
-General description, should include
-options and parameters.
+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.
-.It Ar EXAMPLES
-Examples and suggestions.
-.It Ar DIAGNOSTICS
-Normally used for section four device interface diagnostics.
-.It Ar ERRORS
-Sections two and three error and signal
-handling.
+Files associated with the subject, with short descriptions.
 .It Ar SEE ALSO
 Cross references and citations.
 .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
-If a standard is not applicable, the history
-of the subject should be given.
+A brief history of the subject, including where support first appeared.
 .It Ar BUGS
 Gotchas and caveats.
+.It Ar CAVEATS
+Explanations of common misuses, i.e., security considerations for certain
+library functions.
 .It Ar other
-Customized headers may be added at
-the author's discretion.
+Customized headers may be added at the author's discretion.
 .El
 .It Li \&.Ss
 Subsection Headers.
diff --git a/share/misc/mdoc.template b/share/misc/mdoc.template
index 2d8c1e3ee1d..04593f4bd00 100644
--- a/share/misc/mdoc.template
+++ b/share/misc/mdoc.template
@@ -1,12 +1,12 @@
 .\" The following requests are required for all man pages.
 .Dd Month DD, YYYY
-.Dt NAME SECTION
+.Dt NAME SECTION#
 .Os
 .Sh NAME
 .Nm program
 .Nd one line about what it does 
 .Sh SYNOPSIS
-.\" For a program:  program [-abc] files...
+.\" For a program:  program [-abc] file ...
 .Nm program
 .Op Fl abc
 .Op Ar
@@ -15,20 +15,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
-.\" This next request is for sections 1, 6, 7 & 8 only
-.\" .Sh ENVIRONMENT
-.\" .Sh FILES
-.\" .Sh EXAMPLES
-.\" This next request is for sections 1, 6, 7 & 8 only
-.\"     (command return values (to shell) and fprintf/stderr type diagnostics)
-.\" .Sh DIAGNOSTICS
 .\" 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 SEE ALSO
 .\" .Xr foobar 1
 .\" .Sh STANDARDS
-.\" .Sh HISTORY
 .\" .Sh AUTHORS
+.\" .Sh HISTORY
 .\" .Sh BUGS
+.\" .Sh CAVEATS