tutorial: add some clarifying comments

... on parts a first-time reader might (and actually did) stumble upon.

4 files changed, 48 insertions, 21 deletions

diff --git a/doc/tutorial/hello-world.org b/doc/tutorial/hello-world.org
index 28503545..fbe7093b 100644
--- a/doc/tutorial/hello-world.org
+++ b/doc/tutorial/hello-world.org
@@ -50,7 +50,13 @@ In that configuration, two repositories are defined:
     needed to build the target. These rules are bound via the open name
     ~"rules"~ to the just created repository ~"just-rules"~. In this way, the
     entities provided by ~"just-rules"~ can be accessed from within the
-    ~"tutorial"~ repository via ~["@", "rules", "<module>", "<rule>"]~.
+    ~"tutorial"~ repository via the fully-qualified name
+    ~["@", "rules", "<module>", "<name>"]~; fully-qualified
+    names (for rules, targets to build (like libraries, binaries),
+    etc) are given by a repository name, a path specifying a
+    directory within that repository (the "module") where the
+    specification file is located, and a symbolic name (i.e., an
+    arbitrary string that is used as key in the specification).
 
 The final repository configuration contains a single ~JSON~ object with the key
 ~"repositories"~ referring to an object of repository names as keys and
@@ -75,7 +81,10 @@ binary from the C++ source ~main.cpp~. To define such a target, create a
 
 The ~"type"~ field refers to the rule ~"binary"~ from the module ~"CC"~ of the
 ~"rules"~ repository. This rule additionally requires the string field ~"name"~,
-which specifies the name of the binary to produce. Furthermore, at least one
+which specifies the name of the binary to produce; as the generic interface of
+rules is to have fields either take a list of strings or a list of targets,
+we have to sepcify the name as a list (this rule will simply concatenate all
+strings given in this field). Furthermore, at least one
 input to the binary is required, which can be specified via the target fields
 ~"srcs"~ or ~"deps"~. In our case, the former is used, which contains our single
 source file (files are considered targets).
@@ -158,8 +167,8 @@ $
 To define a custom set of defaults (toolchain and compile flags) for your
 project, you need to create a separate file root for providing required
 ~TARGETS~ file, which contains the ~"defaults"~ target that should be used by
-the rules. This file root is then used as the /target root/ for the rules (i.e.,
-the search path for ~TARGETS~ files). In this way, the description of the
+the rules. This file root is then used as the /target root/ for the rules, i.e.,
+the search path for ~TARGETS~ files. In this way, the description of the
 ~"defaults"~ target is provided in a separate file root, to keep the rules
 repository independent of these definitions.
 
@@ -172,7 +181,9 @@ $ mkdir -p ./tutorial-defaults/CC
 
 In that module, we need to create the file ~tutorial-defaults/CC/TARGETS~ that
 contains the target ~"defaults"~ and specifies which toolchain and compile flags
-to use:
+to use; it has to specify the complete toolchain, but can specify a ~"base"~
+toolchain to inherit from. In our case, we don't use any base, but specify all
+the required fields directly.
 
 #+SRCNAME: tutorial-defaults/CC/TARGETS
 #+BEGIN_SRC js
@@ -283,8 +294,10 @@ the consumer of this library can expect to find the library's artifacts. Note
 that this does not need to reflect the location on the file system (i.e., a
 full-qualified path like ~["com", "example", "utils", "greet"]~ could be used to
 distinguish it from greeting libraries of other projects). The staging directory
-does not only affect the main artifact ~libgreet.a~ but also it's runfiles;
-hence, the public header will be staged to ~"greet/greet.hpp"~. With that
+does not only affect the main artifact ~libgreet.a~ but also it's /runfiles/,
+a second set of artifacts, usually those a consumer needs to make proper use the
+actual artifact; in the case of a libary, the runfiles are its public headers.
+Hence, the public header will be staged to ~"greet/greet.hpp"~. With that
 knowledge, we can now perform the necessary modifications to ~main.cpp~:
 
 #+SRCNAME: main.cpp
diff --git a/doc/tutorial/proto.org b/doc/tutorial/proto.org
index c8ccc5fe..70950868 100644
--- a/doc/tutorial/proto.org
+++ b/doc/tutorial/proto.org
@@ -285,7 +285,7 @@ $
 #+END_SRC
 
 It should be noted, however, that this tight integration of proto
-into our ~C++~ rules is just convenience of our code base. If had
+into our ~C++~ rules is just convenience of our code base. If we had
 to cooperate with rules not aware of proto, we could have created
 a separate rule delegating the library creation to the anonymous
 target and then simply reflecting the values of that target.
diff --git a/doc/tutorial/target-file-glob-tree.org b/doc/tutorial/target-file-glob-tree.org
index c0b8c6ed..bc1d388d 100644
--- a/doc/tutorial/target-file-glob-tree.org
+++ b/doc/tutorial/target-file-glob-tree.org
@@ -379,7 +379,8 @@ INFO: Artifacts built, logical paths are:
 $
 #+END_SRC
 
-To finish the example, we also add a default target, staging
+To finish the example, we also add a default target (using that, if no target
+is specified, ~just~ builds the lexicographically first target), staging
 artifacts according to the usual conventions.
 
 #+BEGIN_SRC js
diff --git a/doc/tutorial/tests.org b/doc/tutorial/tests.org
index 7bbcf66c..f8ad0f6d 100644
--- a/doc/tutorial/tests.org
+++ b/doc/tutorial/tests.org
@@ -1,12 +1,21 @@
 * Creating Tests
 
-To run tests with justbuild, we do /not/ have dedicated ~test~ subcommand.
-Instead, we consider tests being a specific action that generates a test report.
-Consequently, we use the ~build~ subcommand to build the test report, and
-thereby run the test action. Those actions have to be tainted, in our case with
-the string ~"test"~, causing that they can only be depended on by other targets
-that are also tainted with ~"test"~. In this way, it is ensured that no test
-target will end up in a production build.
+To run tests with justbuild, we do /not/ have dedicated ~test~
+subcommand. Instead, we consider tests being a specific action that
+generates a test report. Consequently, we use the ~build~ subcommand
+to build the test report, and thereby run the test action. Test
+actions, however, are slightly different from normal actions in
+that we don't want the build of the test report to be aborted if
+a test action fails (but still, we want only successfully actions
+taken from cache). Rules defining targets containing such special
+actions have to identify themselves as /tainted/ by specifying
+a string explaining why such special actions are justified; in
+our case, the string is ~"test"~. Besides the implicit marking by
+using a tainted rule, those tainting strings can also be explicitly
+assigned by the user in the definition of a target, e.g., to mark
+test data. Any target has to be tainted with (at least) all the
+strings any of its dependencies is tainted with. In this way, it
+is ensured that no test target will end up in a production build.
 
 For the remainder of this section, we expect to have the project files available
 resulting from successfully completing the tutorial section on /Building Hello
@@ -118,7 +127,7 @@ The result of the test target are 5 artifacts: ~result~ (containing ~UNKNOWN~,
 ~PASS~, or ~FAIL~), ~stderr~, ~stdout~, ~time-start~, and ~time-stop~, and a
 single runfile (omitted in the output above), which is a tree artifact with the
 name ~test_greet~ that contains all of the above artifacts. The test was run
-successfully as otherwise all reported artifacts would have been tagged with
+successfully as otherwise all reported artifacts would have been reported as
 ~FAILED~ in the output, and justbuild would have returned the exit code ~2~.
 
 To immediately print the standard output produced by the test binary on the
@@ -276,12 +285,16 @@ The result is also similar, containing also the 5 artifacts and a single runfile
 
 As most people probably do not want to call every test target by hand, it is
 desirable to compound test target that triggers the build of multiple test
-reports. To do so, an ~"install"~ target can be used. It depends on the tests
-that should be triggered and collects the runfiles of those (which happen to be
-tree artifacts named the same way as the test and containing all test results).
+reports. To do so, an ~"install"~ target can be used. The field ~"deps"~ of
+an install target is a list of targets for which the runfiles are collected.
+As for the tests the runfiless happen to be
+tree artifacts named the same way as the test and containing all test results,
+this is precisely what we need.
 Furthermore, as the dependent test targets are tainted by ~"test"~, also the
 compound test target must be tainted by the same string. To create the compound
-test target combining the two tests above, add the following to the top-level
+test target combining the two tests above (the test ~"test"~ from the current
+module and ~["greet", "test"]~, i.e., the target ~"test"~ from the module
+~"greet"~) add the following to the top-level
 ~TARGETS~ file:
 
 #+BEGIN_SRC js