Commits

Anonymous committed b4a21a0

Add a man page.

  • Participants
  • Parent commits 1aac82b

Comments (0)

Files changed (7)

 
 #
 # An internal "whereis" routine to figure out if we have a
-# given program available.
+# given program available.  Put it in the "cons::" package
+# so subsidiary Conscript files can get at it easily, too.
 #
 use Config;
-sub whereis {
+sub cons::whereis {
     my $file = shift;
     foreach my $dir (split(/$Config{path_sep}/, $ENV{PATH})) {
 	$f = File::Spec->catfile($dir, $file);
 # This will allow people to still do SCons work even if they
 # don't have Aegis or RPM installed, for example.
 #
-$aegis = whereis('aegis');
-$aesub = whereis('aesub');
-$rpm = whereis('rpm');
-$jw = whereis('jw');
+$aegis = cons::whereis('aegis');
+$aesub = cons::whereis('aesub');
+$rpm = cons::whereis('rpm');
+$jw = cons::whereis('jw');
 
 #
 # Now grab the information that we "build" into the files (using sed).

File doc/Conscript

 $doc_tar_gz = "#build/dist/scons-doc-$version.tar.gz";
 
 #
+# We'll only try to build text files (for some documents)
+# if lynx is available to do the dump.
+#
+$lynx = cons::whereis('lynx');
+
+#
 # Always create a version.sgml file containing the version information
 # for this run.  Ignore it for dependency purposes so we don't
 # rebuild all the docs every time just because the date changes.
 Ignore("version.sgml");
 
 #
-# Each document will live in its own subdirectory.  List them here.
+# Each document will live in its own subdirectory.  List them here
+# as hash keys, with a hash of the info to control its build.
 #
-@doc_dirs = qw(
-    design
+%doc_dirs = (
+    'design' => {
+    		'html'	=> 'book1.html',
+	},
+    'man' => {
+    		'html'	=> 'scons.html',
+		'text'	=> 1,
+	},
 );
 
 # Find internal dependencies in .sgml files:
 # For each document, build the document itself in HTML, Postscript,
 # and PDF formats.
 #
-foreach $doc (@doc_dirs) {
+foreach $doc (keys %doc_dirs) {
     my $main = "$doc/main.sgml";
     my $out = "main.out";
 
     my $htmldir = "HTML/scons-$doc";
+    my $html = "$htmldir/" . $doc_dirs{$doc}->{'html'};
     my $ps = "PS/scons-$doc.ps";
     my $pdf = "PDF/scons-$doc.pdf";
+    my $text = "TEXT/scons-$doc.txt";
 
     $env->QuickScan(\&scansgml, $main);
 
-    $env->Command("$htmldir/book1.html", $main,
-	qq(jw -b html -o %>:d %<));
+    $env->Command($html, $main,
+	[qq(rm -f %>:d/*.html),
+	 qq(jw -b html -o %>:d %<),
+	]);
 
     $env->Command($ps, $main,
 	[qq(rm -f %>:d/$out),
 	 qq(rm -f %>:d/$out),
 	]);
 
-    push(@tar_deps, "$htmldir/book1.html", $ps, $pdf);
+    if ($doc_dirs{$doc}->{'text'} && $lynx) {
+	$env->Command($text, $html, qq(lynx -dump %<:a > %>));
+    }
+
+    push(@tar_deps, $html, $ps, $pdf);
     push(@tar_list, "$htmldir/[A-Za-z]*", $ps, $pdf);
 }
 

File doc/man/.aeignore

+*,D
+.*.swp
+.consign

File doc/man/desc.sgml

+<!--
+
+  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>

File doc/man/main.sgml

+<!--
+
+  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>

File doc/man/options.sgml

+<!--
+
+  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>

File doc/scons.mod

 <!ENTITY Make "<application>Make</application>">
 <!ENTITY Makepp "<application>Make++</application>">
 <!ENTITY SCons "<application>SCons</application>">
-
+<!ENTITY scons "<application>scons</application>">
 
 
 <!--