About the debugging, reporting, and file generation tools

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

An error is generated during the build that indicates a file cannot be found or opened. The Toolkit message log tells you the name of the file it cannot find, but not which file is referring to it. This makes it difficult to find the source of the error.
Some errors in the DITA source files do not produce any build error messages at all, but the output produced is incorrect. These kinds of problems are subtle and can be very difficult to troubleshoot.

Examples of the second case include the following:

When running under Windows, a referenced filepath uses the wrong case of one of the elements, for example, ../Dir1/fn.ft instead of ../dir1/fn.ft..
A cross-reference points to an ID in a file that does not exist.

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

Which directories contain files used by a given ditamap?
Which files in source directories are not used in a ditamap, and therefore could be erased?
For a given file referenced in a ditamap, what type of file is it, who was its author, how big is it, when was it last changed, and what is it about?
Which URLs are referenced in the files used in a ditamap?
What are all the linked connections from one file to another used by a given ditamap?

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:

Who are the authors and copyright holders?
Which IDs were defined in the source file and were any of them duplicates?
Which keywords were used in the source file <prolog> elements?

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

For more information about these tools, see Using the debugging and reporting tools and Production notes (troubleshooting).