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>

5 files changed, 30 insertions, 51 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>
diff --git a/src/engine/SCons/Script/Main.py b/src/engine/SCons/Script/Main.py
index 58dbf64..238a828 100644
--- a/src/engine/SCons/Script/Main.py
+++ b/src/engine/SCons/Script/Main.py
@@ -211,10 +211,9 @@ class BuildTask(SCons.Taskmaster.OutOfDateTask):
             last_command_end = finish_time
             cumulative_command_time = cumulative_command_time+finish_time-start_time
             if print_action_timestamps:
-                sys.stdout.write("Command execution start time: %s: %f seconds\n"%(str(self.node), start_time))
+                sys.stdout.write("Command execution start timestamp: %s: %f\n"%(str(self.node), start_time))
+                sys.stdout.write("Command execution end timestamp: %s: %f\n"%(str(self.node), finish_time))
             sys.stdout.write("Command execution time: %s: %f seconds\n"%(str(self.node), finish_time-start_time))
-            if print_action_timestamps:
-                sys.stdout.write("Command execution stop time: %s: %f seconds\n"%(str(self.node), finish_time))
 
     def do_failed(self, status=2):
         _BuildFailures.append(self.exception[1])
@@ -679,7 +678,7 @@ def _set_debug_values(options):
         options.tree_printers.append(TreePrinter(status=True))
     if "time" in debug_values:
         print_time = 1
-    if "action_timestamps" in debug_values:
+    if "action-timestamps" in debug_values:
         print_time = 1
         print_action_timestamps = 1
     if "tree" in debug_values:
diff --git a/src/engine/SCons/Script/SConsOptions.py b/src/engine/SCons/Script/SConsOptions.py
index 7b5d523..66c7239 100644
--- a/src/engine/SCons/Script/SConsOptions.py
+++ b/src/engine/SCons/Script/SConsOptions.py
@@ -622,7 +622,7 @@ def Parser(version):
     debug_options = ["count", "duplicate", "explain", "findlibs",
                      "includes", "memoizer", "memory", "objects",
                      "pdb", "prepare", "presub", "stacktrace",
-                     "time", "action_timestamps"]
+                     "time", "action-timestamps"]
 
     def opt_debug(option, opt, value__, parser,
                   debug_options=debug_options,
diff --git a/test/option/debug-action-timestamps.py b/test/option/debug-action-timestamps.py
index 0277516..059cfdf 100644
--- a/test/option/debug-action-timestamps.py
+++ b/test/option/debug-action-timestamps.py
@@ -34,13 +34,13 @@ def setup_fixtures():
     test.file_fixture('../fixture/SConstruct_test_main.py', 'SConstruct')
 
 def test_help_function():
-    # Before anything else, make sure we get valid --debug=action_timestamps results
+    # Before anything else, make sure we get valid --debug=action-timestamps results
     # when just running the help option.
-    test.run(arguments = "-h --debug=action_timestamps")
+    test.run(arguments = "-h --debug=action-timestamps")
     
 def build():
     # Execute build
-    test.run(arguments='--debug=action_timestamps')
+    test.run(arguments='--debug=action-timestamps')
     build_output = test.stdout()
     return build_output
 
@@ -84,8 +84,8 @@ def test_correctness_of_timestamps(build_output):
 
 debug_time_patterns = [
     r'Command execution time: (.*): (\d+\.\d+) seconds',
-    r'Command execution start time: (.*): (\d+\.\d+) seconds',
-    r'Command execution stop time: (.*): (\d+\.\d+) seconds'
+    r'Command execution start timestamp: (.*): (\d+\.\d+)',
+    r'Command execution end timestamp: (.*): (\d+\.\d+)'
 ]
 
 test = TestSCons.TestSCons()