Re: Gnome Help Browser

[Malcolm Tredinnick <malcolm commsecure com au>]

On Sat, Aug 18, 2001 at 10:49:42PM -0400, Matthew Colyer wrote:
> 	My name is Matt and I have helped a little bit in the past with
> Screem code and documentation. I am no expert coder or documenter but I
> would be willing to work on a help browser that works on older machines. I
> can not stand Nautilus it doesn't even render my home directory completely
> at the moment. ( I do not mean to bash the Nautilus folks for writing this
> code. It really is feature rich but some of us just don't have the
> computing power to run it. ) What all would writing the new Gnome Help
> Browser entail doing? 

Woo-hoo! :-)

OK, what follows are just my thought on the issue. They do not represent
any sort of "official" GNOME position, but the general rule that 'the
person who writes the code makes the rules' sort of applies. :-)

In some sort of priority order, a help-browser should be able to do the
following in order to play nicely with GNOME 2.0:

(0) Be a lean, mean, displaying machine.

(1) Display documentation that is given in Docbook-xml format.

(2) Use scrollkeeper to find out meta-information about the
documentation available.

(3) View man and info pages.

Very shortly (hopefully!) development will restart on gnome-db2html3,
which is a module for converting DocBook to html using the GNOME
stylesheets (which have yet to be written) and based upon libxml2 and
libxslt. Neither of these underlying libraries will be particularly
disasterous on low power machines. There is also a requirement in the
gnome-db2html3 design that it caches documents in html form if possible,
so that there may be a short wait when the user initially views a
document, but for frequently used documents it will seem fairly quick
(it's a trade-off between time and disk space, really).

So that takes care of getting the information into some handy format for
the main documentation. I would also like to make sure that info2html
and man2html (which are currently used by gnome-help-browser) are in
working and bug-free condition, since it is much easier to view info
pages via the current help browser than through the 'info' program (in
my opinion).

Using scrollkeeper is also not particularly difficult, since it uses a
nice handy XML format, so libxml2 to the rescue again. It is also fairly
well documented and comes with scripts for accessing the location of
ddocuments, etc. So, really, apart from an optional requirement on
scrollkeeper (it may not be possible to assume that users will have it,
but we will use it if it's there), we can assume the infrastructure for
item (2) exists.

This just leaves the main component, which is displaying the html in a
widget somehow. Bex has previously suggested using the Gimp help browser
to do this. I must adamit to being lazy (well, busy) and not having
looked at that code very much to see if it's easily compatible with
GNOME. Alternatively, we can either use gtkhtml or gtkhtml2. The former
is currently used in the help browser and I'm not sure what it's status
is as a maintained module, but it's not particularly active. The latter
module is a new beast from the Anders Carlson and friends and is
possibly not production ready yet (it's been "nearly ready" for a while
now, but holding your breath will only give you a headache).

The final option for displaying results is the easy one: assume the user
has a web browser of their own choice available. Then we just need to
provide a wrapper so that a call to display GNOME help will ensure the
document is already in html/css form and pass the appropriate URI to the
browser. For a simple solution that doesn't require too much extra
software, this is probably the way to go.

This whole issue is something I've thought a bit about but I am in a
really busy period at work at the moment so I have not had time for a
couple of months to do anything concrete about it. Fortunately that
part of my life should calm down in a couple of weeks, so I can start
contributing to the free software world again. If nobody else pipes up
with a comment that they arae already working on this and you want help
or somebody to bounce ideas off, keep in contact me and I'll be happy to
either help out or provide code for you to test/document/patch/whatever.

Cheers,
Malcolm

-- 
Love may be blind but marriage is a real eye-opener...