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 67d30fc62f10ac69644fdc382a58432302f17a8c..b58a408689da23eeb291a9272f80ab62d61e2361 100644 (file)
--- 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 110f5f5f8ef2d3e994957cbb76fc6612ad7c447c..8a92ffde47c397a9207c97dea5dd86564e3d39a8 100644 (file)
--- 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: