<?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>In the DITA Open Toolkit
1.2 or above, a new logging method is supported      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. The messages in the log file present user
with more      detailed information about the transformation process.
By analyzing these      messages, user can know what cause the problem
and how to solve it.</p><?Pub Caret 347?>   <p>The logging method
is based on Ant's Logger &amp; Listener interface.      By default,
this logging method is disabled, and all the messages occur on   
  the screen just like previous releases.</p>   <p>To start this new
logging method, you need to follow the usage below:   <ul>
<li>In Ant command, specify the logger by appending          <codeph>-logger
org.dita.dost.log.DITAOTBuildLogger</codeph> in the          command
parameters, for example:          <codeblock>ant sample.web -logger org.dita.dost.log.DITAOTBuildLogger
        </codeblock></li>
<li>In Java command, the logger is specified internally, so you do
not          need to specify it again.</li>
</ul></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 using the parameter      <codeph>/logdir:{args.logdir}</codeph> for
the output options.</p>   <p><note>In some cases, there would be no
log file generated:     <ul>
<li>You have entered an invalid Ant command or Java command to start
             the toolkit.</li>
<li>The log file with the same name in the same directory exists and
             can not be deleted.</li>
</ul></note></p> </section>
<section>     <title>Turn on debug mode</title>     <p>Debug mode
is supported along with the new logging method. 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,          you need to
follow the usage below:       <ul>
<li>Append <codeph>-d</codeph> or <codeph>-debug</codeph> in Ant 
            command.</li>
<li>Append <codeph>/d</codeph> or <codeph>/debug</codeph> in Java
             command.</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>     <note>Due to the difference
of underly implementation between Java, And,        and XSL, the property <codeph>args.message.file</codeph> is
only useful        for Java and Ant; To keep the normal function of
log handling, you still        need to ensure there are files 'resource/messages.xml'
and 'resource/messages.dtd'        both in the toolkit's root directory
and in the directory that you run the        toolkit.</note> </section>
</refbody>
</reference>
<?Pub *0000005341?>
