From f2a56f1c612ec4113246740004e6eb529586a09b Mon Sep 17 00:00:00 2001
From: Josh Holtrop <jholtrop@gmail.com>
Date: Sun, 30 Jan 2022 12:46:38 -0500
Subject: [PATCH] More user guide updates for tasks

---
 doc/user_guide.md | 42 +++++++++++++++++++++++++++++-------------
 1 file changed, 29 insertions(+), 13 deletions(-)

diff --git a/doc/user_guide.md b/doc/user_guide.md
index 37336b8..39302f5 100644
--- a/doc/user_guide.md
+++ b/doc/user_guide.md
@@ -358,9 +358,9 @@ It will not remove all built target files, just the installed copies.
 
 ##> Configuring the Project
 
-A `configure` block is optional.
-It can be used to perform various checks and setup operations for a project.
-Example `configure` block:
+Configure task actions can be used to perform various checks and setup
+operations for a project.
+Example `configure` action block:
 
 ```ruby
 configure do
@@ -369,6 +369,17 @@ configure do
 end
 ```
 
+If any configure task action blocks are present, they will be execute when the
+configure operation is performed.
+This happens if the user requests the `configure` task from the command line.
+It also happens if all of the following are true:
+
+  * The project has not yet been configured.
+  * A task that does not have `autoconf` set to `false` is being executed.
+  * The global `autoconf` setting has not been set to `false`.
+
+See ${#Configure Task} for more information about `autoconf`.
+
 ###> Checking for a Compiler
 
 The following methods can be used within a `configure` block to check for a
@@ -619,10 +630,12 @@ If set, a build define of the specified String will be added to the
 
 ##> Building Targets
 
-The `build` block is used to create Environments and register build targets.
-An Rscons build script would not be very useful without a `build` block.
+Building target files is accomplished by using Environments.
+Environments are typically created within the default task or any user-defined
+tasks.
 
-Here is an example `build` block demonstrating how to register a build target:
+Here is an example `default` task block demonstrating how to create an
+Environment and register a build target:
 
 ```ruby
 default do
@@ -1050,7 +1063,7 @@ In other words, build targets are not parallelized across a barrier.
 env.barrier
 ```
 
-##> Other Build Script Methods
+##> Build Script Methods
 
 `rscons` provides several methods that a build script can use.
 
@@ -1101,9 +1114,12 @@ module are made available for the build script to call directly:
 
 ###> Finding Files: The glob Method
 
-The [`glob`](../yard/Rscons/Script/GlobalDsl.html#glob-instance_method) method can be
-used to find files matching the patterns specified.
-It supports a syntax similar to the Ruby [Dir.glob method](https://ruby-doc.org/core-3.1.0/Dir.html#method-c-glob) but operates more deterministically.
+The [`glob`](../yard/Rscons/Script/GlobalDsl.html#glob-instance_method) method
+can be used to find files matching the patterns specified.
+It supports a syntax similar to the Ruby
+[Dir.glob method](https://ruby-doc.org/core-3.1.0/Dir.html#method-c-glob)
+but operates more deterministically (results are ordered based on file names
+rather than file system directory ordering).
 
 Example use:
 
@@ -1166,7 +1182,7 @@ configure do
   rscons "subproject", "configure"
 end
 
-default do
+task "build" do
   rscons "subproject/Rsconscript", "build"
 end
 ```
@@ -1596,8 +1612,8 @@ end
 default do
   Environment.new do |env|
     env["CFLAGS"] = ["-O3", "-Wall"]
-    env.add_build_hook do |build_op|
-      if build_op[:target] =~ %r{build/third-party}
+    env.add_build_hook do |builder|
+      if builder.sources.first =~ %r{src/third-party/}
         build_op[:vars]["CFLAGS"] -= ["-Wall"]
       end
     end