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

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.