|Firebird Docset → Firebird Docwriters' Docs → 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: <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.
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.
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.
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).
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.
<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 author:
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.
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.
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.
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.
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, 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.
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:
An 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 listitems.
Use an orderedlist when 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
A procedure is often rendered like an orderedlist, but the semantics are different: a procedure denotes a sequence of steps to be performed in a given order:
<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
Within a step you can include a substeps element, which in turn contains more steps.
A variablelist is made up of varlistentrys, each of which contains a term followed by a listitem:
<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 (itemizedlist, orderedlist, etc.) as terms. The next section – Links – also consists of one introductory sentence followed by a variablelist.
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 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:
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 book or article; if the target lies outside the current document, use a ulink instead (see below).
As you may have noticed, the clickable region in the PDF is sometimes offset with respect to the link text. This is a known issue in Apache FOP, and there's not much we can do about it.
Use a ulink to link to an Internet resource. The url 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 email element. This will show the email address as a clickable link in the output. This piece of XML:
Send mail to <email>[email protected]</email> to subscribe.
results in the following output:
Send mail to <[email protected]> to subscribe.
If you want the hot text to be different from the email address itself, use a ulink with a mailto: URL.
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!
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.
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.
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.
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:
<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.
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.
<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
In previous versions of this guide, you were warned not to use non-monospaced literallayout because it looked horrible in the PDF output. But this problem has since been solved, as you can see in the PDF.
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
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.
<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 table/informaltable within an entry, or an entrytbl instead of an entry.
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 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.)
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 col and colgroup elements won't be picked up. Specify them in the td/th elements instead – or extend the stylesheets!
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.
To include an image, use a mediaobject containing an imageobject containing an imagedata element:
<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 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.
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.
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:
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>.
If you want a paragraph header or title without creating a subsection, there are a few possibilities.
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.
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.
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.
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:
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&</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.
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 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>.
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>.
Output: The log function takes parameters a and b.
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 computer:
Type <userinput>guest</userinput> at the <prompt>login:</prompt> prompt and the server will greet you with a <computeroutput>Welcome, guest user</computeroutput>.
Output: Type guest at the login: prompt and the server will greet you with a Welcome, guest user.
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 the class attribute of the filename element to directory.
Other possible values for sgmltag.class are: starttag, endtag, emptytag, and genentity (for an entity).
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.
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:
<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 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.
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.
|Firebird Docset → Firebird Docwriters' Docs → Firebird Docwriting Guide → Elements we use frequently|