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

Hi Arsen,

On 1/7/23 21:33, Arsen Arsenović wrote:
> Hi Alex,
> 
> Alejandro Colomar <[email protected]> writes:
> 
>> Hello,
>>
>> As someone with zero knowledge of how info(1) works, but considerable knowledge
>> of how to read a manual page (well, there's little to it; less(1) is really
>> simple), I'd like to recommend something for the info(1) manual page.
> 
> Check out ``info "(info)Help"''.

That brings me to the same as `man info`.

>  This page is also linked through the
> info viewer welcome message: "Welcome to Info version 7.0.1.  Type H for
> help, h for tutorial".  Pressing h at any point in the info viewer takes
> you to that page.

Oh, in the front page of `info info`, I saw that 'H' is for help, and read the 
basic command keys:

[
Next: Stand-alone Info,  Up: (dir)

Stand-alone GNU Info
********************

This documentation describes the stand-alone Info reader which you can
use to read Info documentation.

    If you are new to the Info reader, then you can get started by typing
'H' for a list of basic key bindings.  You can read through the rest of
this manual by typing <SPC> and <DEL> (or <Space> and <Backspace>) to
move forwards and backwards in it.
]


However, help that explains how to navigate is of little help if I first don't 
know how documentation is organized.  In a manual page, it is simple: 
documentation for something is in a single page.  In Texinfo, there is a nodes a 
dir, a pointer, a file, a tree, ...  and I don't know what they mean.

For someone who has never used emacs, learning all this from scratch is... not 
easy.  It's a bit of a chicken-and-egg problem.  I can't say I didn't have this 
problem with less(1) and vim(1), but at least a man page doesn't need that one 
knows everything about less(1); even a novice can use the arrows, and that's 
enough for starting; search and other features can come with learning.

> 
> This message seems to often be missed by users, in my experience.  I
> don't know why - perhaps because it's on the bottom of the screen, below
> the interesting stuff.
> 
>> The info(1) manual page seems to be little more than just a link pointing
>> readers to the actual documentation, accessed through info(1) itself:
>>
>> SEE ALSO
>>         The full documentation for info is maintained as a Texinfo manual.   If
>>         the info program is properly installed at your site, the command
>>
>>                info info
>>
>>         should give you access to the complete manual.  (Or, if you have Emacs,
>>         M‐x info will lead to the manual.)
> 
> This is pretty common with many pages, as manuals generally serve as a
> short summary of a full documentation suite in info pages, where that
> exists.

Yeah, I guess that's normal; I don't expect you to write twice your docs, once 
for man(1) and again for info(1).

> 
>> It might be useful to lessen the learning curve of info(1), and recommend to
>> habitual readers of manual pages to pipe info(1) to less(1), so that the manual
>> is in a more familiar format.  Who knows?  Maybe after reading without much
>> friction the entire info(1) manual you convert some of us.  And if not, at
>> least we were able to read manuals only available through info(1)  :)
>>
>> How about adding the following:
>>
>> 	For readers more familiar with manual pages, it might be interesting
>> 	to pipe info(1) through less(1):
>>
>> 		info info | less
> 
> This suffers from decreased navigability, though, as links (xrefs and
> menu entries especially) become non-clickable.

We have the same issue in the manual pages.  less(1) seems to not be very 
friendly to hyperlinks.  Maybe we could add a disclaimer that piping through 
less(1) would disable links (and maybe other stuff).

>  That said, that could be
> done, if others agree, but I believe a better experience can be created
> by making the info format viewers themselves more accessible for people
> more used to pagers, or otherwise un-adapted to EMACS.

:)

If you could add an alternative mode where it would behave somewhat like 
less(1)/vim(1), that would be great.

> 
> I've been brewing thoughts of how to make the standalone info viewer (or
> an alternative one) more useful to newcomers to GNU.  I'd value your
> feedback, given your background.  I think (Tex)info has a lot to offer
> already, and has large potential for generating new high-quality
> documentation, on top of the large volumes of existing documents.

Maybe vinfo(1) would be a good name for a vi-like info.

However, navigation is only one issue; understanding how the documentation is 
organized is another, which I guess could be better detailed in `info info`.

Maybe before the '5 Selecting a Node' section, you could add one that explains 
what is a node, and all other subdivisions of info documentation, and maybe show 
some visual example (an ascii-art tree or something).

> 
> A suggestion I got already (and I'll see if I can implement it soon) is
> generating a HTML version of the ``(dir)'' node, and probably providing
> a link to it, or a shortcut to jump from info to a HTML view, or
> something like that, so that an end user can make use of the HTML view,
> which is potentially more alike what they'd be adjusted to.

HTML is probably good for some.  However, others prefer the terminal (yes, there 
are terminal HTML browsers, but for some reason I don't find them very useful).

A vi-like info viewer would be interesting (and as a temporary workaround, `info 
x | less` does the job).

> 
> I'm very much looking forward to hearing your thoughts on this, as I
> believe it's quite important.  I must apologize in advance for a lack of
> initiative in the coming few weeks (at least up to FOSDEM), I've a lot
> of work to do right now.

Oh, don't worry at all.  As I said, |less does the trick for me :)

> 
> Thanks in advance, have a great night.

Have a great night :)

Cheers,

Alex

-- 
<http://www.alejandro-colomar.es/>