Learning DocBook/XML

A Basic DocBook File

We will begin with an example DocBook document and explain what each piece of the document does. For the rest of this discussion refer to A Docbook example, BlenderManual.xml below.

<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN" "docbook-xml-4.2/docbookx.dtd"
[

<!ENTITY bver "2.27">

<!ENTITY chapter_introduction   SYSTEM "chapters/introduction/chapter_introduction.xml">
<!ENTITY chapter_installation   SYSTEM "chapters/introduction/chapter_installation.xml">
<!ENTITY chapter_interface      SYSTEM "chapters/interface/chapter_interface.xml">

<!--
Everything between the line above and the line below is treated as a comment.
-->

<!ENTITY FIXME '<inlinegraphic format="PNG" fileref="gfx/general/undercon.png"/>'>
<!ENTITY NEEDHELP '<inlinegraphic format="PNG" fileref="gfx/general/undercon.png"/>'>

]>

<book>
  <!-- PART 1 -Introduction -->
  <part>
    &chapter_introduction;
    &chapter_installation;
    &chapter_interface;
  </part>
</book>

The XML Declaration

At the top of the file is the following line:

<?xml version="1.0"?>

This is known as the XML declaration. All XML documents should begin with an XML declaration.

The DOCTYPE Declaration

The second line is the Document Type Declaration.

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN" "docbook-xml-4.2/docbookx.dtd"
[

This tells the XML interpreter several things. The second word book tells the interpreter what type of document this file is. In this case it is a book, which is a concept from the DocBook DTD.

The end of this line contains information about the DTD we are using. The string has a bunch of information about the DTD. Most of the information doesn't matter to you, just know that we currently use DocBook version 4.2.

The DocBook Hierachy

The basic hierarchy that we use for DocBook looks something like this:

<set>                // A Set of Books
  <book>             // A Book
    <part>           // A division of a Book. Each division can contain a number of elements, such as chapters.
      <chapter>      // A chapter of a book, can also be its own file
        <section>    // A section of a chapter, chapter 1 section 1 will be denoted by 1.1 or something like that
          <section>  // sections can be nested creating subsections and sub-subsections, etc.
            <para>   // a paragraph, the place text actually resides. Paragraphs can be at any level below set, 
		     // text can also reside in lists, glossentries, etc.

Entities

The lines after the Document Type declaration define "Entities" for the DocBook document. Entities are basically handy shortcuts.

<!ENTITY bver "2.27">

<!ENTITY chapter_introduction   SYSTEM "chapters/introduction/chapter_introduction.xml">
<!ENTITY chapter_installation   SYSTEM "chapters/introduction/chapter_installation.xml">

The first line declares an entity called bver, which is just the text "2.27". In order to to put that piece of text anywhere in the document all you have to do is write &bver; For example here: 2.28.

Below the general entities are SYSTEM entities. These refer to system resources. In this case they are used to locate the different files that will come together to form the book. The first entity, chapter_introduction contains the introductory chapter of the book. The content of this chapter is stored in the file chapter_introduction.xml which is located in the chapters/introduction subdirectory. Notice that the path supplied is a local path, that is chapter_introduction.xml and chapter_installation.xml must be in the same directory in order for the DocBook interpreter to work properly.

The Actual Document

After all the entities are declared, the book can be put together. It begins with a <book> tag. A book is required to have a title, which is surrounded by <title> tags. When this document is interpreted, the interpreter substitutes the contents of the file referred to by <chapter_introduction>, chapters/introduction/chapter_introduction.xml, into the main XML file, BlenderManual.xml. This is followed by the contents of chapters/introduction/chapter_installation.xml.

Each tag must be closed with a tag of the same name except that there is a forward slash between the open bracket and the name of the tag. Toward the end of the BlenderManual.xml file the book tag is closed off with </book>. Since the first tag that was opened is now closed, the XML document is finished.

Common Tags

This section discusses some common tags and explains how they are generally used. There are a lot of tags available (300+) which means that most documents will use only a small subset of all the tags. Detailed tag explanations can be found at http://docbook.org/tdg/en/html/docbook.html. Some of the tags are obviously designed for very specific purposes such as <glosssee> which refers one glossary entry to another glossary entry. Others are less specific, such that several options will achieve basically the same stylistic interpretation.

A good example of this are the tags <literal>, <userinput>, and <computeroutput>. Under most circumstances these are interpreted in basically the same way.

However, it is important to realize that this is simply how the interpreter chooses to format these tags. Another interpreter, or another style sheet for the same interpreter, could display these tags in very different ways. Therefore, it is important to use the tag that most closely matches your meaning. Use <userinput> when specifying something a user must input, <computeroutput> when specifying the output of a machine, and <literal> when expressing a literal value.

When listing tags below, specific examples of the contexts in which they are useful will be provided. In reality there aren't too many tags which need to be used. One can simply tell a reader that a specific word is a filename without putting it in a <filename> tag. However, the richness of the document increases when more tags are supplied and it is easier to tell very specifically what something is if a section or piece of text is clearly identified.

Linking

One of the features of DocBook is the ability to create links between sections, text, whatever at will. This means that documentation can be produced with very little replication. If the reader is to be able to easily reference a section as background material, a link to it can be provided. If the reader already knows the background material they can chose not to follow the link.

Setting up a Target

In order to create a link in a document two things are needed. The first is an instruction for DocBook to create a link from a piece of text. The second is a target for the link. To create a target, a tag must have an id. For example, to link to a specific section, change the <section> tag to <section id="section.link"> where "section.link" is just an arbitrary identifier.

The identifier that is used as a target should be text with period separators. If it is a section it is probably best to use something of the form "something.section", etc. Be sure to follow the recommendations of the Blender Documentation Board for the Section called Cross references creating section names if creating documents for the Blender Manual.

Links

Just as there are multiple ways to put targets into your document, there are multiple ways of linking to those targets (as there are multiple ways to do anything in DocBook). Here are the most useful link tags:

<link>

Just a plain old link. In order to link to a specific section the syntax would look something like <link linkend="specific.section">clickable text </link>. This will allow a user to click on "clickable text" which will take them to the specific section you have identified as "specific section".

<ulink>

This tag allows you to link to a Uniform Resource Identifier (URI) outside of the document itself. Generally this will be a Uniform Resource Locator (URL) where a reader can get more information about a subject in your document. The usage looks like this: <ulink url="http://www.blender.com"> Blender.org</ulink>. If you need to link to a local file, follow this convention <ulink url="file://localhost/path/to/filename">Some text here</ulink> to be sure that it can be viewed in most browsers.

<xref>

Xref is much like link except that you can't put any text between the opening and closing tags. You can specify what text will be clickable in two ways. The first is to supply whatever you are linking to with an XRefLabel. Thus, the example of a section target above would become <section id="section.link" xreflabel="label"> . The other way can be used when dealing with a tag that requires you to have a <title> such as chapter. Assume that we have a chapter defined as follows:

<chapterid="specific.chapter"> <title id="specific.chapter.title">Title</title> </chapter>

In order to reference this chapter with an xref you would simply write <xref linkend="specific.chapter" endterm="specific.chapter.title"/>. The word "Title" would appear as clickable in the midst of your text. The same technique can be used with <link>.

Please notice the trailing slash at the end of the "xref" example in the preceding paragraph. Failure to include this slash can cause hours of pain when trying to debug parsing errors in your documents. The same is true of the "anchor" tag.

<screen>
  <![CDATA[
   <chapter id="specific.chapter">
     <title id="specific.chapter.title">Title</title>
   </chapter>
  ]]>
</screen>