Cleanups to mdoc.7 section documentation.

[Kristaps Dzonsons <kristaps@bsd.lv>]

[-- Attachment #1: Type: text/plain, Size: 178 bytes --]

Hi,

I noticed that the section documentation entries redundantly noted
relevant sections.  Removing these led to some clarification, examples,
and so on.

Yeas, nays?

Kristaps

[-- Attachment #2: patch.txt --]
[-- Type: text/plain, Size: 4401 bytes --]

Index: mdoc.7
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/mdoc.7,v
retrieving revision 1.158
diff -u -r1.158 mdoc.7
--- mdoc.7	4 Sep 2010 17:22:41 -0000	1.158
+++ mdoc.7	4 Sep 2010 17:51:58 -0000
@@ -386,20 +386,18 @@
 macro(s) must precede the
 .Sx \&Nd
 macro.
-.Pp
-See
+See also
 .Sx \&Nm
 and
 .Sx \&Nd .
 .It Em LIBRARY
-The name of the library containing the documented material, which is
-assumed to be a function in a section 2, 3, or 9 manual.
+The name of the library containing the documented material.
 The syntax for this is as follows:
 .Bd -literal -offset indent
 \&.Lb libarm
 .Ed
 .Pp
-See
+See also
 .Sx \&Lb .
 .It Em SYNOPSIS
 Documents the utility invocation syntax, function call syntax, or device
@@ -494,34 +492,39 @@
 This is useful when implementing standard functions that may have side
 effects or notable algorithmic implications.
 .It Em RETURN VALUES
-This section documents the
-return values of functions in sections 2, 3, and 9.
-.Pp
-See
+This section documents function return values.
+See also
 .Sx \&Rv .
 .It Em ENVIRONMENT
 Lists the environment variables used by the utility,
-and explains the syntax and semantics of their values.
-The
-.Xr environ 7
-manual provides examples of typical content and formatting.
+and explains the syntax and semantics of their values, such as
+.Bd -literal -offset indent
+\&.Bl \-tag \-width Ds
+\&.It Ev DISPLAY
+The location of the X11 server.
+\&.El
+.Ed
 .Pp
-See
+See also
 .Sx \&Ev .
 .It Em FILES
 Documents files used.
 It's helpful to document both the file name and a short description of how
-the file is used (created, modified, etc.).
+the file is used (created, modified, etc.), such as
+.Bd -literal -offset indent
+\&.Bl \-tag \-width Ds
+\&.It Pa ~/.profile
+User's login profile.
+\&.El
+.Ed
 .Pp
-See
+See also
 .Sx \&Pa .
 .It Em EXIT STATUS
-This section documents the
-command exit status for section 1, 6, and 8 utilities.
+This section documents a utility's exit status.
 Historically, this information was described in
 .Em DIAGNOSTICS ,
 a practise that is now discouraged.
-.Pp
 See
 .Sx \&Ex .
 .It Em EXAMPLES
@@ -529,45 +532,82 @@
 This often contains snippets of well-formed, well-tested invocations.
 Make sure that examples work properly!
 .It Em DIAGNOSTICS
-Documents error conditions.
-This is most useful in section 4 manuals.
+Documents error conditions, such as
+.Bd -literal -offset indent
+\&.Bl -diag
+\&.It "fxp%d: couldn't map memory"
+A fatal initialization error has occurred.
+\&.El
+.Ed
+.Pp
 Historically, this section was used in place of
-.Em EXIT STATUS
-for manuals in sections 1, 6, and 8; however, this practise is
+.Em EXIT STATUS ;
+however, this practise is now
 discouraged.
-.Pp
-See
-.Sx \&Bl
-.Fl diag .
 .It Em ERRORS
-Documents error handling in sections 2, 3, and 9.
+Documents possible
+.Va errno
+values in functions, such as
+.Bd -literal -offset indent
+\&.Bl -tag -width Ds
+\&.It Bq Er ERANGE
+The given string was out of range.
+\&.El
+.Ed
 .Pp
-See
+See also
 .Sx \&Er .
 .It Em SEE ALSO
 References other manuals with related topics.
 This section should exist for most manuals.
 Cross-references should conventionally be ordered first by section, then
-alphabetically.
+alphabetically, such as
+.Bd -literal -offset indent
+\&.Xr atof 3 ,
+\&.Xr atoi 3 ,
+\&.Xr atol 3 ,
+\&.Xr atoll 3 ,
+\&.Xr sscanf 3 ,
+\&.Xr strtod 3 ,
+\&.Xr strtol 3 ,
+\&.Xr strtoul 3
+.Ed
 .Pp
-See
+See also
 .Sx \&Xr .
 .It Em STANDARDS
 References any standards implemented or used.
 If not adhering to any standards, the
 .Em HISTORY
 section should be used instead.
-.Pp
-See
-.Sx \&St .
+See also
+.Sx \&St
+and
+.Sx \&Rs .
 .It Em HISTORY
 A brief history of the subject, including where support first appeared.
 .It Em AUTHORS
 Credits to the person or persons who wrote the code and/or documentation.
-Authors should generally be noted by both name and email address.
+Authors should generally be noted by both name and email address, such
+as
+.Bd -literal -offset indent
+The
+\&.Nm
+reference was written by
+\&.An Joe Random Aq joe@foo.lv .
+.Ed
 .Pp
-See
-.Sx \&An .
+See also
+.Sx \&An
+and
+.Sx \&Aq .
+Note that
+.Sx \&An
+and
+.Sx \&Aq
+are used instead of
+.Sx \&Mt
+for historical reasons.
 .It Em CAVEATS
 Common misuses and misunderstandings should be explained
 in this section.