Merge commit 'upstream/2.1.0'

1 files changed, 44 insertions, 5 deletions

diff --git a/doc/user/troubleshoot.in b/doc/user/troubleshoot.in
index 97df351..615d677 100644
--- a/doc/user/troubleshoot.in
+++ b/doc/user/troubleshoot.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -34,7 +34,7 @@
   &SCons; is no different.
   This appendix contains a number of
   different ways in which you can
-  get some additional insight into &SCons' behavior.
+  get some additional insight into &SCons;' behavior.
 
   </para>
 
@@ -410,12 +410,12 @@
 
     <para>
 
-    The <literaL>--tree</literal> option only prints
+    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
+    the <literal>--tree</literal> option will only
     print the dependency graph for that file:
 
     </para>
@@ -722,7 +722,7 @@
 
     <para>
 
-    For example, the following &SConstruct file:
+    For example, the following &SConstruct; file:
 
     </para>
 
@@ -842,8 +842,47 @@
 
   </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>