[PATCH 1/3] extract "Programming in M4sh" into its own chapter

[Paolo Bonzini]

Ok, so here we go. :-)

This patch raises the level of the "Programming in M4sh" section of the
manual to a chapter.  It is needed to group macros sensibly now that we
are going to document more initialization-related stuff.

2008-10-10  Paolo Bonzini  <address@hidden>

        * doc/autoconf.texi (Programming in M4sh): Make its own chapter.
        Split macros in multiple sections.

---
 ChangeLog         |    4 ++
 doc/autoconf.texi |   81 ++++++++++++++++++++++++++++++++---------------------
 2 files changed, 53 insertions(+), 32 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index e4176e8..db82caa 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2008-10-10  Paolo Bonzini  <address@hidden>
+
+       * doc/autoconf.texi (Programming in M4sh): Make its own chapter.
+
 2008-10-09  Paolo Bonzini  <address@hidden>
 
        * m4sugar/m4sh.m4 (AS_SHELL_SANITIZE): Delay setting as_me
diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index 5753d37..cae6bd5 100644
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -260,6 +260,7 @@ freedom.''
 * Writing Tests::               How to write new feature checks
 * Results::                     What to do with results from feature checks
 * Programming in M4::           Layers on top of which Autoconf is written
+* Programming in M4sh::         Shell portability layer
 * Writing Autoconf Macros::     Adding new macros to Autoconf
 * Portable Shell::              Shell script portability pitfalls
 * Portable Make::               Makefile portability pitfalls
@@ -428,7 +429,11 @@ Programming in M4
 * M4 Quotation::                Protecting macros from unwanted expansion
 * Using autom4te::              The Autoconf executables backbone
 * Programming in M4sugar::      Convenient pure M4 macros
-* Programming in M4sh::         Common shell Constructs
+
+Programming in M4sh
+
+* Common Shell Constructs::     Portability layer for common shell constructs
+* Initialization Macros::       Macros to establish a sane shell environment
 * File Descriptor Macros::      File descriptor macros for input and output
 
 M4 Quotation
@@ -9241,8 +9246,6 @@ matter of fact, @emph{anything that is not documented 
must not be used}.
 * M4 Quotation::                Protecting macros from unwanted expansion
 * Using autom4te::              The Autoconf executables backbone
 * Programming in M4sugar::      Convenient pure M4 macros
-* Programming in M4sh::         Common shell Constructs
-* File Descriptor Macros::      File descriptor macros for input and output
 @end menu
 
 @node M4 Quotation
@@ -11771,10 +11774,7 @@ Any token matching @var{pattern} is allowed, including 
if it matches an
 @end defmac
 
 @node Programming in M4sh
address@hidden Programming in M4sh
-
address@hidden FIXME: Eventually will become a chapter, as it is not related to
address@hidden programming in M4 per se.
address@hidden Programming in M4sh
 
 M4sh, pronounced ``mash'', is aiming at producing portable Bourne shell
 scripts.  This name was coined by Lars J. Aas, who notes that,
@@ -11807,6 +11807,15 @@ delimiter namespace @samp{^_AS[A-Z]} in the output 
file.  You should not
 define your own macros or output shell code that conflicts with these
 namespaces.
 
address@hidden
+* Common Shell Constructs::     Portability layer for common shell constructs
+* Initialization Macros::       Macros to establish a sane shell environment
+* File Descriptor Macros::      File descriptor macros for input and output
address@hidden menu
+
address@hidden Common Shell Constructs
address@hidden Common Shell Constructs
+
 M4sh provides portable alternatives for some common shell constructs
 that unfortunately are not portable in practice.
 
@@ -11820,14 +11829,6 @@ if @code{$file} is @samp{/one/two/three}, the command
 @end defmac
 @end ignore
 
address@hidden AS_BOURNE_COMPATIBLE
address@hidden
-Set up the shell to be more compatible with the Bourne shell as
-standardized by Posix, if possible.  This may involve setting
-environment variables, or setting options, or similar
-implementation-specific actions.
address@hidden defmac
-
 @defmac AS_CASE (@var{word}, @ovar{pattern1}, @ovar{if-matched1}, @
   @dots{}, @ovar{default})
 @asindex{CASE}
@@ -11836,12 +11837,15 @@ against one or more patterns.  @var{if-matched} is 
run if the
 corresponding pattern matched @var{word}, else @var{default} is run.
 @end defmac
 
address@hidden Deprecated, to be replaced by a better API
address@hidden
 @defmac AS_DIRNAME (@var{file-name})
 @asindex{DIRNAME}
 Output the directory portion of @var{file-name}.  For example,
 if @code{$file} is @samp{/one/two/three}, the command
 @code{dir=`AS_DIRNAME(["$file"])`} sets @code{dir} to @samp{/one/two}.
 @end defmac
address@hidden ignore
 
 @defmac AS_IF (@var{test1}, @ovar{run-if-true1}, @dots{}, @ovar{run-if-false})
 @asindex{IF}
@@ -11862,14 +11866,6 @@ ensures any required macros of @code{HANDLE_FOO}
 are expanded before the first test.
 @end defmac
 
address@hidden AS_INIT
address@hidden
-Initialize the M4sh environment.  This macro calls @code{m4_init}, then
-outputs the @code{#! /bin/sh} line, a notice about where the output was
-generated from, and code to sanitize the environment for the rest of the
-script.  Finally, it changes the current diversion to @code{BODY}.
address@hidden defmac
-
 @defmac AS_MKDIR_P (@var{file-name})
 @asindex{MKDIR_P}
 Make the directory @var{file-name}, including intervening directories
@@ -11884,15 +11880,6 @@ script.
 Also see the @code{AC_PROG_MKDIR_P} macro (@pxref{Particular Programs}).
 @end defmac
 
address@hidden AS_SHELL_SANITIZE
address@hidden
-Initialize the shell suitably for @command{configure} scripts.  This has
-the effect of @code{AS_BOURNE_COMPATIBLE}, and sets some other
-environment variables for predictable results from configuration tests.
-For example, it sets @env{LC_ALL} to change to the default C locale.
address@hidden Shell Variables}.
address@hidden defmac
-
 @defmac AS_TR_CPP (@var{expression})
 @asindex{TR_CPP}
 Transform @var{expression} into a valid right-hand side for a C @code{#define}.
@@ -11936,6 +11923,36 @@ glibc (@pxref{String/Array Comparison, , String/Array 
Comparison, libc,
 The @acronym{GNU} C Library}).
 @end defmac
 
address@hidden Initialization Macros
address@hidden Initialization Macros
+
address@hidden AS_BOURNE_COMPATIBLE
address@hidden
+Set up the shell to be more compatible with the Bourne shell as
+standardized by Posix, if possible.  This may involve setting
+environment variables, or setting options, or similar
+implementation-specific actions.  This macro is deprecated, since
address@hidden already invokes it.
address@hidden defmac
+
address@hidden AS_INIT
address@hidden
+Initialize the M4sh environment.  This macro calls @code{m4_init}, then
+outputs the @code{#! /bin/sh} line, a notice about where the output was
+generated from, and code to sanitize the environment for the rest of the
+script.  Finally, it changes the current diversion to @code{BODY}.
address@hidden defmac
+
address@hidden AS_SHELL_SANITIZE
address@hidden
+Initialize the shell suitably for @command{configure} scripts.  This has
+the effect of @code{AS_BOURNE_COMPATIBLE}, and sets some other
+environment variables for predictable results from configuration tests.
+For example, it sets @env{LC_ALL} to change to the default C locale.
address@hidden Shell Variables}.  This macro is deprecated, since
address@hidden already invokes it.
address@hidden defmac
+
 
 @node File Descriptor Macros
 @section File Descriptor Macros
-- 
1.5.5