[src/trunk]: src/usr.bin/make make.1: clean up style, typography, accuracy

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

details:   https://anonhg.NetBSD.org/src/rev/9e01457b393b
branches:  trunk
changeset: 371269:9e01457b393b
user:      rillig <rillig%NetBSD.org@localhost>
date:      Sun Oct 02 23:36:41 2022 +0000

description:
make.1: clean up style, typography, accuracy

In a code example, replace the deprecated `pwd` with the preferred form
$$(pwd).

Shorten the paragraph about escaping a dollar in modifiers, as the
various escaping mechanisms are described in the section 'Expansion of
variables'.

Summarize the previously many cases of the ':from=to' modifier to be
simpler to understand, actually mention what the pattern matching
character '%' can match.

Describe the syntax of function call expressions in conditionals.
Previously, only the function names had been documented.

diffstat:

 usr.bin/make/make.1 |  282 ++++++++++++++++++++++++++-------------------------
 1 files changed, 146 insertions(+), 136 deletions(-)

diffs (truncated from 626 to 300 lines):

diff -r 02b1536b86d4 -r 9e01457b393b usr.bin/make/make.1
--- a/usr.bin/make/make.1       Sun Oct 02 10:40:29 2022 +0000
+++ b/usr.bin/make/make.1       Sun Oct 02 23:36:41 2022 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: make.1,v 1.347 2022/09/15 14:49:36 uwe Exp $
+.\"    $NetBSD: make.1,v 1.348 2022/10/02 23:36:41 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 12, 2022
+.Dd October 2, 2022
 .Dt MAKE 1
 .Os
 .Sh NAME
@@ -67,8 +67,8 @@
 in order to find the specifications.
 If the file
 .Sq Pa .depend
-exists, it is read (see
-.Xr mkdep 1 ) .
+exists, it is read, see
+.Xr mkdep 1 .
 .Pp
 This manual page is intended as a reference document only.
 For a more thorough description of
@@ -148,9 +148,8 @@
 .Ql stdout
 or
 .Ql stderr ,
-debugging output is written to the
-standard output or standard error output file descriptors respectively
-(and the
+debugging output is written to the standard output or standard error output
+respectively (and the
 .Ql \&+
 option has no effect).
 Otherwise, the output is written to the named file.
@@ -252,7 +251,7 @@
 .It Fl i
 Ignore non-zero exit of shell commands in the makefile.
 Equivalent to specifying
-.Sq Ic \&-
+.Ql \&-
 before each command line in the makefile.
 .It Fl J Ar private
 This option should
@@ -368,19 +367,21 @@
 with a blank line for each null or undefined variable.
 The value printed is extracted from the global scope after all
 makefiles have been read.
+.Pp
 By default, the raw variable contents (which may
 include additional unexpanded variable references) are shown.
 If
 .Ar variable
 contains a
 .Ql \&$ ,
-the value is recursively expanded to its complete resultant
-text before printing.
-The expanded value is also printed if
+it is not interpreted as a variable name but rather as an expression.
+Its value is expanded before printing.
+The value is also expanded before printing if
 .Va .MAKE.EXPAND_VARIABLES
 is set to true and the
 .Fl dV
 option has not been used to override it.
+.Pp
 Note that loop-local and target-local variables, as well as values
 taken temporarily by global variables during makefile processing, are
 not accessible via this option.
@@ -464,11 +465,11 @@
 Thus, different groups of the attached shell commands may be run
 depending on the circumstances.
 Furthermore, unlike
-.Ic \&:,
+.Ic \&: ,
 for dependency lines with no sources, the attached shell
 commands are always run.
 Also unlike
-.Ic \&:,
+.Ic \&: ,
 the target is not removed if
 .Nm
 is interrupted.
@@ -504,12 +505,12 @@
 by default only one of these rules may be followed by a creation script.
 If the
 .Sq Ic \&::
-operator is used, however,
-all rules may include scripts and the scripts are executed in the order found.
+operator is used, however, all rules may include scripts,
+and the respective scripts are executed in the order found.
 .Pp
 Each line is treated as a separate shell command,
 unless the end of line is escaped with a backslash
-.Pq Ql \e ,
+.Ql \e ,
 in which case that line and the next are combined.
 If the first characters of the command are any combination of
 .Sq Ic @ ,
@@ -517,11 +518,10 @@
 or
 .Sq Ic \- ,
 the command is treated specially.
-A
-.Sq Ic @
+.Bl -tag -offset indent -width indent
+.It Ic @
 causes the command not to be echoed before it is executed.
-A
-.Sq Ic +
+.It Ic +
 causes the command to be executed even when
 .Fl n
 is given.
@@ -529,10 +529,10 @@
 .Va .MAKE
 special source,
 except that the effect can be limited to a single line of a script.
-A
-.Sq Ic \-
+.It Ic \-
 in compatibility mode
 causes any non-zero exit status of the command line to be ignored.
+.El
 .Pp
 When
 .Nm
@@ -569,14 +569,14 @@
 For example:
 .Bd -literal -offset indent
 avoid-chdir-side-effects:
-       @echo Building $@ in `pwd`
+       @echo "Building $@ in $$(pwd)"
        @(cd ${.CURDIR} && ${MAKE} $@)
-       @echo Back in `pwd`
+       @echo "Back in $$(pwd)"
 
 ensure-one-shell-regardless-of-mode:
-       @echo Building $@ in `pwd`; \e
+       @echo "Building $@ in $$(pwd)"; \e
        (cd ${.CURDIR} && ${MAKE} $@); \e
-       echo Back in `pwd`
+       echo "Back in $$(pwd)"
 .Ed
 .Pp
 Since
@@ -591,12 +591,12 @@
 Variable assignments have the form
 .Sq Ar NAME Ar op Ar value ,
 where:
-.Bl -tag -width Ds
+.Bl -tag -offset Ds -width Ds
 .It Ar NAME
 is a single-word variable name,
 consisting, by tradition, of all upper-case letters,
 .It Ar op
-is one of the five variable assignment operators described below, and
+is one of the variable assignment operators described below, and
 .It Ar value
 is interpreted according to the variable assignment operator.
 .El
@@ -619,9 +619,7 @@
 .It Ic \&?=
 Assign the value to the variable if it is not already defined.
 .It Ic \&:=
-Assign with expansion, i.e. expand the value before assigning it
-to the variable.
-Normally, expansion is not done until the variable is referenced.
+Expand the value, then assign it to the variable.
 .Pp
 .Em NOTE :
 References to undefined variables are
@@ -656,7 +654,7 @@
 .Pp
 If the result of expanding a nested variable expression contains a dollar sign
 .Pq Ql \&$ ,
-the string is subject to further expansion.
+the result is subject to further expansion.
 .Pp
 Variable substitution occurs at four distinct times, depending on where
 the variable is being used.
@@ -692,20 +690,26 @@
 3 3 3
 .Ed
 .Pp
-Because while
-.Va a
+After the loop is executed:
+.Bl -tag -offset indent -width indent
+.It Va a
 contains
-.Ql ${:U1} ${:U2} ${:U3}
-after the loop is executed,
-.Va b
+.Ql ${:U1} ${:U2} ${:U3} ,
+which expands to
+.Ql 1 2 3 .
+.It Va j
 contains
-.Ql ${j} ${j} ${j}
+.Ql ${:U3} ,
 which expands to
-.Ql 3 3 3
-since after the loop completes
-.Va j
+.Ql 3 .
+.It Va b
 contains
-.Ql ${:U3} .
+.Ql ${j} ${j} ${j} ,
+which expands to
+.Ql ${:U3} ${:U3} ${:U3}
+and further to
+.Ql 3 3 3 .
+.El
 .El
 .Ss Variable classes
 The four different classes of variables (in order of increasing precedence)
@@ -848,9 +852,9 @@
 .Sq Va PWD
 for more details.
 .It Va .INCLUDEDFROMDIR
-The directory of the file this Makefile was included from.
+The directory of the file this makefile was included from.
 .It Va .INCLUDEDFROMFILE
-The filename of the file this Makefile was included from.
+The filename of the file this makefile was included from.
 .It Va MAKE
 The name that
 .Nm
@@ -860,7 +864,7 @@
 .Nm
 also sets
 .Va .MAKE
-with the same value.
+to the same value.
 The preferred variable to use is the environment variable
 .Ev MAKE
 because it is more compatible with other make variants
@@ -950,8 +954,8 @@
 Affects the mode that
 .Nm
 runs in.
-It can contain a number of keywords:
-.Bl -hang -width missing-filemon=bf.
+It can contain these keywords:
+.Bl -tag -width indent
 .It Cm compat
 Like
 .Fl B ,
@@ -1202,7 +1206,8 @@
 checks that the specified directory is writable and ignores it if not.
 This check can be skipped by setting the environment variable
 .Sq Ev MAKE_OBJDIR_CHECK_WRITABLE
-to "no".
+to
+.Dq no .
 .It Va .PARSEDIR
 The directory name of the current makefile being parsed.
 .It Va .PARSEFILE
@@ -1306,9 +1311,9 @@
 The supported modifiers are:
 .Bl -tag -width EEE
 .It Cm \&:E
-Replaces each word in the variable with its suffix.
+Replaces each word with its suffix.
 .It Cm \&:H
-Replaces each word in the variable with its dirname.
+Replaces each word with its dirname.
 .It Cm \&:M\| Ns Ar pattern
 Selects only those words that match
 .Ar pattern .
@@ -1323,7 +1328,7 @@
 .Pq Ql \e .
 As a consequence of the way values are split into words, matched,
 and then joined, the construct
-.Dl ${VAR:M*}
+.Ql ${VAR:M*}
 removes all leading and trailing whitespace
 and normalizes the inter-word spacing to a single space.
 .It Cm \&:N\| Ns Ar pattern
@@ -1334,7 +1339,7 @@
 match
 .Ar pattern .
 .It Cm \&:O
-Orders the words alphabetically.
+Orders the words lexicographically.
 .It Cm \&:On
 Orders the words numerically.
 A number followed by one of
@@ -1350,7 +1355,7 @@
 .Ql G .
 Both upper- and lower-case letters are accepted.
 .It Cm \&:Or