<paragraph>
<loud>'No!'</loud> she screamed. <scary>But the bloody hand
<italics>kept on creeping</italics> towards her.</scary>
<picture file="bloody_hand.png"/>
</paragraph>

In the example given above, the words and phrases enclosed in angle brackets are the markup tags. <italics> is a start tag, </italics> is an end tag, and <picture file="bloody_hand.png"/> is a standalone tag, officially termed empty-element tag. XML tags are always formatted like this:

Still referring to our example, the words paragraph, loud, scary, italics and picture are tag names. In the <picture.../> tag, file="bloody_hand.png" is called an attribute, with file the attribute name and bloody_hand.png the attribute value. Attribute values must always be quoted; both single and double quotes are allowed.

XML allows you to define any tags you like, as long as you build them correctly. So <thistag>, <thattag>, and <this_is_not_a_tag/> are all well-formed XML tags. (XML that follows the standard is called well-formed; the term valid is only used for specifically defined implementations – DocBook XML, for instance.)

Clearly the tags themselves are not meant to appear in the final document (that is, the document as it is presented to the readers). Rather, they contain instructions that affect its appearance. XML, when used for writing documentation, is a typical source format, intended to be processed by software to produce nicely formatted output documents. This processing is usually called rendering.

Some tags are unmistakably makeup instructions:

<italics>kept on creeping</italics>

means of course that the words kept on creeping must be displayed or printed in italics. However,

<loud>'No!'</loud>

is a little less obvious. Should the word No! appear in boldface? Or underlined? Or again in italics? Or maybe this text is going to be read out aloud by a speech synthesizer, and the <loud> tag instructs it to raise its voice? All these things are possible, and what's more: often a single XML source document is converted into several different output formats – say, a PDF document, an HTML web page, and a sound file. This is called multichannel publishing. With multichannel publishing, <loud> may be translated to boldface for the PDF document; to a bold, red-colored font for the web page; and to a 50% volume increase for the synthesizer.

Looking at the other tags, <picture.../> is obviously an instruction to insert the image bloody_hand.png into the document, and <scary>, well... this is even less clear then <loud>. Maybe the phrase between the <scary> tags has to drip with blood. Maybe frightening music must be played here. It all depends on the people who defined the tags, and the software they use to do the rendering.

The <paragraph> tag, finally, is a structural tag. It tells us something about the place that the lines have within the document's internal hierarchy. In the final document, paragraphs may or may not be separated by empty lines. Again, that depends on the rendering software and possibly also on user-configurable options. Other structural tags one might think of are e.g. <chapter>, <section>, and <subdocument>.

Because the character “<” has a special meaning as the start of a tag, you can't include it directly as a literal value. Instead, if you want your readers to see an opening angle bracket, you type this:

That's an ampersand, followed by the letters l and t (for less than), followed by a semicolon. You can also use > (greater than) for the closing angle bracket “>”, but you don't have to.

XML has lots of codes like this; they are called entities. Some represent characters, like < and ä (lower a with umlaut) and some serve totally different purposes. But they all start with an ampersand and end with a semicolon.

But wait a minute... if an ampersand marks the start of an entity, how do you include a literal ampersand in your text? Well, there's an entity for that too:

So this line of XML:

Kernigan & Ritchie chose '<' as the less-than operator for C.

will wind up in the final documents as:

Kernigan & Ritchie chose '<' as the less-than operator for C.

And here's some good news: if you use a dedicated XML editor to author your document, you can probably just type “<” and “&” anywhere you want to use them as literals. The editor will make sure that they end up as < and & in the XML as it is saved to disk. You'll find pointers to some XML/DocBook editors later in this guide.

There's one more important XML concept you need to know about: the element. An element is the combination of a start tag, a matching end tag, and everything in between. This “everything in between” is called the element's content, and it may include other elements. Elements are named after their tags, so we can talk about paragraph elements, italics elements etc.

This is an element:

<loud>'No!'</loud>

This is also an element:

<paragraph>This is an element containing <bold>another</bold> 
  element!</paragraph>

Empty-element tags constitute an element all by themselves. These elements can have no content of course, because they don't have a pair of tags:

<picture file="bloody_hand.png"/>

I'm stressing the element concept here because most documentation tends to speak of “chapter elements”, “title elements” etc. rather than “chapter tags” and “title tags”. The terms are often used interchangeably, but there are cases where it's important to know the difference.

Good – that's about all you need to know about XML. By now you should have a general idea of what an XML text looks like, what tags and elements are, and what they are for. As said earlier, the picture is oversimplified but it's good enough for our purposes.

It should also be understood that just writing away in plain, self-invented XML is pretty pointless unless you have processing software that understands your tags. How else are you going to turn your XML source into a nicely formatted, presentable document?

Fortunately, we don't have to worry about developing our own element definitions and conversion software. There are a number of formalized XML types available, each defining a set of tags and, equally important, a set of rules on how to use them. DocBook XML is one of those types.

Important characteristics of DocBook – as opposed to “general” XML – are:

DocBook has a lot of advantages for anybody writing technical documentation. These are the most important ones for us:

Admittedly, none of these benefits is unique to DocBook. But DocBook has them all, and it's widely supported. That makes it the perfect choice for our Firebird documentation.

Here are some links in case you want to find out more about DocBook:

If you know of some other great online resource, please let use know by posting a message to the firebird-docs list.