AC_DEFUN_ONCE documentation

[Alexandre Duret-Lutz]

Here is my proposal.

2004-10-10  Alexandre Duret-Lutz  <address@hidden>

        * doc/autoconf.texi (One-Shot Macros): New node.

Index: doc/autoconf.texi
===================================================================
RCS file: /cvsroot/autoconf/autoconf/doc/autoconf.texi,v
retrieving revision 1.834
diff -u -r1.834 autoconf.texi
--- doc/autoconf.texi   28 Sep 2004 17:21:52 -0000      1.834
+++ doc/autoconf.texi   10 Oct 2004 16:57:54 -0000
@@ -452,6 +452,7 @@
 
 * Prerequisite Macros::         Ensuring required information
 * Suggested Ordering::          Warning about possible ordering problems
+* One-Shot Macros::             Ensuring a macro is called only once
 
 Portable Shell Programming
 
@@ -462,6 +463,7 @@
 * Shell Substitutions::         Variable and command expansions
 * Assignments::                 Varying side effects of assignments
 * Parentheses::                 Parentheses in shell scripts
+* Slashes::                     Slashes in shell scripts
 * Special Shell Variables::     Variables you should not change
 * Limitations of Builtins::     Portable use of not so portable /bin/sh
 * Limitations of Usual Tools::  Portable use of portable tools
@@ -8947,6 +8949,7 @@
 @menu
 * Prerequisite Macros::         Ensuring required information
 * Suggested Ordering::          Warning about possible ordering problems
+* One-Shot Macros::             Ensuring a macro is called only once
 @end menu
 
 @node Prerequisite Macros
@@ -9089,6 +9092,31 @@
 that it has been called.
 @end defmac
 
address@hidden One-Shot Macros
address@hidden One-Shot Macros
address@hidden One-shot macros
address@hidden Macros, called once
+
+Some macros should be called only once, either because calling them
+multiple time is unsafe, or because it is bad style.  For instance
+Autoconf ensures that @code{AC_CANONICAL_BUILD} and cousins
+(@pxref{Canonicalizing}) are evaluated only once, because it makes no
+sense to run these expensive checks more than once.  Such one-shot
+macros can be defined using @code{AC_DEFUN_ONCE}.
+
address@hidden AC_DEFUN_ONCE (@var{macro-name}, @var{macro-body})
address@hidden
+
+Declare macro @var{macro-name} like @code{AC_DEFUN} would (@pxref{Macro
+Definitions}), and emit a warning any time the macro is called more than
+once.
address@hidden defmac
+
+Obviously it is not sensible to evaluate a macro defined by
address@hidden in a macro defined by @code{AC_DEFUN}, most of the
+times you will want to use @code{AC_REQUIRE} (@pxref{Prerequisite
+Macros}).
+
 @node Obsoleting Macros
 @section Obsoleting Macros
 @cindex Obsoleting macros

-- 
Alexandre Duret-Lutz