Imported Upstream version 2.3.1upstream/2.3.1

1 files changed, 0 insertions, 914 deletions

diff --git a/doc/user/troubleshoot.in b/doc/user/troubleshoot.in
deleted file mode 100644
index 7259ed3..0000000
--- a/doc/user/troubleshoot.in
+++ /dev/null
@@ -1,914 +0,0 @@
-<!--
-
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation
-
-  Permission is hereby granted, free of charge, to any person obtaining
-  a copy of this software and associated documentation files (the
-  "Software"), to deal in the Software without restriction, including
-  without limitation the rights to use, copy, modify, merge, publish,
-  distribute, sublicense, and/or sell copies of the Software, and to
-  permit persons to whom the Software is furnished to do so, subject to
-  the following conditions:
-
-  The above copyright notice and this permission notice shall be included
-  in all copies or substantial portions of the Software.
-
-  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
-  KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
-  WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
-  LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
-  OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-  WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-
--->
-
-  <para>
-
-  The experience of configuring any
-  software build tool to build a large code base
-  usually, at some point,
-  involves trying to figure out why
-  the tool is behaving a certain way,
-  and how to get it to behave the way you want.
-  &SCons; is no different.
-  This appendix contains a number of
-  different ways in which you can
-  get some additional insight into &SCons;' behavior.
-
-  </para>
-
-  <para>
-
-  Note that we're always interested in trying to
-  improve how you can troubleshoot configuration problems.
-  If you run into a problem that has
-  you scratching your head,
-  and which there just doesn't seem to be a good way to debug,
-  odds are pretty good that someone else will run into
-  the same problem, too.
-  If so, please let the SCons development team know
-  (preferably by filing a bug report
-  or feature request at our project pages at tigris.org)
-  so that we can use your feedback
-  to try to come up with a better way to help you,
-  and others, get the necessary insight into &SCons; behavior
-  to help identify and fix configuration issues.
-
-  </para>
-
-  <section>
-  <title>Why is That Target Being Rebuilt?  the &debug-explain; Option</title>
-
-    <para>
-
-    Let's look at a simple example of
-    a misconfigured build
-    that causes a target to be rebuilt
-    every time &SCons; is run:
-
-    </para>
-
-    <scons_example name="explain1">
-      <file name="SConstruct" printme="1">
-      # Intentionally misspell the output file name in the
-      # command used to create the file:
-      Command('file.out', 'file.in', 'cp $SOURCE file.oout')
-      </file>
-      <file name="file.in">
-      file.in
-      </file>
-    </scons_example>
-
-    <para>
-
-    (Note to Windows users:  The POSIX &cp; command
-    copies the first file named on the command line
-    to the second file.
-    In our example, it copies the &file_in; file
-    to the &file_out; file.)
-
-    </para>
-
-    <para>
-
-    Now if we run &SCons; multiple times on this example,
-    we see that it re-runs the &cp;
-    command every time:
-
-    </para>
-
-    <scons_output example="explain1" os="posix">
-      <scons_output_command>scons -Q</scons_output_command>
-      <scons_output_command>scons -Q</scons_output_command>
-      <scons_output_command>scons -Q</scons_output_command>
-    </scons_output>
-
-    <para>
-
-    In this example,
-    the underlying cause is obvious:
-    we've intentionally misspelled the output file name
-    in the &cp; command,
-    so the command doesn't actually
-    build the &file_out; file that we've told &SCons; to expect.
-    But if the problem weren't obvious,
-    it would be helpful
-    to specify the &debug-explain; option
-    on the command line
-    to have &SCons; tell us very specifically
-    why it's decided to rebuild the target:
-
-    </para>
-
-    <scons_output example="explain1" os="posix">
-      <scons_output_command>scons -Q --debug=explain</scons_output_command>
-    </scons_output>
-
-    <para>
-
-    If this had been a more complicated example
-    involving a lot of build output,
-    having &SCons; tell us that
-    it's trying to rebuild the target file
-    because it doesn't exist
-    would be an important clue
-    that something was wrong with
-    the command that we invoked to build it.
-
-    </para>
-
-    <para>
-
-    The &debug-explain; option also comes in handy
-    to help figure out what input file changed.
-    Given a simple configuration that builds
-    a program from three source files,
-    changing one of the source files
-    and rebuilding with the &debug-explain;
-    option shows very specifically
-    why &SCons; rebuilds the files that it does:
-
-    </para>
-
-    <scons_example name="explain2">
-      <file name="SConstruct">
-      Program('prog', ['file1.c', 'file2.c', 'file3.c'])
-      </file>
-      <file name="file1.c">
-      file1.c
-      </file>
-      <file name="file2.c">
-      file2.c
-      </file>
-      <file name="file3.c">
-      file3.c
-      </file>
-    </scons_example>
-
-    <scons_output example="explain2" os="posix">
-      <scons_output_command>scons -Q</scons_output_command>
-      <scons_output_command output="    [CHANGE THE CONTENTS OF file2.c]">edit file2.c</scons_output_command>
-      <scons_output_command>scons -Q --debug=explain</scons_output_command>
-    </scons_output>
-
-    <para>
-
-    This becomes even more helpful
-    in identifying when a file is rebuilt
-    due to a change in an implicit dependency,
-    such as an incuded <filename>.h</filename> file.
-    If the <filename>file1.c</filename>
-    and <filename>file3.c</filename> files
-    in our example
-    both included a &hello_h; file,
-    then changing that included file
-    and re-running &SCons; with the &debug-explain; option
-    will pinpoint that it's the change to the included file
-    that starts the chain of rebuilds:
-
-    </para>
-
-    <scons_example name="explain3">
-      <file name="SConstruct">
-      Program('prog', ['file1.c', 'file2.c', 'file3.c'], CPPPATH='.')
-      </file>
-      <file name="file1.c">
-      #include &lt;hello.h&gt;
-      file1.c
-      </file>
-      <file name="file2.c">
-      file2.c
-      </file>
-      <file name="file3.c">
-      #include &lt;hello.h&gt;
-      file3.c
-      </file>
-      <file name="hello.h">
-      #define string    "world"
-      </file>
-    </scons_example>
-
-    <scons_output example="explain3" os="posix">
-      <scons_output_command>scons -Q</scons_output_command>
-      <scons_output_command output="    [CHANGE THE CONTENTS OF hello.h]">edit hello.h</scons_output_command>
-      <scons_output_command>scons -Q --debug=explain</scons_output_command>
-    </scons_output>
-
-    <para>
-
-    (Note that the &debug-explain; option will only tell you
-    why &SCons; decided to rebuild necessary targets.
-    It does not tell you what files it examined
-    when deciding <emphasis>not</emphasis>
-    to rebuild a target file,
-    which is often a more valuable question to answer.)
-
-    </para>
-
-  </section>
-
-  <section>
-  <title>What's in That Construction Environment?  the &Dump; Method</title>
-
-    <para>
-
-    When you create a construction environment,
-    &SCons; populates it
-    with construction variables that are set up
-    for various compilers, linkers and utilities
-    that it finds on your system.
-    Although this is usually helpful and what you want,
-    it might be frustrating if &SCons;
-    doesn't set certain variables that you
-    expect to be set.
-    In situations like this,
-    it's sometimes helpful to use the
-    construction environment &Dump; method
-    to print all or some of
-    the construction variables.
-    Note that the &Dump; method
-    <emphasis>returns</emphasis>
-    the representation of the variables
-    in the environment
-    for you to print (or otherwise manipulate):
-
-    </para>
-
-    <scons_example name="Dump">
-      <file name="SConstruct" printme="1">
-         env = Environment()
-         print env.Dump()
-      </file>
-    </scons_example>
-
-    <para>
-
-    On a POSIX system with gcc installed,
-    this might generate:
-
-    </para>
-
-    <scons_output example="Dump" os="posix" tools="gcc">
-      <scons_output_command>scons</scons_output_command>
-    </scons_output>
-
-    <para>
-
-    On a Windows system with Visual C++
-    the output might look like:
-
-    </para>
-
-    <scons_output example="Dump" os="win32" tools="msvc">
-      <scons_output_command>scons</scons_output_command>
-    </scons_output>
-
-    <para>
-
-    The construction environments in these examples have
-    actually been restricted to just gcc and Visual C++,
-    respectively.
-    In a real-life situation,
-    the construction environments will
-    likely contain a great many more variables.
-    Also note that we've massaged the example output above
-    to make the memory address of all objects a constant 0x700000.
-    In reality, you would see a different hexadecimal
-    number for each object.
-
-    </para>
-
-    <para>
-
-    To make it easier to see just what you're
-    interested in,
-    the &Dump; method allows you to
-    specify a specific constrcution variable
-    that you want to disply.
-    For example,
-    it's not unusual to want to verify
-    the external environment used to execute build commands,
-    to make sure that the PATH and other
-    environment variables are set up the way they should be.
-    You can do this as follows:
-
-    </para>
-
-    <scons_example name="Dump_ENV">
-      <file name="SConstruct" printme="1">
-         env = Environment()
-         print env.Dump('ENV')
-      </file>
-    </scons_example>
-
-    <para>
-
-    Which might display the following when executed on a POSIX system:
-
-    </para>
-
-    <scons_output example="Dump_ENV" os="posix">
-      <scons_output_command>scons</scons_output_command>
-    </scons_output>
-
-    <para>
-
-    And the following when executed on a Windows system:
-
-    </para>
-
-    <scons_output example="Dump_ENV" os="win32">
-      <scons_output_command>scons</scons_output_command>
-    </scons_output>
-
-  </section>
-
-  <section>
-
-  <title>What Dependencies Does &SCons; Know About?  the &tree; Option</title>
-
-    <para>
-
-    Sometimes the best way to try to figure out what
-    &SCons; is doing is simply to take a look at the
-    dependency graph that it constructs
-    based on your &SConscript; files.
-    The <literal>--tree</literal> option
-    will display all or part of the
-    &SCons; dependency graph in an
-    "ASCII art" graphical format
-    that shows the dependency hierarchy.
-
-    </para>
-
-    <para>
-
-    For example, given the following input &SConstruct; file:
-
-    </para>
-
-    <scons_example name="tree1">
-      <file name="SConstruct" printme="1">
-         env = Environment(CPPPATH = ['.'])
-         env.Program('prog', ['f1.c', 'f2.c', 'f3.c'])
-      </file>
-      <file name="f1.c">
-      #include "inc.h"
-      </file>
-      <file name="f2.c">
-      #include "inc.h"
-      </file>
-      <file name="f3.c">
-      #include "inc.h"
-      </file>
-      <file name="inc.h">
-      inc.h
-      </file>
-    </scons_example>
-
-    <para>
-
-    Running &SCons; with the <literal>--tree=all</literal>
-    option yields:
-
-    </para>
-
-    <scons_output example="tree1">
-      <scons_output_command>scons -Q --tree=all</scons_output_command>
-    </scons_output>
-
-    <para>
-
-    The tree will also be printed when the
-    <literal>-n</literal> (no execute) option is used,
-    which allows you to examine the dependency graph
-    for a configuration without actually
-    rebuilding anything in the tree.
-
-    </para>
-
-    <para>
-
-    The <literal>--tree</literal> option only prints
-    the dependency graph for the specified targets
-    (or the default target(s) if none are specified on the command line).
-    So if you specify a target like <filename>f2.o</filename>
-    on the command line,
-    the <literal>--tree</literal> option will only
-    print the dependency graph for that file:
-
-    </para>
-
-    <scons_output example="tree1">
-      <scons_output_command>scons -Q --tree=all f2.o</scons_output_command>
-    </scons_output>
-
-    <para>
-
-    This is, of course, useful for
-    restricting the output from a very large
-    build configuration to just a
-    portion in which you're interested.
-    Multiple targets are fine,
-    in which case a tree will be printed
-    for each specified target:
-
-    </para>
-
-    <scons_output example="tree1">
-      <scons_output_command>scons -Q --tree=all f1.o f3.o</scons_output_command>
-    </scons_output>
-
-    <para>
-
-    The <literal>status</literal> argument may be used
-    to tell &SCons; to print status information about
-    each file in the dependency graph:
-
-    </para>
-
-    <scons_output example="tree1">
-      <scons_output_command>scons -Q --tree=status</scons_output_command>
-    </scons_output>
-
-    <para>
-
-    Note that <literal>--tree=all,status</literal> is equivalent;
-    the <literal>all</literal>
-    is assumed if only <literal>status</literal> is present.
-    As an alternative to <literal>all</literal>,
-    you can specify <literal>--tree=derived</literal>
-    to have &SCons; only print derived targets
-    in the tree output,
-    skipping source files
-    (like <filename>.c</filename> and <filename>.h</filename> files):
-
-    </para>
-
-    <scons_output example="tree1">
-      <scons_output_command>scons -Q --tree=derived</scons_output_command>
-    </scons_output>
-
-    <para>
-
-    You can use the <literal>status</literal>
-    modifier with <literal>derived</literal> as well:
-
-    </para>
-
-    <scons_output example="tree1">
-      <scons_output_command>scons -Q --tree=derived,status</scons_output_command>
-    </scons_output>
-
-    <para>
-
-    Note that the order of the <literal>--tree=</literal>
-    arguments doesn't matter;
-    <literal>--tree=status,derived</literal> is
-    completely equivalent.
-
-    </para>
-
-    <para>
-
-    The default behavior of the <literal>--tree</literal> option
-    is to repeat all of the dependencies each time the library dependency
-    (or any other dependency file) is encountered in the tree.
-    If certain target files share other target files,
-    such as two programs that use the same library:
-
-    </para>
-
-    <scons_example name="tree2">
-      <file name="SConstruct" printme="1">
-         env = Environment(CPPPATH = ['.'],
-                           LIBS = ['foo'],
-                           LIBPATH = ['.'])
-         env.Library('foo', ['f1.c', 'f2.c', 'f3.c'])
-         env.Program('prog1.c')
-         env.Program('prog2.c')
-      </file>
-      <file name="prog1.c">
-      #include "inc.h"
-      </file>
-      <file name="prog2.c">
-      #include "inc.h"
-      </file>
-      <file name="f1.c">
-      #include "inc.h"
-      </file>
-      <file name="f2.c">
-      #include "inc.h"
-      </file>
-      <file name="f3.c">
-      #include "inc.h"
-      </file>
-      <file name="inc.h">
-      inc.h
-      </file>
-    </scons_example>
-
-    <para>
-
-    Then there can be a <emphasis>lot</emphasis> of repetition in the
-    <literal>--tree=</literal> output:
-
-    </para>
-
-    <scons_output example="tree2">
-      <scons_output_command>scons -Q --tree=all</scons_output_command>
-    </scons_output>
-
-    <para>
-
-    In a large configuration with many internal libraries
-    and include files,
-    this can very quickly lead to huge output trees.
-    To help make this more manageable,
-    a <literal>prune</literal> modifier may
-    be added to the option list,
-    in which case &SCons;
-    will print the name of a target that has
-    already been visited during the tree-printing
-    in <literal>[square brackets]</literal>
-    as an indication that the dependencies
-    of the target file may be found
-    by looking farther up the tree:
-
-    </para>
-
-    <scons_output example="tree2">
-      <scons_output_command>scons -Q --tree=prune</scons_output_command>
-    </scons_output>
-
-    <para>
-
-    Like the <literal>status</literal> keyword,
-    the <literal>prune</literal> argument by itself
-    is equivalent to <literal>--tree=all,prune</literal>.
-
-    </para>
-
-  </section>
-
-  <section>
-
-  <title>How is &SCons; Constructing the Command Lines It Executes?  the &debug-presub; Option</title>
-
-    <para>
-
-    Sometimes it's useful to look at the
-    pre-substitution string
-    that &SCons; uses to generate
-    the command lines it executes.
-    This can be done with the &debug-presub; option:
-
-    </para>
-
-    <scons_example name="presub">
-      <file name="SConstruct">
-         env = Environment(CPPPATH = ['.'])
-         env.Program('prog', 'prog.c')
-      </file>
-      <file name="prog.c">
-      prog.c
-      </file>
-    </scons_example>
-
-    <!--
-
-    Have to capture output here, otherwise the - -debug=presub output
-    shows the Python functions from the sconsdoc.py execution wrapper
-    used to generate this manual, not the underlying command-line strings.
-
-    <scons_output example="presub">
-      <scons_output_command>scons -Q - -debug=presub</scons_output_command>
-    </scons_output>
-
-    -->
-
-    <screen>
-      % <userinput>scons -Q --debug=presub</userinput>
-      Building prog.o with action:
-        $CC -o $TARGET -c $CFLAGS $CCFLAGS $_CCOMCOM $SOURCES
-      cc -o prog.o -c -I. prog.c
-      Building prog with action:
-        $SMART_LINKCOM
-      cc -o prog prog.o
-    </screen>
-
-  </section>
-
-  <section>
-
-  <title>Where is &SCons; Searching for Libraries?  the &debug-findlibs; Option</title>
-
-    <para>
-
-    To get some insight into what library names
-    &SCons; is searching for,
-    and in which directories it is searching,
-    Use the <literal>--debug=findlibs</literal> option.
-    Given the following input &SConstruct; file:
-
-    </para>
-
-    <scons_example name="findlibs">
-      <file name="SConstruct" printme="1">
-        env = Environment(LIBPATH = ['libs1', 'libs2'])
-        env.Program('prog.c', LIBS=['foo', 'bar'])
-      </file>
-      <file name="prog.c">
-      prog.c
-      </file>
-      <file name="libs1/libfoo.a">
-      libs1/libfoo.a
-      </file>
-      <file name="libs2/libbar.a">
-      libs2/libbar.a
-      </file>
-    </scons_example>
-
-    <para>
-
-    And the libraries <filename>libfoo.a</filename>
-    and <filename>libbar.a</filename>
-    in <filename>libs1</filename> and <filename>libs2</filename>,
-    respectively,
-    use of the <literal>--debug=findlibs</literal> option yields:
-
-    </para>
-
-    <scons_output example="findlibs">
-      <scons_output_command>scons -Q --debug=findlibs</scons_output_command>
-    </scons_output>
-
-  </section>
-
-  <!--
-
-  <section>
-
-  <title>What Implicit Dependencies Did the &SCons; Scanner find?  the &debug-includes; Option</title>
-
-    <para>
-
-    XXX explain the - - debug=includes option
-
-    </para>
-
-    <scons_example name="includes">
-      <file name="SConstruct" printme="1">
-        env = Environment(CPPPATH = ['inc1', 'inc2'])
-        env.Program('prog.c')
-      </file>
-      <file name="prog.c">
-      #include "file1.h"
-      #include "file2.h"
-      prog.c
-      </file>
-      <file name="inc1/file1.h">
-      inc1/file1.h
-      </file>
-      <file name="inc2/file2.h">
-      inc2/file2.h
-      </file>
-    </scons_example>
-
-    <scons_output example="includes">
-      <scons_output_command>scons -Q - - debug=includes prog</scons_output_command>
-    </scons_output>
-
-  </section>
-
-  -->
-
-  <section>
-
-  <title>Where is &SCons; Blowing Up?  the &debug-stacktrace; Option</title>
-
-    <para>
-
-    In general, &SCons; tries to keep its error
-    messages short and informative.
-    That means we usually try to avoid showing
-    the stack traces that are familiar
-    to experienced Python programmers,
-    since they usually contain much more
-    information than is useful to most people.
-
-    </para>
-
-    <para>
-
-    For example, the following &SConstruct; file:
-
-    </para>
-
-    <scons_example name="stacktrace">
-      <file name="SConstruct" printme="1">
-         Program('prog.c')
-      </file>
-    </scons_example>
-
-    <para>
-
-    Generates the following error if the
-    <filename>prog.c</filename> file
-    does not exist:
-
-    </para>
-
-    <scons_output example="stacktrace">
-      <scons_output_command>scons -Q</scons_output_command>
-    </scons_output>
-
-    <para>
-
-    In this case,
-    the error is pretty obvious.
-    But if it weren't,
-    and you wanted to try to get more information
-    about the error,
-    the &debug-stacktrace; option
-    would show you exactly where in the &SCons; source code
-    the problem occurs:
-
-    </para>
-
-    <scons_output example="stacktrace">
-      <scons_output_command>scons -Q --debug=stacktrace</scons_output_command>
-    </scons_output>
-
-    <para>
-
-    Of course, if you do need to dive into the &SCons; source code,
-    we'd like to know if, or how,
-    the error messages or troubleshooting options
-    could have been improved to avoid that.
-    Not everyone has the necessary time or
-    Python skill to dive into the source code,
-    and we'd like to improve &SCons;
-    for those people as well...
-
-    </para>
-
-  </section>
-
-  <section>
-
-  <title>How is &SCons; Making Its Decisions?  the &taskmastertrace; Option</title>
-
-    <para>
-
-    The internal &SCons; subsystem that handles walking
-    the dependency graph
-    and controls the decision-making about what to rebuild
-    is the <literal>Taskmaster</literal>.
-    &SCons; supports a <literal>--taskmastertrace</literal>
-    option that tells the Taskmaster to print
-    information about the children (dependencies)
-    of the various Nodes on its walk down the graph,
-    which specific dependent Nodes are being evaluated,
-    and in what order.
-
-    </para>
-
-    <para>
-
-    The <literal>--taskmastertrace</literal> option
-    takes as an argument the name of a file in
-    which to put the trace output,
-    with <filename>-</filename> (a single hyphen)
-    indicating that the trace messages
-    should be printed to the standard output:
-
-    </para>
-
-    <scons_example name="taskmastertrace">
-      <file name="SConstruct" printme="1">
-      env = Environment(CPPPATH = ['.'])
-      env.Program('prog.c')
-      </file>
-      <file name="prog.c">
-      #include "inc.h"
-      prog.c
-      </file>
-      <file name="inc.h">
-      #define   STRING  "one"
-      </file>
-    </scons_example>
-
-    <scons_output example="taskmastertrace" os="posix">
-      <scons_output_command>scons -Q --taskmastertrace=- prog</scons_output_command>
-    </scons_output>
-
-    <para>
-
-    The <literal>--taskmastertrace</literal> option
-    doesn't provide information about the actual
-    calculations involved in deciding if a file is up-to-date,
-    but it does show all of the dependencies
-    it knows about for each Node,
-    and the order in which those dependencies are evaluated.
-    This can be useful as an alternate way to determine
-    whether or not your &SCons; configuration,
-    or the implicit dependency scan,
-    has actually identified all the correct dependencies
-    you want it to.
-
-    </para>
-
-  </section>
-
-  <section>
-
-  <title>Watch &SCons; prepare targets for building: the &debug-prepare; Option</title>
-
-    <para>
-
-    Sometimes SCons doesn't build the target you want
-    and it's difficult to figure out why.  You can use
-    the <literal>--debug=prepare</literal> option
-    to see all the targets &SCons; is considering, whether
-    they are already up-to-date or not. The message is
-    printed before &SCons; decides whether to build the target.
-    </para>
-
-  </section>
-
-  <section>
-
-  <title>Why is a file disappearing?  the --debug=duplicate Option</title>
-
-    <para>
-
-    When using the &Duplicate; option to create variant dirs,
-    sometimes you may find files not getting copied to where you
-    expect (or not at all), or files mysteriously disappearing.  These
-    are usually because of a misconfiguration of some kind in the
-    SConstruct/SConscript, but they can be tricky to debug.  The
-    --debug=duplicate option shows each time a variant file is
-    unlinked and relinked from its source (or copied, depending on
-    settings), and also shows a message for removing "stale"
-    variant-dir files that no longer have a corresponding source file.
-    It also prints a line for each target that's removed just before
-    building, since that can also be mistaken for the same thing.
-
-    </para>
-
-  </section>
-
-  <!--
-
-
-  <section>
-
-  <title>Where Are My Build Bottlenecks?  the &profile; Option</title>
-
-    <para>
-
-    XXX explain the - - profile= option
-
-    </para>
-
-  </section>
-
-  -->
-
-  <!--
-
-  <section>
-  <title>Troubleshooting Shared Caching:  the &cache-debug; Option</title>
-
-    <para>
-
-    XXX describe the - - cache-debug option
-    XXX maybe point to the caching.in chapter?
-
-    </para>
-
-  </section>
-
-  -->