docs/84519: [patch] mdoc(7) manpage needs more about AUTHORS

[Gary W. Swearingen]

>Number:         84519
>Category:       docs
>Synopsis:       [patch] mdoc(7) manpage needs more about AUTHORS
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Wed Aug 03 15:20:05 GMT 2005
>Closed-Date:
>Last-Modified:
>Originator:     Gary W. Swearingen
>Release:        FreeBSD 5.4-RELEASE i386
>Organization:
none
>Environment:
n/a
>Description:

Many manpages name "authors" without indicating whether it applies
to the manpage or the software.

The mdoc manpage doesn't require it.  Nor does it say that
author's e-mail addresses should be inclosed in angle brackets,
which seems to be a de facto standard.

>How-To-Repeat:
n/a

>Fix:

The bit about e-mail address quoting probably belongs in a
manpage-wide discussion, but I didn't see a good place for it.


--- mdoc..orig.7	Wed Aug  3 07:26:32 2005
+++ mdoc.7	Wed Aug  3 08:02:43 2005
@@ -2900,10 +2900,13 @@
 .
 .It Li ".Sh AUTHORS"
 Credits should be placed here.
-The
+Use the
 .Ql .An
-macro should be used to specify the name(s) of the person(s).
-.
+macro for names and the
+.Ql .Aq
+macro for e-mail addresses within optional contact information.
+Explicitly indicate whether the person authored the initial manual page
+or the software or whatever the person is being credited for.
 .It Li ".Sh BUGS"
 Blatant problems with the topic go here.
 .El
>Release-Note:
>Audit-Trail:
>Unformatted: