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

On Mon, Jan 09, 2023 at 03:36:44PM -0600, Dave Kemper wrote:
> 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.

It should be noted that the info manpage is automatically generated
from the output of "info --help" and so is necessarily short and not
comprehensive.  "info --help" should only tell about the most important
options: the more that is in there, the less useful it becomes.

> 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

Yes, interesting, but not so useful that it deserves a place in the
help message.  If we document every tip or trick that somebody thought
was useful, then it would become a disorganized pile of junk.

It should be documented, which I didn't see that it was before, so
I've added the following text to info-stnd.texi:

     If Info is invoked when its standard output is not a terminal, it
  does not attempt to start an interactive session; rather, it writes the
  contents of the loaded nodes and subnodes to standard output, as if the
  ‘--output=-’ and ‘--subnodes’ options were given.  This can be used to
  pipe the contents of Info nodes to another program, such as a pager.

Hopefully that is sufficient and correct.

However, there is an example in "info --help":

 info --subnodes -o out.txt emacs
                               dump entire emacs manual to out.txt

If we changed this to

 info --subnodes -o - emacs    dump entire emacs manual to stdout

then the users would be close to figuring out

 info --subnodes -o - emacs | less

as a possibility for themselves.  (It would also save a line.)  I
like the idea of changing this, but maybe somebody has a comment?

> It's also a testament to the power of "less" that it's usable on huge
> man pages like bash(1).

That's not my experience.

For example, I regularly check the perlfunc(1) man page to look up
information on Perl builtins, and find I have to use search expressions
like "^ *shift" to go to the documentation of the "shift" function,
knowing from experience which search expression works for this manual,
otherwise I have to look through several extraneous matches.

If I could type "info perlfunc shift" from the command-line, this
would be much easier.

Another example: compare "info bash param" with "man bash" followed
by /param.  I can get to the documentation on the different types
of parameter expansion much quicker with info.  Even once I discover there
is a section called PARAMETERS, searching for this string (in caps) leads
to extraneous matches of other cross-references to that section.  (I
guess I should have used ^PARAMETERS instead.)  However, that section is
still not what I want.

If I had searched for "parameter" in the bash man page, I would have
missed several occurences of this word due to the word being split
across lines, as in "parame-ters".

Finally I realise I should be searching for "parameter expansion" and
I find what I am looking for.  There is a heading "Parameter Expansion",
but it's not clear if this is a subsection of a larger section - I have
to page up several times to find the EXPANSION heading.  This shows that
it is harder to understand the context of particular parts of a manual,
whereas in Info I could have just pressed "u" to see the containing section
followed by "l" to go back.