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).

Figure 3: A simple brand can be designed for Linux Magazine within minutes with Publican and applied to a document.

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].

Figure 4: Publican can generate a unique look for documents. Developers need to customize passages containing the SETUP keyword.

Buy this article as PDF

Express-Checkout as PDF
Price $2.95
(incl. VAT)

Buy Linux Magazine

SINGLE ISSUES
 
SUBSCRIPTIONS
 
TABLET & SMARTPHONE APPS
Get it on Google Play

US / Canada

Get it on Google Play

UK / Australia

Related content

  • Gnome 2.12

    Gnome 2.10 reconquered many desktops with its return to values such as simplicity, clarity, and ease of use. The new Gnome 2.12 GNU desktop environment continues this emphasis on the basics.

  • Asciidoctor

    The popular AsciiDoc documentation system still has a lot to offer, but more experienced users should check out Asciidoctor, which has some additional new features.

  • AsciiDoc

    AsciiDoc syntax along with its eponymous command lets users create a text document with unobtrusive markup and convert it to a variety of output formats.

  • Open Hardware – Ebook Publishing

    LibreOffice, Calibre, and Sigil help would-be authors with do-it-yourself ebook publishing.

  • Command Line – unoconv

    A hidden utility in the LibreOffice toolbox, unoconv offers a wide array of import and export filter options for use at the command line.

comments powered by Disqus
Subscribe to our Linux Newsletters
Find Linux and Open Source Jobs
Subscribe to our ADMIN Newsletters

Support Our Work

Linux Magazine content is made possible with support from readers like you. Please consider contributing when you’ve found an article to be beneficial.

Learn More

News