Add a man page.

4 files changed, 984 insertions, 0 deletions

diff --git a/doc/man/.aeignore b/doc/man/.aeignore
new file mode 100644
index 0000000..872e8be
--- /dev/null
+++ b/doc/man/.aeignore
@@ -0,0 +1,3 @@
+*,D
+.*.swp
+.consign
diff --git a/doc/man/desc.sgml b/doc/man/desc.sgml
new file mode 100644
index 0000000..da2961e
--- /dev/null
+++ b/doc/man/desc.sgml
@@ -0,0 +1,194 @@
+<!--
+
+  Copyright 2001 Steven Knight
+
+-- >
+
+ <para>
+
+   The &scons; utility builds software (or other files)
+   by determining which component pieces must be rebuilt
+   and executing the necessary commands to rebuild them.
+
+ </para>
+
+ <para>
+
+   By default, &scons; reads configuration information from the
+   file named  <filename>SConstruct</filename> in the current
+   directory.  An alternate file name may be specified via the
+    <option>-f</option> option.  If the alternate file is not in
+   the local directory, &scons; will internally change its working
+   directory (chdir) to the directory containing the file.
+
+ </para>
+
+ <para>
+
+   The configuration file specifies the files to be built, and
+   (optionally) the rules to build those files.  Reasonable default
+   rules exist for building common software components (executable
+   programs, object files, libraries), so that for simple software
+   projects, only the target and input files need be specified.
+
+    <!--
+   See
+   .IR scconsfile (5)
+   for information about the contents of
+   &scons;
+   configuration files.
+   -- >
+
+ </para>
+
+ <para>
+
+   &scons; can scan known input files automatically for dependency
+   information (for example,  <literal>#include</literal> statements
+   in C or C++ files) and will rebuild dependent files appropriately
+   whenever any "included" input file changes. &scons; supports the
+   ability to define new scanners for unknown input file types.
+
+ </para>
+
+ <para>
+
+   &scons; is normally executed in a top-level directory containing a
+   &SConstruct; file, specifying the target or targets to be built as
+   command-line arguments.  The command
+
+ </para>
+
+	<screen>
+	scons .
+	</screen>
+
+ <para>
+
+   will build all target files in or below the current directory
+   ( <filename>.</filename>).
+
+ </para>
+
+	<screen>
+	scons /
+	</screen>
+
+ <para>
+
+   will build all target files in or below the root directory (i.e.,
+   all files).  Specific targets may be supplied:
+
+ </para>
+
+	<screen>
+	scons foo bar
+	</screen>
+
+ <para>
+
+   Targets may be omitted from the command line,
+   in which case the targets specified
+   in the configuration file(s) as
+    <function>Default</function>
+   targets will be built:
+
+ </para>
+
+	<screen>
+	scons
+	</screen>
+
+ <para>
+
+   Specifying "cleanup" targets in configuration files is not
+   necessary.  The  <option>-c</option> flag removes all files
+   necessary to build the specified target:
+
+ </para>
+
+	<screen>
+	# removes all target files
+	scons -c .
+
+	# removes all target files under the specified subdirectories
+	scons -c build export
+	</screen>
+
+ <para>
+
+   A subset of a hierarchical tree may be built by:
+
+ </para>
+
+    <orderedlist>
+    <listitem>
+	<para>
+	remaining at the top-level directory (where the &SConstruct;
+	file lives) and specifying the subdirectory as the target to be
+	built:
+   	 </para>
+	<screen>
+	scons src/subdir
+	</screen>
+    </listitem>
+    <listitem>
+	<para>
+	changing directory and invoking sccons with the
+	<option>-u</option> option, which traverses up the directory
+	hierarchy until it finds the &SConstruct; file, and then builds
+	targets relatively to the current subdirectory:
+	</para>
+	<screen>
+	cd src/subdir
+	scons -u .
+	</screen>
+    </listitem>
+    </orderedlist>
+
+ <para>
+
+   &scons; supports building multiple targets in parallel via a
+    <option>-j</option> option that takes, as its argument, the number
+   of simultaneous tasks that may be spawned:
+
+ </para>
+
+	<screen>
+	# build four targets in parallel
+	&scons; -j 4
+	</screen>
+
+
+ <para>
+
+   Values of variables to be passed to the configuration file(s)
+   may be specified on the command line:
+
+ </para>
+
+	<screen>
+	&scons; debug=1 .
+	</screen>
+
+ <para>
+
+   These variables can be used in the configuration file(s) to modify
+   the build in any way.
+
+ </para>
+
+ <para>
+
+   &scons; can maintain a cache of target (derived) files that can
+   be shared between multiple builds.  When caching is enabled in a
+   configuration file, any target files built by &scons; will be copied
+   to the cache.  If an up-to-date target file is found in the cache, it
+   will be retrieved from the cache instead of being rebuilt locally.
+   Caching behavior may be disabled and controlled in other ways by the
+   <option>--cache-force</option>, <option>--cache-disable</option>,
+   and <option>--cache-show</option> command-line options.  The
+   <option>--random</option> is useful whenever multiple builds may be
+   trying to update the cache simultaneously.
+
+ </para>
diff --git a/doc/man/main.sgml b/doc/man/main.sgml
new file mode 100644
index 0000000..5bac0f0
--- /dev/null
+++ b/doc/man/main.sgml
@@ -0,0 +1,103 @@
+<!--
+
+  Copyright 2001 Steven Knight
+
+-->
+
+<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"
+[
+
+    <!ENTITY % version SYSTEM "../version.sgml">
+    %version;
+
+    <!ENTITY % scons SYSTEM "../scons.mod">
+    %scons;
+
+    <!ENTITY desc SYSTEM "desc.sgml">
+    <!ENTITY options SYSTEM "options.sgml">
+]>
+
+<refentry id="scons">
+
+  <!--
+  <docinfo>
+    <title>SCons Design version &build_version;</title>
+
+    <author>
+      <firstname>Steven</firstname>
+      <surname>Knight</surname>
+    </author>
+
+    <edition>Revision &build_revision; (&build_date;)</edition>
+
+    <pubdate>2001</pubdate>
+
+    <copyright>
+      <year>2001</year>
+      <holder>Steven Knight</holder>
+    </copyright>
+
+    <legalnotice>
+      &copyright;
+    </legalnotice>
+
+    <releaseinfo>version &build_version;</releaseinfo>
+
+  </docinfo>
+  -->
+
+  <refmeta>
+    <refentrytitle>scons</refentrytitle>
+    <manvolnum>1</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>scons</refname>
+    <refpurpose>software constructor</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <cmdsynopsis>
+      <command>scons</command>
+      <arg choice="opt" rep="repeat">
+        <option>OPTION</option>
+      </arg>
+      <arg choice="opt" rep="repeat">
+        name=value
+      </arg>
+      <arg choice="opt" rep="repeat">
+        target
+      </arg>
+    </cmdsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+    &desc;
+  </refsect1>
+
+  <refsect1>
+    <title>Options</title>
+    &options;
+  </refsect1>
+
+  <refsect1>
+    <title>See Also</title>
+    <para>
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Bugs</title>
+    <para>
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Author</title>
+    <para>
+      Steven Knight
+    </para>
+  </refsect1>
+
+</refentry>
diff --git a/doc/man/options.sgml b/doc/man/options.sgml
new file mode 100644
index 0000000..2b824b5
--- /dev/null
+++ b/doc/man/options.sgml
@@ -0,0 +1,684 @@
+<!--
+
+  Copyright 2001 Steven Knight
+
+-- >
+
+<para>
+
+  In general, &scons; supports the same command-line options as GNU
+  &Make;, and many of those supported by &Cons;.
+
+</para>
+
+<variablelist>
+
+  <varlistentry>
+    <term>
+      <option>-b</option>
+    </term>
+    <listitem>
+      <para>
+
+        Ignored for compatibility with non-GNU versions of
+	<application>make</application>.
+
+      </para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term>
+      <option>-c</option>,
+      <option>--clean</option>,
+      <option>--remove</option>
+    </term>
+    <listitem>
+      <para>
+
+        Clean up by removing all target files for which a construction
+        command is specified.
+
+      </para>
+    </listitem>
+  </varlistentry>
+
+ <!--
+
+  <varlistentry>
+    <term>
+      <option>- -cache-disable</option>,
+      <option>- -no-cache</option>
+    </term>
+    <listitem>
+      <para>
+
+        Disable caching.  Will neither retrieve files from cache nor flush
+        files to cache.  Has no effect if use of caching is not specified
+        in a configuration file.
+
+      </para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term>
+     <option>- -cache-force</option>,
+     <option>- -cache-populate</option>
+    </term>
+    <listitem>
+      <para>
+
+        Populate a cache by forcing any already-existing up-to-date
+        target files to the cache, in addition to files built by this
+        invocation.  This is useful to populate a new cache with
+        appropriate target files, or to make available in the cache
+        any target files recently built with caching disabled via the
+        <option>- -cache-disable</option> option.
+
+      </para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term>
+      <option>- -cache-show</option>
+    </term>
+    <listitem>
+      <para>
+
+        When retrieving a target file from a cache, show the command
+        that would have been executed to build the file.  This produces
+        consistent output for build logs, regardless of whether a target
+        file was rebuilt or retrieved from cache.
+
+      </para>
+    </listitem>
+  </varlistentry>
+
+ -->
+
+  <varlistentry>
+    <term>
+      <option>-C</option> <replaceable>directory</replaceable>,
+      <option>--directory=</option><replaceable>directory</replaceable>
+    </term>
+    <listitem>
+      <para>
+
+        Change to the specified <replaceable>directory</replaceable>
+        before reading <filename>SConstruct</filename> or doing
+        anything else.  Multiple <option>-C</option> options are
+        interpreted relative to the previous one.  (This is nearly
+        equivalent to <literal>-f directory/SConstruct</literal>,
+        except that it will search for <filename>SConstruct</filename>,
+        <filename>Sconstruct</filename>, or
+        <filename>sconstruct</filename> in the directory.)
+
+      </para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term>
+     <option>-d</option>
+    </term>
+    <listitem>
+      <para>
+
+        Display dependencies while building target files.  Useful for
+        figuring out why a specific file is being rebuilt, as well as
+        general debugging of the build process.
+
+      </para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term>
+     <option>--debug</option>=<replaceable>flags</replaceable>
+    </term>
+    <listitem>
+      <para>
+
+        Print debugging information. ???
+
+      </para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term> <option>-e</option>,
+     <option>--environment-overrides</option>
+    </term>
+    <listitem>
+      <para>
+
+        Variables from the execution environment override construction
+        variables from the configuration files.
+
+      </para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term>
+      <option>-f</option> <replaceable>file</replaceable>,
+      <option>--file</option>=<replaceable>file</replaceable>,
+      <option>--makefile</option>=<replaceable>file</replaceable>,
+      <option>--sconstruct</option>=<replaceable>file</replaceable>
+    </term>
+    <listitem>
+      <para>
+
+        Use <replaceable>file</replaceable> as the initial configuration
+        file.  If <replaceable>file</replaceable> is in another directory,
+        &scons; will change to that directory before building targets.
+
+      </para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term>
+      <option>-h</option>,
+      <option>--help</option>
+    </term>
+    <listitem>
+      <para>
+
+        Print command-line help message and exit.
+
+      </para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term>
+      <option>-H</option>,
+      <option>--help-local</option>,
+      <option>--local-help</option>
+    </term>
+    <listitem>
+      <para>
+
+        Display a local help message for this build, if one is defined in
+        the configuration file(s).
+
+      </para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term>
+      <option>-i</option>,
+      <option>--ignore-errors</option>,
+    </term>
+    <listitem>
+      <para>
+
+        Ignore all errors from commands executed to rebuild files.
+
+      </para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term>
+      <option>-I</option> <replaceable>directory</replaceable>,
+      <option>--include-dir</option>=<replaceable>directory</replaceable>
+    </term>
+    <listitem>
+      <para>
+
+        Specifies a <replaceable>directory</replaceable> to search for
+        imported Python modules.  If several <option>-I</option> options
+        are used, the directories are searched in the order specified.
+
+      </para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term>
+      <option>-j</option> <replaceable>N</replaceable>,
+      <option>--jobs</option>=<replaceable>N</replaceable>
+    </term>
+    <listitem>
+      <para>
+
+        Specifies the number of jobs (commands) to run simultaneously.
+	If there is more than one <option>-j</option> option,
+	the last one is effective.
+	<!--
+	??? If the <option>-j</option> option
+	is specified without an argument,
+	&scons; will not limit the number of
+	simultaneous jobs.
+	-->
+
+      </para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term>
+      <option>-k</option>,
+      <option>--keep-going</option>,
+    </term>
+    <listitem>
+      <para>
+
+        Continue as much as possible after an error.  The target that
+        failed and those that depend on it will not be remade, but other
+        targets specified on the command line will still be processed.
+
+      </para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term>
+      <option>-l</option>,
+      <option>--load-average</option>=<replaceable>N</replaceable>,
+      <option>--max-load</option>=<replaceable>N</replaceable>
+    </term>
+    <listitem>
+      <para>
+
+	No new jobs (commands) will be started if
+	there are other jobs running and the system load
+	average is at least <replaceable>N</replaceable>
+	(a floating-point number).
+
+	<!--
+        ???
+	With no argument, removes a previous load limit.
+	-->
+
+      </para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term>
+      <option>--list-derived</option>
+    </term>
+    <listitem>
+      <para>
+
+        List derived files (targets, dependencies) that would be built,
+        but do not build them.
+	[XXX This can probably go away with the right
+	combination of other options.  Revisit this issue.]
+
+      </para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term>
+      <option>--list-actions</option>
+    </term>
+    <listitem>
+      <para>
+
+        List derived files that would be built, with the actions
+        (commands) that build them.  Does not build the files.
+	[XXX This can probably go away with the right
+	combination of other options.  Revisit this issue.]
+
+      </para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term>
+      <option>--list-where</option>
+    </term>
+    <listitem>
+      <para>
+
+        List derived files that would be built, plus where the file is
+        defined (file name and line number).  Does not build the files.
+	[XXX This can probably go away with the right
+	combination of other options.  Revisit this issue.]
+
+      </para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term>
+      <option>-m</option>
+    </term>
+    <listitem>
+      <para>
+
+        Ignored for compatibility with non-GNU versions of
+	<application>make</application>.
+
+      </para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term>
+      <option>-n</option>,
+      <option>--just-print</option>,
+      <option>--dry-run</option>,
+      <option>--recon</option>
+    </term>
+    <listitem>
+      <para>
+
+        No execute.  Print the commands that would be executed to build
+        any out-of-date target files, but do not execute the commands.
+
+      </para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term>
+      <option>-o</option> <replaceable>file</replaceable>,
+      <option>--old-file</option>=<replaceable>file</replaceable>,
+      <option>--assume-old</option>=<replaceable>file</replaceable>
+    </term>
+    <listitem>
+      <para>
+
+        Do not rebuild <replaceable>file</replaceable>, and do
+        not rebuild anything due to changes in the contents of
+        <replaceable>file</replaceable>.
+
+      </para>
+    </listitem>
+  </varlistentry>
+
+ <!--
+
+  <varlistentry>
+    <term>
+      <option>- -override</option> <replaceable>file</replaceable>
+    </term>
+    <listitem>
+      <para>
+
+        Read values to override specific build environment variables
+        from the specified <replaceable>file</replaceable>.
+
+      </para>
+    </listitem>
+  </varlistentry>
+
+ -->
+
+ <!--
+
+  <varlistentry>
+    <term>
+      <option>-p</option>
+    </term>
+    <listitem>
+      <para>
+
+        Print the data base (construction environments,
+	Builder and Scanner objects) that are defined
+	after reading the configuration files.
+	After printing, a normal build is performed
+	as usual, as specified by other command-line options.
+        This also prints version information
+	printed by the <option>-v</option> option.
+
+	<!- -
+	???
+	To print the data base without trying
+	to rebuild any files,
+	use <literal>scons -p -f /dev/null</literal>.
+	- ->
+
+      </para>
+    </listitem>
+  </varlistentry>
+
+ -->
+
+  <varlistentry>
+    <term>
+      <option>-q</option>,
+      <option>--question</option>
+    </term>
+    <listitem>
+      <para>
+
+        Do not run any commands, or print anything.  Just return an exit
+        status that is zero if the specified targets are already up to
+        date, nonzero otherwise.
+
+      </para>
+    </listitem>
+  </varlistentry>
+
+ <!--
+
+  <varlistentry>
+    <term>
+      <option>-r</option>,
+      <option>- -no-builtin-rules</option>,
+      <option>-R</option>,
+      <option>- -no-builtin-variables</option>
+    </term>
+    <listitem>
+      <para>
+
+        Clear the default construction variables.  Construction
+        environments that are created will be completely empty.
+
+      </para>
+    </listitem>
+  </varlistentry>
+
+ -->
+
+  <varlistentry>
+    <term>
+      <option>--random</option>
+    </term>
+    <listitem>
+      <para>
+
+        Build dependencies in a random order.  This is useful when
+        building multiple trees simultaneously with caching enabled as a
+        way to prevent multiple builds from simultaneously trying to build
+        or retrieve the same target files.
+
+      </para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term>
+      <option>-s</option>,
+      <option>--silent</option>,
+      <option>--quiet</option>
+    </term>
+    <listitem>
+      <para>
+
+        Silent.  Do not print commands that are executed to rebuild
+        target files.
+
+      </para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term>
+      <option>-S</option>,
+      <option>--no-keep-going</option>,
+      <option>--stop</option>
+    </term>
+    <listitem>
+      <para>
+
+        Ignored for compatibility with GNU <application>make</application>.
+
+      </para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term>
+      <option>-t</option>
+    </term>
+    <listitem>
+      <para>
+
+        Ignored for compatibility with GNU
+        <application>make</application>.  (Touching a file to make it
+        appear up-to-date is unnecessary when using &scons;.)
+
+      </para>
+    </listitem>
+  </varlistentry>
+
+ <!--
+
+  <varlistentry>
+    <term>
+      <option>-u</option>
+    </term>
+    <listitem>
+      <para>
+
+        Traverse up directories until an <filename>SConstruct</filename>
+        or <filename>sconstruct</filename> file is found, and use that
+        as the top of the directory tree.  Only targets at or below the
+        current directory will be built.
+
+      </para>
+    </listitem>
+  </varlistentry>
+
+ -->
+
+  <varlistentry>
+    <term>
+      <option>-v</option>
+    </term>
+    <listitem>
+      <para>
+
+        Print the &scons; version, copyright information,
+	list of authors, and any other relevant information.
+	Then exit.
+
+      </para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term>
+      <option>-w</option>,
+      <option>--print-directory</option>,
+    </term>
+    <listitem>
+      <para>
+
+        Print a message containing the working directory before and
+        after other processing.
+
+      </para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term>
+      <option>--no-print-directory</option>
+    </term>
+    <listitem>
+      <para>
+
+        Turn off -w, even if it was turned on implicitly.
+
+      </para>
+    </listitem>
+  </varlistentry>
+
+ <!--
+
+  <varlistentry>
+    <term>
+      <option>- -write-filenames</option> <replaceable>file</replaceable>
+    </term>
+    <listitem>
+      <para>
+
+        Write all filenames considered into
+        <replaceable>file</replaceable>.
+
+      </para>
+    </listitem>
+  </varlistentry>
+
+ -->
+
+ <!--
+
+  <varlistentry>
+    <term>
+      <option>-W</option> <replaceable>file</replaceable>,
+      <option>- -what-if</option>=<replaceable>file</replaceable>,
+      <option>- -new-file</option>=<replaceable>file</replaceable>,
+      <option>- -assume-new</option>=<replaceable>file</replaceable>
+    </term>
+    <listitem>
+      <para>
+
+        Pretend that the target <replaceable>file</replaceable> has been
+        modified.  When used with the <option>-n</option> option, this
+        show you what would be rebuilt if you were to modify that file.
+        Without <option>-n</option>... what? XXX
+
+      </para>
+    </listitem>
+  </varlistentry>
+
+ -->
+
+  <varlistentry>
+    <term>
+      <option>--warn-undefined-variables</option>
+    </term>
+    <listitem>
+      <para>
+
+        Warn when an undefined variable is referenced.
+
+      </para>
+    </listitem>
+  </varlistentry>
+
+ <!--
+
+  <varlistentry>
+    <term>
+      <option>-Y</option> <replaceable>repository</replaceable>,
+      <option>- -repository</option> <replaceable>repository</replaceable>
+    </term>
+    <listitem>
+      <para>
+
+        Search the specified repository for any input and target
+        files not found in the local directory hierarchy.  Multiple
+        <option>-Y</option> options may specified, in which case the
+        repositories are searched in the order specified.
+
+      </para>
+    </listitem>
+  </varlistentry>
+
+ -->
+
+</variablelist>