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

[Paolo Bonzini-2]

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  <bonzini@...>

        * 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 @@
[phone]  Paolo Bonzini  <bonzini@...>
+
+ * doc/autoconf.texi (Programming in M4sh): Make its own chapter.
+
 2008-10-09  Paolo Bonzini  <bonzini@...>
 
  * 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
-@section Programming in M4sh
-
-@c FIXME: Eventually will become a chapter, as it is not related to
-@c programming in M4 per se.
+@chapter 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.
 
+@menu
+* 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
+@end menu
+
+@node Common Shell Constructs
+@section 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
 
-@defmac AS_BOURNE_COMPATIBLE
-@asindex{BOURNE_COMPATIBLE}
-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.
-@end 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
 
+@c Deprecated, to be replaced by a better API
+@ignore
 @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
+@end 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
 
-@defmac AS_INIT
-@asindex{INIT}
-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}.
-@end 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
 
-@defmac AS_SHELL_SANITIZE
-@asindex{SHELL_SANITIZE}
-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.
-@xref{Special Shell Variables}.
-@end 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
 
+@node Initialization Macros
+@section Initialization Macros
+
+@defmac AS_BOURNE_COMPATIBLE
+@asindex{BOURNE_COMPATIBLE}
+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
+@code{AS_INIT} already invokes it.
+@end defmac
+
+@defmac AS_INIT
+@asindex{INIT}
+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}.
+@end defmac
+
+@defmac AS_SHELL_SANITIZE
+@asindex{SHELL_SANITIZE}
+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.
+@xref{Special Shell Variables}.  This macro is deprecated, since
+@code{AS_INIT} already invokes it.
+@end defmac
+
 
 @node File Descriptor Macros
 @section File Descriptor Macros
--
1.5.5

[Paolo Bonzini-2]

This patch documents $as_me and $LINENO, which are the sole constructs
(for now) that explicitly require a *_PREPARE macro because they are
variables.  So those are defined without the hyphen and documented.

(I started using --thread to keep outgoing mail more organized).

2008-10-10  Paolo Bonzini  <bonzini@...>

        * bin/autoconf.as: Invoke AS_ME_PREPARE.
        * lib/m4sugar/m4sh.m4 (AS_ME_PREPARE, AS_LINENO_PREPARE): New.
        * doc/autoconf.texi (Initialization macros): Document them.
        (Portable Shell): Refer to AS_LINENO_PREPARE.
---
 ChangeLog           |    7 +++++++
 bin/autoconf.as     |    1 +
 doc/autoconf.texi   |   25 +++++++++++++++++++------
 lib/m4sugar/m4sh.m4 |    5 ++---
 4 files changed, 29 insertions(+), 9 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index db82caa..3efc2f2 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,12 @@
 2008-10-10  Paolo Bonzini  <bonzini@...>
 
+ * bin/autoconf.as: Invoke AS_ME_PREPARE.
+ * lib/m4sugar/m4sh.m4 (AS_ME_PREPARE, AS_LINENO_PREPARE): New.
+ * doc/autoconf.texi (Initialization macros): Document them.
+ (Portable Shell): Refer to AS_LINENO_PREPARE.
+
[phone]  Paolo Bonzini  <bonzini@...>
+
  * doc/autoconf.texi (Programming in M4sh): Make its own chapter.
 
 2008-10-09  Paolo Bonzini  <bonzini@...>
diff --git a/bin/autoconf.as b/bin/autoconf.as
index 3a25322..6eab32a 100644
--- a/bin/autoconf.as
+++ b/bin/autoconf.as
@@ -22,6 +22,7 @@ m4_divert_push([HEADER-COPYRIGHT])dnl
 # 02110-1301, USA.
 
 m4_divert_pop([HEADER-COPYRIGHT])dnl back to BODY
+AS_ME_PREPARE[]dnl
 
 usage=["\
 Usage: $0 [OPTION]... [TEMPLATE-FILE]
diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index cae6bd5..1256f97 100644
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -11943,6 +11943,18 @@ generated from, and code to sanitize the environment for the rest of the
 script.  Finally, it changes the current diversion to @code{BODY}.
 @end defmac
 
+@defmac AS_LINENO_PREPARE
+@asindex{LINENO_PREPARE}
+Find a shell that supports the special variable @code{$LINENO}, which
+contains the number of the currently executing line.
+@end defmac
+
+@defmac AS_ME_PREPARE
+@asindex{ME_PREPARE}
+Set up variable @code{$as_me} to be the name of the currently executing
+script.
+@end defmac
+
 @defmac AS_SHELL_SANITIZE
 @asindex{SHELL_SANITIZE}
 Initialize the shell suitably for @command{configure} scripts.  This has
@@ -14002,12 +14014,13 @@ etc.)@: as described above.
 @item LINENO
 Most modern shells provide the current line number in @code{LINENO}.
 Its value is the line number of the beginning of the current command.
-Autoconf attempts to execute @command{configure} with a shell that
-supports @code{LINENO}.
-If no such shell is available, it attempts to implement @code{LINENO}
-with a Sed prepass that replaces each instance of the string
-@code{$LINENO} (not followed by an alphanumeric character) with the
-line's number.
+M4sh, and hence Autoconf, attempts to execute @command{configure} with
+a shell that supports @code{LINENO}.  If no such shell is available, it
+attempts to implement @code{LINENO} with a Sed prepass that replaces each
+instance of the string @code{$LINENO} (not followed by an alphanumeric
+character) with the line's number.  In M4sh scripts you should execute
+@code{AS_LINENO_PREPARE} so that these workarounds are included in
+your script.
 
 You should not rely on @code{LINENO} within @command{eval}, as the
 behavior differs in practice.  Also, the possibility of the Sed
diff --git a/lib/m4sugar/m4sh.m4 b/lib/m4sugar/m4sh.m4
index b64a6cf..b9db92d 100644
--- a/lib/m4sugar/m4sh.m4
+++ b/lib/m4sugar/m4sh.m4
@@ -457,9 +457,6 @@ export LC_ALL
 LANGUAGE=C
 export LANGUAGE
 
-dnl Delay this until after shell functions are defined.
-AS_REQUIRE([_AS_ME_PREPARE])
-
 # CDPATH.
 $as_unset CDPATH
 ])# AS_SHELL_SANITIZE
@@ -911,6 +908,7 @@ fi
 # _AS_ME_PREPARE
 # --------------
 # Define $as_me to the basename of the executable file's name.
+m4_defun([AS_ME_PREPARE], [AS_REQUIRE([_$0])])
 m4_defun([_AS_ME_PREPARE],
 [AS_REQUIRE([_AS_BASENAME_PREPARE])dnl
 as_me=`AS_BASENAME("$[0]")`
@@ -939,6 +937,7 @@ m4_define([_AS_LINENO_WORKS],
 # the case of embedded executables (such as config.status within
 # configure) you'd compare LINENO wrt config.status vs. _oline_ wrt
 # configure.
+m4_defun([AS_LINENO_PREPARE], [AS_REQUIRE([_$0])])
 m4_defun([_AS_LINENO_PREPARE],
 [AS_REQUIRE([_AS_CR_PREPARE])dnl
 AS_REQUIRE([_AS_ME_PREPARE])dnl
--
1.5.5

[Paolo Bonzini-2]

Finally, here is AS_INIT_GENERATED.  Unfortunately it does not do
really everything as it does not include the she-bang line, but that's
good enough for now and it can be used already in status.m4.

2008-10-10  Paolo Bonzini  <bonzini@...>

        * lib/m4sugar/m4sh.m4 (AS_INIT_GENERATED): New.
        * lib/autoconf/status.m4 (_AC_OUTPUT_CONFIG_STATUS): Use it.
        * doc/autoconf.texi (Initialization macros): Document it.
---
 ChangeLog              |    6 ++++++
 doc/autoconf.texi      |    9 +++++++++
 lib/autoconf/status.m4 |    6 +-----
 lib/m4sugar/m4sh.m4    |   10 ++++++++++
 4 files changed, 26 insertions(+), 5 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 3efc2f2..c91dc10 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,11 @@
 2008-10-10  Paolo Bonzini  <bonzini@...>
 
+ * lib/m4sugar/m4sh.m4 (AS_INIT_GENERATED): New.
+ * lib/autoconf/status.m4 (_AC_OUTPUT_CONFIG_STATUS): Use it.
+ * doc/autoconf.texi (Initialization macros): Document it.
+
[phone]  Paolo Bonzini  <bonzini@...>
+
  * bin/autoconf.as: Invoke AS_ME_PREPARE.
  * lib/m4sugar/m4sh.m4 (AS_ME_PREPARE, AS_LINENO_PREPARE): New.
  * doc/autoconf.texi (Initialization macros): Document them.
diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index 1256f97..f7a06c9 100644
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -11943,6 +11943,15 @@ generated from, and code to sanitize the environment for the rest of the
 script.  Finally, it changes the current diversion to @code{BODY}.
 @end defmac
 
+@defmac AS_INIT_GENERATED
+@asindex{INIT}
+Initialize the M4sh environment.  This macro emits again all the
+code that is generated by @code{AS_INIT}, including the expansion of
+@code{AS_BOURNE_COMPATIBLE} and @code{AS_SHELL_SANITIZE}.  It is meant
+to be used in a here document when generating other shell scripts,
+after having output the @code{#! /bin/sh} line using @code{#! $SHELL.}
+@end defmac
+
 @defmac AS_LINENO_PREPARE
 @asindex{LINENO_PREPARE}
 Find a shell that supports the special variable @code{$LINENO}, which
diff --git a/lib/autoconf/status.m4 b/lib/autoconf/status.m4
index ddc5f47..6d622b9 100644
--- a/lib/autoconf/status.m4
+++ b/lib/autoconf/status.m4
@@ -1332,11 +1332,7 @@ SHELL=\${CONFIG_SHELL-$SHELL}
 _ACEOF
 
 cat >>$CONFIG_STATUS <<\_ACEOF || ac_write_fail=1
-AS_SHELL_SANITIZE
-dnl Watch out, this is directly the initializations, do not use
-dnl AS_PREPARE, otherwise you'd get it output in the initialization
-dnl of configure, not config.status.
-_AS_PREPARE
+AS_INIT_GENERATED
 exec AS_MESSAGE_FD>&1
 
 # Save the log message, to keep $[0] and so on meaningful, and to
diff --git a/lib/m4sugar/m4sh.m4 b/lib/m4sugar/m4sh.m4
index b9db92d..bbf9a25 100644
--- a/lib/m4sugar/m4sh.m4
+++ b/lib/m4sugar/m4sh.m4
@@ -1676,6 +1676,16 @@ m4_define([AS_VAR_POPDEF],
 ## ----------------- ##
 
 
+# AS_INIT_GENERATED
+# -----------------
+# Emit m4sh initialization code in a suitable form for a here document.
+# Does not emit the `#!' sequence, which should be generated with
+# `#! $SHELL'.
+m4_defun([AS_INIT_GENERATED],
+[m4_require([AS_PREPARE])dnl
+AS_SHELL_SANITIZE
+_AS_PREPARE])
+
 # AS_INIT
 # -------
 # Initialize m4sh.
--
1.5.5

[Eric Blake]

Paolo Bonzini <bonzini <at> gnu.org> writes:

> 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.

OK to apply.

--
Eric Blake

[Eric Blake]

Paolo Bonzini <bonzini <at> gnu.org> writes:

>
> This patch documents $as_me and $LINENO, which are the sole constructs
> (for now) that explicitly require a *_PREPARE macro because they are
> variables.  So those are defined without the hyphen and documented.
>

OK to apply, after addressing these nits.

Add a NEWS item mentioning the new macros.

>
> +@defmac AS_LINENO_PREPARE
> +@asindex{LINENO_PREPARE}
> +Find a shell that supports the special variable @code{$LINENO}, which
> +contains the number of the currently executing line.
> +@end defmac

I would consider writing this as @env{LINENO} rather than @code{$LINENO}.  
Also, add @evindex LINENO.  And it may be worth a mention that configure
scripts have already done AS_{LINENO,ME}_PREPARE (these macros are only needed
for third-party m4sh scripts that don't use the undocumented AS_PREPARE, and
which don't use other m4sh features that pull in these two variables).

> +
> +@defmac AS_ME_PREPARE
> +@asindex{ME_PREPARE}
> +Set up variable @code{$as_me} to be the name of the currently executing
> +script.
> +@end defmac

I would mention that it is the basename (not the complete $0), but am not quite
sure of the best wording to use for that.  Add @evindex as_me.

> +M4sh, and hence Autoconf, attempts to execute @command{configure} with
> +a shell that supports @code{LINENO}.  If no such shell is available, it
> +attempts to implement @code{LINENO} with a Sed prepass that replaces each
> +instance of the string @code{$LINENO} (not followed by an alphanumeric
> +character) with the line's number.  In M4sh scripts you should execute
> +@code{AS_LINENO_PREPARE} so that these workarounds are included in
> +your script.

Worth another mention that configure does this automatically?

>
> -dnl Delay this until after shell functions are defined.
> -AS_REQUIRE([_AS_ME_PREPARE])
> -

Looks like you sent this mail before rebasing (shouldn't be a problem, though).

--
Eric Blake

[Paolo Bonzini-2]

Eric Blake wrote:
> Paolo Bonzini <bonzini <at> gnu.org> writes:
>
>> This patch documents $as_me and $LINENO, which are the sole constructs
>> (for now) that explicitly require a *_PREPARE macro because they are
>> variables.  So those are defined without the hyphen and documented.
>>
>
> OK to apply, after addressing these nits.

Pushed.

Paolo

[Ralf Wildenhues]

Hi,

> Paolo Bonzini writes:
> >
> > This patch documents $as_me and $LINENO, which are the sole constructs
> > (for now) that explicitly require a *_PREPARE macro because they are
> > variables.  So those are defined without the hyphen and documented.

How about also adding tests for them?

Anything that is documented (and most stuff that is undocumented) but
not explicitly tested basically has to be assumed to be broken.

As a really really minor nit, I noted that commit logs use a bit
different styles.  I'm not sure whether it's worth making a fuss
of it, but I'd volunteer writing a script to convert from ChangeLog
entries to commit log entries if that helps.

In fact, I think this is a good first approximation (note embedded TAB):

git diff HEAD ChangeLog |
sed -n '/^+$/,$s/^+ //p' |
sed '1a\
'

Cheers,
Ralf

[Paolo Bonzini-2]

> How about also adding tests for them?

Okay, I will.

> In fact, I think this is a good first approximation (note embedded TAB):
>
> git diff HEAD ChangeLog |
> sed -n '/^+$/,$s/^+ //p' |
> sed '1a\
> '

Aha, I see.  I'm currently using my own script for that as a
prepare-commit-msg hook, I'll adjust it for the autoconf repository.

Paolo

[Paolo Bonzini-2]

Paolo Bonzini wrote:
>> How about also adding tests for them?
>
> Okay, I will.

This should be enough for AS_LINENO_PREPARE:

2008-10-12  Paolo Bonzini  <bonzini@...>

        * tests/m4sh.at: Use documented AS_LINENO_PREPARE.

diff --git a/tests/m4sh.at b/tests/m4sh.at
index d8542ed..854b4da 100644
--- a/tests/m4sh.at
+++ b/tests/m4sh.at
@@ -386,7 +386,7 @@

 AT_DATA_M4SH([script.as],
 [[AS_INIT
-_AS_LINENO_PREPARE
+AS_LINENO_PREPARE

 func_return () {
   (exit $1)
@@ -429,7 +429,7 @@

 AT_DATA_M4SH([script.as],
 [[AS_INIT
-_AS_LINENO_PREPARE
+AS_LINENO_PREPARE

 func_success () {
   return 0
@@ -507,7 +507,6 @@

 AT_DATA_M4SH([script.as],
 [[AS_INIT
-_AS_LINENO_PREPARE

 echo "AS_HELP_STRING([--an-option],[some text])"
 echo "AS_HELP_STRING([--another-much-longer-option],

Paolo

[Eric Blake]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

According to Paolo Bonzini on 10/10/2008 1:02 AM:
> Finally, here is AS_INIT_GENERATED.  Unfortunately it does not do
> really everything as it does not include the she-bang line, but that's
> good enough for now and it can be used already in status.m4.

I'm still not understanding your comments in other mail about why
AS_INIT_GENERATED must involve m4_require.  I think we need another round
of email discussion before this is ready to go.

>
> 2008-10-10  Paolo Bonzini  <bonzini@...>
>
> * lib/m4sugar/m4sh.m4 (AS_INIT_GENERATED): New.
> * lib/autoconf/status.m4 (_AC_OUTPUT_CONFIG_STATUS): Use it.
> * doc/autoconf.texi (Initialization macros): Document it.
>  
> +@defmac AS_INIT_GENERATED
> +@asindex{INIT}

s/INIT/INIT_GENERATED/

> +Initialize the M4sh environment.  This macro emits again all the
> +code that is generated by @code{AS_INIT}, including the expansion of
> +@code{AS_BOURNE_COMPATIBLE} and @code{AS_SHELL_SANITIZE}.  It is meant
> +to be used in a here document when generating other shell scripts,

s/a here document/a quoted here document/

> +after having output the @code{#! /bin/sh} line using @code{#! $SHELL.}

An example would be nice.  It takes two here documents, one unquoted, to
expand $SHELL, and a second quoted, so that no text produced by
AS_INIT_GENERATED is mistakenly expanded early.  But it seems like this
recommendation is incomplete.  Both autoconf's status.m4 and libtool's
libtool.m4 use the two-step sequence:
| #!$SHELL
| SHELL=\${CONFIG_SHELL-$SHELL}
needed so that if /bin/sh is inadequate, the shell attempts to re-exec
with the same shell learned during configure.

Also, there is the matter that if AS_MESSAGE_LOG_FD is currently defined,
it must either be temporarily suppressed in m4 so that any AS_MESSAGE
usage to the child script does not attempt to access a non-existent log,
or else reopened in shell immediately after AS_INIT_GENERATED.  This is
probably worth a mention in the manual.

>  
>  
> +# AS_INIT_GENERATED
> +# -----------------
> +# Emit m4sh initialization code in a suitable form for a here document.

s/a here document/a quoted here document/

> +# Does not emit the `#!' sequence, which should be generated with
> +# `#! $SHELL'.

Again, I'd be more comfortable also mentioning the SHELL= line, and the
prefix lines occur in an unquoted here-doc.

> +m4_defun([AS_INIT_GENERATED],
> +[m4_require([AS_PREPARE])dnl

Why is the m4_require needed?  Just because the child script is given all
m4sh features still doesn't explain why we have to blindly enable all m4sh
features in the parent; isn't an as-needed preparation in the parent
script still possible?

- --
Don't work too hard, make some time for fun as well!

Eric Blake             ebb9@...
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (Cygwin)
Comment: Public key at home.comcast.net/~ericblake/eblake.gpg
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iEYEARECAAYFAkjzPFsACgkQ84KuGfSFAYDmaACfbfKqsTTpvsfzvHhvEYfCxCDg
Ln8AnivUumT54fEEjVM00SMA2zwYeaGA
=MrNf
-----END PGP SIGNATURE-----

[Paolo Bonzini-2]

> Also, there is the matter that if AS_MESSAGE_LOG_FD is currently defined,
> it must either be temporarily suppressed in m4 so that any AS_MESSAGE
> usage to the child script does not attempt to access a non-existent log,
> or else reopened in shell immediately after AS_INIT_GENERATED.  This is
> probably worth a mention in the manual.

I see... maybe we should provide AS_STATE_PUSH and AS_STATE_POP macros
that do all the required macro resetting, in case in the future other
macros have to be renamed like that.

>> +# AS_INIT_GENERATED
>> +# -----------------
>> +# Emit m4sh initialization code in a suitable form for a here document.
>
> s/a here document/a quoted here document/
>
>> +# Does not emit the `#!' sequence, which should be generated with
>> +# `#! $SHELL'.
>
> Again, I'd be more comfortable also mentioning the SHELL= line, and the
> prefix lines occur in an unquoted here-doc.

I just added a reference to the manual in m4sh.m4.

>> +m4_defun([AS_INIT_GENERATED],
>> +[m4_require([AS_PREPARE])dnl
>
> Why is the m4_require needed?  Just because the child script is given all
> m4sh features still doesn't explain why we have to blindly enable all m4sh
> features in the parent; isn't an as-needed preparation in the parent
> script still possible?

No.  Say the parent requires feature Z, which adds a suggested test.
The child, instead, requires everything, including feature Y which in
turn adds a required test; so the child requires Y and suggests Z.

Now, suppose that there is a shell on the system that supports {Z} and
one that supports {Y}, but not one that includes {Y,Z}.  Since the child
does not run AS_CLEANUP, it does not have the loop to choose a better
shell; so the child must use the second of the two available shells.
But if you do not do that m4_require here, the parent will provide {Z}
instead.

This is not likely, but neither is it only hypothetical: just replace Z
with $LINENO and Y with shell functions.

I tested the attached patch with "make pdf" too and checked that there
are no overfull hboxes.

Paolo

2008-10-13  Paolo Bonzini  <bonzini@...>

        * lib/m4sugar/m4sh.m4 (AS_INIT_GENERATED): New.
        * lib/autoconf/status.m4 (_AC_OUTPUT_CONFIG_STATUS): Use it.
        * doc/autoconf.texi (Initialization macros): Document it.
 
diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index d9d82aa..67dbd8b 100644
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -11943,6 +11943,38 @@ generated from, and code to sanitize the environment for the rest of the
 script.  Finally, it changes the current diversion to @code{BODY}.
 @end defmac
 
+@defmac AS_INIT_GENERATED
+@asindex{INIT_GENERATED}
+Initialize the M4sh environment.  This macro emits again all the
+code that is generated by @code{AS_INIT}, including the expansion of
+@code{AS_BOURNE_COMPATIBLE} and @code{AS_SHELL_SANITIZE}.  It is meant
+to be used in a quoted here document when generating other shell scripts.
+
+Note that @code{AS_INIT_GENERATED} does not emit the entire prolog,
+including the @code{#! /bin/sh} line.  Currently, the suggested idiom
+for writing a M4sh shell script within another script is:
+
+@example
+m4_rename([AS_MESSAGE_LOG_FD], [save_AS_MESSAGE_LOG_FD])dnl
+cat > "@var{file}" <<__EOF__
+#! $SHELL
+# Generated by $as_me.
+# ...
+
+SHELL=\$@{CONFIG_SHELL-$SHELL@}
+__EOF__
+
+cat >>"@var{file}" <<\__EOF__
+AS_INIT_GENERATED
+# ...
+__EOF__
+m4_rename([save_AS_MESSAGE_LOG_FD], [AS_MESSAGE_LOG_FD])dnl
+@end example
+
+This, however, may change in the future until the M4sh interface is
+stabilized further.
+@end defmac
+
 @defmac AS_LINENO_PREPARE
 @asindex{LINENO_PREPARE}
 @evindex LINENO
diff --git a/lib/autoconf/status.m4 b/lib/autoconf/status.m4
index ddc5f47..6d622b9 100644
--- a/lib/autoconf/status.m4
+++ b/lib/autoconf/status.m4
@@ -1332,11 +1332,7 @@ SHELL=\${CONFIG_SHELL-$SHELL}
 _ACEOF
 
 cat >>$CONFIG_STATUS <<\_ACEOF || ac_write_fail=1
-AS_SHELL_SANITIZE
-dnl Watch out, this is directly the initializations, do not use
-dnl AS_PREPARE, otherwise you'd get it output in the initialization
-dnl of configure, not config.status.
-_AS_PREPARE
+AS_INIT_GENERATED
 exec AS_MESSAGE_FD>&1
 
 # Save the log message, to keep $[0] and so on meaningful, and to
diff --git a/lib/m4sugar/m4sh.m4 b/lib/m4sugar/m4sh.m4
index aa5669b..8d4b07c 100644
--- a/lib/m4sugar/m4sh.m4
+++ b/lib/m4sugar/m4sh.m4
@@ -1688,6 +1688,17 @@ m4_define([AS_VAR_POPDEF],
 ## ----------------- ##
 
 
+# AS_INIT_GENERATED
+# -----------------
+# Emit m4sh initialization code in a suitable form for a quoted
+# here document.  Does not emit the `#!' sequence, which should be
+# generated with `#! $SHELL'; see the manual or autoconf/status.m4
+# for more detail.
+m4_defun([AS_INIT_GENERATED],
+[m4_require([AS_PREPARE])dnl
+AS_SHELL_SANITIZE
+_AS_PREPARE])
+
 # AS_INIT
 # -------
 # Initialize m4sh.

[Eric Blake]

Paolo Bonzini <bonzini <at> gnu.org> writes:

> I see... maybe we should provide AS_STATE_PUSH and AS_STATE_POP macros
> that do all the required macro resetting, in case in the future other
> macros have to be renamed like that.

Sounds like an idea (but it can be a separate patch).

> Now, suppose that there is a shell on the system that supports {Z} and
> one that supports {Y}, but not one that includes {Y,Z}.  Since the child
> does not run AS_CLEANUP, it does not have the loop to choose a better
> shell; so the child must use the second of the two available shells.
> But if you do not do that m4_require here, the parent will provide {Z}
> instead.

Thanks for the clarification.  And this also explains why the child script must
be generated with #!$SHELL, rather than #!/bin/sh - we are reusing the
knowledge learned during the parent script on which shell provided all the
required features (both an optimization that makes the child faster, and a
technical necessity since we don't have a counterpart M4SH-SANITIZE diversion
for dumping AS_CLEANUP into the child script).

>
> This is not likely, but neither is it only hypothetical: just replace Z
> with $LINENO and Y with shell functions.

Which shells lack shell functions?  Every shell I've tried appears to have them
(this includes Solaris /bin/sh and cygwin ash, which both lack LINENO).  But
your argument is still sound - cygwin ash lacks $(()), while Solaris /bin/sh
lacks ${foo#*/}, and both of those are features I hope to start adding in
_AS_DETECT_SUGGESTED to optimize configure scripts on shells that support them.

>
> I tested the attached patch with "make pdf" too and checked that there
> are no overfull hboxes.

Always a nice check to run on doc changes.  Thanks!

> +Note that @code{AS_INIT_GENERATED} does not emit the entire prolog,
> +including the @code{#! /bin/sh} line.  Currently, the suggested idiom
> +for writing a M4sh shell script within another script is:

I would write the paragraph like this (I think it is important to warn the user
to _not_ blindly use /bin/sh in the child script):

Note that @code{AS_INIT_GENERATED} does not emit the entire prolog.  In
particular, the child script must be previously started with @code{#!$SHELL},
rather than @code{#!/bin/sh}, because this macro intentionally skips the search
for a sufficient shell that was performed in the parent script.  Currently, the
suggested idiom for writing a M4sh shell script within another script is:

> +
> +This, however, may change in the future until the M4sh interface is
> +stabilized further.

s/until/as/

OK to apply with these changes.

--
Eric Blake

[Paolo Bonzini-2]

>> This is not likely, but neither is it only hypothetical: just replace Z
>> with $LINENO and Y with shell functions.
>
> Which shells lack shell functions?

Well, there is always that infamous version of zsh that does not pass
the test. :-(

>> +Note that @code{AS_INIT_GENERATED} does not emit the entire prolog,
>> +including the @code{#! /bin/sh} line.  Currently, the suggested idiom
>> +for writing a M4sh shell script within another script is:
>
> I would write the paragraph like this (I think it is important to warn the user
> to _not_ blindly use /bin/sh in the child script):

Okay, thanks.

Paolo