Just Objects XBook
==================

Generate documentation using XML documents. XBook is supposed to be a lightweight
toolset as compared to DocBook. However not all your content needs to be in XML.
You may include other documents such as generated by javadoc or plain HTML. XBook
will integrate those documents into a single navigation structure.

XBook includes the following tools that can be used
standalone as well:

- xmenu for generating DHTML style dropdown menus
- xdoc for generating HTML docs from XML (like documents and photo albums)

XBook is a tool that binds it all together, i.e. your book may contain all some or none
of the above document types. 

Version info
------------
see VERSION

Planned modifications
---------------------
see TODO

License info
------------
see LICENSE

Author/Contact
--------------
Just van den Broecke
Just Objects B.V.
just@justobjects.nl

Install
-------
Unpack. 
Modify the .bat  in bin (or make corresponding .sh).
See if you can make the examples in /test working
The most important files are 
/lib/xbook.jar the classes and resources specific to XBook
/lib/xbookaux.jar third party classes (XML parser, XSL parser[Xalan] etc)
/src/nl/justobjects/xbook/ contains .java files
/src/nl/justobjects/xbook/rsc contains resource files (DTD, XSL)

Concepts
--------
A book is assembled by bundling documents into a book file (see e.g. test/book/mybook.xml)
Documents may be XML documents according to doc.dtd (<document> tag)
or preformatted (<external> tag). Folders can be defined using the <folder> tag.

You generate the HTML output using the class nl.justobjects.xbook.XBook with two arguments
arg1: the book file
arg2: the output dir

An optional -lite argument generates only lightweight HTML menus.

The book XML file is parsed and processed:
XML to HTML conversion for <document> based on DTD type (doc, album, etc)
optional copying for <external>

The output is generated into the specified output directory. XMenu is used to generate
the output menu structure.
 
Getting Started
---------------
Look at the examples in the /test directory. Each has a .bat file to run them.
Go to a directory and run the bat file from there.

test/doc just converts a single XML document to HTML
test/book is a complete xbook with XML documents and others
test/album is a an example photo album
test/menu is a an example for just generating HTML menus from XML
test/page is a an example for simple webpages

To create your documents in XML you need to get familiar with the DTDs in
/src/nl/justobjects/xbook/rsc/dtd
Best is to start from an existing example such as test/doc/amuse-overview.xml

There are not many tags to learn (at least as compared to DocBook).

Another example is the use of XBook for the documentation itself. The
source documents are in /xdoc, the generated docs in /doc.
And the online documentation.

Gotchas
-------
- if you are on Unix-es without X installed album.dtd may not work (AWT requires X).
- with Ant an older version of Xalan may already be in your CLASSPATH this
  may give severe errors (XSLTHelper NullPointerException)

CLASSPATH
---------
The xbook.jar and xbookaux.jar files contain all resources you need (.class, DTDs, XSL files etc). Only
if you need to overule XSL style or DTDs, you need to put them first in your CLASSPATH.

All DTDs and includes work according to the CLASSPATH (the cpath:/ directive is obsolete)..

For example in your book.xml:

<!DOCTYPE xbook SYSTEM "nl/justobjects/xbook/rsc/dtd/xbook.dtd">

This searches the DTD in the CLASSPATH.

Ant
---
XBook can be called from within Ant. See /xdoc/build.xml for examples. There are
two ways to invoke xbook from Ant: using the XBookAntTask or through a
standard java exec Ant task. The easiest is using the XBookAntTask but this
may not work in all cases.

- Using the XBookAntTask
The Xbook ant task takes two parameters: the book file ("book") and the output dir ("dest").
 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.  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>

- Using a standard Java task
This invokes XBook by forking a java JVM. 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>

Skins
-----
Skin support starts in version 1.1.2 to alter the style of your documents. For now the default skin 
is used as in src/nl/justobjects/xbook/rsc/skin. You may now alter these files to get other colors/fonts
in documents and albums.
More elaborate skins in future versions. 

Extending XDoc
--------------
Starting in version 1.1.3 xdoc (XDoc.java) provides a generic processor to transform any XML document
to any HTML document. You can add your own DTDs and XSL stylesheet. Currently the following convention 
is used:

- the dtd name is used by XDoc to determine an XSL stylesheet the convention is 
that dtd name "mydoc" should have a stylesheet "nl.justobjects.xbook.rsc.xsl.mydoc2html.xsl"
Both the dtd and the XSL stylesheet should be found through the CLASSPATH
 The DTD name is in the DOCTYPE statement such as
<!DOCTYPE mydoc SYSTEM "mydir/mydoc.dtd" >
In this case mydir should be in your CLASSPATH when calling xdoc or xbook.
For an example see the FAQ example under $INSTALL_DIR/test/extend