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.
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).
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.
Infos
- Markdown: http://daringfireball.net/projects/markdown/syntax
- DocBook Project: http://docbook.sourceforge.net
- reStructuredText: http://docutils.sourceforge.net/rst.html
- DAPS: http://opensuse.github.io/daps/
- Publican: https://fedorahosted.org/publican/
- Yelp: http://yelp.io
- DAPS installation: https://github.com/openSUSE/daps/blob/master/INSTALL.adoc
- Apache FOP: http://xmlgraphics.apache.org/fop/
- DocManager: https://github.com/openSUSE/docmanager
- DAPS documentation: https://opensuse.github.io/daps/doc/index.html
- Publican Git repository: https://git.fedorahosted.org/git/publican.git
- gettext: https://www.gnu.org/software/gettext/
- Publican documentation: https://jfearn.fedorapeople.org/en-US/Publican/4.0/html/Users_Guide/
- Mallard: http://projectmallard.org
- Gnome Yelp wiki: https://wiki.gnome.org/Apps/Yelp/
- DoCookBook: http://doccookbook.sourceforge.net
- "Mallard" by Mario Blättermann, Linux Pro Magazine, issue 132, November 2011, pg. 54
- Dita community: http://dita.xml.org
- DITA Open Toolkit: http://www.dita-ot.org
« Previous 1 2 3
Buy this article as PDF
(incl. VAT)