DocBook Publishing

It is important to understand that this framework is not a WYSIWYG solution or "Click-clack" application (a Windows application operated by mouse click). Articles are rather written in soucecode in DocBook ( XML) and then compiled. This might remind you on the good old TEX times where a document was written in the same way.

If you are afraid of using command lines, I can only recommend to use the common Office tools and keep your hands off this approach.

You should be familiar with XML and XSLT basics so that you will not become confused even by the easiest topics. All other information is described in this article so that you will be successful in a very short time.

To create all formats, some software packages are required:

It is recommended to download Java directly from Sun. The Runtime 1.3.1_06 ^[1] for Windows is available at http://java.sun.com/j2se/1.3/download.html . Sun supplies a common setup so that it can easily be installed.

Important: To ensure that the main batch file which starts Ant finds Java, you need to set the environment variable JAVA_HOME. Alternatively it is also possible to enter the Java installation path directly in the batch file.

To check if all settings are right, carry out the following tests in the command line:

[C:\ ]$ echo %JAVA_HOME% 
 C:\Programme\JavaSoft\jdk1.3.1_06 
 [C:\ ]$ %JAVA_HOME%\bin\java 
 Usage: java [-options] class [args...]
 (to execute a class)
 or java -jar [-options] jarfile [args...]
 (to execute a jar file)
 ... 

For defining and transforming with XSLT some additional Java libraries (JARs) are required. As these are the same for all projects, it is recommended to install them in the Lib directory of „JAVA_HOME“ (here „ C:\Programme\JavaSoft\jdk1.3.1_06\lib “. Download the libraries here .

HTMLDOC is available from http://www.easysw.com/htmldoc/ as source code and binary, although the functionality of the binary is supposed to be limited. I did not try this out but compiled a new binary.

Only required is the htmldoc.exe and a few font files which as a default are expected by the binary in „ C:\Program Files\htmldoc . This ZIP file contains all files (Version 1.8.21). Make sure that the binary htmldoc.exe is found in the PATH. This is done by copying it to the Windows directory. If you do not like this, create a new directory for such tools (I use „ C:\Programme\bin “) and adapt the path so that the directory is included. Test this by entering htmldoc in the prompt. The following should be displayed:

[C:\ ]$ htmldoc
 ERROR: No HTML files!
HTMLDOC Version 1.8.21 Copyright 1997-2002 Easy Software Products, All Rights Reserved.
This software is governed by the GNU General Public License, Version 2, and is based in part on the work of the Independent JPEG Group.
 
Usage:
 htmldoc [options] filename1.html [ ... filenameN.html ]
 
Options:
 
 --batch filename.book
 ...       

The tool w3m for creating plain text is available for download at http://www.w3m.org/ . The only thing you need for this framework is the w3m.exe binary and CGYWIN-DLL ^[2] . You can download it here directly. As described above, copy the EXE and DLL to a directory included in the path. The command line should look as follows:

[C:\ ]$ w3m
 version w3m/0.1.9
usage: w3m [options] [URL or filename]
options: 

-t tab set tab width
 ... 

The Microsoft Help compiler is directly available form Microsoft clicking this URL . The file HTMLHELP.EXE Version 1.32 is the required file and started after the download. The setup installs the HTML Help Workshop usually using the path C:\Programme\HTML Help Workshop“. Again, if you want to run this directly, the directory must be included in the path. As an alternative you can also copy the file „hhc.exe“ to the tool directory. The command line will look as follows:

[C:\ ]$ hhc
 Usage: hhc <filename>
 where <filename> = an HTML Help project file
 Example: hhc myfile.hhp       

Python is available from http://www.python.org/ or download ActivePython from ActiveState . As said before: Python needs to be included in the path after installation. Both distributions usually do this automatically. Test directly in the prompt:

[C:\ ]$ python
 ActivePython 2.2.1 Build 222 (ActiveState Corp.) based on
Python 2.2.1 (#34, Apr 15 2002, 09:51:39) [MSC 32 bit (Intel)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>>     

To close the interactive mode, press CTRL-Z

Important: To generate the "real" Word document, the win32com extension needs to be installed- Test in the prompt with:

>>> import win32com
>>> print win32com
 <module 'win32com' from 'C:\Python22\Lib\site-packages\win32com\__init__.pyc'>       

Now you nearly have all the tools you need, only missing is the first project. You can download this file from the section Download and generate all pages and output format with „ make all “.

Nevertheless, it is easier to start with the „Hello World“ project which is described in the next chapter.

This is an optional component as you can use any editor to create a DocBook source code file. Especially for the beginner it might easier to start with OpenOffice. The advantage of the OpenOffice Writer is that you can edit your text WYSIWYG without seeing the XML code. This advantage might also be a disadvantage as you will not have complete control over all aspects of DocBook Publishing. OpenOffice Version 1.0.1 can be downloaded from http://www.openoffice.org/ .

To generate DocBook with OpenOffice a package is required which converts the OpenOffice format to DocBook. This is for example the package OOo2sDbk dar. See chapter 6 „DocBook with OpenOffice“ for more information.

The package can easily be installed. Only extract the zip file ooo2sdbk.zip to the directory of the Python Site package. The module is then commonly available. Download the package from this Website as it contains extended functionality compared to the original.

Test respectively:

>>> import ooo2sdbk
>>> print ooo2sdbk
 <module 'ooo2sdbk' from 'C:\Python22\Lib\site-packages\ooo2sdbk\__init__.pyc'> 

The following explanations follow mainly the reference book of Norman Walsh and Leonard Muellner (see here).

Typically a book is a larger bit of work than an article. Its structure comprises meta information (<bookinfo>), which describe the author, the title and the copyright information. It might also have a Preface Vorwort and several chapters which are divided into paragraphs. In addition it is possible to have appendixes, literatur reference list, a glossary and an index.

An article is much shorter as it does not contain as much parts as a book and is usually only structured into individual chapters. But it does also contain meta information (<articleinfo>) and can have appendixes, a literature reference list, glossary and index.

The following XML section shows a typical structure of a DocBook book.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"../../common/docbook/dtd/docbookx.dtd">
<book lang="de">
 <title>Mein erstes DocBook Buch</title>
 <bookinfo> 
     <author>
       <honorific>Dipl.-Ing</honorific>
       <firstname>Stefan</firstname>
       <surname>Rinke</surname>
     </author>
 </bookinfo>
 <preface> 
     <title>Vorwort</title>
     <para>In einem Vorwort stehen Dinge über das Buch an sich.</para>
 </preface>
 <chapter> 
     <title>Einführung</title>
     <para>Dies ist ein einfacher Artikel
       <indexterm> 
         <primary>Artikel</primary>
         <secondary>DocBook-Artikel</secondary>
       </indexterm>.
     Das ist nur ein Beispielabsatz.</para>
 </chapter>
 <appendix> 
     <title>Anhang 1</title>
     <para>Das ist ein Anhang.</para>
 </appendix>
 <glossary> 
     <glossdiv>
       <title>Ein Glossar</title>
       <glossentry>
         <glossterm id="DocBook">DocBook</glossterm>
         <glosssee>DocBook ist ein Standard zur Erstellung...</glosssee>
       </glossentry>
     </glossdiv>
 </glossary>
 <index/> 
</book>

	The Bookinfo section is optional although you might want to be named as the author.
	The Preface is also optional. But if the book becomes very large, the preface will have about this strucutre.
	Here follow one or several chapters which start with a title <title> and are even more structured by paragraphs <para>.
	With this an index entry is created. The secondary entry is optional.
	Following tihs you will have one or more appendixes.
	If you want to, you can also add a glossary.
	This tag marks the position where the completed index is to be inserted.

To see how such a book might look in HTML^[3], click hier.

A simple article looks accordingly:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"../../common/docbook/dtd/docbookx.dtd">
<article lang="de">
 <title>Mein erster Artikel</title>
 <articleinfo>
     <author>
       <honorific>Dipl.-Ing</honorific>
       <firstname>Stefan</firstname>
       <surname>Rinke</surname>
     </author>
 </articleinfo>
 <para>Dies ist ein einfacher Artikel. Dieser Ausdruck
     <indexterm>
       <primary>Ausdruck</primary>
     </indexterm>
         soll im Index erscheinen.</para>
 <appendix>
     <title>Anhang 1</title>
     <para>Das ist ein Anhang.</para>
 </appendix>
 <glossary>
     <glossdiv>
       <title>Ein Glossar</title>
       <glossentry>
         <glossterm id="DocBook">DocBook</glossterm>
         <glosssee>DocBook ist ein Standard zur Erstellung...</glosssee>
       </glossentry>
     </glossdiv>
 </glossary>
 <index/>
</article>         

To see the result online, click here.

More deeper knowledge on DocBook can be found in the following online resources.

5.4.1. DocBook: The Definitive Guide

The Standard: DocBook: The Definitive Guide which can be read online and offers information from scratch to reference material.

Figure 5.1.  DocBook: The definitive Guide

OpenOffice uses paragraph formats, character formats and frame formats for formatting documents. The are named and linked to certain layout rules. The connection between DocBook and OpenOffice is made exactly over these predefined formats. If for instance a sentence contains a filename, then it is formatted in OpenOffice with the character format „filename“ and converted later into <filename>...</filename> .

It is the same with paragraph format for enumeration or numbered lists: one can use them in OpenOffice as usual and they will be converted in the corrosponding DocBook tags automatically. To make this always work right, one should use a document template or an empty standard document. Such a document is included in the framework.

The most corrosponding formats / tags are intuitive, a more detailed description is on Eric Bellot's website.