An Internationalized Software Project With Auto Tools
Prev Documentation Overview Next

Documentation Overview

While the steps discussed so far were quite staight forward, adding a documentation is an uncommon field. First the documentation format is important. A wide range exists, from text files, man and info pages on command line tools, to html or xml pages, hlp and chm files on gui based applications. For portable gui applications a user friendly help format is required, which exists on linux/unix as well as on windows. Here the choice was html help.

HTML Help

Html help is a set of .html files, which must obey some constraints. These files can be showns with any html viewer. This is the help solution on linux/unix. On windows a few additional files (.hhk, .hhp, .hhc) have to be added to be able to compile these help files into a single .chm file, which is a user friendly help system on windows. The exact format of all these files is discussed elsewhere; as they are not created directly, it is of no interest here.

As .html files can be created with any html editor easily, using them to write a documentation seems to be good solution. Unfortunately, .html files are not translatable. While a translator can off course use an html editor to write a translated documentation, there is no merge tool like gettext, which marks changes in the original documentation and merges the translated changes into the translation.

po4a

po4a (short for: po for all) is an open source project, which wants to make the power of gettext available to other file formats, not only source code. To do so po4a provides (among others) three command line tools: These three tools allow the creation of a translation workflow similar to the localization of the program messages. There are just two drawbacks: first the created po files are somtimes still hard to maintain. po4a becomes powerfull, if the documentation is large and changes only in some areas. Second, po4a does not allow html as source format. Therefore the html help files need to be generated as well from a source code supported by po4a

Docbook

Docbook is an xml usage (style sheet) which allows to write even complex documentations. There are some docbook processors (like xsltproc), which generate common help files formats (like html help) from docbook .xml files. This conversion is controlled by an .xsl file.

Documentation Worklflow

Therefore general documentation workflow implemented here is as follows: As the result on linux/unix, a set of html files exist for each language. On 'make install' these are copied to a configurable directory. The name of this directory is passed to the main programm as a compiler option, so that the executed program can locate the help files and show them in an html browser.

On windows one chm file is created for each language. These files differ in their file name and exist in the same directory than the executable, so that it can launch the corresponging help file.

Next this workflow is implemented step by step.
Prev Home Next
Using gettext Adding HTML Help Documentation