This file discusses issues related to HTML being used alongside or
instead of Info as a documentation format.  As this has been discussed
for many years without much progress being made, it was thought helpful
to create a file like this to collect all the issues in one place.  Then,
we could avoid having the same discussions over and over again.  Anybody
raising the question could be referred to this file so they could be
aware of the current situation.

* Why?

(Excerpt from mail to bug-texinfo@gnu.org in April 2019).

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

Links to these discussions:
https://lists.gnu.org/archive/html/bug-texinfo/2019-04/msg00001.html
https://lists.gnu.org/archive/html/bug-texinfo/2019-10/msg00010.html
https://lists.gnu.org/archive/html/bug-texinfo/2019-11/msg00003.html

Image support would be another advantage of HTML.

An earlier document on this issue, from Per Bothner in 2016:

http://per.bothner.com/blog/2016/texinfo-roadmap/

* Requirements

Simply using the system web browser to access HTML manuals is not
acceptable as an Info replacement.

Search in the document's indices should be allowed.

There should also be facility for handling intermanual-links and searching
a path for manuals installed in multiple locations on a system.

* Browser software

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

However, this system is only appropriate for online manuals, not for
locally installed manuals.  The reason for this is that it only handles
one manual at a time and does not handle searching for a manual.

Another system has been developed using the embedded WebKitGTK browser,
under the 'infog' directory in the Texinfo sources.

Video demo https://www.gnu.org/software/texinfo/video/demo.webm
(from November 2019)

From a private email (October 2020):
> The main problem with the two embedded HTML renderers we used (we also
> developed a program with QtWebEngine in this branch:
> https://git.savannah.gnu.org/cgit/texinfo.git/log/?h=qt-info) is their
> segmented architecture, and the difficulty of getting information in and
> out of them.  As web browsers and websites are so complicated and
> unreliable, they make the code which processes and renders the HTML pages
> run in a separate process, so if the renderer crashes or freezes, some
> recovery action can be taken.
> 
> Most of the complexity and code in both programs was to work around
> this, creating and using communications channels between the two halves
> of the program.  If the process displaying the UI wants access to data
> from within the HTML page that the rendering process has displayed,
> for example, HTML elements for index entries in a page, so that
> index entries can be listed in some widget, then it can't simply
> access those data structures in the address space of the process:
> it has to create, send and receive messages over some channel.
> 
> WebKitGTK had an API to access DOM elements in the renderer thread,
> but this API was deprecated in favour of injected JavaScript (I never
> worked out how to use this so am not sure if it is possible to achieve
> the same results).  Hence a two-part architecture would have to be
> replaced with a three-part architecture: instead of
> 
> UI process<--->Browser process
> 
> there would be
> 
> UI process<--->Browser process (native code)<-->Browser process (Javascript)
> 
> (The QtWebEngine program had a similar architecture except it was
> even worse, with a message-passing system between JavaScript code
> running in different contexts.)

(Since that email was written some use has been made of injected
JavaScript.)


* Location of locally installed HTML files


The current code under js/infog looks for MANUAL under
/usr/share/texinfo/html/MANUAL_html and
/usr/local/share/texinfo/html/MANUAL_html.
Users or distributions would need to copy/symlink the manuals to this
location.  The /usr/share/texinfo/html directory is akin to the
/usr/share/info/dir file in the Info system.

Currently infog only supports "split" installed HTML manuals
(meaning a collection of smaller HTML files rather than one large HTML file).

The GNU coding standards specify a 'docdir' directory for a package.  For
example, '/usr/local/share/doc/YOURPKG'.  It would be natural to install
Texinfo HTML documentation under '/usr/local/share/doc/YOURPKG/html'.

However, we did not use /usr/local/share/doc because
manual names are distinct from package names.  For example,
"emacs" would be the package name for many manuals ("tramp",
"org", "calc", etc.).  Hence, a user might not find the tramp
manual under /usr/local/share/doc/tramp/html but somewhere under
/usr/local/share/doc/emacs.

The location of files is needed for users to find a manual by name
and to follow cross-references between manuals.

Debian alse has some guidance on where HTML documentation could
be installed -

https://www.debian.org/doc/debian-policy/ch-docs.html#additional-documentation

- but file locations on Debian are not completely consistent (e.g. the
make manual is under /usr/share/doc/make-doc/make.html, while gdb
is under /usr/share/doc/gdb-doc/html/gdb).


%

It was also an issue as to how to get the manual name from a link.
In recent Texinfo releases, links to other manuals are annotated with the
"data-manual" attribute.  This solves the problem of getting the manual
name.

Texinfo manuals are put on the web with a variety of URL formats and
it is not possible to reliably get a manual name from a URL or even
to tell if a URL is to a Texinfo manual or to some other webpapge.  It's
unlikely we could persuade everybody to change their URL formats to
be something a browser could parse reliably to get the manual name.  Here
are some examples of URL's and the manual names:

https://www.gnu.org/software/trans-coord/manual/cvs/html_node/ - "cvs"
https://gmplib.org/manual/ - "gmp"
http://lilypond.org/doc/v2.22/Documentation/internals/ - "lilypond-internals"
https://gcc.gnu.org/onlinedocs/gfortran/ - "gfortran"


Prior to this, we mooted the idea of outputting links in HTML documents
differently if they were to be installed locally rather than put on the web.
For example, link to "../auth/index.html" instead of
"https://www.gnu.org/software/emacs/manual/html_node/auth/index.html".  With
the right installation standards, this would have allowed inter-manual
links to work in regular web browsers (although only for a single
installation location).

* Where to store non-English manuals

Possibly in a subdirectory named with the language code

* Coordinate with other projects

It's hard to make progress on this due to the need to coordinate with
different projects.  It's a chicken-and-egg problem: an HTML Info
program could not be released until people had documentation installed
where the program could read it, but people are also not motivated
to install documentation in a place that no program would use it.

Changes would be needed in other projects

* Distributions (Guix, Debian...) - Install HTML documentation
* Automake - rules for generating and installing HTML documentation
* Emacs - Info mode
* GNOME/other desktop environments - see if work on webkitgtk-info
or other could be integrated into other help systems like yelp
or DevHelp.