Every piece of documentation in our manual module is part of a <set>. This is the topmost element in the DocBook hierarchy. A set contains a number of <book>s, which in turn contain <chapter>s, and so on.

One advantage of placing books in a set is that they can reference each other, i.e. you can insert links in your documentation pointing to an exact spot in another book. This advantage is limited however by the fact that such links don't work across PDF file boundaries (a restriction that doesn't apply to the HTML output). Another advantage is automatic ToC (Table of Contents) generation.

Fortunately, placing books in the same set does not imply that they also have to live together in one big file. DocBook allows you to set up a main document as shown below. (Don't worry about the section starting with "<!DOCTYPE" – you won't have to write horrible stuff like that yourself. At the very worst you will have to copy and edit it, if you translate an existing set.)

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE set PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
  "docbookx/docbookx.dtd" [
    <!ENTITY preface SYSTEM "firebirddocs/preface.xml">
    <!ENTITY fb-intro SYSTEM "firebirddocs/firebirdintro.xml">
    <!ENTITY ...>
    <!ENTITY ...>
]>

<set id="firebird-books">
  &preface;
  &fb-intro;
  ...
  ...
</set>

With the main document set up like above, the various books can be in separate files: preface.xml, firebirdintro.xml, etc., which we can edit independently. Such a file – yours, for instance – is roughly structured like this:

<?xml version="1.0" encoding="UTF-8"?>

<book id="fbintro">
  <chapter id="fbintro-preface">
    ...
    ...
  </chapter>
  <chapter id="fbintro-installing-firebird">
    ...
    ...
  </chapter>
  ...
  ...
</book>

Of course if you set up a new document it must be made known to the main set, but this is something we'll discuss with you when you're ready to start writing. (We don't give a general rule here because it depends on what you're going to write – a book, an article, a chapter, a couple of chapters... – and how your work fits in with the rest.)

Every DocBook file must start with this line:

<?xml version="1.0" encoding="UTF-8"?>

(Note: for some languages, UTF-16 will be the better choice.)

If you write your documentation “by hand”, i.e. in a text editor, you must type that line yourself. If you use a dedicated XML editor, it will be inserted automatically when you create a new document.

If you type your DocBook XML in a text editor like Notepad, emacs or ConText, you can use linebreaks, indentation and multiple spaces more or less as you please. Every occurrence of whitespace (a sequence of one or more space, tab, linefeed or formfeed characters) will be converted to a single space character in the output. So this:

<section><title>Firebird Architectures</title><para>Now let's have a
look at Firebird's different architectures.</para><itemizedlist>
<listitem><para>First, there's the so-called <firstterm>Classic Server
</firstterm>.</para></listitem><listitem><para>Then there is <firstterm>
Superserver</firstterm> architecture.</para></listitem><listitem><para>
And finally, with the release of Firebird 1.5 we also have the 
<firstterm>embedded server</firstterm>.</para></listitem></itemizedlist>
</section>

will result in the same output as this:

<section>
  <title>Firebird Architectures</title>
  <para>Now let's have a look at Firebird's different
    architectures.</para>
  <itemizedlist>
    <listitem>
      <para>First, there's the so-called 
        <firstterm>Classic Server</firstterm>.</para>
    </listitem>
    <listitem>
      <para>Then there is <firstterm>Superserver</firstterm> 
        architecture.</para>
    </listitem>
    <listitem>
      <para>And finally, with the release of Firebird 1.5 we also
        have the <firstterm>embedded server</firstterm>.</para>
    </listitem>
  </itemizedlist>
</section>

Needless to say, the second form is much easier to read and understand for a human. So if you type your XML by hand, format the text in such a way that the structure is as clear as possible. Like the prophets said: “Indent! Indent! Indent!” (Or was that repent? No, I'm sure it was indent.)

If you use a dedicated XML editor, please be aware that hitting Enter may automatically close the current <para> and open a new one. Make sure you know how your editor behaves in this respect, and use the Enter key accordingly. Also check what happens to multiple consecutive whitespace characters, as some XML editors may use special tricks to preserve them.