Docbook: an XML vocabulary for writing documentation, manuals and technical books

article*

Front Matter Elements*

preface, toc, partintro, ...

Back Matter Elements*

appendix, glossary, index,

Out of Flow Elements

<article xmlns='http://docbook.org/ns/docbook'>
<title>Example sidebar</title>
<section>
  <title>An Example Section</title>
  <para>Some narrative text.</para>
  <sidebar>
    <title>A Sidebar</title>
    <para>Sidebar content.</para>
  </sidebar>
  <para>The continuing flow of the narrative text, as if the
  sidebar was not present.</para>
</section>
</article>

<article xmlns='http://docbook.org/ns/docbook'>
<title>Example of an annotation</title>
 <annotation xml:id="note-parts-list">
  <para>This list is not comprehensive.</para>
</annotation>
  <para annotations="note-parts-list">An automobile
  contains an engine, wheels, doors, and windows.</para>

</article>

Numbered and unnumbered lists

They are either an orderedlist or an itemizedlist. Both are made up of listitem's.

Lists of Definitions

A variablelist is a list of terms and definitions or descriptions.

While glossarys are usually limited to component or section boundaries, appearing at the end of a book or chapter, for instance, glosslists can appear anywhere that the other list types are allowed.

Using a glosslist in running text, instead of a variablelist, for example, maintains the semantic distinction of a glossary. This distinction may be necessary if you want to automatically point to the members of the list with glossterms in the body of the text.

<glosslist>
<glossentry><glossterm>C</glossterm>
<glossdef>
<para>A programming language invented by K & R. </para>
</glossdef>
</glossentry>
<glossentry><glossterm>Pascal</glossterm>
<glossdef>
<para>A programming language invented by Niklaus Wirth.
</para>
</glossdef>
</glossentry>
</glosslist>

Would be presented as:

C

A programming language invented by K&R.

Pascal

A programming language invented by Niklaus Wirth.

'example's in DocBook

This is an 'example':

'figure's in DocBook

This is an example SVG image:

This is the code:

<mediaobject>
              <imageobject>
                <imagedata>
                  <svg xmlns="http://www.w3.org/2000/svg"
                       width="100" height="100" version="1.1">
                    <rect x="20" y="20" width="80" height="80" style="fill:blue; stroke:green; stroke-width: 2; fill-opacity: 0.5; stroke-opacity: 0.9"/>
                  </svg>
                </imagedata>
              </imageobject>
            </mediaobject>

'table's in DocBook

DocBook supports CALS tables (defined with tgroup, colspec, spanspec, thead, tfoot, tbody, row, entry, entrytbl, and caption) and HTML tables (defined with col, colgroup, thead, tfoot, tbody, tr, td, and caption). Both describe tables geometrically using rows, columns, and cells.

CALS tables

Example table

Sample CALS Table

HTML tables

Sample HTML Table

Cross references within a document

DocBook 4 employs the built-in feature of XML for cross referencing within a document, in which attributes are used to identify starting and ending points for cross references. In an XML DTD, an attribute can be assigned an attribute type of ID. That type of attribute is used to label an element as a potential target (end point) of a cross reference. The attribute name does not have be ID, it just needs to be declared as that type. In DocBook 4, the name of the attribute assigned this purpose just happens to be named id as well. In the DocBook DTD, almost every element can have an id attribute, with attribute type ID. That means any element in your document could be the target of a cross reference.

In DocBook 5, you use xml:id instead of id. The xml:id attribute is predefined to have attribute type ID, whether or not a schema is available to confirm it.

According to the XML standard, every value of an attribute with type ID must be unique. In DocBook, this means every instance of an id (DocBook 4) or xml:id (DocBook 5) attribute in a document must be unique within that document. When you validate your document, the validator will tell you if you have any duplicate id attributes.

Other attributes can have a type of IDREF, which is used to point to an ID on another element to form a cross reference. There are a handful of elements in the DocBook DTD that have attributes of type IDREF, of various names. There are two main elements that are used to create cross references to targets within the same document:

xref

An automatic cross reference that generates the text of the reference. For that purpose, it is an empty element that takes no content of its own. The stylesheets control what output is generated. The generated text can be the target element's titleabbrev (if it has one) or title, number label (if it has one), or both.

link

A cross reference where you supply the text of the reference as the content of the link element. Therefore it must not be an empty element.

Both of these elements require a linkend attribute whose value must match some id or xml:id value in the document. Here are two examples in DocBook 4:

Internal Cross References Example

<chapter  id="intro">
  <title>Introduction</title>
  <para>Welcome to our new product. One of its
  new features is a <link  linkend="WidgetIntro">widget</link>.
  Other new features include ... </para>
</chapter>

<chapter  id="WidgetIntro">
  <title>Introducing the Widget</title>
  <para>Widgets are just one of our new features.
  For a complete list of new features, see <xref  linkend="intro"/>.
  </para>
</chapter>

...

Here is some guidance for using these cross reference elements:

Use xref when you want to reference another element's title or number. It will automatically get the current information so you do not have to maintain such references.

Use link when you want to create a less formal reference that does not include the title or number. You can use whatever words you want.

When adding an id or xml:id attribute, put it on the element itself, not the title. The stylesheets know how to find the title for each element being referenced.

Not all elements are appropriate as targets of an xref, because they do not have a title or number. For example, you may want to cross reference to a para, but you wouldn't want the whole paragraph to be copied as the reference text. See the next section for options you can add to use xref anyway.

Universal linking in DocBook 5

In DocBook 4, only specialized elements are used for creating links within and between documents. In DocBook 4, you can use xref or link with linkend attributes to form links within a DocBook document, you can use olink to form links between DocBook documents, and you can use ulink to form an arbitrary URL link.

In DocBook 5, almost all elements can be used as the basis for a link. That's because almost all elements have a set of attributes that are defined in the XLink namespace, such as xlink:href. For example, you can turn a command element into a link that targets the reference page for the command.

<para>Use the
<command xlink:href="#ref-preview">Preview</command>
command to generate a preview.</para>

The XML Linking Language (XLink) has been a W3C standard since 2001. That standard says that any XML element can become the source or target of a link if it has the universal XLink attributes on it. These attributes are in their own namespace named http://www.w3.org/1999/xlink. Because these attributes are in their own namespace, they do not interfere with any native attributes declared for an element.

An xlink:href attribute value can have several different forms:

• An attribute such as xlink:href="#intro" refers to an xml:id attribute that exists in the current document. This is similar to the DocBook 4 link and xref elements. The link and xref elements were retained in DocBook 5.
• An attribute such as xlink:href="http://docbook.org" refers to an arbitrary URL. This is similar to the DocBook 4 ulink element, which was removed in DocBook 5. Instead of ulink, use a link element with a URL in its xlink:href attribute.
• An olink-style link from any element can be formed using two attributes. If there is a xlink:role="http://docbook.org/xlink/role/olink" attribute present, then a link attribute of the form xlink:href="targetdoc#targetptr" is interpreted as the two parts of an olink. The olink element itself is retained in DocBook 5. See Chapter 24, Olinking between documents to learn more about DocBook olinks.

At the same time, the familiar DocBook linking attribute linkend has also been added anywhere an XLink can be used. The linkend attribute is limited to linking to an xml:id target within the same document.

The universal linking mechanism enables you to create logical links between any two DocBook elements. However, such logical links may or may not be expressible in formatted output. For example, if you put an xlink:href on an inline element, then the text of the inline element can become clickable link text in the output. However, if you put an xlink:href attribute on a block element such as section, then it is doubtful that making all the text in the section into a clickable link will be useful. The DocBook stylesheets currently only handle xlink:href on inline elements for this reason. If you want to express linking from a block element, you will have to customize the stylesheet to do so, perhaps by putting a clickable icon in the margin.

Line annotations

You can mix lineannotation elements in with your code to explain something directly in the text. For example:

<programlisting># constructor
sub new {
    my ($file, $output) = @_; <lineannotation>Store args</lineannotation>
    my $dir = basename $file; <lineannotation>Get dir name</lineannotation>
}
</programlisting>

Line annotations in the stock stylesheet print as italic, but they inherit the monospace font family of the programlisting.

Line numbering

You can add line numbers to the listing, and then your paragraphs can refer to the line numbers. Currently line numbering is only available with the Java processors Saxon and Xalan, not xsltproc, because it is done with an extension function.

Line numbers are turned on by a linenumbering attribute on each programlisting element that needs line numbering. By default, the numbering starts at 1, but you can assign your own starting number with the optional startinglinenumber attribute. You can also continue the numbering from the most recent programlisting that had line numbering by adding a continuation="continues" attribute to the current element. The following is an example with startinglinenumber:

<programlisting linenumbering="numbered" startinglinenumber="12">

Once your lines are numbered, you can refer to the line numbers in the paragraphs. The problem with line numbers, though, is you cannot see them until the text is formatted at least once. Also, if you edit the code, the line numbers may change and you will need to adjust your number references. It is useful for stable code examples, though.

Callouts

You can use callouts to mark specific locations in a program listing and link explanatory text to the marks. In DocBook, the callout element contains the explanatory text. The mark, which is called a callout bug, is most easily placed using the co element. Those two elements can be linked to each other to allow the reader to conveniently move back and forth between them.

The callout bug is usually rendered as a white number in a black circle.

<programlisting>
#ifndef _My_Parser_h_  <co  id="condition-co"  linkends="condition" />
#define _My_Parser_h_
#include "MyFetch.h"   <co id="headerfile-co" linkends="headerfile" />
class My_Parser  <co id="classdef-co" linkends="classdef" />
{
public:
        //
        // Construction/Destruction
        //
        My_Parser();  <coref  linkend="classdef-co"/>
        virtual      ~My_Parser() = 0;
        virtual int  parse(MyFetch &amp;fetcher) = 0;
};
#endif
</programlisting>

<calloutlist>
  <callout arearefs="condition-co"  id="condition" >
    <para>Make this conditional.</para>
  </callout>
  <callout arearefs="headerfile-co" id="headerfile">
    <para>Load necessary constants.</para>
  </callout>
  <callout arearefs="classdef-co" id="classdef">
    <para>Define new class</para>
  </callout>
</calloutlist>

• Use a co element to place a callout bug in your code sample. The element is empty, with all the information in attributes.
• Give the co an id or xml:id value so the callout text can be linked directly to the callout bug location.
• Its linkend attribute value (condition) should match the id or xml:id value of its callout element. That forms a link from the callout bug to the text.
• Use a coref instead of a co when you want to create a duplicate bug number. That is, when you have more than one location in your code that needs to refer to the same callout paragraph, use a coref for any but the first location. The linkend of the coref must point to the id of the master co element. The duplicate callout icons will all hotlink to the same callout paragraph. But the icon next to the callout paragraph will link back only to the master co element.
• A calloutlist contains a set of callout elements, and formats them as a list.
• Each callout element is paired up with a co element. The numbering order is based on the co order, so you should keep the callout elements in the same order.
• The arearefs attribute value matches the id value of its co callout bug . That forms a link from the callout text to the callout bug.
• Give the callout an id value so the callout bug can link directly to its callout text.

Supported Docbook Elements

A proper subset of Docbook, namely Simple Docbook, is supported. The Simplified DocBook elements that are not supported are authorgroup, biblioxxx, entrytbl, and spanspec.

In the following table, elements that are defined for Simplified DocBook are marked with a dagger.

Links in Sdop

Attribute id is only supported for chapter and section elements and is used for making links[, but then the documentation for links is inadequate].

If an index is generated, the page numbers it contains are made into clickable links. This and the generation of clickable links from xref elements are turned off by setting xref_links parameter to no. The colour of these links is by default the same colour as the surrounding text, but it can be explicitly specified by xref_rgb, as in <?sdop xref_rgb="0,0,1"?>.

Here is a full example:

<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/css" href="docbook.css"?>

<book>
  <title>A sdop test file</title>
  <para>...</para>
  <chapter id='ch01'>
    <title>First Chapter</title>
    <para>...</para>
  </chapter>
  <chapter>
    <title>Second Chapter</title>
    <para>An xref: <xref linkend='ch01'/>...</para>
    <para>A ulink: <ulink url='circularia.t15.org'/>...</para>
  </chapter>
</book>

Links Within the (XML) Document

The link source is identified through a Docbook 5 xml:id="your_identifier" attribute in a visible element. Then you can use a plain link element with a linkend attribute:

<link linkend="you_identifier">link_text</link>

Transforming to a single HTML file

Just use the html/docbook.xsl. As this stylesheet does not name the output, use a switch as in

xsltproc  --output  myfile.html  docbook.xsl  myfile.xml

Processing part of a document

You may want to generate output for only part of large DocBook document. For example, you might need just one book from a set document, or one chapter from a book document, etc. The DocBook XSL stylesheets have a parameter that lets you output part of a document.

There are two conditions that must be met:

• The content you want to output is contained in a single element. You cannot use this feature to output an arbitrary selection of elements.
• The selected element must have an id attribute on it.

You process the document as you normally would, but you set the stylesheet parameter rootid to the id attribute value of the element you want to process. For example, if you have a book with three chapters:

<book>
  <chapter id="introduction">
    ...
  </chapter>
  <chapter id="installing">
    ..
  </chapter>
  <chapter id="administering">
    ...
  </chapter>
</book>

You can generate an HTML file for the second chapter with a command like the following:

 xsltproc --stringparam  rootid  "using" --output  chap2.html html/docbook.xsl  myfile.xml

The chap2.html output file will contain just the second chapter. The entire document is still parsed, so there will not be signficant savings of processing time and the selected content is still processed within the context of the entire document. Any cross references to other chapters will be properly formed, but the links will not actually go anywhere because the targets are not included in the output.

Transforming to multiple HTML files (chunking)

Include the line: <?xml-stylesheet type="text/xsl" href="/usr/share/xml/docbook/stylesheet/docbook-xsl/html/chunk.xsl" ?> at the top of your document and process with an XSLT processor like xsltproc. Or better still, passed the stylesheet as a parameter to the XSLT processor (xsltproc or whatever). The default behaviour chunks up to sect1 elements. If you want to chunk the first sect1 sections too, include --stringparam chunk.first.sections 1 in your command line.

If you want the output to go into a chosen subdirectory, write a processing instruction just after the opening tag of the element like <?dbhtml dir="HowToMakeABook" ?>. (On the other hand, you don't want to specify an output file name.) You can also write processing instructions to determine how files are named by writing an analogous processing instruction following the opening tag of a chunkable element, like this:

<chapter><?dbhtml filename="intro.html" ?>
  <title>Introduction</title>

This way your xml file will get transformed into its component *.html files corresponding to chapters, sections etc plus an index.html file.