[ale] TFM - was: I am so tired of Linux Fanatics

Thu Jul 8 11:28:28 EDT 2010

That's a very good question. I wish I had the answer. GNU likes to use info
pages (which really need to be read in some tool other than 'info'). I would
suspect that the man page docs are maintained (haphazardly) by either the
current tool maintainer or by one or more of the distros (especially when
the tools are distro customised)

I think just a simple 'move the examples to the top' would be a huge
improvement for most man pages! Or at least desginate an "Examples" section
that can be quickly searched for. So many tools don't have any examples and
they need some to illustrate common or typical uses.

The linux documentation project tldp.org has a ton of info and they are
always looking for new doc writers to update existing docs and add new ones.
They are often "outdated but extremely useful".

On Thu, Jul 8, 2010 at 11:04 AM, wolf at wolfhalton.info
<wolf at wolfhalton.info>wrote:

>  Jim,
> This is a place where an ounce of initiative would be worth a ton of
> complaining.  Where could a person get themselves hooked up with whoever
> maintains (or doesn't maintain) man pages?
> I started working on developing a rewrite of some man pages for a few
> packages I use a lot, so the examples were at the top and not obscure.  Many
> newbies believe foobar is a real linux command (I know from testing a couple
> hundred new linux users).  Nobody has time to take on the man pages for
> 30000 packages, but if every one of us took on 1 or 2 of the man pages then
> the "F" in RTFM might be "fine", "fun" or "fabulous."  What say you?
>
> -Wolf
>
> -----Original Message-----
> *From*: Jim Kinney <jim.kinney at gmail.com<Jim%20Kinney%20%3cjim.kinney at gmail.com%3e>
> >
> *Reply-to*: Atlanta Linux Enthusiasts - Yes! We run Linux! <ale at ale.org>
> *To*: Atlanta Linux Enthusiasts - Yes! We run Linux! <ale at ale.org<Atlanta%20Linux%20Enthusiasts%20-%20Yes%21%20We%20run%20Linux%21%20%3cale at ale.org%3e>
> >
> *Subject*: Re: [ale] I am so tired of Linux Fanatics
> *Date*: Thu, 8 Jul 2010 09:36:43 -0400
>
> My greatest "AH HA!" moment reading man pages was when I discovered I could
> search for terms within man pages by hitting /<search term>  or /"search
> term" when it had spaces.
>
> And yes, release notes should be merged into the man pages as a "current
> version" section. I recently spent many days trying in vain to get a
> particular aplications client libraries to compile. Total fail. Turns out
> there was a blurb in a .2 version release notes that briefly pointed out the
> client libs were merged into the server libs and not needed as a stand-alone
> anymore. Since entire application had various version numbers for the
> different pieces, I had grabbed the latest of each.
>
> at least there _were_ release notes!
>
> eons ago (before SuSE drank the kool-aide and open-sourced their installer)
> I was tinkering with a SuSE installation issue. They had no release notes on
> their installer. They had notes on the distro but their installer was a
> black box. And it was failing to run on my chipset (that was about 2 years
> old so it should have been supported). End result is RedHat installed nicely
> and their notes on their installer covered the chipset initialization
> failure and provided a workaround (don't ask. It was like RedHat 4.2 era).
> Thusly, I wound up firmly in the RedHat camp since their output was more
> professional and robust and informative and open. And unlike the Debian
> installs at the time (which always worked - BTW) did not require that I know
> memory address space values (in hex of course) in order to accept a
> configuration during installtion. Granted, if I just hit "OK" on everything
> it all worked but it felt like a dead vertical learning curve while carrying
> a load of lead bricks by a cord in my teeth while climbing a greased rope
> that was on fire.
>
> And from that was born Ubuntu....  :D
>
> On Thu, Jul 8, 2010 at 7:34 AM, Paul Cartwright <ale at pcartwright.com>
> wrote:
>
> On Wed July 7 2010, Jim Philips wrote:
> > The problem with RTFM is the assumption that the fine manual was well
> > written in the first place. I have been using Linux since 1995 and I have
> >  always felt that the man pages were written in exceptionally poor
> fashion.
> > The immediate underlying assumption is that you need to know about
> > *everything* and that most basic functions of a command are beside the
> > point. The man page for grep is an excellent example. They never go
> > straight to the point. The high use examples are always buried somewhere
> > that you would least be likely to look for them. The "F" in RTFM is not
> at
> > all deserved. How can I find a file containing "x" in my home directory?
> > The question will only be answered in the most convoluted way.
>
>
> I forget the man page I was looking for once, but the option I was looking
> for
> was somewhere in 3,000 lines of gobbledegook, and I couldn't find it.. some
> of those man pages are just totally outrageous! This App I used to install
> came out with a new version, and it didn't install right. I read the
> installation guide backwards & forwards, with no help. I finally asked
> the "GURU" and he said " oh, that option is listed in the release-notes!!
>
>
> --
> Paul Cartwright
> Registered Linux user # 367800
> Registered Ubuntu User #12459
> http://usdebtclock.org/
>
> _______________________________________________
>
>
> Ale mailing list
> Ale at ale.org
> http://mail.ale.org/mailman/listinfo/ale
> See JOBS, ANNOUNCE and SCHOOLS lists at
> http://mail.ale.org/mailman/listinfo
>
>
>
>
> --
> --
> James P. Kinney III
> Actively in pursuit of Life, Liberty and Happiness
> Doing pretty well on all 3 pursuits
>
>  Faith is a cop-out. If the only way you can accept an assertion is by
> faith, then you are conceding that it can’t be taken on its own merits.
>    Dan Barker, "Losing Faith in Faith", 1992
>
> _______________________________________________
> Ale mailing listAle at ale.orghttp://mail.ale.org/mailman/listinfo/ale
> See JOBS, ANNOUNCE and SCHOOLS lists athttp://mail.ale.org/mailman/listinfo
>
>
>
> _______________________________________________
> Ale mailing list
> Ale at ale.org
> http://mail.ale.org/mailman/listinfo/ale
> See JOBS, ANNOUNCE and SCHOOLS lists at
> http://mail.ale.org/mailman/listinfo
>
>

-- 
-- 
James P. Kinney III
Actively in pursuit of Life, Liberty and Happiness
Doing pretty well on all 3 pursuits

 Faith is a cop-out. If the only way you can accept an assertion is by
faith, then you are conceding that it can’t be taken on its own merits.
   Dan Barker, "Losing Faith in Faith", 1992
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.ale.org/pipermail/ale/attachments/20100708/ed7ec967/attachment.html 