make(1): fix a few inconsistencies in the manual page

usr.bin/make/make.1

@@ -1,4 +1,4 @@
-.\"	$NetBSD: make.1,v 1.286 2020/08/05 08:50:42 dholland Exp $
+.\"	$NetBSD: make.1,v 1.287 2020/08/19 06:10:06 rillig Exp $
 .\"
 .\" Copyright (c) 1990, 1993
 .\"	The Regents of the University of California.  All rights reserved.
@@ -29,7 +29,7 @@
 .\"
 .\"	from: @(#)make.1	8.4 (Berkeley) 3/19/94
 .\"
-.Dd August 5, 2020
+.Dd August 19, 2020
 .Dt MAKE 1
 .Os
 .Sh NAME
@@ -318,7 +318,8 @@ as an argument).
 .It Fl n
 Display the commands that would have been executed, but do not
 actually execute them unless the target depends on the .MAKE special
-source (see below).
+source (see below) or the command is prefixed with
+.Ql Ic + .
 .It Fl N
 Display the commands which would have been executed, but do not
 actually execute any of them; useful for debugging top-level makefiles
@@ -622,7 +623,7 @@ This shorter form is not recommended.
 .Pp
 If the variable name contains a dollar, then the name itself is expanded first.
 This allows almost arbitrary variable names, however names containing dollar,
-braces, parenthesis, or whitespace are really best avoided!
+braces, parentheses, or whitespace are really best avoided!
 .Pp
 If the result of expanding a variable contains a dollar sign
 .Pq Ql \&$
@@ -1184,7 +1185,7 @@ Replaces each word in the variable with its suffix.
 .It Cm \&:H
 Replaces each word in the variable with everything but the last component.
 .It Cm \&:M Ns Ar pattern
-Select only those words that match
+Selects only those words that match
 .Ar pattern .
 The standard shell wildcard characters
 .Pf ( Ql * ,
@@ -1208,11 +1209,11 @@ This is identical to
 but selects all words which do not match
 .Ar pattern .
 .It Cm \&:O
-Order every word in variable alphabetically.
+Orders every word in variable alphabetically.
 .It Cm \&:Or
-Order every word in variable in reverse alphabetical order.
+Orders every word in variable in reverse alphabetical order.
 .It Cm \&:Ox
-Randomize words in variable.
+Shuffles the words in variable.
 The results will be different each time you are referring to the
 modified variable; use the assignment with expansion
 .Pq Ql Cm \&:=
@@ -1262,7 +1263,7 @@ If a
 .Va utc
 value is not provided or is 0, the current time is used.
 .It Cm \&: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.
 .It Cm \&:localtime[=utc]
 The value is a format string for
 .Xr strftime 3 ,
@@ -1272,7 +1273,7 @@ If a
 .Va utc
 value is not provided or is 0, the current time is used.
 .It Cm \&:tA
-Attempt to convert variable to an absolute path using
+Attempts to convert variable to an absolute path using
 .Xr realpath 3 ,
 if that fails, the value is unchanged.
 .It Cm \&:tl
@@ -1284,7 +1285,7 @@ This modifier sets the separator to the character
 If
 .Ar c
 is omitted, then no separator is used.
-The common escapes (including octal numeric codes), work as expected.
+The common escapes (including octal numeric codes) work as expected.
 .It Cm \&:tu
 Converts variable to upper-case letters.
 .It Cm \&:tW
@@ -1300,9 +1301,9 @@ See also
 .Sm off
 .It Cm \&:S No \&/ Ar old_string No \&/ Ar new_string No \&/ Op Cm 1gW
 .Sm on
-Modify the first occurrence of
+Modifies the first occurrence of
 .Ar old_string
-in the variable's value, replacing it with
+in each word of the variable's value, replacing it with
 .Ar new_string .
 If a
 .Ql g
@@ -1310,7 +1311,7 @@ is appended to the last slash of the pattern, all occurrences
 in each word are replaced.
 If a
 .Ql 1
-is appended to the last slash of the pattern, only the first word
+is appended to the last slash of the pattern, only the first occurrence
 is affected.
 If a
 .Ql W
@@ -1400,9 +1401,9 @@ and
 are subjected to variable expansion before being parsed as
 regular expressions.
 .It Cm \&:T
-Replaces each word in the variable with its last component.
+Replaces each word in the variable with its last path component.
 .It Cm \&:u
-Remove adjacent duplicate words (like
+Removes adjacent duplicate words (like
 .Xr uniq 1 ) .
 .Sm off
 .It Cm \&:\&? Ar true_string Cm \&: Ar false_string
@@ -1418,7 +1419,7 @@ usually contain variable expansions.
 A common error is trying to use expressions like
 .Dl ${NUMBERS:M42:?match:no}
 which actually tests defined(NUMBERS),
-to determine is any words match "42" you need to use something like:
+to determine if any words match "42" you need to use something like:
 .Dl ${"${NUMBERS:M42}" != \&"\&":?match:no} .
 .It Ar :old_string=new_string
 This is the
@@ -1462,7 +1463,7 @@ in either the
 or
 .Ar old_string ,
 only the first instance is treated specially (as the pattern character);
-all subsequent instances are treated as regular characters
+all subsequent instances are treated as regular characters.
 .Pp
 Variable expansion occurs in the normal fashion inside both
 .Ar old_string
@@ -1479,11 +1480,10 @@ This is the loop expansion mechanism from the OSF Development
 Environment (ODE) make.
 Unlike
 .Cm \&.for
-loops expansion occurs at the time of
-reference.
-Assign
+loops, expansion occurs at the time of reference.
+Assigns
 .Ar temp
-to each word in the variable and evaluate
+to each word in the variable and evaluates
 .Ar string .
 The ODE convention is that
 .Ar temp
@@ -1494,7 +1494,7 @@ For example.
 However a single character variable is often more readable:
 .Dl ${MAKE_PRINT_VAR_ON_ERROR:@v@$v='${$v}'${.newline}@}
 .It Cm \&:_[=var]
-Save the current variable value in
+Saves the current variable value in
 .Ql $_
 or the named
 .Va var
@@ -1515,7 +1515,7 @@ is used to save the result of the
 modifier which is later referenced using the index values from
 .Ql :range .
 .It Cm \&:U Ns Ar newval
-If the variable is undefined
+If the variable is undefined,
 .Ar newval
 is the value.
 If the variable is defined, the existing value is returned.
@@ -1525,7 +1525,7 @@ It is handy for setting per-target CFLAGS for instance:
 If a value is only required if the variable is undefined, use:
 .Dl ${VAR:D:Unewval}
 .It Cm \&:D Ns Ar newval
-If the variable is defined
+If the variable is defined,
 .Ar newval
 is the value.
 .It Cm \&:L
@@ -1654,7 +1654,7 @@ Returns the number of words in the value.
 .El \" :[range]
 .El
 .Sh INCLUDE STATEMENTS, CONDITIONALS AND FOR LOOPS
-Makefile inclusion, conditional structures and for loops  reminiscent
+Makefile inclusion, conditional structures and for loops reminiscent
 of the C programming language are provided in
 .Nm .
 All such structures are identified by a line beginning with a single
@@ -1700,7 +1700,7 @@ The possible conditionals are as follows:
 The message is printed along with the name of the makefile and line number,
 then
 .Nm
-will exit.
+will exit immediately.
 .It Ic .export Ar variable ...
 Export the specified global variable.
 If no variable list is provided, all globals are exported
@@ -1889,7 +1889,7 @@ 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 empty string in the case
+variable is being compared against 0, or an empty string in the case
 of a string comparison.
 .Pp
 When
@@ -1930,7 +1930,7 @@ The syntax of a for loop is:
 .Pp
 .Bl -tag -compact -width Ds
 .It Ic \&.for Ar variable Oo Ar variable ... Oc Ic in Ar expression
-.It Aq make-rules
+.It Aq make-lines
 .It Ic \&.endfor
 .El
 .Pp
@@ -1942,7 +1942,7 @@ On each iteration of the loop, one word is taken and assigned to each
 in order, and these
 .Ic variables
 are substituted into the
-.Ic make-rules
+.Ic 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

usr.bin/make/unit-tests/varmod-subst.mk

@@ -1,4 +1,4 @@
-# $NetBSD: varmod-subst.mk,v 1.2 2020/08/16 12:30:45 rillig Exp $
+# $NetBSD: varmod-subst.mk,v 1.3 2020/08/19 06:10:06 rillig Exp $
 #
 # Tests for the :S,from,to, variable modifier.
 
@@ -14,6 +14,10 @@ WORDS=		sequences of letters
 .if ${WORDS:S,e,*,1} != "s*quences of letters"
 .warning The :S modifier flag '1' is not applied exactly once.
 .endif
+.if ${WORDS:S,f,*,1} != "sequences o* letters"
+.warning The :S modifier flag '1' is only applied to the first word,\
+	 not to the first occurrence.
+.endif
 .if ${WORDS:S,e,*,} != "s*quences of l*tters"
 .warning The :S modifier does not replace every first match per word.
 .endif