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

[Arsen Arsenović]

Hi Alex,

Alejandro Colomar <alx.manpages@gmail.com> writes:

>> Check out ``info "(info)Help"''.
>
> That brings me to the same as `man info`.

Hmph, that might be an alias on my system.  ``h'' should take you there,
though.

>>  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.

I am reading two problems from this:

1) From a first peek, it's not obvious that there's a tree involved.

   I've been given the suggestion of including a tree hierarchy on the
   left side of the screen, if the screen is wide enough, that annotates
   ones position in the info document hierarchy and makes it clear where
   you are and when you move.  Maybe this would help?  Plus, adding a
   section that explains the structure of a Texinfo manual as you
   mention below.

2) EMACS isn't that common anymore, and the chance that one is not used
   to it, or that one has never used it, is high.

   I'm not sure what can be done about this without stepping on toes of
   those used to the current info keymap.  My infinite notebook has an
   entry somewhere in it that talks about potentially adding a nano-like
   informative panel on the bottom of the screen to inform the
   first-time users of the basics of navigation.  I feel this might also
   draw more attention to the welcome message since it adds a noticeable
   visual element to the bottom of the screen.  Maybe that works?

>> 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).

Right, as a basic pager, it's really not accustomed to that.  Other
side-effects include text not being reflowed on window size changes.

>>  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.

That's there!  ``info --vi-keys''

>> 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.

Maybe installing a vinfo wrapper that just calls info --vi-keys "$@"
would help.

> 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).

It could be useful to cover nodes and menus in a brief section in the
getting started section, yes, I agree.

>> 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).

Heh, yes, I'd not certainly not want to get rid of the terminal
accessibility - hell, I rely on it a lot ;) - but HTML seems less
integrated than Info can get, and it might be preferred by a lot of
folk, hence, it would be nice to have it up to par.

> 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

Thanks :)
-- 
Arsen Arsenović

signature.asc
Description: PGP signature