Re: Help API for GNOME 2.0

[Dan Mueth <d-mueth uchicago edu>]

On Thu, 12 Jul 2001, Malcolm Tredinnick wrote:

> On Wed, Jul 11, 2001 at 06:50:39PM +0100, Sander Vesik wrote:
> > On Tue, 10 Jul 2001, Dan Mueth wrote:
> > >         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.

Right.  We have to make sure that the packages are relocatable too.

> > 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.

Sounds good.

> > > 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.

After chatting on #sun a bit this morning...  It sounds like all GNOME
programs which use the component system are abysmally slow on Solaris.
Apparantly Evolution even slower than Nautilus.  Since I see no
fundamental reason why GNOME programs or the component system must be
slower on Solaris than on Linux, I expect that it is just a matter of work
to fix it.  And since GNOME isn't really GNOME without any of the apps
which use the component system, I'm betting this problem will be fixed ;)

So, I'm going to start assuming that Nautilus will work alright on Solaris
as our help browser and forget about the need for an HTML-only help
browser unless people start making a lot of noise.

> So this brings up another question (which may already be know): how do I
> tell my Gnome installation what help browser to call.

The control center allows you to set the "ghelp:" handler (ie. help
browser) in the URL handler section.

> > > 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".

This seems like the right way to go.  Of course there is no need to do
this until somebody actually decides to create an alternative help
browser.

> 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.

This sounds like #1, since you have to pull the code that converts XML to
HTML out of Nautilus and put it into gnome-libs.

> > Well, it would allow things like

/me anxiously waits to hear what sort of things it allows

Dan