Re: Help API for GNOME 2.0

[John Fleck <jfleck inkstain net>]

Folks -

Much to comment on here. I'll try to incorporate responses to most of
the thread, but I'll break some bits out into separate
missives. Thanks to Dan for thinking this through and getting us
started.

On Tue, Jul 10, 2001 at 04:34:52PM -0500, Dan Mueth wrote:
> 
> 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)

If we're using some sort of a caching system to speed up rendering (as
our KDE friends have decided to do), it also needs to search for a
cached copy of a rendered doc first before looking for xml and
sgml. (This may be especially important for the big docs David Merrill
has discussed. I think it makes sense to match our caching system up
with KDE's so we'll be able to easily read one another's cached docs.)

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

I'm content with this.

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

Sorry if I missed it, but has anyone objected to this? It seems fine
to be to drop the pbox stuff, but I hope we haven't missed some cogent
argument for keeping it.

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

I think we need to do this. As Telsa and David Merrill pointed out,
folks may want to use any one of a variety of tools to view help. Our
goal should be to make gnome-db2html3 and the associated tools a black
box (or a pair of black boxes) that takes the appropriate function
calls and returns displayable html that could be viewed in the browser
of choice.

Rodney Dawes (aka dobey) has been working on adding help browser
capability to Encompass, for example, which is much more lightweight
than Nautilus and could make a good alternative for folks concerned
about Nautilus' weight:

http://primates.ximian.com/~dobey/encompass-plan.txt

(In suggesting this, I'm not suggesting we abandon Nautilus as our
primary help browser. I'm merely suggesting we make the basic
functionality available to other browsers as well. Because
gnome-db2html2/3 work(s) standalone, this capability already implicitly
exists.)

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

I'm back!

Cheers,
-- 
John Fleck
jfleck inkstain net (h), http://www.inkstain.net/fleck/