Re: jrb help: XML & HTML

[Dan Mueth <d-mueth uchicago edu>]

On 4 Sep 2001, Mikael Hallendal wrote:

> > 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:
>
> Perhas I misunderstood this but it isn't (XMLfilename, XMLid) that you
> call gnome-help with, is it?
> You call it with (DocumentName, SectionName) which is then looked up in
> ScroolKeeper to a (Filename, tag) (where tag could be the name of an
> HTML-anchor).

The GNOME 1.x help API explicitly referred to HTML documents by giving an
HTML filename with anchor.  The simplest way to transition to to GNOME 2.x
is to add new functions which behave similarly but refer to an XML
file and id.

If we wanted to put ScrollKeeper in the middle, we would do so using a URI
scheme which extends beyond GNOME and works with KDE, LDP, etc. docs.
Then all our docs and apps would refer to other docs using this URI
scheme, and ScrollKeeper could act to resolve these URI's (into file: or
potentially http: or other).  I think this may be a really nice way to do
things and would be within the scope of ScrollKeeper, but we aren't at
this point yet and probably won't be in time for GNOME 2.  (Especially
since the GNOME 2 platform is supposed to be frozen.) If people like this
approach (or dislike it), speak up and we can decide whether this goes on
our TODO list.

Dan