writing help files for gnome 2.0 programs

[Allin Cottrell <cottrell wfu edu>]

Is there any up-to-date guidance available on this topic? Google turns
up many references on various combinations of keywords such as
"gnome2", "documentation", "help" and so on, but most of them are
quite out of date.

I have documentation for my app in valid Docbook xml, and for gnome
1.4 I was able to turn it into valid HTML and have it display nicely
in gnome-help-browser (besides turning it into PDF with jade and
jadetex).  I'm kind of at sea with the new yelp system.  I can
appreciate the advantages (from some points of view) of having the
help files in xml rather than pre-converting them to HTML, but many
details seem out of whack.

* Speed of rendering.  Yelp is SLOOOW.  Much slower than the old
browser, which is hardly surprising since it's having to do a lot more
work.  Slower still than MS's compiled html help, which I have to say
appears very fast to the user.

* How is one supposed to deal with features such as "admon graphics"?
I have these in my xml, and the graphics are not found.

* How are you supposed to get an app's help files to appear in yelp's
main menus (content lists)?  This "just worked" in gnome 1.4 if you
put the help files in the right place, but I can't find how to add my
app in 2.0.

* How do you (or can you?) control the structure or appearance of an
app's help files?  (E.g., does it all appear in one gulp or is it
broken into separately displayed sections?  Is there a distinct
left-hand pane with a navigable table of contents?)  I would think of
these things as being controlled by a stylesheet, but I'm quite hazy
on how stylesheets enter into the yelp process.  Can an app specify
and supply its own xsl, or what?

* None of the images in my helpfiles are found unless I hard-code a
".png" extension onto the end of the filerefs.  This seems broken.
What is the correct procedure?

Well, that's probably enough to be going on with ;-)

-- 
Allin Cottrell
Department of Economics
Wake Forest University, NC