DITAblogs (troubleshooting)

Cross-reference debugging tool (ditadebug.php)

Once we had large numbers of source files and directories to deal with, we ran into the following kinds of error situations that were difficult to resolve:


Here is an example of an error message generated by the Toolkit that is caused by a bad href. Notice that the message tells you which file is referenced, but not the location of the original reference.

[pipeline] [DOTJ013E][ERROR] Failed to parse the referenced 
file 'installing\nstalling_fo.dita' due to below exception. 
Please correct the reference base on the exception message.
[pipeline] java.io.FileNotFoundException: 
C:\DITAOT_UGRef_SOURCE\installing\nstalling_fo.dita 
(The system cannot find the file specified)
		

Partly as a learning exercise, and partly to allow us to address these issues, we wrote a build tool that starts from a DITA map file and builds a set of cross-reference and error reports for the files used by the DITA map. This can be done because all the files that make up a DITA source tree have to be well-formed and valid XML files. Standard XML parsing libraries can be used to "walk" the set of source files included by the DITA map.

Our PHP script (ditadebug.php) uses the SimpleXML PHP library routines. We added an Ant target to our build script that allows us to run this tool every time we build the book. For the same error shown above, our tool produces the following error message:

Error, file C:\DITAOTUG_SOURCE\processing\../installing/nstalling_fo.dita does not exist!
Bad reference: C:\DITAOTUG_SOURCE\processing\processing_pdf2.dita =>
../installing/nstalling_fo.dita
		

Now we know which file is missing and where the bad reference is! The PHP script is available as part of the DITA Open Toolkit documentation package.

Here is a subset of a ditadebug-generated report for this document that illustrates the types of information it generates.

Starting from ditamap DITAOTUG.ditamap
dir: .\ file: DITAOTUG.ditamap

6 unused files in directories used by this map: 

C:\DITAOTUG_SOURCE\images\dita_finch_logo.jpg , *No DOCTYPE*
...
C:\DITAOTUG_SOURCE\ugxref.txt , *No DOCTYPE*

27 directories in this map: 

C:\DITAOTUG_SOURCE
C:\DITAOTUG_SOURCE\accessing
...
C:\DITAOTUG_SOURCE\troubleshooting

349 files and links in this map: 

C:\DITAOTUG_SOURCE\DITAOTUG_bkinfo.dita , bkinfo
C:\DITAOTUG_SOURCE\DITAOTUG.ditamap , bookmap
...
https://sourceforge.net/projects/dita-ot , *https*

493 references in this map: 

DITAOTUG.ditamap , bkinfo , 
C:\DITAOTUG_SOURCE\DITAOTUG_bkinfo.dita
DITAOTUG.ditamap , chapter , 
C:\DITAOTUG_SOURCE\release_current\relcurrent_map.ditamap
...
C:\DITAOTUG_SOURCE\introduction\aboutdita.dita , conref , 
C:\DITAOTUG_SOURCE\core_vocabulary\darwininfo_typingarch.dita
#darwininfo_typingarch/darwininfo_typingarch_term
C:\DITAOTUG_SOURCE\core_vocabulary\ditaot.dita#ditaot/ditaot_term
...
C:\DITAOTUG_SOURCE\core_vocabulary\xalan.dita , xref , 
C:\DITAOTUG_SOURCE\release_current\sysreqs.dita
C:\DITAOTUG_SOURCE\core_vocabulary\xalan.dita , xref , 
http://archive.apache.org/dist/xml/xalan-j/
		

Message topic generation tool (ditamsg_generator.xsl)

Below is a listing for the XSLT stylesheet used to read the DITA Open Toolkit message repository resource/messages.xml file and convert it to a DITA reference topic (see Messages generated by the Toolkit). This reference topic has been generated multiple times during the production cycle of the DITA Open Toolkit User Guide, as the Toolkit moved to new point releases.

<?xml version="1.0" encoding="ISO-8859-1"?>
<!-- Edited with XML Spy v4.2 -->
<xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:output method="xml" encoding="ISO-8859-1" indent="yes"
doctype-public="-//OASIS//DTD DITA Reference//EN" 
doctype-system="http://docs.oasis-open.org/dita/v1.0.1/dtd/reference.dtd"/>

<!-- Stylesheet to convert messages.xml to a DITA reference topic messages.dita -->
<!-- Author: Dick Johnson 05/27/2006 -->

<xsl:template match="//messages">


<reference id="messages">
<title>DITA Open Toolkit Messages</title>
<refbody>

<!-- put all the Ant messages in a simple table -->
<section id="ant">
<title>Ant messages</title>
<p></p>

<simpletable>
<sthead>
<stentry>Message number</stentry>
<stentry>Type</stentry>
<stentry>Message text</stentry>
<stentry>Action</stentry>
</sthead>

<xsl:apply-templates select="message[substring(@id,1,4)='DOTA']" />

</simpletable>
</section>

<!-- put all the Java messages in a simple table -->
<section id="java">
<title>Java messages</title>
<p></p>

<simpletable>
<sthead>
<stentry>Message number</stentry>
<stentry>Type</stentry>
<stentry>Message text</stentry>
<stentry>Action</stentry>
</sthead>

<xsl:apply-templates select="message[substring(@id,1,4)='DOTJ']" />

</simpletable>
</section>

<!-- put all the XSLT messages in a simple table -->
<section id="xslt">
<title>XSLT messages</title>
<p></p>

<simpletable>
<sthead>
<stentry>Message number</stentry>
<stentry>Type</stentry>
<stentry>Message text</stentry>
<stentry>Action</stentry>
</sthead>

<xsl:apply-templates select="message[substring(@id,1,4)='DOTX']" />

</simpletable>
</section>

</refbody>
</reference>

</xsl:template>

<!-- Reformat an individual message -->
<xsl:template match="message">
 
<strow>
<stentry>
<msgnum>
<xsl:apply-templates select="@id" /></msgnum>
</stentry>
<stentry>
<xsl:apply-templates select="@type" />
</stentry>
<stentry>
<msgph>
<xsl:apply-templates select="reason" /></msgph>
</stentry>
<stentry>
<xsl:apply-templates select="response" />
</stentry>

</strow>

</xsl:template>


<xsl:template match="description">
<p>
<td><xsl:value-of select="."/></td>
</p>
</xsl:template>

<xsl:template match="link">
<a>
<xsl:attribute name="href">
<xsl:value-of select="."/>
</xsl:attribute>
Item link</a>
</xsl:template>

</xsl:stylesheet>