<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
<reference id="troubleshooting" xml:lang="en-us">
<title>Troubleshooting</title>
<shortdesc>This section is used for identifying problems when installing
     and executing the DITA Open Toolkit.</shortdesc>
<refbody>
    <!--
    <section id="section_rtj_4gj_wd">
      <title>Warning: XML resolver not found; external catalogs will be ignored</title>
      <p>Caused by <codeph>org.apache.tools.ant.types.resolver.ApacheCatalogResolver</codeph> class
        not being available in Ant claspath.</p>
      <ol>
        <li>Check that <codeph>ANT_HOME</codeph> system variable is correctly set. </li>
        <li>Check that <filepath>$ANT_HOME/lib/ant-apache-resolver.jar</filepath> exists.</li>
      </ol>
    </section>
    <section id="section_gpl_dhj_wd">
      <title>List file dita.xml.properties or dita.list not found</title>
      <p> Encountered during preprocessing.</p>
      <ol>
        <li>Check that classpath contains <filepath>$DITA_HOME/lib/dost.jar</filepath>.</li>
      </ol>
    </section>
    -->
    <section id="section_stj_4gj_wd">
      <title>Out of Memory Error</title>
      <p>In some cases, you might receive a message stating the build has failed due to an "Out of
        Memory" error. In many cases this can be solved by switching from Xalan to Saxon as the
        default processor. Recent versions of the "Full Easy Install" toolkit distribution ship with
        Saxon instead of Xalan.</p>
      <p>If that does not work, please follow the steps below to fix this problem:</p>
      <ol>
        <li>
          <p platform="windows">For Windows, type <codeph>set ANT_OPTS=%ANT_OPTS% -Xmx256M</codeph>
            in the command prompt before running a build. Alternatively, you can add the value
              <codeph>-Xmx256M</codeph> to the <codeph>ANT_OPTS</codeph> environment variable.</p>
          <p platform="linux osx">For Linux, type <codeph>export ANT_OPTS=$ANT_OPTS
              -Xmx256M</codeph> in the command prompt before running a build.</p>
        </li>
        <li>Run the transformation again.</li>
      </ol>
    </section>
    <section>
      <title>java.io.IOException: Can't store Document</title>
      <p>In some cases, when you run the JavaHelp transformation, you might receive the exception
        above. This problem is caused by some HTML files unrelated with the current JavaHelp
        transformation were found under the output directory. Please follow the steps below to fix
        this problem:</p>
      <ol>
        <li>Change into the output directory.</li>
        <li>Clean the output directory.</li>
        <li>Run the JavaHelp transformation again.</li>
      </ol>
    </section>
    <section>
      <title>Failed to load message file</title>
      <p>In some situations, the toolkit may fails to load the message file <filepath>messages.xml</filepath> and begin
        to throw exceptions.</p>
      <p>To fix this problem, you need to check if the files <filepath>resource/messages.xml</filepath> and
        <filepath>resource/messages.dtd</filepath> exist in the toolkit. If not, please copy them from the toolkit's
        root directory.</p>
    </section>
    <section>
      <title>Commas in file names</title>
      <p>Commas in file names will cause trouble during the processing because Ant uses commas as
        the delimiters when processing batch files in a list. Please prevent using commas in the
        name of DITA files.</p>
    </section>
    <section>
      <title>Stack Overflow</title>
      <p>Sometimes, you will receive an error during the transformation which says the stack memory
        overflows. Please follow the steps below to fix the problem:</p>
      <ol>
        <li>
          <p platform="windows">For Windows, type <codeph>set ANT_OPTS=%ANT_OPTS% -Xms512M</codeph>
            in the command prompt, you can also choose to add a new opition
              <codeph>-Xms512M</codeph> to the <codeph>ANT_OPTS</codeph> environment variable.</p>
          <p platform="linux osx">For Linux, type <codeph>export ANT_OPTS=$ANT_OPTS
              -Xms512M</codeph> in the command prompt.</p>
        </li>
        <li>Run the transformation again.</li>
      </ol>
    </section>
  </refbody>
</reference>
