discuss: man pages
Subject:
man pages
From:
Rahul ####@####.####
Date:
15 May 2003 14:58:05 -0000
Message-Id: <20030515145802.69786.qmail@web8004.mail.in.yahoo.com>
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
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.
An example would demonstrate my point
This is the present form
“
Man less
Less- less is opposite of more. (supposed to be brief
information)
More geeky information here
Alphabetical list of options with no indication of
what is more commonly used
Optional examples – most probably not there
Files
Bugs
Author information”
Ya this is probably some very funny guy expressing
his classic nerd jokes and pun but what am I supposed
to learn from this. More is definitely not opposite of
more and even will not be able to understand what less
does that soon from the man pages. My initial reaction
would be “ what – less is opposite of more”. So? What
the heck? I would get bogged down with options, bored
and irritated with the terseness and give up in
frustration.
Here would be my idea of writing a friendly man page.
Man less
Less – less is a command that can also act as a filter
used for viewing information one screen at a time. It
is similar to the more command but has the capability
to move both back and forward when viewing
information. Users can scroll through any text
information.
For example,
/Cat myfile.txt/ - would display a text file on
screen but you can only see the last part if the file
contains more information than what would typically
fit in a single screen(24 lines).
Less myfile.txt
This command would display the file “myfile.txt” one
screen at a time (ie) if the file has more information
than can be displayed in a single screen it would wait
for the user to scroll through the document using
arrow keys. You can use q to quit reading.
It can also be used a filter. For example,
Rpm – qa lists all the packages installed in your
system. This would probably not fit in a single
screen. So we can use
Rpm –qa | less
For viewing information one screen at time. Here less
acts a filter.
Good list of examples
More relevant options in probable order of usage
Bugs
Author information.
Web links to latest copy in LDP?
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.
One more issue with man pages is how relevant they
are. Like I said a alphabetical listing of options is
irrelevant most of the time. How am I supposed to
understand which of the ls umpteen options are
probably more useful?. The command should illustrate
common usage patterns and help the users understand
not only how but also why a command is usually used.
For example,
The man page for cat says that it is used to
concatinating files. This is definitely true but is it
relevant to the user?
We all know that cat is more used for displaying files
and also that the less command is more appropriate for
that usually. So why isnt it reflected in the man
pages. We can start such a project specifically to
rewrite or write an alternative set of documentation.
If we are writing an alternative set, we don’t need to
mention each and every command, we can start off with
the important stuff and refer users to man pages for
more advanced stuff.
If we are writing an alternative set,
The format can either be the man or info page formats.
Why?
We can concentrate on writing documentation and
existing tools would be able to use the stuff we
write without any changes.
Example:
help less
Would display user friendly “helpful” information
while internally using man or info/ pman or pinfo.
Today when I don’t know something about a command,
asking someone else who does know how it is used is
much better than going through the comprehensive but
terse manual pages. I think this should change.
Let me know what you people think of all this.
Regards
Rahul Sundaram
________________________________________________________________________
Missed your favourite TV serial last night? Try the new, Yahoo! TV.
visit http://in.tv.yahoo.com
