Hi, Michael Natterer <mitch@xxxxxxxx> 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 problems. 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" /> </gimp-help> 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", "/usr/share/gimp-freetype/help/refs.xml" "http://freetype.gimp.org/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" /> </gimp-help> 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 scripts. 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). Sven
