Document the .An (author name) macro. Also cleanup some other problems

I noticed while editing these man pages.

Usage: .An Author_name

Example:

This manual page was written by
.An Mike Pritchard Aq mpp@FreeBSD.ORG .

Produces:

This manual page was written by Mike Pritchard <mpp@FreeBSD.ORG>.

2 files changed, 52 insertions, 23 deletions

diff --git a/share/man/man7/mdoc.7 b/share/man/man7/mdoc.7
index ac2adae..2117a63 100644
--- a/share/man/man7/mdoc.7
+++ b/share/man/man7/mdoc.7
@@ -30,7 +30,7 @@
 .\" SUCH DAMAGE.
 .\"
 .\"	@(#)mdoc.7	8.2 (Berkeley) 12/30/93
-.\"	$Id: mdoc.7,v 1.4 1997/03/07 03:28:15 jmg Exp $
+.\"	$Id: mdoc.7,v 1.5 1997/03/19 20:31:37 mpp Exp $
 .\"
 .Dd December 30, 1993
 .Os
@@ -281,7 +281,8 @@ Produces
 .Ss Manual Domain Macros
 .Bl -column "Name" "Parsed" Callable" -compact
 .It Em Name	Parsed	Callable	Description
-.It Li \&Ad Ta Yes Ta Yes Ta Address. "(This macro may be deprecated.)"
+.It Li \&Ad Ta Yes Ta Yes Ta "Address. (This macro may be deprecated.)"
+.It Li \&An Ta Yes Ta Yes Ta "Author name."
 .It Li \&Ar Ta Yes Ta Yes Ta "Command line argument."
 .It Li \&Cd Ta \&No Ta \&No Ta "Configuration declaration (section four only)."
 .It Li \&Cm Ta Yes Ta Yes Ta "Command line argument modifier."
@@ -347,7 +348,7 @@ Produces
 .It Li \&Qq Ta Yes Ta Yes Ta "Strait Double quote."
 .It Li \&Re Ta \&No Ta \&No Ta "Reference start."
 .It Li \&Rs Ta \&No Ta \&No Ta "Reference start."
-.It Li \&Rv Ta \&No Ta \&No Ta "Return values."
+.It Li \&Rv Ta \&No Ta \&No Ta "Return values (sections two and three only)."
 .It Li \&Sc Ta Yes Ta Yes Ta "Single close quote."
 .It Li \&So Ta Yes Ta Yes Ta "Single open quote."
 .It Li \&Sq Ta Yes Ta Yes Ta "Single quote."
@@ -357,7 +358,7 @@ Produces
 .It Li \&Tn Ta Yes Ta Yes Ta "Trade or type name (small Caps)."
 .It Li \&Ux Ta Yes Ta Yes Ta Ux
 .It Li \&Xc Ta Yes Ta Yes Ta "Extend argument list close."
-.It Li \&Xo Ta Yes Ta Yes Ta "Extend argument list close."
+.It Li \&Xo Ta Yes Ta Yes Ta "Extend argument list open."
 .El
 .\" .It Sy \&Hf Ta \&No Ta \&No Ta "Include file with header"
 .Pp
diff --git a/share/man/man7/mdoc.samples.7 b/share/man/man7/mdoc.samples.7
index f746482..93840cc 100644
--- a/share/man/man7/mdoc.samples.7
+++ b/share/man/man7/mdoc.samples.7
@@ -30,7 +30,7 @@
 .\" SUCH DAMAGE.
 .\"
 .\"     @(#)mdoc.samples.7	8.2 (Berkeley) 12/30/93
-.\"	$Id: mdoc.samples.7,v 1.13 1997/03/19 20:31:42 mpp Exp $
+.\"	$Id: mdoc.samples.7,v 1.14 1997/03/19 21:01:45 mpp Exp $
 .\"
 .\" This tutorial sampler invokes every macro in the package several
 .\" times and is guaranteed to give a worst case performance
@@ -131,6 +131,7 @@ outlined as follows:
 .Tn "MANUAL DOMAIN"
 .Bl -tag -width flag -compact -offset indent
 .It "Addresses" .
+.It "Author name" .
 .It "Arguments" .
 .It "Configuration Declarations (section four only)" .
 .It "Command Modifier" .
@@ -147,7 +148,6 @@ outlined as follows:
 .It "Names" .
 .It "Options" .
 .It "Pathnames" .
-.It "Return Values"
 .It "Variables" .
 .It "Cross References" .
 .El
@@ -171,6 +171,7 @@ outlined as follows:
 .It "No Space Macro" .
 .It "Section Cross References" .
 .It "References and Citations" .
+.It "Return Values (sections two and three only)"
 .It "Trade Names (Acronyms and Type Names)" .
 .El
 .It
@@ -824,6 +825,33 @@ It is an error to call
 without arguments.
 .Li \&.Ad
 is callable by other macros and is parsed.
+.Ss Author Name
+The
+.Ql \&.An
+macro is used to specify the name of the author of the item being
+documented, or the name of the author of the actual manual page.
+Any remaining arguments after the name information are assumed 
+to be punctuation.
+.Pp
+.Dl Usage: .An author_name \*(Pu
+.Bl -tag -width ".An Joe Author ) ) ," -compact -offset 14n
+.It Li \&.An Joe\ Author
+.An Joe Author
+.It Li \&.An Joe\ Author\ ,
+.An Joe\ Author ,
+.It Li \&.An Joe\ Author\ \&Aq\ nobody@FreeBSD.ORG
+.An Joe Author Aq nobody@FreeBSD.ORG
+.It Li \&.An Joe\ Author\ )\ )\ ,
+.An Joe Author ) ) ,
+.El
+.Pp
+The
+.Ql \&.An
+macro is parsed and is callable.
+It is an error to call
+.Ql \&.An
+without
+any arguments.
 .Ss Argument Macro
 The
 .Li \&.Ar
@@ -1302,23 +1330,6 @@ macro formats path or file names.
 The
 .Ql \&.Pa
 macro is parsed and is callable.
-.Ss Return Values
-The
-.Ql \&.Rv
-macro generates text for use in the
-.Sx RETURN VALUES
-section.
-.Pp
-.Dl Usage: .Rv [-std function]
-.Pp
-.Ql \&.Rv -std atexit
-will generate the following text:
-.Pp
-.Rv -std atexit
-.Pp
-The
-.Fl std
-option is valid only for manual page sections 2 and 3.
 .Ss Variables
 Generic variable reference:
 .Pp
@@ -1632,6 +1643,23 @@ The purpose is to allow trade names
 to be pretty printed in
 .Xr troff Ns / Ns Xr ditroff
 output.
+.Ss Return Values
+The
+.Ql \&.Rv
+macro generates text for use in the
+.Sx RETURN VALUES
+section.
+.Pp
+.Dl Usage: .Rv [-std function]
+.Pp
+.Ql \&.Rv -std atexit
+will generate the following text:
+.Pp
+.Rv -std atexit
+.Pp
+The
+.Fl std
+option is valid only for manual page sections 2 and 3.
 .Ss Trade Names (or Acronyms and Type Names)
 The trade name macro is generally a small caps macro for
 all upper case words longer than two characters.