[src/trunk]: src/usr.bin/make Revert the man page as well. (hi joerg)

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

details:   https://anonhg.NetBSD.org/src/rev/b7aeda5adb82
branches:  trunk
changeset: 332152:b7aeda5adb82
user:      dholland <dholland%NetBSD.org@localhost>
date:      Tue Sep 09 06:39:59 2014 +0000

description:
Revert the man page as well. (hi joerg)

Revert it to 20140823 (-r1.230), before the controversial commits,
which changed it a good deal.

diffstat:

 usr.bin/make/make.1 |  460 +++++++--------------------------------------------
 1 files changed, 64 insertions(+), 396 deletions(-)

diffs (truncated from 683 to 300 lines):

diff -r d9a326a8a75e -r b7aeda5adb82 usr.bin/make/make.1
--- a/usr.bin/make/make.1       Tue Sep 09 06:38:33 2014 +0000
+++ b/usr.bin/make/make.1       Tue Sep 09 06:39:59 2014 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: make.1,v 1.236 2014/09/05 06:57:20 wiz Exp $
+.\"    $NetBSD: make.1,v 1.237 2014/09/09 06:39:59 dholland 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 4, 2014
+.Dd February 14, 2014
 .Dt MAKE 1
 .Os
 .Sh NAME
@@ -209,6 +209,8 @@
 option to print raw values of variables.
 .It Ar v
 Print debugging information about variable assignment.
+.It Ar w
+Print entering and leaving directory messages, pre and post processing.
 .It Ar x
 Run shell commands with
 .Fl x
@@ -350,8 +352,6 @@
 then the value will be expanded before printing.
 .It Fl W
 Treat any warnings during makefile parsing as errors.
-.It Fl w
-Print entering and leaving directory messages, pre and post processing.
 .It Fl X
 Don't export variables passed on the command line to the environment
 individually.
@@ -382,27 +382,17 @@
 In general, lines may be continued from one line to the next by ending
 them with a backslash
 .Pq Ql \e .
-For any line that is not a shell command line (i.e. it does not begin
-with a tab), the backslash, the following newline character, and initial
-whitespace on the following line are compressed into a single space.
-On command lines the backslash and the newline are left intact and
-if the following line begins with tab(s), the first one is removed.
+The trailing newline character and initial whitespace on the following
+line are compressed into a single space.
 .Sh FILE DEPENDENCY SPECIFICATIONS
-Dependency lines consist of one or more targets, an operator, zero
-or more sources, and an optional semicolon followed by a command.
+Dependency lines consist of one or more targets, an operator, and zero
+or more sources.
 This creates a relationship where the targets
 .Dq depend
 on the sources
 and are usually created from them.
-.Bd -literal -offset indent
-target [target...]: [source...] [;command]
-.Ed
-.Pp
 The exact relationship between the target and the source is determined
-by the operator, presented by a colon in the example, that separates
-them.
-A target may only appear on the left hand side of one type of operator
-in a single makefile.
+by the operator that separates them.
 The three operators are as follows:
 .Bl -tag -width flag
 .It Ic \&:
@@ -413,7 +403,6 @@
 The target is removed if
 .Nm
 is interrupted.
-This is the only operator available in POSIX compatible makefiles.
 .It Ic \&!
 Targets are always re-created, but not until all sources have been
 examined and re-created as necessary.
@@ -427,22 +416,12 @@
 Otherwise, 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, only the depencies in the first rule encountered are
-used.
-The commands from the rules do accumulate and are executed in the order
-the rules were defined if the target needs to be updated.
+operator is used.
 The target will not be removed if
 .Nm
 is interrupted.
 .El
 .Pp
-The optional semicolon separated command in the dependency line is
-strongly discouraged except to specify an empty rule to nullify
-an existing suffix transformation rule (see
-.Ic .SUFFIXES ) .
-More information on commands is in the section
-.Sx SHELL COMMANDS .
-.Pp
 Targets and sources may contain the shell wildcard values
 .Ql \&? ,
 .Ql * ,
@@ -461,124 +440,16 @@
 .Ql {}
 need not necessarily be used to describe existing files.
 Expansion is in directory order, not alphabetically as done in the shell.
-.Ss Suffix transformation rules
-Suffix transformation rules allow
-.Nm
-to infer the commands used to bring targets up to date based on their
-suffixes.
-These are also known as inference rules or just suffix rules.
-A suffix transformation rule is a rule whose dependency line has either
-of these forms:
-.Bd -literal -compact -offset indent
-\&.s1.s2: [source...]
-\&.s1: [source...]
-.Ed
-Additionally, both
-.Pa .s1
-and
-.Pa .s2
-need to be defined as dependencies on the special target
-.Ic .SUFFIXES .
-.Pp
-A suffix transformation rule tells
-.Nm
-that any file named
-.Pa file.s2 Pq the first form
-or
-.Pa file Pq the second form
-can be made with the provided rules from a file named
-.Pa file.s1 .
-Suffix transformation rules are only tried when there is no explicit
-rule to make a target.
-Single suffix rules (ther second form) are only tried if the target has
-no known suffix.
-Suffixes are tried in the order they have been specified to the
-.Ic .SUFFIXES
-special target.
-An explicit dependency line with no commands can be used to add more
-dependencies, while still allowing for the use of the inferred commands.
-.Pp
-In POSIX compatible makefiles there are no sources listed in
-a suffix transformation rule definition and only a single transformation
-step is tried.
-This implementation allows dependencies to be listed and handles them
-as additional dependencies on any file that gets created with the suffix
-transformation.
-This can be combined with
-.Em dynamic sources .
-Transformations can also be chained: if
-.Pa file.s1
-could be made from
-.Pa file.s2
-but it does not exist,
-.Nm
-will try the suffix transformation rules which could make it from any
-.Pa file.s3
-and so forth.
-The shortest path from an existing file or an explicit rule will be
-chosen.
-.Pp
-Usable commands for these rules cannot be written without knowing what
-the actual sources and targets are.
-This information is provided with the local variables listed in the
-section
-.Dq Variable classes .
-.Ss Archive member targets
-A target or a source of the form
-.Pa archive(member)
-refers to file
-.Pa member
-in an
-.Ic ar
-library archive named
-.Pa archive .
-The modification time stored for the member in the archive is used in
-up-to-dateness checks.
-In POSIX compatible makefiles the member file must be an object file and
-have the suffix
-.Pa .o .
-.Pp
-Library members can also be inferred.
-The POSIX compatible way is to define a suffix transformation rule with
-the name
-.Pa .s1.a ,
-as
-.Pa .a
-is the traditional suffix of such archives.
-This rule is used to update
-.Pa member.o
-from the file
-.Pa member.s1
-in any archive file,
-regardless of any suffix the archive file may or may not have.
-.Pp
-As an extension, if the POSIX compatible behavior does not yield commands,
-.Nm
-looks if it could make the member if it were a regular file.
-If it can, then it tries to find a transformation rule from that file
-to the suffix of the archive for adding the file in to the archive.
 .Sh SHELL COMMANDS
-Each target may have associated with it a series of shell commands, which
-immediately follow the dependency line.
-These commands are normally used to create a file corresponding to
-the target name.
-The first command line (or only line, if there is only one) may be on
-the same line with the dependency information, separated by a semicolon.
-Every command line in this script following the dependency line
+Each target may have associated with it a series of shell commands, normally
+used to create the target.
+Each of the commands in this script
 .Em must
 be preceded by a tab.
-Placing commands on the dependency line is not a good practice.
-
-A target name may appear on the left hand side of the dependency
-operator in any number of dependency lines.
-Only one of these dependency specifications may be followed by a creation
-script, unless the
+While any target may appear on a dependency line, only one of these
+dependencies may be followed by a creation script, unless the
 .Ql Ic \&::
 operator is used.
-If more than one rule with commands is encountered, the last one is used.
-Overriding rules has its use cases, but sometimes it can happen by accident.
-A notice of each overridden rule is included in the parsing debugging
-category.
 .Pp
 If the first characters of the command line are any combination of
 .Ql Ic @ ,
@@ -629,52 +500,20 @@
 For example, any command which needs to use
 .Dq cd
 or
-.Dq chdir
-without side-effects should be put in parenthesis so they are executed
-in a subshell:
+.Dq chdir ,
+without side-effect should be put in parenthesis:
 .Bd -literal -offset indent
 
 avoid-chdir-side-effects:
        @echo Building $@ in `pwd`
-       @(cd ${.CURDIR} && ${MAKE} $@)
+       @(cd ${.CURDIR} && ${.MAKE} $@)
        @echo Back in `pwd`
 
 ensure-one-shell-regardless-of-mode:
        @echo Building $@ in `pwd`; \\
-       (cd ${.CURDIR} && ${MAKE} $@); \\
+       (cd ${.CURDIR} && ${.MAKE} $@); \\
        echo Back in `pwd`
 .Ed
-.Pp
-The backslash and the following newline are retained in the input to
-the shell, but if the next line starts with tab(s), the first one of
-those is removed.
-This allows you to align the commands in the rule without introducing
-unwanted whitespace into the command line itself.
-What happens to the backslash-newline pair is up to the shell.
-The standard shell,
-.Xr sh 1 ,
-removes them both elsewhere than in single quotes, effectively catenating
-the two lines.
-The following examples demonstrate escaped newlines in command lines.
-.Bl -column -offset indent "    echo \*qfoo\\xxxx" "|      cd dir \\xxxx"
-.It "echo-foobar:"      Ta "|  syntax-error:"
-.It "    echo \*qfoo\\" Ta "|      for i in a b\\"
-.It "    bar\*q"        Ta "|      do\\"
-.It                     Ta "|        echo $i\\"
-.It                     Ta "|      done"
-.El
-.Pp
-The first one is an unnecessarily contrived way of doing
-.Bd -compact -offset indent
-.Ic "echo \*qfoobar\*q"
-.Ed
-The second one demonstrates why the semicolon is required in many places
-where in a similar looking regular shell script it wouldn't be.
-After the shell has removed the backslash newline pairs, the result
-would be the syntactically incorrect command
-.Bd -compact -offset indent
-.Ic "for i in a bdo  echo $idone"
-.Ed
 .Sh VARIABLE ASSIGNMENTS
 Variables in make are much like variables in the shell, and, by tradition,
 consist of all upper-case letters.
@@ -784,36 +623,23 @@
 .It Command line variables
 Variables defined as part of the command line.
 .It Local variables
-There are seven variables that are defined specific to a certain target.
-Five of these are defined in POSIX but only in their short form.
-The variables are as follows:
+Variables that are defined specific to a certain target.
+The seven local variables are as follows:
 .Bl -tag -width ".ARCHIVE"
 .It Va .ALLSRC
 The list of all sources for this target; also known as