[src/trunk]: src/usr.bin/make make.1: rewrite many details in a more precise way

[rillig <rillig%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/838f208b7a33
branches:  trunk
changeset: 369931:838f208b7a33
user:      rillig <rillig%NetBSD.org@localhost>
date:      Thu Sep 08 20:22:55 2022 +0000

description:
make.1: rewrite many details in a more precise way

diffstat:

 usr.bin/make/make.1 |  370 ++++++++++++++++++++++++++--------------------------
 1 files changed, 185 insertions(+), 185 deletions(-)

diffs (truncated from 933 to 300 lines):

diff -r a0396ca9a9d6 -r 838f208b7a33 usr.bin/make/make.1
--- a/usr.bin/make/make.1       Thu Sep 08 15:22:43 2022 +0000
+++ b/usr.bin/make/make.1       Thu Sep 08 20:22:55 2022 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: make.1,v 1.336 2022/09/07 23:34:56 rillig Exp $
+.\"    $NetBSD: make.1,v 1.337 2022/09/08 20:22:55 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 September 7, 2022
+.Dd September 8, 2022
 .Dt MAKE 1
 .Os
 .Sh NAME
@@ -626,15 +626,20 @@
 .Em not
 expanded.
 This can cause problems when variable modifiers are used.
+.\" See var-op-expand.mk, the section with LATER and INDIRECT.
 .It Ic \&!=
 Expand the value and pass it to the shell for execution,
 then assign the output from the child's standard output to the variable.
 Any newlines in the result are replaced with spaces.
 .El
 .Ss Expansion of variables
-In contexts where variables are expanded,
+In most contexts where variables are expanded,
 .Ql \&$$
 expands to a single dollar sign.
+In other contexts (most variable modifiers, string literals in conditions),
+.Ql \&\e$
+expands to a single dollar sign.
+.Pp
 References to variables have the form
 .Ql \&${ Ns Ar name Ns Oo \&: Ns Ar modifiers Oc Ns }
 or
@@ -647,9 +652,9 @@
 This allows almost arbitrary variable names, however names containing dollar,
 braces, parentheses or whitespace are really best avoided.
 .Pp
-If the result of expanding a variable contains a dollar sign
+If the result of expanding a nested variable expression contains a dollar sign
 .Pq Ql \&$ ,
-the string is expanded again.
+the string is subject to further expansion.
 .Pp
 Variable substitution occurs at four distinct times, depending on where
 the variable is being used.
@@ -688,7 +693,7 @@
 Because while
 .Va a
 contains
-.Ql 1 2 3
+.Ql ${:U1} ${:U2} ${:U3}
 after the loop is executed,
 .Va b
 contains
@@ -698,7 +703,7 @@
 since after the loop completes
 .Va j
 contains
-.Ql 3 .
+.Ql ${:U3} .
 .El
 .Ss Variable classes
 The four different classes of variables (in order of increasing precedence)
@@ -716,9 +721,9 @@
 Variables that are defined specific to a certain target.
 .El
 .Pp
-Local variables can be set on a dependency line, if
+Local variables can be set on a dependency line, unless
 .Va .MAKE.TARGET_LOCAL_VARIABLES
-is not set to
+is set to
 .Ql false .
 The rest of the line
 (which already has had global variables expanded)
@@ -749,7 +754,7 @@
 which have already been expanded.
 .El
 .Pp
-The seven built-in local variables are as follows:
+The seven built-in local variables are:
 .Bl -tag -width ".Va .ARCHIVE" -offset indent
 .It Va .ALLSRC
 The list of all sources for this target; also known as
@@ -830,9 +835,9 @@
 sets or knows about the following variables:
 .Bl -tag -width .MAKEOVERRIDES
 .It Va .ALLTARGETS
-The list of all targets encountered in the Makefile.
-If evaluated during
-Makefile parsing, lists only those targets encountered thus far.
+The list of all targets encountered in the makefiles.
+If evaluated during makefile parsing,
+lists only those targets encountered thus far.
 .It Va .CURDIR
 A path to the directory where
 .Nm
@@ -967,36 +972,40 @@
 is available, the system calls which are of interest to
 .Nm .
 The captured output can be very useful when diagnosing errors.
-.It Pa curdirOk= Ar bf
+.It Pa curdirOk= Ns Ar bf
 Normally
 .Nm
-does not create .meta files in
+does not create
+.Pa .meta
+files in
 .Sq Va .CURDIR .
 This can be overridden by setting
 .Va bf
-to a value which represents True.
-.It Pa missing-meta= Ar bf
+to a value which represents true.
+.It Pa missing-meta= Ns Ar bf
 If
 .Va bf
-is True, a missing
+is true, a missing
 .Pa .meta
 file makes the target out-of-date.
-.It Pa missing-filemon= Ar bf
+.It Pa missing-filemon= Ns Ar bf
 If
 .Va bf
-is True, missing filemon data makes the target out-of-date.
+is true, missing filemon data makes the target out-of-date.
 .It Pa nofilemon
 Do not use
 .Xr filemon 4 .
 .It Pa env
 For debugging, it can be useful to include the environment
-in the .meta file.
+in the
+.Pa .meta
+file.
 .It Pa verbose
 If in
 .Dq meta
 mode, print a clue about the target being built.
 This is useful if the build is otherwise running silently.
-The message printed the value of:
+The message printed is the expanded value of
 .Va .MAKE.META.PREFIX .
 .It Pa ignore-cmd
 Some makefiles have commands which are simply not stable.
@@ -1006,10 +1015,10 @@
 mode.
 See also
 .Ic .NOMETA_CMP .
-.It Pa silent= Ar bf
+.It Pa silent= Ns Ar bf
 If
 .Va bf
-is True, when a .meta file is created, mark the target
+is true, when a .meta file is created, mark the target
 .Ic .SILENT .
 .It Pa randomize-targets
 In both compat and parallel mode, do not make the targets in the usual order,
@@ -1087,13 +1096,13 @@
 support, this is set to the path of the device node.
 This allows makefiles to test for this support.
 .It Va .MAKE.PID
-The process-id of
+The process ID of
 .Nm .
 .It Va .MAKE.PPID
-The parent process-id of
+The parent process ID of
 .Nm .
 .It Va .MAKE.SAVE_DOLLARS
-Value should be a boolean that controls whether
+If true,
 .Ql $$
 are preserved when doing
 .Ql :=
@@ -1105,10 +1114,10 @@
 .Ql $
 per normal evaluation rules.
 .It Va .MAKE.UID
-The user-id running
+The numeric ID of the user running
 .Nm .
 .It Va .MAKE.GID
-The group-id running
+The numeric group ID of the user running
 .Nm .
 .It Va MAKE_PRINT_VAR_ON_ERROR
 When
@@ -1139,7 +1148,7 @@
 iterations of the loop rather than a space.
 For example, the printing of
 .Sq Va MAKE_PRINT_VAR_ON_ERROR
-could be done as ${MAKE_PRINT_VAR_ON_ERROR:@v@$v='${$v}'${.newline}@}.
+could be done as ${MAKE_PRINT_VAR_ON_ERROR:@v@$v='${$v:Q}'${.newline}@}.
 .It Va .OBJDIR
 A path to the directory where the targets are built.
 Its value is determined by trying to
@@ -1159,16 +1168,16 @@
 .Sq Ev MAKEOBJDIR
 is set in the environment or on the command line.)
 .It
-.Ev ${.CURDIR} Ns Pa /obj. Ns Ev ${MACHINE}
+.Cm ${.CURDIR} Ns Pa /obj. Ns Ev ${MACHINE}
 .It
-.Ev ${.CURDIR} Ns Pa /obj
+.Cm ${.CURDIR} Ns Pa /obj
 .It
-.Pa /usr/obj/ Ns Ev ${.CURDIR}
+.Pa /usr/obj/ Ns Cm ${.CURDIR}
 .It
-.Ev ${.CURDIR}
+.Cm ${.CURDIR}
 .El
 .Pp
-Variable expansion is performed on the value before it's used,
+Variable expansion is performed on the value before it is used,
 so expressions such as
 .Dl ${.CURDIR:S,^/usr/src,/var/obj,}
 may be used.
@@ -1195,23 +1204,17 @@
 .Sq Ev MAKE_OBJDIR_CHECK_WRITABLE
 to "no".
 .It Va .PARSEDIR
-A path to the directory of the current
-.Sq Pa Makefile
-being parsed.
+A path to the directory of the current makefile being parsed.
 .It Va .PARSEFILE
-The basename of the current
-.Sq Pa Makefile
-being parsed.
+The basename of the current makefile being parsed.
 This variable and
 .Sq Va .PARSEDIR
-are both set only while the
-.Sq Pa Makefiles
-are being parsed.
+are both set only while the makefiles are being parsed.
 If you want to retain their current values, assign them to a variable
 using assignment with expansion
 .Sq Cm \&:= .
 .It Va .PATH
-A variable that represents the list of directories that
+The space-separated list of directories that
 .Nm
 searches for files.
 The search list should be updated using the target
@@ -1264,21 +1267,17 @@
 instead.
 .El
 .Ss Variable modifiers
-Variable expansion may be modified to select or modify each word of the
-variable (where a
-.Dq word
-is white-space delimited sequence of characters).
-The general format of a variable expansion is as follows:
+The general format of a variable expansion is:
 .Pp
 .Sm off
 .D1 Ic \&${ Ar variable\| Oo Ic \&: Ar modifier\| Oo Ic \&: Ar ... Oc Oc Ic \&}
 .Sm on
 .Pp
-Each modifier begins with a colon,
-which may be escaped with a backslash
+Each modifier begins with a colon.
+To escape a colon, precede it with a backslash
 .Pq Ql \e .
 .Pp
-A set of modifiers can be specified via a variable, as follows:
+A list of indirect modifiers can be specified via a variable, as follows:
 .Pp
 .Bd -literal -offset indent
 .Ar modifier_variable\^ Li \&= Ar modifier Ns Oo Ic \&: Ns Ar ... Oc
@@ -1287,23 +1286,30 @@
 .Sm on
 .Ed
 .Pp
-In this case the first modifier in the
+In this case, the first modifier in the
 .Ar modifier_variable
-does not
-start with a colon, since that must appear in the referencing
-variable.
+does not start with a colon,
+since that colon already occurs in the referencing variable.
 If any of the modifiers in the
 .Ar modifier_variable
-contain a dollar sign
+contains a dollar sign
 .Pq Ql $ ,
 these must be doubled to avoid early expansion.