Bug 31271

Summary: rl(4) discourages vender openness by disparaging remarks.
Product: Documentation Reporter: Gary W. Swearingen <swear>
Component: Books & ArticlesAssignee: Tom Rhodes <trhodes>
Status: Closed FIXED    
Severity: Affects Only Me    
Priority: Normal    
Version: Latest   
Hardware: Any   
OS: Any   
Attachments:
Description Flags
file.diff none

Description Gary W. Swearingen 2001-10-15 00:10:01 UTC 
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.)
================

Fix: Remove the most offending/unnecessary/unhelpful sentence.

patch -d "unknown uncompressed man directory" < this-PR
How-To-Repeat: n/a
================
Comment 1 Dima Dorfman 2001-10-15 00:24:59 UTC 
"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.
Comment 2 Gary W. Swearingen 2001-10-15 04:25:49 UTC 
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.
Comment 3 Murray Stokely freebsd_committer freebsd_triage 2001-11-05 09:21:58 UTC 
State Changed
From-To: open->analyzed

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. ;)
Comment 4 Giorgos Keramidas 2001-11-27 15:58:56 UTC 
> 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
Comment 5 Tom Rhodes freebsd_committer freebsd_triage 2002-11-06 01:20:08 UTC 
Responsible Changed
From-To: freebsd-doc->trhodes

Task list.
Comment 6 Tom Rhodes freebsd_committer freebsd_triage 2002-11-06 03:59:58 UTC 
State Changed
From-To: analyzed->feedback

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.
Comment 7 Tom Rhodes freebsd_committer freebsd_triage 2002-11-20 00:35:46 UTC 
State Changed
From-To: feedback->closed

I've cleaned up the paragraph.