From swear@blarg.net  Thu Mar 28 21:58:22 2002
Return-Path: <swear@blarg.net>
Received: from lists.blarg.net (lists.blarg.net [206.124.128.17])
	by hub.freebsd.org (Postfix) with ESMTP id F1D9437B41C
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 28 Mar 2002 21:58:21 -0800 (PST)
Received: from thig.blarg.net (thig.blarg.net [206.124.128.18])
	by lists.blarg.net (Postfix) with ESMTP id 9BF68BDC2
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 28 Mar 2002 21:58:21 -0800 (PST)
Received: from localhost.localdomain ([206.124.139.115])
	by thig.blarg.net (8.9.3/8.9.3) with ESMTP id VAA19522
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 28 Mar 2002 21:58:20 -0800
Received: (from jojo@localhost)
	by localhost.localdomain (8.11.6/8.11.3) id g2T5us200723;
	Thu, 28 Mar 2002 21:56:54 -0800 (PST)
	(envelope-from swear@blarg.net)
Message-Id: <sradsrgbmh.dsr@localhost.localdomain>
Date: 28 Mar 2002 21:56:54 -0800
From: "Gary W. Swearingen" <swear@blarg.net>
Reply-To: swear@blarg.net
To: FreeBSD-gnats-submit@freebsd.org
Subject: ed(4) manual has skimpy synopsis, etc.
X-GNATS-Notify:

>Number:         36467
>Category:       docs
>Synopsis:       ed(4) manual has skimpy synopsis, etc.
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    trhodes
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Thu Mar 28 22:00:02 PST 2002
>Closed-Date:    Fri Apr 19 09:33:45 PDT 2002
>Last-Modified:  Fri Apr 19 09:33:45 PDT 2002
>Originator:     Gary W. Swearingen
>Release:        FreeBSD 4.5-STABLE i386
>Organization:
none
>Environment:
n/a
================
>Description:

The ed(4) manual has an inadequate synopsis: "device ed"

Also, the manual doesn't say that "device miibus" is also needed.
================
>How-To-Repeat:
n/a
================
>Fix:

Change the synosis to:

    device   ed# at isa? port # irq # iomem #

Add this new first paragraph to the "Caveats" section:

    Use of this device requires the use of "device miibus".
>Release-Note:
>Audit-Trail:

From: Tom Rhodes <darklogik@pittgoth.com>
To: "Gary W. Swearingen" <swear@blarg.net>
Cc: FreeBSD-gnats-submit@FreeBSD.org
Subject: Re: docs/36467: ed(4) manual page has skimpy synopsis, etc.
Date: Mon, 1 Apr 2002 23:15:14 -0500

 Is this really an important change?  I think that LINT describes this
 driver well, and feel that most people who are compiling their kernel
 would check the LINT file.  On the other hand, if we did this here,
 then it would have to be done elsewhere, on other manual pages such as
 ep(4).
 
 That sounds difficult to keep up with, mainly due to device driver
 changes, manual page consistancy, things like that.  Whats your
 opinion on this matter Gary?  Everyone else?
 
 -- 
 Tom (Darklogik) Rhodes
 www.FreeBSD.org  -The Power To Serve
 www.Pittgoth.com -Pittgoth Discussion Portal
 trhodes@ {Pittgoth.com, FreeBSD.org}

From: swear@blarg.net (Gary W. Swearingen)
To: Tom Rhodes <darklogik@pittgoth.com>
Cc: FreeBSD-gnats-submit@FreeBSD.org
Subject: Re: docs/36467: ed(4) manual page has skimpy synopsis, etc.
Date: 02 Apr 2002 12:01:06 -0800

 Tom Rhodes <darklogik@pittgoth.com> writes:
 
 > Is this really an important change?  I think that LINT describes this
 > driver well, and feel that most people who are compiling their kernel
 > would check the LINT file.  On the other hand, if we did this here,
 > then it would have to be done elsewhere, on other manual pages such as
 > ep(4).
 > 
 > That sounds difficult to keep up with, mainly due to device driver
 > changes, manual page consistancy, things like that.  Whats your
 > opinion on this matter Gary?  Everyone else?
 
 Well, we only have four levels of importance to attach to it, high,
 medium, low, and closed.  I think it deserves "low"; otherwise, a Policy
 should be documented that erroneous Synopsis lines shall be removed from
 and not added to existing manuals if there is an example line in LINT.
 
 Do this:
     zcat /usr/share/man/man4/* | grep Cd | grep device | less
 and I think you'll see that most of those that should have the extra
 info have it, especially since many of those displayed don't need extra
 info.  But there are probably many that are erroneous.
 
 But it seems almost trivial to keep up with by comparison to the other
 sections of the Section 4 manuals (though it's clearly not as important).
 
 The LINT and GENERIC files just have examples; they don't (and IMO
 shouldn't) have explanations; they belong in real documentation.
 Unfortunately, this PR won't help much, but I'll write another PR on
 LINT with a reference to the generic explanations in the appropriate
 
 IIRC, LINT and GENERIC often omit examples of valid syntaxes, so the
 example for "ed" doesn't tell the user that the manual's "device ed"
 won't work.  Some of the drivers allow both such forms for fixed
 and dynamic configuration.

From: Tom Rhodes <darklogik@pittgoth.com>
To: swear@blarg.net (Gary W. Swearingen)
Cc: freebsd-doc@FreeBSD.ORG, FreeBSD-gnats-submit@FreeBSD.ORG
Subject: Re: docs/36467: ed(4) manual page has skimpy synopsis, etc.
Date: Tue, 2 Apr 2002 15:47:03 -0500

 On Tue, 2 Apr 2002 12:10:04 -0800 (PST)
 swear@blarg.net (Gary W. Swearingen) wrote:
 
 > The following reply was made to PR docs/36467; it has been noted by
 > GNATS.
 > 
 > From: swear@blarg.net (Gary W. Swearingen)
 > To: Tom Rhodes <darklogik@pittgoth.com>
 > Cc: FreeBSD-gnats-submit@FreeBSD.org
 > Subject: Re: docs/36467: ed(4) manual page has skimpy synopsis, etc.
 > Date: 02 Apr 2002 12:01:06 -0800
 > 
 >  Tom Rhodes <darklogik@pittgoth.com> writes:
 
 Gary, this is alot of work...  I do agree with you, though, as
 inconsistancy in manual pages, or all forms of documentation in
 general, is just plain ugly to look over.  Something will come of this
 ;)
 
 -- 
 Tom (Darklogik) Rhodes
 www.FreeBSD.org  -The Power To Serve
 www.Pittgoth.com -Pittgoth Discussion Portal
 trhodes@{Pittgoth.com, FreeBSD.org}
 PGP key by www:
 http://www.pittgoth.com/~darklogik/darklogik.key
 
State-Changed-From-To: open->analyzed 
State-Changed-By: trhodes 
State-Changed-When: Wed Apr 10 08:34:29 PDT 2002 
State-Changed-Why:  
After a brief discussion with Gary, I figure this one is mine. 


Responsible-Changed-From-To: freebsd-doc->trhodes 
Responsible-Changed-By: trhodes 
Responsible-Changed-When: Wed Apr 10 08:34:29 PDT 2002 
Responsible-Changed-Why:  
After a brief discussion with Gary, I figure this one is mine. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=36467 
State-Changed-From-To: analyzed->patched 
State-Changed-By: trhodes 
State-Changed-When: Tue Apr 16 15:52:18 PDT 2002 
State-Changed-Why:  
I added more information to the synopsis area, however, miibus was already 
added, I'll MFC in 3 days. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=36467 
State-Changed-From-To: patched->closed 
State-Changed-By: trhodes 
State-Changed-When: Fri Apr 19 09:32:50 PDT 2002 
State-Changed-Why:  
I added miibus to the manual page in STABLE, along with more information in the 
synopsis. 

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