Merge branch 'docs-recursion' into maint

* docs-recursion:
  docs: recursive make considered harmful

1 files changed, 21 insertions, 10 deletions

diff --git a/doc/automake.texi b/doc/automake.texi
index 13f72000c..6c83a1376 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -4183,13 +4183,25 @@ For simple projects that distribute all files in the same directory
 it is enough to have a single @file{Makefile.am} that builds
 everything in place.
 
-In larger projects it is common to organize files in different
-directories, in a tree.  For instance one directory per program, per
-library or per module.  The traditional approach is to build these
-subdirectories recursively: each directory contains its @file{Makefile}
-(generated from @file{Makefile.am}), and when @command{make} is run
-from the top level directory it enters each subdirectory in turn to
-build its contents.
+In larger projects, it is common to organize files in different
+directories, in a tree.  For example, there could be a directory
+for the program's source, one for the testsuite, and one for the
+documentation; or, for very large projects, there could be one
+directory per program, per library or per module.
+
+The traditional approach is to build these subdirectories recursively,
+employing @emph{make recursion}: each directory contains its
+own @file{Makefile}, and when @command{make} is run from the top-level
+directory, it enters each subdirectory in turn, and invokes there a
+new @command{make} instance to build the directory's contents.
+
+Because this approach is very widespread, Automake offers built-in
+support for it.  However, it is worth nothing that the use of make
+recursion has its own serious issues and drawbacks, and that it's
+well possible to have packages with a multi directory layout that
+make little or no use of such recursion (examples of such packages
+are GNU Bison and GNU Automake itself); see also the @ref{Alternative}
+section below.
 
 @menu
 * Subdirectories::              Building subdirectories recursively
@@ -4203,7 +4215,7 @@ build its contents.
 
 @cindex @code{SUBDIRS}, explained
 
-In packages with subdirectories, the top level @file{Makefile.am} must
+In packages using make recursion, the top level @file{Makefile.am} must
 tell Automake which subdirectories are to be built.  This is done via
 the @code{SUBDIRS} variable.
 @vindex SUBDIRS
@@ -4484,7 +4496,7 @@ variables it cannot ensure the corresponding directory exists.
 If you've ever read Peter Miller's excellent paper,
 @uref{http://miller.emu.id.au/pmiller/books/rmch/,
 Recursive Make Considered Harmful}, the preceding sections on the use of
-subdirectories will probably come as unwelcome advice.  For those who
+make recursion will probably come as unwelcome advice.  For those who
 haven't read the paper, Miller's main thesis is that recursive
 @command{make} invocations are both slow and error-prone.
 
@@ -4494,7 +4506,6 @@ believe.  This work is new and there are probably warts.
 to write a single @file{Makefile.am} for a complex multi-directory
 package.
 
-
 By default an installable file specified in a subdirectory will have its
 directory name stripped before installation.  For instance, in this
 example, the header file will be installed as