Re: General complaint about GNU's preference for "info" versus "man"

[Stepan Kasal]

Hello,

On Fri, Apr 21, 2006 at 01:56:26PM -0700, address@hidden wrote:
> Man pages should be complete and should also be the primary source of 
> online documentation, [...].  I have been a Unix user since 1990, [...]

I understand your feelings.  And yes, I use man pages as a reference
manual, for the basic explanation of a tool.

And yes, I don't like the ``the above is not true, read info'' sentences
added to each manpage.

In ancient times, the GNU project tried to replace manpages by the info
system.  Though this has some resonance among emacs users, in general the
concept failed, and I think it's time to accept that manpages will exist
forever, as Fortran will.  ;-)

But I think that the man format can not hold all the information.

When Unix started, it was a bunch of simple programs, each of them was
simple enough to be described in one page.

But I'm afraid that things which don't fit this schema appeared very soon:
when was awk invented?

GNU awk comes with a complete man page, which is good, yet it is not the
best manual possible.  It comes also with it's texinfo manual, which is
a hypertext-version of a nicely written book, which teaches you the issues
very gently, yet it also serves as a reference manual.  In both these roles,
the hyperlinks come very handy.

Another documentation which shows that the man format don't fit ideally
for it is procmail.  Do you feel it is right that I have to remember that
the tutorial is invoked by ``man procmailex''?

Then you have the manual for Autoconf: besides documenting the usage of
the programs delivered, which fit the manpage framework perfectly, there
is a long section about portable shell programming.  That wouldn't fit into
manpages very well.

The Automake manual is another example of thing which benefits from being
written in a sane hypertext markup.

Yes, there were attempts to abuse the manpage system to ``make it do''.

TCL/Tk abused the section for C library calls, and placed more than 700
new manpages there.  Others create new sections, which is more sane.
But both of these solutions pollute the namespace.  Would you still
consider man so handy if ``man -a open'' would displayed dozen pages?

Then there is Perl, which somehow combines the above two:
the Perl itself brings more than hundred perl* pages to section 1,
and then there is the 3pm manual section.

All the above examples how that there is huge amount of documentation
which doesn't belong to manpages.

> It is counterproductive to have two distinct and seperate sets of
> information for the same command... [...]

Actually there are three: info, man, and --help.  Each of them has
it's role, --help is always at hend, but it's too terse to be usable.
The manpage is a quick handy reference.  And then there is the whole
manual, written in a full-fledged hypertext markup.

Yes, there should be one ultimate source for the three.  Naturally, it
should be the biggest one, the shorter ones should be excerpts.
AFAIK, no one has solved this.

BTW: I'd like to speak against help2man here: the above explains that
man should have more information than --help.  help2man creates too
terse manpage from too long --help.  (The --help need not otherwise
list all options, or could rely that the names of some are
self-explaining.)

So the problem is clear:
how can one have one ultimate source for info, man and possibly also
--help?
I think that a well-written proposal could be of great help.

Have a nice day,
        Stepan