Update debug=action-timestamps

+ Rename to action-timestamps (from action_timestamps) for
  consistency with other compound word options.
+ Put manpage entry in alphabetical order.
+ Describe what option does and shorten it (refers to debug=time
  instead of duplicating it)
+ Change prints a bit (and tests to match)
+ Show scons version where added.
+ Slight adjustment to manpage introduction to debug options.

Along the way, fixes a lingering tag mismatch from an earlier
documentation PR.

Updates PR#3456

Signed-off-by: Mats Wichmann <mats@linux.com>

2 files changed, 21 insertions, 41 deletions

diff --git a/doc/man/scons.xml b/doc/man/scons.xml
index ae54e2e..e0f920d 100644
--- a/doc/man/scons.xml
+++ b/doc/man/scons.xml
@@ -686,19 +686,32 @@ option except for the way default targets are handled.
 When this option is used and no targets are specified on the command line,
 all default targets are built, whether or not they are below the current
 directory.</para>
-
   </listitem>
   </varlistentry>
+
   <varlistentry>
-  <term>--debug=<emphasis>type</emphasis></term>
+  <term>--debug=<replaceable>type</replaceable>[<replaceable>,type</replaceable>...]</term>
   <listitem>
 <para>Debug the build process.
-<emphasis>type[,type...]</emphasis>
-specifies what type of debugging. Multiple types may be specified,
-separated by commas. The following types are valid:</para>
+<emphasis>type</emphasis>
+specifies the kind of debugging info to emit.
+Multiple types may be specified, separated by commas.
+The following entries show the recognized types:</para>
+  </listitem>
+  </varlistentry>
 
+  <varlistentry>
+  <term>--debug=action-timestamps</term>
+  <listitem>
+<para>Prints additional time profiling information. For
+each command, shows the absolute start and end times.
+This may be useful in debugging parallel builds.
+Implies the <option>--debug=time</option> option.
+</para>
+<para>Since &scons; 3.1.</para>
   </listitem>
   </varlistentry>
+
   <varlistentry>
   <term>--debug=count</term>
   <listitem>
@@ -893,40 +906,6 @@ should take place in parallel.)
   </listitem>
   </varlistentry>
 
-<varlistentry>
-  <term>--debug=action_timestamps</term>
-  <listitem>
-    <para>Prints additional time profiling information:</para>
-    <itemizedlist>
-      <listitem>
-        <para>The time spent executing each individual build command</para>
-      </listitem>
-      <listitem>
-        <para>The total build time (time SCons ran from beginning to end)</para>
-      </listitem>
-      <listitem>
-        <para>The total time spent reading and executing SConscript files</para>
-      </listitem>
-      <listitem>
-        <para>The total time spent SCons itself spend running
-(that is, not counting reading and executing SConscript files)</para>
-      </listitem>
-      <listitem>
-        <para>The total time spent executing all build commands</para>
-      </listitem>
-      <listitem>
-        <para>The elapsed wall-clock time spent executing those build commands</para>
-      </listitem>
-      <listitem>
-        <para>The absolute start and end wall-clock time spent executing those build commands</para>
-      </listitem>
-      <listitem>
-        <para>The time spent processing each file passed to the <emphasis>SConscript()</emphasis> function</para>
-      </listitem>
-    </itemizedlist>
-  </listitem>
-</varlistentry>
-
   <varlistentry>
   <term>--diskcheck=<emphasis>types</emphasis></term>
   <listitem>
@@ -2278,10 +2257,10 @@ env.SomeTool(targets, sources)
 
 <refsect2 id='builder_methods'><title>Builder Methods</title>
 
-<para>You tell <program>scons</program> what to build
+<para>You tell <command>scons</command> what to build
 by calling Builders, functions which know to take a
 particular action when given files of a particular type
-to produce a particular result type. <program>scons</program>
+to produce a particular result type. <command>scons</command>
 defines a number of builders, and you can also write your own.
 Builders are attached to a &consenv; as methods,
 and the available builder methods are listed as
diff --git a/doc/user/depends.xml b/doc/user/depends.xml
index 5a78eb5..cd5094a 100644
--- a/doc/user/depends.xml
+++ b/doc/user/depends.xml
@@ -764,6 +764,7 @@ int main() { printf("Hello, world!\n"); }
     encounter them in older &SConscript; files.
 
     </para>
+  </section>
   
   <section>
   <title>Implicit Dependencies:  The &cv-CPPPATH; Construction Variable</title>