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

[Arsen Arsenović]

Hi Alex,

Alejandro Colomar <alx.manpages@gmail.com> 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"''.  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.

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.

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

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.

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.

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.

Thanks in advance, have a great night.
-- 
Arsen Arsenović

signature.asc
Description: PGP signature