Bug 36467

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}

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.

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

Comment 4 Tom Rhodes 2002-04-10 16:34:29 UTC

State Changed
From-To: open->analyzed

After a brief discussion with Gary, I figure this one is mine. 

Comment 5 Tom Rhodes 2002-04-10 16:34:29 UTC

Responsible Changed
From-To: freebsd-doc->trhodes

After a brief discussion with Gary, I figure this one is mine.

Comment 6 Tom Rhodes 2002-04-16 23:52:18 UTC

State Changed
From-To: analyzed->patched

I added more information to the synopsis area, however, miibus was already 
added, I'll MFC in 3 days.

Comment 7 Tom Rhodes 2002-04-19 17:32:50 UTC

State Changed
From-To: patched->closed

I added miibus to the manual page in STABLE, along with more information in the 
synopsis.