Re: Confusing sample in autoconf manual

[Eric Blake]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

According to santilistas on 8/9/2009 11:08 AM:

[finally getting to this thread]

> By the way, is this the correct list to send this remarks?
> 
> In section 3.1.2 The Autoconf language, there is the example on Iron
> Maiden and AC_DC.
> 
> @example
> echo "Hard rock was here!  --[AC_DC]"
> @end example

in configure.ac

> 
> which results in:
> 
> @example
> echo "Hard rock was here!  --AC_DC"
> @end example

in configure

> that demonstrates the losing of the quotation. However, a little bit
> below there is this example:
> 
> @example
> AC_MSG_WARN([[AC_DC stinks  --Iron Maiden]])
> @end example

in configure.ac

which leads to something roughly like:

$as_echo "AC_DC stinks  --Iron Maiden"

in configure.

> 
> which tries to show that the quotation is lost, but there is no quotation.

There WAS quotation - the double quotes were around the entire sentence,
rather than just the problematic section.  But I can improve the example
to mention which file we are looking at, and show both quoting styles:

> @example
> [echo "Hard rock was here!  --AC_DC"] dnl style 1
> echo "Hard rock was here!  --[AC_DC]" dnl style 2
> @end example

in configure.ac, leads to:

> @example
> echo "Hard rock was here!  --AC_DC"
> echo "Hard rock was here!  --AC_DC"
> @end example

in configure.

> 
> Shouldn't it be written like this?:
> 
> @example
> AC_MSG_WARN([[AC_DC stinks  --[Iron Maiden] ]])
> @end example

No, unless we want [] in configure, which is NOT what the first example
was doing.

> --santilín

Do you have a full name that you'd like to be credited as in the THANKS
file?  Other than that, here's what I'm thinking of pushing.

- --
Don't work too hard, make some time for fun as well!

Eric Blake             address@hidden
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (Cygwin)
Comment: Public key at home.comcast.net/~ericblake/eblake.gpg
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iEYEARECAAYFAkqpusgACgkQ84KuGfSFAYBiwgCgyusjRiBalFgYbsiBBn4My+AU
G8cAn3D71FsxBsw7vIgMjcS+hvbKlWzo
=1PZD
-----END PGP SIGNATURE-----

>From 881638c743d349a62ab32664d6d27e7bd26f4d9e Mon Sep 17 00:00:00 2001
From: Eric Blake <address@hidden>
Date: Thu, 10 Sep 2009 20:47:50 -0600
Subject: [PATCH] Improve documentation on quoting.
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* doc/autoconf.texi (Autoconf Language): Clarify quoting example.
* THANKS: Update.
Reported by santilín.

Signed-off-by: Eric Blake <address@hidden>
---
 ChangeLog         |    5 +++++
 doc/autoconf.texi |   23 ++++++++++++++++++++---
 2 files changed, 25 insertions(+), 3 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 9ea4ed6..97bed79 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,10 @@
 2009-09-10  Eric Blake  <address@hidden>

+       Improve documentation on quoting.
+       * doc/autoconf.texi (Autoconf Language): Clarify quoting example.
+       * THANKS: Update.
+       Reported by santilín.
+
        Document that AS_INIT is automatically used.
        * doc/autoconf.texi (Initialization Macros) <AS_INIT>: Add words
        to clarify that only bare-bones scripts need a direct AS_INIT.
diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index 4203cd0..50583f5 100644
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -1177,29 +1177,46 @@ Autoconf Language

 In other cases, you may have to use text that also resembles a macro
 call.  You must quote that text even when it is not passed as a macro
-argument:
+argument.  For example, these two approaches in @file{configure.ac}
+(quoting just the potential problems, or quoting the entire line) will
+protect your script in case autoconf ever adds a macro @code{AC_DC}:

 @example
 echo "Hard rock was here!  --[AC_DC]"
+[echo "Hard rock was here!  --AC_DC"]
 @end example

 @noindent
-which results in:
+which results in this text in @file{configure}:

 @example
 echo "Hard rock was here!  --AC_DC"
+echo "Hard rock was here!  --AC_DC"
 @end example

 @noindent
 When you use the same text in a macro argument, you must therefore have
 an extra quotation level (since one is stripped away by the macro
 substitution).  In general, then, it is a good idea to @emph{use double
-quoting for all literal string arguments}:
+quoting for all literal string arguments}, either around just the
+problematic portions, or over the entire argument:

 @example
+AC_MSG_WARN([[AC_DC] stinks  --Iron Maiden])
 AC_MSG_WARN([[AC_DC stinks  --Iron Maiden]])
 @end example

+However, the above example triggers a warning about a possibly
+unexpanded macro when running @command{autoconf}, because it collides
+with the namespace of macros reserved for the Autoconf language.  To be
+really safe, you can use additional escaping (either a quadrigraph, or
+creative shell constructs) to silence that particular warning:
+
address@hidden
+echo "Hard rock was here!  --AC""_DC"
+AC_MSG_WARN([[AC@@&t@@_DC stinks  --Iron Maiden]])
address@hidden example
+
 You are now able to understand one of the constructs of Autoconf that
 has been continually address@hidden  The rule of thumb is that
 @emph{whenever you expect macro expansion, expect quote expansion};
-- 
1.6.3.3.334.g916e1