Blender Documentation: Last modified July 30 2003 s68
<<< Previous | About the Blender Documentation Project | Next >>>

# Learning DocBook/XML

Learning DocBook can seem a little scary at first, just like learning Blender. We're not going to go into too much detail about DocBook. There is an excellent on-line reference entitled DocBook: The Definitive Guide , available on-line. It can be found it at http://docbook.org/tdg/en/html/docbook.html. The purpose of this section is to teach just enough about DocBook to make the reader dangerous.

One thing to be aware of: there are actually two versions of DocBook that are in widespread use. One is for DocBook using SGML. The other is for DocBook using XML. While there are only a few differences between them, we will confine our discussion to the XML version of DocBook.

## 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.

### Document Structure

As mentioned above there is a basic structure to DocBook documents. The tags that give structure to a DocBook document are outlined below:

`<set>`

  The top level of the DocBook documentation. A set of books. It is unlikely that you will ever have to work with a `<set>` tag, it is included here for general reference purposes.

<book>

  This is exactly the same as a physical book. It is a volume that may be distributed on its own or as part of a set. In the Blender Manual documentation, the `<book>` tag is only used in the top-level file `BlenderManual.xml`.

`<chapter>`

  Exactly what the name suggests - a chapter in a book. This can be a separate file, or part of the overall book file. Each chapter in the Blender documentation is generally a separate file.

`<section>`

  This is a part of a chapter. By nesting `<section>` tags it is possible to create subsections and sub-subsections. Generally, when writing a file that will be part of a larger file, it is of the section variety.

`<para>`

  This is a paragraph. As a rule of thumb, nearly all text entered should be between `<para>` tags. When there are two different paragraphs, they must be enclosed in two separate sets of paragraph tags. Paragraph tags, like paragraphs, cannot be nested.

### 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.

### Lists

There are a total of seven types of lists that you can put in DocBook documents. We will only discuss 3 of them. They are:

Itemized List

  A plain old bulleted list. Here is an example of an itemized list.

      <orderedlist>
        <listitem>
          <para>
            Download the latest version of Blender.
          </para>
        </listitem>
        <listitem>
          <para>
            Study the Blender Manual.
          </para>
        </listitem>
        <listitem>
          <para>
            Create an awesome gallery.
          </para>
        </listitem>
        <listitem>
          <para>
            Write my Blender Screenplay.
          </para>
        </listitem>
      </orderedlist>

  Here is what it looks like after it has been formatted:

  - Download the latest version of Blender.

  - Study the Blender Manual.

  - Create an awesome gallery.

  - Write my Blender Screenplay.

Ordered List

  A numbered list. Here is an example:

      <orderedlist>
        <listitem>
          <para>Start Blender</para>
        </listitem>
        <listitem>
          <para>
            Type <userinput>SPACEBAR</userinput> to open the Add Menu.
          </para>
        </listitem>
        <listitem>
          <para>
            Next, click with the LMB (left mouse button) on the menu-entry <quote>MESH</quote>. The menu changes and will show the
            different possibilities for adding mesh-objects.
          </para>
        </listitem>
        <listitem>
          <para>
            Select <quote>Plane</quote>, the Toolbox disappears and a Plane appears at the 3D cursor. We are currently in the EditMode
            where we can edit the shape of the mesh itself.
          </para>
        </listitem>
      </orderedlist>

  Here is what the example above looks like when formatted.

  1. Start Blender

  2. Type `SPACEBAR` to open the Add Menu.

  3. Next, click with the LMB (left mouse button) on the menu-entry "MESH". The menu changes and will show the different possibilities for adding mesh-objects.

  4. Select "Plane", the Toolbox disappears and a Plane appears at the 3D cursor. We are currently in the EditMode where we can edit the shape of the mesh itself.

Variable List

  This is a list that appears as a series of terms and their definition. It is similar to the style that a glossary is in, and is the style of this very list. Here is an example:

      <variablelist>
        <varlistentry>
          <term><sgmltag>&lt;quote&gt;</sgmltag></term>
          <listitem>
            <para>
              This puts the text between the quote tags in
              quotes. The same effect can be derived by putting
              double quotes (") around a word in a text mode.
              However, using tags is more proper and will ensure that
              the quotes are properly represented no matter what
              country your document is published in.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><sgmltag>&lt;emphasis&gt;</sgmltag></term>
          <listitem>
            <para>
              Emphasizes the text through the use of italics or
              boldface type.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><sgmltag>&lt;footnote&gt;</sgmltag></term>
          <listitem>
            <para>
              Inserts a footnote<footnote>
              <para>Which looks something like this.</para>
              </footnote> at the point in the text where the opening
              tag is and then the actual text of the footnote (which
              is contained between the footnote tags, and generally
              between para tags) at the bottom of the page.
            </para>
          </listitem>
        </varlistentry>
      </variablelist>

As I mentioned above, there are four other types of list that I have not mentioned here. These are `CalloutList`, `GlossList`, `SegmentedList` and `SimpleList`. For more details on this list go to the DocBook documentation.

### Formatting

There are a few other stylistic tags that are helpful. They are listed below in no particular order.

`<quote>`

  This puts the text between the quote tags in quotes. The same effect can be derived by putting double quotes (") around a word in a free text. However, using tags ensures that the quotes are properly represented no matter what country your document is published in.

`<emphasis>`

  Emphasizes the text through the use of italics or boldface type.

`<email>`

  Inserts the email address between the tags into the document, hyper-text linked if possible.

`<userinput>`

  Gives a consistent form to the text that a user should enter into a computer program.

`<computeroutput>`

  Gives a consistent form to the text that a computer application might output.

`<note>`

  Separates the text in note from the rest of the document and calls attention to it.

`<Warning>`

  Much like a note, but calls greater attention to the text of the warning.

`<Tip>`

  Like a warning and a Note, but calls attention to the text in a different way. Which one of these tags you choose should depend on the actual meaning of the text you want to enclose with these tags. If it is a note, use note; a tip, use tip, etc. `<caution>` and `<important>` also fall into this class of tags.

`<filename>`

  This gives a consistent formatting to filenames and directories. A filename should just be enclosed in `<filename>` tags, whereas a directory should have an opening filename tag that looks like this: `<filename class="directory">`.

`<literal>`

  Presents the content of this tag as a literal value. Generally used on numbers rather than text you want to appear literally on the screen.

An additional useful bit of formatting is the ability to display literal text without any sort of interpretation of your markup. There are several ways to do this, the one I have chosen looks like this:

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

Here is what the above example looks like once formatted.

<<< Previous | Home | Next >>>
Getting your system ready for DocBook/XML (-) | Up | The Blender Documentation Project styleguide