discuss: man pages
Subject:
Re: man pages
From:
Stein Gjoen ####@####.####
Date:
31 May 2003 22:13:05 -0000
Message-Id: <3EC947CC.10100@mail.nyx.net>
Rahul Sundaram wrote:
>
> Hi
>
> Here I am presenting my opinion on man pages and
> making a few suggestions on how LDP can deal with
> this.
>
> The GNU has been calling man pages outdated stuff and
> replaced them with info pages. Man pages cater to the
At the same time Andries Brouwer has expressed
his doubts about the info format in strong language.
Moreover he has started to translate info pages to
man pages.
> expert who already knows what he deals. If I am a new
> user trying to learn say what ls does from the command
> line, the almost infinite number of options would
> scare me off Linux for the rest of my life. We can
> either make man pages more user friendly, replace them
> with info pages or make a complete new set of
> alternative documentation (which is really heavy work)
> but I don't think that man pages in their present form
> should be given as a form of help for anybody new to
> Linux. Are info pages better?. For new users it
> probably explains much more than a typical man page
> does. It should start out with a brief explanation of
> the command. The important options first, the example
> and then the other commands and related files etc.
I believe this is attacking the problem from the
wrong direction. For new users even man in itself
might be too complicated; it is my experience that
very few know of the man -k option when they need
it the most: in the beginning.
I therefore believe the best idea is to have a few
reference sheets that show the most common commends
with the most common options in the style you suggest.
make it short so it can be put on the wall next to
the monitor.
After a while, perhaps 2 weeks, the user moves on
and is ready for the more advanced options at which
point the terse but complete man pages are all that
is needed.
There is already a Tips-HOWTO that should cover some
of this ground; could you have a look at it and post
your coments to it?
[snip examples]
>
> This probably insults the expert but would be much
> more readable to newbies. We can be redundant and
> tutorial like with no terse explanations and try to
> explain things as much as we can.
TLDP has the challenging task of offering useful
information to the novices as well as the experts.
rather than simplifying what we have I believe it
is more productive to write starting points for
the newcomers and let them progress.
Regards,
Stein Gjoen
