This User Guide provides a high-level description of the DITA Compare product and includes links to more detailed descriptions contained in the Reference document.
The result of a comparison is a DITA document with differences marked using one of a number of possible output formats
DITA Compare can be downloaded in three different versions. The Mac and Java/Unix versions provide a Java API whereas the .NET version provides a .NET API, and also differs from the others as it comes without a GUI application (which requires Java). The Mac and Java/Unix versions represent builds optimised specifically for the Mac and Unix operating systems, hence the minor differences between them are associated with the way the application is installed and the GUI application is started. The versions are summarised below:
DITA Compare provides an API designed for seamless integration with other systems. Whilst the API provides the most features for controlling and monitoring a comparison, a command-line interface is also provided for convenience.
A GUI application is also provided (except in the .NET version), but this is intended to provide a simple way to show the potential of DITA Compare's features, rather than as an every-day productivity tool.
The result of a comparison is a DITA document that shows differences either using standard DITA markup or markup/processing-instructions tailored for specific DITA tools. The available output formats are standard DITA (exploiting rev and status attributes), plus tracked change formats for the Arbortext, FrameMaker, oXygen and XMetal editors. These are summarised in the table below, and described fully in the Output Formats section of the Reference document.
This section guides you through three simple DITA comparison scenarios, but let's first have a high-level look at what is required to invoke a comparison:
No matter what interface you use, to start a comparison with DITA Compare, you need supply only 4 bits of information:
Parameters are used to control various aspects of a comparison, these are summarised in the Customizing a Comparison section of this document.
The most significant parameter when performing a comparision is output-format, described in the Output Format section. The value of this also affects the default values of other parameters.
In a topic comparison, two versions of a topic are compared and the result is a topic file with differences marked up in accordance with the selected Output Format. Here's a high-level diagram showing the comparison:
The Java code below shows the compare method being invoked on a new instance of DitaTopicCompare. The method call supplies the two input files and the output file as File arguments:
DitaTopicCompare dtc= new DitaTopicCompare(); dtc.compare(new File("C:\\test\\topic-scenario\\topic-a.dita"), new File("C:\\test\\topic-scenario\\topic-b.dita"), new File("C:\\test\\topic-scenario\\out-file.dita"));
An extract from the resulting output file is shown below, the output-format is DITA Markup, the default. This extract shows the mis-spelled word 'hgh' has been replaced with 'high'. Two ph elements have been used to wrap each word and each element uses DITA's own rev and status attributes
<p>In this User Guide we provide a <ph status="deleted" rev="deltaxml-delete">hgh</ph> <ph status="new" rev="deltaxml-add">high</ph> -level description
This DITA Markup output is 'vendor neutral' such that it can be rendered in a useful way in any XML editor that either works with conditional processing or attribute-controlled styling of the WISYWIG (author) view. The screenshot below shows the output as viewed in the 'author' view of SyncroSoft oXygen editor - with the 'Colored revision changes' style selected.
A Mapfile Comparison is a comparison of the DITA map file itself, as opposed to a comparison of the referenced topics (for this, see the Map Topic Set Comparison section).
For this comparison type, the output is a DITA map file with differences marked according to the chosen Output Format.
DitaMapfileCompare dmc = new DitaMapfileCompare(); File in1 = new File("c:\\test\\folderA\\maps\\ditamapA.ditamap"); File in2 = new File("c:\test\\folderB\\maps\\ditamapB.ditamap"); File out = new File("c:\\test\\map-file-scenario\\result.ditamap"); dmc.compare(in1, in2, out);
This comparison type involves the comparison of a set of all the topics referenced from the supplied top-level DITA maps. Here's a high-level diagram showing the comparison:
Changes within topics are marked up using the Output Format specified at the time the comparison is invoked. In the example code (below), the OXYGEN_TCS (oXygen Tracked Changes) output format is used.
DitaMapTopicsetCompare dmc = new DitaMapTopicsetCompare(); dmc.setMapResultStructure(MapResultStructure.UNIFIED_MAP); dmc.setMapResultOrigin(MapResultOrigin.B_DOCUMENT); dmc.setOutputFormat(OutputFormat.OXYGEN_TCS); File in1 = new File("c:\\test\\folderA\\maps\\ditamapA.ditamap"); File in2 = new File("c:\\test\\folderB\\maps\\ditamapB.ditamap"); File out = new File("c:\\test\\map-scenario\\result"); dmc.compare(in1, in2, out);
In the example above, the MapResultStructure enum type UNIFIED_MAP is used to set the result structure, whilst MapResultOrigin.B_DOCUMENT specifies that the result should be shown as modifications to the second map (map B) passed as an argument to the compare method.
In these map comparison scenarios, all topics referenced by each input map are copied to newly created container directories for their respective maps. It is therefore the copies of the DITA map and topic files that are annotated (in the 'Folder B' copy by default) to show the differences found. Whilst this Map Copy approach is inherently safer because the original file copies are left untouched, an In Place map comparison mode is also provided.
An In Place comparison annotates the files (in 'Folder B' by default) in their original location, but creates backup copies at the same location with a 'bak' suffix. This mode may be useful if you want to perform a comparison on your own copies of the two input maps, or if the input maps are under version control in a repository. To invoke an In Place comparison from the API, the compareInplace method is used instead of the compare method, from the command-line, the output destination path is simply substituted with the 'inplace' string.
When performing a map comparison, Dita Compare provides a choice of result structures: Topic Set, Map Pair and Unified Map (described in the Map Topicset Result section of the Reference). The map comparison scenarios outlined here use the same input maps but show each of the three available result structures.
The diagram below shows representations of the two DITA maps used as inputs to the comparison for each of the following comparison scenarios included in this section.
In this scenario, three arguments are supplied to the compare method: the first two arguments are input locations referencing the top-level ditamap files for the DITA map versions, the final argument is the output destination, which should be an empty directory. The only other setting for this scenario is the MapResultStructure property which is set to TOPIC_SET (see the Map Level Output Formats Reference section for further details).
The diagram below shows that, for this map comparison, the input directories, labelled Folder A and Folder B are copied to the supplied output directory
By default, all changes are described in the result in terms of modifications to the second input map supplied, DitaMap B in this case. The map and topics in the Folder B copy are arranged and annotated to describe the map comparison result as outlined below:
The ditamap file in Folder B uses rev and status attributes to describes the differences found in the referenced topics, the XML for this is shown below:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd"> <map> <topicref href="../topics/topic1.dita" status="unchanged"/> <topicref href="../topics/topic2.dita" status="unchanged"/> <topicref href="../../_a-0-file-/topics/topic4A.dita" rev="deltaxml-delete" status="deleted"/> <topicref href="../topics/topic3.dita" status="changed"/> <topicref href="../topics/topic4B.dita" rev="deltaxml-add" status="new"/> </map>
This scenario is the same as the previous with one exception: a Map Pair result is specified for the output. This is done by setting the MapResultStructure property to MAP_PAIR.
The result of this map comparison is shown below.
This diagram shows the DITA map labelled DitaMap B only references topics in Folder B, but there's now an additional Remainder DITA map. This Remainder DITA map references all topics referenced in the DitaMap A map, but not found in DitaMap B, effectively the deleted topics.
This Map Pair structure has a benefit over a Topic Set in that it preserves the hierarchy of topic references, as illustrated by Topic2 still being nested within Topic1, the downside is that deleted topics can not be seen in the context of DitaMap B, they can only be viewed from the Remainder map.
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd"> <map xmlns:ditaarch="http://dita.oasis-open.org/architecture/2005/"> <title>Simple DITA Map Sample</title> <topicref href="../topics/topic1.dita" status="unchanged"> <topicref href="../topics/topic2.dita" status="unchanged"/> </topicref> <topicref href="../topics/topic3.dita" status="changed"/> <topicref href="../topics/topic4B.dita" rev="deltaxml-add" status="new"/> </map>
This scenario is the same as the previous with one exception: a Unified Map result is specified for the output. This is done by setting the MapResultStructure property to UNIFIED_MAP.
The result of this map comparison is shown below.
This diagram shows the DITA map labelled DitaMap B references topics in Folder A and Folder B. The topicref elements in DitaMap A referencing topics not referenced in DitaMap B are adjusted and inserted into DitaMap B, but marked as deletions.
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd"> <map xmlns:ditaarch="http://dita.oasis-open.org/architecture/2005/"> <title>Simple DITA Map Sample</title> <topicref href="../topics/topic1.dita" status="unchanged"> <topicref href="../topics/topic2.dita" status="unchanged"/> </topicref> <topicref href="../../_a-0-file-/topics/topic4a.dita" rev="deltaxml-delete" status="deleted"/> <topicref href="../topics/topic3.dita" status="changed"/> <topicref href="../topics/topic4B.dita" rev="deltaxml-add" status="new"/> </map>
This Unified Map structure aspires to combine the benefits of the Topic Set and Map Pair result structures. So it preserves the hierarchy of topic references in DitaMap B and attempts to insert 'missing' DitaMap A topic references (and their hierarchy also) as close as possible to the DitaMap B location where they are found to be missing.
This result structure is most suitable for cases where the structure of the two DitaMaps (A and B) is broadly similar, so missing topic references can be inserted close to their original position without compromising the original structure.
DITA Compare provides a set of parameters used to control the way comparisons are performed and results are formatted. Initially these parameters have default values for the most common use cases, but these values can be configured via the command-line, GUI or API. A summary of the features controlled by parameters is given in the table below:
|Lexical Preservation||Control preservation of processing instructions, comments, whitespace, entity references, DTD declarations etc.|
|Text Comparison||Control the granularity of a comparison, (e.g. word by word)|
|Table Processing||Validation and processing of DITA tables|
|Representation of Revisions||How the revision of elements, attributes or other node types is represented in the result.|
|Map Control||For map comparisons. Affects the way DITA maps are copied and results structured|
|Editor Optimization||Optimise the output to suit specific DITA editors|
|DITA settings||Control features for specialization, element ordering, reference resolving etc.|
The command line syntax for invoking a comparison with comparison parameters is shown in the topic comparison example below - here param is the parameter name and value is the value to assign to the parameter.
java -jar deltaxml-dita.jar compare topic in1.xml in2.xml out.xml [param=value]*