(The following represents my evaluation. Although it
contains many facts, you may weigh up them differently.)
Why not DocBook?
Some people have asked why I created a new XML format and didn't choose
DocBook as the basis for my transformations.
Well, first of all: I don't know any free DocBook tool that produces
output that is decent enough for me. Typically the printed output is not
very beautiful and many things simply don't work (e.g. formulae). So I
felt forced to create transformations by myself anyway.
Nevertheless I could have chosen DocBook as the starting point. I
didn't do this because:
- DocBook is highly optimised for technical documentation which is a
very important but also very narrow field. This is the underlying reason
for some of the following points.
- DocBook is huge. While tbook has 80 elements,
DocBook has almost 400. However many of them deal with extremely specific
things (e.g. environment variables), so for general purpose these elements are
irrelevant. On the one hand you are not forced to use the entirety
of DocBook, on the other hand every effort with DocBook is multiplied by its
- You (the author) have to get at least an overview of all the DocBook
- The DTD has to be read by the text editor or the transformer every time,
which can be annoyingly slow even on modern computers.
- Every transformation tool has to cope with all elements. (Believe me,
the 80 tbook
elements are hard enough.)
- DocBook forces to use deep nesting. While tbook has a rather "flat"
structure, DocBook very often makes one or two additional elements necessary.
For example, a graphics in DocBook is included with
<figure label="1.1" float="1">
<imagedata fileref="galaxie.png" format="PNG"/>
whereas in tbook
you just say
<graphics file="galaxie" kind="vector"/>
- DocBook's content models are too liberal. Sometimes one gets
the impression that you can use any DocBook element within any other DocBook
element. Although this is not true of course, I dislike such arbitrary
is rather strict and yet it covers most document structures that you can find
in books, papers, and theses. This has some advantages:
DocBook's arbitrary content models allow for absurd constructs and, even worse,
make it impossible to write transformation programs that can guarantee to
work. Instead they must hope that you don't use all features of DocBook
which is very unfortunate in my opinion.
- It forces you to write a well structured and well ordered document which is
a good thing in my opinion (and in your reader's opinion probably).
- It enables XML editors to help you greatly with the input.
- It simplifies the creation of useful tbook tools.
- I miss many things in the DocBook DTD. While it's still not
totally clear how math will eventually look like in DocBook, I especially need
and a couple of further elements and attributes. I could add these
elements to DocBook, but this wouldn't be DocBook anymore and therefore
existing DocBook tools wouldn't work anyway.
- something like the <psfrag> element for neat graphics
- overlay graphics (bitmap+vector),
- the style and class attributes that are extremely
practical for Web output,
- a connection to BibTeX files for my literature,
- explicit horizontal lines in tables,
- a formula element with simple non-MathML syntax,
- a <letter> element,
- DocBook tries to enforce pure logical markup to its
fingertips. I don't think that this is the right way. For large
structures like chapters and lists logical markup is a good thing, so tbook uses it, too.
However for inline text you may need more control, and thus you need
visual markup. For example, if you say in a table caption "certain
values are printed in bold face" you want to set them easily and safely to bold
face. Or, you may want to print a warning in red, or include a skip
between two paragraphs. DocBook intentionally supresses such
wishes. But for me it's hard to write real world texts without
implements visual markup very carefully, and makes use of the lessons we've
learned from visual markup in LaTeX.
- DocBook's processing expectations often are too
unspecific. Two typical examples. DocBook's
<computeroutput> element has the following processing
expectation: "[...] It’s often presented in a fixed width
font." For many people it may be sufficient to assume something, but
I as the author want to know such things, so this "often" is too
wishy-washy. The same is true for labelling of figures, tables etc.
You simply don't know which figure will get which number eventually. So
the numbering may be different in different copies of your text which is
unacceptable if for example people talk about your text by phone. tbook is rock-solid in this
- DocBook's customisation is too difficult. For example if you
want to change the main font, for tbook it's sufficient to create a one-line text file
in the current directory. Good LaTeX and CSS interfaces make it very
simple to customise the layout of tbook documents. In typical DocBook tools such
tasks are much more difficult and usually involve to modify style sheets
written in an exotic computer language.
- And, finally – you can convert tbook to DocBook so that you can use all tools of the
DocBook world. Although the transformation exploits DocBook as much as
possible, the transformation isn't lossless. (Not surprising after the
I'd lose credibility if I didn't mention the other side. If your texts
don't have a very complex structure (e.g. no formulae, no bibliography, no
index) the differences melt down to the non-existence of really nice free
DocBook conversion tools. If, additionally, the output quality is not too
important, or you are prepared to write your own conversion tools (as some
people do), DocBook may well be sufficient for you.
Every tool has its purpose. DocBook's purpose is technical
documentation. For example, tbook's manual pages are written in DocBook.
I'd have even written tbook's main documentation in DocBook, too, but the
Texinfo system turned out to be even better suited for this task.
To sum it up: DocBook for technical documentation and special
tasks like manual pages, and tbook for scientific texts. For general texts you may use both, however tbook is simpler and –
if you don't want to program yourself – produces nicer output.
Torsten Bronger, mailto:email@example.com.