|Firebird Documentation Index → Firebird Docwriting Guide → 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).
The most common hierarchy is, starting at the top:
<para>. A book may also contain
<article>s instead of
The next subsections will discuss some of the issues related to the document structure.
Sets, books, chapters, articles and top-level sections should
always have an
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
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
usersguide, followed by a dash, followed
by one or more other lowercase words. Examples are
usersguide-download-install. This is not a DocBook
requirement, but our own convention.
If you create a new set, or translate one, you must set the
lang attribute on the root
<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
attribute is optional.
Sets, books, chapters, articles and sections must always have a
title – either as a direct child,
or within an
(see below). It is even legal to include it in both, but in that case
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.
title is long, you
should add a
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
is used. The same strategy is followed for the outline in the PDF
documents (that's the navigation frame on the left).
If you write a book or an article, you must include a
articleinfo element at the start. Inside it
you can put author information and more. Other
exist, but you will rarely need them.
<book id='usersguide' lang='en'> <bookinfo> <title>Firebird Users Guide</title> <author> <firstname>William</firstname> <surname>Shakespeare</surname> </author> <edition>25 January 2006 – Document version 1.2</edition> </bookinfo> ... ... </book>
If the author is a company or other organisation, or a group you
want to refer to as a collective, use
corpauthor instead of
If there are several authors and you want to name them
separately, create an
corpauthor) element for each of
them and wrap them together in an
authorgroup element – all within the
Section elements are a bit different from the rest in that there are two flavors of them:
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
<sect5> range. These elements must be
properly nested, with
<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
<chapter> and we can live with that,
In early versions of this guide, the
was recommended for presentational reasons. Due to improvements in
the stylesheets, this is no longer an issue. Pick whichever you
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
The following example gives you an idea of how to structure your document:
<?xml version="1.0" encoding="UTF-8"?> <book id="usersguide"> <bookinfo> <title>Firebird Users Guide</title> <author> <firstname>William</firstname> <surname>Shakespeare</surname> </author> <edition>25 January 2006 – Document version 1.2</edition> </bookinfo> <chapter id="usersguide-intro"> <title>Introduction</title> <para>Hello! This is the introductory text to the Firebird Users Guide.</para> </chapter> <chapter id="usersguide-download-install"> <title>Downloading and installing Firebird</title> <para>In this chapter we'll demonstrate how to download and install Firebird.</para> <section id="usersguide-download"> <title>Downloading Firebird</title> <para>To download Firebird from the Internet, first go to the following URL: etc. etc. etc.</para> ...more paragraphs, possibly subsections... </section> <section id="usersguide-install"> <title>Installing Firebird</title> <para>Installing Firebird on your system goes like this: etc. etc.</para> ...more paragraphs, possibly subsections... </section> </chapter> ...more chapters... <appendix id="usersguide-dochist"> <title>Document history</title> ...to be discussed later! <appendix id="usersguide-license"> <title>License notice</title> ...to be discussed later! </book>
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,
sections can start directly with one or
para elements. But once
you include sections in a chapter, or subsections in a section,
you can't add any more
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
If you use an XML editor, chances are that you rarely have
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.
Skip the rest of the elements subsections if you already know everything about DocBook elements.
DocBook offers various list elements, of which the following are used frequently:
itemizedlist is used
to enumerate items whose order is not (very) important:
<itemizedlist spacing="compact"> <listitem><para>Oranges are juicy</para></listitem> <listitem><para>Apples are supposed to be healthy</para></listitem> <listitem><para>Most people find lemons way too sour</para> </listitem> </itemizedlist>
The items in the list are generally marked with a bullet in the rendered output docs:
Oranges are juicy
Apples are supposed to be healthy
Most people find lemons way too sour
If you leave out the
spacing attribute, it will default to
normal, which means that vertical whitespace
(usually one line's height) will be inserted between the
you want to stress the order of the entries:
<orderedlist spacing="compact" numeration="loweralpha"> <listitem><para>Sumerians 3300 BC – 1900 BC</para></listitem> <listitem><para>Assyrian Empire 1350 BC – 612 BC</para></listitem> <listitem><para>Persian Empire 6th century BC – 330 BC</para> </listitem> </orderedlist>
By default, arabic numerals (1, 2, 3, ...) will be placed
before the items, but you can change this with the
numeration attribute. Output:
Sumerians 3300 BC – 1900 BC
Assyrian Empire 1350 BC – 612 BC
Persian Empire 6th century BC – 330 BC
procedure is often
rendered like an
but the semantics are different: a procedure denotes a sequence of
steps to be performed in a given
<procedure> <step><para>Pick the lock</para></step> <step><para>Rob the house</para></step> <step><para>Get arrested</para></step> </orderedlist>
Here's how the above example is rendered:
Pick the lock
Rob the house
step you can
which in turn contains more
variablelist is made up
varlistentrys, each of which
term followed by a
<variablelist> <varlistentry> <term>Tag</term> <listitem> <para>A piece of text enclosed in angle brackets</para> </listitem> </varlistentry> <varlistentry> <term>Element</term> <listitem> <para>A start tag, a matching end tag, and everything in between</para> </listitem> </varlistentry> <varlistentry> <term>Content of an element</term> <listitem> <para>Everything between the matching tags</para> </listitem> </varlistentry> </variablelist>
The list you are reading right now, enumerating the
different types of lists, is a
variablelist with the element names
orderedlist, etc.) as terms. The next
section – Links – also consists of one
introductory sentence followed by a
You can create hyperlinks to targets in your own document, in another document in the set, or on the Internet.
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
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
Click here to jump to the introduction.
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
article; if the target lies outside
the current document, use a
ulink instead (see below).
ulink to link to an
Internet resource. The
attribute is mandatory:
Click <ulink url="http://docbook.org/tdg/en/">this link</ulink> to read The Definitive Guide on DocBook.
The words “
this link” will
rendered as a hyperlink to
http://docbook.org/tdg/en/, like this:
Click this link to read The Definitive Guide on DocBook.
You can make an email link with a
ulink, but it's easier to use the
Send mail to <email>email@example.com</email> to subscribe.
results in the following output:
Send mail to
If you want the hot text to be different from the email
address itself, use a
If you include links to email addresses – whether 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 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.
If you include code fragments in your doc, put them in a
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.
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 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:
<screen> D:\Firebird\manual_incl_howto\src\build>build ugh java version "1.4.2_01" Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.2_01-b06) Java HotSpot(TM) Client VM (build 1.4.2_01-b06, mixed mode) Buildfile: build.xml BUILD FAILED Target `ugh' does not exist in this project. </screen>
And this is how it's rendered:
D:\Firebird\manual_incl_howto\src\build>build ugh java version "1.4.2_01" Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.2_01-b06) Java HotSpot(TM) Client VM (build 1.4.2_01-b06, mixed mode) Buildfile: build.xml BUILD FAILED Target `ugh' does not exist in this project.
programlisting, keeps your layout
intact, but it usually doesn't change the font – unless you set
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.
<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>
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 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
para's, lists, etc.
Here's an example of an
<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:
If you want an example without a mandatory title, use an
examples are also left out of the examples index.
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.
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
tbody elements. Each of these has one or more
rows, which in turn have as many
entrys (cells) as you have specified
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.
<table id="docwritehowto–table–dboftheyear"> <title>LinuxQuestions.org poll: Database of the year 2003</title> <tgroup cols="3"> <colspec align="left" colname="col–dbname" colwidth="2*"/> <colspec align="right" colname="col–votes" colwidth="1*"/> <colspec align="right" colname="col–perc" colwidth="1*"/> <thead> <row> <entry align="center">Database</entry> <entry align="center">Votes</entry> <entry align="center">Percentage</entry> </row> </thead> <tfoot> <row> <entry>Total</entry> <entry>1111</entry> <entry>99.99</entry> </row> </tfoot> <tbody> <row> <entry>MySQL</entry> <entry>405</entry> <entry>36.45</entry> </row> <row> <entry>Firebird</entry> <entry>403</entry> <entry>36.27</entry> </row> ... 5 more rows not shown here .... </tbody> </tgroup> </table>
And here's the resulting table:
Table 2. LinuxQuestions.org poll: Database of the year 2003
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
informaltable within an
entry, or an
entrytbl instead of an
Tables have many more features than shown here, but we'll leave those for you to explore.
DocBook versions 4.3 and up also allow you to fill a table the
HTML way, with
trs 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
An HTML table can't have
tgroups; you put the
trs either directly in the table or in
tbody elements which are direct children of
the table. Also, it has a
instead of a
informaltable has neither caption nor
Here is the source of an HTML table:
<table bgcolor="blue" border="1"> <caption align="bottom">An HTML-style table</caption> <tr bgcolor="#FFE080"> <th>First column</th> <th bgcolor="#FFFF00">Second column</th> </tr> <tr align="center"> <td bgcolor="orange" colspan="2">Table cell spanning two columns</td> </tr> <tr> <td bgcolor="#00FFC0">Yes, here I am</td> <td align="right" bgcolor="#E0E0E0" rowspan="2" valign="bottom">And there I go!</td> </tr> <tr> <td bgcolor="#FFA0FF">Another row...</td> </tr> </table>
And here's the result:
|First column||Second column|
|Table cell spanning two columns|
|Yes, here I am||And there I go!|
Not all HTML table elements and attributes are supported by our
stylesheets. For instance, properties specified in
colgroup elements won't be picked up.
Specify them in the
th elements instead – or extend the
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.
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
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
Insert a processing instruction at the beginning of the table:
<table frame="all" id="ufb-about-tbl-features"> <?dbfo keep-together='auto'?> <title>Summary of features</title>
In XMLMind, this is done as follows:
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.
keep-together='auto' on that
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
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
Make sure that the element fits on one page before using
To include an image, use a
mediaobject containing an
imageobject containing an
<mediaobject> <imageobject> <imagedata align="center" fileref="images/services.png" format="PNG"/> </imageobject> </mediaobject>
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
always be of the form
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!
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.
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
and after that in
if you use the original image, there's no need to waste CVS space by
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.
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:
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:
If you insert a
<warning> element in your text, don't start
it with the word
warning, because these
words are usually automatically generated by the rendering
You may have noticed that the words
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
If you want a paragraph header or title without creating a subsection, there are a few possibilities.
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.
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)
formalpara is a
paragraph with a title. Our stylesheets render the title as a
<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.
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
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
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 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
application are both used for executable
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&</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
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 !
The use of
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>.
Output: The COUNTRY table has two fields: COUNTRY and CURRENCY.
These three speak for themselves, I trust.
The <function>log</function> function takes parameters <parameter>a</parameter> and <parameter>b</parameter>.
function takes parameters
prompt is used for a
string inciting the user to enter some text;
userinput refers to text entered by the
user (not necessarily at a prompt!);
computeroutput is text displayed by the
Type <userinput>guest</userinput> at the <prompt>login:</prompt> prompt and the server will greet you with a <computeroutput>Welcome, guest user</computeroutput>.
guest at the
and the server will greet you with a
The text on a keyboard key, or its common name:
Hit the <keycap>Del</keycap> key to erase the message, or <keycap>SPACE</keycap> to move on.
Output: Hit the Del key to erase the message, or SPACE to move on.
This element is used extensively throughout this guide: it marks SGML and XML tags, elements, attributes, entities etc.:
If it concerns a directory, set the <sgmltag class="attribute">class</sgmltag> attribute of the <sgmltag class="element">filename</sgmltag> element to <sgmltag class="attvalue">directory</sgmltag>.
Output: If it concerns a directory, set
class attribute of the
filename element to
Other possible values for
genentity (for an entity).
emphasis to stress
words in general,
book titles etc., and
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 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
<para>An <quote lang="en">English quote</quote> and a <quote lang="fr">French quote</quote>.</para>
Output: An “English quote” and a « French quote ».
Please note that you shouldn't use the
lang attribute on
quotes in your own docs. Your root
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
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
At all costs avoid using the word <literal>humongous</literal> in your documentation.
Output: At all costs avoid using the
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.
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
literal and an
application may have the exact same
typography; the same goes for
So what's the point of all these different tags? Why not use just
a few, like
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,
literal, the semantics would be lost.
Remember that DocBook XML is all about structure and semantics.
citetitle may look
the same as
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.
|Firebird Documentation Index → Firebird Docwriting Guide → Elements we use frequently|