[Nautilus-list] Re: Help API for GNOME 2.0

[Sander Vesik <Sander Vesik Sun COM>]

On Tue, 10 Jul 2001, Dan Mueth wrote:

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

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. 

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


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

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.

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

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

>   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

> 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 

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

	Sander

One day a tortoise will learn to fly
	-- Terry Pratchett, 'Small Gods'