Re: Help API for GNOME 2.0

[Dan Mueth <d-mueth uchicago edu>]

On 11 Jul 2001, Gregory Leblanc wrote:

> On 10 Jul 2001 16:34:52 -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:
>
> Hmm.  At this point, there are only two browsers that I know of which
> are planning to support viewing DocBook docs natively, and both are
> still in development (KDE and GNOME, if that wasn't obvious).

I think this is right.  I imagine at least one of these will fork off a
web-application so that people can have help browsers built into their web
pages (somebody emailed the ScrollKeeper list about doing this, and I
think the LDP likes to have these sort of web apps too).  I wouldn't be
surprised if somebody decided to build a light-weight single-purpose help
browser for GNOME off of the code in Nautilus - especially if we move it
into gnome-libs.  But right now, I think it is just the two: KDE and
GNOME.

> Right now, I'm thinking that having the converters (converting DocBook
> and man/info pages) in Nautilus isn't the right place for them, as this
> hinders creating alternate help browsers, for whatever reason someone
> might want one.

This makes more sense in the long run.  If John Fleck agrees, I'll leave
it to him to decide when is the right time to move since he'll probably
be the one to do the work.

> We need some uniform method for applications to load up their manual.
> The application shouldn't need to know anything about the program that
> will be displaying the manual, it just needs to be able to say "open to
> the Table of Contents", or "Open to the section about fooing with bar".
> If that doesn't work, can somebody help me understand why, and what else
> the application should need to tell the help browser?

Things aren't too sophistocated yet.  I'm still thinking along the GNOME
1.x line in that you basically have one function: "show this part of this
document".  For HTML, that means a given file and anchor.  For XML, than
means a given file and id.  The awkward thing is that the mapping {XML
filename, XML id} |-> {HTML filename, anchor} requires knowledge about the
full XML file and the stylesheet.  Generally one sectioning id from the
XML file becomes the HTML filename and the XML id becomes the anchor, but
there are several other possibilities.  So while the application doesn't
know anything about the help browser, the arguments the app passes through
gnome-libs to the browser tend to be XML-centric or HTML-centric.

It would be great to have tighter integration between applications and the
browser than just this one basic function, but I'm not getting too
ambitious here: (1) We don't have a lot of time before the platform
freeze, and (2) As anybody in the GDP knows, moving to XML docs,
gnome-db2html3, a new style guide and word list, a review process, etc.
will keep us plenty busy as it is.

Dan