Quotation Rule Of Thumb - take 2

[Pavel Roskin]

Hello!

This is the revised patch for "Quotation Rule Of Thumb". Since the patch
is hard to read, I converted the new variant of text to html and put here:

http://www.red-bean.com/~proski/autoconf_8.html#SEC95

I still feel uneasy whether we should document double quoting or always
recommend using quadrigraphs. This variant documents both.

ChangeLog:
        * doc/autoconf.texi (Quotation Rule Of Thumb): Document
        quadrigraphs. Better examples. Mostly rewritten.

-- 
Regards,
Pavel Roskin

____________________________
--- doc/autoconf.texi
+++ doc/autoconf.texi
@@ -7600,86 +7600,113 @@

 @center @emph{One pair of quotes per pair of parentheses.}

-Never over-quote, never under-quote, in particular in the definition of
-macros.  In the few places where the macros need to use brackets
-(usually in C program text or regular expressions), quote properly
address@hidden arguments}!
+Remember that Autoconf deals with shell and C code which is full of
+symbols that have special meaning in @code{m4}.  That's why care should
+be taken to prevent @code{m4} from interpreting that code throughout the
+expansion process, but in the same time expand every macro.

-It is frequent to read Autoconf programs with snippets like:
+Following is an example of proper quoting:

 @example
-AC_TRY_LINK(
-changequote(<<, >>)dnl
-<<#include <time.h>
-#ifndef tzname /* For SGI.  */
-extern char *tzname[]; /* RS6000 and others reject char **tzname.  */
-#endif>>,
-changequote([, ])dnl
-[atoi (*tzname);], ac_cv_var_tzname=yes, ac_cv_var_tzname=no)
address@hidden
+AC_CHECK_LIB([z], [adler32], [],
+             [AC_MSG_ERROR([zlib is required])])
address@hidden group
 @end example

address@hidden
-which is incredibly useless since @code{AC_TRY_LINK} is @emph{already}
-double quoting, so you just need:
+Note that @code{AC_MSG_ERROR} is passed as text to @code{AC_CHECK_LIB}
+and is expanded by @code{m4} after @code{AC_CHECK_LIB}.
+
+Sometimes you can find that the arguments are not quoted, but it's
+a bad practice.  Some macros can expand to simple constructs, so that
+the caller processes the already expanded code without any adverse
+effects.  However, as Autoconf develops, macros like @code{AC_MSG_ERROR}
+grow in complexity, and then you suddenly have a problem, usually an
address@hidden error or invalid shell code in @code{configure}.  Here's
+a @emph{bad} example:

 @example
-AC_TRY_LINK(
-[#include <time.h>
-#ifndef tzname /* For SGI.  */
-extern char *tzname[]; /* RS6000 and others reject char **tzname.  */
-#endif],
-            [atoi (*tzname);],
-            [ac_cv_var_tzname=yes],
-            [ac_cv_var_tzname=no])
address@hidden
+AC_CHECK_LIB(z, adler32, ,
+             AC_MSG_ERROR(zlib is required))
address@hidden group
 @end example

address@hidden
-The M4 fluent reader noted that these two writings are rigorously
-equivalent, since @code{m4} swallows both the @samp{changequote(<<, >>)}
-and @samp{<<} @samp{>>} when it @dfn{collects} the arguments: these
-quotes are not part of the arguments!
+Note that you technically don't have to quote the arguments that don't
+contain macros, commas and other @code{m4} active symbols, but the
+Autoconf style recommends you to quote anyway.
+
+If you double quote the arguments, the macros will not be expanded -
+they will be left in the @code{configure} script as is, causing it to
+be invalid shell code.  The @code{autoconf} program can usually detect
+such cases and report an error.

-Simplified, the example above is just doing this:
+If the argument contains square brackets meant to be interpreted
+literally you may need to use @emph{double} quotes:

 @example
-changequote(<<, >>)dnl
-<<[]>>
-changequote([, ])dnl
address@hidden
+AC_LINK_IFELSE([AC_LANG_PROGRAM(
+[[#include <time.h>
+#ifndef tzname /* For SGI.  */
+extern char *tzname[]; /* RS6000 rejects char **tzname.  */
+#endif]],
+                                [atoi (*tzname);])],
+               [ac_cv_var_tzname=yes],
+               [ac_cv_var_tzname=no])
address@hidden group
 @end example

address@hidden
-instead of simply
+This approach has several limitations. You cannot use macros in the
+double-quoted arguments. You cannot use non-matching square brackets.
+Also, the dollar sign followed by a number is interpreted by @code{m4}
+no matter how many quotes you are using.

address@hidden
-[[]]
address@hidden example
+In order to circumvent those limitations (albeit at the expense of
+readability), Autoconf provides so called quadrigraphs, which are
+replaced with the ``problematic'' characters after the m4 processing
+is done.  The quadrigraphs are substituted according to the following
+table:
+
address@hidden @samp
address@hidden @@<:@@
+[
+
address@hidden @@:>@@
+]
+
address@hidden @@S\@@
+$
+
address@hidden @@%:@@
+#

address@hidden table

-With macros which do not double quote their arguments (which is the
-rule), double quote the (risky) literals:
+The above example can now be rewritten as:

 @example
address@hidden
 AC_LINK_IFELSE([AC_LANG_PROGRAM(
-[[#include <time.h>
-#ifndef tzname /* For SGI.  */
-extern char *tzname[]; /* RS6000 and others reject char **tzname.  */
-#endif]],
+[@@%:@@include <time.h>
+@@%:@@ifndef tzname /* For SGI. */
+extern char *tzname@@<:@@@@:>@@; /* RS6000 rejects char **tzname. */
+@@%:@@endif],
                                 [atoi (*tzname);])],
                [ac_cv_var_tzname=yes],
                [ac_cv_var_tzname=no])
address@hidden group
 @end example

address@hidden FIXME: Quadrigraphs and hopeless cases.
+Never over-quote, never under-quote, in particular in the definition of
+macros.  In the few places where the macros need to use brackets
+(usually in C program text or regular expressions), quote properly
address@hidden arguments} or use quadrigraphs!

-When you create a @code{configure} script using newly written macros,
-examine it carefully to check whether you need to add more quotes in
-your macros.  If one or more words have disappeared in the @code{m4}
-output, you need more quotes.  When in doubt, quote.
-
-However, it's also possible to put on too many layers of quotes.  If
-this happens, the resulting @code{configure} script will contain
-unexpanded macros.  The @code{autoconf} program checks for this problem
-by doing @samp{grep AC_ configure}.
+Note that some macros, for example as @code{AC_TRY_LINK}, are trying to
+help you pass C code to them by quoting some of their arguments
+themselves.  This practice is now deprecated.  Such macros will be
+gradually eliminated.


 @node Reporting Messages, Dependencies Between Macros, Quoting, Writing Macros
____________________________