Add variable interpolation to the man page

2 files changed, 140 insertions, 101 deletions

diff --git a/doc/Conscript b/doc/Conscript
index 7266807..a04d280 100644
--- a/doc/Conscript
+++ b/doc/Conscript
@@ -39,17 +39,19 @@ $doc_tar_gz = "#build/dist/scons-doc-${\$env->{VERSION}}.tar.gz";
 $groff = cons::whereis('groff');
 $lynx = cons::whereis('lynx');
 $man2html = cons::whereis('man2html');
-
-#
-# 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_;
+$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.
 -->
@@ -57,98 +59,99 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
 <!ENTITY buildversion "${\$env->{VERSION}}">
 <!ENTITY buildrevision "${\$env->{REVISION}}">
 _EOF_
-close(FILE);
-
-Ignore("version.sgml");
-
-#
-# 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 = (
-    'design' => {
-    		'html'	=> 'book1.html',
-	},
-    'user' => {
-    		'html'	=> 'book1.html',
-	},
-);
-
-# Find internal dependencies in .sgml files:
-#
-#	<!entity bground SYSTEM "bground.sgml">
-#	<graphic 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 @includes = ();
-    do {
-	if (/<!entity\s+(?:%\s+)?(?:\S+)\s+SYSTEM\s+"([^"]*)">/i) {
-	    push(@includes, $1);
-  	} elsif (/<graphic[^>]*\sfileref="([^"]*)"/) {
-	    push(@includes, "design/$1");
+    close(FILE);
+
+    Ignore("version.sgml");
+
+    #
+    # 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 = (
+        'design' => {
+                'html'	=> 'book1.html',
+    	},
+        'user' => {
+                'html'	=> 'book1.html',
+  	},
+    );
+
+	# Find internal dependencies in .sgml files:
+	#
+	#	<!entity bground SYSTEM "bground.sgml">
+	#	<graphic 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 @includes = ();
+    	do {
+		if (/<!entity\s+(?:%\s+)?(?:\S+)\s+SYSTEM\s+"([^"]*)">/i) {
+		    push(@includes, $1);
+	  	} elsif (/<graphic[^>]*\sfileref="([^"]*)"/) {
+		    push(@includes, "design/$1");
+		}
+	    } while (<scan::quickscan::SCAN>);
+	    @includes;
 	}
-    } while (<scan::quickscan::SCAN>);
-    @includes;
-}
-
-#
-# 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 %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($html, $main,
-	qq(rm -f %>:d/*.html
-	   jw -b html -o %>:d %<
-	   mv -v %>:d/index.html %> || true
-	));
-
-    $env->Command($ps, $main,
-	qq(rm -f %>:d/$out
-	   jw -b ps -o %>:d %<
-	   mv %>:d/main.ps %>
-	   rm -f %>:d/$out
-	));
-
-    $env->Command($pdf, $main,
-	qq(rm -f %>:d/$out
-	   jw -b pdf -o %>:d %<
-	   mv %>:d/main.pdf %>
-	   rm -f %>:d/$out
-	));
-
-    if ($doc_dirs{$doc}->{'text'} && $lynx) {
-	$env->Command($text, $html, qq(lynx -dump %<:a > %>));
-    }
+	#
+	# 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);
+	}
 
-    push(@tar_deps, $html, $ps, $pdf);
-    push(@tar_list, $htmldir, $ps, $pdf);
+	#
+	# For each document, build the document itself in HTML, Postscript,
+	# and PDF formats.
+	#
+	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($html, $main,
+		qq(rm -f %>:d/*.html
+		   jw -b html -o %>:d %<
+		   mv -v %>:d/index.html %> || true
+		));
+
+		$env->Command($ps, $main,
+		qq(rm -f %>:d/$out
+		   jw -b ps -o %>:d %<
+		   mv %>:d/main.ps %>
+		   rm -f %>:d/$out
+		));
+
+		$env->Command($pdf, $main,
+		qq(rm -f %>:d/$out
+		   jw -b pdf -o %>:d %<
+		   mv %>:d/main.pdf %>
+		   rm -f %>:d/$out
+		));
+
+		if ($doc_dirs{$doc}->{'text'} && $lynx) {
+		$env->Command($text, $html, qq(lynx -dump %<:a > %>));
+		}
+
+		push(@tar_deps, $html, $ps, $pdf);
+		push(@tar_list, $htmldir, $ps, $pdf);
+	}
 }
 
 #
diff --git a/doc/man/scons.1 b/doc/man/scons.1
index 39d9fc7..ad00907 100644
--- a/doc/man/scons.1
+++ b/doc/man/scons.1
@@ -504,7 +504,7 @@ env.Object(target = 'bar', source = 'bar.c')
 .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 exeuctable prefix and suffix (if any) are
+compiled to object files. The executable prefix and suffix (if any) are
 automatically added to the target. Example:
 
 .RS
@@ -699,6 +699,41 @@ Specifies a builder to use when a source file name suffix does not match
 any of the suffixes of the builder. Using this argument produces a
 multi-stage builder.
 
+.LP
+
+.B scons
+performs construction variable interpolation on the strings that make up
+the command line of builders before executing the command.
+Variables are specified by a $ prefix and the variable name may be
+surrounded by curly braces ({}) to separate the name from the trailing
+characters. Besides construction variables, scons provides the following
+variables for each command execution:
+
+.IP TARGET
+The file name of the target being built, or the file name of the first 
+target if multiple targets are being built.
+
+.IP TARGETS
+The file names of the targets being built.
+
+.IP SOURCES
+The file names of the sources of the build command.
+
+.LP 
+
+For example, given the construction variable CC='cc', targets=['foo'], and
+sources=['foo.c', 'bar.c']:
+
+.RS
+action='$CC -c -o $TARGET $SOURCES'
+.RE
+
+would produce the command line:
+
+.RS
+cc -c -o foo foo.c bar.c
+.RE
+
 .\" XXX document how to add user defined scanners. 
 
 .SH ENVIRONMENT
@@ -721,3 +756,4 @@ source code.
 
 .SH AUTHOR
 Steven Knight <knight@baldmt.com>, et. al.
+