On Sat, Sep 10, 2005 at 10:28:52AM -0700, David E. Fox wrote: > On Thu, 8 Sep 2005 10:52:50 -0600 > Paul E Condon <[EMAIL PROTECTED]> wrote: > A C compiler is perhaps more relevant to this discussion, and it > permits me to interject a point. When the average user wants to compile > "Hello World", for instance, doing it by reading "man gcc" often does > not prove useful. Why? Because "man gcc" (as many other man pages for > Unix systems) lists all possible ways to use "gcc". In practice, most > users will not use nearly all those options, and somewhere, buried in > the man page, there exist instructions on how to compile a simple > program: > > $ cc -O -o hello hello.c (or even simpler, remove the -O) > > Man pages (generally) don't progress from simple usages to more complex > ones - they present in toto everything all at once. I saw that early on > by reading "man bash".
Which is of course they the GNU people prefer info pages :-P
Seriously, the standard man page format wasn't designed for mass usage,
it was for the sysadmin who needed a reference to remind them of some
obscure (or not) feature they had forgotten, not to teach the usage of
the command. Of course some commands (like bash) are really not
amenable to the man format (I hate trying to find anything on really
long man pages like the bash one) because they do too much (to be
explain in a single reasonably sized page). It'd be
like trying to explain everything about 'how to use' gcc in a man page.
The gcc man page recognizes that and simply lists the options available with
a minimum of comment; the bash man page is an abomination.
Of course now everyone tells newbies 'read the man page' which is of
course just silly. Assuming a package is actually documented they
should be told to go to /usr/share/doc/package-doc{/html/index.html}
where presumably it actually has useful information on using the package
for people who haven't used the program before.
Some man pages have basic beginning instructions, but that depends on
the philsophy of the document writer wrt what a man page should be.
signature.asc
Description: Digital signature
