DocBook

DocBook
←	Chapter 9. Documentation	→

DocBook Overview

DocBook is a Document Type Definition (DTD) for creating structured documents. Any technical documentation has by definition a deep structure. In the software-age does the documentation change as rapid as software. The documentation must follow and support the same organizing principles practiced in software development. The documentation structure might even be more complex than the structure of the documented software.

DocBook itself is a transient format, allowing any kind of conversion. May it from man-pages to DocBook to XHTML. Or as in round-trip : from a popular word-processor to DocBook to another or the same word processor.

DocBook is the standard documentation format for Linux® –Linux Documentation Project (LDP). Other large Linux® projects also use DocBook for documentation.

The versatility and plain-text format makes DocBook a practical solution for technical documents. DocBook documents can be put under version control; while the writer is still free to select her favored writing-tool, either a word-processor or editor.

I am using XAE with Emacs for writing DocBook documents. This way, I can write documentation and source code within the same environment. Often, at almost the same time; switching between documenting and programming without delay.

A DocBook 4.5 based documentation may consist of many filial documents. These filial documents are integrated through entities into the documentation. or »xinclude« The mechanism is similar to an »include« statement in C or a »package require« in Tcl/Tk.

Pictures and examples are also referenced from external sources. Referenced files are better maintable than single documents. Unfortunately, the DocBook syntax highlighting does not yet work inside of referenced source code.

There are two reference methods in DocBook: entityref and fileref. entityref is the more natural way for figures, were an entity, pointing to the figure, gets defined inside the master document. Through entityref and a XML catalogs, parametric documents become feasible. There is one cavet with entityref without a catalog: file paths are absolute, even when the entity uses relative path! The used XML catalog must resolve the entityref to avoid absolute file pathes in the target document. fileref on the other hand allows for relative file names –relative to the master document; preserving the relative path in the generating HTML.

Fileref is still parameterizable: In combination with format. The format value may serve as the file extension.

format="SVG"
fileref="graphics/mygraphics"

here a file named mygrpahics.SVG must exist inside the local directory mygraphics.

Using entities as parameter values.

<!ENTITY sdpi "20">
<!ENTITY cwidth "90">

<!-- format and file names as entitties -->
<!ENTITY ftype "SVG">
<!ENTITY cshierarchy "csshierarchy02">
...
      <figure id="csshier">
        <title>Hierarchy of Listboxes</title>
        <mediaobject>
          <imageobject>
            <imagedata
              format="&ftype;"
              align="center"
              contentwidth="&cwidth;%"
              contentdepth="88em"
              scale="&sdpi;"
              scalefit="1"
              fileref="pictures/&cshierarchy;" />
            </imageobject>
          </mediaobject>
        </figure>

refentry and Entities

refentry is the DocBook man page. Each template will have its own refentry document.

The refentry documents are then assembled into a larger document through entities.

Example 9.1. Entity Reference

<!ENTITY mytemplatepage SYSTEM
           "mytemplate.xml">

The Entity defined in Example 9.1, “Entity Reference” is later referenced inside the DocBook 4.5 document, see Example 9.2, “Using an Entity”.

Example 9.2. Using an Entity

&mytemplate; <!-- Here the entity is used -->

Any used entity must be defined either in the DOCTYPE preamble of a stand alone document, or inside the master document.

An entity can be seen as a variable definition. Entities add flexibility to a document.

Example 9.3. DOCTYPE and Entity.

<!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/
         docbook/xml/4.5/docbookx.dtd"[

<!ENTITY mytemplatepage SYSTEM  "mytemplate.xml">
]>

The Example 9.3, “DOCTYPE and Entity.” makes the entity »mytemplatepage« known inside the entire DocBook document. The Example 9.2, “Using an Entity” can be used in referenced documents, too.

XAE Emacs Commentary Block

Each refentry document, generated by Jeszra, contains a commentary block at the end of the file. This block controls how the document is treated inside the editor Emacs.

Emacs provides a couple of different modes for XML and DocBook. This block is dedicated to the XAE mode.

Example 9.4. DocBook Mode in Emacs

               
<!-- 
Local Variables:
mode: xae
coding: utf-8-unix
sgml-indent-step: 2
sgml-indent-data: t
sgml-set-face: t
sgml-parent-document: ("appendix.xml" "appendix" )
sgml-insert-missing-element-comment: nil
End:
-->

The Example 9.4, “DocBook Mode in Emacs” declares the parent document for this document as: »appendix.xml« of type »appendix«.

Emacs will parse the parent document for entities whenever it is told to do so –through such a comment block. Thus DOCTYPE declarations can be omitted inside a child document. Only a single entity list must exist inside the master document for the entire documentation.

←	↖	→
Chapter 9. Documentation	↑	Creating Documents