<?xml version="1.0" encoding="utf-8"?>
<?xml-stylesheet
 href="urn:x-daps:xslt:profiling:docbook45-profile.xsl" 
 type="text/xml"
 title="Profiling step"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.docbook.org/xml/4.5/docbookx.dtd"
[<!ENTITY % entities SYSTEM "entity-decl.ent">
%entities;
]>
<chapter id="cha.daps.user.trouble">
 <title>Troubleshooting</title>
 <abstract>
  <para>
   This chapter lists common problems and possible solutions, sorted into
   categories. </para>
 </abstract>
 <remark>taroth 2012-12-12: todo - for FOP installation, mention download from
  offo.sourceforeg.net in troubleshooting section and add xref</remark>
 <!-- <qandaset><title>Installation and First Steps</title>
  <qandaentry>
   <question>
   <para><remark>taroth 2012-06-01: FIXME</remark></para>
   </question>
   <answer/>
  </qandaentry>
 </qandaset>
-->
 <qandaset id="qa.daps.user.trouble.output">
  <title>Generating Output</title>
  <qandaentry>
   <question>
    <para>Profiling does not work as expected?</para>
   </question>
   <answer>
    <procedure>
     <step>
      <para> Check the values of your profiling attributes in the XML files:
       They must use consistent spelling throughout a documentation project. If
       you assigned multiple values to a profiling attribute, check if the
       values are separated with a semicolon, for example,
        <literal>os="linux;unix"</literal>. </para>
     </step>
     <step>
      <para> Check the &dc; file for your documentation project: Does it
       contain one or multiple <parameter>PROF*</parameter> parameters?
       Otherwise &dapsacr; does not know which profiling attributes to
       interpret. Do the <parameter>PROF*</parameter> parameters match the
       profiling attributes used in the XML files? Do the values of the
        <parameter>PROF*</parameter> parameters match the attribute values used
       in the XML files? </para>
     </step>
     <step>
      <para> Check the &main; file of your documentation projects: Does its
       header contain the following line? </para>
      <screen>href="urn:x-daps:xslt:profiling:docbook45-profile.xsl" type="text/xml"</screen>
      <para> If not, any profiling parameters in the &dc; file will be
       ignored during generation of the output. </para>
     </step>
    </procedure>
    <para> For more details, refer to <xref linkend="sec.daps.user.edit.profile"
     /> and <ulink url="http://www.sagehill.net/docbookxsl/Profiling.html"/>.
    </para>
   </answer>
  </qandaentry>
 </qandaset>

 <qandaset id="qa.daps.user.trouble.misc">
  <title>Miscellaneous</title>
  <qandaentry id="qa.daps.user.trouble.misc.verbosity">
   <question>
    <para>Why does &dapsacr; not talk to me? <remark>dpopov 2016-10-12: Why  don't &dapsacr; give me any feedback?</remark>
    </para>
   </question>
   <answer>
    <para>By default &dapsacr; only shows the result of the current subcommand. 
     To increase the verbosity run <command>daps</command> with the option
     <option>-v</option>, <option>-vv</option>, or <option>-vvv</option>.
     For the highest verbosity, use the <option>--debug</option> option. </para>
   </answer>
  </qandaentry>
  <qandaentry>
   <question>
    <para>Where do I find the log files?</para>
   </question>
   <answer>
    <para> If you run into problems with &dapsacr; that you cannot
     classify, check the &dapsacr; log files in
       <filename><replaceable>YOUR_DOC_DIR</replaceable>/build/<replaceable>BOOKNAME</replaceable>/log</filename>.
     A complete log file of the latest
     <command>daps&nbsp;<replaceable>subcommand</replaceable> </command>
     that was executed is available in <filename><replaceable>YOUR_DOC_DIR</replaceable>/build/<replaceable>BOOKNAME</replaceable>/log/make_<replaceable>SUBCOMMAND</replaceable>.log</filename>
    </para>
    <para> In case of an error the complete log file will be shown on the screen
     (STDOUT). </para>
   </answer>
  </qandaentry>
  <qandaentry>
   <question>
    <para>Are all changes to &dapsacr; backward-compatible?</para>
   </question>
   <answer>
    <para>
      No. If you have recently updated to a higher &dapsacr; version and
      afterward experience strange behavior that are difficult to debug, check
      your custom &dapsacr; configuration file (&dapsconf-user;) against the
      system-wide configuration file (&dapsconf-sys;). Search for any
      parameters that may have changed. By default, the settings in the custom
      &dapsacr; configuration file will override the settings in
      &dapsconf-sys;. Therefore any parameter incompatibilities between the
      files may lead to unexpected behavior of &dapsacr;.
    </para>
    <para>
      When switching from &dapsacr; 1.x to &dapsacr; &dapsversion;, especially
      check the syntax of any XSLT parameters that you are using (on the
      command line, in scripts or in &dc; files). If you have not adjusted the
      parameters to the new syntax, this may result in strange error messages.
      For details, refer to <xref linkend="cha.daps.user.config"/>.
    </para>
   </answer>
  </qandaentry>
 </qandaset>
</chapter>
