documentation maintenance

doc/src/bjam.adoc

@@ -303,7 +303,7 @@ used to make a record of that directory.
 === Rules
 
 The basic `b2` language entity is called a rule. A rule is defined in
-two parts: the procedure and the actions. The procedure is a body of jam
+two parts: the procedure and the actions. The procedure is a body of Jam
 statements to be run when the rule is invoked; the actions are the OS
 shell commands to execute when updating the built targets of the rule.
 
@@ -450,14 +450,14 @@ cause `b2` to exit with an error code:
 
 [source]
 ----
-### argument error
-# rule report ( pronoun index ?  : state  : names + )
-# called with: ( I 2 foo  : sorry  : Joe Dave Pete )
-# extra argument foo
-### argument error
-# rule report ( pronoun index ?  : state  : names + )
-# called with: ( I 2  : sorry )
-# missing argument names
+...
+error: rule report ( pronoun index ?  : state  : names + )
+error: called with: ( I 2 foo  : sorry  : Joe Dave Pete )
+error: extra argument foo
+...
+error: rule report ( pronoun index ?  : state  : names + )
+error: called with: ( I 2  : sorry )
+error: missing argument names
 ----
 
 If you omit the list of formal arguments, all checking is bypassed as in
@@ -748,7 +748,8 @@ The `GLOB_ARCHIVE` rule does name globing of object archive members.
 
 [source]
 ----
-rule GLOB_ARCHIVE ( archives * : member-patterns * : downcase-opt ? : symbol-patterns ? )
+rule GLOB_ARCHIVE ( archives * : member-patterns *
+                  : downcase-opt ? : symbol-patterns ? )
 ----
 
 Similarly to `GLOB`, this rule is used to match names of member files in
@@ -887,6 +888,27 @@ rule SPLIT_BY_CHARACTERS ( string : delimiters )
 `SPLIT_BY_CHARACTERS` splits the specified _string_ on any delimiter
 character present in _delimiters_ and returns the resulting list.
 
+[[jam.language.rules.builtins.utility._subst__]]
+===== `SUBST`
+
+The `SUBST` rule does pattern matching and substitution.
+
+[source]
+----
+rule SUBST ( string regexp replacements + )
+----
+
+Replaces the _string_ matching the _regexp_ with all _replacements_.
+The _regexp_ argument accepts a regular expression of the same type
+as those used by the `MATCH` rule.
+In _replacements_, the placeholders `\0` and `$0` are replaced with the full
+matched string, while `\N` and `$N` are replaced with the substring matched
+by group (`()` regexp subexpression) N-th.  Currently only 9 groups are
+supported, so '$10' in a replacement is interpreted as '$1' followed by
+a '0' character.
+Note that unlike `MATCH`, _regexp_ does not have to contain a group
+for a result to be returned.
+
 [[jam.language.rules.builtins.utility._update__]]
 ===== `UPDATE`
 
@@ -895,7 +917,7 @@ character present in _delimiters_ and returns the resulting list.
 rule UPDATE ( targets * )
 ----
 
-Classic jam treats any non-option element of command line as a name of
+Classic Jam treats any non-option element of command line as a name of
 target to be updated. This prevented more sophisticated handling of
 command line. This is now enabled again but with additional changes to
 the `UPDATE` rule to allow for the flexibility of changing the list of
@@ -1786,7 +1808,8 @@ have not returned at the time of the `VARNAMES` invocation.
 [source]
 ----
 rule IMPORT ( source_module ? : source_rules *
-            : target_module ? : target_rules * )
+            : target_module ? : target_rules *
+            : localize ? )
 ----
 
 The `IMPORT` rule copies rules from the _source_module_ into the
@@ -1806,6 +1829,11 @@ IMPORT m1 : rule1 : m2 : m1-rule1 ;
 IMPORT m1 : [ RULENAMES m1 ] : m2 : [ RULENAMES m1 ] ;
 ----
 
+If _localize_ is supplied _target_rules_ are executed in _target_module_,
+with corresponding access to that module's local variables.
+Existing rules in _target_module_ are silently overwritten by
+imported _target_rules_.
+
 [[jam.language.modules.the__export__rule]]
 ==== The `EXPORT` Rule
 
@@ -1997,7 +2025,7 @@ the file system through a process called binding. Binding is a process
 of searching for a file with the same name as the target (sans grist),
 based on the settings of the target-specific `SEARCH` and `LOCATE`
 variables.
-* In addition to local and global variables, jam allows you to set a
+* In addition to local and global variables, Jam allows you to set a
 variable `on` a target. Target-specific variable values can usually not
 be read, and take effect only in the following contexts:
 ** In updating actions, variable values are first looked up `on` the
@@ -2043,7 +2071,7 @@ the leading and trailing angle brackets. When grist is added to a name
 with `$(var:G=expr)`, existing grist is first stripped. Then, if `expr` is
 non-empty, leading <s and trailing >s are added if necessary to form an
 expression of the form <expr2>; <expr2> is then prepended.
-* When Jam is invoked it imports all environment variable settings into
+* When bjam is invoked it imports all environment variable settings into
 corresponding Jam variables, followed by all command-line (-s...)
 variable settings. Variables whose name ends in PATH, Path, or path are
 split into string lists on OS-specific path-list separator boundaries
@@ -2060,9 +2088,9 @@ MESSAGE ?\= starting jam... ;
 if $(MESSAGE) { ECHO The message is: $(MESSAGE) ; }
 ----
 +
-If the user wants a specific message, he invokes jam with
+If the user wants a specific message, he invokes bjam with
 `-sMESSAGE=message
-            text`. If he wants no message, he invokes jam with
+            text`. If he wants no message, he invokes bjam with
 `-sMESSAGE=` and nothing at all is printed.
 * The parsing of command line options in Jam can be rather unintuitive,
 with regards to how other Unix programs accept options. There are two

doc/src/debug.adoc

@@ -43,8 +43,11 @@ The `kill` command terminates the current child immediately.
 Breakpoints are set using the `break` command. The location of the
 breakpoint can be specified as either the name of a function (including
 the module name) or or a file name and line number of the form
-`file:line`. When a breakpoint is created it is given a unique id which
-is used to identify it for other commands.
+`file:line` (in this last case the line must contain a Jam statement for the
+breakpoint to be effective, a breakpoint set on an empty line or a line
+with a comment will not work.)
+When a breakpoint is created it is given a unique id which is used to
+refer it in other commands.
 
 ....
 (b2db) break Jamfile:10

doc/src/extending.adoc

@@ -18,17 +18,17 @@ metatarget::
   with a set of properties to produce concrete targets.
 concrete target::
   Object that corresponds to a file or an action.
-jam target::
+Jam target::
   Low-level concrete target that is specific to Boost.Jam build engine.
   Essentially a string -- most often a name of file.
 
 In most cases, you will only have to deal with concrete targets and the
 process that creates concrete targets from metatargets. Extending
-metatarget level is rarely required. The jam targets are typically only
+metatarget level is rarely required. The Jam targets are typically only
 used inside the command line patterns.
 
 WARNING: All of the Boost.Jam target-related builtin rules, like
-`DEPENDS` or `ALWAYS` operate on jam targets. Applying them to metatargets or
+`DEPENDS` or `ALWAYS` operate on Jam targets. Applying them to metatargets or
 concrete targets has no effect.
 
 [[b2.extender.overview.metatargets]]
@@ -126,8 +126,8 @@ local t = [ new file-target $(name) : CPP : $(project) : $(a) ] ;
 ----
 
 The first line creates an instance of the `action` class. The first
-parameter is the list of sources. The second parameter is the name a
-jam-level link:#b2.overview.jam_language.actions[action]. The third
+parameter is the list of sources. The second parameter is the name of a
+Jam-level link:#b2.overview.jam_language.actions[action]. The third
 parameter is the property-set applying to this action. The second line
 creates a target. We specify a name, a type and a project. We also pass
 the action object created earlier. If the action creates several

doc/src/faq.adoc

@@ -113,11 +113,11 @@ intention in such cases.
 
 Many users would like to use environment variables in Jamfiles, for
 example, to control the location of external libraries. In many cases it
-is better to declare those external libraries in the site-config.jam
+is better to declare those external libraries in the `site-config.jam`
 file, as documented in the link:#b2.recipes.site-config[recipes
 section]. However, if the users already have the environment variables
 set up, it may not be convenient for them to set up their
-site-config.jam files as well and using the environment variables might
+`site-config.jam` files as well and using the environment variables might
 be reasonable.
 
 Boost.Jam automatically imports all environment variables into its

doc/src/overview.adoc

@@ -217,7 +217,7 @@ This is a regular if-statement. The condition is composed of:
 
 * Literals (true if at least one string is not empty)
 * Comparisons: `a operator b` where _operator_ is one of `=`, `!=`, `<`,
-`>`, `<=` or `>=`. The comparison is done pairwise between each string
+`>`, `\<=` or `>=`. The comparison is done pairwise between each string
 in the left and the right arguments.
 * Logical operations: `! a`, `a && b`, `a || b`
 * Grouping: `( cond )`
@@ -258,7 +258,7 @@ names.
 
 [[b2.overview.jam_language.actions]]
 Sometimes, you need to specify the actual command lines to be used when
-creating targets. In the jam language, you use named actions to do this.
+creating targets. In the Jam language, you use named actions to do this.
 For example:
 
 [source]
@@ -649,7 +649,7 @@ B2 recognizes the following command line options.
   Write the updating actions to the specified file instead of running
   them.
 `-s var=value`::
-  Set the variable `var` to `value` in the global scope of the jam language
+  Set the variable `var` to `value` in the global scope of the Jam language
   interpreter, overriding variables imported from the environment.
 `--command-database=_format_`::
   Output a compile commands database as _format_. Currently _format_ can be:

doc/src/reference.adoc

@@ -604,7 +604,7 @@ _`<option-name>option-value syntax`_:
   A catalog file used to rewrite remote URL's to a local copy.
 
 The xsltproc module provides the following rules. Note that these
-operate on jam targets and are intended to be used by another toolset,
+operate on Jam targets and are intended to be used by another toolset,
 such as boostbook, rather than directly by users.
 
 `xslt`::

doc/src/sequence.adoc

@@ -3,53 +3,58 @@
 
 Various useful list functions. Note that algorithms in this module
 execute largely in the caller's module namespace, so that local rules
-can be used as function objects. Also note that most predicates can be
-multi-element lists. In that case, all but the first element are
-prepended to the first argument which is passed to the rule named by the
-first element.
+can be used as function objects (predicates.) Also note that predicates can
+be multi-element lists, any further argument to be passed is simply appended
+before the call.
 
 1. `rule filter ( predicate + : sequence * )`
 +
-Return the elements `e` of `$(sequence)` for which `[ $(predicate) e ]`
+Return the elements `e` of `sequence` for which `[ $(predicate) e ]`
 has a non-null value.
 
 2. `rule transform ( function + : sequence * )`
 +
-Return a new sequence consisting of `[ $(function) $(e) ]` for each
-element `e` of `$(sequence)`.
+Return a new sequence consisting of `[ $(function) e ]` for each
+element `e` of `sequence`.
 
 3. `rule reverse ( s * )`
 +
 Returns the elements of `s` in reverse order.
 
 4. `rule insertion-sort ( s * : ordered * )`
 +
-Insertion-sort `s` using the BinaryPredicate `ordered`.
+Insertion-sort `s` using the `ordered` predicate or
+lexicagraphically (i.e. using `<`) when no predicate is supplied.
 
 5. `rule merge ( s1 * : s2 * : ordered * )`
 +
-Merge two ordered sequences using the BinaryPredicate `ordered`.
+Merge two ordered sequences using the `ordered` predicate or
+lexicagraphically (i.e. using `<`) when no predicate is supplied.
 
-6. `rule join ( s * : joint ? )`
+6. `compare ( s1 * : s2 * : ordered * )`
 +
-Join the elements of `s` into one long string. If `joint` is supplied,
-it is used as a separator.
+Compares two sequences using the 'ordered' predicate or
+lexicagraphically (i.e. using `<`) when no predicate is supplied.
 
-7. `rule length ( s * )`
+7. `rule join ( s * : joint ? )`
++
+Join the elements of `s` using `joint` as separator if supplied.
+
+8. `rule length ( s * )`
 +
 Find the length of any sequence.
 
-8. `rule unique ( list * : stable ? )`
+9. `rule unique ( list * : stable ? )`
 +
 Removes duplicates from `list`. If `stable` is passed, then the order of
 the elements will be unchanged.
 
-9. `rule max-element ( elements + : ordered ? )`
+10. `rule max-element ( elements + : ordered ? )`
 +
 Returns the maximum number in `elements`. Uses `ordered` for comparisons
 or `numbers.less` if none is provided.
 
-10. `rule select-highest-ranked ( elements * : ranks * )`
+11. `rule select-highest-ranked ( elements * : ranks * )`
 +
 Returns all of `elements` for which the corresponding element in the
 parallel list `rank` is equal to the maximum value in `rank`.

doc/src/tasks.adoc

@@ -738,7 +738,7 @@ B2 supports automatic searching for referenced global projects. For example,
 if you have references to `/boost/predef` with some minimal configuration B2
 can find the B2 project for it and automatically resolve the reference. The
 searching supports two modes: finding regular B2 project directories, and
-package/config style loading of single jam files.
+package/config style loading of single Jam files.
 
 [[b2.tasks.projectsearch.path]]
 === Search Path
@@ -774,7 +774,7 @@ Regardless of how the search path is specified, how the search happens is the
 same. Searching involves either searching for a B2 project directory, i.e.
 a directory containing a jamfile, or searching for a specially named `*.jam`
 file to include (similar to how the <<Package Managers>> support includes
-jam files).
+Jam files).
 
 For a given _project-id_ of the form `/d1/d2/../dn` we search for the following,
 in this order:

src/engine/builtins.cpp

@@ -1291,8 +1291,8 @@ LIST * builtin_import( FRAME * frame, int flags )
         imported = import_rule( r, target_module, list_item( target_iter ) );
         if ( !list_empty( localize ) )
             rule_localize( imported, target_module );
-        /* This rule is really part of some other module. Just refer to it here,
-         * but do not let it out.
+        /* This rule is really part of some other module. Just refer to it
+         * here, but it shall be considered a local rule.
          */
         imported->exported = 0;
     }

src/engine/rules.cpp

@@ -130,7 +130,9 @@ static rule_ptr define_rule( module_ptr src_module, b2::value_ptr rulename,
     rule_ptr const r = enter_rule( rulename, target_module );
     if ( r->module != src_module )
     {
-        /* If the rule was imported from elsewhere, clear it now. */
+        /* If the rule was imported from elsewhere, clear it now. This can
+         * can happen, for example, when an imported rule does an overwrite
+         */
         set_rule_body( r, 0 );
         set_rule_actions( r, 0 );
         /* r will be executed in the source module. */
@@ -590,7 +592,7 @@ static rule_ptr global_rule( rule_ptr r )
 /*
  * new_rule_body() - make a new rule named rulename in the given module, with
  * the given argument list and procedure. If exported is true, the rule is
- * exported to the global module as modulename.rulename.
+ * a Jam "non local" rule, i.e. is supposed to appear in the global module.
  */
 
 rule_ptr new_rule_body( module_ptr m, b2::value_ptr rulename, function_ptr procedure,