Re: info -> html

[Patrice Dumas]

On Wed, Mar 21, 2012 at 05:00:49PM -0700, Karl Berry wrote:
> Chong (and Patrice and Sergey and Stefano),
> 
> So, on this project to replace Info with an HTML or XML format (which
> will probably be news to S&S), Chong wrote me:
> 
>     Probably the way to start is to install HTML/XML manuals
>     side-by-side with Info files, and change the viewers so that when
>     pointed to an Info topic, they load and display the HTML/XML version
>     if it is available, instead of the Info file.
> 
> Sure, sounds like a reasonable starting point to me.

It is not very clear what an Info viewer is in that context.  In the
case of emacs, that makes some sense, but in the case of the standalone
Info viewer, the idea would certainly rather be to replace it with a
tiny wrapper for a console web browser such as lynx, with the only
thing that the wrapper would do would be to translate a manual and node
name to an url to a local file.

Of course the standalone Info reader could do that delegation only if 
the html file exists or something like that.

Also the mangling of node name could either be done beforehand by 
texi2any, or dynamically by the wrapper around the console browser, be
it the Info reader itself or an external command (I think that an
external command would certainly be better, but I am not really sure).

> We should think hard about exactly how we want to install the HTML
> files.  We definitely don't want one big directory of everything, the
> way $(infodir) is.  I imagine one directory per manual (= dir entry).
> With any images in that directory.

If this is the case, we will have to change the way cross manual
references are done.  Indeed, cross manual references imply all manuals
in the same directory.

> There is also the issue of HTML, unlike Info or XML, being available in
> both monolithic and (multiple) split-file forms.  Perhaps we should
> require that the local version be monolithic?  After all, network
> bandwidth shouldn't come into play for local viewers, and it would so
> much simpler not to worry about split files.

There are other arguments for monolithic manuals.  Indeed, and in
contrast with the Info reader, HTML viewer have no concept of what
constitutes a manual, so things that require the concept of a whole 
manual, searching for a string comes to mind, maybe there are other
things, that cannot be represented by hyperlinks won't work for a 
split manual.

> Clearly all of this will also affect Automake (and the coding
> standards).  Right now, the coding standards say that HTML files get
> installed in /usr/local/share/doc/YOURPKG[-VERSION] by default.  Is that
> really what we want for "Info" viewers to find them?  I am doubtful.

In my opinion, the most problematic issue will certainly be ensuring
correct cross manual hyperlinks.  For that 

  /usr/local/share/doc/YOURPKG[-VERSION] 

clearly doesn't work, but, as I say above, not having the monolithic
manuals in the same directory also does not work, even if it could be
quite easy to change the cross ref stuff to add a directory even for
monolithic manuals.

There is also the issue of htmlxref.cnf, the manuals meant to be
installed locally certainly should ignore completly those files.  That
should certainly be trivial to add an option or customization variable
that prevents htmlxref.cnf files to be used, however.

> (And, are we going to try to support multiple installed versions this
> time around?  Hmm ...)

I can't see a simple way, given that hyperlinks must be correct at the
manual generation time.  We can imagine a dir.html with entries
dynamically modified, but I don't think modifying the manuals
dynamically would be wise.

-- 
Pat