1 files changed, 74 insertions, 62 deletions

diff --git a/bmake.cat1 b/bmake.cat1
index feb93698e34f..564e811737da 100644
--- a/bmake.cat1
+++ b/bmake.cat1
@@ -89,9 +89,15 @@ BMAKE(1)                FreeBSD General Commands Manual               BMAKE(1)
 
              g3      Print the input graph before exiting on error.
 
+             h       Print debugging information about hash table operations.
+
              j       Print debugging information about running multiple
                      shells.
 
+             L       Turn on lint checks.  This will throw errors for variable
+                     assignments that do not parse correctly, at the time of
+                     assignment so the file and line number are available.
+
              l       Print commands in Makefiles regardless of whether or not
                      they are prefixed by `@' or other "quiet" flags.  Also
                      known as "loud" behavior.
@@ -188,7 +194,7 @@ BMAKE(1)                FreeBSD General Commands Manual               BMAKE(1)
 
      -n      Display the commands that would have been executed, but do not
              actually execute them unless the target depends on the .MAKE spe-
-             cial source (see below).
+             cial source (see below) or the command is prefixed with `+'.
 
      -N      Display the commands which would have been executed, but do not
              actually execute any of them; useful for debugging top-level
@@ -260,25 +266,31 @@ BMAKE(1)                FreeBSD General Commands Manual               BMAKE(1)
 FILE DEPENDENCY SPECIFICATIONS
      Dependency lines consist of one or more targets, an operator, and zero or
      more sources.  This creates a relationship where the targets ``depend''
-     on the sources and are usually created from them.  The exact relationship
-     between the target and the source is determined by the operator that sep-
-     arates them.  The three operators are as follows:
-
-     :     A target is considered out-of-date if its modification time is less
-           than those of any of its sources.  Sources for a target accumulate
-           over dependency lines when this operator is used.  The target is
-           removed if bmake is interrupted.
-
-     !     Targets are always re-created, but not until all sources have been
-           examined and re-created as necessary.  Sources for a target accumu-
-           late over dependency lines when this operator is used.  The target
-           is removed if bmake is interrupted.
-
-     ::    If no sources are specified, the target is always re-created.  Oth-
-           erwise, a target is considered out-of-date if any of its sources
-           has been modified more recently than the target.  Sources for a
-           target do not accumulate over dependency lines when this operator
-           is used.  The target will not be removed if bmake is interrupted.
+     on the sources and are customarily created from them.  A target is con-
+     sidered out-of-date if it does not exist, or if its modification time is
+     less than that of any of its sources.  An out-of-date target will be re-
+     created, but not until all sources have been examined and themselves re-
+     created as needed.  Three operators may be used:
+
+     :     Many dependency lines may name this target but only one may have
+           attached shell commands.  All sources named in all dependency lines
+           are considered together, and if needed the attached shell commands
+           are run to create or re-create the target.  If bmake is inter-
+           rupted, the target is removed.
+
+     !     The same, but the target is always re-created whether or not it is
+           out of date.
+
+     ::    Any dependency line may have attached shell commands, but each one
+           is handled independently: its sources are considered and the
+           attached shell commands are run if the target is out of date with
+           respect to (only) those sources.  Thus, different groups of the
+           attached shell commands may be run depending on the circumstances.
+           Furthermore, unlike :, for dependency lines with no sources, the
+           attached shell commands are always run.  Also unlike :, the target
+           will not be removed if bmake is interrupted.
+     All dependency lines mentioning a particular target must use the same
+     operator.
 
      Targets and sources may contain the shell wildcard values `?', `*', `[]',
      and `{}'.  The values `?', `*', and `[]' may only be used as part of the
@@ -374,7 +386,7 @@ BMAKE(1)                FreeBSD General Commands Manual               BMAKE(1)
 
      If the variable name contains a dollar, then the name itself is expanded
      first.  This allows almost arbitrary variable names, however names con-
-     taining dollar, braces, parenthesis, or whitespace are really best
+     taining dollar, braces, parentheses, or whitespace are really best
      avoided!
 
      If the result of expanding a variable contains a dollar sign (`$') the
@@ -729,6 +741,9 @@ BMAKE(1)                FreeBSD General Commands Manual               BMAKE(1)
                      contains a variable transform.  `PWD' is set to the value
                      of `.OBJDIR' for all programs which bmake executes.
 
+     .SHELL          The pathname of the shell used to run target scripts.  It
+                     is read-only.
+
      .TARGETS        The list of targets explicitly specified on the command
                      line, if any.
 
@@ -765,7 +780,7 @@ BMAKE(1)                FreeBSD General Commands Manual               BMAKE(1)
           ponent.
 
      :Mpattern
-          Select only those words that match pattern.  The standard shell
+          Selects only those words that match pattern.  The standard shell
           wildcard characters (`*', `?', and `[]') may be used.  The wildcard
           characters may be escaped with a backslash (`\').  As a consequence
           of the way values are split into words, matched, and then joined, a
@@ -779,11 +794,11 @@ BMAKE(1)                FreeBSD General Commands Manual               BMAKE(1)
           This is identical to `:M', but selects all words which do not match
           pattern.
 
-     :O   Order every word in variable alphabetically.
+     :O   Orders every word in variable alphabetically.
 
-     :Or  Order every word in variable in reverse alphabetical order.
+     :Or  Orders every word in variable in reverse alphabetical order.
 
-     :Ox  Randomize words in variable.  The results will be different each
+     :Ox  Shuffles the words in variable.  The results will be different each
           time you are referring to the modified variable; use the assignment
           with expansion (`:=') to prevent such behavior.  For example,
 
@@ -821,13 +836,13 @@ BMAKE(1)                FreeBSD General Commands Manual               BMAKE(1)
           utc value is not provided or is 0, the current time is used.
 
      :hash
-          Compute a 32-bit hash of the value and encode it as hex digits.
+          Computes a 32-bit hash of the value and encode it as hex digits.
 
      :localtime[=utc]
           The value is a format string for strftime(3), using localtime(3).
           If a utc value is not provided or is 0, the current time is used.
 
-     :tA  Attempt to convert variable to an absolute path using realpath(3),
+     :tA  Attempts to convert variable to an absolute path using realpath(3),
           if that fails, the value is unchanged.
 
      :tl  Converts variable to lower-case letters.
@@ -836,7 +851,7 @@ BMAKE(1)                FreeBSD General Commands Manual               BMAKE(1)
           Words in the variable are normally separated by a space on expan-
           sion.  This modifier sets the separator to the character c.  If c is
           omitted, then no separator is used.  The common escapes (including
-          octal numeric codes), work as expected.
+          octal numeric codes) work as expected.
 
      :tu  Converts variable to upper-case letters.
 
@@ -847,20 +862,20 @@ BMAKE(1)                FreeBSD General Commands Manual               BMAKE(1)
           white space.  See also `:[@]'.
 
      :S/old_string/new_string/[1gW]
-          Modify the first occurrence of old_string in the variable's value,
-          replacing it with new_string.  If a `g' is appended to the last
-          slash of the pattern, all occurrences in each word are replaced.  If
-          a `1' is appended to the last slash of the pattern, only the first
-          word is affected.  If a `W' is appended to the last slash of the
-          pattern, then the value is treated as a single word (possibly con-
-          taining embedded white space).  If old_string begins with a caret
-          (`^'), old_string is anchored at the beginning of each word.  If
-          old_string ends with a dollar sign (`$'), it is anchored at the end
-          of each word.  Inside new_string, an ampersand (`&') is replaced by
-          old_string (without any `^' or `$').  Any character may be used as a
-          delimiter for the parts of the modifier string.  The anchoring,
-          ampersand and delimiter characters may be escaped with a backslash
-          (`\').
+          Modifies the first occurrence of old_string in each word of the
+          variable's value, replacing it with new_string.  If a `g' is
+          appended to the last delimiter of the pattern, all occurrences in
+          each word are replaced.  If a `1' is appended to the last delimiter
+          of the pattern, only the first occurrence is affected.  If a `W' is
+          appended to the last delimiter of the pattern, then the value is
+          treated as a single word (possibly containing embedded white space).
+          If old_string begins with a caret (`^'), old_string is anchored at
+          the beginning of each word.  If old_string ends with a dollar sign
+          (`$'), it is anchored at the end of each word.  Inside new_string,
+          an ampersand (`&') is replaced by old_string (without any `^' or
+          `$').  Any character may be used as a delimiter for the parts of the
+          modifier string.  The anchoring, ampersand and delimiter characters
+          may be escaped with a backslash (`\').
 
           Variable expansion occurs in the normal fashion inside both
           old_string and new_string with the single exception that a backslash
@@ -878,16 +893,13 @@ BMAKE(1)                FreeBSD General Commands Manual               BMAKE(1)
           instances of the search pattern pattern as occur in the word or
           words it is found in; the `W' modifier causes the value to be
           treated as a single word (possibly containing embedded white space).
-          Note that `1' and `g' are orthogonal; the former specifies whether
-          multiple words are potentially affected, the latter whether multiple
-          substitutions can potentially occur within each affected word.
 
           As for the :S modifier, the pattern and replacement are subjected to
           variable expansion before being parsed as regular expressions.
 
-     :T   Replaces each word in the variable with its last component.
+     :T   Replaces each word in the variable with its last path component.
 
-     :u   Remove adjacent duplicate words (like uniq(1)).
+     :u   Removes adjacent duplicate words (like uniq(1)).
 
      :?true_string:false_string
           If the variable name (not its value), when parsed as a .if condi-
@@ -898,7 +910,7 @@ BMAKE(1)                FreeBSD General Commands Manual               BMAKE(1)
           variable expansions.  A common error is trying to use expressions
           like
                 ${NUMBERS:M42:?match:no}
-          which actually tests defined(NUMBERS), to determine is any words
+          which actually tests defined(NUMBERS), to determine if any words
           match "42" you need to use something like:
                 ${"${NUMBERS:M42}" != "":?match:no}.
 
@@ -916,7 +928,7 @@ BMAKE(1)                FreeBSD General Commands Manual               BMAKE(1)
           pattern matching character (%) in either the new_string or
           old_string, only the first instance is treated specially (as the
           pattern character); all subsequent instances are treated as regular
-          characters
+          characters.
 
           Variable expansion occurs in the normal fashion inside both
           old_string and new_string with the single exception that a backslash
@@ -925,17 +937,17 @@ BMAKE(1)                FreeBSD General Commands Manual               BMAKE(1)
 
      :@temp@string@
           This is the loop expansion mechanism from the OSF Development Envi-
-          ronment (ODE) make.  Unlike .for loops expansion occurs at the time
-          of reference.  Assign temp to each word in the variable and evaluate
-          string.  The ODE convention is that temp should start and end with a
-          period.  For example.
+          ronment (ODE) make.  Unlike .for loops, expansion occurs at the time
+          of reference.  Assigns temp to each word in the variable and evalu-
+          ates string.  The ODE convention is that temp should start and end
+          with a period.  For example.
                 ${LINKS:@.LINK.@${LN} ${TARGET} ${.LINK.}@}
 
           However a single character variable is often more readable:
                 ${MAKE_PRINT_VAR_ON_ERROR:@v@$v='${$v}'${.newline}@}
 
      :_[=var]
-          Save the current variable value in `$_' or the named var for later
+          Saves the current variable value in `$_' or the named var for later
           reference.  Example usage:
 
                 M_cmpv.units = 1 1000 1000000
@@ -948,7 +960,7 @@ BMAKE(1)                FreeBSD General Commands Manual               BMAKE(1)
           later referenced using the index values from `:range'.
 
      :Unewval
-          If the variable is undefined newval is the value.  If the variable
+          If the variable is undefined, newval is the value.  If the variable
           is defined, the existing value is returned.  This is another ODE
           make feature.  It is handy for setting per-target CFLAGS for
           instance:
@@ -957,7 +969,7 @@ BMAKE(1)                FreeBSD General Commands Manual               BMAKE(1)
                 ${VAR:D:Unewval}
 
      :Dnewval
-          If the variable is defined newval is the value.
+          If the variable is defined, newval is the value.
 
      :L   The name of the variable is the value.
 
@@ -1033,7 +1045,7 @@ BMAKE(1)                FreeBSD General Commands Manual               BMAKE(1)
           #      Returns the number of words in the value.
 
 INCLUDE STATEMENTS, CONDITIONALS AND FOR LOOPS
-     Makefile inclusion, conditional structures and for loops  reminiscent of
+     Makefile inclusion, conditional structures and for loops reminiscent of
      the C programming language are provided in bmake.  All such structures
      are identified by a line beginning with a single dot (`.') character.
      Files are included with either .include <file> or .include "file".  Vari-
@@ -1057,7 +1069,7 @@ BMAKE(1)                FreeBSD General Commands Manual               BMAKE(1)
 
      .error message
              The message is printed along with the name of the makefile and
-             line number, then bmake will exit.
+             line number, then bmake will exit immediately.
 
      .export variable ...
              Export the specified global variable.  If no variable list is
@@ -1191,7 +1203,7 @@ BMAKE(1)                FreeBSD General Commands Manual               BMAKE(1)
      variable expansion, either the left or right hand side of a `==' or `!='
      operator is not an integral value, then string comparison is performed
      between the expanded variables.  If no relational operator is given, it
-     is assumed that the expanded variable is being compared against 0 or an
+     is assumed that the expanded variable is being compared against 0, or an
      empty string in the case of a string comparison.
 
      When bmake is evaluating one of these conditional expressions, and it
@@ -1210,12 +1222,12 @@ BMAKE(1)                FreeBSD General Commands Manual               BMAKE(1)
      The syntax of a for loop is:
 
      .for variable [variable ...] in expression
-     <make-rules>
+     <make-lines>
      .endfor
 
      After the for expression is evaluated, it is split into words.  On each
      iteration of the loop, one word is taken and assigned to each variable,
-     in order, and these variables are substituted into the make-rules inside
+     in order, and these variables are substituted into the make-lines inside
      the body of the for loop.  The number of words must come out even; that
      is, if there are three iteration variables, the number of words provided
      must be a multiple of three.
@@ -1556,4 +1568,4 @@ BMAKE(1)                FreeBSD General Commands Manual               BMAKE(1)
 
      There is no way of escaping a space character in a filename.
 
-FreeBSD 11.3                     June 5, 2020                     FreeBSD 11.3
+FreeBSD 11.3                    August 28, 2020                   FreeBSD 11.3