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:
po4a-gettextize: extracts all translatable strings into a pot file (like xgettext),
po4a-translate: recreates original files from the pot file or a translated version from the translated .po files and
po4a-updatepo: merges the translated .po files, if the original files have been changed.
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:
The documentation is written in english in docbook .xml files. Pictures are allowed. An additonal .xsl file
controls the conversion of these files.
xsltproc is used to convert the .xml files into .html files. These are the final english documentation files on
linux/unix. Additionally an .hhk, .hhc and .hhp file is generated by xsltproc for the .chm file generation.
On windows the help compiler hhc is used to create a windows help file .chm from all the files generated in the previous step.
This is the final english documentation file on windows.
po4a-gettextize is used to create or update the .pot file with all translatable strings from the source .xml files. po4a-updatepo
is used to create or merge it into the language dependent .po files. The .po files are translated by the translators.
po4a-translate is used to create translated .xml files from the translated .po and the source .xml files. For each translated .xml
file set, xsltproc is used to created the .html files and hhc is used to create the .chm file. These are the translated help files.
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.