Firebird Documentation Index → Firebird Docwriting Guide → Setting up your DocBook doc |
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.
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.
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.
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.
Firebird Documentation Index → Firebird Docwriting Guide → Setting up your DocBook doc |