Doc and README/RELEASE updates in preparation for eventual 0.07 release. (Later this week?)

2 files changed, 230 insertions, 274 deletions

diff --git a/doc/Conscript b/doc/Conscript
deleted file mode 100644
index 9eef3e6..0000000
--- a/doc/Conscript
+++ /dev/null
@@ -1,254 +0,0 @@
-#
-# Conscript file for building SCons documentation.
-#
-
-#
-# Copyright (c) 2001, 2002 Steven Knight
-#
-# 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.
-#
-
-Import qw( env );
-
-#
-#
-#
-$doc_tar_gz = "#build/dist/scons-doc-${\$env->{VERSION}}.tar.gz";
-
-#
-# We'll only try to build text files (for some documents)
-# if lynx is available to do the dump.
-#
-$fig2dev = cons::whereis('fig2dev');
-$groff = cons::whereis('groff');
-$lynx = cons::whereis('lynx');
-$man2html = cons::whereis('man2html');
-$jw = cons::whereis('jw');
-
-if ($jw) {
-    #
-    # 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.
-    #
-    $verfile = SourcePath("version.sgml");
-    unlink($verfile);
-    chmod(0664, $verfile);
-    open(FILE, ">$verfile") || die "Cannot open '$verfile': $!";
-    print FILE <<_EOF_;
-<!--
-THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
--->
-<!ENTITY builddate "${\$env->{DATE}}">
-<!ENTITY buildversion "${\$env->{VERSION}}">
-<!ENTITY buildrevision "${\$env->{REVISION}}">
-_EOF_
-    close(FILE);
-
-    Ignore("version.sgml");
-
-    # Find internal dependencies in .sgml files:
-    #
-    #	<!entity bground SYSTEM "bground.sgml">
-    #	<graphic fileref="file.jpg">
-    #	<imagedata fileref="file.jpg">
-    #
-    # This only finds one per line, and assumes that anything
-    # defined as a SYSTEM entity is, in fact, a file included
-    # somewhere in the document.
-    sub scansgml {
-	my $dir = shift;
-        my @includes = ();
-        do {
-    	if (/<!entity\s+(?:%\s+)?(?:\S+)\s+SYSTEM\s+"([^"]*)">/i) {
-    	    push(@includes, $1);
-      	} elsif (/<(?:graphic|imagedata)\s+fileref="([^"]*)"\s+format="([^"]*)"/) {
-	    ($file, $format) = ($1, $2);
-	    $file = "$file.$format" if ($file !~ /\.$format$/);
-	    if ($dir && ! File::Spec->file_name_is_absolute($file)) {
-		$file = "build/doc/$dir/$file";
-	    }
-    	    push(@includes, $file);
-      	} elsif (/<(?:graphic|imagedata)\s+fileref="([^"]*)"/) {
-	    $file = $1;
-	    if ($dir && ! File::Spec->file_name_is_absolute($file)) {
-		$file = "build/doc/$dir/$file";
-	    }
-    	    push(@includes, $file);
-    	}
-        } while (<scan::quickscan::SCAN>);
-        @includes;
-    }
-
-    #
-    # Each document will live in its own subdirectory.  List them here
-    # as hash keys, with a hash of the info to control its build.
-    #
-    %docs = (
-        'design' => {
-                'htmlindex'	=> 'book1.html',
-		'ps'		=> 1,
-		'pdf'		=> 1,
-		'text'		=> 0,
-		'scan'		=> sub { scansgml("design") },
-    	},
-	'python10' => {
-		'htmlindex' 	=> 't1.html',
-		'html' 		=> 1,
-		'ps'		=> 1,
-		'pdf'		=> 0,
-		'text'		=> 0,
-    		'graphics'	=> [qw( arch builder job-task node scanner sig )],
-		'scan'		=> sub { scansgml("python10") },
-	},
-        'user' => {
-                'htmlindex'	=> 'book1.html',
-                'html'		=> 1,
-		'ps'		=> 1,
-		'pdf'		=> 1,
-		'text'		=> 0,
-		'scan'		=> sub { scansgml("user") },
-  	},
-    );
-
-    #
-    # We have to tell Cons to QuickScan the top-level SGML files which
-    # get included by the document SGML files in the subdirectories.
-    #	
-    @included_sgml = qw(
-    	scons.mod
-    	copyright.sgml
-    );
-
-    foreach $sgml (@included_sgml) {
-    	$env->QuickScan(\&scansgml, $sgml);
-    }
-
-    #
-    # For each document, build the document itself in HTML, Postscript,
-    # and PDF formats.
-    #
-    foreach $doc (keys %docs) {
-	my $main = "$doc/main.sgml";
-	my $out = "main.out";
-
-	my $htmldir = "HTML/scons-$doc";
-	my $htmlindex = "$htmldir/" . $docs{$doc}->{'htmlindex'};
-	my $html = "HTML/scons-$doc.html";
-	my $ps = "PS/scons-$doc.ps";
-	my $pdf = "PDF/scons-$doc.pdf";
-	my $text = "TEXT/scons-$doc.txt";
-
-	if ($docs{$doc}->{'scan'}) {
-	    $env->QuickScan($docs{$doc}->{'scan'}, $main);
-	}
-
-	if ($docs{$doc}->{'html'}) {
-	    $env->Command($htmlindex, $main,
-		qq(rm -f %>:d/*.html
-		   jw -b html -o %>:d %<
-		   mv -v %>:d/index.html %> || true
-		));
-
-	    $env->Command($html, $main, qq(jw -u -b html %< > %>));
-	
-	    push(@tar_deps, $html, $htmlindex);
-	    push(@tar_list, $html, $htmldir);
-	    if ($fig2dev) {
-		for $g (@{$docs{$doc}->{'graphics'}}) {
-		    $fig = "$doc/$g.fig";
-		    $jpg = "$htmldir/$g.jpg";
-		    $env->Command($jpg, $fig, qq($fig2dev -L jpeg -q 100 %< %>));
-		    $env->Depends($ps, $jpg);
-		}
-	    }
-	}
-
-	if ($docs{$doc}->{'ps'}) {
-	    $env->Command($ps, $main,
-		qq(rm -f %>:d/$out
-		   jw -b ps -o %>:d %<
-		   mv %>:d/main.ps %>
-		   rm -f %>:d/$out
-		));
-	    push(@tar_deps, $ps);
-	    push(@tar_list, $ps);
-	    if ($fig2dev) {
-		for $g (@{$docs{$doc}->{'graphics'}}) {
-		    $fig = "$doc/$g.fig";
-		    $eps = "PS/$g.eps";
-		    $env->Command($eps, $fig, qq($fig2dev -L eps %< %>));
-		    $env->Depends($ps, $eps);
-		}
-	    }
-	}
-
-	if ($docs{$doc}->{'pdf'}) {
-	    $env->Command($pdf, $main,
-		qq(rm -f %>:d/$out
-		   jw -b pdf -o %>:d %<
-		   mv %>:d/main.pdf %>
-		   rm -f %>:d/$out
-		));
-	    push(@tar_deps, $pdf);
-	    push(@tar_list, $pdf);
-	}
-
-	if ($docs{$doc}->{'text'} && $lynx) {
-	    $env->Command($text, $html, qq(lynx -dump %<:a > %>));
-	    push(@tar_deps, $text);
-	    push(@tar_list, $text);
-	}
-    }
-}
-
-#
-# Man page(s), in good ol' troff format.
-#
-my $scons_1 = "man/scons.1";
-
-if ($groff) {
-    my $ps = "PS/scons-man.ps";
-    my $text = "TEXT/scons-man.txt";
-
-    $env->Command($ps, $scons_1, "groff -man -Tps %< > %>");
-
-    $env->Command($text, $scons_1, "groff -man -Tascii %< > %>");
-
-    push(@tar_deps, $ps, $text);
-    push(@tar_list, $ps, $text);
-}
-
-if ($man2html) {
-    my $html = "HTML/scons-man.html";
-
-    $env->Command($html, $scons_1, "man2html %< > %>");
-
-    push(@tar_deps, $html);
-    push(@tar_list, $html);
-}
-
-#
-# Now actually create the tar file of the documentation,
-# for easy distribution to the web site.
-#
-$env->Command($doc_tar_gz,
-	      @tar_deps,
-	      qq(tar zchv -f %> -C build/doc @tar_list));
diff --git a/doc/man/scons.1 b/doc/man/scons.1
index 5fdc1aa..afd4c16 100644
--- a/doc/man/scons.1
+++ b/doc/man/scons.1
@@ -614,6 +614,8 @@ Turn off -w, even if it was turned on implicitly.
 .\" repositories are searched in the order specified.
 
 .SH CONFIGURATION FILE REFERENCE
+.\" .SS Python Basics
+.\" XXX Adding this in the future would be a help.
 .SS Construction Environments
 A construction environment is the basic means by which the configuration
 files communicate build information to 
@@ -646,7 +648,25 @@ provides the following builders:
 .IP Object
 Builds an object file from one or more C, C++, or Fortran source files.
 Source files must have one of the following extensions:
-.c, .C, .cc, .cpp, .cxx, .c++, .C++, .f, .F, .for, .FOR, .fpp, .FPP. 
+.ES
+  .c      C file
+  .C      WIN32:  C file
+          POSIX:  C++ file
+  .cc     C++ file
+  .cpp    C++ file
+  .cxx    C++ file
+  .cxx    C++ file
+  .c++    C++ file
+  .C++    C++ file
+  .f      Fortran file
+  .F      WIN32:  Fortran file
+          POSIX:  Fortran file + C pre-processor
+  .for    Fortran file
+  .FOR    Fortran file
+  .fpp    Fortran file + C pre-processor
+  .FPP    Fortran file + C pre-processor
+.EE
+.IP
 The target object file prefix and suffix (if any) are automatically
 added. Examples:
 
@@ -668,9 +688,17 @@ env.Object(target = 'ddd.obj', source = 'ddd.c', shared = 1)
 .EE
 
 .IP Program
-Builds an executable given one or more object files or C/C++ source
-files. If any C/C++ source files are given, then they will be automatically
-compiled to object files. The executable prefix and suffix (if any) are
+Builds an executable given one or more object files or C, C++
+or Fortran source files.
+If any C, C++ or Fortran source files are specified,
+then they will be automatically
+compiled to object files using the
+.B Object
+builder;
+see that builder's description for
+a list of legal source file suffixes
+and how they are interpreted.
+The executable prefix and suffix (if any) are
 automatically added to the target. Example:
 
 .ES
@@ -730,8 +758,10 @@ is automatically added to the target
 if it is not already present. Example:
 
 .ES
-env.CFile(target = 'foo.c', source = 'foo.l') # builds foo.c
-env.CFile(target = 'bar', source = 'bar.y')   # builds bar.c
+# builds foo.c
+env.CFile(target = 'foo.c', source = 'foo.l')
+# builds bar.c
+env.CFile(target = 'bar', source = 'bar.y')
 .EE
 
 .IP CXXFile
@@ -742,8 +772,10 @@ is automatically added to the target
 if it is not already present. Example:
 
 .ES
-env.CXXFile(target = 'foo.cc', source = 'foo.ll') # builds foo.cc
-env.CXXFile(target = 'bar', source = 'bar.yy')   # builds bar.cc
+# builds foo.cc
+env.CXXFile(target = 'foo.cc', source = 'foo.ll')
+# builds bar.cc
+env.CXXFile(target = 'bar', source = 'bar.yy')
 .EE
 
 .IP DVI
@@ -754,9 +786,12 @@ is automatically added to the target
 if it is not already present. Example:
 
 .ES
-env.DVI(target = 'aaa.dvi', source = 'aaa.tex')   # builds from aaa.tex
-env.DVI(target = 'bbb', source = 'bbb.ltx')       # builds bbb.dvi
-env.DVI(target = 'ccc.dvi', source = 'ccc.latex') # builds from ccc.latex
+# builds from aaa.tex
+env.DVI(target = 'aaa.dvi', source = 'aaa.tex')
+# builds bbb.dvi
+env.DVI(target = 'bbb', source = 'bbb.ltx')
+# builds from ccc.latex
+env.DVI(target = 'ccc.dvi', source = 'ccc.latex')
 .EE
 
 .IP PDF
@@ -768,8 +803,10 @@ is added automatically to the target
 if it is not already present.  Example:
 
 .ES
-env.PDF(target = 'aaa.pdf', source = 'aaa.tex')   # builds from aaa.tex
-env.PDF(target = 'bbb', source = 'bbb.dvi')       # builds bbb.dvi
+# builds from aaa.tex
+env.PDF(target = 'aaa.pdf', source = 'aaa.tex')
+# builds bbb.dvi
+env.PDF(target = 'bbb', source = 'bbb.dvi')
 .EE
 
 .IP PostScript
@@ -781,13 +818,22 @@ is added automatically to the target
 if it is not already present.  Example:
 
 .ES
-env.PostScript(target = 'aaa.ps', source = 'aaa.tex')   # builds from aaa.tex
-env.PostScript(target = 'bbb', source = 'bbb.dvi')      # builds bbb.dvi
+# builds from aaa.tex
+env.PostScript(target = 'aaa.ps', source = 'aaa.tex')
+# builds bbb.dvi
+env.PostScript(target = 'bbb', source = 'bbb.dvi')
 .EE
 .LP
 .B scons
 automatically scans
-C, C++ and Fortran source files with .F, .fpp, or .FOR file extensions
+C source files, C++ source files, and
+Fortran source files with
+.B .F
+(POSIX systems only),
+.B .fpp,
+or
+.B .FPP
+file extensions
 for C preprocessor dependencies,
 so the dependencies do not need to be specified explicitly.
 In addition, all builder
@@ -801,19 +847,34 @@ Additional Environment methods include:
 
 .TP
 .RI Command( target ", " source ", " commands )
-Executes a specific command
-(or list of commands)
+Executes a specific action
+(or list of actions)
 to build a target file or files.
 This is more convenient
 than defining a separate Builder object
 for a single special-case build.
 
+Note that an action can be an external command,
+specified as a string,
+or a callable Python object;
+see "Action Objects," below.
+Examples:
+
 .ES
 env.Command('foo.out', 'foo.in',
             "$FOO_BUILD < $SOURCES > $TARGET")
+
 env.Command('bar.out', 'bar.in',
             ["rm -f $TARGET",
              "$BAR_BUILD < $SOURCES > $TARGET"])
+
+def rename(env, target, source):
+    import os
+    os.rename('.tmp', str(target[0]))
+
+env.Command('baz.out', 'baz.in',
+            ["$BAZ_BUILD < $SOURCES > .tmp",
+	     rename ])
 .EE
 
 .TP
@@ -926,7 +987,22 @@ env.Update(CCFLAGS = '-g', FOO = 'foo.xxx')
 .EE
 
 .SS Construction Variables
-
+.\" XXX From Gary Ruben, 23 April 2002:
+.\" I think it would be good to have an example with each construction
+.\" variable description in the documentation.
+.\" eg.
+.\" CC     The C compiler
+.\"    Example: env["CC"] = "c68x"
+.\"    Default: env["CC"] = "cc"
+.\" 
+.\" CCCOM  The command line ...
+.\"    Example:
+.\"        To generate the compiler line c68x -ps -qq -mr -o $TARGET $SOURCES
+.\"        env["CC"] = "c68x"
+.\"        env["CFLAGS"] = "-ps -qq -mr"
+.\"        env["CCCOM"] = "$CC $CFLAGS -o $TARGET $SOURCES
+.\"    Default:
+.\"        (I dunno what this is ;-)
 A construction environment has an associated dictionary of construction
 variables that are used by built-in or user-supplied build rules. A number
 of useful construction variables are automatically defined by scons for
@@ -961,7 +1037,13 @@ The suffix for C source files.
 This is used by the internal CFile builder
 when generating C files from Lex (.l) or YACC (.y) input files.
 The default suffix, of course, is
-.IR .c .
+.I .c
+(lower case).
+On case-insensitive systems (like Win32),
+SCons also treats
+.I .C
+(upper case) files
+as C files.
 
 .IP CPPFLAGS
 C preprocessor options.
@@ -1005,6 +1087,18 @@ This is used by the internal CXXFile builder
 when generating C++ files from Lex (.ll) or YACC (.yy) input files.
 The default suffix is
 .IR .cc .
+SCons also treats files with the suffixes
+.IR .cpp ,
+.IR .cxx ,
+.IR .c++ ,
+and
+.I .C++
+as C++ files.
+On case-sensitive systems (Linux, UNIX, and other POSIX-alikes),
+SCons also treats
+.I .C
+(upper case) files
+as C++ files.
 
 .IP CXXCOM
 The command line used to compile a C++ source file to an object file.
@@ -1711,6 +1805,16 @@ a command-line Action is returned.
 Action('$CC -c -o $TARGET $SOURCES')
 .EE
 
+.\" XXX From Gary Ruben, 23 April 2002:
+.\" What would be useful is a discussion of how you execute command
+.\" shell commands ie. what is the process used to spawn the shell, pass
+.\" environment variables to it etc., whether there is one shell per
+.\" environment or one per command etc.  It might help to look at the Gnu
+.\" make documentation to see what they think is important to discuss about
+.\" a build system. I'm sure you can do a better job of organising the
+.\" documentation than they have :-)
+
+
 .IP List
 If the argument is a list,
 then a list of Action objects is returned.
@@ -1982,6 +2086,112 @@ The
 argument is the argument supplied
 when the scanner was created, if any.
 
+.SH SYSTEM-SPECIFIC BEHAVIOR
+SCons and its configuration files are very portable,
+due largely to its implementation in Python.
+There are, however, a few portability
+issues waiting to trap the unwary.
+.SS .C file suffix
+SCons handles the upper-case
+.B .C
+file suffix differently,
+depending on the capabilities of
+the underlying system.
+On a case-sensitive system
+such as Linux or UNIX,
+SCons treats a file with a 
+.B .C
+suffix as a C++ source file.
+On a case-insensitive system
+such as Windows,
+SCons treats a file with a 
+.B .C
+suffix as a C source file.
+.SS .F file suffix
+SCons handles the upper-case
+.B .F
+file suffix differently,
+depending on the capabilities of
+the underlying system.
+On a case-sensitive system
+such as Linux or UNIX,
+SCons treats a file with a 
+.B .F
+suffix as a Fortran source file
+that is to be first run through
+the standard C preprocessor.
+On a case-insensitive system
+such as Windows,
+SCons treats a file with a 
+.B .F
+suffix as a Fortran source file that should
+.I not
+be run through the C preprocessor.
+.SS WIN32:  Cygwin Tools and Cygwin Python vs. Windows Pythons
+Cygwin supplies a set of tools and utilities
+that let users work on a
+Windows system using a more POSIX-like environment.
+The Cygwin tools, including Cygwin Python,
+do this, in part,
+by sharing an ability to interpret UNIX-like path names.
+For example, the Cygwin tools
+will internally translate a Cygwin path name
+like /cygdrive/c/mydir
+to an equivalent Windows pathname
+of C:/mydir (equivalent to C:\\mydir).
+
+Versions of Python
+that are built for native Windows execution,
+such as the python.org and ActiveState versions,
+do not have the Cygwin path name semantics.
+This means that using a native Windows version of Python
+to build compiled programs using Cygwin tools
+(such as gcc, bison, and flex)
+may yield unpredictable results.
+"Mixing and matching" in this way
+can be made to work,
+but it requires careful attention to the use of path names
+in your SConscript files.
+
+In practice, users can sidestep
+the issue by adopting the following rules:
+When using gcc,
+use the Cygwin-supplied Python interpreter
+to run SCons;
+when using Microsoft Visual C/C++
+(or some other Windows compiler)
+use the python.org or ActiveState version of Python
+to run SCons.
+.SS WIN32:  scons.bat file
+On WIN32 systems,
+SCons is executed via a wrapper
+.B scons.bat
+file.
+This has (at least) two ramifications:
+
+First, Windows command-line users
+that want to use variable assignment
+on the command line
+may have to put double quotes
+around the assignments:
+
+.ES
+scons "FOO=BAR" "BAZ=BLEH"
+.EE
+
+Second, the Cygwin shell does not
+recognize this file as being the same
+as an
+.B scons
+command issued at the command-line prompt.
+You can work around this either by
+executing
+.B scons.bat
+from the Cygwin command line,
+or by creating a wrapper shell
+script named
+.B scons .
+
 .SH EXAMPLES
 
 To help you get started using SCons,