jrb help: XML & HTML

[Dan Mueth <d-mueth uchicago edu>]

It looks like we have not reached concensus on whether to support anything
other than XML, so I thought I'd throw in my two pence...

We definitely want to support XML as our primary format.  This will give
us a lot more functionality than HTML.

Shipping HTML versions of XML docs which we ship...  The potential gain is
that people gain the flexibility of using a help browser which does not
render XML docs.  The main issue here is that Nautilus was painfully slow
on slow machines in the past.  I do not know if all the recent speedups
fix this problem.  The main problem with shipping both HTML and XML and
supporting non-XML browsers is that the help API becomes more complicated.
I think I described this in greater detail on this list a while back, but
the short version is: When foo.xml is converted to HTML, you get a handful
of HTML files with anchors.  Thus, you cannot merely specify a position in
the doc by the (path, XMLfilename, XMLid)  triplet when calling
gnome_help_foo(). You need to specify the HTML filename and anchor, which
take the place of the XML filename and id but are different.  I believe we
have four solutions:

(1) not support HTML docs at all

(2) allow HTML docs, but use different API.  Thus, whether HTML or XML is
used is determined at hack-time, and not at run-time.

(3) Write a tool to automagically convert (XMLfilename,XMLid) to
(HTMLfilename, HTMLanchor) and stick it in gnome-libs.  I think this would
need the full XML/XSLT approach, which would be some work.  It may also
have a substantial performance penalty.

(4) Expand the triplet into a quintuplet: (path, XMlfilename, XMLid,
HTMLfilename, HTMLid).  (Really the last two can be merged to make this a
quadruplet.)  Thus, we build redundancy into the API call.  The downside
to this is that it requires that the hackers/doc writers convert each doc
to HTML and figure out what the HTMLfilename and HTMLid are for each API
call.

My vote is to do #2:  We strongly encourage everybody to write their docs
in XML and to ship only XML.  If somebody really wants to write a GNOME
app but use docs which are in HTML only, we provide an API which lets them
do so.  At the same time, we try to break out the core XML->HTML stuff
from Nautilus into a core GNOME package and encourage people to write an
alternative, light-weight browser for people on machines which can't
handle Nautilus.

BTW: As I understand it, the current form of JRB Help does not allow for
real fallback from XML docs to HTML docs.  It might do #2 without
explicitly distinguishing between HTML and XML docs by having different
function names for the two cases.  (Jonathan - Is this right?)

Dan