discuss: Thread: man pages

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

Rahul Sundaram wrote:
> 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.

I think there are two different needs here that are best addressed with 
two different sets of documentation.

When learning how to use Linux, users need tutorial documents. The HOWTOs 
and web sites are generally good for teaching. They offer lots of 
explanations and examples, which is exactly right for learning a new tool.

But when trying to remember how to use a command that I'm already familiar 
with, I do not want to wade through pages and pages of HOWTOS or search 
all over the Web. A terse, but comprehensive man or info page is just right.

Tony
-- 
Anthony E. Greene ####@####.####
OpenPGP Key: 0x6C94239D/7B3D BD7D 7D91 1B44 BA26 C484 A42A 60DD 6C94 239D
AOL/Yahoo Chat: TonyG05   HomePage: <http://www.pobox.com/~agreene/>
Linux. The choice of a GNU generation. <http://www.linux.org/>

Greg Ferguson wrote:
> While on the topic - would people be interested in a collection of man 
> pages (filtered to HTML via man2html; browseable, etc.) on the LDP site?

GNOME includes a tool to do this locally on a machine. Using Galeon, I can 
enter a URL like this:

   man:less

to view the manpage for 'less'. It also works for GNOME Help pages 
(ghelp:subject). I tried it with GNU info pages, but I don't remember the 
results.

Tony
-- 
Anthony E. Greene ####@####.####
OpenPGP Key: 0x6C94239D/7B3D BD7D 7D91 1B44 BA26 C484 A42A 60DD 6C94 239D
AOL/Yahoo Chat: TonyG05   HomePage: <http://www.pobox.com/~agreene/>
Linux. The choice of a GNU generation. <http://www.linux.org/>

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1


On Thu, 15 May 2003, Anthony E. Greene wrote:

> Greg Ferguson wrote:
> > While on the topic - would people be interested in a collection of man 
> > pages (filtered to HTML via man2html; browseable, etc.) on the LDP site?
> 
> GNOME includes a tool to do this locally on a machine. Using Galeon, I can 
> enter a URL like this:
> 
>    man:less
> 
> to view the manpage for 'less'. It also works for GNOME Help pages 
> (ghelp:subject). I tried it with GNU info pages, but I don't remember the 
> results.

Yes, and there are several other possibilities, but it would be nice to 
have them online for people who don't have a working Linux system at hand, 
I think.  Sometimes.

Tille.



- -- 

My Penguin, my freedom.		http://tille.soti.org

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.6 (GNU/Linux)
Comment: For info see http://www.gnupg.org

iD8DBQE+w7vgsIIUbMXbBA8RAjPLAKCx1mgoUkp8I8SwegB2OrAnWhDUfwCgkx3p
syZdNPiXZo7Uj3fxDB/GmOk=
=K0iy
-----END PGP SIGNATURE-----

You raise some outstanding points.

   > 	The GNU has been calling man pages outdated stuff and
   > replaced them with info pages.

The GNU info browser (in my unesteemed opinion) is confusing for anyone
not familiar with the Emacs way of doing things. The paging is the
biggest problem; it's very easy to get stuck at the end of a page if you
don't remember the correct combination of keys. The one thing it does
well is allow moving between cross-referrenced *-headings. Pinfo is
better, but how is a newbie going to know to use that program
preferrentially?

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

Some manpages are like this. Most aren't. Maybe this is a formatting 
issue as opposed to a content issue?

   > We can
   > either make man pages more user friendly, replace them
   > with info pages

I've been disappointed with most of the info pages I've consulted. The 
info page in question is usually a) marginally more readable, b) less 
comprehensive, or c) doesn't exist for the program in question. (Rarely 
they do get it right, though, as in the textutils documentation.)

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

IMHO we need a new form of documentation like we need another linux
distro. Writing and compiling it would consume hours of volunteer work
that more efficiently used refining documentation that's already there.
If the system's not broken, should we fix it with a gnu one that's
worse? ;^) If manpage authors would simply expand on their documents I
daresay there would be no issue.

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

Interesting. When I consult documentation it's usually to have a
question answered or to learn about an application. I doubt people sit
down to read man/info pages like a novel. My biggest gripe with all
documentation is that it is incomplete and/or it doesn't give enough
examples. So how would you decide on the content to cut when even a
newbie might have a relatively specific question? I suggest instead a
well-written manpage for everyone to consult from the start that is the
standard reference for that application, sort of a definitive text
complete with hints, examples, etc., but synopsis and options for the
experienced and impatient.

How do we get better manpages? Maybe TLDP should offer to preview, proof
or rewrite manpages at the discretion of the author. I'm sure a lot of
developers wouldn't object, and for those who write substandard manpages
and don't participate, maybe a 'manpage hall of shame' could be used to
pressure offenders.

I was a newbie only a few short years ago and remember it well, so I
feel somewhat qualified to comment on the subject.

hs

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On Thu, 15 May 2003, Howard Shane wrote:

> How do we get better manpages? Maybe TLDP should offer to preview, proof
> or rewrite manpages at the discretion of the author. I'm sure a lot of
> developers wouldn't object, and for those who write substandard manpages
> and don't participate, maybe a 'manpage hall of shame' could be used to
> pressure offenders.

Well yes, and make it known that there is such a service, in case people 
only want to develop programs and are no natural born writers.  I know a 
lot of those.  The form under which the doc is made available (man/info 
page, --help, apropos, graphic browsers, ..) is less important than the 
general accessability.
 
However, if you say the daily publishing rate at freshmeat, sourceforge 
and other software sites, I imagine we will need an awful lot of 
volunteers.

Tille.

- -- 

My Penguin, my freedom.		http://tille.soti.org

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.6 (GNU/Linux)
Comment: For info see http://www.gnupg.org

iD8DBQE+w+CEsIIUbMXbBA8RAqW7AJwMHKPTXzqGU9LRpK2w3XrlM+nGgACgp1ib
QzHcITJ76tlYrMX3NOsVvvc=
=Tku0
-----END PGP SIGNATURE-----

* Howard Shane; ####@####.#### on 15 May, 2003 wrote:
>I've been disappointed with most of the info pages I've consulted. The 
>info page in question is usually a) marginally more readable, b) less 
>comprehensive, or c) doesn't exist for the program in question. (Rarely 
>they do get it right, though, as in the textutils documentation.)

Well said, being able to program does not necessarily mean being able to
document what is intended. IMHO 95% of info and man pages do suck and
thats one of the reasons I pay X amount of dollars to publishers like
Oreilly to get a better documentation of what I should have already by
having the program.



-- 

Togan Muftuoglu

Anthony E. Greene wrote:

> Greg Ferguson wrote:
> 
>> While on the topic - would people be interested in a collection of man 
>> pages (filtered to HTML via man2html; browseable, etc.) on the LDP site?
> 
> 
> GNOME includes a tool to do this locally on a machine. Using Galeon, I 
> can enter a URL like this:
> 
>   man:less
> 
> to view the manpage for 'less'. It also works for GNOME Help pages 
> (ghelp:subject). I tried it with GNU info pages, but I don't remember 
> the results.
> 
> Tony

KDE Konqueror does the same. Just enter "man:less" (or "man:/less")
into the address field. It also handles GNU info pages ("info:/info")
very well -- finally I was able to read them, because there are
hyperlinks "Which Just Work (tm)". KDE help pages and manuals are
shown with "help:/kdeprint" for example.

Cheers,
Kurt

On Thu, May 15, 2003 at 03:58:02PM +0100, Rahul Sundaram wrote:
> Here I am presenting my opinion on man pages and making a few
> suggestions on how LDP can deal with this.

This is part of the overall problem of integrating Linux documentation.
It's a big project that needs at lot of volunteer effort which the LDP
hasn't available at present.

> 	The GNU has been calling man pages outdated stuff and
> replaced them with info pages.
But I think they are still more widely used that info pages.
> Man pages cater to the expert who already knows what he deals. 
Not always.  Some are tutorial with examples, etc.

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

If you type ls --help it shows all the options and then by using
<shift><PageUp> you can go scroll back to the first screenfull of them.
The large number of options also illustrates the power of Linux.

[snip]
> /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).

Use <shift><PageUp> to read what scrolled by too fast.
<shift><PageDown> scrolls back down. 

			David Lawyer

Sure, rewriting all documentation seems like a good idea, lol, I don't think 
so, there's no way the LDP has time to create a simplified manual page for 
every existant tool.
Sure, I think the idea is great but its not practical, I mean you could 
rewrite pages for the core utilities.
My HOWTO does this (to a point, its not designed to be a man page rewrite of 
every existant tool).
The GNU/Linux Tools Summary HOWTO is hosted here:
www.karakas-online.de/LinuxCommands/t1.html

So if you did want to go ahead with the idea feel free to reference material 
from there.
The idea is good but I don't think its very practical to carry out........
Also we don't need to get rid of man pages (as previously stated by someone 
else) they are important for power-users and administrators, we simply need 
a simplified version of man pages for new users.....

_________________________________________________________________
ninemsn Extra Storage is now available. Get larger attachments - 
send/receive up to 2MB attachments (up to 100 percent more per e-mail). Go 
to  http://join.msn.com/?page=dept/home&pgmarket=en-au