Re: Help API for GNOME 2.0

[Malcolm Tredinnick <malcolm commsecure com au>]

On Wed, Jul 11, 2001 at 06:50:39PM +0100, Sander Vesik wrote:
> On Tue, 10 Jul 2001, Dan Mueth wrote:
> > 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
> > 
> 
> The problems I see with this is that it forces all applications using the
> gnome help API to install the help files in the same location, something
> which you may be not able to do with you don't say have root access on the
> machine. 

Agreed. We've just crawled out of this hole with requiring things like
pixmaps to be installed in a single hard-coded directory. Let's not get
back into it via another route.

> How about:
> 	gnome_help_display(key, path, name, linkid)
> and
> 	gnome_help_display_html(key, path, name)
> 
> Where key is a string:
> 	a) NULL in which case it behaves as described before
> 	b) used as a key to look up the "virtual root" of help files using
> 	   gconf key /help/virtual_roots/$key allowing apoplications to
> 	   register their own help file locations

This seems like the correct approach to me. The path should definitely
be a gconf thing.

[...snip...]

> > 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?
> > 
> 
> Well, yes, I also hope nautilus is going to be usable on Solaris (and
> other non-Linux operating systems). gnome-2.0 with major functionality
> regressions as seen from the point of view of an end user (no
> nautilus) just doesn't make any sense.

Umm .. I no longer have a machine with 32M of RAM to test this on (I'm
going to buy a cheap third-hand machine next week with limited memory to
play with for these purposes), but when I tried Nautilus on such a box
about three months ago it was unusable! I don't know if the recent round
of speed improvements have also improved the memory requirements down to
almost nothing, but it is completely unacceptable for Gnome not to
function on such machines.  Sure, you have to turn all the bells and
whistles off, but you shouldn't have to turn the help files off.

To my mind, _requiring_ Nautilus on such a machine would be shipping
with reduced functionality, since it rules out Gnome as an alternative.
So we need to have some way of allowing alternative help browsers. So
Dan's comment is still an open question, but to my mind, Sander's
preference is the wrong way to go here (sorry, Sander).

So this brings up another question (which may already be know): how do I
tell my Gnome installation what help browser to call. Suppose I have a
help browser that can process SGML files. So I guess that means it
really provides the appropriate bonobo interface. What tells the system
to call Malcolms-own-help-browser, rather than, say, a Nautilus program
which isn't installed?

> > 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.
> > 
> 
> It is more of a decision along the lines of 'do we want alternative help
> browsers'. If yes, then we should do this.

I vote "yes".

> >   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.
> 
> This sounds bad. 

Agreed.

> >   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.
> 
> well, you could make use of the xsltproc from lixslt and just do it, but
> it sounds problematic and can introduce race conditions and other nasties

What is wrong with this?
      4) An HTML help browser can exist transparently if it does the
	 following: converts XML helps files to HTML either on-demand or
	 en masse (a cron job to keep up to date, perhaps). Then it sees
	 every request for a help file and maps that to the appropriate
	 HTML file. How it does this is up to the help browser.

In this way, you can have Netscape/Mozilla/Galeon/FooBrowser/whatever as
your help browser, even, but there needs to be a wrapper app that is
what is called when help is required and it then makes the appropriate
call to Mozilla, etc as appropriate. In fact, one wrapper app fits all
here, since it's just a matter of changing which web browser it calls in
the final phase.

I'm probably overlooking something obvious, though.

> > Out of all of these, I guess #1 is the Right way, supposing that we
> > actually care about HTML-only browsers.
> > 
> 
> Well, it would allow things like 

???

Something appears to be missing here (or you came up with a null
examples set). :-)

Cheers,
Malcolm

-- 
Save the whales. Collect the whole set.