Daniel Egger <[EMAIL PROTECTED]> writes:

> Am Die, 2003-08-19 um 02.31 schrieb Sven Neumann:
> (...)
>> Actually it was Mitch's idea. Perhaps he should continue to explain it
>> then.
> Exactly, why are you bothering me with an example?

Here we go (ignoring the rest of the thread)...

It all starts with the uglyness of the current implementation.
Whenever we specify a help page in the current codebase, we have
to write something like:

  gimp_dialog_new (..., "dialogs/file_new.html", ...);

This is absolutely unmaintainable since it spreads the knowledge about
where to find help pages across the whole source code.  Apart from
that, it's simply ugly. Even worse, it's my own fault from pre 1.2
days and I feel like I have to fix that ;)

To keep it simple and straightforward, I'd like to replace that with:

  gimp_dialog_new (..., GIMP_HELP_FILE_NEW, ...);

and have these constants defined in one header file. The advantage
of this approach is that we keep all available help topics in one
place and that the compiler will not like unavailable help topics,
so we can't suffer from typos like in the current implementation.

The header would look like:

#define GIMP_HELP_FILE_NEW      "gimp-file-new"
#define GIMP_HELP_FILE_OPEN     "gimp-file-open"
#define GIMP_HELP_IMAGE_FLATTEN "gimp-image-flatten"


For a smooth transition the first step would be to have:

#define GIMP_HELP_FILE_NEW "dialogs/file_new.html"

so we can collect needed help items without breaking the current
system (which is already broken but still kindof works if you
badly symlink aroung)

That's basically everything that needs to be changed in the core.

The help browser however still needs to find the actual help pages so
there needs to be a mapping from these string IDs to links of some
sort for finding the content (like relative paths or uris to html

That mapping would preferably be a XML file like:

  <help-item id="gimp-file-new" uri="file/file-new.html" />
  <help-item id="gimp-file-open" uri="file/file-open.html" />
  <help-item id="gimp-image-flatten" uri="image/image.html#flatten" />

I don't care about the element names and stuff, it should just be
simple enough to keep a GMarkup based parser simple too.

How should this XML file be generated? I suggest to simply use the
same IDs as section IDs in the XML source so the mapping file
can be generated automatically.

I also thought about generating the header which defines the help
items, but gimp would depend on gimp-help or vice versa then, which is
probably a bad idea. Also, manually syncing the gimp's and gimp-help's
ID space will make us look at it more often, which can't be bad ;)

The generated mapping file would be installed under a defined name
(like gimp-help.xml) and the help browser would parse it when it first
opens a given help tree.

This approach also covers 3rd party plug-ins since they can tell the
gimp where their help tree is. The help browser has access to this
path and can simply open the gimp-help.xml file from that given help

All that needs to be done from the help system's side is generating
this mapping file and installing it in the top help dir.

I will add the header mentioned above tomorrow and start adding items
to it, so we can see all needed help items in one place (using the
<implementation deatil> approach above).

Is this a solution everybody can live with or did I miss something
obvious? If it sounds reasonable, we should go ahead, it's not even
an awful lot of work (the coding part, not writing the help pages :)

Gimp-developer mailing list

Reply via email to