Linux docs (was:Re: [tlug] Re: IPv6)

[Scott Robbins <scottro@example.com>]

On Sat, Nov 17, 2007 at 06:10:31PM +0900, burlingk@example.com wrote:
> 
> 
> -----Original Message-----
> > From: Stephen J. Turnbull
> > Sent: Saturday, November 17, 2007 1:43 PM
> >
> > Scott Robbins writes:
> >
> >> ifconfig actually give an example of giving an alias (the Linux ifconfig
> >> manpage
> >
> > Ah, well, that's just a bug.  Probably occasioned by the lack of
> > attention to manpages on a system where Info manuals and HTML HOWTOs
> > are the preferred forms of documentation, I admit.  I think a lot of
> > your issue with Linux *documentation* comes from the fact that it's
> > not in manpage form.
> >
> 
> I keep running into issues where certain distributitions like
> to separate all the documentation packages from the main packages
> themselves, so I never realise half of the HTML and info files
> even exist.  ^^;; 

As Stephen says, that's a bug in a way.  I consider man pages buggy
actually.  To Josh, Stephen and the other coders--suppose you gave me a
program you'd written and said, here, it probably won't run till you use
it three times, and if it still doesn't work, it's your lack of skill?
That's a man page and as it's software, it's buggy.  :) QED.  

Seriously, I think Stephen got lucky in my choice of examples.  (I have
to send a note to Dru Lavigne, who uses that example in her classes.)

I haven't booted up Linux yet this morning, but will check later.  The
ifconfig doc is probably a better example.  AFAICT, there is no mention
of how to create an alias on an interface.  

Fedora tends to have many things in /usr/share/doc, so that's the second
place I look.  (I guess it should be 3rd, after info.)

One problem is that some distros have their own good docs (and Fedora is
really one of them, as a rule) but that as Ken writes, they're not
always in the usual places.  Other things, especially Gnome related, as
a friend of mine says, have sparse docs for the user, good docs for the
developers, and nothing in between.  This holds for Gnome stuff on
FreeBSD as well. For example, I see nothing in the avahi-daemon man page
to tell me *why* it is required for OpenOffice.  It's supposed to have
something to do with zeroconf and DNS.  So why is it required (in the
FreeBSD port) for Gimp and OO?   

Recent Fedora updates have broken sound for many people.  One reason is
ConsoleKit.  There doesn't seem to be any good documentation on which
services can be turned off at startup, and Fedora runs many of them by
default.  Many people rely on the mjmwired website page about it to
judge what is and isn't needed.  ConsoleKit is described as something
that enables fast user switching and a few other minor things,
especially if you don't use Gnome.  

In a thread on RH's bugzilla, I mentioned that I had fixed my sound
issues by re-enabling ConsoleKit. A developer posted that turning it off
can break many things and that he had decided that from Fedora 9 up he
was going to basically make it impossible to turn it off.  

I posted back that wouldn't it be less effort to make a few lines of
documentation warning people it should be left enabled?  He wrote back
that after spending 10 hours a day fixing problems caused by people
ignoring his warnings, he felt that he would be better of doing it his
way.  (This wasn't acrimonious at all, on either side.)

Now, having ConsoleKit be linked to so many other things annoys me, but
again, going back to my earlier post, in FreeBSD, there are various
services that can be turned on and off, either in /boot/loader.conf or
/etc/rc.conf.  Each one has a man page that gives a pretty good idea of
why you should or shouldn't have it.  I wish that Fedora had that, and
feel that its lack is a Bad Thing(TM). 

Sorry for the length of this, and of course, FreeBSD's man pages can
often be obscure as well, but I think that the BSDs in general do pay
more attention to the docs.  I also think my picture of why it's been
that way is good for a chuckle, if nothing else.  


-- 
Scott Robbins
PGP keyID EB3467D6
( 1B48 077D 66F6 9DB0 FDC2 A409 FA54 EB34 67D6 )
gpg --keyserver pgp.mit.edu --recv-keys EB3467D6

Buffy: You know, you could have brought that up to us
before we did it.
Giles: I did! I said there could be dire consequences.
Buffy: Yes, but you say that about chewing too fast.