FYI: underquoted AC_DEFUN doc for branch-1-7

[Alexandre Duret-Lutz]

I'm installing the documentation for underquoted AC_DEFUN on
branch-1-7 too, so that we can easily refer people to it before
1.8 is released.

2003-08-31  Alexandre Duret-Lutz  <address@hidden>

        * automake.texi (Extending aclocal): Merge changes from HEAD, to
        explain that aclocal 1.8 will warn about underquoted AC_DEFUN.

Index: automake.texi
===================================================================
RCS file: /cvs/automake/automake/automake.texi,v
retrieving revision 1.305.2.32
diff -u -r1.305.2.32 automake.texi
--- automake.texi       24 Aug 2003 22:37:41 -0000      1.305.2.32
+++ automake.texi       31 Aug 2003 21:18:17 -0000
@@ -1766,24 +1766,79 @@
 @cindex aclocal, extending
 @cindex Extending aclocal
 
-The @code{aclocal} program doesn't have any built-in knowledge of any
+The @command{aclocal} program doesn't have any built-in knowledge of any
 macros, so it is easy to extend it with your own macros.
 
-This is mostly used for libraries which want to supply their own
-Autoconf macros for use by other programs.  For instance the
address@hidden library supplies a macro @code{AM_GNU_GETTEXT} which
-should be used by any package using @code{gettext}.  When the library is
-installed, it installs this macro so that @code{aclocal} will find it.
-
-A file of macros should be a series of @code{AC_DEFUN}'s.  The
address@hidden programs also understands @code{AC_REQUIRE}, so it is
-safe to put each macro in a separate file.  @xref{Prerequisite Macros, ,
-, autoconf, The Autoconf Manual}, and @ref{Macro Definitions, , ,
-autoconf, The Autoconf Manual}.
+This can be used by libraries which want to supply their own Autoconf
+macros for use by other programs.  For instance the @command{gettext}
+library supplies a macro @code{AM_GNU_GETTEXT} which should be used by
+any package using @command{gettext}.  When the library is installed, it
+installs this macro so that @command{aclocal} will find it.
 
 A macro file's name should end in @file{.m4}.  Such files should be
-installed in @code{`aclocal --print-ac-dir`} (which usually happens to
-be @file{$(datadir)/aclocal}).
+installed in @file{$(datadir)/aclocal}.  This is as simple as writing:
+
address@hidden
+aclocaldir = $(datadir)/aclocal
+aclocal_DATA = mymacro.m4 myothermacro.m4
address@hidden example
+
+A file of macros should be a series of properly quoted
address@hidden's (@pxref{Macro Definitions, , , autoconf, The
+Autoconf Manual}).  The @command{aclocal} programs also understands
address@hidden (@pxref{Prerequisite Macros, , , autoconf, The
+Autoconf Manual}), so it is safe to put each macro in a separate file.
+Each file should have no side effects but macro definitions.
+Especially, any call to @code{AC_PREREQ} should be done inside the
+defined macro, not at the beginning of the file.
+
address@hidden underquoted AC_DEFUN
address@hidden AC_DEFUN
address@hidden AC_PREREQ
+
+Starting with Automake 1.8, @command{aclocal} will warn about all
+underquoted calls to @code{AC_DEFUN}.  We realize this will annoy a
+lot of people, because @command{aclocal} was not so strict in the past
+and many third party macros are underquoted; and we have to apologize
+for this temporary inconvenience.  The reason we have to be stricter
+is that a future implementation of @command{aclocal} will have to
+temporary include all these third party @file{.m4} files, maybe
+several times, even those which are not actually needed.  Doing so
+should alleviate many problem of the current implementation, however
+it requires a stricter style from the macro authors.  Hopefully it is
+easy to revise the existing macros.  For instance
address@hidden
+# bad style
+AC_PREREQ(2.57)
+AC_DEFUN(AX_FOOBAR,
+[AC_REQUIRE([AX_SOMETHING])dnl
+AX_FOO
+AX_BAR
+])
address@hidden example
address@hidden
+should be rewritten as
address@hidden
+AC_DEFUN([AX_FOOBAR],
+[AC_PREREQ(2.57)dnl
+AC_REQUIRE([AX_SOMETHING])dnl
+AX_FOO
+AX_BAR
+])
address@hidden example
+
+Wrapping the @code{AC_PREREQ} call inside the macro ensures that
+Autoconf 2.57 will not be required if @code{AX_FOOBAR} is not actually
+used.  Most importantly, quoting the first argument of @code{AC_DEFUN}
+allows the macro to be redefined or included twice (otherwise this
+first argument would be expansed during the second definition).
+
+If you have been directed here by the @command{aclocal} diagnostic but
+are not the maintainer of the implicated macro, you will want to
+contact the maintainer of that macro.  Please make sure you have the
+last version of the macro and that the problem already hasn't been
+reported before doing so: people tend to work faster when they aren't
+flooded by mails.
 
 
 @node Top level, Alternative, configure, Top
-- 
Alexandre Duret-Lutz