Michael Natterer <[EMAIL PROTECTED]> writes:

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

I thought about this some more and I see some potential problems when
it comes to third-party documentation. However I think that the
current proposal can relatively easy be improved to cope with these

Let's call each help-tree, either installed by gimp-help or by a
plug-in, a help domain. The problem I see is that the current proposal
doesn't define a way to link between help domains. While for example
the freetype plug-in might install it's own help file(s), there is no
way for the author of the text-tool help to link to this page and the
freetype help author cannot link to the text tool documentation.

This problem could be solved by allowing links in the help pages to
point to the registered identifiers instead of pointing directly to
HTML pages. So when the text-tool help wants to link to the move-tool,
it would use something like

  <link gimp-help:href="gimp-move-tool" />

and the help-browser would have to use it's mapping file to find the
HTML page from the identifier.

"gimp-help:" means that the identfier is supposed to be looked up in
the "gimp-help" help domain. I would suggest we use XML namespace to
identify the help domains. This means. that the XML mapping file that
announces the help to the help-browser would look like this:

  <gimp-help xmlns:help="http://www.gimp.org/help/gimp.html";>
    <help-item help:id="gimp-file-new" uri="file/file-new.html" />
    <help-item help:id="gimp-file-open" uri="file/file-open.html" />
    <help-item help:id="gimp-image-flatten" uri="image/image.html#flatten" />

This is just a small modification to Mitch's proposal. It introduces a
namespace to be used for ID attributes. The namespace prefix is
irrelevant and can be choosen short since the namespace is identified
by the URL given in its declaration. A plug-in that wishes to register
help pages with the GIMP would have to announce the location of the
help tree on disk, the location of the mapping file (could probably be
derived from the help path) and an URL that identifies the namespace
for the IDs it wants to register. So for example the freetype plug-in
would call

 gimp_plugin_help_register ("/usr/share/gimp-freetype/help",

The mapping file it registers (here called "refs.xml") would perhaps
look like this:

  <gimp-help xmlns:freetype="http://freetype/gimp.org/help";>

    <help-item freetype:id="top"          uri="freetype.html" />
    <help-item freetype:id="kerning"      uri="options.html#kerning" />
    <help-item freetype:id="antialiasing" uri="options.html#antialiasing" />


Any help page could then refer to the freetype plug-in by using

  <link xmlns:ft="http://freetype.gimp.org/help"; ft:href="top" />

As you can see, the namespace prefix is irrelevant, we can choose
"ft:" here to keep the notation short. Of course if multiple links to
the freetype plug-in are needed, the namespace can be declard in the
top-level element and the link would simply become

  <link ft:href="top" />

I am not sure how much work is needed to teach the help-browser about
a new link type and XML namespaces but I think it might be worth the
effort. This architecture should allow us to do some nifty stuff and
it will assure that no conflicts will ever arise from help registered
by third-party plug-ins.

My proposal would also allow to split the help between the GIMP core
and the plug-ins we ship with GIMP. Just as we do for i18n now, where
there are translation domains for the core, the plug-ins and
script-fu, there could be help domains for the core, the standard
plug-ins and individual domains for Script-Fu, Python and Perl

As a last note, let me outline a small error in the proposal I just
made. Since <link /> is not part of XHTML, we should check if there's
an element we can (ab)use or we need to introduce a namespace for the
link element (or whatever it would be called).

Gimp-developer mailing list

Reply via email to