XBook - Generation Guide

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

FileID: $Id: generation-guide.xml,v 1.4 2003/11/19 15:12:09 just Exp $
Date: 24.jan.2002

This document describes the tools and stylesheets used in the generation process.


1. Introduction

[WORK IN PROGRESS]

2. Generating the Book (xbook.bat|sh)

2.1. Purpose

This script is used to generate the entire site from a book.xml file according to book.dtd.

2.2. Usage

   xbook.bat|sh [-lite] <book file> <destination directory>
   

The optional -lite option can be used to generate only lightweight HTML menus (like in this documentation) i.s.o. DHTML menus. If not specified both a lightweight and DHTML menu is generated. The lightweight index file is called index-lite.html.

2.3. Example

See the test/book example directory.

3. Generating Documents (xdoc.bat|sh)

3.1. Purpose

This script is used to generate HTML from an XML document written according to one of the standard document DTDs like doc.dtd, page.dtd or album.dtd. Or a user-provided DTD when extensibility is used. This command takes the DTD name of the document and maps it to a corresponding XSLT sheet according to the convention <DTDname>2html.xsl. For example the DTD name "album" maps to album2html.xsl. The XSLT file name is searched through the CLASSPATH, first prefixed with nl/justobjects/xbook/rsc/xsl/. If not found through the name itself.

3.2. Usage

   xdoc.bat|sh <source XML file> [destination HTML file];
   

3.3. Example

See the test/doc|album|page|extend example directories.

4. Generating the Book through ANT

4.1. Purpose

XBook generation can be done through the <xbook> optional Ant task provided with the XBook distribution (see XBookAnttask.java) or directly using the standard Ant <java> task.

4.2. Usage

4.2.1. Invoking XBook using the XBook Ant Task

Basically you need to specify two things in the Ant build.xml file: the taskdef for xbook and the actual xbook task. The xbook task takes the standard parameters also used in the script: book, dest and lite (boolean). Important is that Ant can find xbook.jar and xbookaux.jar This may be done by providing these jars within the classpath, through standard Ant extensibility or explicitly when defining the task (as done in the example). NOTE: conflicts may arise when Xalan is in your Ant lib dir. You may then see something like "nl.justobjects.xbook.XSLTHelper class not found". In that case you may better invoke xbook through a standard Ant java task (see below). The xbook task takes the standard parameters also used in the script: book, dest and lite (boolean).

Here is an example:

<!-- Defines the XBook task and its CLASSPATH --> <taskdef name="xbook" classname="nl.justobjects.xbook.XBookAntTask"> <classpath> <pathelement location="${basedir}/../lib/xbook.jar"/> <pathelement location="${basedir}/../lib/xbookaux.jar"/> </classpath> </taskdef> <!-- Invoke XBook --> <target name="main"> <xbook book="${basedir}/book.xml" dest="${basedir}/result" lite="true"/> </target>

4.2.2. Invoking XBook using the Ant Java task

This is often the safest way when CLASSPATH issues and Xalan conflicts arise when using the XBookAntTask. Here is an example.

<target name="xbookexec"> <java classname="nl.justobjects.xbook.XBook" fork="true" failonerror="true" maxmemory="128m" > <arg value="-lite"/> <arg value="${basedir}/book.xml"/> <arg value="${basedir}/result"/> <classpath> <pathelement location="${basedir}/../lib/xbook.jar"/> <pathelement location="${basedir}/../lib/xbookaux.jar"/> </classpath> </java> </target>

4.3. Example

Below is the XBook project Ant build file for the documentation where the two ways of invoking XBook within Ant are provided.

1: <!-- 2: 3: ANT Build file for XBook doc 4: 5: This file needs to be separate in order to have XBook jars build 6: first to build its own documentation (chicken/egg). This 7: way the Ant Xbook taskdef doesn't need to be in the CLASSPATH so we 8: can just run plain Ant. 9: 10: Can also be used to just build documentation without building 11: the entire thing. 12: 13: author: Just 14: version: $Id: build.xml,v 1.9 2003/11/19 15:38:53 just Exp $ 15: 16: --> 17: <project name="xbook" default="xbookexec" basedir="."> 18: 19: <!-- Defines the XBook task and its CLASSPATH --> 20: <taskdef name="xbook" classname="nl.justobjects.xbook.XBookAntTask"> 21: 22: <classpath> 23: <!-- <pathelement location="/home/just/tmp/build/xbook"/> --> 24: <pathelement location="${basedir}/../lib/xbook.jar"/> 25: <pathelement location="${basedir}/../lib/xbookaux.jar"/> 26: </classpath> 27: </taskdef> 28: 29: <!-- Just Do It (generate lightweight HTML menu ) --> 30: <target name="main"> 31: <xbook book="${basedir}/book.xml" dest="${basedir}/../doc" lite="true"/> 32: </target> 33: 34: <!-- Alternative way if conflicts with Ant occur. --> 35: <target name="xbookexec"> 36: <java classname="nl.justobjects.xbook.XBook" fork="true" 37: failonerror="true" 38: maxmemory="128m" 39: > 40: <arg value="-lite"/> 41: <arg value="${basedir}/book.xml"/> 42: <arg value="${basedir}/../doc"/> 43: <classpath> 44: <pathelement location="${basedir}/../lib/xbook.jar"/> 45: <pathelement location="${basedir}/../lib/xbookaux.jar"/> 46: </classpath> 47: </java> 48: </target> 49: </project>

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
[WordAssociationFootball]
Monty Python's WordAssociationFootball