discuss: man pages
Subject:
Re: man pages
From:
Howard Shane ####@####.####
Date:
15 May 2003 18:35:40 -0000
Message-Id: <3EC3DDE3.2060902@charter.net>
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
