<?xml version="1.0" encoding="UTF-8"?>
<!--Arbortext, Inc., 1988-2010, v.4002-->
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN"
 "reference.dtd">
<?Pub Sty _display FontColor="red"?>
<reference id="loghandling" xml:lang="en-us">
<title>Problem determination and log analysis</title>
<refbody>
<section>   <title>Introduction</title>   <p>The DITA-OT command-line tool has a logging method to log messages both on the screen and into
        the log file. The messages on the screen present user with the status information, warning,
        error, and fatal error messages. By analyzing these messages, user can know what cause the
        problem and how to solve it. In the command-line tool the logger use is specified
        internally, so you do not need to specify it.</p>
      <p>When running DITA-OT directly with Ant, different loggers provided by Ant can be used to
        get different log output. See Ant documentation for more information.</p> </section>
<section>     <title>Analyze messages on the screen</title>      <p>During
the building process, some information or messages occur on the  
   screen to tell you about the status, warnings, errors, or fatal
errors.       You need to analyze the messages to solve the problems.
  <ul>
<li>If the build succeeded with some warning messages on the screen,
         it means that there are something incorrect within the user
input           parameters or source DITA files; but you can still
get the          correct output.</li>
<li>If the build succeeded with some error messages on the screen,
         it means that there are something incorrect within the user
input          parameters or source DITA files; the output maybe not
correct.</li>
<li>If the build failed with fatal error message on the screen,  
       it means that there are something illegal or invalid within
the user          input parameters or source DITA files; you may get
no output, or wrong          output.</li>
</ul>   </p> </section>
<section>
      <title>Analyze messages in the log file</title>
      <p>A log file in plain text format is generated in the log directory, which has a name
        combined with both input file name and transform type. You can open it and find more
        detailed information, which are helpful for solving problems. You can use the same way
        introduced above to analyze the messages and solve the problems.</p>
      <p>The log directory can be specified by:</p>
      <ul>
        <li>using Ant, with argument <codeph>-logfile=<userinput>log-file</userinput></codeph></li>
        <li>using command-line tool, the parameter
            <codeph>/logdir:<userinput>log-dir</userinput></codeph>.</li>
      </ul>
    </section>
<section>     <title>Turn on debug mode</title>     <p>Under debug mode, diagnostic information, such as: environment variables, stack trace, will
        be logged into the log file. These information can help the user or developer to go deep
        into the problems and find the root cause.</p>     <p>By default, the debug mode is disabled. To turn on the debug mode on, you need to follow the
        usage below: <ul>
          <li>Append <codeph>-v</codeph> and <codeph>-Dargs.debug=yes</codeph> in Ant command.</li>
          <li>Append <codeph>/d</codeph> or <codeph>/debug</codeph> in command-line tool.</li>
        </ul></p> </section>
<section>     <title>About message file</title>     <p>The message
file is used to store the detailed log messages, these        messages
are read dynamically from this file. To ensure those messages    
   can be read correctly during the transform process, the message
file        should be located properly. In some situations, the toolkit
may fails        to load the message file due to some exceptions thrown.
Please refer to        <xref href="DITA-troubleshooting.xml"></xref> for
detailed information.</p>     <p>For high level users and developers,
there is a property        <codeph>args.message.file</codeph> in the
toolkit's ant script, it is        used to config the message file,
you can override it in your ant script.</p> </section>
</refbody>
</reference>
<?Pub *0000005341?>
