I’m at my second tutorial of the day, on DocBook, an XML DTD for
technical documentation. I’m not really looking at this from an open source
project perspective, just as a general tool. I have a feeling that this
would be a good thing to use in general. The peaker is Bob Stayton from
Sagehill Enterprises.
DocBook has been around since 1991, originally for SGML, though we’re
looking to use it for XML. It not only includes the DTD that describes the
legal syntax, but also related stylesheets and tools. (There’s a
DocBook
SourceForge project where lots of these tools are maintained and available.)
I like the idea of using this is that the documentation gets marked up
based on the meaning of the information, not based on the look you want.
After you get all the content created, then you worry about what it
looks like, using stylesheets to format a single file in many different
ways. There are great free multi-platforms publishing tools, and it’s common to take a
single source file and get HTML, XHTML, XSL-FO (for PDF creation), HTML
Help, man pages, TeX, RTF, JavaHelp, and others.
Note that DocBook is not a word processor or layout tool, like Microsoft Word or
FrameMaker. It’s not visual, it’s based on the meaning of content. Oh, and
it’s not simple, so it has a long learning curve.
DocBook is particularly good when youneed multiple output formats, long
term maintenance of documentation over multiple releases, long documentation
sets, and shared authoring. It’s good for software documentation. It has a
lot of tags designed specifically for these kinds of documents, has lots of
open source tools available to build one, and can be built via make files
every time the application gets built. It’s widely used in the open source
community (Linux Documentation Project, FreeBSD, Red Hat, GNOME, KDE,
PostgreSQL, PHP), as well as by large companies (like Sun, IBM, Microsoft,
and HP).
The DocBook DTDs are at version 4.2, managed by OASIS (Organization for
the Advancement of Structured Information Standards). It has 388 elements.
Of course, XML users mostly use schemas now, rather than DTDs. There’s an
experimental schema (or two) available now that can be used instead of the
DTD.
The presenter wrote a web
tool that allows you to explore the DocBook XML DTD as a
hypertext document. This should help deal with all those 388 elements.
How can we write DocBook files? Well, any text editor can do it, so long
as we like typing angle brackets. Graphical editors that understand DocBook
and let you work at a higher level include
XMetaL and
ArborText.
Once you’ve written DocBook files, how can you check that they’re right?
The graphical tools include the functions, otherwise you can use
xmllint, which is part of libxml2.
The command to validate a file is xmllint –noout –valid
filename.xml. OpenSP is another tool, part of
OpenJade. The command for
this is onsgmls -s -wxml -wno-explicit-sgml-decl xml.dcl
filename.xml. (And who says open source tools can be hard to use?)
Let’s say we have validated DocBook files. What do we do with them? We
describe the output format we like with stylesheets (regular XSL or DSSSL
which is an SGML kind of stylesheet with good samples available for
DocBook). Then process the files to get the nice output with processing
tools. If the stylesheets are XSL, we can use any XSLT processor such as
Saxon, xsltproc,
Xalan, msxml from Microsoft,
and others. If we want to use XSL-FO, we can use Apache FOP,
PassiveTeX
(which interests me; I’ve been using TeX for twenty years), and
commercial products.
For DSSSL (pronounced diss-ull), there is
Jade from James Clark,
OpenJade, and commercial products.
So do we use XML or SGML? XSL or DSSSL? For new projects, XML is
probably the way to go. There’s no great reason to convert existing SGML to
XML, but going forward XML is te way to go. And the XSL versus DSSSL
decision is only even available with XML. XSL has more tools and is clearly
the future. But if you want to generate print files, the free DSSSL tools
are more mature than the free XSL-FO tools.
Now, what I’ve been waiting for: writing DocBook! Here’s an example.
<?xml version="1.0"?> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/xml/4.2/docbookx.dtd"> <book> <title>Using a mouse</title> <para>The mouse controls the pointer.</para> <chapter> <title>Mouse buttons</title> <para>A mouse has one, two, or three buttons.</para> </chapter> </book>
That’s a complete legal DocBook “book”. In DocBook, you can write a file
that represents a set of books or one book. The
hierarchy is:
<set> <book> <part> (optional) <preface> <chapter> <reference> <appendix> <glossary> <index>
Within those elements you have hierarchies available (such as sections
within a chapter). There are two ways to tag sections:
<chapter> <section> <section> <section> <section> <section>
or
<chapter> <sect1> <sect2> <sect2> <sect1> <sect1>
The second way forces you to decide on nesting levels. The first way lets
you drag a section inside another section, nesting them. In the second way,
you’d have to retag the outer section to nest it in another section.
If you aren’t up to a complete book you can write an article
(generally like a single chapter), which is good for white papers.
Block elements are things like paragraphs, lists, notes, examples.
In output, they will start on a new line and end with a line break, with
lines wrapping inside of it (generally). Block elements can nest, or they
can contain regular text or inline elements. Inline elements
appear within a line of text, with no implicit line breaks before or after.
Inline elements can contain just text, or can nest. Text display
elements preserve whitespace and can control
fonts and font styles.
Writing text. In DocBook (and XML in general) you can write text between
open and closing tags, and that becomes the content of the element.
However, some characters can’t be used: <, >, and &. You’ve got
to escape those characters by writing them as <, >, and
&. Or we can use CDATA:
<![CDATA[unescaped content that can go on and on. ]]>
Formal displays are elements like figure, example, table,
equation, because those elements not only contain content, they are numbered
and titled.
Graphics are tricky, because different target formats use
different graphics formats. You might want a GIF for a web page, but EPS
for a printed page. Graphics are represented by mediaobject
elements. These elements each contain one or more imagedata
elements, one for each output format you might want, as in:
<mediaobject> <imageobject role="html"> <imagedata fileref="mouse.gif"/> </imageobject> <imageobject role="fo"> <imagedata fileref="mouse.eps"/> </imageobject> </mediaobject>
Cross references. You can cross reference (e.g., link) within a
single file, or between files. Use the linkend attribute to point to
a target element that has an id attribute. The xref element
generates link text, and link uses the text content. Both work only
within a single document. Use olink to link between documents.
Here’s an example:
<chapter id="Mouse"> <title>Using a Mouse</title> ... see <xref linkend="Mouse"/>.
the output when translated to HTML would look like
See <a href="#Mouse">Chapter 3, Using a Mouse</a>.
In printed text, the output might add a footnote at the point of the xref,
with the footnote containing the same text and a page number.
Using external cross references is more complicated. The olink
element uses two attributes: targetdoc to point to another document,
and targetprt to point to an ID in that document. This requires
setting up a target database and creates dependencies between the documents.
And it’s break time.
Charles Engelke's Blog 