From: Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
Date: Sat, 22 Jan 2011 18:39:29 +0000 (+0100)
Subject: docs: document how to use comment characters in rules.
X-Git-Tag: v2.68b~116
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=80ca89f803a12d1ad674ca8c3f27a7966e2cf968;p=thirdparty%2Fautoconf.git

docs: document how to use comment characters in rules.

* doc/autoconf.texi (Comments in Make Rules): Explain how to
produce a `#' in a rule.
(Comments in Make Macros): Add cross reference.
Suggestion from Eric Blake.

Signed-off-by: Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
---

diff --git a/ChangeLog b/ChangeLog
index 67d30fc6..b58a4086 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,11 @@
 2011-01-22  Ralf Wildenhues  <Ralf.Wildenhues@gmx.de>
 
+	docs: document how to use comment characters in rules.
+	* doc/autoconf.texi (Comments in Make Rules): Explain how to
+	produce a `#' in a rule.
+	(Comments in Make Macros): Add cross reference.
+	Suggestion from Eric Blake.
+
 	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):
diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index 110f5f5f..8a92ffde 100644
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -19553,6 +19553,21 @@ all:
         : "foo"
 @end example
 
+Conversely, if you want to use the @samp{#} character in some command,
+you can only do so by expanding it inside a rule (@pxref{Comments in
+Make Macros}).  So for example, if @samp{COMMENT_CHAR} is substituted by
+@command{config.status} as @samp{#}, then the following substitutes
+@samp{@@COMMENT_CHAR@@} in a generated header:
+
+@example
+foo.h: foo.h.in
+        sed -e 's|@@''COMMENT_CHAR''@@|@@COMMENT_CHAR@@|g' \
+            $(srcdir)/foo.h.in > $@@
+@end example
+
+The funny shell quoting avoids a substitution at @command{config.status}
+run time of the left-hand side of the @command{sed} @samp{s} command.
+
 @node Newlines in Make Rules
 @section Newlines in Make Rules
 @cindex Newlines in @file{Makefile} rules
@@ -19599,7 +19614,8 @@ CPPFLAGS = "-DCOMMENT_CHAR='#'"
 @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.
+single and double quotes specially here; @pxref{Comments in Make Rules},
+for a more portable alternative.
 
 Even without quoting involved, comments can have surprising effects,
 because the whitespace before them is part of the variable value: