details: https://anonhg.NetBSD.org/src/rev/473ab2fe9830
branches: trunk
changeset: 937444:473ab2fe9830
user: rillig <rillig%NetBSD.org@localhost>
date: Wed Aug 19 06:10:06 2020 +0000
description:
make(1): fix a few inconsistencies in the manual page
diffstat:
usr.bin/make/make.1 | 60 ++++++++++++++++----------------
usr.bin/make/unit-tests/varmod-subst.mk | 6 ++-
2 files changed, 35 insertions(+), 31 deletions(-)
diffs (246 lines):
diff -r 6373b6962809 -r 473ab2fe9830 usr.bin/make/make.1
--- a/usr.bin/make/make.1 Wed Aug 19 06:08:27 2020 +0000
+++ b/usr.bin/make/make.1 Wed Aug 19 06:10:06 2020 +0000
@@ -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 @@
.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 @@
.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 @@
.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 @@
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 @@
.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 @@
.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 @@
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 @@
.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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
.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 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 @@
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 @@
.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 @@
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
diff -r 6373b6962809 -r 473ab2fe9830 usr.bin/make/unit-tests/varmod-subst.mk
--- a/usr.bin/make/unit-tests/varmod-subst.mk Wed Aug 19 06:08:27 2020 +0000
+++ b/usr.bin/make/unit-tests/varmod-subst.mk Wed Aug 19 06:10:06 2020 +0000
@@ -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 @@
.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