Re: writing help files for gnome 2.0 programs

[Allin Cottrell <cottrell wfu edu>]

On 24 Aug 2002, Mikael Hallendal wrote:

> In order to get the help files into ScrollKeeper (which is used to
> keep track on all documentation you have installed) you need to
> write an OMF-file...

Thanks for the details on this.  I do have an omf file for my app's
help, but either it's not right or scrollkeeper is misconfigured.
I'll work on it some more.

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

The graphics accompanying "admonitions" (tips, warnings and so on).
Actually, after updating a few things these are now appearing OK -- I
don't know what specific change made the difference.

> > * 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?
>
> Correctly setup the TOC is displayed in a tree-view to the left of the
> actual document view in Yelp while showing the document.

I'm not sure what "correctly setup" means here.  My document is a
valid docbook "book" instance (it's quite long and complex).  It has a
TOC alright, but this is not appearing in a left pane: it's all in one
pane.

> Yelp chunks your document into sections while viewing (so that you
> only get one section a time).

I'm seeing that now.  I think something was wrong with scrollkeeper
which had the effect that my whole document appeared in one go.

> > * 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?
>
> Hmm.. why shouldn't you add the .png to the end of filerefs?

Because the .png extension on the graphics is specific to certain
output formats.  My xml is also used to generate a MS-style .chm
document, and in that case the extension is .gif.  For making
postscript the extension is .eps.  Xml is a general specification of
the content of the document; the stylesheets for specific output
formats should add the information about what sort of graphics to look
for.

Allin Cottrell.