Date: Tue, 2 Apr 2002 12:10:04 -0800 (PST) From: swear@blarg.net (Gary W. Swearingen) To: freebsd-doc@FreeBSD.org Subject: Re: docs/36467: ed(4) manual page has skimpy synopsis, etc. Message-ID: <200204022010.g32KA4P07498@freefall.freebsd.org>
index | next in thread | raw e-mail
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:
> 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.
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
help
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200204022010.g32KA4P07498>