Table of Contents
DeltaXML DocBook Compare ReadMe
Welcome to the DeltaXML DocBook Compare product. DeltaXML DocBook Compare enables you to compare two versions of a DocBook file against each other to produce a new DocBook file marked with revisionflag attributes where it has been changed.
DeltaXML DocBook Compare compares two input DocBook documents and generates an output DocBook document marked up with revisionflag attributes to show where/how the document has changed. This can then be processed further using our DocBook xsl customisation to produce HTML or XML-FO output that highlights added and deleted content and, in the case of XSL-FO, contains changebars.
N.B. Only documents of the same type can be compared against each other, so a book can be compared against another book but not against an article or a chapter. Also, a DocBook 4 input cannot be compared against a DocBook 5 input that uses the new DocBook namespace.
The easiest way to access DeltaXML DocBook Compare is to use the GUI, a demonstration application providing a graphical interface to let you compare your own DocBook files. Select two files and the GUI will display the generated DocBook.
You can start the GUI by
running deltaxml-docbook-gui.sh in your terminal.
The API provides a simple way to integrate DeltaXML DocBook Compare into your existing DocBook processing workflow. It provides access to all of the parameters and allows the use of various combinations of Java Objects as input/output types.
See the API documentation for details on parameter settings and their effects.
DeltaXML DocBook Compare can be run using a command-line interface that is invoked from a terminal window or Windows command line. It is used like this:
java -jar deltaxml-docbook.jar command arguments
The following commands and arguments are supported:
- license
- Prints out the current activated license details.
- describe
- Lists the options available on the compare command.
- compare
- Compares two inputs to produce a result. Takes a minimum of three
file arguments, the two input files and a location to output the result e.g.
java -jar deltaxml-docbook.jar compare input1.xml input2.xml result.xml. There are a number of other optional arguments that can be used. For a full list, run the describe command.
The distribution includes the OASIS DTD, XML Shema and RelaxNG Schema for DocBook 4.3, 4.4, 4.5 and 5.0 as well as the Apache XML Commons Resolver to provide support for XML catalog use. This means, that out-of-the-box, the tool will not need to download the DTDs for these DocBook versions but will use its local copy.
If you wish to use additional catalogs that are searched before the in-built catalog you need to supply the
location(s) using a deltaxmlConfig.xml file. A sample file (and dtd) is provided in the
samples/config directory of this distribution. Copy these files into either the installation
directory of deltaxml-docbook.jar
file or into your user home directory and then modify the value of com.deltaxml.ext.catalog.files to the
relevant path(s). For example:
<configProperty name="com.deltaxml.ext.catalog.files"
value="C:\catalogs\my_catalog.xml;C:\another-catalog.xml" />
If you wish to completely override the built-in catalog, set the xml.catalog.files
property instead.
Please note, it is also possible to use the built-in catalog first, and then additional catalogs
by using the fixed
com.deltaxml.rsc.catalog.files property within the definition of the
xml.catalog.files property as follows:
<configProperty name="xml.catalog.files"
value="${com.deltaxml.rsc.catalog.files};C:\catalogs\my_catalog.xml" />
An alternative way of setting these properties for a single Java invocation only is to use a System property setting when invoking the java command. e.g.
-Dcom.deltaxml.ext.catalog.files.catalog.files=C:\catalogs\my_catalog.xml;C:\another-catalog.xml
Some application servers use classloaders that, for security reasons, limit the ability
to dynamically access some resources and access the location of the running code. If this is
the case, you will need to set the xml.catalog.files variable even if you wish
to use the inbuilt dtds. It should be set to the following, with the relevant path:
<configProperty name="xml.catalog.files"
value="jar:file:/path/to/install/directory/deltaxml-dita.jar!/catalog.xml" />
The Unicode Character Set includes many code points for private use, which are recognised as legitimate Unicode character codes, but are not provided with an (abstract) character. Instead, they are intended to be used within closed systems as the user or developer sees fit. For further details please refer to either the UniCode standard or the Wikipedia entry on Unicode's private use characters.
This product internally uses five characters from the Unicode private character set to represent the values of the predefined XML entities, as illustrated by the following table. For those with a background in XSLT processing, we are following Michael Kay's XSLT-2 'Character Maps as a Substitute for disable-output-escaping' scheme, from the 4th edition of his Programmer's Reference to XSLT 2.0 and XPath2.0 book.
| Predefined XML Entity | Private Unicode Character |
|---|---|
| < |  |
| & |  |
| > |  |
| ' |  |
| " |  |
We are always keen to improve our products - please make use of our Support Forums if you have any comments or suggestions while working with DeltaXML. We hope you enjoy it!
The licence file may need to be upgraded or replaced, such as when changing from an evaluation to full licence or renewing an annual subscription. It is usually located in the top-level directory of the installation. However, it can also be located in a user's home directory, though in this case the licence will only be available to the user whose home directory the licence file is in. The upgrading process is simply a mater of replacing the original licence file with an updated licence file.
The DeltaXML software is licenced under the terms described in the file Licence.html. The licence terms in this file differ
depending upon whether this is an evaluation release of the software or a purchased
release.
Included in the distribution is the saxon9pe.jar, which is a
binary component of the professional edition
of Saxon ('The SAXON XSLT and XQuery Processor from Saxonica Limited.'). This version
of Saxon may only be used when invoked from a DeltaXML product.
The home page for Saxonica is http://www.saxonica.com. For further
details of Saxon's licensing please see http://www.saxonica.com/license/license.xml and the
docs/notices/saxon/ subdirectory included in the
DeltaXML DocBook Compare distribution. In particular, the docs/notices/saxon/LEGAL.txt file describes how the
license/notices of third party code included in Saxon is handled.
This product includes software developed by the Apache Software Foundation (http://www.apache.org), these include:
- the
xercesImpl.jarcomponent from the binary 2.9.0 release of the Xerces-J SAX parser. - the DeltaXML variant of the
resolver.jarcomponent from the 1.2 release of the Apache Commons Resolver OASIS catalog reader.
The DeltaXML adaptation of Apache's resolver contains standard fixes for some of the known bugs and an enhancement that enables entities to be loaded via Java's resource loading mechanism. For further information please contact us.
These components are: Copyright (c) 1999-2006 The Apache Software Foundation. All rights reserved. and are licensed under the terms of the Apache License, Version 2.0. These components must be used under the terms of the license at: http://www.apache.org/licenses/LICENSE-2.0
In accordance with section 4(d) of the Apache License, the notices for these libraries are enclosed in appropriately labelled subdirectories of the DeltaXML DocBook Compare distribution, as follows:
- Xerces-J SAX parser notices are in the
docs/notices/xerces/directory. - Resolver catalog reader notices are in the
docs/notices/resolver/directory.
The deltaxml-docbook.jar file contains one compiled class from the
'TrueLicense Library', which is a component of the TrueLicense Library Collection. This code
is: Copyright 2005 Schlichtherle IT Services, and licensed under the terms of the Apache License, Version
2.0.
In accordance with section 4(d) of the Apache License, the notices for these libraries are
enclosed in the docs/notices/truelicense/ directory of
the DeltaXML DocBook Compare distribution.
Included in this distribution are unmodified copies of the OASIS DocBook 4.4 and 4.5 DTDs (extracted from http://www.docbook.org/xml/4.4/docbook-xml-4.4.zip and
http://www.docbook.org/xml/4.5/docbook-xml-4.5.zip respectively), unmodified copies of the OASIS DocBook 5.0 DTD, XML Schema and RelaxNG Schema (extracted from http://www.docbook.org/xml/5.0/docbook-5.0.zip) and a modified version of the DocBook 4.3 DTD (extracted from http://www.docbook.org/xml/4.3/docbook-xml-4.3.zip with catalog.xml modified where stated. These are all 'Copyright OASIS Open' as stated at the start
of each file.
The Standard Widget Toolkit (SWT) has been used to construct the GUI components used in
the release. One or more jar files may be included according to the specific platform
release. These are licensed using the Eclipse Public License version 1.0 and a copy of the
EPL is available at: http://www.eclipse.org/legal/epl-v10.html. The various SWT files also include
third party content which may have different copyright and license terms. We have included
the various about.html files with further details and the
about_files directories with these notices as summarized below:
| filename | license details | associated notices |
|---|---|---|
swt-lib/cocoa-macosx-x86.jar | docs/notices/swt/cocoa-macosx-x86/about.html | docs/notices/swt/cocoa-macosx-x86/about_files/ |
swt-lib/cocoa-macosx-x86_64.jar | docs/notices/swt/cocoa-macosx-x86_64/about.html | docs/notices/swt/cocoa-macosx-x86_64/about_files/ |
swt-lib/gtk-linux-x86.jar | docs/notices/swt/gtk-linux-x86/about.html | docs/notices/swt/gtk-linux-x86/about_files/ |
swt-lib/gtk-linux-x86_64.jar | docs/notices/swt/gtk-linux-x86_64/about.html | docs/notices/swt/gtk-linux-x86_64/about_files/ |
Included in the distribution is a GUI which is built using the Java port of PureMVC. The PureMVC product and documentation is available from http://trac.puremvc.org/PureMVC_Java. For details of the PureMVC licensing please refer to the files within the docs/notices/puremvc/ directory of the DeltaXML DocBook Compare distribution.