Elements we use frequently

This section discusses the DocBook elements we use most in our
Firebird docs. It includes lots of examples in DocBook XML format. If you
use an XML authoring tool, what you see on your screen may look nothing
like the examples given here, but if you open your XML file in a text
editor – or choose a text view in your XML tool – you will see the actual
XML. You may also have a look at the XML sources that are already in the
manual module, to see how the other authors build up their docs and apply
tags.

Please read the subsection on hierarchical elements even if you're a
proficient DocBook writer, as it contains some guidelines specific to our
project. After that, you can skip the rest of the DocBook
subsections.

If you're new to DocBook, don't be discouraged by the length of this
section. My advice is that you carefully read the
subsection on hierarchical elements, and skim the others. Don't worry if
there are things you don't understand at once, and by no means try to
learn the material by heart! Just have this guide handy when you write
your doc, and revisit the element subsections from time to time (like when
you need them).

Hierarchical elements

The most common hierarchy is, starting at the top: <set> – <book> – <chapter> – <section> – <para>. A book may also contain <article>s instead of <chapter>s.

The next subsections will discuss some of the issues related to
the document structure.

The id attribute

Sets, books, chapters, articles and top-level sections should
always have an id attribute.
Other elements may also have one. The id allows an element to be
referenced from another part of the document, and even from another
document in the set. Ids are not visible in the rendered docs (except
in the HTML source text), but they are used to form the HTML file
names.

All id attributes must be
unique within the entire bookset. Note that the different language
versions each live in their own set, so it's OK to keep the original
ids in a translation.

Within a book or article, all ids should start with the same lowercase
word, e.g. usersguide, followed by a dash, followed
by one or more other lowercase words. Examples are
usersguide-intro and
usersguide-download-install. This is not a DocBook
requirement, but our own convention.

The lang attribute on
non-English sets

If you create a new set, or translate one, you must set the
lang attribute on the root
element:

<set id="firebird-books-fr" lang="fr">

This will ensure that the right captions are generated for
notes, warnings etc., and that localized quotation marks are used.
It's also good practice to use this attribute on the individual docs,
just in case they're ever build out of the context of your set.

For English sets, the lang
attribute is optional.

Titles

Sets, books, chapters, articles and sections must always have a
title – either as a direct child,
or within an xxxinfo element
(see below). It is even legal to include it in both, but in that case
the two titles
must be the same. Unlike id, which is an attribute, title is an element. And unlike the id, the
title will appear in the output docs.

If the title is long, you
should add a titleabbrev element
immediately after it, containing a shortened form of the title. The
main reason for this is that each generated HTML page contains a
so-called hierarchy bar or “you-are-here line” at the top
and bottom. This bar shows all the steps from the topmost element (the
set) down to the page you are on.
The items are clickable so the bar doesn't only give you an insight in
where you are in the hierarchy, but it also lets you navigate up to
the higher-level elements easily. It looks best if all the items fit
on one line, so for each item the titleabbrev is shown if the element in
question has one; if not, the title
is used. The same strategy is followed for the outline in the PDF
documents (that's the navigation frame on the left).

Info elements

If you write a book or an article, you must include a bookinfo or articleinfo element at the start. Inside it
you can put author information and more. Other xxxinfo elements
exist, but you will rarely need them.

If the author is a company or other organisation, or a group you
want to refer to as a collective, use corpauthor instead of author:

<corpauthor>IBPhoenix Editors</corpauthor>

If there are several authors and you want to name them
separately, create an author (or
corpauthor) element for each of
them and wrap them together in an authorgroup element – all within the
xxxinfo
element.

Types of sections

Section elements are a bit different from the rest in that there
are two flavors of them:

First, the <section>
element as mentioned earlier. It can be used recursively, i.e. you
can have a <section> in a
<section> in a <section>... This type has the advantage
that you can move entire subtrees up or down the hierarchy without
having to change the tags.

Then there's the <sect1>,
<sect2> ... <sect5> range. These elements must be
properly nested, with <sect1> at
the top, <sect2> within <sect1> etc. You cannot put a <sect3> directly in a <sect1>. This is less flexible than
<section>, but in practice it
rarely hurts. After all, the same “rigidity” applies
to <set>, <book> and <chapter> and we can live with that,
too.

Note

In early versions of this guide, the <sectN> series
was recommended for presentational reasons. Due to improvements in
the stylesheets, this is no longer an issue. Pick whichever you
want.

Appendices

You can add one or more appendix elements after the last chapter in
a book, or after the last section in an article. Appendices can
contain just about everything that a section can contain, including other
sections.

Example structure

The following example gives you an idea of how to structure your
document:

Some points to note

First, notice again that attribute values must always be
quoted. (But if you fill them in in an attribute editor, don't
insert quotes: the editor will take care of them.)

As you can see in the example, chapters and sections can start directly with one or
more para elements. But once
you include sections in a chapter, or subsections in a section,
you can't add any more para
elements after them – only within them. Good DocBook-aware XML
editors simply won't let you do such a thing, but if you type your
DocBook XML by hand this is something you need to be aware
of.

If you use an XML editor, chances are that you rarely have
to create para elements
explicitly. For instance, if I insert a chapter or a section in XMLMind XML
Editor, a first – empty – para is automatically created. And when
I type text in a paragraph and hit ENTER, that
paragraph is automatically closed with a </para> and a next one created.

The list you are reading right now, enumerating the
different types of lists, is a variablelist with the element names
(itemizedlist, orderedlist, etc.) as terms. The next
section – Links – also consists of one
introductory sentence followed by a variablelist.

Links

You can create hyperlinks to targets in your own document, in
another document in the set, or on the Internet.

link

link is the generic
element to point to another location in the document or set. The
linkend attribute must always
be present; its value should be the id of the element you link to (the
link target).

Click <link linkend="docwritehowto-introduction">here</link> to jump
to the introduction.

In the rendered document, the word
“here” will be hot
text, that is: a clickable link pointing to the
introduction:

Caution

Although you can use link to point to any element in the
entire set, you should only do so if the link target will be in
the same PDF document as the link itself. The HTML version is
fully hyperlinked, but links in the PDF rendering don't work
across documents. Our PDFs typically contain one book or article; if the target lies outside
the current document, use a ulink instead (see below).

ulink

Use a ulink to link to an
Internet resource. The url
attribute is mandatory:

If you want the hot text to be different from the email
address itself, use a ulink
with a mailto: URL.

Warning

If you include links to email addresses – whether with
email or with ulink – or even if you only
mention them in your text, and your
document is subsequently published on the Internet, these email
addresses will be exposed to harvesting robots used by spammers.
This will likely increase the amount of spam sent to such
addresses. Always make sure the owner of the address agrees
before publishing it!

anchor

An anchor is an empty
element marking an exact spot in the document. It doesn't show up
in the text that your readers see, but it can be used as a link
target. This is useful if you want to link to a place somewhere in
the middle of a long paragraph:

<para id="lost-at-sea">
Blah blah blah...
and some more...
and then some...
Now here's an interesting place in the paragraph I want to be able
to link to:
<anchor id="captain-haddock"/>There it is!
Paragraph drones on...
and on...
and on...
</para>

Having placed the anchor, you can create a link to
it:

<link linkend="captain-haddock">Go to the interesting spot</link> in
that long, long paragraph.

If your link targets a short element, or the beginning of an
element, it's easier to give the target element an id and use that as linkend.

Program listings, screens, literal layout, and examples

programlisting

If you include code fragments in your doc, put them in a
programlisting element.
Everything you type within a programlisting will be rendered
verbatim, including line breaks, spaces etc. Also, a fixed-width
font will be used in the rendered documents. The term
“program listing” is to be interpreted loosely here:
you should also use this element for SQL fragments and DocBook XML
examples. This guide – and especially the section about elements,
which you are reading now – is littered with programlistings, so you already know
what they look like:

Programlistings are rendered like this.

Important

In programlistings you should limit the line length to
around 70 characters, otherwise the text will run off the right
edges of the rendered PDF documents. The same goes for other
layout-preserving elements like screen, literallayout, etc.

screen

Use a screen element to
show what a user sees or might see on a computer screen in text
mode, or in a terminal window. Here too, your layout will be
preserved and a fixed-width font used, but the semantics are
different. It may or may not look different from a programlisting
in the output. Here's a short example, showing what happens if you
try to build a non-existing target in the manual tree:

literallayout, like
screen and programlisting, keeps your layout
intact, but it usually doesn't change the font – unless you set
the class attribute to
monospaced. It's also more
general than the previous two in the sense that there's no meaning
attached to its content: you can put any kind of text here of
which you want to preserve the layout.

Example source:

<literallayout>
The Sick Rose
Oh Rose, thou art sick!
The invisible worm
That flies in the night,
In the howling storm,
Has found out thy bed
Of crimson joy,
And his dark secret love
Doth thy life destroy.
— William Blake
</literallayout>

Output:

The Sick Rose

Oh Rose, thou art sick!
The invisible worm
That flies in the night,
In the howling storm,

Has found out thy bed
Of crimson joy,
And his dark secret love
Doth thy life destroy.

— William Blake

example

An example is a formal
example with a title. It is usually given an id so it can be referred to from other
places in the document. An index of examples is built
automatically when the document is rendered. You'll often find
programlisting's in an example, but it may also contain
screen's, para's, lists, etc.

Here's an example of an example:

<example id="docwritehowto-sql-example">
<title>An SQL example</title>
<para>With this command you can list all the records in the COUNTRY
table:</para>
<programlisting>SELECT * FROM COUNTRY;</programlisting>
</example>

In the output this will look like:

Example 1. An SQL example

With this command you can list all the records in the
COUNTRY table:

SELECT * FROM COUNTRY;

If you want an example without a mandatory title, use an
informalexample. Informal
examples are also left out of the examples index.

Tables

If you have ever made an HTML table for a website, you won't have
much difficulty creating tables in DocBook. There are differences
though, and DocBook tables are vastly richer.

A table consists of a title and one or more tgroups – usually one. The tgroup element has one mandatory attribute:
cols. You must set this attribute
to the number of columns in the tgroup. Within a tgroup you can place thead, tfoot and tbody elements. Each of these has one or more
rows, which in turn have as many
entrys (cells) as you have specified
in the cols attribute. (You can
combine cells by creating spans, but we won't go into that here.)

So much for the basic structure. Now we'll show you an example;
first in DocBook XML source text, and then the resulting table in the
rendered output document. Don't worry about the <colspec>s for now; these are non–mandatory
subelements used for finetuning.

By the way, these are the actual results of a real poll at
LinuxQuestions.org. As you can see, if only three more people had voted
for Firebird we would have won. If you know who these three persons are,
please report them to our Chief Inquisitor. He would like to have a
little, er... talk with them :–)

Tables are automatically indexed. An informaltable has the same structure as a
table but doesn't require a title and
is not included in the index. If you want to nest tables, either use a
table/informaltablewithin an
entry, or an entrytblinstead of an
entry.

Tables have many more features than shown here, but we'll leave
those for you to explore.

HTML tables

DocBook versions 4.3 and up also allow you to fill a table the
HTML way, with trs instead of
rows, and td/th
instead of entry elements. Why
would you want to do that? There are two situations where it may be
advantageous to use an HTML table:

You already have the HTML table available, and you'd rather
not spend time converting it;

You want to use several different background colors in the
table. This can be done in a DocBook table too, but only with
processing instructions – one for each
target for every child element that needs an explicit color. In an
HTML table you can use the children's bgcolor attributes.

An HTML table can't have tgroups; you put the trs either directly in the table or in
thead / tfoot / tbody elements which are direct children of
the table. Also, it has a caption
instead of a title. (An informaltable has neither caption nor
title.)

Not all HTML table elements and attributes are supported by our
stylesheets. For instance, properties specified in col and colgroup elements won't be picked up.
Specify them in the td/th elements instead – or extend the
stylesheets!

Note

In XMLMind, you can only create an HTML table from the menu
opened by the “Add table” button on the toolbar. From
the Edit pane you can only add regular DocBook tables.

PDF rendering of large tables

DocBook tables belong to a
group called formal elements. Formal elements
are included in automatically generated indices (list of tables, list
of figures etc.); if a formal element doesn't have an id attribute, the stylesheets assign one.
The templates that generate the XSL-FO output (this is the
intermediate stage for the PDF) also give each formal object the
attribute keep-together.within-page="always" to
prevent page breaks to occur within the object. This is usually fine,
but what if the object doesn't fit on one page? Until recently, we
used Apache FOP 0.20.5 to render the XSL-FO output to PDF. This
processor simply ignored the keep-together attribute if the object was
too large. But the current version (0.93 or higher)
always enforces it. The result is that if the
object is too large, it is truncated (or wrecked in some other way) to
make it fit on the page. This is a feature, not a bug, so there's no
use complaining about it.

There are two ways to work around this problem if a table grows
too large to fit on a single page:

If the table doesn't need a title and you don't mind that it
won't be included in the List of Tables, use an informaltable instead.

Place the cursor somewhere in the title or select the
entire title element.

Choose Edit -> Processing Instruction ->
Insert Processing Instruction Before from the menu.
A green line will appear above the title.

Type keep-together='auto' on that
line.

With the cursor still on the green line, choose
Edit -> Processing Instruction -> Change
Processing Instruction Target from the menu. A
dialogue box pops up.

In the dialogue box, change target to
dbfo and click OK.

Of course you can do the same for smaller tables if you want
them to be breakable. The opposite instruction, <?dbfo keep-together='always'>, will prevent
page breaks in informaltables.
Make sure that the element fits on one page before using
this!

Images

To include an image, use a mediaobject containing an imageobject containing an imagedata element:

You may wonder why you need three nested elements to include a
simple image. There's a good reason for this, but I'm not going to tell
you ;-) — it's of no concern to us. All we have to know is that this is
how it's done.

Regardless of the location of the image relative to the DocBook
source, the fileref should
always be of the form
images/filename.ext.
This is because, both for the HTML and the FO output, the image files
will be copied from their source locations to a subdirectory called
images under the output
directory. (The FO output is an intermediate form. Once converted to
PDF, the image will be included in the file itself.)

If the fileref is not “correct” from the source
file's point of view, you won't see the image in XMLMind. If this
bothers you, create a symlink to the images folder (Linux) or copy the
images folder into the same folder as the source file (Windows).
Creating a shortcut under Windows doesn't seem to do the trick. Only do
this in your local copy – don't commit duplicated image folders to
CVS!

A mediaobject is formatted as a
separate block. If you want the image inlined with the text, use an
inlinemediaobject instead; the nested
elements remain the same.

Note for translators

Translators: Any images that you don't edit or replace by a
localised version should not be copied into your language set. As from
January 2006, the build tools first look in your language's image
folder (e.g. manual/src/docs/firebirddocs-fr/images),
and after that in manual/src/docs/firebirddocs/images. So,
if you use the original image, there's no need to waste CVS space by
duplicating it.

The same behaviour applies to other base sets: if an image
referenced from, say, the Spanish Release Notes sources is not in
rlsnotes-es/images, the one in
rlsnotes/images is used. It
doesn't work across base sets, though.

Admonitions

DocBook has several tags to mark a block of text as a note, a
warning, a tip, etc. In the output documents such blocks typically
appear indented, and marked with an icon or a word to denote their
purpose. These tags are, in alphabetical order:

<caution>, <important>, <note>, <tip>, and <warning>

I will give you a <tip> as an
example; the others are used in exactly the same way:

<tip>
<para>If you insert a caution, important, note, tip, or warning
element in your text, don't start it with the word caution,
important, note, tip, or warning, because these words are usually
automatically generated by the rendering engine.</para>
</tip>

And this is the result:

Tip

If you insert a <caution>,
<important>, <note>, <tip>, or <warning> element in your text, don't start
it with the word caution,
important, note,
tip, or warning, because these
words are usually automatically generated by the rendering
engine.

You may have noticed that the words caution,
important etc. look different from the rest of the
tip's text. How come? Well, to tell you the truth, I've surrounded them
with special tags (first with <sgmltag>s, the second time with <literal>s) to make them look like that. But
this made the source XML look very noisy, so I decided to remove those
tags from the example source I presented to you.

You can optionally give the admonition a title. If you don't, a default header (in the
document language) will be generated in the output.

If you want to set off a block of text from its surroundings
without marking it as a tip or whatever, use a <blockquote>.

Paragraph headers

If you want a paragraph header or title without creating a
subsection, there are a few possibilities.

bridgehead

A bridgehead is a
free-floating title between paragraphs, not associated with the
start of a chapter or section. The renderas attribute determines how it
will be rendered.

<para>You may remember that Mr. Hardy started with this firm as
elevator boy and with grim determination worked his way up to
the top. And after the wedding today he becomes General Manager
of this vast organisation.</para>
<bridgehead renderas="sect5">Mr. Laurel's comments</bridgehead>
<para>We also spoke to his lifetime friend and companion Mr. Laurel.
Mr. Laurel says that after viewing the situation from all sides,
he is thoroughly reconciled to the fact that the moving picture
industry is still in its infancy. Mr. Laurel also states that
technology, whilst it may appear to be the center of all—</para>

The above source is rendered as:

You may remember that Mr. Hardy started with this firm as
elevator boy and with grim determination worked his way up to
the top. And after the wedding today he becomes General Manager
of this vast organisation.

Mr. Laurel's comments

We also spoke to his lifetime friend and companion Mr.
Laurel. Mr. Laurel says that after viewing the situation from
all sides, he is thoroughly reconciled to the fact that the
moving picture industry is still in its infancy. Mr. Laurel also
states that technology, whilst it may appear to be the center of
all—

You are free in your choice of renderas level, but the logical choice
would normally be the current section level plus (at least)
one.

formalpara

A formalpara is a
paragraph with a title. Our stylesheets render the title as a
run-in head.

<formalpara>
<title>Motherly love:</title>
<para>This is the love your mother has for you, not to be
confused with brotherly or otherly love.</para>
</formalpara>

In the output this looks like:

Motherly love: This is the love your mother has for you, not to be
confused with brotherly or otherly love.

A period will be appended to the title, unless it already
ends with a punctuation character.

Various inline elements

To conclude the subsection on DocBook elements I will now briefly
introduce a number of inline elements. They are
called “inline” because they don't interrupt the flow of
the text. If I use e.g. an emphasis
element:

Don't <emphasis>ever</emphasis> call me fat again!

the result is this:

Don't ever call me fat again!

The word “ever” is emphasized, but it keeps its place
in the sentence. We've already encountered some inline elements before:
the various link types. Other elements – like table, warning, blockquote and programlisting – are always displayed as a
block, set apart from the surrounding text (even if you
“inline” them in your XML source). Not surprisingly, these
are called block elements. Block elements often
contain inline elements; the reverse is not possible.

OK, let's get started with those inline elements. I'll include
examples – both XML source and rendered output – for most of
them:

filename – command – application – envar

Use the filename tag to
mark file names in the broadest sense. Attributes can optionally
indicate that the file is a header file, a directory, etc.

Place your doc in the <filename
class="directory">src/docs/firebirddocs</filename> subdirectory.

The output reads:

Place your doc in the src/docs/firebirddocs
subdirectory.

command and application are both used for executable
programs. command is usually
chosen for smaller programs and internal commands; its content
should be the exact command as given on a command line; application is generally used for bigger
programs and need not be the name of the executable file. Both can
refer to the same program:

Type <command>netscape&amp;</command> in a terminal window to start
<application>Netscape Navigator</application>.

This is rendered as:

Type netscape& in a terminal window
to start Netscape Navigator.

envar denotes an
environment variable.

subscript – superscript

These two do the expected thing:

After inventing the formula e = mc<superscript>2</superscript>, I
really felt like a glass of liquid H<subscript>2</subscript>O !

Output: After inventing the formula e =
mc2, I really felt like a glass of
liquid H2O !

varname – constant – database

The use of varname and
constant should be obvious. The
<database> tag is not only meant
for databases, but also for database objects:

The <database class="table">COUNTRY</database> table has two fields:
<database class="field">COUNTRY</database> and
<database class="field">CURRENCY</database>.

Use emphasis to stress
words in general, citetitle for
book titles etc., and firstterm
if you introduce a new word or concept to your readers:

We use <firstterm>DocBook XML</firstterm> for our Firebird
documentation. A short introduction follows;
<emphasis>please</emphasis> read it carefully! If you want to know
more about the subject, buy <citetitle>DocBook – The Definitive
Guide</citetitle>.

Output: We use DocBook
XML for our Firebird documentation. A short
introduction follows; please read it
carefully! If you want to know more about the subject, buy
DocBook – The Definitive Guide.

quote – literal

Use quote for an inline
quotation (as opposed to a blockquote). Quotation marks will be
inserted automatically. Using quote instead of typing the quote
characters yourself (which is also perfectly legal) has the
advantage that we can alter the type of quotation marks through
stylesheets if we want to. Also, quotes differ per
language:

Please note that you shouldn't use the lang attribute on quotes in your own docs. Your root
element's lang attribute will
ensure that the right type of quotes are used. If someone
translates your document – and changes the root lang attrib – it will be rendered with
the quotation marks for the target language. Of course I had to
use the attribute here to show the difference, and to make sure
that the different quotation marks survived any
translation.

A literal is a word or
text fragment to be taken literally. It is a rather general
element, often used to make certain words stand out
typographically:

At all costs avoid using the word <literal>humongous</literal> in
your documentation.

Output: At all costs avoid using the
word humongous in your documentation.

Should you always use these inline elements wherever you can?
Well, if you do, you will certainly make your document richer; you'll
make it easier to scan for filenames for instance, or to generate an
index of all the applications mentioned in your document. On the other
hand, there are so many of these semantic elements (in fact we've only
discussed a few here) that if you apply them
everywhere you can, you'll probably wind up in a straightjacket before
you can finish your doc. This is not what we want: if you really have to
go mad, please do so after you've committed your
document :–)

So, as a general advice: go a bit easy on those inlines; use them
wherever you think it makes sense, but don't overdo it.

To wrap up the elements

You may have noticed that in the rendered documents (you're
reading one now, unless you opened the XML version) many different
elements have the same appearance: a filename, a literal and an application may have the exact same
typography; the same goes for emphasis, firstterm and citetitle.

So what's the point of all these different tags? Why not use just
a few, like emphasis and literal, if they're going to look the same
anyway? Well, there are two very good reasons not to:

First, if we dropped most of our inlines in favor of say,
emphasis and literal, the semantics would be lost.
Remember that DocBook XML is all about structure and semantics.
firstterm and citetitle may look
the same as emphasis once
rendered, but they are not the same thing. The
XML source knows that, even if it doesn't always show. This
information is useful, and we don't want to lose it.

Further, we can adapt our stylesheets for each type of element
individually. As soon as we decide that a firstterm should look different from a
citetitle, we can arrange for
that – but only if they are indeed marked with
different tags, not if they are both emphasis's in the XML source.

This concludes the sections on DocBook. With the knowledge
presented above, you should now be able to author DocBook XML documents
for the Firebird project. Of course if you use a dedicated XML editor –
which, again, is highly advisable – you must also consult its
documentation to learn how to use it; that's one thing this guide
doesn't cover.