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.
The four other formats covered here are:
- 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
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
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 documentA 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>
Some examples of tags:
- <orderedlist> </orderedlist>
- <indexentry> </indexentry>
- <table> </table>
- Table of contents
- <ToC> </ToC>
- <copyright> </copyright>
- <section> <sect1> </sect1> </section>
<imagedata fileref="image.gif" format="gif"/>
A DocBook file is an XML file, no special extension is required for filenames.
- Oasis. DocBook or Simplified DocBook specifications, and shema. Complete list of tags.
- DocBook. "The definitive guide". With a FAQ.
- OpenJade. Convert XML to other formars. Open source version.
- FOP. Produces various formats, including PDF.
- XmlMind. A complete Java editor, can generate HTML or PDF.
- Lyx. LaTex editor (Win/Lin).