Add an outline for a User's Guide.

20 files changed, 908 insertions, 0 deletions

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>