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 <[EMAIL PROTECTED]> 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
> [EMAIL PROTECTED]
>
>
> --
> To UNSUBSCRIBE, email to [EMAIL PROTECTED]
> with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]
>
--
Paul E Condon
[EMAIL PROTECTED]
--
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]
