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 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:
deltaxml-docbook.exe 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.
deltaxml-docbook.exe 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.exe
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" />
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 'bin' 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.
The core DeltaXML code is written in Java, compiled to Java Virtual Macine (JVM)
bytecode, and packaged into appropriately named Java archive files (jars). These are converted
into .Net binary files via the use of the IKVM's ikvmc 'JVM to .Net Common
Inermediate Language (CIL) bytecode' compiler. In addition, the third-party binary jar
libraries, which the core deltaXML code uses, are also converted to .Net CIL bytecode in a
similar manner. These third-party binary libraries are otherwise unaltered, with the exception
of our modified variant of the Apache Commons Resolver.
Included in the distribution are those IKVM DLLs that are linked to from DeltaXML DocBook Compare. The IKVM product and documentation is available from http://www.ikvm.net. For details of the IKVM licensing please refer to the files within the docs/notices/ikvm/ directory of the DeltaXML DocBook Compare distribution.
Included in the distribution is the saxon9pe.dll, which is a
dotnet IKVM translation of the - otherwise unmodified -
saxon9pe.jar, 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.
Also included in the distribution is the net.sf.saxon.dotnet
package from the open source home edition of Saxon (Saxon-HE), which is compiled and IKVM
translated to the saxon9pe-dotnet.dll library. Saxon-HE is provided under
the terms of the Mozilla Public License, a copy of which can be obtained at http://www.mozilla.org/MPL/.
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.dlllibrary which is an IKVM compiled combination of thexercesImpl.jarcomponent from the binary 2.9.0 release of the Xerces-J SAX parser and the DeltaXML adaptaion (variant) of theresolver.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 an IKVMed translation of 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.