From owner-freebsd-doc Sun Oct 14 20:30:11 2001 Delivered-To: freebsd-doc@freebsd.org Received: from freefall.freebsd.org (freefall.FreeBSD.org [216.136.204.21]) by hub.freebsd.org (Postfix) with ESMTP id B8B3237B40E for ; Sun, 14 Oct 2001 20:30:02 -0700 (PDT) Received: (from gnats@localhost) by freefall.freebsd.org (8.11.4/8.11.4) id f9F3U2935746; Sun, 14 Oct 2001 20:30:02 -0700 (PDT) (envelope-from gnats) Date: Sun, 14 Oct 2001 20:30:02 -0700 (PDT) Message-Id: <200110150330.f9F3U2935746@freefall.freebsd.org> To: freebsd-doc@freebsd.org Cc: From: swear@blarg.net (Gary W. Swearingen) Subject: Re: docs/31271: rl(4) discourages vender openness by disparaging remarks. Reply-To: swear@blarg.net (Gary W. Swearingen) Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk List-ID: List-Archive: (Web Archive) List-Help: (List Instructions) List-Subscribe: List-Unsubscribe: X-Loop: FreeBSD.org The following reply was made to PR docs/31271; it has been noted by GNATS. From: swear@blarg.net (Gary W. Swearingen) To: Dima Dorfman Cc: FreeBSD-gnats-submit@freebsd.org Subject: Re: docs/31271: rl(4) discourages vender openness by disparaging remarks. Date: 14 Oct 2001 20:25:49 -0700 Dima Dorfman writes: > "Gary W. Swearingen" wrote: > > >Description: > > > > rl(4) discourages device manufacturer's openness > > ... or encourages them to write better documentation :-). Maybe, but I'd rather risk more poor documentation than risk no more documentation. Besides, one can make the point without being insulting about it, and keep both risks lower. > > --- /tmp/rl.4.old Sun Oct 14 15:51:07 2001 > > +++ /tmp/rl.4 Sun Oct 14 15:51:47 2001 > > @@ -189,9 +189,6 @@ > > The driver probably should not be > > depending on this characteristic. > > .Pp > > -The RealTek data sheets are of especially poor quality: the grammar > > -and spelling are awful and there is a lot of information missing, > > -particularly concerning the receiver operation. > > One particularly > > important fact that the data sheets fail to mention relates to the > > way in which the chip fills in the receive buffer. > > If you think this is rude, I invite you to read the first paragraph of > the third comment block of the source code (sys/pci/if_rl.c). It > says, in part: "This is probably the worst PCI ethernet controller > ever [made]". What your change removes is much more polite, albeit > more visible. Further, your change takes away the context from the > sentence following it. Not enough context to worry about. About the only thing removed besides the insults is redundant anyway. The existence of data sheets is mentioned in the "See Also" section. The whole "Bugs" section should be moved to the source code and both purged of insults which do no good and can only do harm. I see nothing in the bugs section that's useful to a user and so don't see that any of it belongs in the User Manual, let alone rants on RealTek's documents. Thanks for reading my own little rant. To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message