Author: Just van den Broecke
This document describes the main features and usages of XBook. It is work in progress...
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.
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.
XBook is very well suited to write technical documentation such as project documentation, manuals, Howto's etc.
This section introduces the main features of XBook. The XBook Guides provide more extensive covering for authoring, generation and extensibility..
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.
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.
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
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).
XBook provides an Ant-task in order to generate your documentation as part of your Ant build. This is very handy for project documentation.
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.
Yes documentation is gradually coming. There is so much to uncover...
The documention is divided into three categories of documents dependent on your activities:
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.
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.
World Wide Web Consortium. http://www.w3c.org
World Wide Web Consortium. Extensible Markup Language (XML) 1.0. W3C Recommendation; http://www.w3.org/TR/1998/REC-xml-19980210
Norman Walsh et al.; www.docbook.org
Norman Walsh et al.; DocBook: The Definitive Guide ; O'Reilly; www.oreilly.com/catalog/docbook/