Re: Any interest in using HTML for locally-installed Texinfo documentation?

[Ludovic Courtès]

Hello Gavin,

Gavin Smith <address@hidden> skribis:

> Documentation for GNU packages and others is often installed in the
> Info format, a plain text format.  Using a plaintext based format for
> documentation does not take advantage of bitmapped displays that have
> been available for decades.  It does not allow styling of text or
> reflowing of text.  Much information is lost in the conversion from
> Texinfo to Info and any attempt in, for example, Emacs to re-add this
> information is unreliable.
>
> Nonetheless, Info viewers have continued to have advantages over web
> browsers.  They are fast, and have features for searching the manual
> with index lookup.  They allow the use of keyboard commands.
>
> In attempt to bring some of the benefits of the Info viewers to HTML
> documentation in web browsers, in 2017, as part of Google Summer of
> Code, Matthieu Lirzin worked on a JavaScript interface that works with
> the HTML that texi2any produces.  His work is substantially complete.
> A manual with this interface added is at
> https://www.gnu.org/software/texinfo/manual/texinfo-html/Overview.html.
> All the important keyboard commands that work in the Info viewers are
> implemented, including index lookup.

Nice!  Org-info.js achieved something similar (info "(org) JavaScript
support") and I agree that it’s a great improvement.

I hope we can eventually upload manuals on gnu.org that take advantage
of this features when viewed with browsers that support JavaScript
(“progressive enhancement” as they call it.)  We could change Gnulib’s
‘gendocs.sh’ to do the right thing.  I’d suggest improving the CSS to
make the document less dense, but that’s a minor issue.

(For some reason ‘i’ does open the index search box for me, but then
hitting enter doesn’t produce any effect.  The other navigation commands
work fine, though.)

> I believe this work has great potential to increase the ease of
> accessing documentation, including documentation locally installed on
> a user's own computer.  When a user is using a bitmapped display (e.g.
> with X11), this could become the default way that they access
> documentation.

I hear the argument; it’s true that not everyone uses Emacs or is
familiar with the standalone Info reader.  Rendering of Info manuals in
Emacs is not bad, but a modern browser can do a better job.

Yet I’m not completely sold to the everything in the browser approach,
and everything in JavaScript.  In an ideal world (for me), we’d rather
provide a local documentation viewer that renders Texinfo directly.
TTN’s IXIN experiment was a step in the right direction IMO, but I
understand this approach is not something that’s happening now.

When talking about ease of access, we can’t ignore keyword searches.
How would you do ‘info -k’?  How would you even simply point your
browser to a specific manual?  What about inter-manual cross-references?
Would we need a mechanism similar to ‘hxmlxref.cnf’ but that would
browse local manuals?  What would be the recommended solution for Emacs
and console users?

> I am contacting you because the distribution level may be the best
> place to push this forward.  There are two reasons:
> * The distribution could take care of installation of HTML
> documentation files (at the moment, there is no standard place to
> install these, and Automake does not support installing HTML files
> generated from Texinfo).
> * It could also take responsibility for checking web browser
> compatibility.  Even if we don't use the JavaScript interface for
> documentation on the GNU website due to browser compatibility
> concerns, an OS distribution would have control over which browser was
> used to view documentation.

I think we could do this in Guix when we have answers to the questions
above.  :-)

There’s a side issue, which is that HTML documentation tends to take
quite a lot of space, but we’ll see whether that’s a problem.

> Although I have little knowledge of Guix, it is the natural choice of
> operating system distribution to contact about this possibility, as
> both Texinfo and Guix are GNU projects.

A good idea!  We should also consider working on adjusting policies and
practices in GNU, too.  At that point, it’ll be easier to reach out to
other distros.

Thank you,
Ludo’.