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

[Arsen Arsenović]

Hi,

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Dave Kemper <saint.snit@gmail.com>
>> Date: Mon, 9 Jan 2023 15:36:44 -0600
>> Cc: arsen@aarsen.me, alx.manpages@gmail.com, g.branden.robinson@gmail.com, 
>>      help-texinfo@gnu.org
>> 
>> 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.
>
> There are people who weren't yet exposed to the superior power of
> Info, because no one could be bothered telling them the main points
> and punch lines.  And then there are old habits that die hard.
>
> The GNU project has as its _policy_ to prefer Info documentation.  We
> are executing this policy because we fully agree with it, but even if
> we didn't agree, when we accept the nomination of maintainers of some
> GNU package, we promise to uphold these policies.

This is what this thread ought to be addressing.  The main points and
punch lines should come front and center (say, in the first visible
screen of the tutorial, or even in help2man output).

Also, I didn't realize this before it was mentioned here, but yes,
``(info)Help'' indeed comes with EMACS.  Perhaps we should include a
copy in the Texinfo distribution too, or encourage downstreams to
extract info.info out of EMACS, so that those installing info but not
EMACS (which is rather common) have immediate access to the tutorial.
Eli, Gavin, what do you think about that?

>> 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.
>
> This is not Texinfo preference, this is the preference of the GNU
> project as a whole.  You are supposed to hear about this policy being
> upheld in any GNU forum.  And Groff is itself documented in an Info
> manual, btw.
>
> Don't get me wrong: I _love_ Less.  I use it every day, and at the
> time contributed to its development.  I just prefer not to use it for
> reading documentation when an Info manual is available, that's all.
> And I always explain to the uninitiated the most important and
> powerful commands of Info, with some success.

Indeed, this isn't a jab at less(1).  It's a great pager - but a pager
isn't a documentation viewer (or, similarly, a documentation viewer isn't
solely a pager).

>> All I'm saying is, don't confuse YOUR (collective help-texinfo)
>> worldview with THE worldview.
>
> See above: it's not our view, it's a policy that we must uphold.
>
>> 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.
>
> But we don't _want_ users to use Info like that.

Teaching this technique by default would, indeed, result in users
hindering themselves.  I'm afraid this might be the status quo
currently, though, as people are unaware of how to use Info to its full
power, whether that's because EMACS-like controls are unfamiliar, or
because it's a non-graphical program, or because users instinctively
prefer HTML despite it being less navigable, ...

This, I feel, is an important area of improvement.

>> 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."
>
> I disagree that it's an important piece of information.
>
>> > 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.
>
> All of these capabilities have direct equivalences in Info.  Users are
> better off learning how to use an Info reader, and use it efficiently,
> than learning about piping from Info.

I must say that, years ago, as I just started using GNU, less(1) did not
come naturally to me.  There's a valid argument to make about supporting
more less-like keys such that users accustomed to less can get into info
easier.

--vi-keys is indeed not in the (roff) manual for info, presumably
because it's also not in info --help.  I think this flag should be added
there, along with maybe also including vi-key equivalents in the
tutorial.  I'd like to hear your thoughts on this, Dave, and the general
experience of info with --vi-keys.

>> > 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.
>
> No.  It isn't documented well because we consider it obscure and not
> worthy of more detailed documentation.  There's no circle.  A circle
> would mean that it's obscure because the Texinfo maintainers aren't
> familiar with it, and they aren't familiar because it isn't
> documented.  That is not the case: I personally know about this
> capability since very long ago, and used it once or twice during the 3
> decades I'm using Texinfo and help developing it.
>
>> 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?
>
> Because there are much better ways.  For example, any large Info
> manual should never be (and usually isn't) read in its entirety more
> then once.  Thereafter, people should use index-searching commands to
> quickly and efficiently find the subject of their current interest.
> There's nothing even approaching this capability in the "pipe-to-Less"
> method.  How do you read even the Groff's manual, let alone something
> like Emacs or ELisp (or even Texinfo) using this method? what do you
> search for to skip irrelevant stuff, without the help of a
> well-thought index?
>
> Our efforts to improve the Texinfo documentation are better spent on
> making these aspects of Info more easily discoverable and more widely
> known, than on advertising obscure options that keep users from
> discovering and using Info.

I must say, bash is a particularly good example of why less(1) is not
powerful enough to read documentation beyond what can be considered a
reference.  Before getting accustomed to working with Info, I can't
recall a single decent experience searching through manuals for a
builtin, or worse, a flag.  Manuals are hugely hindered by the lack of
indices, links and, broadly, structured jumps.

>> 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 why the Info reader has the vi-keys option.  (You are talking
> to the person who suggested adding that option to Info and implemented
> its first version, back in 1999.  If you examine the key bindings
> under that option, you will discover that quite a few of them mimic
> Less, and that is also not a coincidence.)  I consider _that_ to be
> the proper way of reaching out to users of Less and helping them open
> up and eventually migrate to Info.

+1

It's valuable to give users something familiar, but there's no reason to
encourage them to heavily hinder their workflow.

>> That's getting a lot of mileage out of adding one sentence and one
>> example usage to info(1).  Thank you for considering this.
>
> I don't mind a single sentence (and it's Gavin's call after all), I'm
> just saying that the issue at hand is not a sentence, the issue is the
> clash of two different philosophies.


Apologies for my lack of response and initiative, I am quite busy
currently, but I hope we can get productive results in the field of
making Texinfo more approachable to those accustomed to manuals and
other documentation systems.  The latter part is also what's driving
some of my motivation behind improving the HTML output, so that it may
be comparable to the Info reader, but more familiar to those who are
used to HTML documentation (but I'll need to fully read the TODO.HTML
before doing anything in that regard - when the time comes).  It's also
generally useful to be able to access Texinfo manuals from machines that
do not have the viewer or EMACS (phones, MS-w. machines, or
distributions without either OOTB).

I hope we can put something together to help the users, have a great
day,
-- 
Arsen Arsenović

signature.asc
Description: PGP signature