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 DocBookhere
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:

Postscript, for printing.

PDF or HTML for online viewing.

RTF, for importing into Microsoft Word or other word-processing
programs.

... and others, such as ISO standard ODF (for OpenOffice.org and other programs)
or Word OOXML (docx),
depending on what DocBook
conversion software is
available to you.

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?

v3.1 SGML

v4.1.2 XML

v4.2 XML

v4.3 XML

v4.4 XML

v4.5 XML

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:

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 db2psor docbook2ps(DocBook-to-Postscript),
db2pdfor docbook2pdf(DocBook-to-PDF),
db2htmlor docbook2html(DocBook-to-HTML),
and db2rtfor 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:

PRO: The XSL-FO converter can create not only the
PDF, RTF, and
HTML files as the Linux converter can, but can also create native OOXML
(for Word 2007) or ODF (for OpenOffice.org).

PRO: The RTF conversion is better than what I've
become acccustomed to with
the existing Linux utilities, in that some troublesome elements like
footnotes (and possibly hyperlinks) are converted more
accurately. The extra RTF accuracy I mentioned applies to Word 2003, but not necessarily to
other versions of Word.
[It's worth noting that Microsoft changes the RTF specification
slightly with each version of Word,
so not every version of RTF works equally well with every version of Word. In fact, to put it
bluntly, some things that work in earlier versions no longer work in
later versions, and I suppose the converse must be true as well.]

CON: I've had absolutely no luck trying to convince the
XSL-FO converter to create the PDF bookmarks necessary for a bookmark
pane when viewing the document in Adobe Acrobat Reader or similar
programs. On the other hand, the tables of contents in the PDF
files are clickable, and therefore provide most of the same benefits as
the bookmark pane would

CON: I've had limited luck trying to get the XSL-FO
converter to number the pages as I desire. (Roman numerals for
the table-of-contents, and restarting the page numbers at 1 with the
actual body of the text.)

Difference: The XSL-FO
converter uses XSL stylesheets rather than DSSSL stylesheets, so
the stylesheet modifications I suggest above
won't work as given. I have made
some changes to the XSL stylesheets that come with the converter, and
these changes are available to you if you
download the Do178Builder
development snapshot. Consult the README file in the
snapshot for instructions. (You must use my stylesheet in
conjunction with the stylesheets distributed with the XSL-FO
converter if
you expect to produce something like the sample documents
below.) I actually provide two XSL stylesheets. One,
Do178Builder.xsl, is designed for compatibility with the DSSSL
stylesheets; the compatibility isn't perfect, but the results are
somewhat similar. The other, MyCustomization.xsl, is a
jumping-off point you can use to customize the stylesheets for your own
purpose; it happens to produce a result that's somewhat visually
similar to a document template they like us to use at the company for
which I work, and includes some flourishes like a logo in the page
headers.

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.

Created
using the db2pdf converter,
in Linux, with DSSSL stylesheets.

Created
using the xslutility converter

and
the Do178Builder.xsl
stylesheet.

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 Postscript or PDF: Use EPS (Encapsulated PostScript)
format.

For HTML: Use any of the formats a typical browser can
support,
such
as GIF, JPG, or PNG. The default used by the conversion is GIF,
but
can be changed by editing the default stylesheet. (On my SuSE
Linux
system, for example, I changed "gif" to "png" in the
%graphic-default-extension%
entry of the file /usr/share/sgml/docbook-toys/suse-both.dsl.
Locating
the appropriate stylesheet on your system might be an effort.)

For RTF: The default graphics format is EPS.
Unfortunately,
if you load the RTF file into Microsoft Word with embedded EPS
graphics,
the graphics won't be previewed on screen, and will only print on
Postscript
printers. It's therefore better to use another graphic format
(like
JPG or PNG). I haven't found out yet how to change the default.

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.