Add an outline for a User's Guide.

22 files changed, 934 insertions, 1 deletions

diff --git a/doc/Conscript b/doc/Conscript
index 9e5f0d9..8a5f15f 100644
--- a/doc/Conscript
+++ b/doc/Conscript
@@ -48,6 +48,9 @@ Ignore("version.sgml");
     		'html'	=> 'scons.html',
 		'text'	=> 1,
 	},
+    'user' => {
+    		'html'	=> 'book1.html',
+	},
 );
 
 # Find internal dependencies in .sgml files:
diff --git a/doc/scons.mod b/doc/scons.mod
index 7e5470e..7a36685 100644
--- a/doc/scons.mod
+++ b/doc/scons.mod
@@ -57,7 +57,7 @@
 
 <!--
 
-  Methods and functions.  This includes both functions from both
+  Methods and functions.  This includes functions from both
   the Build Engine and the Native Python Interface.
 
 -->
@@ -65,17 +65,29 @@
 <!ENTITY Alias "<function>Alias</function>">
 <!ENTITY Aliases "<function>Aliases</function>">
 <!ENTITY Build "<function>Build</function>">
+<!ENTITY Cache "<function>Cache</function>">
 <!ENTITY Clean "<function>Clean</function>">
+<!ENTITY Clone "<function>Clone</function>">
 <!ENTITY Command "<function>Command</function>">
 <!ENTITY Copy "<function>Copy</function>">
 <!ENTITY Default "<function>Default</function>">
+<!ENTITY DefaultRules "<function>DefaultRules</function>">
+<!ENTITY Depends "<function>Depends</function>">
 <!ENTITY Environment "<function>Environment</function>">
 <!ENTITY Export "<function>Export</function>">
 <!ENTITY Help "<function>Help</function>">
+<!ENTITY Ignore "<function>Ignore</function>">
+<!ENTITY Install "<function>Install</function>">
+<!ENTITY InstallAs "<function>InstallAs</function>">
 <!ENTITY Link "<function>Link</function>">
 <!ENTITY Local "<function>Local</function>">
+<!ENTITY Module "<function>Module</function>">
+<!ENTITY Objects "<function>Objects</function>">
 <!ENTITY Precious "<function>Precious</function>">
 <!ENTITY Repository "<function>Repository</function>">
+<!ENTITY RuleSet "<function>RuleSet</function>">
+<!ENTITY Salt "<function>Salt</function>">
+<!ENTITY SourceSignature "<function>SourceSignature</function>">
 <!ENTITY Task "<function>Task</function>">
 
 
@@ -95,6 +107,16 @@
 
 <!--
 
+  Environment variables.
+
+-->
+
+<!ENTITY SCONSFLAGS "<varname>SCONSFLAGS</varname>">
+
+
+
+<!--
+
   Builder and Scanner objects.
 
 -->
diff --git a/doc/user/.aeignore b/doc/user/.aeignore
new file mode 100644
index 0000000..872e8be
--- /dev/null
+++ b/doc/user/.aeignore
@@ -0,0 +1,3 @@
+*,D
+.*.swp
+.consign
diff --git a/doc/user/builders.sgml b/doc/user/builders.sgml
new file mode 100644
index 0000000..f74f1aa
--- /dev/null
+++ b/doc/user/builders.sgml
@@ -0,0 +1,32 @@
+<!--
+
+  Copyright 2001 Steven Knight
+
+-->
+ <para>
+
+   X
+
+ </para>
+
+ <section>
+ <title>Builders That Execute External Commands</title>
+
+   <para>
+
+   X
+
+   </para>
+
+ </section>
+
+ <section>
+ <title>Builders That Execute Python Functions</title>
+
+   <para>
+
+   X
+
+   </para>
+
+ </section>
diff --git a/doc/user/caching.sgml b/doc/user/caching.sgml
new file mode 100644
index 0000000..66db8ad
--- /dev/null
+++ b/doc/user/caching.sgml
@@ -0,0 +1,21 @@
+<!--
+
+  Copyright 2001 Steven Knight
+
+-->
+ <para>
+
+   X
+
+ </para>
+
+ <section>
+ <title>The &Cache; Method</title>
+
+   <para>
+
+   X
+
+   </para>
+
+ </section>
diff --git a/doc/user/cons.sgml b/doc/user/cons.sgml
new file mode 100644
index 0000000..2514e74
--- /dev/null
+++ b/doc/user/cons.sgml
@@ -0,0 +1,21 @@
+<!--
+
+  Copyright 2001 Steven Knight
+
+-->
+ <para>
+
+   X
+
+ </para>
+
+ <section>
+ <title>X</title>
+
+   <para>
+
+   X
+
+   </para>
+
+ </section>
diff --git a/doc/user/depends.sgml b/doc/user/depends.sgml
new file mode 100644
index 0000000..eb5c422
--- /dev/null
+++ b/doc/user/depends.sgml
@@ -0,0 +1,76 @@
+<!--
+
+  Copyright 2001 Steven Knight
+
+-->
+ <para>
+
+   X
+
+ </para>
+
+ <section>
+ <title>MD5 Signatures</title>
+
+   <para>
+
+   X
+
+   </para>
+
+ </section>
+
+ <section>
+ <title>Time Stamps</title>
+
+   <para>
+
+   X
+
+   </para>
+
+ </section>
+
+ <section>
+ <title>The &Depends; Method</title>
+
+   <para>
+
+   X
+
+   </para>
+
+ </section>
+
+ <section>
+ <title>The &Ignore; Method</title>
+
+   <para>
+
+   X
+
+   </para>
+
+ </section>
+
+ <section>
+ <title>The &Salt; Method</title>
+
+   <para>
+
+   X
+
+   </para>
+
+ </section>
+
+ <section>
+ <title>The &SourceSignature; Method</title>
+
+   <para>
+
+   X
+
+   </para>
+
+ </section>
diff --git a/doc/user/environments.sgml b/doc/user/environments.sgml
new file mode 100644
index 0000000..59ad3cf
--- /dev/null
+++ b/doc/user/environments.sgml
@@ -0,0 +1,43 @@
+<!--
+
+  Copyright 2001 Steven Knight
+
+-->
+ <para>
+
+   X
+
+ </para>
+
+ <section>
+ <title>The &Environment; Constructor</title>
+
+   <para>
+
+   X
+
+   </para>
+
+ </section>
+
+ <section>
+ <title>The &Clone; Method</title>
+
+   <para>
+
+   X
+
+   </para>
+
+ </section>
+
+ <section>
+ <title>The &Copy; Method</title>
+
+   <para>
+
+   X
+
+   </para>
+
+ </section>
diff --git a/doc/user/errors.sgml b/doc/user/errors.sgml
new file mode 100644
index 0000000..2514e74
--- /dev/null
+++ b/doc/user/errors.sgml
@@ -0,0 +1,21 @@
+<!--
+
+  Copyright 2001 Steven Knight
+
+-->
+ <para>
+
+   X
+
+ </para>
+
+ <section>
+ <title>X</title>
+
+   <para>
+
+   X
+
+   </para>
+
+ </section>
diff --git a/doc/user/example.sgml b/doc/user/example.sgml
new file mode 100644
index 0000000..2514e74
--- /dev/null
+++ b/doc/user/example.sgml
@@ -0,0 +1,21 @@
+<!--
+
+  Copyright 2001 Steven Knight
+
+-->
+ <para>
+
+   X
+
+ </para>
+
+ <section>
+ <title>X</title>
+
+   <para>
+
+   X
+
+   </para>
+
+ </section>
diff --git a/doc/user/hierarchy.sgml b/doc/user/hierarchy.sgml
new file mode 100644
index 0000000..3b5e24f
--- /dev/null
+++ b/doc/user/hierarchy.sgml
@@ -0,0 +1,32 @@
+<!--
+
+  Copyright 2001 Steven Knight
+
+-->
+ <para>
+
+   X
+
+ </para>
+
+ <section>
+ <title>&SConscript; Files</title>
+
+   <para>
+
+   X
+
+   </para>
+
+ </section>
+
+ <section>
+ <title>X</title>
+
+   <para>
+
+   X
+
+   </para>
+
+ </section>
diff --git a/doc/user/main.sgml b/doc/user/main.sgml
new file mode 100644
index 0000000..eb7ab39
--- /dev/null
+++ b/doc/user/main.sgml
@@ -0,0 +1,153 @@
+<!--
+
+  Copyright 2001 Steven Knight
+
+-->
+
+<!doctype book PUBLIC "-//OASIS//DTD DocBook V4.1//EN"
+[
+
+    <!ENTITY % version SYSTEM "../version.sgml">
+    %version;
+
+    <!ENTITY % scons SYSTEM "../scons.mod">
+    %scons;
+
+    <!ENTITY preface SYSTEM "preface.sgml">
+    <!ENTITY simple SYSTEM "simple.sgml">
+    <!ENTITY environments SYSTEM "environments.sgml">
+    <!ENTITY depends SYSTEM "depends.sgml">
+    <!ENTITY more SYSTEM "more.sgml">
+    <!ENTITY hierarchy SYSTEM "hierarchy.sgml">
+    <!ENTITY variants SYSTEM "variants.sgml">
+    <!ENTITY builders SYSTEM "builders.sgml">
+    <!ENTITY scanners SYSTEM "scanners.sgml">
+    <!ENTITY repositories SYSTEM "repositories.sgml">
+    <!ENTITY caching SYSTEM "caching.sgml">
+    <!ENTITY run SYSTEM "run.sgml">
+    <!ENTITY troubleshoot SYSTEM "troubleshoot.sgml">
+    <!ENTITY reference SYSTEM "reference.sgml">
+    <!ENTITY errors SYSTEM "errors.sgml">
+    <!ENTITY example SYSTEM "example.sgml">
+    <!ENTITY make SYSTEM "make.sgml">
+    <!ENTITY cons SYSTEM "cons.sgml">
+
+]>
+
+<book>
+  <bookinfo>
+    <title>SCons User Guide &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>
+
+  </bookinfo>
+
+  <chapter id="chap-preface">
+    <title>Preface</title>
+    &preface;
+  </chapter>
+
+  <chapter id="chap-simple">
+    <title>Simple Builds</title>
+    &simple;
+  </chapter>
+
+  <chapter id="chap-environments">
+    <title>Construction Environments</title>
+    &environments;
+  </chapter>
+
+  <chapter id="chap-depends">
+    <title>Dependencies</title>
+    &depends;
+  </chapter>
+
+  <chapter id="chap-more">
+    <title>More Things to Do With Builds</title>
+    &more;
+  </chapter>
+
+  <chapter id="chap-hierarchical">
+    <title>Hierarchial Builds</title>
+    &hierarchy;
+  </chapter>
+
+  <chapter id="chap-variant">
+    <title>Variant Builds</title>
+    &variants;
+  </chapter>
+
+  <chapter id="chap-builders">
+    <title>Writing Builders</title>
+    &builders;
+  </chapter>
+
+  <chapter id="chap-scanners">
+    <title>Writing Scanners</title>
+    &scanners;
+  </chapter>
+
+  <chapter id="chap-repositories">
+    <title>Building From Code Repositories</title>
+    &repositories;
+  </chapter>
+
+  <chapter id="chap-caching">
+    <title>Caching Built Files</title>
+    &caching;
+  </chapter>
+
+  <chapter id="chap-run">
+    <title>How to Run &SCons;</title>
+    &run;
+  </chapter>
+
+  <chapter id="chap-troubleshooting">
+    <title>Troubleshooting</title>
+    &troubleshoot;
+  </chapter>
+
+  <appendix id="app-quick">
+    <title>Quick Reference</title>
+    &reference;
+  </appendix>
+
+  <appendix id="app-errors">
+    <title>Errors Generated by &SCons;</title>
+    &errors;
+  </appendix>
+
+  <appendix id="app-example">
+    <title>Complex &SCons; Example</title>
+    &example;
+  </appendix>
+
+  <appendix id="app-make">
+    <title>Converting From Make</title>
+    &make;
+  </appendix>
+
+  <appendix id="app-cons">
+    <title>Converting From Cons</title>
+    &cons;
+  </appendix>
+
+</book>
diff --git a/doc/user/make.sgml b/doc/user/make.sgml
new file mode 100644
index 0000000..2514e74
--- /dev/null
+++ b/doc/user/make.sgml
@@ -0,0 +1,21 @@
+<!--
+
+  Copyright 2001 Steven Knight
+
+-->
+ <para>
+
+   X
+
+ </para>
+
+ <section>
+ <title>X</title>
+
+   <para>
+
+   X
+
+   </para>
+
+ </section>
diff --git a/doc/user/more.sgml b/doc/user/more.sgml
new file mode 100644
index 0000000..dc1d0a3
--- /dev/null
+++ b/doc/user/more.sgml
@@ -0,0 +1,109 @@
+<!--
+
+  Copyright 2001 Steven Knight
+
+-->
+ <para>
+
+   X
+
+ </para>
+
+ <section>
+ <title>The &InstallAs; Method</title>
+
+   <para>
+
+   X
+
+   </para>
+
+ </section>
+
+ <section>
+ <title>The &Precious; Method</title>
+
+   <para>
+
+   X
+
+   </para>
+
+ </section>
+
+ <section>
+ <title>The &Command; Method</title>
+
+   <para>
+
+   X
+
+   </para>
+
+ </section>
+
+ <section>
+ <title>The &Objects; Method</title>
+
+   <para>
+
+   X
+
+   </para>
+
+ </section>
+
+ <section>
+ <title>The &Program; Method</title>
+
+   <para>
+
+   X
+
+   </para>
+
+ </section>
+
+ <section>
+ <title>The &Library; Method</title>
+
+   <para>
+
+   X
+
+   </para>
+
+ </section>
+
+ <section>
+ <title>The &Module; Method</title>
+
+   <para>
+
+   X
+
+   </para>
+
+ </section>
+
+ <section>
+ <title>The &RuleSet; Method</title>
+
+   <para>
+
+   X
+
+   </para>
+
+ </section>
+
+ <section>
+ <title>The &DefaultRules; Method</title>
+
+   <para>
+
+   X
+
+   </para>
+
+ </section>
diff --git a/doc/user/preface.sgml b/doc/user/preface.sgml
new file mode 100644
index 0000000..2fddf4e
--- /dev/null
+++ b/doc/user/preface.sgml
@@ -0,0 +1,65 @@
+<!--
+
+  Copyright 2001 Steven Knight
+
+-->
+ <para>
+
+   X
+
+ </para>
+
+ <section>
+ <title>Why &SCons;?</title>
+
+   <para>
+
+   X
+
+   </para>
+
+ </section>
+
+ <section>
+ <title>History</title>
+
+   <para>
+
+   X
+
+   </para>
+
+ </section>
+
+ <section>
+ <title>Conventions</title>
+
+   <para>
+
+   X
+
+   </para>
+
+ </section>
+
+ <section>
+ <title>Acknowledgements</title>
+
+   <para>
+
+   X
+
+   </para>
+
+ </section>
+
+ <section>
+ <title>Contact</title>
+
+   <para>
+
+   X
+
+   </para>
+
+ </section>
diff --git a/doc/user/reference.sgml b/doc/user/reference.sgml
new file mode 100644
index 0000000..594ced1
--- /dev/null
+++ b/doc/user/reference.sgml
@@ -0,0 +1,43 @@
+<!--
+
+  Copyright 2001 Steven Knight
+
+-->
+ <para>
+
+   X
+
+ </para>
+
+ <section>
+ <title>Command-Line Options</title>
+
+   <para>
+
+   X
+
+   </para>
+
+ </section>
+
+ <section>
+ <title>Default Builders</title>
+
+   <para>
+
+   X
+
+   </para>
+
+ </section>
+
+ <section>
+ <title>X</title>
+
+   <para>
+
+   X
+
+   </para>
+
+ </section>
diff --git a/doc/user/repositories.sgml b/doc/user/repositories.sgml
new file mode 100644
index 0000000..8ba1ff7
--- /dev/null
+++ b/doc/user/repositories.sgml
@@ -0,0 +1,32 @@
+<!--
+
+  Copyright 2001 Steven Knight
+
+-->
+ <para>
+
+   X
+
+ </para>
+
+ <section>
+ <title>The &Repository; Method</title>
+
+   <para>
+
+   X
+
+   </para>
+
+ </section>
+
+ <section>
+ <title>X</title>
+
+   <para>
+
+   X
+
+   </para>
+
+ </section>
diff --git a/doc/user/run.sgml b/doc/user/run.sgml
new file mode 100644
index 0000000..3ba222f
--- /dev/null
+++ b/doc/user/run.sgml
@@ -0,0 +1,65 @@
+<!--
+
+  Copyright 2001 Steven Knight
+
+-->
+ <para>
+
+   X
+
+ </para>
+
+ <section>
+ <title>Command-line Target Aliases</title>
+
+   <para>
+
+   X
+
+   </para>
+
+ </section>
+
+ <section>
+ <title>Selective Builds</title>
+
+   <para>
+
+   X
+
+   </para>
+
+ </section>
+
+ <section>
+ <title>Build Pruning</title>
+
+   <para>
+
+   X
+
+   </para>
+
+ </section>
+
+ <section>
+ <title>Overriding Construction Variables</title>
+
+   <para>
+
+   X
+
+   </para>
+
+ </section>
+
+ <section>
+ <title>The &SCONSFLAGS; Environment Variable</title>
+
+   <para>
+
+   X
+
+   </para>
+
+ </section>
diff --git a/doc/user/scanners.sgml b/doc/user/scanners.sgml
new file mode 100644
index 0000000..2514e74
--- /dev/null
+++ b/doc/user/scanners.sgml
@@ -0,0 +1,21 @@
+<!--
+
+  Copyright 2001 Steven Knight
+
+-->
+ <para>
+
+   X
+
+ </para>
+
+ <section>
+ <title>X</title>
+
+   <para>
+
+   X
+
+   </para>
+
+ </section>
diff --git a/doc/user/simple.sgml b/doc/user/simple.sgml
new file mode 100644
index 0000000..eef6b45
--- /dev/null
+++ b/doc/user/simple.sgml
@@ -0,0 +1,87 @@
+<!--
+
+  Copyright 2001 Steven Knight
+
+-->
+ <para>
+
+   X
+
+ </para>
+
+ <section>
+ <title>The &SConstruct; File</title>
+
+   <para>
+
+   X
+
+   </para>
+
+ </section>
+
+ <section>
+ <title>The &Program; Builder</title>
+
+   <para>
+
+   X
+
+   </para>
+
+ </section>
+
+ <section>
+ <title>The &Library; Builder</title>
+
+   <para>
+
+   X
+
+   </para>
+
+ </section>
+
+ <section>
+ <title>The &Install; Builder</title>
+
+   <para>
+
+   X
+
+   </para>
+
+ </section>
+
+ <section>
+ <title>Running &SCons;</title>
+
+   <para>
+
+   X
+
+   </para>
+
+ </section>
+
+ <section>
+ <title>The &Default; Method</title>
+
+   <para>
+
+   X
+
+   </para>
+
+ </section>
+
+ <section>
+ <title>The &Help; Method</title>
+
+   <para>
+
+   X
+
+   </para>
+
+ </section>
diff --git a/doc/user/troubleshoot.sgml b/doc/user/troubleshoot.sgml
new file mode 100644
index 0000000..2514e74
--- /dev/null
+++ b/doc/user/troubleshoot.sgml
@@ -0,0 +1,21 @@
+<!--
+
+  Copyright 2001 Steven Knight
+
+-->
+ <para>
+
+   X
+
+ </para>
+
+ <section>
+ <title>X</title>
+
+   <para>
+
+   X
+
+   </para>
+
+ </section>
diff --git a/doc/user/variants.sgml b/doc/user/variants.sgml
new file mode 100644
index 0000000..2514e74
--- /dev/null
+++ b/doc/user/variants.sgml
@@ -0,0 +1,21 @@
+<!--
+
+  Copyright 2001 Steven Knight
+
+-->
+ <para>
+
+   X
+
+ </para>
+
+ <section>
+ <title>X</title>
+
+   <para>
+
+   X
+
+   </para>
+
+ </section>