2006-10-13  Stepan Kasal  <address@hidden>

	* doc/autoconf.texi (Autoheader Macros): Warn that the text
	added to the template can get mangled.

Index: doc/autoconf.texi
===================================================================
RCS file: /cvsroot/autoconf/autoconf/doc/autoconf.texi,v
retrieving revision 1.1093
diff -u -r1.1093 autoconf.texi
--- doc/autoconf.texi	11 Oct 2006 22:38:42 -0000	1.1093
+++ doc/autoconf.texi	13 Oct 2006 09:34:16 -0000
@@ -3137,27 +3137,12 @@
 symbol, you must define a template for it.  If there are missing
 templates, @command{autoheader} fails with an error message.
 
-The simplest way to create a template for a @var{symbol} is to supply
-the @var{description} argument to an @samp{AC_DEFINE(@var{symbol})}; see
address@hidden Symbols}.  You may also use one of the following macros.
+The template for a @var{symbol} is created
+by @command{autoheader} from
+the @var{description} argument to an @code{AC_DEFINE};
+see @ref{Defining Symbols}.
 
address@hidden AH_VERBATIM (@var{key}, @var{template})
address@hidden
-Tell @command{autoheader} to include the @var{template} as-is in the header
-template file.  This @var{template} is associated with the @var{key},
-which is used to sort all the different templates and guarantee their
-uniqueness.  It should be a symbol that can be defined via @code{AC_DEFINE}.
-
-For example:
-
address@hidden
-AH_VERBATIM([_GNU_SOURCE],
-[/* Enable GNU extensions on systems that have them.  */
-#ifndef _GNU_SOURCE
-# define _GNU_SOURCE
-#endif])
address@hidden example
address@hidden defmac
+For special needs, you can use the following macros.
 
 
 @defmac AH_TEMPLATE (@var{key}, @var{description})
@@ -3189,6 +3174,14 @@
 @end defmac
 
 
address@hidden AH_VERBATIM (@var{key}, @var{template})
address@hidden
+Tell @command{autoheader} to include the @var{template} as-is in the header
+template file.  This @var{template} is associated with the @var{key},
+which is used to sort all the different templates and guarantee their
+uniqueness.  It should be a symbol that can be defined via @code{AC_DEFINE}.
+
+
 @defmac AH_TOP (@var{text})
 @ahindex{TOP}
 Include @var{text} at the top of the header template file.
@@ -3201,6 +3194,16 @@
 @end defmac
 
 
+Please note that @var{text} gets included ``verbatim'' to the template file,
+not to the resulting config header, so it can easily get mangled when the
+template is processed.  There is rarely a need for something else than
+
address@hidden
+AH_BOTTOM([#include <custom.h>])
address@hidden example
+
+
+
 @node Configuration Commands
 @section Running Arbitrary Configuration Commands
 @cindex Configuration commands