- Rollback of changes for revision 5355 (Additional chapter for User Guide, Basic steps)

13 files changed, 10 insertions, 414 deletions

diff --git a/doc/user/MANIFEST b/doc/user/MANIFEST
index 3f9eda3..0994f2b 100644
--- a/doc/user/MANIFEST
+++ b/doc/user/MANIFEST
@@ -40,7 +40,6 @@ sconf.xml
 separate.xml
 simple.xml
 sourcecode.xml
-start.xml
 tasks.xml
 tools.xml
 troubleshoot.xml
diff --git a/doc/user/depends.in b/doc/user/depends.in
index de5eb42..88828fe 100644
--- a/doc/user/depends.in
+++ b/doc/user/depends.in
@@ -914,7 +914,7 @@
 
   </section>
 
-  <section id="sect-implicit-dependencies">
+  <section>
   <title>Implicit Dependencies:  The &cv-CPPPATH; Construction Variable</title>
 
     <para>
diff --git a/doc/user/depends.xml b/doc/user/depends.xml
index c423172..a5e84d6 100644
--- a/doc/user/depends.xml
+++ b/doc/user/depends.xml
@@ -903,7 +903,7 @@
 
   </section>
 
-  <section id="sect-implicit-dependencies">
+  <section>
   <title>Implicit Dependencies:  The &cv-CPPPATH; Construction Variable</title>
 
     <para>
diff --git a/doc/user/environments.in b/doc/user/environments.in
index e74ffac..f767676 100644
--- a/doc/user/environments.in
+++ b/doc/user/environments.in
@@ -1095,7 +1095,7 @@ environment, of directory names, suffixes, etc.
 
     </section>
 
-    <section id="sect-clone-environments">
+    <section>
     <title>Making Copies of &ConsEnvs;:  the &Clone; Method</title>
 
       <para>
diff --git a/doc/user/environments.xml b/doc/user/environments.xml
index 73d84d3..b2a8505 100644
--- a/doc/user/environments.xml
+++ b/doc/user/environments.xml
@@ -1089,7 +1089,7 @@ environment, of directory names, suffixes, etc.
 
     </section>
 
-    <section id="sect-clone-environments">
+    <section>
     <title>Making Copies of &ConsEnvs;:  the &Clone; Method</title>
 
       <para>
diff --git a/doc/user/hierarchy.in b/doc/user/hierarchy.in
index b423465..d70633d 100644
--- a/doc/user/hierarchy.in
+++ b/doc/user/hierarchy.in
@@ -478,7 +478,7 @@ make no difference to the build.
 
   </section>
 
-  <section id="sect-sharing-environments">
+  <section>
   <title>Sharing Environments (and Other Variables) Between &SConscript; Files</title>
 
     <para>
diff --git a/doc/user/hierarchy.xml b/doc/user/hierarchy.xml
index baf8065..2e2941c 100644
--- a/doc/user/hierarchy.xml
+++ b/doc/user/hierarchy.xml
@@ -442,7 +442,7 @@ make no difference to the build.
 
   </section>
 
-  <section id="sect-sharing-environments">
+  <section>
   <title>Sharing Environments (and Other Variables) Between &SConscript; Files</title>
 
     <para>
diff --git a/doc/user/main.in b/doc/user/main.in
index 2e3683f..4b0807d 100644
--- a/doc/user/main.in
+++ b/doc/user/main.in
@@ -152,11 +152,6 @@
     &build-install;
   </chapter>
 
-   <chapter id="chap-start">
-     <title>Basic steps and advice</title>
-     &start;
-  </chapter>
-
   <chapter id="chap-simple">
     <title>Simple Builds</title>
     &simple;
diff --git a/doc/user/main.xml b/doc/user/main.xml
index ccc3208..4b0807d 100644
--- a/doc/user/main.xml
+++ b/doc/user/main.xml
@@ -85,7 +85,6 @@
     <!ENTITY sconf SYSTEM "sconf.xml">
     <!ENTITY separate SYSTEM "separate.xml">
     <!ENTITY simple SYSTEM "simple.xml">
-    <!ENTITY start SYSTEM "start.xml">
     <!ENTITY sourcecode SYSTEM "sourcecode.xml">
     <!ENTITY tasks SYSTEM "tasks.xml">
     <!ENTITY tools SYSTEM "tools.xml">
@@ -153,11 +152,6 @@
     &build-install;
   </chapter>
 
-  <chapter id="chap-start">
-    <title>Basic steps and advice</title>
-    &start;
-  </chapter>
-
   <chapter id="chap-simple">
     <title>Simple Builds</title>
     &simple;
diff --git a/doc/user/simple.in b/doc/user/simple.in
index 373d2b8..8a25be5 100644
--- a/doc/user/simple.in
+++ b/doc/user/simple.in
@@ -297,7 +297,7 @@
 
  </section>
 
- <section id="sect-sconstruct-file">
+ <section>
  <title>The &SConstruct; File</title>
 
    <para>
@@ -353,7 +353,7 @@
 
    </section>
 
-   <section id="sect-order-independent">
+   <section>
    <title>&SCons; Functions Are Order-Independent</title>
 
      <para>
diff --git a/doc/user/simple.xml b/doc/user/simple.xml
index e24ecbd..2a687a0 100644
--- a/doc/user/simple.xml
+++ b/doc/user/simple.xml
@@ -322,7 +322,7 @@
 
  </section>
 
- <section id="sect-sconstruct-file">
+ <section>
  <title>The &SConstruct; File</title>
 
    <para>
@@ -378,7 +378,7 @@
 
    </section>
 
-   <section id="sect-order-independent">
+   <section>
    <title>&SCons; Functions Are Order-Independent</title>
 
      <para>
diff --git a/doc/user/start.in b/doc/user/start.in
deleted file mode 100644
index 3d1693b..0000000
--- a/doc/user/start.in
+++ /dev/null
@@ -1,196 +0,0 @@
-<!--
-
-  __COPYRIGHT__
-
-  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.
-
--->
-
- <para>
-
-If you're completely new to a build system like &SCons;, this chapter is written for you.
-We very briefly discuss the general setup of your project, regarding the &SCons; configuration
-files &SConstruct; and &SConscript;.
-Additionally, a few guidelines are provided about how to start a project...hopefully preventing you from
-running into dead-end after dead-end later on.
-
- </para>
-
- <section>
- <title>SCons files</title>
-   <para>
-Okay, so you have a version of your shiny new project, ready for its very first &SCons; build. Or maybe you decided
-to drop make/autotools, and want to try out &SCons; on the cool media-message-mailing library that you already provide
-on Sourceforge (Tigris, Github, Bitbucket, Launchpad...).
-</para>
-<para>
-Let's say you have a source folder in your file system, a directory with all the input files for the build process.
-These may be C or C++ files, TeX/LaTeX sources or a Java package tree. For a start we also assume that you want the
-resulting files, like libs, executables, JARs and PDFs, to be created in the same folder structure. Alongside your
-sources, so to speak.
-</para>
-<para>
-In order to get &SCons; going you have to give it your input files and tell it what to build. Like in most build systems,
-this is done by writing a special text file (or several of them) further describing your build setup. You place this
-file, named &SConstruct; (see <xref linkend="chap-simple"></xref>), at the top of your source folder tree:
-</para>
-<screen>
-yoursrc
-    yourlib1
-        *.cpp/h
-    yourlib2
-        *.cpp/h
-    yourexe
-        *.cpp/h
-    README
-    INSTALL
-    SConstruct
-</screen>
-<para>
-To start a build, you open a terminal (text console, prompt, shell,...whatever it is called in your current system) and
-change into the folder with the &SConstruct; in it. Having &SCons; properly installed (see <xref linkend="chap-build-install"></xref>), you call the command
-</para>
-   <screen>
-      % <userinput>scons</userinput>
-   </screen>
-<para>
-and the processing starts. &SCons; reads your &SConstruct; and starts to build things for you, hopefully.
-</para>
-<para>
-So much for a very quick start and the basics about how to get &SCons; going.
-A discussion of &SCons; at great length can be found in the following
-chapters and sections. Read on please, to learn more about all the available features and possibilities...
-</para>
-
- </section>
-
- <section>
- <title>A few additional guidelines</title>
-
-   <para>
-   With &SCons; and the power of Python as backup, you are pretty much free to do anything
-   you like. However, when you start without any prior experience a few pointers might
-   help as a good foundation for your work. That's exactly what the following list is there
-   for. A few best practices and you can have your pick...or roll your own stuff.
-   </para>
-
-   <itemizedlist>
-
-    <listitem>
-      <para><emphasis>Think in modules</emphasis>: Try to create an &SConscript; for
-        each subfolder, containing one of your libs or executables.
-        Then, call these &SConscript;s from a single &SConstruct; at the top of your
-        build directory.
-      </para>
-      <para>
-        From what our experience tells us, this is the setup that offers you the most flexibility
-        regarding build options and variant dirs. It may look a bit complicated and overdone
-        right now, but starting this way pays off really fast.
-      </para>
-      <para>
-A simple example:
-      </para>
- <screen>
-yoursrc
-    yourlib1
-        SConscript
-        *.cpp/h
-    yourlib2
-        SConscript
-        *.cpp/h
-    SConstruct
-</screen>
-<para>
-would include the &SConscript;s by
-</para>
-<screen>
-SConscript(['yourlib1/SConscript'])
-SConscript(['yourlib2/SConscript'])
-</screen>
-<para>
-in the &SConstruct;.
-</para>
-<para>Check out <xref linkend="sect-sconstruct-file"></xref> and <xref linkend="chap-hierarchical"></xref> for more infos about this.
-</para>
-   </listitem>
-
-    <listitem>
-      <para><emphasis>Configure at the top and reuse</emphasis>: Configure the environments that you
-        need, in your &SConstruct; file at the very top of your build tree.
-        Don't create them anew in each &SConscript; (module) but export them globally
-        and use Clone() to make a local copy where required.
-      </para>
-      <para>
-        In your &SConstruct; at the top you can create and export a basic Environment as:
-<screen>
-env = Environment(tools=['default'], CC='/opt/arm-gcc_4.01/bin/gcc')
-Export('env')
-</screen>
-        and access it in one of your &SConscript;s by:
-<screen>
-Import('env')
-debug_env = env.Clone()
-debug_env.Append(CCFLAGS=['-g'])
-debug_env.Program('foo','foo.c')
-</screen>
-</para>
-<para>
-Pointers to more info are <xref linkend="chap-environments"></xref>, 
-especially <xref linkend="sect-construction-environments"></xref> and 
-<xref linkend="sect-clone-environments"></xref>, as well as <xref linkend="sect-sharing-environments"></xref>.
-      </para>
-    </listitem>
-    <listitem>
-      <para><emphasis>Think in dependencies</emphasis>: &SCons; works by knowing dependencies. Internally,
-        it builds a large dependency
-        graph (DAG, <emphasis>directed acyclic graph</emphasis>) for all its build tasks. The single
-        files are managed as nodes, while the edges represent the build dependencies.
-        No dependency, no build. It's that simple.
-        Try to forget about those phony targets, that you may have used all throughout <literal>make</literal> (shudder).
-        Check out this User manual, or ask for help on the &SCons; mailing lists. Don't fall back to those
-        bad old habits and hack around, only because you're under time pressure. Try to do your builds the &SCons; way!
-      </para>
-      <para>
-       <xref linkend="chap-depends"></xref>, <xref linkend="sect-implicit-dependencies"></xref>,
-       <xref linkend="chap-builders-writing"></xref>, and <xref linkend="chap-scanners"></xref>
-       will tell you more about how dependencies work in &SCons; and can be bent
-       the way you want them.
-      </para>
-    </listitem>
-    <listitem>
-      <para><emphasis>Don't serialize</emphasis>: Finally, &SCons; is all about handling large projects with complicated builds. It is specially
-        optimized for working in parallel, and schedules all the single build tasks automatically.
-        This means that you can't easily get &SCons; to execute some scripts <literal>A</literal> and <literal>B</literal> in a predefined sequence (cf. <xref linkend="sect-order-independent"></xref>).
-        If you want to define a simple series of build tasks, that have to get executed in a fixed order regardless
-        of dependencies and timestamps, you should consider to use a simple shell or Python script as
-        wrapper instead.
-        Don't hurt your brain, while trying to force &SCons; into doing something that it wasn't designed for in the
-        first place.
-      </para>
-      <para>
-       &SCons; supports building multiple targets in parallel via a <literal>-j</literal> option that
-       takes, as its argument, the number of simultaneous tasks that may be
-       spawned: <quote><literal>scons -j 4</literal></quote> builds four targets
-       in parallel, for example.
-      </para>
-    </listitem>
-   </itemizedlist>
-
- </section>
diff --git a/doc/user/start.xml b/doc/user/start.xml
deleted file mode 100644
index 3d1693b..0000000
--- a/doc/user/start.xml
+++ /dev/null
@@ -1,196 +0,0 @@
-<!--
-
-  __COPYRIGHT__
-
-  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.
-
--->
-
- <para>
-
-If you're completely new to a build system like &SCons;, this chapter is written for you.
-We very briefly discuss the general setup of your project, regarding the &SCons; configuration
-files &SConstruct; and &SConscript;.
-Additionally, a few guidelines are provided about how to start a project...hopefully preventing you from
-running into dead-end after dead-end later on.
-
- </para>
-
- <section>
- <title>SCons files</title>
-   <para>
-Okay, so you have a version of your shiny new project, ready for its very first &SCons; build. Or maybe you decided
-to drop make/autotools, and want to try out &SCons; on the cool media-message-mailing library that you already provide
-on Sourceforge (Tigris, Github, Bitbucket, Launchpad...).
-</para>
-<para>
-Let's say you have a source folder in your file system, a directory with all the input files for the build process.
-These may be C or C++ files, TeX/LaTeX sources or a Java package tree. For a start we also assume that you want the
-resulting files, like libs, executables, JARs and PDFs, to be created in the same folder structure. Alongside your
-sources, so to speak.
-</para>
-<para>
-In order to get &SCons; going you have to give it your input files and tell it what to build. Like in most build systems,
-this is done by writing a special text file (or several of them) further describing your build setup. You place this
-file, named &SConstruct; (see <xref linkend="chap-simple"></xref>), at the top of your source folder tree:
-</para>
-<screen>
-yoursrc
-    yourlib1
-        *.cpp/h
-    yourlib2
-        *.cpp/h
-    yourexe
-        *.cpp/h
-    README
-    INSTALL
-    SConstruct
-</screen>
-<para>
-To start a build, you open a terminal (text console, prompt, shell,...whatever it is called in your current system) and
-change into the folder with the &SConstruct; in it. Having &SCons; properly installed (see <xref linkend="chap-build-install"></xref>), you call the command
-</para>
-   <screen>
-      % <userinput>scons</userinput>
-   </screen>
-<para>
-and the processing starts. &SCons; reads your &SConstruct; and starts to build things for you, hopefully.
-</para>
-<para>
-So much for a very quick start and the basics about how to get &SCons; going.
-A discussion of &SCons; at great length can be found in the following
-chapters and sections. Read on please, to learn more about all the available features and possibilities...
-</para>
-
- </section>
-
- <section>
- <title>A few additional guidelines</title>
-
-   <para>
-   With &SCons; and the power of Python as backup, you are pretty much free to do anything
-   you like. However, when you start without any prior experience a few pointers might
-   help as a good foundation for your work. That's exactly what the following list is there
-   for. A few best practices and you can have your pick...or roll your own stuff.
-   </para>
-
-   <itemizedlist>
-
-    <listitem>
-      <para><emphasis>Think in modules</emphasis>: Try to create an &SConscript; for
-        each subfolder, containing one of your libs or executables.
-        Then, call these &SConscript;s from a single &SConstruct; at the top of your
-        build directory.
-      </para>
-      <para>
-        From what our experience tells us, this is the setup that offers you the most flexibility
-        regarding build options and variant dirs. It may look a bit complicated and overdone
-        right now, but starting this way pays off really fast.
-      </para>
-      <para>
-A simple example:
-      </para>
- <screen>
-yoursrc
-    yourlib1
-        SConscript
-        *.cpp/h
-    yourlib2
-        SConscript
-        *.cpp/h
-    SConstruct
-</screen>
-<para>
-would include the &SConscript;s by
-</para>
-<screen>
-SConscript(['yourlib1/SConscript'])
-SConscript(['yourlib2/SConscript'])
-</screen>
-<para>
-in the &SConstruct;.
-</para>
-<para>Check out <xref linkend="sect-sconstruct-file"></xref> and <xref linkend="chap-hierarchical"></xref> for more infos about this.
-</para>
-   </listitem>
-
-    <listitem>
-      <para><emphasis>Configure at the top and reuse</emphasis>: Configure the environments that you
-        need, in your &SConstruct; file at the very top of your build tree.
-        Don't create them anew in each &SConscript; (module) but export them globally
-        and use Clone() to make a local copy where required.
-      </para>
-      <para>
-        In your &SConstruct; at the top you can create and export a basic Environment as:
-<screen>
-env = Environment(tools=['default'], CC='/opt/arm-gcc_4.01/bin/gcc')
-Export('env')
-</screen>
-        and access it in one of your &SConscript;s by:
-<screen>
-Import('env')
-debug_env = env.Clone()
-debug_env.Append(CCFLAGS=['-g'])
-debug_env.Program('foo','foo.c')
-</screen>
-</para>
-<para>
-Pointers to more info are <xref linkend="chap-environments"></xref>, 
-especially <xref linkend="sect-construction-environments"></xref> and 
-<xref linkend="sect-clone-environments"></xref>, as well as <xref linkend="sect-sharing-environments"></xref>.
-      </para>
-    </listitem>
-    <listitem>
-      <para><emphasis>Think in dependencies</emphasis>: &SCons; works by knowing dependencies. Internally,
-        it builds a large dependency
-        graph (DAG, <emphasis>directed acyclic graph</emphasis>) for all its build tasks. The single
-        files are managed as nodes, while the edges represent the build dependencies.
-        No dependency, no build. It's that simple.
-        Try to forget about those phony targets, that you may have used all throughout <literal>make</literal> (shudder).
-        Check out this User manual, or ask for help on the &SCons; mailing lists. Don't fall back to those
-        bad old habits and hack around, only because you're under time pressure. Try to do your builds the &SCons; way!
-      </para>
-      <para>
-       <xref linkend="chap-depends"></xref>, <xref linkend="sect-implicit-dependencies"></xref>,
-       <xref linkend="chap-builders-writing"></xref>, and <xref linkend="chap-scanners"></xref>
-       will tell you more about how dependencies work in &SCons; and can be bent
-       the way you want them.
-      </para>
-    </listitem>
-    <listitem>
-      <para><emphasis>Don't serialize</emphasis>: Finally, &SCons; is all about handling large projects with complicated builds. It is specially
-        optimized for working in parallel, and schedules all the single build tasks automatically.
-        This means that you can't easily get &SCons; to execute some scripts <literal>A</literal> and <literal>B</literal> in a predefined sequence (cf. <xref linkend="sect-order-independent"></xref>).
-        If you want to define a simple series of build tasks, that have to get executed in a fixed order regardless
-        of dependencies and timestamps, you should consider to use a simple shell or Python script as
-        wrapper instead.
-        Don't hurt your brain, while trying to force &SCons; into doing something that it wasn't designed for in the
-        first place.
-      </para>
-      <para>
-       &SCons; supports building multiple targets in parallel via a <literal>-j</literal> option that
-       takes, as its argument, the number of simultaneous tasks that may be
-       spawned: <quote><literal>scons -j 4</literal></quote> builds four targets
-       in parallel, for example.
-      </para>
-    </listitem>
-   </itemizedlist>
-
- </section>