Publishing systems for DocBook XML

Yelp

The help browser for the Gnome desktop environment goes by the name of Yelp [6]. It can display DocBook documents, among other things, without the need for conversion up front (Figure 5). It comes with the yelp-tools package, which according to the Yelp homepage contains small programs for creating, editing, managing, and publishing documents. The DocBook and Mallard [14] input formats are supported. Mallard is similar to DocBook but uses a simpler repertoire of XML elements and uses a separate file for each text section.

Figure 5: Gnome's help browser Yelp displays DocBook documents, but the documentation is less complete.

If you need information about the yelp-build tool, for example, you will notice that the documentation available on the Yelp website is pretty sparse. Although the tool supports DocBook versions 4 and 5, it seems to be a second class citizen: The attractive EPUB target format is the reserve of Mallard, as is the option to use a cache for converting (Figure 6).

Figure 6: The Yelp documentation is sparse and shows a strong preference for the Mallard format.

Reading material on yelp-new for new documents is sparse as well, but yelp-check is worthy of note: It validates DocBook XML, checks cross references and external links, ensures the integrity of image files, and finds extraneous files.

Ironically, what is most missed in Yelp tools is a decent manual to provide users with an overall picture of how to create a documentation project and how the individual tools fit into the workflow, from initial stages to output formats. The Gnome wiki [15] is not much help and cites outdated or even missing pages.

Summary

DAPS and Publican are full-fledged systems that DocBook professionals – and newcomers, too – can use to manage their documentation projects from start to finish. They both go above and beyond individual manuals because they support sets (i.e., collections of books) with cross references that are guaranteed to work.

Both tools reign in their particular domains: DAPS supports WebHelp output and many graphics formats; the manual also reveals how developers can migrate existing DocBook projects to the suite. Publican, on the other hand, makes it easy to create unique brands. The SUSE group is quite active in terms of layout and design, too, but its focus is on customizing DocBook XSL style sheets. Team member Thomas Schraitle devotes a whole book to the topic as an open source project [16].

Another advantage of the Red Hat tool is that Publican has integrated localization, which will appeal to anyone wanting to implement widespread language support. Publican also packages RPMs for Fedora and RHEL and can handle Red Hat's Brew build system.

Gnome's Yelp draws the short straw, mainly because of the poor documentation for the documentation tool. It is also the reason for the gaps in the general overview in Table 1. However, the lack of DocBook capability only matters if you insist on using this format; after all, Gnome help can be written pretty easily with Mallard [17].

Table 1

Feature Overview

Name

DAPS

Publican

Yelp

License

GPLv2 or GPLv3

GPLv2+ and Artistic License 1.0

GPLv2+

Version

2.1

4.3

3.16

XSL formatter

DocBook XSL

DocBook XSL

Yelp XSL

PDF formatter

Apache FOP

Apache FOP, Wkhtmltopdf

Not specified

Glue code

Bash, Make

Perl

C

Own themes

Yes

Yes

Not specified

Source text input formats

DocBook XML 4 and 5

DocBook XML 4.5 and 5

Mallard, Docbook XML 4 and 5

XML spellcheck

Yes

Rudimentary

Not specified

Link check

Yes

Yes

Yes

Draft watermarks

Yes

Yes

Not specified

Annotations

Yes

Yes

Yes

Custom layouts

Yes

No

Not specified

Own themes

No

Yes

Not specified

Output formats

HTML, HTML single, WebHelp, TXT, MAN, PDF, PDF grayscale, Mobi, EPUB

HTML, HTML single, HTML desktop, TXT, MAN, PDF, EPUB, Eclipse

HTML, XHTML

Localization

Own tool DocManager

Installed, uses GNU gettext

Via xml2po

Extras

RPM, Emacs macros, XML Bigfile, partial builds

RPM, Brew integration, website, Drupal export, accessibility (Section 508)

DocBook display

Conditional text

Yes

Yes

Not specified

Outlook

Topic-oriented publishing manages sections with similar content as standalone components, compiles them to create larger units, and rehashes the results. Mallard shows a tendency toward topic orientation, but the buzzword among documentation authors is Darwin Information Typing Architecture (DITA) [18]. Like DocBook, the XML architecture specification is maintained by an Organization for the Advancement of Structured Information Standards (OASIS) working group.

A collection of useful tools is already available under the Apache license in the form of the DITA Open Toolkit [19]. The Yelp developers are experimenting with DITA, as well.

The Author

Mathias Huber is an avid Linux user and works in the documentation department of thin client specialist IGEL Technology.

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.

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

  • Tea 26.0.0 Editor Can Handle Lua, Perl and Vala

    Tea, a source code editor for HTML, DocBook and Latex, is now available in version 26.0.0. The new release includes support for more programming languages and new features.

comments powered by Disqus

Direct Download

Read full article as PDF:

Price $2.95

News