Re: Gripes with "info" Command

[Eli Zaretskii]

> Date: Fri, 7 Apr 2006 19:11:49 +0200
> From: Stepan Kasal <address@hidden>
> Cc: Dave Jarvis <address@hidden>
> 
>   Eli thinks that the problem is that Dave doesn't know the various info
> readers well enough.  I think that the problem might be that we know them
> too well, and we are not open for views which look at out current
> practice from distance and show what is obviously broken.
> (I have the impression that Dave knows enough details, he just haven't
> list the perspective.)

My problem with Dave wasn't complaints about Info, it was _useless_
complaints.  He seems to think that a Help system should assume no
prior knowledge on the user's part.  For example, he saw a problem in
the fact that "info --help" and "info --usage" do different things,
whereas ``info'' and ``help'' are synonyms.  (And this is only an
example of his approach.)

To me, this sounds incredibly silly.  It should be quite obvious to
anyone involved in this business that using modern computers requires
_gobs_ of contextual knowledge and jargon/slang.  Info documentation
tries to do many things, but one thing it does _not_ try to do is
teach users all this initial knowledge, and nor should it try to, IMO.

Another example of Dave's unconstructive approach is his insistence
that only Unix and GNU systems have this problem, while MS-Windows
doesn't.  That's simply not true.  Try typing "help" at the Windows
command prompt, and you will see something very similar to what Bash
displays.  And the GUI Help system is not much better.  For example,
its opening screen doesn't give me a clue where to find information
about code development support tools.  In fact, I find the opening
screen quite useless.

Now, it is easy to mock _any_ software, and it is especially easy to
mock a Help system which starts with a tutorial about itself.  Such
bootstrap style situations are notoriously hard to get right, and the
Info manual about itself did indeed change in major ways during the
years, as user experience and comments poured in.  It (the Info
tutorial) is still evolving.  What we need is constructive
suggestions, not silly mocking.

As for being ``not open to differing views'', you, Stepan, and others
should know that this is about the last thing the Texinfo project can
be accused of.  Several major features were added to Info over the
years because users were unhappy with some aspects of Info's behavior.
Examples include the --usage and --vi-keys options.  If the critique
is serious and specific, it is received with an open mind.

> I use good old man.  Yes, it's not hypertext

FWIW, Emacs makes man pages behave as hypertext.

> and it's not suitable for
> viewing the whole books of technical documentation (called Texinfo in
> our GNU-speak), but it is sufficient as a ``help''.

IMHO, man pages are only sufficient for learning the command-line
switches.  They never explain any background about the programs, and
almost never say anything besides the bare-bones switches.  It is
impossible to _learn_ about a package you never used from man pages
alone, unless it is a very simple program or package.

> I'm afraid we should admit to ourselves that at our times, the
> hypertext browser area is dominated by HTML browsers, so we should
> just use one.

HTML browsers are not a good substitute for Info because they lack
several extremely useful and efficient commands, such as the index
search commands and the apropos features.  Without these features, all
one can do with a manual is to search its entire text for strings, or
try to find what one wants by traversing the TOC.  In large manuals,
this is simply too inefficient.  When I want to find something in a
manual, if I cannot find it in a matter of seconds, I become very
irritated, because I cannot afford wasting many minutes on fruitless
searches through gobs of material I have no interest in.  If something
like that happens in an Info manual, it generally means that one or
more index entries are missing.  Fortunately, most large Info manuals
are very well indexed.

> When I need a documentation for a command, I use `man' or google.
> There are two exceptions where I use the Info system: the autoconf and
> automake manual.  I don't use emacs to access it: I;m afraid it would
> take a few seconds for start, and I'm afraid I'd have to press C-xC-c
> instead of q.

Emacs is supposed to be always running; if you don't use it for your
routine work, starting it just for Info is not for you.

> I use the info command, for example `info autoconf' it brings me to
> the usage page[1], and I press `u' twice to get to (Autoconf)Top.
> Then I hold downarrow to get to `Portable Shell' section, Enter,s
> then I hold downarrow for another two seconds to get to the menu below
> the text and choose one of the last three items.

That's a terribly inefficient use of Info.

> This procedure seems to contain some moves which are just a waste of
> time.  I think I should do something about it, prehaps install the HTML
> versions of Autoconf and Automake manuals, and make a few bookmarks.

Emacs supports bookmarks.  And if you are willing to add bookmark
support to Info, I'm sure Karl will gratefully accept patches.
However, this:

> (If it were possible to have bookmarks in the standalone info browser,
> I would still hesitate to learn another bookmark system.)

seems to say that you don't really want bookmarks in Info, all you
want is HTML.  Fine, that's your prerogative, but please don't try to
convince us heavy Info users, who are accustomed to its superior
search capabilities, that HTML is the way of the future.

> I just tried ``info awk'' now: it brings me to ``man gawk'', because
> in the ``man'' world, there is an alias, but not in the dirlist file.

Either you have an old Gawk version installed or this is an
installation problem on your machine, because gawk.texi I have does
have 2 dir entries, one for gawk and another for awk.

> I tried the pinfo command, and I'm not happy with it:
> 1) The description of the package in my description says that it is
> better because it looks like lynx.  Then it is better to use the
> HTML format of Texinfo manuals, and a browser of my choice, perhaps
> lynx, perhaps something which better matches my needs.
> 2) `pinfo autoconf' brought me the man page (it seems it doesn't use
> /usr/local/share/info/dir) and I wasn't able to access the dir node,
> neither by `t', nor by `d', so I hit `q'.

Try tkinfo, then, perhaps it will suit you better.  (I myself use
Emacs exclusively, when I'm in a GUI environment, and in text only
environment the stand-alone Info is very adequate for what I need.)

> GNU official positions seems to be that the info system is phasing
> out the man pages.  (Perhaps the feeling is that the `man' is too
> UNIXy and thus not ``free enough.'')

No, the GNU project thinks that man pages are simply not good enough
as documentation.  However, please note that this is an entirely
different issue: this thread is not about documentation quality of the
Info _manuals_, it is about user interface and efficiency of the Info
_readers_.

> I'd agree with Dave that it's time to phase out Info output format.

If there's a better format, maybe.

> Using an HTML browser for accessing the Texinfo manuals seems to be
> more reasonable.

I tried to explain above why it isn't, at least for me.

> I think some distribution use a local web server for help system.  I
> don't think it's that bad, beacuse you can easily install a local
> search engine into it.

Given enough time and effort, one can do _anything_.  The question is
not what _can_ be done, the question is what works out of the box.
Let's not forget that most people don't have time to hack every
deficiency they bump into, they usually have some real work to do and
some real deadlines to meet.  When I need to find something in the
docs, I need it _now_, and installing a search engine and tuning it is
something I cannot afford wasting my time on.

> [2] It seems that the distribution adds a symlink
>       /usr/share/man/man1/awk.1.gz -> gawk.1.gz
> it's not the gawk itself.  But again, why is the direntry missing?

I don't know.  It's something specific to your machine, cause on mine
there are both gawk and awk direntries

> because no one notices, man has still much bigger impact than info.

I suggest not to jump to such general conclusions based on your single
machine.  I'd say no one notices because no one but you have this
problem ;-)