Re: writing help files for gnome 2.0 programs

[Mikael Hallendal <micke codefactory se>]

fre 2002-08-23 klockan 05.27 skrev Allin Cottrell:

Hi!

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:

http://scrollkeeper.sourceforge.net/documentation/writing_scrollkeeper_omf_files/index.html

The hard part comes after this, and that is to setup your directory
structure to install the documentation correctly.

I looked in the gedit module when I this up for MrProject the other day.

There is a file xmldocs.make which you have to put in $(top_srcdir) (or
edit it if you want to put it else-where).

This is a make-file helping you to set the rest up. (You can copy this
from gedit or mrproject module in GNOME CVS). This makefile contains
some helpful documentation in the beginning.

You can look in mrproject/docs/user-guide/C/Makefile.am to see how I set
it up for MrProject.

Figures must go into figures/*.png or you will have to edit
xmldocs.make.

Don't forget the omf-install directory. I copied the Makefile.am from
gedit module and changed the omf_dest_dir to $(datadir)/omf/mrproject.

Please let me know if I can help in any way.

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

Of course pre-generated HTML will always be faster. In Yelp HEAD this is
supported and we will pre-generate the files into HTML in GNOME 2.2.
 
> * 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?

> * 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. Yelp chunks
your document into sections while viewing (so that you only get one
section a time).

That is:

Section A
  |
  +-- Section B
  |
  +-- Section C

If you click on "Section A" you get a page with both "Section B" and
"Section C" inside (since they are part of "Section A"). But if you
click on "Section B" you only get that section.

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

Hope this helps!

Regards,
  Mikael Hallendal

-- 
Mikael Hallendal                micke codefactory se
CodeFactory AB                  http://www.codefactory.se/
Office: +46 (0)8 587 583 05     Cell: +46 (0)709 718 918