1. Introduction

DocBook defines a set of markup elements useful for marking up text so that the text can then be transformed into several different formats.

It's possible to create documents in different formats HTML, XML, RTF, TeX, and others.

The idea is to write just once and reach the largest possible number of people with the information.

Digital information not stored properly tends to get lost. Due to the fact that not containing uncommon characters (such as binary formats) it's possible to index and search directly on the documents written on SGML and consequently on DocBook.

The SGML systems use markups to make their description. DocBook holds over 300 markup elements each one with several attributes which can assume several values, these can be fixed or defined by the document / style that the author has used.

Just to remind if any changes are made on the DocBook's definitions DTD, it's no longer DocBook.

2. Documents

This document uses the following conventions[1]:

    <para>Beginning and end of paragraph</para>

3. Configuration needed

The identifier systems used by the SGML and by some tools are based on catalogues which perform the translation of these identifiers over to files holding the necessary definitions.

The section on tailoring a catalogue (see Section 4) will give more details about these files.

For such tools to be able to find the necessary catalogue(s) the value of the environment variable SGML_CATALOG_FILES should be configured, as shown in the following example:

    $ export SGML_CATALOG_FILES="/usr/lib/sgml/catalog"

This is the only necessary additional configuration for the DocBook, tools and the like to work correctly on your platform.

4. Creating and modifying catalogues

A catalogue is a text file containing the translation rules of the public identifier to system's files.

They make easy to use the DocBook, for they allow each user to have their files installed in a different place (e.g. your home directory, /usr/local/sgml or in any other place) though no other change on the document is necessary to be processed and "compiled".

    -- Catalogue for the Conectiva Styles --                             
    
    OVERRIDE YES
     
    PUBLIC "-//Conectiva SA//DTD DocBook Conectiva variant V1.0//EN"     
           "/home/ldp/styles/books.dtd" 
    
    DELEGATE "-//OASIS" 
             "/home/ldp/SGML/dtds/catalog.dtd"
    
    DOCTYPE BOOK /home/ldp/SGML/dtds/docbook/db31/docbook.dtd            
     
    -- EOF -- 
            

As in the example above, to associate an identifier to a file just follow the sequence shown:

1. Copy the identifier PUBLIC

2. Type the identifying text

3. Indicate the path to the associated file

    "-//Conectiva SA//DTD books V1.0//EN"

5. Tools for Document Edition Using DocBook

Several tools are available to facilitate the edition work of documents on the DocBook format. Due to the complexity of its rules and the large variety of element options and attributes to them, the use of these automatic tools are recommended.

A comprehensive list can be found at the OASIS tools list.

Particularly and without the intention to start any religious "war" among editors, I think the solution emacs + psgml is the best solution at hands, regarding either the open source or the free of charge issue.

The tool used is according to each author's preference, however, it's recomended to have at least the following features:

• Analysis of the DTD dynamically

• Insertion of elements based on DTD analyzed

• Visual highlight of the text either in color or any other possible attributes. This helps to differentiate the text from constant processing elements and instructions on it.

6. Writing with DocBook elements

An editor capable of inserting an element according with DTD analisys helps a lot since it can allow or not the element to be used at the position where the cursor is in. This way you can be sure that no invalid element was added anywhere in your document.

In order to ensure future changes are as easy as possible, authors should try to keep as much compatibility as possible with theXML version of the DocBook DTD. This means keeping element names in upper case, using double quotes in all attributes, not using "markup minimizations" (explained below), and not omitting end tags. Most tools that automatically insert elements (like psgml+emacs) follow these rules automatically or with some fine tuning.

There are several forms of markup minimization. These include empty tags. One example of tag minimization is that instead of typing the end tag you simply type </>. Another example, as said before, is ommiting tags. You can see both examples below:

    <para>I'm using <emphasis>here</>, normal text here, 
    and <>here</> I emphasized the text again, with empty tags.</para>

Each type of document created has a specific structure and example of documents can found afterwards on this document. (see Section 12).

Considering the explanation above we can proceed to instructions on how to write a document using DocBook.

    <firstname>First_Name</firstname>
    <othername>Middle_Name</othername>
    <surname>Surname</surname>
                  

    <keycombo>
       <keycap>Ctrl</keycap>
       <keycap>S</keycap>
    </keycombo>
                  

    <menuchoice>
       <shortcut>
          <keycombo>
             <keycap>Ctrl</keycap>
             <keycap>S</keycap>
          </keycombo>
       </shortcut>
       <guimenu>Arquivo</guimenu>
       <guimenuitem>Salvar</guimenuitem>
    </menuchoice>
                  

    <blockquote>
       <attribution>Text Author</attribution>
       <para>Quote Text.</para>
    </blockquote>
                  

    <filename>file</filename>

    <filename id="directory">directory</filename>

    <emphasis>text</emphasis>

    <footnote>
       <to>Footnote text</to>
    </footnote>

    <ulink url="http://www.conectiva.com>Conectiva S.A.</>

    <itemizedlist>
       <listitem>
          <to>item</to>
       </listitem>
       <listitem>
          <to>item</to>
       </listitem>
    </itemizedlist>

    <orderedlist>
       <listitem>
          <to>item</to>
       </listitem>
       <listitem>
          <to>item</to>
       </listitem>
    </orderedlist>

    <segmentedlist>
       <title>Binary to decimal conversion</title>
       <segtitle>Binary</segtitle>
       <segtitle>Decimal</segtitle>
       </seglistitem><seg>00</seg><seg>0</seg>
       </seglistitem>
       <seglistitem><seg>01</seg><seg>1</seg>
       </seglistitem>
       <seglistitem><seg>10</seg><seg>2</seg>
    </segmentedlist>

    <variablelist>
       <varlistentry>
          <term>Entry 1</term>
          <listitem>
             <to>Description</to>
          </listitem>
       </varlistentry>
       <varlistentry>
          <term>Entry 2</term>
          <listitem>
             <to>Description</to>
          </listitem>
       </varlistentry>
    </variablelist>

    <simplelist type="horiz" columns="3">
       <member>1</member>
       <member>2</member>
       <member>3</member>
       <member>4</member>
       <member>5</member>
       <member>6</member>
    </simplelist>
    <simplelist type="inline">
       <member>A</member>
       <member>B</member>
       <member>C</member>
       <member>D</member>
       <member>E</member>
       <member>F</member>
    </simplelist>

    <glossentry>
       <glossterm>Term</glossterm>
       <glossdef>
          <to>Definition</to>
       </glossdef>
    </glossentry>

    <section id="secao">
    ...
    </section>
    <section id="reference the other section">
    ...
    <to>Please, see<xref linkend="secao"> for more information.

7. Encoding Indexes

The generation of indexes depends on the markups inserted in the text.

Such markups will be processed afterwards by an external tool and will generate the index. An example of such a tool is the collateindex.pl script (see Section 11.1). Details about the process used to generate these indexes are shown in Section 11.3.

The indexes have nesting levels. The markup of an index is done by the code Example 2.

    <indexterm>
       <primary>Main level</primary>
       <secondary>Second level</secondary>
       <tertiary>Third level</tertiary>
    </indexterm>
          

It's possible to refer to chapters, sections and other parts of the document using the attribute zone.

    <section id="encoding-index">
        <title>Encoding Indexes</title>
    
        <indexterm zone="encoding-index">
          <primary>edition</primary>
          <secondary>index</secondary>
        </indexterm>
    
        <para>The generation of indexes depend on the inserted markups on the text. </para>
          

The Example 3 has the code used to generate the entry of this edition on the index. In fact, since the attribute zone is used, the index statement could be located anywhere in the document or even in a separate file.

However, to facilitate maintenance the entries for the index were all placed after the text to which it refers.

        <PARA>Typing the text normally sometimes there's the need of 
       <INDEXTERM CLASS="startofrange" ID="example-band-index">
          <PRIMARY>examples</PRIMARY>
          <SECONDARY>index</SECONDARY>
       </INDEXTERM>
       mark large amounts of text.</para>
    
       <para>Keep inserting the paragraphs normally.</para>
    
       <para>Until the end of the section intended
       to be indexed.
       <INDEXTERM STARTREF="example-band-index" CLASS="endofrange">.
       </PARA>

8. Inserting Pictures

It's necessary to insert pictures for all types of media on which the document will be published.

If you use the TeX format you'll need the images as a PostScript file. For online publishing you can use any kind of common image file, such as JPG, GIF or PNG.

The easiest way to insert pictures is the use of the attribute fileref. Usually pictures are generated in JPG and in PostScript (PS or EPS).

    <figure>
       <title>Picture's Title</title>
       <graphic fileref="images/file"></graphic>
    </figure>

Replacing <figure> by <informalfigure> eliminates the need to insert a title for the picture.

There's still the float attribute on which the value 0 indicates that the picture should be placed exactly where the text flux appears. The value 1 allows the picture to be moved to a more convenient location (this location can be described on the style sheet used or even can be controlled by the application being used).

    <figure>
       <title>Title</title>
       <mediaobject>
          <imageobject>
             <imagedata fileref="images/file.eps" format="eps">
          </imageobject>
          <imageobject>
             <imagedata fileref="images/file.jpg" format="jpg">
          </imageobject>
          <textobject>
             <phrase>Here there's an image of this example</phrase>
          </textobject>
          <caption><para>Image Description. Optional. </para></caption>
       </mediaobject>
    </figure>

9. Tables

Many information are best represented when formatted as tables.

A primitive way to create tables was already presented on the Table 1 with the use of <simplelist>, however, the DocBook has more sophisticated methods to deal with this information.

    <table frame="all">
      <title>Sample Table</title>
      <tgroup cols="5">
        <colspec colname="column1">
        <colspec colname="column2">
        <colspec colname="column3">
        <colspec colnum="5" colname="column5">
        <spanspec namest="column1" nameend="column2" spanname="span-horiz" align="center">
        <spanspec namest="column2" nameend="column3" spanname="span-horiz-vert" align="center">
        <thead>
          <row>
            <entry spanname="span-horiz">
               <foreignphrase>Span</foreignphrase> horizontal
            </entry>
            <entry>Heading 2</entry>
            <entry>Heading 3</entry>
            <entry>Heading 4</entry>
          </row>
        </thead>
        <tfoot>
          <row>
            <entry>Footing 1</entry>
            <entry>Footing 2</entry>
            <entry>Footing 3</entry>
            <entry>Footing 4</entry>
            <entry>Footing 5</entry>
          </row>
        </tfoot>
        <tbody>
          <row>
            <entry>Data11</entry>
            <entry>Data12</entry>
            <entry>Data13</entry>
            <entry>Data14</entry>
            <entry>Data15</entry>
          </row>
          <row>
            <entry>Data21</entry>
            <entry>Data22</entry>
            <entry>Data23</entry>
            <entry>Data24</entry>
            <entry morerows="1" valign="middle">
               <foreignphrase>Span</foreignphrase> vertical
            </entry>
          </row>
          <row>
            <entry>Data31</entry>
            <entry spanname="span-horiz-vert" morerows="1" valign="bottom">
               <foreignphrase>Span</foreignphrase> duplo
            </entry>
            <entry>Data34</entry>
          </row>
          <row>
            <entry>Data41</entry>
            <entry>Data44</entry>
            <entry>Data45</entry>
          </row>
        </tbody>
      </tgroup>
    </table>
    
          

10. Listings and program codes

An interesting feature is to show parts of code and the possibility to comment on them. The DocBook allows the insertion of the program code and also callouts to specific lines of this code.

Such a feature was used, for example, to demonstrate how a catalogue file is configured (see Section 4).

The used code was demonstrated below. In case the callout feature isn't desired, it's possible to eliminate the areas between <areaspec> and <calloutlist>.

    <example id="sample-catalog">
      <title>Catalog Sample</title>
      <programlistingco>
        <areaspec>
          <area coords="1" id="ex.catalogue.comment">
          <area coords="5" id="ex.catalogue.definition">
          <area coords="11" id="ex.catalogue.eof">
        </areaspec>
            <programlisting>
    -- Catalogues for the Conectiva S.A. Style --
    
    OVERRIDE YES
     
    PUBLIC "-//Conectiva SA//DTD books V1.0//EN" "/home/ldp/estilos/livros.dtd" 
    
    DELEGATE "-//OASIS" "/home/ldp/SGML/dtds/catalog.dtd"
    
    DOCTYPE BOOK /home/ldp/SGML/dtds/docbook/db31/docbook.dtd
     
    -- EOF -- 
            </programlisting>
        <calloutlist>
          <callout arearefs="ex.catalogue.comment">
            <to> Comment. Comments begin with <quote>--</quote> 
            and follows to the end of the line. </to> 
          </callout>
          <callout arearefs="ex.catalogue.definition">
            <to> The public type association 
               <parameter class="option">"-//Conectiva SA//DTD books V1.0//EN"</parameter> 
               with the file <filename>books.dtd</filename> on the directory
               <filename class="directory">/home/ldp/estilos</filename>. </para> 
          </callout>
          <callout arearefs="ex.catalogue.eof">
            <para> Comment informing the end of the file. </para>
          </callout>
        </calloutlist>
      </programlistingco>
    </example>
        

The listings can be directly inserted on the document's body without the need of the element <example> or <para>.

The calling coordinates specifications are done with reference to the code line which will be commented.

11. Tools & Hints

The process of producing output and generating indexes is repetitive and error prone. To make things easier some scripts are included here to facilitate this work. Customize and use them at will.

    #!/bin/bash
    #
    # Compile DocBook documents into several output formats.
    #
    # Godoy.
    # 19991230 - Initial release.
    # 20000117 - Placed the options using "case" and parameters passed 
    #	     via command line. The pages on the Zope are already updated.
    #	      --- Removed to public version (/home/ldp). 
    # 20000120 - Placed the call to use the books.dtd.
    # 20000126 - Placed the commands for the index generation.
    # 
    
    # If the jade is already installed, disconsider the line bellow.
     JADE=/usr/bin/jade
    
    # If the jade package is already installed, disconsider the line bellow.
    # JADE=/usr/bin/openjade
    
    DOCUMENT=$1
    shift 1
    TYPE=$1
    
    . ~/.bash_profile
    . ~/.bashrc
    
    case $TYPE in
        html)
           rm -f *.htm
           rm -f *.html
           perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -N -o index.sgml 
           jade -t sgml -V html-index -d /home/ldp/SGML/style/dsssl/docbook/html/docbook.dsl $DOCUMENT.sgml
           perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -o index.sgml HTML.index
           $JADE -t sgml -i html -d /home/ldp/SGML/style/dsssl/docbook/html/docbook.dsl -d /home/ldp/SGML/conectiva/livros.dsl#html $DOCUMENT.sgml
        ;;
        rtf)
           rm -f $DOCUMENT.rtf
           perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -N -o index.sgml 
           jade -t sgml -V html-index -d /home/ldp/SGML/style/dsssl/docbook/html/docbook.dsl $DOCUMENT.sgml
           perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -o indice.sgml HTML.index
           $JADE -t rtf -V rtf-backend -d /home/ldp/SGML/style/dsssl/docbook/print/docbook.dsl -d /home/ldp/SGML/conectiva/books.dsl#print $DOCUMENT.sgml
        ;;
        xml)
           rm -f $DOCUMENT.xml
           perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -N -o index.sgml 
           jade -t sgml -V html-index -d /home/ldp/SGML/style/dsssl/docbook/html/docbook.dsl $DOCUMENT.sgml
           perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -o indice.sgml HTML.index
           $JADE -t sgml -i xml -d /home/ldp/SGML/style/xsl/docbook/html/docbook.xsl $DOCUMENT.sgml
        ;;
        tex)
           rm -f $DOCUMENT.tex
           perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -N -o indice.sgml 
           jade -t sgml -V html-index -d /home/ldp/SGML/style/dsssl/docbook/html/docbook.dsl $DOCUMENT.sgml
           perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -o indice.sgml HTML.index
           $JADE -t tex -V tex-backend -d /home/ldp/SGML/style/dsssl/docbook/print/docbook.dsl -d /home/ldp/SGML/conectiva/livros.dsl#print $DOCUMENT.sgml
        ;;
        dvi)
           rm -f $DOCUMENT.tex
           rm -f $DOCUMENT.dvi
           perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -N -o indice.sgml 
           jade -t sgml -V html-index -d /home/ldp/SGML/style/dsssl/docbook/html/docbook.dsl $DOCUMENT.sgml
           perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -o indice.sgml HTML.index
           $JADE -t tex -V tex-backend -d /home/ldp/SGML/style/dsssl/docbook/print/docbook.dsl -d /home/ldp/SGML/conectiva/livros.dsl#print $DOCUMENT.sgml
           jadetex $DOCUMENT.tex
        ;;
        mirror)
           rm -f $DOCUMENT.tex
           rm -f $DOCUMENT.dvi
           rm -f $DOCUMENT.mirror.ps
           perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -N -o indice.sgml 
           jade -t sgml -V html-index -d /home/ldp/SGML/style/dsssl/docbook/html/docbook.dsl $DOCUMENT.sgml
           perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -o indice.sgml HTML.index
           $JADE -t tex -V tex-backend -d /home/ldp/SGML/style/dsssl/docbook/print/docbook.dsl -d /home/ldp/SGML/conectiva/livros.dsl#print $DOCUMENT.sgml
           jadetex $DOCUMENT.tex
           dvips -h /home/ldp/estilos/skel/mirr.hd -O 1.5cm,3cm -f $DOCUMENT.dvi -o $DOCUMENT.mirror.ps
        ;;
        ps)
           rm -f $DOCUMENT.tex
           rm -f $DOCUMENT.dvi
           rm -f $DOCUMENT.ps
           perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -N -o indice.sgml 
           jade -t sgml -V html-index -d /home/ldp/SGML/style/dsssl/docbook/html/docbook.dsl $DOCUMENT.sgml
           perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -o indice.sgml HTML.index
           $JADE -t tex -V tex-backend -d /home/ldp/SGML/style/dsssl/docbook/print/docbook.dsl -d /home/ldp/SGML/conectiva/livros.dsl#print $DOCUMENT.sgml
           jadetex $DOCUMENT.tex
           dvips -The 1.5cm,3cm -f $DOCUMENT.dvi -o $DOCUMENT.ps
        ;;
        *)
           echo "How to use: $0 file {html|tex|rtf|xml|ps|dvi|mirror}"
           exit 1
           esac
    
    exit 0
    
            

    <!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
    <!entity html-docbook PUBLIC "-//Norman Walsh//DOCUMENT DocBook HTML Stylesheet//EN" CDATA DSSSL>
    <!entity print-docbook PUBLIC "-//Norman Walsh//DOCUMENT DocBook Print Stylesheet//EN" CDATA DSSSL>
    ]>
    
    <style-sheet>
    <style-specification use="html">
    <style-specification-body>
    
    ; Includes a summary at the beginning of an item. 
    (define %generate-article-toc% #t)
    
    </style-specification-body>
    </style-specification>
    <style-specification use="print">
    <style-specification-body>
    
    ; Includes a summary at the beginning of an item.    
    (define %generate-article-toc% #t)
    
    </style-specification-body>
    </style-specification>
    <external-specification id="html" document="html-docbook">
    <external-specification id="print" document="print-docbook">
    </style-sheet>
    
            

    <!doctype article PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [

<!-- Insertion of the index -->
<!entity index SYSTEM "index.sgml">
]>
            

    <!entity % review "INCLUDE">
    ...
    <![%review;[
<para>This paragrph will be included on the draft when the entity
"review" is defined with the value "INCLUDE". </para>
]]>
            

12. Document samples

As stated before each type of document has a particular heading and valid commands structure. The following sub-sections will provide heading and valid commands structures on articles and books.

These examples do not cover all possibilities and they are available here only with the intention to serve as generic guides for what it's possible to do.

    <article class="whitepaper" id="using -docbook" lang="pt-br"><?dbhtml filename="using-docbook.html">
    
      <artheader>
        <title>Como-Fazer DocBook</title>
        <author>
          <firstname>Jorge</firstname>
          <othername>Luiz</othername>
          <surname>Godoy</surname>
          <othername>Filho</othername>
          <affiliation>
            <orgname><ulink url="http://www.conectiva.com">Conectiva S.A.</ulink></orgname>
            <orgdiv>Publishing Departmentt;/orgdiv>
            <address><email>godoy@conectiva.com</email></address>
          </affiliation>
        </author>
        <revhistory>
          <revision>
            <revnumber>1.0</revnumber>
            <date>27 de janeiro de 2000</date>
            <authorinitials>godoy</authorinitials>
            <revremark>Versão inicial.</revremark>
          </revision>
        </revhistory>
    
        <legalnotice>
          <para>This document can be freely translated and distributed. It's released 
          under the LDP License.</para>
        </legalnotice>
    
        <keywordset>
          <keyword>SGML</keyword>
          <keyword>DocBook</keyword>
          <keyword>DTD</keyword>
          <keyword>XML</keyword>
          <keyword>catalogs</keyword>
          <keyword>documents</keyword>
          <keyword>Publishingdlt;/keyword>
          <keyword>Conectiva</keyword>
          <keyword>configuration</keyword>
          <keyword>use</keyword>
          <keyword>tools</keyword>
          <keyword>HOWTO</keyword>
        </keywordset>
    
      </artheader>
    
          

    <book id="network-systems-administration><?dbhtml filename="html/networkadm.html">
      <bookinfo>
        <author>
          <firstname>Jorge</firstname>
          <surname>Godoy</surname>
          <affiliation>
            <orgname>&conectivasa;</orgname>
            <orgdiv>Publishing Departmentlt;/orgdiv>
            <address role="email">godoy@conectiva.com.br</address>
          </affiliation>
        </author>
        <editor>
          <firstname>Jorge</firstname>
          <surname>Godoy</surname>
        </editor>
        <copyright>
          <year>2000</year>
          <holder>&conectiva;</holder>
        </copyright>
        <title>Network and Systems Administration Using Linux</title>
        <legalnotice>
          <para>The contents of this book can be freely used and distributed
          as far as the source is mentioned as a reference that is, its bibliograph.</para>
        </legalnotice>
        <edition>INTERNAL Edition for comments</edition>
        <publisher>
          <publishername>Conectiva S/A</publishername>
          <address><city>Curitiba</city><country>Brasil</country></address>
        </publisher>
        <revhistory>
          <revision>
            <revnumber>1.0</revnumber>
            <date>Maio de 2000</date>
            <revremark>First Edition</revremark>
          </revision>
        </revhistory>
        <isbn>ISBN#</isbn>
        <pubdate>$Data: 1999/12/30 $</pubdate>
      </bookinfo>