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

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"''.  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ć

-----BEGIN PGP SIGNATURE-----

iOYEARYKAI4WIQT+4rPRE/wAoxYtYGFSwpQwHqLEkwUCY7nnOF8UgAAAAAAuAChp
c3N1ZXItZnByQG5vdGF0aW9ucy5vcGVucGdwLmZpZnRoaG9yc2VtYW4ubmV0RkVF
MkIzRDExM0ZDMDBBMzE2MkQ2MDYxNTJDMjk0MzAxRUEyQzQ5MxAcYXJzZW5AYWFy
c2VuLm1lAAoJEFLClDAeosSTqTgBAI5y65qCztfitfaA3sUpoLaOhWb40znf5Az0
A73mzUBwAQCOX8i1e7GMjNxCr8V7SUGgoG49iOVMAuL6P7ra1pNTDA==
=U0kD
-----END PGP SIGNATURE-----