Imported Upstream version 2.3.1upstream/2.3.1

1 files changed, 1284 insertions, 0 deletions

diff --git a/doc/man/scons-time.xml b/doc/man/scons-time.xml
new file mode 100644
index 0000000..026c24d
--- /dev/null
+++ b/doc/man/scons-time.xml
@@ -0,0 +1,1284 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- lifted from troff+man by doclifter -->
+<refentry id='sconstime1'
+          xmlns="http://www.scons.org/dbxsd/v1.0"
+          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+          xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd">
+<!--  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 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. -->
+
+<!--  doc/man/scons-time.xml  2014/03/02 14:18:15 garyo -->
+
+<!--  ES \- Example Start \- indents and turns off line fill -->
+<!--  EE \- Example End \- ends indent and turns line fill back on -->
+<!-- '\"========================================================================== -->
+<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -->
+<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -->
+<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -->
+<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -->
+<refmeta>
+<refentrytitle>SCONS-TIME</refentrytitle>
+<manvolnum>1</manvolnum>
+<refmiscinfo class='source'>March 2014</refmiscinfo>
+</refmeta>
+<refnamediv id='name'>
+<refname>scons-time</refname>
+<refpurpose>generate and display SCons timing information</refpurpose>
+</refnamediv>
+<refsynopsisdiv id='synopsis'>
+<cmdsynopsis>
+  <command>scons-time</command>    
+    <arg choice='plain'><replaceable>subcommand</replaceable></arg>
+    <arg choice='opt' rep='repeat'><replaceable>options</replaceable></arg>
+    <arg choice='opt' rep='repeat'><replaceable>arguments</replaceable></arg>
+</cmdsynopsis>
+</refsynopsisdiv>
+
+<!-- body begins here -->
+
+<refsect1 id='generating_timing_information'><title>Generating Timing Information</title>
+<para><emphasis role="bold">scons-time run</emphasis>
+[<option>-hnqv</option>]
+[<option>--aegis=</option><replaceable>PROJECT</replaceable>]
+[<option>-f </option><emphasis>FILE</emphasis>]
+[<option>--number=</option><replaceable>NUMBER</replaceable>]
+[<option>--outdir=</option><replaceable>OUTDIR</replaceable>]
+[<option>-p </option><emphasis>STRING</emphasis>]
+[<option>--python=</option><replaceable>PYTHON</replaceable>]
+[<option>-s </option><emphasis>DIR</emphasis>]
+[<option>--scons=</option><replaceable>SCONS</replaceable>]
+[<option>--svn=</option><replaceable>URL</replaceable>]
+[<emphasis>ARGUMENTS</emphasis>]</para>
+<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -->
+
+<refsect2 id='extracting_function_timings'><title>Extracting Function Timings</title>
+<para><emphasis role="bold">scons-time func</emphasis>
+[<option>-h</option>]
+[<option>--chdir=</option><replaceable>DIR</replaceable>]
+[<option>-f </option><emphasis>FILE</emphasis>]
+[<option>--fmt=</option><replaceable>FORMAT</replaceable>]
+[<option>--func=</option><replaceable>NAME</replaceable>]
+[<option>-p </option><emphasis>STRING</emphasis>]
+[<option>-t </option><emphasis>NUMBER</emphasis>]
+[<option>--title= TITLE</option>]
+[<emphasis>ARGUMENTS</emphasis>]</para>
+<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -->
+</refsect2>
+
+<refsect2 id='extracting_memory_statistics'><title>Extracting Memory Statistics</title>
+<para><emphasis role="bold">scons-time mem</emphasis>
+[<option>-h</option>]
+[<option>--chdir=</option><replaceable>DIR</replaceable>]
+[<option>-f </option><emphasis>FILE</emphasis>]
+[<option>--fmt=</option><replaceable>FORMAT</replaceable>]
+[<option>-p </option><emphasis>STRING</emphasis>]
+[<option>--stage=</option><replaceable>STAGE</replaceable>]
+[<option>-t </option><emphasis>NUMBER</emphasis>]
+[<option>--title=</option><replaceable>TITLE</replaceable>]
+[<emphasis>ARGUMENTS</emphasis>]</para>
+<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -->
+</refsect2>
+
+<refsect2 id='extracting_object_counts'><title>Extracting Object Counts</title>
+<para><emphasis role="bold">scons-time obj</emphasis>
+[<option>-h</option>]
+[<option>--chdir=</option><replaceable>DIR</replaceable>]
+[<option>-f </option><emphasis>FILE</emphasis>]
+[<option>--fmt=</option><replaceable>FORMAT</replaceable>]
+[<option>-p </option><emphasis>STRING</emphasis>]
+[<option>--stage=</option><replaceable>STAGE</replaceable>]
+[<option>-t </option><emphasis>NUMBER</emphasis>]
+[<option>--title=</option><replaceable>TITLE</replaceable>]
+[<emphasis>ARGUMENTS</emphasis>]</para>
+<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -->
+</refsect2>
+
+<refsect2 id='extracting_execution_times'><title>Extracting Execution Times</title>
+<para><emphasis role="bold">scons-time time</emphasis>
+[<option>-h</option>]
+[<option>--chdir=</option><replaceable>DIR</replaceable>]
+[<option>-f </option><emphasis>FILE</emphasis>]
+[<option>--fmt=</option><replaceable>FORMAT</replaceable>]
+[<option>-p </option><emphasis>STRING</emphasis>]
+[<option>-t </option><emphasis>NUMBER</emphasis>]
+[<option>--title=</option><replaceable>TITLE</replaceable>]
+[<option>--which=</option><replaceable>WHICH</replaceable>]
+[<emphasis>ARGUMENTS</emphasis>]</para>
+<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -->
+</refsect2>
+
+<refsect2 id='help_text'><title>Help Text</title>
+<para><emphasis role="bold">scons-time help</emphasis>
+<emphasis>SUBCOMMAND</emphasis>
+[...]</para>
+<!-- '\"========================================================================== -->
+</refsect2>
+</refsect1>
+
+<refsect1 id='description'><title>DESCRIPTION</title>
+<para>The 
+<command>scons-time</command>
+command runs an SCons configuration
+through a standard set of profiled timings
+and can extract and graph information from the
+resulting profiles and log files of those timings.
+The action to be performed by the
+<command>scons-time</command>
+script is specified
+by a subcommand, the first argument on the command line.
+See the
+<link linkend="subcommands">SUBCOMMANDS</link>
+section below for information about the operation
+of specific subcommands.</para>
+
+<para>The basic way to use
+<command>scons-time</command>
+is to run the
+<emphasis role="bold">scons-time run</emphasis>
+subcommand
+(possibly multiple times)
+to generate profile and log file output,
+and then use one of the other
+subcommands to display the results
+captured in the profiles and log files
+for a particular kind of information:
+function timings
+(the
+<emphasis role="bold">scons-time func</emphasis>
+subcommand),
+total memory used
+(the
+<emphasis role="bold">scons-time mem</emphasis>
+subcommand),
+object counts
+(the
+<emphasis role="bold">scons-time obj</emphasis>
+subcommand)
+and overall execution time
+(the
+<emphasis role="bold">scons-time time</emphasis>
+subcommand).
+Options exist to place and find the
+profiles and log files in separate directories,
+to generate the output in a format suitable
+for graphing with the
+<citerefentry><refentrytitle>gnuplot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+program,
+and so on.</para>
+
+<para>There are two basic ways the
+<emphasis role="bold">scons-time run</emphasis>
+subcommand
+is intended to be used
+to gather timing statistics
+for a configuration.
+One is to use the
+<option>--svn=</option>
+option to test a configuration against
+a list of revisions from the SCons Subversion repository.
+This will generate a profile and timing log file
+for every revision listed with the
+<option>--number=</option>
+option,
+and can be used to look at the
+impact of committed changes to the
+SCons code base on a particular
+configuration over time.</para>
+
+<para>The other way is to profile incremental changes to a
+local SCons code base during a development cycle--that is,
+to look at the performance impact of changes
+you're making in the local tree.
+In this mode,
+you run the
+<emphasis role="bold">scons-time run</emphasis>
+subcommand
+<emphasis>without</emphasis>
+the
+<option>--svn=</option>
+option,
+in which case it simply looks in the profile/log file output directory
+(the current directory by default)
+and automatically figures out the
+<emphasis>next</emphasis>
+run number for the output profile and log file.
+Used in this way,
+the development cycle goes something like:
+make a change to SCons;
+run
+<emphasis role="bold">scons-time run</emphasis>
+to profile it against a specific configuration;
+make another change to SCons;
+run
+<emphasis role="bold">scons-time run</emphasis>
+again to profile it;
+etc.</para>
+<!-- '\"========================================================================== -->
+</refsect1>
+
+<refsect1 id='options'><title>OPTIONS</title>
+<para>The
+<command>scons-time</command>
+command only supports a few global options:</para>
+<variablelist>
+  <varlistentry>
+  <term>-h, --help</term>
+  <listitem>
+<para>Displays the global help text and exits,
+identical to the
+<emphasis role="bold">scons-time help</emphasis>
+subcommand.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-V, --version</term>
+  <listitem>
+<para>Displays the
+<command>scons-time</command>
+version and exits.</para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>Most functionality is controlled by options
+to the individual subcommands.
+See the next section for information
+about individual subcommand options.</para>
+<!-- '\"========================================================================== -->
+</refsect1>
+
+<refsect1 id='subcommands'><title>SUBCOMMANDS</title>
+<para>The
+<command>scons-time</command>
+command supports the following
+individual subcommands.</para>
+<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -->
+
+<refsect2 id='the_func_subcommand'><title>The func Subcommand</title>
+<para><emphasis role="bold">scons-time func</emphasis>
+[<option>-h</option>]
+[<option>--chdir=</option><replaceable>DIR</replaceable>]
+[<option>-f </option><emphasis>FILE</emphasis>]
+[<option>--fmt=</option><replaceable>FORMAT</replaceable>]
+[<option>--func=</option><replaceable>NAME</replaceable>]
+[<option>-p </option><emphasis>STRING</emphasis>]
+[<option>-t </option><emphasis>NUMBER</emphasis>]
+[<option>--title= TITLE</option>]
+[<emphasis>ARGUMENTS</emphasis>]</para>
+
+<para>The
+<emphasis role="bold">scons-time func</emphasis>
+subcommand displays timing information
+for a specific Python function within SCons.
+By default, it extracts information about the
+<emphasis role="bold">_main</emphasis>()
+function,
+which includes the Python profiler timing
+for all of SCons.</para>
+
+<para>The
+<emphasis role="bold">scons-time func</emphasis>
+subcommand extracts function timing information
+from all the specified file arguments,
+which should be Python profiler output files.
+(Normally, these would be
+<emphasis role="bold">*.prof</emphasis>
+files generated by the
+<emphasis role="bold">scons-time run</emphasis>
+subcommand,
+but they can actually be generated
+by any Python profiler invocation.)
+All file name arguments will be
+globbed for on-disk files.</para>
+
+<para>If no arguments are specified,
+then function timing information
+will be extracted from all
+<emphasis role="bold">*.prof</emphasis>
+files,
+or the subset of them
+with a prefix specified by the
+<option>-p</option>
+option.</para>
+
+<para>Options include:</para>
+<variablelist>
+  <varlistentry>
+  <term>-C DIRECTORY, --chdir=DIRECTORY</term>
+  <listitem>
+<para>Changes to the specified
+<emphasis>DIRECTORY</emphasis>
+before looking for the specified files
+(or files that match the specified patterns).</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-f FILE, --file=FILE</term>
+  <listitem>
+<para>Reads configuration information from the specified
+<emphasis>FILE</emphasis>.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-fmt=FORMAT, --format=FORMAT</term>
+  <listitem>
+<para>Reports the output in the specified
+<emphasis>FORMAT</emphasis>.
+The formats currently supported are
+<emphasis role="bold">ascii</emphasis>
+(the default)
+and
+<emphasis role="bold">gnuplot</emphasis>.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--func=NAME</term>
+  <listitem>
+<para>Extracts timings for the specified function
+<emphasis>NAME</emphasis>.
+The default is to report cumulative timings for the
+<emphasis role="bold">_main</emphasis>()
+function,
+which contains the entire SCons run.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-h, --help</term>
+  <listitem>
+<para>Displays help text for the
+<emphasis role="bold">scons-time func</emphasis>
+subcommand.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-p STRING, --prefix=STRING</term>
+  <listitem>
+<para>Specifies the prefix string for profiles
+from which to extract function timing information.
+This will be used to search for profiles
+if no arguments are specified on the command line.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-t NUMBER, --tail=NUMBER</term>
+  <listitem>
+<para>Only extracts function timings from the last
+<emphasis>NUMBER</emphasis>
+files.</para>
+<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -->
+  </listitem>
+  </varlistentry>
+</variablelist>
+</refsect2>
+
+<refsect2 id='the_help_subcommand'><title>The help Subcommand</title>
+<para><emphasis role="bold">scons-time help</emphasis>
+<emphasis>SUBCOMMAND</emphasis>
+[...]
+The
+<emphasis role="bold">help</emphasis>
+subcommand prints help text for any
+other subcommands listed as later arguments on the command line.</para>
+<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -->
+</refsect2>
+
+<refsect2 id='the_mem_subcommand'><title>The mem Subcommand</title>
+<para><emphasis role="bold">scons-time mem</emphasis>
+[<option>-h</option>]
+[<option>--chdir=</option><replaceable>DIR</replaceable>]
+[<option>-f </option><emphasis>FILE</emphasis>]
+[<option>--fmt=</option><replaceable>FORMAT</replaceable>]
+[<option>-p </option><emphasis>STRING</emphasis>]
+[<option>--stage=</option><replaceable>STAGE</replaceable>]
+[<option>-t </option><emphasis>NUMBER</emphasis>]
+[<option>--title=</option><replaceable>TITLE</replaceable>]
+[<emphasis>ARGUMENTS</emphasis>]</para>
+
+<para>The
+<emphasis role="bold">scons-time mem</emphasis>
+subcommand displays how much memory SCons uses.</para>
+
+<para>The
+<emphasis role="bold">scons-time mem</emphasis>
+subcommand extracts memory use information
+from all the specified file arguments,
+which should be files containing output from
+running SCons with the
+<option>--debug=memory</option>
+option.
+(Normally, these would be
+<emphasis role="bold">*.log</emphasis>
+files generated by the
+<emphasis role="bold">scons-time run</emphasis>
+subcommand.)
+All file name arguments will be
+globbed for on-disk files.</para>
+
+<para>If no arguments are specified,
+then memory information
+will be extracted from all
+<emphasis role="bold">*.log</emphasis>
+files,
+or the subset of them
+with a prefix specified by the
+<option>-p</option>
+option.</para>
+
+<variablelist>
+  <varlistentry>
+  <term>-C DIR, --chdir=DIR</term>
+  <listitem>
+<para>Changes to the specified
+<emphasis>DIRECTORY</emphasis>
+before looking for the specified files
+(or files that match the specified patterns).</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-f FILE, --file=FILE</term>
+  <listitem>
+<para>Reads configuration information from the specified
+<emphasis>FILE</emphasis>.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-fmt=FORMAT, --format=FORMAT</term>
+  <listitem>
+<para>Reports the output in the specified
+<emphasis>FORMAT</emphasis>.
+The formats currently supported are
+<emphasis role="bold">ascii</emphasis>
+(the default)
+and
+<emphasis role="bold">gnuplot</emphasis>.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-h, --help</term>
+  <listitem>
+<para>Displays help text for the
+<emphasis role="bold">scons-time mem</emphasis>
+subcommand.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-p STRING, --prefix=STRING</term>
+  <listitem>
+<para>Specifies the prefix string for log files
+from which to extract memory usage information.
+This will be used to search for log files
+if no arguments are specified on the command line.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--stage=STAGE</term>
+  <listitem>
+<para>Prints the memory used at the end of the specified
+<emphasis>STAGE</emphasis>:
+<emphasis role="bold">pre-read</emphasis>
+(before the SConscript files are read),
+<emphasis role="bold">post-read ,</emphasis>
+(after the SConscript files are read),
+<emphasis role="bold">pre-build</emphasis>
+(before any targets are built)
+or
+<emphasis role="bold">post-build</emphasis>
+(after any targets are built).
+If no
+<option>--stage</option>
+option is specified,
+the default behavior is
+<emphasis role="bold">post-build</emphasis>,
+which reports the final amount of memory
+used by SCons during each run.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-t NUMBER, --tail=NUMBER</term>
+  <listitem>
+<para>Only reports memory statistics from the last
+<emphasis>NUMBER</emphasis>
+files.</para>
+<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -->
+  </listitem>
+  </varlistentry>
+</variablelist>
+</refsect2>
+
+<refsect2 id='the_obj_subcommand'><title>The obj Subcommand</title>
+<para><emphasis role="bold">scons-time obj</emphasis>
+[<option>-h</option>]
+[<option>--chdir=</option><replaceable>DIR</replaceable>]
+[<option>-f </option><emphasis>FILE</emphasis>]
+[<option>--fmt=</option><replaceable>FORMAT</replaceable>]
+[<option>-p </option><emphasis>STRING</emphasis>]
+[<option>--stage=</option><replaceable>STAGE</replaceable>]
+[<option>-t </option><emphasis>NUMBER</emphasis>]
+[<option>--title=</option><replaceable>TITLE</replaceable>]
+[<emphasis>ARGUMENTS</emphasis>]</para>
+
+<para>The
+<emphasis role="bold">scons-time obj</emphasis>
+subcommand displays how many objects of a specific named type
+are created by SCons.</para>
+
+<para>The
+<emphasis role="bold">scons-time obj</emphasis>
+subcommand extracts object counts
+from all the specified file arguments,
+which should be files containing output from
+running SCons with the
+<option>--debug=count</option>
+option.
+(Normally, these would be
+<emphasis role="bold">*.log</emphasis>
+files generated by the
+<emphasis role="bold">scons-time run</emphasis>
+subcommand.)
+All file name arguments will be
+globbed for on-disk files.</para>
+
+<para>If no arguments are specified,
+then object counts
+will be extracted from all
+<emphasis role="bold">*.log</emphasis>
+files,
+or the subset of them
+with a prefix specified by the
+<option>-p</option>
+option.</para>
+<variablelist>
+  <varlistentry>
+  <term>-C DIR, --chdir=DIR</term>
+  <listitem>
+<para>Changes to the specified
+<emphasis>DIRECTORY</emphasis>
+before looking for the specified files
+(or files that match the specified patterns).</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-f FILE, --file=FILE</term>
+  <listitem>
+<para>Reads configuration information from the specified
+<emphasis>FILE</emphasis>.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-fmt=FORMAT, --format=FORMAT</term>
+  <listitem>
+<para>Reports the output in the specified
+<emphasis>FORMAT</emphasis>.
+The formats currently supported are
+<emphasis role="bold">ascii</emphasis>
+(the default)
+and
+<emphasis role="bold">gnuplot</emphasis>.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-h, --help</term>
+  <listitem>
+<para>Displays help text for the
+<emphasis role="bold">scons-time obj</emphasis>
+subcommand.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-p STRING, --prefix=STRING</term>
+  <listitem>
+<para>Specifies the prefix string for log files
+from which to extract object counts.
+This will be used to search for log files
+if no arguments are specified on the command line.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--stage=STAGE</term>
+  <listitem>
+<para>Prints the object count at the end of the specified
+<emphasis>STAGE</emphasis>:
+<emphasis role="bold">pre-read</emphasis>
+(before the SConscript files are read),
+<emphasis role="bold">post-read ,</emphasis>
+(after the SConscript files are read),
+<emphasis role="bold">pre-build</emphasis>
+(before any targets are built)
+or
+<emphasis role="bold">post-build</emphasis>
+(after any targets are built).
+If no
+<option>--stage</option>
+option is specified,
+the default behavior is
+<emphasis role="bold">post-build</emphasis>,
+which reports the final object count during each run.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-t NUMBER, --tail=NUMBER</term>
+  <listitem>
+<para>Only reports object counts from the last
+<emphasis>NUMBER</emphasis>
+files.</para>
+<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -->
+  </listitem>
+  </varlistentry>
+</variablelist>
+</refsect2>
+
+<refsect2 id='the_run_subcommand'><title>The run Subcommand</title>
+<para><emphasis role="bold">scons-time run</emphasis>
+[<option>-hnqv</option>]
+[<option>--aegis=</option><replaceable>PROJECT</replaceable>]
+[<option>-f </option><emphasis>FILE</emphasis>]
+[<option>--number=</option><replaceable>NUMBER</replaceable>]
+[<option>--outdir=</option><replaceable>OUTDIR</replaceable>]
+[<option>-p </option><emphasis>STRING</emphasis>]
+[<option>--python=</option><replaceable>PYTHON</replaceable>]
+[<option>-s </option><emphasis>DIR</emphasis>]
+[<option>--scons=</option><replaceable>SCONS</replaceable>]
+[<option>--svn=</option><replaceable>URL</replaceable>]
+[<emphasis>ARGUMENTS</emphasis>]
+The
+<emphasis role="bold">scons-time run</emphasis>
+subcommand is the basic subcommand
+for profiling a specific configuration
+against a version of SCons.</para>
+
+<para>The configuration to be tested
+is specified as a list of files
+or directories that will be unpacked or copied
+into a temporary directory
+in which SCons will be invoked.
+The
+<emphasis role="bold">scons-time run</emphasis>
+subcommand understands file suffixes like
+<markup>.tar</markup>,
+<markup>.tar.gz</markup>,
+<markup>.tgz</markup>
+and
+<markup>.zip</markup>
+and will unpack their contents into a temporary directory.
+If more than one argument is specified,
+each one will be unpacked or copied
+into the temporary directory "on top of"
+the previous archives or directories,
+so the expectation is that multiple
+specified archives share the same directory layout.</para>
+
+<para>Once the file or directory arguments are unpacked or
+copied to the temporary directory,
+the
+<emphasis role="bold">scons-time run</emphasis>
+subcommand runs the
+requested version of SCons
+against the configuration
+three times:</para>
+<variablelist>
+  <varlistentry>
+  <term>Startup</term>
+  <listitem>
+<para>SCons is run with the
+<option>--help</option>
+option so that just the SConscript files are read,
+and then the default help text is printed.
+This profiles just the perceived "overhead" of starting up SCons
+and processing the SConscript files.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>Full build</term>
+  <listitem>
+<para>SCons is run to build everything specified in the configuration.
+Specific targets to be passed in on the command l ine
+may be specified by the
+<emphasis role="bold">targets</emphasis>
+keyword in a configuration file; see below for details.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>Rebuild</term>
+  <listitem>
+<para>SCons is run again on the same just-built directory.
+If the dependencies in the SCons configuration are correct,
+this should be an up-to-date, "do nothing" rebuild.</para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>Each invocation captures the output log file and a profile.</para>
+
+<para>The
+<emphasis role="bold">scons-time run</emphasis>
+subcommand supports the following options:</para>
+<variablelist>
+  <varlistentry>
+  <term>--aegis=PROJECT</term>
+  <listitem>
+<para>Specifies the Aegis
+<emphasis>PROJECT</emphasis>
+from which the
+version(s) of
+<emphasis role="bold">scons</emphasis>
+being timed will be extracted.
+When
+<option>--aegis</option>
+is specified, the
+<option>--number=</option><replaceable>NUMBER</replaceable>
+option specifies delta numbers
+that will be tested.
+Output from each invocation run will be placed in file
+names that match the Aegis delta numbers.
+If the
+<option>--number=</option>
+option is not specified,
+then the default behavior is to time the
+tip of the specified
+<emphasis>PROJECT</emphasis>.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-f FILE, --file=FILE</term>
+  <listitem>
+<para>Reads configuration information from the specified
+<emphasis>FILE</emphasis>.
+This often provides a more convenient way to specify and
+collect parameters associated with a specific timing configuration
+than specifying them on the command line.
+See the
+<link linkend="configuration_file">CONFIGURATION FILE</link>
+section below
+for information about the configuration file parameters.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-h, --help</term>
+  <listitem>
+<para>Displays help text for the
+<emphasis role="bold">scons-time run</emphasis>
+subcommand.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-n, --no-exec</term>
+  <listitem>
+<para>Do not execute commands,
+just printing the command-line equivalents of what would be executed.
+Note that the
+<command>scons-time</command>
+script actually executes its actions in Python,
+where possible,
+for portability.
+The commands displayed are UNIX
+<emphasis>equivalents</emphasis>
+of what it's doing.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--number=NUMBER</term>
+  <listitem>
+<para>Specifies the run number to be used in the names of
+the log files and profile outputs generated by this run.</para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>When used in conjunction with the
+<option>--aegis=</option><replaceable>PROJECT</replaceable>
+option,
+<emphasis>NUMBER</emphasis>
+specifies one or more comma-separated Aegis delta numbers
+that will be retrieved automatically from the specified Aegis
+<emphasis>PROJECT</emphasis>.</para>
+
+<para>When used in conjunction with the
+<option>--svn=</option><replaceable>URL</replaceable>
+option,
+<emphasis>NUMBER</emphasis>
+specifies one or more comma-separated Subversion revision numbers
+that will be retrieved automatically from the Subversion
+repository at the specified
+<emphasis>URL</emphasis>.
+Ranges of delta or revision numbers
+may be specified be separating two numbers
+with a hyphen
+(<emphasis role="bold">-</emphasis>).</para>
+
+<para>Example:</para>
+<literallayout class="monospaced">
+% scons-time run --svn=<ulink url='http://scons.tigris.org/svn/trunk'>http://scons.tigris.org/svn/trunk</ulink> --num=1247,1249-1252 .
+</literallayout> <!-- .fi -->
+<variablelist>
+  <varlistentry>
+  <term>-p STRING, --prefix=STRING</term>
+  <listitem>
+<para>Specifies the prefix string to be used for all of the log files
+and profiles generated by this run.
+The default is derived from the first
+specified argument:
+if the first argument is a directory,
+the default prefix is the name of the directory;
+if the first argument is an archive
+(tar or zip file),
+the default prefix is the the base name of the archive,
+that is, what remains after stripping the archive suffix
+(<markup>.tgz</markup>, <markup>.tar.gz</markup> or <markup>.zip</markup>).</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--python=PYTHON</term>
+  <listitem>
+<para>Specifies a path to the Python executable to be used
+for the timing runs.
+The default is to use the same Python executable that
+is running the
+<command>scons-time</command>
+command itself.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-q, --quiet</term>
+  <listitem>
+<para>Suppresses display of the command lines being executed.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-s DIR, --subdir=DIR</term>
+  <listitem>
+<para>Specifies the name of directory or subdirectory
+from which the commands should be executed.
+The default is XXX</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--scons=SCONS</term>
+  <listitem>
+<para>Specifies a path to the SCons script to be used
+for the timing runs.
+The default is XXX</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--svn=URL, --subversion=URL</term>
+  <listitem>
+<para>Specifies the
+<emphasis>URL</emphasis>
+of the Subversion repository from which the
+version(s) of
+<emphasis role="bold">scons</emphasis>
+being timed will be extracted.
+When
+<option>--svn</option>
+is specified, the
+<option>--number=</option><replaceable>NUMBER</replaceable>
+option specifies revision numbers
+that will be tested.
+Output from each invocation run will be placed in file
+names that match the Subversion revision numbers.
+If the
+<option>--number=</option>
+option is not specified,
+then the default behavior is to time the
+<emphasis role="bold">HEAD</emphasis>
+of the specified
+<emphasis>URL</emphasis>.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-v, --verbose</term>
+  <listitem>
+<para>Displays the output from individual commands to the screen
+(in addition to capturing the output in log files).</para>
+<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -->
+  </listitem>
+  </varlistentry>
+</variablelist>
+</refsect2>
+
+<refsect2 id='the_time_subcommand'><title>The time Subcommand</title>
+<para><emphasis role="bold">scons-time time</emphasis>
+[<option>-h</option>]
+[<option>--chdir=</option><replaceable>DIR</replaceable>]
+[<option>-f </option><emphasis>FILE</emphasis>]
+[<option>--fmt=</option><replaceable>FORMAT</replaceable>]
+[<option>-p </option><emphasis>STRING</emphasis>]
+[<option>-t </option><emphasis>NUMBER</emphasis>]
+[<option>--title=</option><replaceable>TITLE</replaceable>]
+[<option>--which=</option><replaceable>WHICH</replaceable>]
+[<emphasis>ARGUMENTS</emphasis>]</para>
+
+<para>The
+<emphasis role="bold">scons-time time</emphasis>
+subcommand displays SCons execution times
+as reported by the
+<userinput>scons --debug=time</userinput>
+option.</para>
+
+<para>The
+<emphasis role="bold">scons-time time</emphasis>
+subcommand extracts SCons timing
+from all the specified file arguments,
+which should be files containing output from
+running SCons with the
+<option>--debug=time</option>
+option.
+(Normally, these would be
+<emphasis role="bold">*.log</emphasis>
+files generated by the
+<emphasis role="bold">scons-time run</emphasis>
+subcommand.)
+All file name arguments will be
+globbed for on-disk files.</para>
+
+<para>If no arguments are specified,
+then execution timings
+will be extracted from all
+<emphasis role="bold">*.log</emphasis>
+files,
+or the subset of them
+with a prefix specified by the
+<option>-p</option>
+option.</para>
+<variablelist>
+  <varlistentry>
+  <term>-C DIR, --chdir=DIR</term>
+  <listitem>
+<para>Changes to the specified
+<emphasis>DIRECTORY</emphasis>
+before looking for the specified files
+(or files that match the specified patterns).</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-f FILE, --file=FILE</term>
+  <listitem>
+<para>Reads configuration information from the specified
+<emphasis>FILE</emphasis>.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-fmt=FORMAT, --format=FORMAT</term>
+  <listitem>
+<para>Reports the output in the specified
+<emphasis>FORMAT</emphasis>.
+The formats currently supported are
+<emphasis role="bold">ascii</emphasis>
+(the default)
+and
+<emphasis role="bold">gnuplot</emphasis>.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-h, --help</term>
+  <listitem>
+<para>Displays help text for the
+<emphasis role="bold">scons-time time</emphasis>
+subcommand.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-p STRING, --prefix=STRING</term>
+  <listitem>
+<para>Specifies the prefix string for log files
+from which to extract execution timings.
+This will be used to search for log files
+if no arguments are specified on the command line.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-t NUMBER, --tail=NUMBER</term>
+  <listitem>
+<para>Only reports object counts from the last
+<emphasis>NUMBER</emphasis>
+files.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--which=WHICH</term>
+  <listitem>
+<para>Prints the execution time for the specified
+<emphasis>WHICH</emphasis>
+value:
+<emphasis role="bold">total</emphasis>
+(the total execution time),
+<emphasis role="bold">SConscripts</emphasis>
+(total execution time for the SConscript files themselves),
+<emphasis role="bold">SCons</emphasis>
+(exectuion time in SCons code itself)
+or
+<emphasis role="bold">commands</emphasis>
+(execution time of the commands and other actions
+used to build targets).
+If no
+<option>--which</option>
+option is specified,
+the default behavior is
+<emphasis role="bold">total</emphasis>,
+which reports the total execution time for each run.</para>
+<!-- '\"========================================================================== -->
+  </listitem>
+  </varlistentry>
+</variablelist>
+</refsect2>
+</refsect1>
+
+<refsect1 id='configuration_file'><title>CONFIGURATION FILE</title>
+<para>Various
+<command>scons-time</command>
+subcommands can read information from a specified
+configuration file when passed the
+<option>-f</option>
+or
+<option>--file</option>
+options.
+The configuration file is actually executed as a Python script.
+Setting Python variables in the configuration file
+controls the behavior of the
+<command>scons-time</command>
+script more conveniently than having to specify
+command-line options or arguments for every run,
+and provides a handy way to "shrink-wrap"
+the necessary information for producing (and reporting)
+consistent timing runs for a given configuration.</para>
+<variablelist>
+  <varlistentry>
+  <term><emphasis role="bold">aegis</emphasis></term>
+  <listitem>
+<para>The Aegis executable for extracting deltas.
+The default is simply
+<emphasis role="bold">aegis</emphasis>.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis role="bold">aegis_project</emphasis></term>
+  <listitem>
+<para>The Aegis project from which deltas should be extracted.
+The default is whatever is specified
+with the
+<option>--aegis=</option>
+command-line option.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis role="bold">archive_list</emphasis></term>
+  <listitem>
+<para>A list of archives (files or directories)
+that will be copied to the temporary directory
+in which SCons will be invoked.
+<markup>.tar</markup>,
+<markup>.tar.gz</markup>,
+<markup>.tgz</markup>
+and
+<markup>.zip</markup>
+files will have their contents unpacked in
+the temporary directory.
+Directory trees and files will be copied as-is.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis role="bold">initial_commands</emphasis></term>
+  <listitem>
+<para>A list of commands that will be executed
+before the actual timed
+<emphasis role="bold">scons</emphasis>
+runs.
+This can be used for commands that are necessary
+to prepare the source tree-for example,
+creating a configuration file
+that should not be part of the timed run.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis role="bold">key_location</emphasis></term>
+  <listitem>
+<para>The location of the key on Gnuplot graphing information
+generated with the
+<option>--format=gnuplot</option>
+option.
+The default is
+<emphasis role="bold">bottom left</emphasis>.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis role="bold">prefix</emphasis></term>
+  <listitem>
+<para>The file name prefix to be used when
+running or extracting timing for this configuration.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis role="bold">python</emphasis></term>
+  <listitem>
+<para>The path name of the Python executable
+to be used when running or extracting information
+for this configuration.
+The default is the same version of Python
+used to run the SCons</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis role="bold">scons</emphasis></term>
+  <listitem>
+<para>The path name of the SCons script to be used
+when running or extracting information
+for this configuration.
+The default is simply
+<emphasis role="bold">scons</emphasis>.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis role="bold">scons_flags</emphasis></term>
+  <listitem>
+<para>The
+<emphasis role="bold">scons</emphasis>
+flags used when running SCons to collect timing information.
+The default value is
+<option>--debug=count --debug=memory --debug=time --debug=memoizer</option>.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis role="bold">scons_lib_dir</emphasis></term>
+  <term><emphasis role="bold">scons_wrapper</emphasis></term>
+  <term><emphasis role="bold">startup_targets</emphasis></term>
+  <term><emphasis role="bold">subdir</emphasis></term>
+  <listitem>
+<para>The subdirectory of the project into which the
+<command>scons-time</command>
+script should change
+before executing the SCons commands to time.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis role="bold">subversion_url</emphasis></term>
+  <listitem>
+<para>The Subversion URL from</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis role="bold">svn</emphasis></term>
+  <listitem>
+<para>The subversion executable used to
+check out revisions of SCons to be timed.
+The default is simple
+<emphasis role="bold">svn</emphasis>.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis role="bold">svn_co_flag</emphasis></term>
+  <term><emphasis role="bold">tar</emphasis></term>
+  <term><emphasis role="bold">targets</emphasis></term>
+  <listitem>
+<para>A string containing the targets that should be added to
+the command line of every timed
+<emphasis role="bold">scons</emphasis>
+run.
+This can be used to restrict what's being timed to a
+subset of the full build for the configuration.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis role="bold">targets0</emphasis></term>
+  <term><emphasis role="bold">targets1</emphasis></term>
+  <term><emphasis role="bold">targets2</emphasis></term>
+  <term><emphasis role="bold">title</emphasis></term>
+  <term><emphasis role="bold">unzip</emphasis></term>
+  <term><emphasis role="bold">verbose</emphasis></term>
+  <term><emphasis role="bold">vertical_bars</emphasis></term>
+  <listitem>
+<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -->
+<para></para> <!-- FIXME: blank list item -->
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<refsect2 id='example'><title>Example</title>
+<para>Here is an example
+<command>scons-time</command>
+configuration file
+for a hypothetical sample project:</para>
+
+<literallayout class="monospaced">
+# The project doesn't use SCons natively (yet), so we're
+# timing a separate set of SConscript files that we lay
+# on top of the vanilla unpacked project tarball.
+arguments = ['project-1.2.tgz', 'project-SConscripts.tar']
+
+# The subdirectory name contains the project version number,
+# so tell scons-time to chdir there before building.
+subdir = 'project-1.2'
+
+# Set the prefix so output log files and profiles are named:
+#     project-000-[012].{log,prof}
+#     project-001-[012].{log,prof}
+# etc.
+prefix = 'project'
+
+# The SConscript files being tested don't do any SConf
+# configuration, so run their normal ./configure script
+# before we invoke SCons.
+initial_commands = [
+    './configure',
+]
+
+# Only time building the bin/project executable.
+targets = 'bin/project'
+
+# Time against SCons revisions of the branches/core branch
+subversion_url = '<ulink url='http://scons.tigris.org/svn/scons/branches/core'>http://scons.tigris.org/svn/scons/branches/core</ulink>'
+</literallayout> <!-- .fi -->
+<!-- '\"========================================================================== -->
+</refsect2>
+</refsect1>
+
+<refsect1 id='environment'><title>ENVIRONMENT</title>
+<para>The
+<command>scons-time</command>
+script uses the following environment variables:</para>
+<variablelist>
+  <varlistentry>
+  <term><emphasis role="bold">PRESERVE</emphasis></term>
+  <listitem>
+<para>If this value is set,
+the
+<command>scons-time</command>
+script will
+<emphasis>not</emphasis>
+remove the temporary directory or directories
+in which it builds the specified configuration
+or downloads a specific version of SCons.</para>
+<!-- '\"========================================================================== -->
+  </listitem>
+  </varlistentry>
+</variablelist>
+</refsect1>
+
+<refsect1 id='see_also'><title>SEE ALSO</title>
+<para><citerefentry><refentrytitle>gnuplot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+<citerefentry><refentrytitle>scons</refentrytitle><manvolnum>1</manvolnum></citerefentry></para>
+
+</refsect1>
+
+<refsect1 id='authors'><title>AUTHORS</title>
+<para>Steven Knight &lt;knight at baldmt dot com&gt;</para>
+</refsect1>
+</refentry>
+