Multilingual Eclipse help using Docbook
June 8th, 2010 by Alexander NittkaBased on Robert’s blog on creating an Eclipse Help plugin, I want to extend that example to support multiple languages. By default, Eclipse seems already to interpret toc.xml, contexts.xml (for contexts defined using the contexts extension point) and the html-files from an nl/de, nl/fr,… directory within the plugin if the corresponding locale is set in the Eclipse start parameters.
So the idea is to adapt the sample to allow docbook sources for all wanted languages within the plugin. There are other objectives that I want to address here:
- some support for keeping help in synch for all languages
- try to support some basic context help
In this post, I will not present many snippets but only briefly describe the intentions of the sample help project (download here).
You’ll have to copy the docbook-xml-4.5- and docbook-xsl-files to the corresponing directories in the project as described in Robert’s blog. Note that you don’t need the modified eclipse33.xsl file. For our purposes, we further extended that file and it is included in the docbook-directory and automatically used. There you also find the build script. I have limited experience with xslt and ant (not to say none), so there is much room for improvement.
The docbook directory should contain one subdirectory per language named corresponding to the intended locale (the sample has one for German and one for English). The script assumes that for each language the root xml file is called manual.xml. After first running the script (which probably fails) a run-configuration is created. In the JRE-tab, choose “run in the same JRE as workspace” as described in Robert’s blog. Afterwards, the build should be successful.
If you don’t change the parameters, a contexts.xml will be generated. It basically contains all ids you define in the docbook sources along with a link to their location in the generated html file. Also a ContextConstants.java is generated which contains java-constants for all those ids. Why that? The idea is to simplify a basic context sensitive help. Usually you don’t write a help plugin for its own purpose but for documenting some other set of plugins.
Assuming, you have defined a view in some plugin (and it implements Adaptable) you can use the following code to get a link to the documentation for that view in the dynamic help (please make getInternalHelpContext in HelpUtil.java a public method…)
public Object getAdapter(Class adapter) {
if (IContextProvider.class.equals(adapter)) {
return HelpUtil.getInternalHelpContext(
APxHelpUtil.ConstantForContextThatShouldBeUsedForTheView);
}
...
}
When the dynamic help view is open this should cause a see-also-link to the documentation to be displayed.
The generated constants make sure that the context you call actually exists (otherwise you get a compile error, as the constant is not known). But they also help you to keep the help for different languages in synch. Ideally, the structure of the help is the same for all languages and only the texts differ. So for every language you would use the same ids for chapters, sections etc. If sturcture and ids are indeed the same, the generated ContextConstants will be identical for all languages. If not, they differ and you have feedback that something is wrong.
There are a couple of things missing. If there are broken links in the docbook files (i.e. pointers to non-existent ids), the build process does not fail. The generated html files will contain ???. It would be cool if there was some automatic report for that. Also, the help will not work if toc.xml or contexts.xml contain a & as in ä. For some characters, there is a replace statement in the build.xml but it would be nice, if the “correct” characters were already generated. Anyway, I have tried to provide helpful comments in the build script so that you should get an idea what is going on and have hints for making your own adaptions. Note that contexts.xml and plugin.xml will “always” be overwritten, so if you want to define your ones, you have to adapt the script and the transformations accordingly.

