KNOW HOW Docbook
Writing Docbook Files with Open Office
Writing Assistant
Docbook is the de-facto standard
for technical documentation. Open
Office helps to prevent XML format
documents from turning into a
coding nightmare.
BY ROLF STRATHEWERD
he Docbook format is a good
choice for program manuals. Web-
Tsites, books, manpages and an
integrated help system can all be gener-
ated from a central XML file. And this
would seem to save you a lot of work at
first glance. Open Source projects like Figure 1: The latest Open Office versions (1.1 RC3 in our example) can handle Docbook files. Styles are
Gnome and KDE, and companies such assigned to various XML elements to provide this functionality
as HP or Sun, all use Docbook for this
reason. realistic. Just like Docbook, the native The second incarnation tried to use
But, unfortunately, a closer look Open Office format is based on XML. only native Open Office tools, and to
reveals how verbose the Docbook format Just don t be fooled by the sxw suffix on read Docbook files in the word proces-
really is. Longer text passages without Open Office text files. SXW files are sor. The developers cautiously described
any formatting are simple enough, but simple ZIP archives. Among other com- their implementation as a proof of con-
tables, lists, interfaces and other ele- ponents (such as embedded images), cept, and it failed to achieve similar
ments might tax your typing skills. XML they include the text itself in a file called results to OOo2sDBK.
editors can help you with this work, but content.xml that contains the XML Open Office 1.1 includes a develop-
the actually coding can be bothersome. formatted document. As the Open Office ment based on this variant, and thus
Also, learning a special language just for framework supports filter based file supports Simplified Docbook (a  lite
documentation is a lot of work. If the importing and exporting, it should be version of the standard). RC3 (Release
manual is to be written by mere mortals simple to integrate the Docbook format. Candidate 3) already provides beta stan-
 as opposed to programmers  it makes But actually, it is not quite that simple. dard Docbook functionality, although the
sense to keep it simple. The first implementation of this idea documentation does not quite match the
One practical and obvious approach was by Éric Bellot. Éric adopted an usual software. The basic statements are
would be to allow technical authors to approach for his OOo2sDBK [4] (Open appropriate, but some detail is not quite
use a normal word processor. This would Office org to simplified Docbook) tool, up to date, which can lead to confusion
take some of the load off authors without opting to use Python and Saxon as at times.
the required Docbook skills, although it conversion tools, rather than native
XML Variants
does assume automatic conversion of Open Office tools. As Éric was only inter-
the results. ested in an Open Office to Docbook Although both Open Office and Docbook
converter  Éric did not envisage a round use the XML data format, there is one
Open Office as a Docbook
trip  and, being French himself, only major difference between the two. Doc-
Editor
provided French language documenta- book has nothing to do with the
Open Office has quite a few of the pre- tion, the program did not prove overly document layout. Its tags only specify
requisites that make this approach sound popular. the function of a text passage (the name
42 December 2003 www.linux-magazine.com
Docbook KNOW HOW
of the author, headings, or body text), package. The latter is essential for con- transformation. The first technique re-
without actually specifying the appear- verting from and to Docbook. The quires a stylesheet, such as the sample at
ance. This task is handled by stylesheets typical point of departure is a document [3]. The XML file additionally needs the
that help produce the final layout of the style called DocBookStyle.stw, which document. Referring to the stylesheet resides in path to Open Office/share/ type= text/css ?> tag adding to the
allows attributes such as italicized xslt/docbook/. This style document authors names and headings in larger includes all the styles required to work gant CSS technique assumes a state-
font sizes to be applied. with Docbook. of-the-art browser.
In contrast to this, word processing The Stylist provides an initial The second approach allows you to
systems are not typically concerned with overview. You can press [F11] to display choose the target format. One of the sim-
the content and its structure, but with a list of styles. The list includes some plest transformation types produces a
the appearance of the text. Formatting default styles and the new additions for large HTML file:
instructions directly influence the Docbook. Figure 1 shows a typical view,
appearance of the text. If you select based on a sample text file. saxon example.xml /Path/docbookU
Courier, 8 point, bold and green for a text Selecting Save as& and then DocBook /html/docbook.xsl > example.html
passage, these attributes will be lost dur- (simplified) as the format, tells Open
ing conversion to Docbook format. Office to generate an XML file. Figure 2 Sourceforge [5] provides a number of
Indirect style-based formatting allows shows the structure of the file. If you useful transformation scripts. There are
these two worlds to co-operate. Authors look closely, you will note that the attrib- also alternative processing tools to the
can use styles to mark up a text passage utes bold and italics have disappeared. Saxon utiliy [2].
as a heading, for example. The style con- The scripts do not convert these attrib- Some of you may be wondering why
tains details of the layout applicable to utes to Docbook tags, although the text you should go to all this trouble, just to
headings. is retained. produce HTML. Open Office can do that
You can use two methods with XML anyway, and can even generate PDF doc-
Practical Applications
files created in this way: online format- uments as of version 1.1. Although this
In addition to Open Office 1.1 (at least ting with CSS (Cascading Style Sheets) objection is valid, Docbook does offer
RC3) [1] you will need a current Java or XSL (Extensible Stylesheet Language) some advantages when you need to sep-
advertisement
KNOW HOW Docbook
Listing 2: Export Extension

name="programlisting">



Just like an Open Office text, a
Docbook file is subdivided into sections.
You can define a section explicitly by
selecting Insert | Section or implicitly by
applying styles to a text. The styles
Heading 1 through Heading 4 are exam-
ples of the latter. There are three
additional sections that an author can
specify explicitly if required: ArticleInfo,
Abstract or Appendix (these names are
case-sensitive!).
Graphics are another minor pitfall. If
the author checks the Link checkbox
when inserting a graphic, Open Office
will not display the results correctly,
Figure 2: The Docbook XML code generated from the test document and viewed in Mozilla Firebird unless the graphic is declared as an
inlinegraphic. Make sure that you retain
arate the content from the presentation, ments of the nested structure first, and the original external image file in this
for example, when several people are using the stylist to format them, before case. In contrast, embedded graphics are
working on a project where a uniform going on to convert the whole area into a placed in the SXW file. The same applies
appearance is required. bookmark with a specific name. You can to other media objects.
assume that this approach will be
Limits More Tags for Open Office
adopted by the final Open Office 1.1
Éric Bellot s OOo2sDBK encountered release, unless a superior method is A glance at the list of supported tags in
some difficulties which have not quite found in the meantime. The current Table 1 shows that some of these tags are
been resolved so far. For example, Open release (RC4) does not implement this not part of the Simplified Docbook for-
Office does not provide any native facility. mat: such as the interface elements
means of producing nested tags, The developers have devised an guibutton or guimenu. These tags are
although there are situations where Doc- interim solution for the articleinfo area, specified by the full Docbook standard.
book needs them; such as metadata in using several global variables to store the On the other hand, important elements,
the articleinfo tag. The author info for a appropriate information. Each variable such as programlisting are missing.
document needs to be nested as shown has a serial number starting with Luckily, it is quite simple to resolve this
in Listing 1. articleinfo.author_0.firstname_0, which issue.
Although Open Office is now capable expects the first name of the first author Open Office uses only one document
of generating some of these tags, the of the current document. These variables style and two XSL stylesheets to support
documentation describes a completely are hidden in the menu below Insert |
different method. According to the docu- Fields | Other.
Listing 3: Import Extension
mentation, the author is required to use
Pitfalls
bookmarks, specifying the inner ele-
match="programlisting">
Take care when loading an existing Doc-

book file. As Open Office only supports a
Listing 1: Docbook
subset of all tags, the results may not be
File Author
name="text:style-name">Source
what you expect, if you save the file.
Text
Avoid saving files under their original
Rolf
names. Cross-check the XML code with
Strathewerd
Table 1 to find out where and when you

are likely to run into any issues.
44 December 2003 www.linux-magazine.com
Docbook KNOW HOW
the whole range of Docbook functions.
Table 1: Compatibility
Both stylesheets (for the data export and
XML-Tag Supported XML-Tag Supported
import facilities) are stored with the style
abbrev link '
below /Path to Open Office/share/
abstract ' listitem '
xslt/docbook.
acronym literal
To add a tag, first edit the sofftodoc-
appendix ' literallayout
bookheadings.xsl stylesheet. This style-
articleinfo ' mediaobject '
sheet provides the export function. The
attribution note '
Source Text paragraph style is a useful
affiliation ' objectinfo
starting point for the programlisting tag.
application1 ' option
Listing 2 shows the lines you need to
article ' olink1 '
add. Use the text block as the section.
audioobject ' orderedlist '
Open Office will now save programlist-
audiodata orgname '
ing, but you need to tell Open Office to
authorblurb othercredit
load the tag to provide a genuine round authorinitials othername
trip. This is just as easy, as can be seen authorgroup para '
author ' phrase
in Listing 3.
biblio.. programlisting
This enhancement was quite simple
blockquote ' pubdate
because Source Text is already defined as
caption ' publishername
an Open Office style. To define other
citetitle quote
styles, you would also need to add the
colspec ' releaseinfo '
styles to the style. But again, doing so is
command ' replaceable
not difficult. Selecting Format | Styles |
computeroutput ' revdescription
Catalog will take you where you need to
copyright ' revhistory
go.
corpauthor revision
date revnumber
Conclusion
edition ' revmark
It does look like the Open Office team
editor row '
was bragging when it promised full sup-
email section '
port for Simplified Docbook. At a second
emphasis ' sectioninfo
glance, the support provided is less com-
entry ' sidebar
plete than might be expected. The
epigraph subject
functionality turns out to be a mixture of
example subjectset
Docbook and Simplified Docbook, which
figure subjectterm
was obviously compiled with software filename ' subtitle '
documentation in mind. This is a prag- firstname ' subscript1 '
footnote ' superscript1 '
matic approach designed to tempt
guibutton1 ' surname '
anyone looking to write documentation
guimenu1 ' systemitem '
into risking typing a few lines.
guisubmenu1 ' table '
However, the current version cannot
highlight1 ' tbody '
be recommended for more complex doc-
holder term '
umentation projects. The fact that style-
honorific textobject
sheets are easily extensible does auger
imageobject ' tgroup '
well for the future  maybe a few gener-
imagedata ' thead '
ous code donors can help the Open
informaltable ' title '
Office project on its way. %
inlinemediaobject titleabbrev
issuenum trademark
INFO
itemizedlist ' ulink '
[1] Open Office: http://www.openoffice.org/
inlinegraphic ' userinput '
jobtitle variablelist '
[2] Saxon: http://saxon.sourceforge.net/
keyword varlistentry '
[3] Sample stylesheet:
keywordset videodata
http://www.oasis-open.org/docbook/
keycap1 ' videoobject
xml/simple/4.1.2.5/sdocbook.css
keycombo1 ' volumenum
[4] OOo2sDBK: http://www.chez.com/
keysym1 ' xref '
ebellot/ooo2sdbk/
legalnotice year '
[5] Transformation scripts for Docbook:
1
These tags are not simplified Docbook tags,
linage
http://sourceforge.net/projects/docbook/ although they are specified in the full standard.
www.linux-magazine.com December 2003 45