Re: manpage for GNU utilities?
Hi,
I think we can agree on the fact that shipping man pages with
out dated information is wrong, and that man pages are not always the
ideal documentation format (longer documents _are_ better as info),
but that ``standard unix'' commands should have basic docuentation in
man page formats (though a line saying "refer to the info system for
details" should be acceptable).
>>"Chris" == Chris Lawrence <quango@ix.netcom.com> writes:
Chris> On Feb 21, Manoj Srivastava wrote:
>> This is an opinion. I tend to disagree.
Chris> Well, Christian *asked* for opinions. I provided one.
quite.
>> Who needs to pull up emacs to read info pages? there is a stand
>> alone info, which is faster than lynx, and has way better search
>> capabilities than either lynx or "less".
Chris> Last I checked, it also had incomprehensible key-bindings
Chris> (which permanently discouraged me from using it) and took up
Chris> space on my hard drive that could be better used.
``Incomprehensible keybindings'' is a loaded phrase. An
equally loaded phrase is ``refusal to learn the proper tool for the
job''.
Chris> I have used info (so I do have knowledge of the tools
Chris> available), and found it a rather worthless tool for reading
Chris> documentation for those reasons; your mileage may vary.
I personally do not find the info keys incomprehensible, but I
spent some time learning how to use info, and in a number of cases
info is my preferred documentation format.
>> I understand people who say outdated man pages are bad, but lack of
>> knowledge of the tools available is no justification in a policy
>> debate.
Chris> Ok, so I have to install yet another application capable of
Chris> reading info files just to get relevant information on a
Chris> command?
I think so, yes, depending on your definition of relevant,
especially if you want the gory details.
Chris> Info is only useful for one thing: reading info files.
Ture enough. It does it well, too, in my opinion. Ain't that
the unix way? To do one thing, and do it well?
Chris> If the information was provided as a man page or a HTML
Chris> file, info wouldn't be necessary on my system.
Quite so. If all the information were provided as info files,
I would not need man on my system. In many cases I prefer reading
documentation, especially large amounts of documentation, as info
files.
Take perl for example. Comes as a bunch of man pages. How I
wish they has chosen info instead -- It takes several frustating
efforts to get information about anything at all. Perldoc is of
little help, and we do not have perlindex available for Debian.
Chris> In any event, anyone can use "man".
Anyone can use info, by that token. One has to learn how to
use a pager well (I tried it on my wwife recently. She did not think
less was intuitive)
Chris> Relevant and accurate information about the tools should be
Chris> provided on man pages.
Hmmm. You may have a point here. But in that case, a statement
like look at the info files for details should be acceptable.
Chris> Info, HTML, etc. should be for more detailed reference (a
Chris> tutorial should be provided as Info or HTML, for example).
Hmm, I think I agree.
Chris> Besides, shipping man pages that don't even have up-to-date
Chris> information on them is pretty silly, particularly ones that say
Chris> "Read the info file to actually use this program" while
Chris> blathering on for pages and pages about the options you could
Chris> have supplied to some version of the program that's eight years
Chris> old, and particularly for programs that are "standard Unix
Chris> commands," whatever that means...
Here, I tend to agree.
Chris> No commercial Unix vendor would say "Read our custom,
Chris> narrowly-supported documentation format since we can't be
Chris> bothered to write a proper man page," and whatever the FSF's
Chris> rather misguided inclincations, nor should we.
In that case, we should start writing man pages, and not just
file bug reports and leave the task to a few maintainers that are
stuck with packages with mostly info documentation.
manoj
--
On the old "You Bet Your Life" program, Groucho Marx was getting to
know one of his contestants. The man told Groucho that he had 10
children. "Why so many children?" Groucho asked. "Well, I love my
wife", the man answered. Groucho paused but a second, then said "I
love my cigar but I take it out of my mouth once in a while!"
Manoj Srivastava <srivasta@acm.org> <http://www.datasync.com/%7Esrivasta/>
Key C7261095 fingerprint = CB D9 F4 12 68 07 E4 05 CC 2D 27 12 1D F5 E8 6E
Reply to: