FYI: m4sugar doc patch

[Eric Blake]

I've had this sitting on my tree for a while; it cleans up a fixme in the docs, 
so I'm committing it.

2007-09-25  Eric Blake  <address@hidden>

        Improve documentation of M4 parameter expansion.
        * doc/autoconf.texi (Quoting and Parameters): New section.
        (Quotation and Nested Macros): Improve wording.

From: Eric Blake <address@hidden>
Date: Tue, 25 Sep 2007 11:58:50 -0600
Subject: [PATCH] Improve documentation of M4 parameter expansion.

* doc/autoconf.texi (Quoting and Parameters): New section.

Signed-off-by: Eric Blake <address@hidden>
---
 ChangeLog         |    4 ++
 doc/autoconf.texi |   91 ++++++++++++++++++++++++++++++++++++++++++++++-------
 2 files changed, 83 insertions(+), 12 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 102aa72..95c1196 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,9 @@
 2007-09-25  Eric Blake  <address@hidden>
 
+       Improve documentation of M4 parameter expansion.
+       * doc/autoconf.texi (Quoting and Parameters): New section.
+       (Quotation and Nested Macros): Improve wording.
+
        Improve C99 detection.
        * lib/autoconf/c.m4 (_AC_PROG_CC_C99): Add support for HP cc, and
        avoid deprecation warning with icc.
diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index f05b109..8d41f47 100644
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -435,6 +435,7 @@ M4 Quotation
 
 * Active Characters::           Characters that change the behavior of M4
 * One Macro Call::              Quotation and one macro call
+* Quoting and Parameters::      M4 vs. shell parameters
 * Quotation and Nested Macros::  Macros calling macros
 * Changequote is Evil::         Worse than INTERCAL: M4 + changequote
 * Quadrigraphs::                Another way to escape special characters
@@ -9098,10 +9099,6 @@ and their interface might change in the future.  As a 
matter of fact,
 @cindex M4 quotation
 @cindex quotation
 
address@hidden FIXME: Grmph, yet another quoting myth: quotation has *never*
address@hidden prevented `expansion' of $1.  Unless it refers to the expansion
address@hidden of the value of $1?  Anyway, we need a rewrite address@hidden
-
 The most common problem with existing macros is an improper quotation.
 This section, which users of Autoconf can skip, but which macro writers
 @emph{must} read, first justifies the quotation scheme that was chosen
@@ -9111,6 +9108,7 @@ former helps one to follow the latter.
 @menu
 * Active Characters::           Characters that change the behavior of M4
 * One Macro Call::              Quotation and one macro call
+* Quoting and Parameters::      M4 vs. shell parameters
 * Quotation and Nested Macros::  Macros calling macros
 * Changequote is Evil::         Worse than INTERCAL: M4 + changequote
 * Quadrigraphs::                Another way to escape special characters
@@ -9124,8 +9122,8 @@ To fully understand where proper quotation is important, 
you first need
 to know what the special characters are in Autoconf: @samp{#} introduces
 a comment inside which no macro expansion is performed, @samp{,}
 separates arguments, @samp{[} and @samp{]} are the quotes themselves,
-and finally @samp{(} and @samp{)} (which M4 tries to match by
-pairs).
address@hidden(} and @samp{)} (which M4 tries to match by pairs), and finally
address@hidden inside a macro definition.
 
 In order to understand the delicate case of macro calls, we first have
 to present some obvious failures.  Below they are ``obvious-ified'',
@@ -9246,10 +9244,77 @@ car([[[a]]])
 @result{}[a]
 @end example
 
address@hidden Quoting and Parameters
address@hidden
+
+When M4 encounters @samp{$} within a macro definition, followed
+immediately by a character it recognizes (@address@hidden@samp{9},
address@hidden, @samp{@@}, or @samp{*}), it will perform M4 parameter
+expansion.  This happens regardless of how many layers of quotes the
+parameter expansion is nested within, or even if it occurs in text that
+will be rescanned as a comment.
+
address@hidden
+define([none], [$1])
address@hidden
+define([one], [[$1]])
address@hidden
+define([two], [[[$1]]])
address@hidden
+define([comment], [# $1])
address@hidden
+define([active], [ACTIVE])
address@hidden
+none([active])
address@hidden
+one([active])
address@hidden
+two([active])
address@hidden
+comment([active])
address@hidden active
address@hidden example
+
+On the other hand, since autoconf generates shell code, you often want
+to output shell variable expansion, rather than performing M4 parameter
+expansion.  To do this, you must use M4 quoting to separate the @samp{$}
+from the next character in the definition of your macro.  If the macro
+definition occurs in single-quoted text, then insert another level of
+quoting; if the usage is already inside a double-quoted string, then
+split it into concatenated strings.
+
address@hidden
+define([single], [a single-quoted $[]1 definition])
address@hidden
+define([double], [[a double-quoted $][1 definition]])
address@hidden
+single
address@hidden single-quoted $1 definition
+double
address@hidden double-quoted $1 definition
address@hidden example
+
+Posix states that M4 implementations are free to provide implementation
+extensions when @address@hidden is encountered in a macro definition.
+Autoconf reserves the longer sequence @address@hidden@{} for use with planned
+extensions that will be available in the future @acronym{GNU} M4 2.0,
+but guarantees that all other instances of @address@hidden will be output
+literally.  Therefore, this idiom can also be used to output shell code
+parameter references:
+
address@hidden
+define([first], address@hidden@}])first
address@hidden@address@hidden
address@hidden example
+
+Posix also states that @samp{$11} should expand to the first parameter
+concatenated with a literal @samp{1}, although some versions of
address@hidden M4 expand the eleventh parameter instead.  For
+portability, you should only use single-digit M4 parameter expansion.
+
 With this in mind, we can explore the cases where macros invoke
 address@hidden
 
-
 @node Quotation and Nested Macros
 @subsection Quotation and Nested Macros
 
@@ -9343,17 +9408,19 @@ qar([int tab[10];])
 @noindent
 Ahhh!  That's much better.
 
-But note what you've done: now that the arguments are literal strings,
-if the user wants to use the results of expansions as arguments, she has
-to use an @emph{unquoted} macro call:
+But note what you've done: now that the result of @code{qar} is always
+a literal string, the only time a user can use nested macros is if she
+relies on an @emph{unquoted} macro call:
 
 @example
 qar(active)
 @result{}ACT
+qar([active])
address@hidden
 @end example
 
 @noindent
-where she wanted to reproduce what she used to do with @code{car}:
+leaving no way for her to reproduce what she used to do with @code{car}:
 
 @example
 car([active])
@@ -9394,7 +9461,7 @@ needs.  For instance, by default M4 uses @samp{`} and 
@samp{'} as
 quotes, but in the context of shell programming (and actually of most
 programming languages), that's about the worst choice one can make:
 because of strings and back-quoted expressions in shell code (such as
address@hidden'this'} and @samp{`that`}), because of literal characters in usual
address@hidden'this'} and @samp{`that`}), and because of literal characters in 
usual
 programming languages (as in @samp{'0'}), there are many unbalanced
 @samp{`} and @samp{'}.  Proper M4 quotation then becomes a nightmare, if
 not impossible.  In order to make M4 useful in such a context, its
-- 
1.5.3.2