Help API for GNOME 2.0

[Dan Mueth <d-mueth uchicago edu>]

Hi,

We need to update the GNOME help API for GNOME 2.0.  For now, I'm just
thinking about the calls to bring up the help browser and not pop-up
help.

The main question we need to answer is whether we want to support
HTML-only help browsers. If we can assume that the only help browsers
people want to run can handle SGML/XML (ie. Nautilus), then we can do
something simple like:

        gnome_help_display(path, name, linkid)
                path = path in $PREFIX/share/gnome/help (as GNOME 1.x)
                name = doc file name, without extension (it will search
                       for .xml, then for .sgml)
                linkid = this is the id attribute inside the doc to link
                         to

        gnome_help_display_html(path, name)
                path = path in $PREFIX/share/gnome/help (as GNOME 1.x)
                name = HTML file name, with extension and target

*  Note that 'name' has somewhat different meanings in the two cases
** Note that gnome_help_display_html() would be the same as
   gnome_help_display() was in GNOME 1.x

Here the second function is provided for people who want to ship HTML-only
documents, which is not how the core GNOME documents will be shipped and
will prevent them from taking advantage of indexing, TOC, etc., but surely
some users of the GNOME platform will want to ship only HTML docs anyway.
So, most apps would use the first function, and thus users can only use
help browsers which grok XML/SGML/DocBook.  For now, this is just
Nautilus.

If we are content with this, then we are in good shape.  I say we get rid
of the old gnome_help_pbox_*() functions, at least for XML/SGML docs,
since they don't really make sense in this context.  We will need to
update gnome_help_file_find_file to not only figure out the preferred
locale which has the document, but also to search for both XML and SGML
files.  Aside from these small changes, I think we'd be done.

Are we content with requiring browsers to read XML/SGML?  The main concern
I have heard about this requirement is that Nautilus on Solaris has
serious problems.  So, I think the people who need to answer this is
probably whoever is hacking on Nautilus for Solaris.  (Who is that?) I
surely hope Nautilus on Solaris is working great by GNOME 2.0.  What do
the Solaris Nautilus hackers think?

If we decide that we want to allow HTML-only browsers, then we have a
handful of options but they all have their drawbacks.  To name a few:

  1) Move gnome-db2html3 out of Nautilus and into the core GNOME
     libraries.  This would allow other help browsers, even if
     they are HTML-only, to display the documents.

  2) Expand gnome_help_display() to accept the extra parameter needed
     for the help system to identify which HTML file to render. This
     is just one extra parameter, but it creates extra work for every
     call since the developer must parse the doc with gnome-db2html3
     to see how it gets broken into pages and what the file names are.

  3) Write a little program which reads the XML/SGML file and uses it
     and the stylesheet to determine the generated HTML filenames
     from #2.  This would require that both the SGML/XML and the
     HTML files are shipped and that the help system parses the
     SGML/XML and then the browser parses the HTML each time a doc
     is viewed.

Out of all of these, I guess #1 is the Right way, supposing that we
actually care about HTML-only browsers.

Thoughts?

Dan

PS: Unfortunately John Fleck, the maintainer of gnome-db2html3, is out of
town this week, so we may have to wait a bit for his input.