Publishing systems for DocBook XML
Lost in Translation
One of the documentation team's important tasks is to collaborate with translators. This involves localizing XML source code, replacing images, and managing updates. The SUSE team uses the locdrop
DAPS option for exporting files and then imports the completed translation using unpack-locdrop
. The SUSE developers have also created an open source tool in the form of DocManager [9], which cooperates with DAPs and manages the workflow of documentation projects with the help of metadata.
A comprehensive user manual [10] and a quick start guide – made with DAPS, of course – provide users with a detailed explanation on how to use the complex suite and leave virtually no questions unanswered.
Publican
Publican [5] is available in the Red Hat, Fedora, Debian, and Ubuntu package archives. If you have openSUSE, note that it can only be installed on version 12.1 or later. Just as with DAPS, developers can also check out the publishing system from Git [11] to use the most recent version.
Red Hat's Publican system also uses DocBook XSL stylesheets and Apache FOP to generate various output formats. Perl serves as an integration language. Important information, such as the DocBook version and the document class, can be found in the ~/publican.cfg
and <project_name>/publican.cfg
files.
The publican
command supports a large number of actions and has a very long man page: publican create
generates a new documentation project, publican build
produces output from HTML to PDF and help plugins for Eclipse, and publican clean
deletes temporary files.
The build action also supports the test
format, which doesn't build anything but checks whether a particular language version of a document can be built without errors:
publican build --formats=test --langs=de-DE
The Publican developers came up with a viable workflow for internationalization and localization and have added it to the Publican command. A document project has a separate directory for each language version; the directory is named per the ISO language code, such as pt-BR
for Brazilian Portuguese. The
publican update_po --langs=hi-IN,ru-RU
command tells Publican to extract the character strings to be translated for Hindi and Russian from the DocBook XML and package them in appropriate directories.
The PO format from GNU gettext [12] is used in this case, and widespread tool support is available. The format is also suitable for translation portals from open source projects, for which volunteers choose work packages to translate themselves. Publican currently supports more than 40 languages; standard content, such as formatting conventions, are already localized.
Publican provides functions for identifying unused XML or image files, for displaying used or prohibited DocBook tags, or for packaging as aids for a documentation project workflow. Packaging is not just for RPMs, but also for importing into CMS Drupal or as a website with a search engine-optimized sitemap.
Brands
As a publishing system for RHEL, Fedora, Gimp, and the like, Publican uses brands to adapt documents to the corporate design. Debian has its own Publican brand in its package archive, and a generic-looking common
package is in the public domain.
Designers can also create their own brands. The
publican create_brand --name=LM --lang=en-US
command creates a style directory for Linux Pro Magazine (Figure 3).
Its files contain the word SETUP
in the places that need customization. They are easy to find using the grep
command (Figure 4):
grep -rHn --color=auto 'SETUP' *
Furthermore, standard image files, such as the logo, need to be replaced and the overrides.css
stylesheets need to be edited. Publican can package brands as RPMs or as tarballs. If you don't want to create a package, you can use the --brand_dir
option to specify which brand directory you want to use. Red Hat's team rounds off the Publican tool with a detailed manual [13].
« Previous 1 2 3 Next »
Buy this article as PDF
(incl. VAT)