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)<br>
<br>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.<br>
<br>The linux documentation project <a href="http://tldp.org">tldp.org</a> 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". <br>
<br><div class="gmail_quote">On Thu, Jul 8, 2010 at 11:04 AM, <a href="mailto:wolf@wolfhalton.info">wolf@wolfhalton.info</a> <span dir="ltr"><<a href="mailto:wolf@wolfhalton.info">wolf@wolfhalton.info</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">
<div>
Jim,<br>
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?<br>
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?<br>
<br>
-Wolf<br>
<br>
-----Original Message-----<br>
<b>From</b>: Jim Kinney <<a href="mailto:Jim%20Kinney%20%3cjim.kinney@gmail.com%3e" target="_blank">jim.kinney@gmail.com</a>><br>
<b>Reply-to</b>: Atlanta Linux Enthusiasts - Yes! We run Linux! <<a href="mailto:ale@ale.org" target="_blank">ale@ale.org</a>><br>
<b>To</b>: Atlanta Linux Enthusiasts - Yes! We run Linux! <<a href="mailto:Atlanta%20Linux%20Enthusiasts%20-%20Yes%21%20We%20run%20Linux%21%20%3cale@ale.org%3e" target="_blank">ale@ale.org</a>><br>
<b>Subject</b>: Re: [ale] I am so tired of Linux Fanatics<br>
<b>Date</b>: Thu, 8 Jul 2010 09:36:43 -0400<br>
<br>
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.<br>
<br>
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. <br>
<br>
at least there _were_ release notes!<br>
<br>
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.<br>
<br>
And from that was born Ubuntu.... :D<br>
<br>
On Thu, Jul 8, 2010 at 7:34 AM, Paul Cartwright <<a href="mailto:ale@pcartwright.com" target="_blank">ale@pcartwright.com</a>> wrote: <br>
<blockquote>
On Wed July 7 2010, Jim Philips wrote:<br>
> The problem with RTFM is the assumption that the fine manual was well<br>
> written in the first place. I have been using Linux since 1995 and I have<br>
> always felt that the man pages were written in exceptionally poor fashion.<br>
> The immediate underlying assumption is that you need to know about<br>
> *everything* and that most basic functions of a command are beside the<br>
> point. The man page for grep is an excellent example. They never go<br>
> straight to the point. The high use examples are always buried somewhere<br>
> that you would least be likely to look for them. The "F" in RTFM is not at<br>
> all deserved. How can I find a file containing "x" in my home directory?<br>
> The question will only be answered in the most convoluted way.<br>
<br>
<br>
I forget the man page I was looking for once, but the option I was looking for<br>
was somewhere in 3,000 lines of gobbledegook, and I couldn't find it.. some<br>
of those man pages are just totally outrageous! This App I used to install<br>
came out with a new version, and it didn't install right. I read the<br>
installation guide backwards & forwards, with no help. I finally asked<br>
the "GURU" and he said " oh, that option is listed in the release-notes!!<br>
<br>
<br>
--<br>
Paul Cartwright<br>
Registered Linux user # 367800<br>
Registered Ubuntu User #12459<br>
<a href="http://usdebtclock.org/" target="_blank">http://usdebtclock.org/</a><br>
<br>
_______________________________________________<br>
<br>
<br>
Ale mailing list<br>
<a href="mailto:Ale@ale.org" target="_blank">Ale@ale.org</a><br>
<a href="http://mail.ale.org/mailman/listinfo/ale" target="_blank">http://mail.ale.org/mailman/listinfo/ale</a><br>
See JOBS, ANNOUNCE and SCHOOLS lists at<br>
<a href="http://mail.ale.org/mailman/listinfo" target="_blank">http://mail.ale.org/mailman/listinfo</a><br>
<br>
</blockquote>
<br>
<br>
<br>
-- <br>
-- <br>
James P. Kinney III<br>
Actively in pursuit of Life, Liberty and Happiness <br>
Doing pretty well on all 3 pursuits <br>
<br>
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.<br>
Dan Barker, "Losing Faith in Faith", 1992 <br>
<br>
<pre>_______________________________________________
Ale mailing list
<a href="mailto:Ale@ale.org" target="_blank">Ale@ale.org</a>
<a href="http://mail.ale.org/mailman/listinfo/ale" target="_blank">http://mail.ale.org/mailman/listinfo/ale</a>
See JOBS, ANNOUNCE and SCHOOLS lists at
<a href="http://mail.ale.org/mailman/listinfo" target="_blank">http://mail.ale.org/mailman/listinfo</a>
</pre>
<br>
</div>
<br>_______________________________________________<br>
Ale mailing list<br>
<a href="mailto:Ale@ale.org">Ale@ale.org</a><br>
<a href="http://mail.ale.org/mailman/listinfo/ale" target="_blank">http://mail.ale.org/mailman/listinfo/ale</a><br>
See JOBS, ANNOUNCE and SCHOOLS lists at<br>
<a href="http://mail.ale.org/mailman/listinfo" target="_blank">http://mail.ale.org/mailman/listinfo</a><br>
<br></blockquote></div><br><br clear="all"><br>-- <br>-- <br>James P. Kinney III<br>Actively in pursuit of Life, Liberty and Happiness <br>Doing pretty well on all 3 pursuits <br><br> 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.<br>
Dan Barker, "Losing Faith in Faith", 1992 <br><br>