Re: info info; man info (documentation about info)

[Dave Kemper]

On 1/9/23, Eli Zaretskii <eliz@gnu.org> wrote:
> It is not a coincidence that the GNU project deprecated man pages in
> favor of Info manuals.

A decision that, decades on, still does not garner universal acclaim.
But I'm not here to preach the superiority of one format or another,
merely to advocate offering users the most possible options.

> Frankly, I cannot even understand how you can
> compare a linear reading through sufficiently long text, with only
> Less-style regexp search as your navigation aid, with what an Info
> reader provides when you read an Info manual.

Viva la difference!

But it's easy to understand the source of this difference.  I'm
writing in an Info forum, so it's natural that you and others here are
predisposed to prefer the Info way of doing things.  But bring this up
over on the groff forum, where man pages are a central topic, and
you'll get a rather different viewpoint.  That's where I learned this
capability, from others who found it useful, and where I've
subsequently mentioned it to others who've said they also find it
useful.

All I'm saying is, don't confuse YOUR (collective help-texinfo)
worldview with THE worldview.  The main points are: (a) the info
program can accommodate both types of users; and (b) two small
additions to the info man page will let users see both paths available
to them.  Some users, no doubt, will quickly conclude that using
"less" as an Info pager is, to quote Gavin, "defective," and never use
it again.  Others will love being able to leverage knowledge of a
pager that is usable on a variety of unwieldy documents.

Furthermore, by showing that "info" output CAN be piped, you open Info
documents up to a world of possibilities that neither you nor I can
even think of.  Even someone wanting a ballpark for something as
simple as "How does the size of the emacs manual compare to that of
the sed one?" can use it:

$ info sed | wc
$ info emacs | wc

Piping and redirecting are CENTRAL to Unix's power, and the fact that
the "info" command allows this is an important piece of information to
communicate to users (as I mentioned before, it's not intuitive, as it
is with a lot of Unix commands, because the default interface is
interactive), even if the recipient of that knowledge never once pipes
it through "less."

> An Info manual is much more than the sum total of the text in it.  The
> cross-references and the index commands make finding stuff in an Info
> much more efficient and fast, and the ability to jump to a
> cross-referenced material and then come back allows to consult the
> details without losing the context and the main subject you are
> reading on.

True, and I'm not arguing against the advantages of the info interface.

What I'm saying is that users come to tools from vastly different
contexts and backgrounds.  A user who regularly uses "less" on other
enormous files or output streams will have a toolkit of keystrokes for
doing this, will know how use marks and regular-expression searches,
replicating some of that ability (and in some cases improving on it:
by setting marks at places throughout the document, the user can jump
between them in arbitrary order rather than having to navigate forward
and back among existing links).  Let users see their options for
browsing Info manuals, and they can decide what works best for THEM.

> It's an obscure capability

But that's circular: it's obscure because it's not well documented,
and now you're saying it shouldn't be better documented because it's
obscure.

> It's
> again not an incident that the vast majority of man pages are quite
> short and dedicated to a single relatively small subject.

It's also a testament to the power of "less" that it's usable on huge
man pages like bash(1).  And if someone has learned how to use "less"
effectively to navigate and search such a page, why shouldn't they at
least be informed they can use that knowledge on Info documents?  It's
not locking them into anything if they decide the info interface is
better.  It's revealing that choices are available.

Additionally, as Alex pointed out when starting this thread, if you
give users a familiar toehold into the expansive information Info
documentation provides, they'll be more likely to explore other ways
of accessing it.

That's getting a lot of mileage out of adding one sentence and one
example usage to info(1).  Thank you for considering this.