Topicset Map Sample

Summary

This sample compares two DITA maps, doc1/maps/main.ditamap and doc2/maps/main.ditamap, using all three of the available map result structures: the 'topic set', the 'map-pair' and the 'unified-map'.

An alternative form of the 'map pair' and 'unified map' comparisons is provided, where the output format is set to oXygen tracked changes. This is done in order to illustrate that whether a topic contains reportable change is dependant on the output format. For example, the DITA markup output format cannot represent insertion, deletion or change within a comment, whereas the oXygen track changes output format can. Therefore, we have added a comment to the Aligning Topics topic, which appears in both results, but is only marked as changed in the DITA map file, when the tracked change output format is selected.

Script Features

The sample script (Ant or batch file - depending on download) includes examples with result structures set to topic-set, map-pair and unified-map. Different 'result origin' settings are also used.

Result Origin

The 'result origin' is the input map that is used to form the basis of the output, as discussed in Map LeveL Output Formats Section of the Reference and the map-result-origin parameter documentation.

Output Structure and Destination

The output of these commands are put into the topic-set-A, map-pair-B and unified-map-B directories, which contain a result-alias.ditamap file whose content references the actual results, but can be used as a result in its own right. Note that in the case of the map pair result, the alias combines the two main result maps into a single document.

Please refer to Map LeveL Output Formats Section of the Reference and the map-result-structure parameter documentation for more details.

Java Platform

Using Ant

The sample comparison can be run via an build script using the following commands.

antRun all comparisons.
ant run
ant run-topic-set-ARun the 'topic set' comparison (where the first 'A' input is being used as the 'result origin').
ant run-map-pair-BRun the 'map pair' comparison (where the second 'B' input is being used as the 'result origin').
ant run-unified-map-BRun the 'unified map' comparison (where the second 'B' input is being used as the 'result origin').
ant run-map-pair-B-otcsRun the 'map pair' comparison with the oXygen tracked changes output format selected.
ant run-unified-map-B-otcsRun the 'unified map' comparison with the oXygen tracked changes output format selected.
ant cleanRemove the generate output.

From the Command-Line

The 'topic-set' sample can be run directly by issuing the following command

For Windows

java -jar ..\..\deltaxml-dita.jar compare map doc1\maps\main.ditamap doc1\maps\main.ditamap topic-set-A ^
  map-result-origin=A ^
  map-result-structure=topic-set

PowerShell Usage: Replace the ^ line-continuation character with the ` character.

For Mac OS (or Unix)

java -jar ../../deltaxml-dita.jar compare map doc1/maps/main.ditamap doc1/maps/main.ditamap topic-set-A \
  map-result-origin=A \
  map-result-structure=topic-set

The 'map pair' or 'unified map' comparisons can be run in a similar manner to the 'topic set', but in this case the map-result-orign is B, the map-result-structure is map-pair or unified-map, and the map-copy-location is map-pair-B or unified-map-B. Further, it is possible to select the oXygen tracked changes output format, by adding the parameter output-format=oxygen-tcs to the arguments.

.NET Platform

Using a Batch File

Run the rundemo.bat batch file either by entering rundemo from the command-line or by double-clicking on this file from Windows Explorer. This script runs the same comparison 3 times with different output settings.

From the Command-Line

The 'topic-set' sample comparison can also be run from the command line, using the following:

..\..\bin\deltaxml-dita.exe compare map doc1\maps\main.ditamap doc2\maps\main.ditamap topic-set-A ^
  map-result-origin=A ^
  map-result-structure=topic-set

The 'map pair' or 'unified map' comparisons can be run in a similar manner to the 'topic set', but in this case the map-result-orign is B, the map-result-structure is map-pair or unified-map, and the map-copy-location is map-pair-B or unified-map-B. Further, it is possible to select the oXygen tracked changes output format, by adding the parameter output-format=oxygen-tcs to the arguments.