Hi,
it looks as if Mitch liked my proposal so he went ahead and
implemented it. The gimp-freetype plug-in has also been updated to use
the new API. It registers help in it's query function as follows:
gimp_plugin_help_register ("http://freetype.gimp.org/help";,
help_uri);
help_uri is a local file: URI that points to the path of the locally
installed help-files. There is file called gimp-help.xml installed
there that says:
<?xml version="1.0"?>
<gimp-help xmlns:ft="http://freetype.gimp.org/help";>
<help-item ft:id="plug-in-freetype" ref="index.html" />
</gimp-help>
When the GIMP helpbrowser is started, it is passed the list of help
domains that the core has build from the various plug-ins registering
their help. It parses these files and is now able to map any help
request to an URL. A help request consists of an ID and an URI that
identifies the namespace for this ID.
This solves the problem of plug-ins registering their help and as the
implementation shows, it even works in practise. What still needs to
be figured out is if we want the help files to make any use of these
IDs for cross-linking purposes. I think the generated HTML files
should be as self-contained as possible. So they should use simple
HTML links (<a href="foo"/>) whenever possible. Whenever possible
means that either the link is local to the help-domain or it was
somehow translated when the HTML was generated or in a post-processing
step. I will try to outline how this could work:
Let's suppose the core help wants to refer to the freetype plug-in.
The HTML files could contain a link like the following one:
<a href="missing.html" ft:idref="plug-in-freetype">FreeType plug-in</a>
The ft namespace would have to be declared either locally or in a
higher-level element, for example in the toplevel html element:
<html xmlns:ft="http://freetype.gimp.org/help";>
For any HTML browser this should be a valid link to a page
"missing.html" in the local help-domain that explains that the page
the documentation wanted to link to doesn't exist.
A smarter help-browser, like the one we will provide, could use the
idref attribute and pass a help request to the help system that will
eventually give it an URL to the locally installed freetype help pages
or perhaps even some online version of them.
I really like the idea of putting all help pages on-line. Having help
paes on-line with broken cross-links that only a special help-browser
can understand is of course not an option. However I believe that the
idref attribute proposed above should allow to write an XSLT that
resolves these links. We could put a collection of help-domains
on-line and have a script convert the cross-links into links that work
for any browser. The necessary information to resolve the links is in
the gimp-help.xml files that are installed for every help-domains.
It's the same information that the help-browser uses when a
help-request is made. Since this information is available as XML, an
XSLT can be used to resolve the cross-links beforehand. I guess I will
have to write the XSLT to prove that this will really work but I am
confident that it will.
Sven
