Re: Help!

[Paul E Condon <pecondon@mesanetworks.net>]

On Sat, Sep 10, 2005 at 05:56:32PM -0400, C Shore wrote:
> 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 <pecondon@mesanetworks.net> wrote:

The stuff below is not what I wrote. What I wrote has been snipped in its
entirety

> > 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

Man pages are one form of documentation. Other forms are Tutorial,
Administrator's Guide, User's Guide, comments in the source code,
etc. Documentation comes in many levels, and should come in many
levels. Man pages are one of them. For the C++ compiler, the book
by B. Stroustrup is some of the documentation.

> > 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". 

There is a strict format for man pages. This format is inappropriate for
some programs, but I believe that there are good reasons for sticking to
the strict format even when it is inappropriate. And, especially when that
format is inappropriate, there should be other documentation. Hopefully,
the developers of the software include a person who is capable of writing
natural language and this person is assigned the task of documenting the
software at all appropriate levels, and writing a format standard compliant
man page. 

In reality this is often difficult for computer geeks, more difficult than
producing an intuitive GUI. But it should be done as best they can.

> 
> 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 

It was, I think, designed at Bell Labs by the originators of UNIX. In
those days, everyone who was allowed to touch the console was ipso facto
a sysadmin, and they designed it for themselves. (The term sysadmin had
not yet been invented, I believe.)

> 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 

I don't think so. Mostly I see 'RTFM', not 'RTFMP'. Telling anyone, 
'RTFM' is never appropriate. An explicit reference to a But that isn't the
issue that prompted all this heated discussion. The issue was the
claim that a newbie should not have to read _any_ documentation in
order to use the software. I think you will find that opinion in the
archive of this thread. That opinion is, IMHO, silly. It is also silly
to suppose that the man page is the only documentation that is
necessary.

> 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.
> 

See comments, above, about strict format of man page. Mostly, I see the
writers being more or less capable of sticking to that format. Think of
writing man pages as an English language geeky variant of writing haiku.
Its not easy for everyone.

> 


-- 
Paul E Condon           
pecondon@mesanetworks.net