From swear@blarg.net  Sun Oct 14 16:07:45 2001
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 4B20837B401
	for <FreeBSD-gnats-submit@freebsd.org>; Sun, 14 Oct 2001 16:07:45 -0700 (PDT)
Received: from thig.blarg.net (thig.blarg.net [206.124.128.18])
	by lists.blarg.net (Postfix) with ESMTP id 5860DBD39
	for <FreeBSD-gnats-submit@freebsd.org>; Sun, 14 Oct 2001 16:07:44 -0700 (PDT)
Received: from localhost.localdomain ([206.124.139.115])
	by thig.blarg.net (8.9.3/8.9.3) with ESMTP id QAA05704
	for <FreeBSD-gnats-submit@freebsd.org>; Sun, 14 Oct 2001 16:07:44 -0700
Received: (from jojo@localhost)
	by localhost.localdomain (8.11.6/8.11.3) id f9EN6tF33529;
	Sun, 14 Oct 2001 16:06:55 -0700 (PDT)
	(envelope-from swear@blarg.net)
Message-Id: <s5r8s5n7n4.8s5@localhost.localdomain>
Date: 14 Oct 2001 16:06:55 -0700
From: "Gary W. Swearingen" <swear@blarg.net>
Reply-To: swear@blarg.net
To: FreeBSD-gnats-submit@freebsd.org
Subject: rl(4) discourages vender openness by disparaging remarks.
X-GNATS-Notify:

>Number:         31271
>Category:       docs
>Synopsis:       rl(4) discourages vender openness by disparaging remarks.
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    trhodes
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Sun Oct 14 16:10:01 PDT 2001
>Closed-Date:    Tue Nov 19 16:36:10 PST 2002
>Last-Modified:  Tue Nov 19 16:36:10 PST 2002
>Originator:     Gary W. Swearingen
>Release:        FreeBSD 4.4-RELEASE i386
>Organization:
none
>Environment:
n/a
================
>Description:

rl(4) discourages device manufacturer's openness by disparaging (in
unnecessarily rude terms) the documentation they graciously provided on
their web site.  Such remarks might discourage this or other
manufacturers from opening their documents.

(The man page also says much that would be better placed in the driver
source, but it's probably not worthwhile moving it.)
================
>How-To-Repeat:
n/a
================
>Fix:

Remove the most offending/unnecessary/unhelpful sentence.

patch -d "unknown uncompressed man directory" < this-PR

--- /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.
>Release-Note:
>Audit-Trail:

From: Dima Dorfman <dima@trit.org>
To: swear@blarg.net
Cc: FreeBSD-gnats-submit@freebsd.org
Subject: Re: docs/31271: rl(4) discourages vender openness by disparaging remarks. 
Date: Sun, 14 Oct 2001 23:24:59 +0000

 "Gary W. Swearingen" <swear@blarg.net> wrote:
 > >Description:
 > 
 > rl(4) discourages device manufacturer's openness
 
 ... or encourages them to write better documentation :-).
 
 > --- /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.

From: swear@blarg.net (Gary W. Swearingen)
To: Dima Dorfman <dima@trit.org>
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 <dima@trit.org> writes:
 
 > "Gary W. Swearingen" <swear@blarg.net> 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.
State-Changed-From-To: open->analyzed 
State-Changed-By: murray 
State-Changed-When: Mon Nov 5 01:21:58 PST 2001 
State-Changed-Why:  
Does anyone else have an opinion on the subject?  Should we keep this 
text or tone it down a bit?  I'm not even going to dare bring this up 
with the driver author (wpaul) for fear he will take the opportunity 
to add even more colorful language to describe RealTek. ;) 


http://www.FreeBSD.org/cgi/query-pr.cgi?pr=31271 

From: Giorgos Keramidas <charon@labs.gr>
To: "Gary W. Swearingen" <swear@blarg.net>
Cc: Murray Stokely <murray@FreeBSD.org>,
	FreeBSD-gnats-submit@FreeBSD.org
Subject: Re: docs/31271: rl(4) discourages vender openness by disparaging remarks.
Date: Tue, 27 Nov 2001 17:58:56 +0200

 > State-Changed-From-To: open->analyzed
 > State-Changed-By: murray
 > State-Changed-When: Mon Nov 5 01:21:58 PST 2001
 > State-Changed-Why:
 > Does anyone else have an opinion on the subject?  Should we keep this
 > text or tone it down a bit?  I'm not even going to dare bring this up
 > with the driver author (wpaul) for fear he will take the opportunity
 > to add even more colorful language to describe RealTek. ;)
 
 I think that we should try to avoid making nasty remarks about
 hardware vendors.  I mean, in our lists, in the archives, it's
 probably OK, but in documentation that is shipped with FreeBSD, it's
 kind of embarrassing.
 
 -giorgos
Responsible-Changed-From-To: freebsd-doc->trhodes 
Responsible-Changed-By: trhodes 
Responsible-Changed-When: Tue Nov 5 17:20:08 PST 2002 
Responsible-Changed-Why:  
Task list. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=31271 
State-Changed-From-To: analyzed->feedback 
State-Changed-By: trhodes 
State-Changed-When: Tue Nov 5 19:59:58 PST 2002 
State-Changed-Why:  
Removed the 'problematic' portions of the page (6 lines) leaving just 
the facts from the paragraph.  Feedback state until I actually work over 
some of the comments in the driver manual page. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=31271 
State-Changed-From-To: feedback->closed 
State-Changed-By: trhodes 
State-Changed-When: Tue Nov 19 16:35:46 PST 2002 
State-Changed-Why:  
I've cleaned up the paragraph. 

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