From f02c72e46b66a2153bef114507db217223544c8d Mon Sep 17 00:00:00 2001
From: Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
Date: Sat, 22 Jan 2011 11:16:27 +0100
Subject: [PATCH] docs: new sections about comments and whitespace in make
 macros.

* doc/autoconf.texi (Top, Portable Make): Adjust menus.
(Comments in Make Macros, Trailing whitespace in Make Macros):
New sections.
Suggestion by Stefano Lattarini.

Signed-off-by: Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
---
 ChangeLog         |  6 ++++++
 doc/autoconf.texi | 53 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 59 insertions(+)

diff --git a/ChangeLog b/ChangeLog
index c4c2bc1a..67d30fc6 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,11 @@
 2011-01-22  Ralf Wildenhues  <Ralf.Wildenhues@gmx.de>
 
+	docs: new sections about comments and whitespace in make macros.
+	* doc/autoconf.texi (Top, Portable Make): Adjust menus.
+	(Comments in Make Macros, Trailing whitespace in Make Macros):
+	New sections.
+	Suggestion by Stefano Lattarini.
+
 	docs: do not use AIX 5.3 cp -R.
 	* doc/autoconf.texi (Limitations of Usual Tools): Document one
 	instance of the cp -R bug on AIX 5.3.  This seems to have been
diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index b1496c6d..110f5f5f 100644
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -533,6 +533,8 @@ Portable Make Programming
 * Parallel Make::               Parallel @command{make} quirks
 * Comments in Make Rules::      Other problems with Make comments
 * Newlines in Make Rules::      Using literal newlines in rules
+* Comments in Make Macros::     Other problems with Make comments in macros
+* Trailing whitespace in Make Macros::  Macro substitution problems
 * obj/ and Make::               Don't name a subdirectory @file{obj}
 * make -k Status::              Exit status of @samp{make -k}
 * VPATH and Make::              @code{VPATH} woes
@@ -19137,6 +19139,8 @@ itself.
 * Parallel Make::               Parallel @command{make} quirks
 * Comments in Make Rules::      Other problems with Make comments
 * Newlines in Make Rules::      Using literal newlines in rules
+* Comments in Make Macros::     Other problems with Make comments in macros
+* Trailing whitespace in Make Macros::  Macro substitution problems
 * obj/ and Make::               Don't name a subdirectory @file{obj}
 * make -k Status::              Exit status of @samp{make -k}
 * VPATH and Make::              @code{VPATH} woes
@@ -19577,6 +19581,55 @@ nlinit=`echo 'nl="'; echo '"'`; eval "$$nlinit"; \
 sed -e "s/\$$/\\$$@{nl@}/" < input > output
 @end example
 
+@node Comments in Make Macros
+@section Comments in Make Macros
+@cindex Comments in @file{Makefile} macros
+@cindex @file{Makefile} macros and comments
+
+Avoid putting comments in macro values as far as possible.  Posix
+specifies that the text starting from the @samp{#} sign until the end of
+the line is to be ignored, which has the unfortunate effect of
+disallowing them even within quotes.  Thus, the following might lead to
+a syntax error at compile time:
+
+@example
+CPPFLAGS = "-DCOMMENT_CHAR='#'"
+@end example
+
+@noindent
+as @samp{CPPFLAGS} may be expanded to @samp{"-DCOMMENT_CHAR='}.
+Luckily, most @command{make} implementations disregard this and treat
+single and double quotes specially here.
+
+Even without quoting involved, comments can have surprising effects,
+because the whitespace before them is part of the variable value:
+
+@example
+foo = bar # trailing comment
+print: ; @@echo "$(foo)."
+@end example
+
+@noindent
+prints @samp{bar .}, which is usually not intended, and can expose
+@command{make} bugs as described below.
+
+@node Trailing whitespace in Make Macros
+@section Trailing whitespace in Make Macros
+@cindex whitespace in @file{Makefile} macros
+@cindex @file{Makefile} macros and whitespace
+
+GNU @command{make} 3.80 mistreats trailing whitespace in macro
+substitutions and appends another spurious suffix:
+
+@example
+empty =
+foo = bar $(empty)
+print: ; @@echo $(foo:=.test)
+@end example
+
+@noindent
+prints @samp{bar.test .test}.
+
 @node obj/ and Make
 @section The @file{obj/} Subdirectory and Make
 @cindex @file{obj/}, subdirectory
-- 
2.47.2