Firebird DocsetFirebird Docwriters' DocsFirebird Docwriting Guide → Setting up your DocBook doc
Firebird home Firebird home Prev: DocBook XML authoring toolsHome: Firebird DocsetUp: Firebird Docwriting GuideNext: Elements we use frequently

Setting up your DocBook doc

Creating the document
Typing text

Hello – still with us? I know I spent quite some time explaining about XML and DocBook, but I really feel I had to do that because these are new concepts to a lot of people. Just giving them some links and telling them to go find out by themselves would probably lose us some otherwise valuable docwriters.

Anyway, here we are: finally ready to start writing our doc. This section discusses setting up your DocBook document; the next one is all about applying the right tags and attributes in the right places.

Creating the document

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.

File locations for the different sets

Files for the English user documentation set must be placed in the manual/src/docs/firebirddocs directory tree. Non-English docs go in trees like manual/src/docs/firebirddocs-fr, manual/src/docs/firebirddocs-es, etc.

Since January 2006 we have the possibility of creating additional base sets, the first one added being rlsnotes, the Release Notes set. The same logic applies here: English Release Notes stuff goes into manual/src/docs/rlsnotes, French into manual/src/docs/rlsnotes-fr, and so on.

Each of these directory trees – firebirddocs, firebirddocs-es, firebirddocs-nl, rlsnotes, rlsnotes-fr, etc. – houses a separate <set>, with one master document and any number of include files.

Typing text

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.

Prev: DocBook XML authoring toolsHome: Firebird DocsetUp: Firebird Docwriting GuideNext: Elements we use frequently
Firebird DocsetFirebird Docwriters' DocsFirebird Docwriting Guide → Setting up your DocBook doc