A short docbook primer

Writing proceedings for the SVG Open 2008 conference


Table of Contents

Why docbook?
The document structure
The article body
Structuring the article with sections
Itemized and ordered lists
Embedding Graphics
Linking to internal and external resources
Publishing code listings
Tables
Bibliography
Docbook Resources
Bibliography

At the first SVG Open conference in Zurich, 2002, we instructed paper authors to submit their papers in XHTML format. We provided a sample structure as XHTML and CSS stylesheets in order to get a similar structure and look for all papers. We asked authors to validate their papers at the W3C XHTML validator prior to submission. Unfortunately, only a minority of the authors delivered well-formed and valid XHTML files. Even worse, some authors used Microsoft Word or similar tools to generate their XHTML files. It is well-known that MS Word (esp. older versions) creates non-valid and suboptimal XHTML code. The organizers of the first SVG Open conference spent many hours to correct the most obvious and severe XHTML errors.

As a consequence, the organizers of the second edition of the conference (2003) requested gcapaper, a subset of the docbook format. In recent years, the standard docbook (article profile) was requested. This has the advantage that authors can use standard XML editors or specialized docbook editors, while the conference organizers get a more structured, well-formed and valid result files. The organizers provide XSLT files for conversion to the XHTML format. Alternatively, the same source file could be used for conversion to other formats, such as the PDF format. Docbook is widely used in technical documentation, as a documentation source for many open source projects, and in the publishing industry. Finally, docbook plays well with SVG content (both inline and external) and other multimedia objects (such as audio and video).

For the purpose of conference proceedings, the docbook "article" type is the logical choice. Following is the basic structure of an article, consisting of the XML header, the root element (<article/>), containing the <info/> section and the document itself (the sections):

                
<?xml version="1.0" encoding="UTF-8"?>
<?oxygen RNGSchema="http://www.docbook.org/xml/5.0/rng/docbook.rng" type="xml"?>
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
    <info>
        <title>A short docbook primer</title>
        <subtitle>Writing proceedings for the SVG Open 2008 conference</subtitle>
        <keywordset>
            <keyword>paper formats</keyword>
            <keyword>conference proceedings</keyword>
        </keywordset>
        <authorgroup>
            <author>
                <personname>
                    <firstname>Mark</firstname>
                    <surname>Foster</surname>
                </personname>
                <email>mark.foster@nowhere.com</email>
                <personblurb><para>Some information about the person ...</para></personblurb>
                <affiliation>
                    <jobtitle>Chief documentation officer</jobtitle>
                    <org>
                        <orgname>Nowhere.com</orgname>
                        <address>
                            <city>New York</city>
                            <street>345 Fifth Avenue</street>
                            <postcode>23509</postcode>
                            <country>United States</country>
                            <phone>++1-44-944 72 66</phone>
                            <fax>++1-44-944 </fax>
                        </address>  
                    </org>
                 </affiliation>
            </author>
            <author>
                <personname>
                    <honorific>Prof. Dr</honorific>
                    <firstname>Michael</firstname>
                    <surname>Müller</surname>
                </personname>
                <email>michael.mueller@nowhere.com</email>
                <personblurb><para>Dr. Müller is the technical directory of the company nowhere.com</para></personblurb>
                <affiliation>
                    <jobtitle>CTO</jobtitle>
                    <org>
                        <orgname>Nowhere.com</orgname>
                        <address>
                            <city>New York</city>
                            <street>345 Fifth Avenue</street>
                            <postcode>23509</postcode>
                            <country>United States</country>
                            <phone>++1-44-944 72 66</phone>
                            <fax>++1-44-944 </fax>
                        </address>  
                    </org>
                </affiliation>
            </author>
        </authorgroup>
        <abstract>
            <para>The purpose of this document is ...</para>
        </abstract>
    </info>
    <section>
    	<title>A title</title>
    	<para>A paragraph ...</para>
    </section>
    <section>
    	<title>A title</title>
    	<para>A paragraph ...</para>
    </section>
</article>              

            

In the <info/> section you should add the document <title/> and <subtitle/>, information about the authors (<author/> or <authorgroup/>) and a short <abstract/>. The <author/> element contains the <personname/> element, the <email/> element, the <personblurb/> element and the <affiliation/> (containing the jobtitle and information on the organization). The main "body" of the article follows after the <info/> section, and should start with a <sect1/> or <section/> element. Information on the article "body" follows in the next section.

You can embed both raster (png or jpeg) or vector graphics (svg), using the <figure/> element and a <mediaobject/> inside the figure element. You shouldn't change image alignment parameters. These are handled with XSLT conversion.

Following is the code of a <bibliography/> element, the <bibliodiv/> element for adding structure in the bibliography, and individual <biblioentry/> elements:

            
<bibliography xmlns='http://docbook.org/ns/docbook'>
<title>A Test Bibliography</title>

<bibliodiv><title>Books</title>

<biblioentry>
  <abbrev>AhoSethiUllman96</abbrev>
  <authorgroup>
    <author><personname>
      <firstname>Alfred V.</firstname><surname>Aho</surname>
    </personname></author>
    <author><personname>
      <firstname>Ravi</firstname><surname>Sethi</surname>
    </personname></author>
    <author><personname>
      <firstname>Jeffrey D.</firstname><surname>Ullman</surname>
    </personname></author>
  </authorgroup>
  <copyright><year>1996</year>
             <holder>Bell Telephone Laboratories, Inc.</holder></copyright>
  <editor><personname>
    <firstname>James T.</firstname><surname>DeWolf</surname>
</personname></editor>
  <biblioid class="isbn">0-201-10088-6</biblioid>
  <publisher>
    <publishername>Addison-Wesley Publishing Company</publishername>
  </publisher>
  <title>Compilers, Principles, Techniques, and Tools</title>
</biblioentry>

<biblioentry xreflabel="Kites75">
  <authorgroup>
    <author><personname>
      <firstname>Andrea</firstname><surname>Bahadur</surname>
    </personname></author>
    <author><personname>
      <firstname>Mark</firstname><surname>Shwarek</surname>
    </personname></author>
  </authorgroup>
  <copyright><year>1974</year><year>1975</year>
     <holder>Product Development International Holding N. V.</holder>
     </copyright>
  <biblioid class="isbn">0-88459-021-6</biblioid>
  <publisher>
    <publishername>Plenary Publications International, Inc.</publishername>
  </publisher>
  <title>Kites</title>
  <subtitle>Ancient Craft to Modern Sport</subtitle>
  <pagenums>988-999</pagenums>
</biblioentry>

</bibliodiv>
<bibliodiv><title>Periodicals</title>

<biblioentry>
  <abbrev>Walsh97</abbrev>
  <biblioset relation='journal'>
    <title>XML: Principles, Tools, and Techniques</title>
    <publisher>
      <publishername>O'Reilly &amp; Associates, Inc.</publishername>
    </publisher>
    <biblioid class='issn'>1085-2301</biblioid>
    <editor><personname>
      <firstname>Dan</firstname><surname>Connolly</surname>
    </personname></editor>
  </biblioset>
  <biblioset relation='article'>
    <title>A Guide to XML</title>
    <author><personname>
      <surname>Walsh</surname><firstname>Norman</firstname>
    </personname></author>
    <copyright><year>1997</year><holder>ArborText, Inc.</holder></copyright>
    <pagenums>97-108</pagenums>
  </biblioset>
</biblioentry>

</bibliodiv>

</bibliography>

        

The rendering of the bibliography can be seen at the end of page.

A reference to an entry in the bibliography can be made as follows:

            
        <para><xref linkend="AhoSethiUllman96"/> state that ...</para>

        

[AhoSethiUllman96] state that ...

Docbook resources can be found at the official docbook homepage. There is the official DocBook 5 specification, a free downloadable DocBook book, a DocBook FAQ and a DocBook XSLT book available to help you get started. A listing of XML editors supporting docbook and specialized docbook editors is available from the DocBook Wiki.