RSS

Search Engine

Showing posts with label DocBook with Eclipse - Tutorial. Show all posts
Showing posts with label DocBook with Eclipse - Tutorial. Show all posts

Saturday, October 16, 2010

Introduction to DocBook

1.1. Overview

DocBook is a standard for creating well-formated plain text documents. It allows the creation of documentation that is portable between different operating systems and text processing tools. DocBook documents can easily be transformed into other output formats via XSLT . XSLT stands for Extensible Stylesheet Language Transformation. DocBook is plain text and can therefore be writen in a text editor which supports plain text as output format and put under version control.

Stylesheets for converting DocBook to common output are available, e.g. to convert into HTML, pdf, java help or Unix man pages.

DocBook has two main document class, book and article.

  • Article: Used for writing technical articles. The main tag is article. Article is used in the following example.

  • Book: Used for longer description. The main tags is book. In addition to sections which are used in an article another structuring element exists, the chapter.

   

Tip

The above defines that the DTD is stored in a directory one levels above the document directory.

1.3. The required toolset

To create DocBook files and to convert them into other formats you have to use :

  • The DocBook DTD which defines how a DocBook must be written.

  • XSLT stylesheets to convert your DocBook into another format.

  • A XSLT parser

We will use Eclipse as an XML editor, Xalan as the XSLT parser and Apache Ant for the XSLT transformation.

Installation

2.1. Eclipse

You need to have the Eclipse installed. See Eclipse IDE for installing and using Eclipse. We will use Apache Ant but Ant is integrated into Eclipse therefore no additional installation is required.

2.2. Docbook and Stylesheets

Download the Docbook DTD and XSLT stylesheets. You can download the Docbook DTD from http://www.oasis-open.org/docbook/xml/4.5 and the XSLT stylesheets from http://docbook.sourceforge.net At of the time of writing this article the version "1.75.2" is the most recent version. Download the docbook-xsl distribution, e.g. "docbook-xsl-1.75.2.zip".

2.3. XSL processor

Unfortunately the XSL processor included into the JVM has problem with the XSLT stylesheets. Therefore download the Xalan XSL processor from http://xml.apache.org/xalan-j/ .

Thank you

Thank you for practicing with this tutorial.

I maintain this tutorial in my private time.