XBook Overview

Author: Just van den Broecke
Organization: Just Objects B.V.
Email: just@justobjects.nl

FileID: $Id: overview.xml,v 1.10 2003/01/06 10:28:08 just Exp $
Date: 28.mar.2002

This document describes the main features and usages of XBook. It is work in progress...


1. Introduction

XBook provides a toolset that facilitates organizing, authoring and publishing documentation for the web. The "X" in XBook refers to the fact that documentation is written in XML. But XBook has more features than just generating HTML from XML so read on.

2. XBook and DocBook

Yes the "Book" in XBook has some connotation with similar tools called DocBook and StyleBook (used internally in Jakarta Apache projects). There are important differences however with DocBook that may make you decide (not) to use XBook.

DocBook is extremely powerful but at the same time also has a steep learning curve (see e.g. the 648 page O'Reilly Book on DocBook. In my projects I needed a lightweight tool in which I could use and add simple DTDs with just a few tags to learn. In addition I felt the need to integrate and organize other types of documentation (Javadoc, text files, HTML files) possibly generated by other tools like JavaDoc (maybe even DocBook in the future!) and generate an entire navigational site.

In addition I needed a way to extend and reuse both DTD and XSLT stylesheets.

3. When Should I use XBook ?

XBook is very well suited to write technical documentation such as project documentation, manuals, Howto's etc.

4. A Quick Tour

This section introduces the main features of XBook. The XBook Guides provide more extensive covering for authoring, generation and extensibility..

4.1. XML Documents

Well, the document you are reading right now was originally written in XML. XBook provides several lightweight DTDs for writing documents. Using the xdoc commands in the bin directory you can quickly convert this type of XML documents to HTML. You may use XBook just for producing stand-alone documents and even add your own DTDs and XSLT stylesheets.

See XBook authoring guides.

4.2. Writing the Book

Consider having a bunch of documents, some may be written in XML using doc.dtd, others may be generated (Javadoc or TogetherJ) or directly written in HTML. How can you organize this wild bunch into a set of coherent indexed web pages ?

XBook provides a book DTD called book.dtd. This DTD allows you to specify the hierarchical structure of your book in XML and how to integrate external (non-XML) documents through directives. Using one of the xbook commands from the bin directory you can generate an entire indexed website containing all documents. Any XML-documents specified in your book.xml are automatically converted to HTML (using xdoc) in the process. External documents and assets (images, applets etc) may be copied dependent on directives (as attributes) you provide in book.xml.

See XBook Authoring Guide.

4.3. No XML, No Problem

You are not obliged to write documents in XML, except for the book.xml. You may in some cases just create a book.xml with just external documents, for example to quickly generate a website. For this purpose you may want to use xmenu which is used internally to generate the site after all the book and all documents have been processed.

See also the Menu Authoring Guide

4.4. No DHTML, No Problem

In the default case the xbook command generates an DHTML-based site (through XMenu). However not all browsers support DHTML to the same extend. In this case you may want to use the -lite commandline option to generate a lightweight pure HTML site. Note that in the default (DHTML) the lightweight menu is generated as well. Browsers not supporting NS/MSIE compatible DHTML are automatically redirected to the lightweight pages (index-lite.html).

4.5. Automation with Ant

XBook provides an Ant-task in order to generate your documentation as part of your Ant build. This is very handy for project documentation.

See XBook Generation Guide.

4.6. Extensibility: Adding your own DTDs and XSLT files

Several standard DTDs and corresponding stylesheets (XSLT) are provided by XBook but you can very easily add your own DTDs and transform documents according to your DTDs with your own XSLT stylesheets. Examples are provided in the distribution (directory: test/extend).

See the Extensibility Guide.

5. Documentation

Yes documentation is gradually coming. There is so much to uncover...

The documention is divided into three categories of documents dependent on your activities:

  1. Authoring
  2. Generating output
  3. Extending XBook

6. Getting Started

Once you have unpacked the .zip or .tar.gz distribution, consult the Readme file. If you are upgrading consult also the Version file for update notices.

The test directories provide examples. Best is to start with a simple example such as in test/page and test/album.

You may need to adapt the xbook.bat|sh and xdoc.bat|sh scripts for your local installment but in some cases (specifically on Unix) they may work out-of-the-box.

More complex examples are in test/doc and test/book. Super-users may want to look in how to extend XBook in test/extend.

7. Example Uses

I now use XBook in most of my projects. Also some of my customers are happy with XBook. Some even generate XBook-compliant XML documents from C++ source code in javadoc-style!

See for example: www.keyworx.org:8005/doc.

Another example is just using the photo album www.justobjects.org/amelot.

Especially for Java project documentation XBook is really handy.

References

[W3C]
World Wide Web Consortium. http://www.w3c.org
[W3C-XML]
World Wide Web Consortium. Extensible Markup Language (XML) 1.0. W3C Recommendation; http://www.w3.org/TR/1998/REC-xml-19980210
[DocBook1]
Norman Walsh et al.; www.docbook.org
[DocBook2]
Norman Walsh et al.; DocBook: The Definitive Guide ; O'Reilly; www.oreilly.com/catalog/docbook/