DocBook, universal format for technical documents

DocBook is one of five formats dedicated for writing technical documents, reference manuals for example. It is an XML schema (or DTD, or Relax NG), the information is described independently of the presenting.

Summary

Docbook, format XML de document automatique

Formatting automatically documents

Why use Docbook?
How to use DocBook? Convert to PDF?
The shortest example
Content of a DocBook document
Elements of DocBook
DocBook file
Links

The four other formats covered here are:

LaTex.
Textinfo. From a formatted text file, produces an HTML page, an info file or a printable PDF document.
PDF. Mainly for printing, can be used as electronic support.
XPS (XML Paper Specification). New format from Microsoft and intended to replace PDF. May become standard on Windows Vista and common to all desktop applications.

Why use DocBook?

PDF and XPS format are mostly dedicated to printing, and may be generated from DocBook or textinfo files, and should not be used as source files. PDF it less convenient for the web, because not all search engines can parse the content.

Tex, even it is rather old, does not have very simple tools to process it.
Texinfo also requires a tedious manual editing. Texinfo can be - theoretically - converted to DocBook by makeinfo.

You can write technical documents with Open Office, and save them in HTML or PDF.
But the interest of DocBook is in separating data and presenting, the possibility to create automatically documents, and the ability to generate documents from databases. Can convert them to HTML or PDF also.
You can also process the data in several ways (extracting, multiple views, etc...)

DocBook is now used for the documentation of Linux and FreeBSD.

How to use DocBook? Convert to PDF?

A text may be edited directly, or with a graphical editor (see at resources below).
It is possible also to produce a DocBook file from a word processor as Open Office (but this is still alpha for now).
For a manual conversion process, some tools are required:

The DocBook DTD.
The XSL DocBook style sheet.
The XSLT processor.

Some style sheet allows to produce HTML or XSL-FO from a DocBook document.

With the FOP program and the XSL-FO, a PDF file is created with this command:

java org.apache.fop.apps.Fop  -xml myfile.xml  -xsl DocBook-xsl/fo/DocBook.xsl   -PDF myfile.PDF

But you should use an editor instead.

The shortest example

<book id="book1">
     <title>Minimal book</title>
     <chapter id="chapter1">
          <title>One-line chapter</title>
          <para>Just one line of text</para>
     </chapter>
</book>

Content of a DocBook document

A DocBook document is an XML file with predefined tags. They are defined inside a schema or DTD, that is the model of the document structure.

Sample of DocBook document

<?xml version="1.0"?>
<article>
  <title>DocBook Example</title> 
  <section> 
    <title>
       Presentation
    </title>
  <itemizedlist>
   <listitem> 
     <para>
       element
     </para>
   </listitem>
   <listitem> 
     <para>
        element
     </para> 
   </listitem> 
   </itemizedlist> 
    <para> 
        another paragraph
    </para> 
  </section> 
</article>

Standard tags

Some examples of tags:

List: <orderedlist> </orderedlist>
Index: <indexentry> </indexentry>
Table: <table> </table>
Table of contents: <ToC> </ToC>
Legal: <copyright> </copyright>
Structure: <section> <sect1> </sect1> </section>
Image: <imageobject>
<imagedata fileref="image.gif" format="gif"/>
</imageobject>

DocBook file

A DocBook file is an XML file, no special extension is required for filenames.