From garys@opusnet.com  Wed Aug  3 15:16:08 2005
Return-Path: <garys@opusnet.com>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id 9BB5016A41F
	for <FreeBSD-gnats-submit@freebsd.org>; Wed,  3 Aug 2005 15:16:08 +0000 (GMT)
	(envelope-from garys@opusnet.com)
Received: from opusnet.com (mail.opusnet.com [209.210.200.6])
	by mx1.FreeBSD.org (Postfix) with ESMTP id 519D643D4C
	for <FreeBSD-gnats-submit@freebsd.org>; Wed,  3 Aug 2005 15:16:08 +0000 (GMT)
	(envelope-from garys@opusnet.com)
Received: from localhost.localhost [70.98.246.232] by opusnet.com with ESMTP
  (SMTPD32-8.05) id AFB458940146; Wed, 03 Aug 2005 08:16:04 -0700
Received: from localhost.localhost (localhost.localhost [127.0.0.1])
	by localhost.localhost (8.13.3/8.13.3) with ESMTP id j73FHga3006755
	for <FreeBSD-gnats-submit@freebsd.org>; Wed, 3 Aug 2005 08:17:42 -0700 (PDT)
	(envelope-from garys@opusnet.com)
Received: (from jojo@localhost)
	by localhost.localhost (8.13.3/8.13.3/Submit) id j73FHYat006754;
	Wed, 3 Aug 2005 08:17:34 -0700 (PDT)
	(envelope-from garys@opusnet.com)
Message-Id: <ovd5ov2goh.5ov@mail.opusnet.com>
Date: Wed, 03 Aug 2005 08:17:34 -0700
From: "Gary W. Swearingen" <garys@opusnet.com>
Reply-To: garys@opusnet.com
To: FreeBSD-gnats-submit@freebsd.org
Subject: [patch] mdoc(7) manpage needs more about AUTHORS
X-GNATS-Notify:

>Number:         84519
>Category:       docs
>Synopsis:       [patch] mdoc(7) manpage needs more about AUTHORS
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Wed Aug 03 15:20:05 GMT 2005
>Closed-Date:    Thu Oct 12 20:39:39 GMT 2006
>Last-Modified:  Thu Oct 12 20:39:39 GMT 2006
>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:
Responsible-Changed-From-To: freebsd-doc->garys 
Responsible-Changed-By: garys 
Responsible-Changed-When: Sun Aug 28 20:08:00 GMT 2005 
Responsible-Changed-Why:  
I'll work with vender on this. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=84519 
State-Changed-From-To: open->suspended 
State-Changed-By: garys 
State-Changed-When: Sat Oct 1 23:08:41 GMT 2005 
State-Changed-Why:  
I sent patch to maintainter over a month ago. 
I don't care what happens with this PR. 


Responsible-Changed-From-To: garys->freebsd-doc 
Responsible-Changed-By: garys 
Responsible-Changed-When: Sat Oct 1 23:08:41 GMT 2005 
Responsible-Changed-Why:  
I sent patch to maintainter over a month ago. 
I don't care what happens with this PR. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=84519 
State-Changed-From-To: suspended->closed 
State-Changed-By: ru 
State-Changed-When: Thu Oct 12 20:31:42 UTC 2006 
State-Changed-Why:  
This change has been accepted upstream (from ChangeLog): 

: 2005-08-29  Gary W. Swearingen  <garys@opusnet.com> 
:  
:         * tmac/groff_mdoc.man: Go into more details how the `AUTHORS' 
:         section should look like. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=84519 
>Unformatted:
