Guide to Publishing with DITA Open Toolkit
Introduction
The DITA Open Toolkit (DITA-OT) is considered the reference implementation for DITA publishing and it is used in a number of content management and other publishing systems for converting DITA content into other publishing formats including xhtml, PDF and epubs.
This guide documents how to customize DITA-OT processing so that changes can be viewed in various publication forms. Using a ditaval file it is possible to changed font styling (underline and strike-through), font colour and for certain output types include change-bars in the result.
Topic comparison
Topic comparison has been a capability of DITA Compare from its initial release. A ditaval file (deltaxml.ditaval) file is included in the release that demonstrates styling possibilities for topic level comparison.
In the 5.0 release this file has been extended to cover and document changebar support in PDF output.
Map comparison
Versions 1.7 and 1.8 of DITA-OT have limited capabilities for describing Map Comparison results. Some of the issues we have identified include:
Inconsistencies in the handling of rev attributes on the root element of a topic between different output types. For example, with org.dita.pdf2 plugin topic level changes cannot be easily seen.
Poor support for topicref styling which results in Table of Contents which do not indicate added or deleted topics, making it difficult to find or review changes in a PDF document.
DeltaXML would like to see improvements in future release of DITA-OT to address these issues and will contribute and work with the DITA-OT community to address these limitations. In the meantime we have created some small 'patch' downloads for:
DITA-OT version 1.8, 1.8.4 and 1.8.5 (as available from the sourceforge download site)
DITA-OT included as part of the DITA framework in oXygenXML versions 15 , 15.1 and 17
These updates replace three of the DITA-OT files in the org.dita.pdf2 plugin directory. Each of the downloads inlcudes a README file with installation instructions.
The updates are available from our Miscellaneous Downloads section.
To use this enhancement please unpack the files and follow the instructions in the included ReadMe.txt file. We would recommend also using deltaxml.ditaval file discussed above.
Please be aware this download is a temporary response to the issue to allow preview testers and early adopters to produce publications with changes highlighted. When these changes are hopefully available in a future DITA-OT release we will remove this download.
Prepared Samples
Updating DITA-OT may be a complex task in some systems. To provide an example of how the effect of the updates we have prepared two PDF files generated using DITA-OT 1.8, using the org.dita.pdf2 output type, deltaxml.ditaval and the XEP topic shell. One of the result is generated using standard 1.8 code and the other is generated using the enhancements we have available for download. You will see that the Table of Contents shows which topics are added/deleted and also those topics (the final two pages) are styled to show their status and additionally a change-bar is provided.
Small Map Sample using as released DITA-OT: map-compare-standard.pdf
Small Map Sample using enhanced DITA-OT: map-compare-enhanced.pdf