Home
DO-178B
Do178Builder
Tutorial
Samples
DocBook
Birds Project
About DocBook		  
Bird Man, a painting by artist Lynn Rothan

Contents

What is DocBook?
Why do we use DocBook format?
What Versions of DocBook are Used?
Customizing Stylesheets to Get the Perfect Document Style
Converting DocBook documents, under *NIX and (Hopefully) Mac OS X
Converting DocBook documents, under Microsoft Windows
Graphics

What is DocBook?

DocBook is an SGML or XML based markup language designed for producing books and technical articles.  (In SGML or XML terminology, DocBook is a DTD.)  You can find out more about DocBook here or here.

Why do we use DocBook format?

We use DocBook to isolate data maintenance from document formatting.  If I had to support all kinds of document formats within the Do178Builder program itself, I'd never even have attempted to write the program in the first place.  Why reinvent the wheel?

A DocBook file containing a DO-178B document can be easily converted with freely available utilities into a variety of formats:

Furthermore, you have a lot more control over the exact format of these conversions than you would have if Do178Builder directly printed your documents.  Each of the conversions is based on a "stylesheet," and by changing the stylesheet you can change the output appearance.

Personally, I'd advise you to publish directly to PDF, and avoid the temptation to convert the stuff into Microsoft Word for manual reformatting.  It's the kind of thing that seems easier in the short term, but eats enormous amounts of time in the long run.  Of course, you're free to do as you like.

What Versions of DocBook are Used?

Traditionally, Do178Builder has used only DocBook SGML v3.1.  Even at the time Do178Builder was first created, v3.1 was not the most up-to-date version of DocBook.  However, Do178Builder did not really require most of the features in DocBook, and therefore didn't need to keep up with the latest version.  Furthermore, the documentation for v3.1 was and is online, while the documentation for later versions lagged somewhat.  (To be honest, I bought the v3.1 guide in a used-book store before I even knew what DocBook was, let alone that it was going to be central to any of my plans, and I hated to waste the $5 I had spent on the book....)

Beginning with Do178Builder's 20080127 development snapshot, optional support for DocBook XML v4.x has been added.   The reason for this is that while DocBook v3.1 remains available, and it remains perfectly feasible and simple for Linux users such as myself to continue using that version, on more primitive platforms such as Microsoft Windows it is somewhat more problematic to do so.  Tools on that platform tend to want to support only XML, and only DocBook v4.x.  Consequently, I've chosen to add some extra support for those poor, sad Windows users.  After all, they have a hard enough time of it already, without my adding to their woes.  And, in the intervening years, the full documentation for DocBook v4.x has become available (at the link listed above), so that's no longer a reason to avoid DocBook 4.x.

By default , v3.1 SGML is still used.  If you start Do178Builder with one of the command-line switches "--x412", "--x42", "--x43", "--x44", or "--x45", then v4.x XML will be used instead.  This is explained in more detail on the tutorial page, where the command-line switches are described in detail. 

Since DocBook 3.1 is not precisely compatible with DocBook 4.x, and since DocBook SGML is not exactly compatible with DocBook XML, some philosophical choices have had to be made regarding the exact style of DocBook markup that Do178Builder uses to implement various effects.  Wherever possible, of course, compatible markup is used.  Where compatible markup is not possible, Do178Builder always chooses to use DocBook 3.1 SGML markup internally; however, it converts the markup as necessary to DocBook 4.x XML when output files are created, so it's not something you normally have to worry about unless you manually add your own markup for DocBook commands that Do178Builder doesn't directly support.  In that case, you may get markup that will work for you, but that Do178Builder cannot automatically convert if a different version of DocBook is selected later.

Customizing Stylesheets to Get the Perfect Document Style

The default appearances of documents converted from the DocBook SGML/XML into PDF or other printable forms are very good, in my view, and could easily be used without change.  But you may want a little more control, perhaps to conform to your company's standard for document formats.  Perhaps you need different page headers, or different fonts, or a watermark.  In that case, you can tweak the default stylesheets to get exactly the appearances you like.  And of course, you only have to tweak the stylesheets once, rather than for every document set.

(I guess I should warn you that one obstacle you may face in using Do178Builder is that it could take an enormous effort to customize the DocBook stylesheets so greatly that you can match an arbitrary style that has been created in Microsoft Word—and realize that all styles are arbitrary.  Once you've heard a boss proclaim with all sincerity that a DER will be confused and couldn't possibly approve your software documentation because the company logo doesn't appear 0.5" from the upper left-hand corner of the page in those documents, you'll know what I mean.)

The stylesheets provided with the usual Linux-based DocBook converter programs are written in a language called DSSSL (Document Style Semantics and Specification Language).  The same stylesheets seem to work both the DocBook SGML 3.1 and DocBook XML 4.x. 

I should also mention that some DocBook converter programs may use stylesheets that are written in XSL (eXtensible Style Language).  XSL stylesheets are much more complex than DSSSL stylesheets, and my understanding of them is more limited, so I can't really explain here how to customize them.  With that said, however, in the source tree for the Do178Builder program that you get when downloading the development snapshot there is an XSL stylesheet called Do178Builder.xsl that can be used to publish documents not unlike those that you can get using the DSSSL stylesheets, and another XSL stylesheet called MyCustomization.xsl that you might be able to use as a starting point for making some of your own customizations.  I say "not unlike" rather than "the same", because I haven't figured out how to fully modify them to get exactly identical results to the DSSSL stylesheets.  But they're close enough for government work.  The README file in the development-snapshot source tree describes how to use them with the XMLmind converter program (see below).  So I'll discuss only the DSSSL stylesheets here.

The default DSSSL stylesheets are pretty complex, and it is apparently best to limit your changes (when you can) to changing a few default values.  This is explained in section 4.4 of the first edition of DocBook: The Definitive Guide, which the authors (Walsh & Muellner) and the publisher (O'Reilly) have graciously made available online.

The specific DSSSL stylesheet customizations I prefer to make for printable documents are listed below; yours will undoubtedly be different:

;; Do178Builder options.
(define %funcsynopsis-decoration% #t)
(define %admon-graphics-path% "./")
(define %admon-graphics% #f)
(declare-characteristic preserve-sdata?
    "UNREGISTERED::James Clark//Characteristic::preserve-sdata?"
    #f)
(define %two-side% #f)
(define %paper-type% "USletter")
(define %generate-article-toc% #t)
(define (toc-depth nd) 10)
(define %generate-article-titlepage-on-separate-page% #t)
(define %article-page-number-restart% #t)
(define (article-titlepage-recto-elements)
  (list (normalize "corpname")
        (normalize "title")
        (normalize "subtitle")
        (normalize "corpauthor")
        (normalize "authorgroup")
        (normalize "author")
        (normalize "abstract")
        (normalize "releaseinfo")
        (normalize "pubdate")
        (normalize "copyright")
        (normalize "legalnotice")
        (normalize "graphic")))
(define %generate-article-toc-on-titlepage% #f)
(define %section-autolabel% #t)
(define %visual-acuity% "presbyopic")
(define %generate-part-toc% #t)
(define %graphic-default-extension% "jpg")
Figuring out where on your system the DSSSL stylesheets are stored may be a bit of a trick.  Carefully examining the messages displayed when actually converting DocBook files (as described in the next section), you may find that the name of the default stylesheet is listed.  Here are some default stylesheets of which I am aware:

Converting DocBook documents, under *NIX and (Hopefully) Mac OS X

Many of the major Linux distributions contain (for free) all of the tools you need for converting the DocBook DO-178B documents as described above.  All you have to do is make sure the tools are installed.  Debian, SuSE, and Fedora or Fedora Core Linux fall into this category, to my knowledge.  But with some effort, you can install the tools on any Unix-type operating system, even if not included with your distribution.

The programs for the conversions are called db2ps or docbook2ps (DocBook-to-Postscript), db2pdf or docbook2pdf (DocBook-to-PDF), db2html or docbook2html (DocBook-to-HTML), and db2rtf or docbook2rtf (DocBook-to-RTF).  These are actually scripts, based on the free programs jade (or openjade) and TeX (or LaTeX).  Using them is completely straightforward.

For example, suppose that I have used Do178Builder to create PSAC.sgml.  Then to create a PDF file from that, I'd use the command

db2pdf PSAC.sgml

Or if (say) I had used Do178Builder with the command-line switch "--x45" to create PSAC.xml, then I could convert that to an RTF file for importing into OpenOfficeor Microsoft Word  with the command

db2rtf PSAC.xml

Using programs like db2pdf, db2rtf, etc., is not the only alternative for performing DocBook conversions under Linux.  The method described in the following section (covering Microsoft Windows) using the XMLmind XSL-FO converter program works perfectly well also.

By the way, while I've had no problems to speak of in converting DocBook 3.1 SGML using the commands described above on any Linux in which I've tried it, I have seen cases where some problems occur in the conversion of DocBook 4.x XML.  Specifically, on my Fedora Core 5 box, scripts like db2pdf and db2rtf will print some silly error messages and refuse to perform an XML conversion unless you do a little hacking on them first.  On Fedora Core 1, Fedora Core 5, and Fedora 8 systems, db2pdf is a simple one-line script reading

jw -f docbook -b pdf "$@"

To get it to work properly in Fedora Core 5, I had to modify it to say instead

jw -f docbook -b pdf --dcl /usr/share/sgml/xml.dcl "$@"

Presumably, a similar fix works for db2rtf, or other conversion scripts.

Converting DocBook documents, under Microsoft Windows

I believe that one way to convert DocBook under Windows is to install Cygwin, which is a sort of Linux emulator for Win32, and then to install the DocBook tools under Cygwin, so that you could use the same commands and stylesheet modifications mentioned above.  But I've not done it myself.  If/when I know more about doing so, I'll post it here.

One reader (Chris Lambrecht) has pointed out that the XMLmind XSL-FO Converter (xslutility) is capable of performing the conversion under Windows.  Actually, XMLmind converter is a Java program—there's also a .NET version—and thus is a cross-platform program that can run not only on Windows, but presumably on Linux, Mac OS X, FreeBSD, or any other operating system with Java support.  I personally have tried it both on Windows and on Linux.  The XMLmind converter comes in two flavors:  the "Personal Edition" (which is free) and the "Professional Edition" (which is quite expensive, by my standards).  As near as I can see, the Personal Edition has all of the capabilities you'd need for use with Do178Builder, so there would be no technical need to purchase the Professional Edition.  On the other hand, while the Personal Edition is free of cost, it is not open-source, and you must agree to a license that makes it unclear whether you'd be allowed to use it within the context in which DO-178B/DO-254 documents are typically created.  Nor is there any guarantee that the Personal Edition will be available (or available for free) in the future, so I'd think you'd be unwise to make it a central part of any documentation strategy.  But I'd advise you to read the license for yourself, and make your own determination.  (Actually, the XMLmind converter seems to be largely but not completely based on the open source projects Saxon and Apache FOP, and you may be able to get mostly the same results by using those programs, but I've not tried it.)

If you are able to use the XMLmind converter program, then there are some pros and cons vs. using the db2XXX scripts described in the preceding section:
For a visual comparison, below are PHAC documents (the DO-254 Plan for Hardware Aspects of Certification) for the fake "Birds PLD" project described elsewhere on this website.  The only differences between the methods of creation for the various PDFs were that different DocBook converter programs were used (db2pdf vs. xslutility), and different stylesheets (DSSSL vs. XSL); in other words, Do178Builder produced a single set of DocBook 4.1.2 XML files, and that same set of DocBook XML files was post-processed for all of the PDFs.

Click to enlarge.

Created using the db2pdf converter,
in Linux, with DSSSL stylesheets.
Click to see the PDF file

Created using the xslutility converter
 and the Do178Builder.xsl stylesheet.
 Click to enlarge

Created using the xslutility converter
and the MyCustomization.xsl stylesheet.

The XSL-FO converter program itself is quite straightforward to operate, and doesn't really require any instructions.  It may be worthwhile to note that some of the stylesheet parameters can be adjusted through the converter program's user interface without having to modify the stylesheets themselves, but it's an obscure enough feature that you may need to hunt around to figure out how to do it.

By the way, as I mentioned in the preceding section, the XMLmind XSL-FO converter program works perfectly well under Linux also.  If you choose to do so, here's a little trouble-shooting tip:  The converter program requires true Java, and does not work correctly with the replacement GNU gij program installed by default in some Linux distributions.  This is true on my Fedora Core 5 system, for example.  Fortunately, the Java JDK (www.sun.com) can be downloaded and installed for free, but doing so does not necessarily turn it into the default Java used.  You can find out what Java is being used with the command

java -version

If this shows that gij will be run, you need to perform some kind of trickery to make sure that true Java is used by the XMLmind XSL-FO converter program instead of gij.  Various tricks will work, such as moving the directory which contains the 'java' executable to someplace early in the PATH.  Perhaps the easiest thing to do is to edit the xslutility file itself, which happens to be a script, so that 'java' has a full pathname.

Graphics

Originally, this section contained a description of the best graphics formats to use, relative to the type of document format (PDF, RTF, etc.) you wished to create.  However, for a number of years I have simply been using JPEG graphics across the board, regardless of the output format, so I assume that a discussion of this topic is no longer needed.

Production of text-only documents with Do178Builder is perfectly straightforward, but including graphics (such as organization charts) is marginally trickier.  The problem is that not all of the target formats can accept the same graphic-file format.  So, unless you're absolutely sure how you intend to convert the DocBook files, you may need to supply the same graphic in several formats.  Here's a summary of the formats you should use: For example, consider including an organization chart into your DO-178B documents.  You might provide the graphic in two formats, say OrgChart.GIF and OrgChart.EPS.  Within Do178Builder, when you specify the filename of the graphic file, you'd simply use "OrgChart."  The file-extension ".GIF" or ".EPS" would be filled in for you automatically during the document conversion.

Without changing the default extensions, I know of no really clean way to handle the graphics for an RTF document.  The best solution I've found so far is to produce the graphics in a format good for Microsoft Word, such as JPEG, but to simply rename the files as if they were EPS files before converting the documents.  For example, create OrgChart.JPG, but rename it to OrgChart.EPS.  Hopefully, a much cleaner solution can be found.

This page was last modified by Ron Burkey on 03/12/2008. Contact the Birds Project.