Using the tools

Tools overview

Because the authors of this document needed debugging, reporting, and automatic file generation support not available in DITA Open Toolkit, they produced several tools of their own. These tools are now available as part of the Toolkit.

Message topic generator (ditamsg_generator.xsl)

An XSLT stylesheet (ditamsg_generator.xsl) was used to automate the creation of the Toolkit messages reference topic (Messages generated by the Toolkit). This stylesheet could be useful to other DITA users as an example of how to handle a similar task when documenting other software, especially when the product messages are stored in a valid XML file.

DITA debugging tools (ditadebug.php, ditaedit.php and ditalinks.php)

Three debugging tools were written to deal with the following kinds of problems that were encountered while writing this document.

Cross-referencing problems handled by ditadebug.php

Examples of the second case include the following:

The ditadebug.php tool also helps to answer the following kinds of questions:

String search and replace with ditaedit.php

The ditaedit.php tool can be used to search for strings in all files in a DITA map. It can also be used to replace strings in all files.

URL checking problems handled by ditalinks.php

The ditalinks.php tool checks external URLs and verifies that they exist.

Note: The only kind of URL this tool cannot handle is one requiring login to a website. The tool reports these with the message "URL may not exist." You will need to verify these manually.

DITA reporting tools (ditaauthors.php, ditaids.php, and ditakeys.php)

While writing this document we found it useful to have several types of reporting information derived from the source files:

The ditaauthors.php, ditaids.php, and ditakeys.php tools were written to provide answers to these questions.

Build preview tool (ditapreview.php)

The ditapreview.php tool dynamically builds a DITA map file for only the most recently modified topics and then invokes Internet Explorer to display them.

Software prequisites required

To run these tools you must have the PHP interpreter installed on your build machine. PHP is a free tool that can be downloaded from

Example of how to invoke the tools

You can include any of these tools as part of an Ant build script. The following example shows how to run the debugging tool and write the output to a file.

<!-- create the ditamap debug cross-reference -->
<target name="debug">
<echo>Building debugging file ditadebug.txt</echo>
<mkdir dir="${outdir}/debug_files"/>
<exec executable="${PHPdir}/php.exe" dir = "${projdir}" 
<arg value="${projdir}/project/tools/ditadebug.php"/>
<arg value="${MAP_file}"/>