Re: Help!

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

I need an editor ( person who reads my stuff and makes corrections).

On Sat, Sep 10, 2005 at 06:23:25PM -0600, Paul E Condon wrote:
> 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 
   document which will guide the reader to the answer to the question. 
                                                          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
> 
> 
> -- 
> To UNSUBSCRIBE, email to debian-user-REQUEST@lists.debian.org 
> with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
> 

-- 
Paul E Condon           
pecondon@mesanetworks.net