Re: __m4_version__ and frozen files

[Eric Blake]

Ralf Wildenhues <Ralf.Wildenhues <at> gmx.de> writes:

> 
> Is it intentional that you add the --undefine after every frozen file?

Yes, since earlier processing (see parse_args) guarantees that all files prior 
to the last .m4f file are ignored (frozen files are the cumulative state of all 
earlier files).  files_to_options should only ever see zero or one .m4f, and if 
it sees one, it should be the first.

> I suppose m4 evaluates arguments in the order given?  Perusing m4.info,
> it seems that -U is evaluated after any reloading has taken place, so
> you can limit yourself to undefining __m4_version__ once.  Instead of
> appending to $arg, you could also just push another argument to @res
> right away, too, which maybe looks a bit cleaner.
> 
> Fine with me otherwise.

I updated the comments to mention the above pre-conditions, then pushed.

I also noticed some option documentation inconsistencies, so I'm pushing this:

>From f4df9b9b40517e5c23845a61837d6d0fcbe49081 Mon Sep 17 00:00:00 2001
From: Eric Blake <address@hidden>
Date: Tue, 26 Aug 2008 09:28:15 -0600
Subject: [PATCH] Update invocation documentation.

* doc/autoconf.texi (autoscan Invocation): Mention --debug.
(autoreconf Invocation): Mention -v.
(autom4te Invocation): Tie --freeze to -F, not -f.
(autoupdate Invocation): Mention --prepend-include.
* doc/install.texi (configure Invocation): Mention --help=short,
--help=recursive, -n/--no-create, --prefix.  Avoid TABs.
* bin/autoscan.in ($help): Omit space before `...'.
* bin/ifnames.in ($help): Likewise.
* bin/autoconf.as (Usage): Likewise.
* bin/autoreconf.in ($help): Likewise.
* bin/autoheader.in ($help): Likewise.
* bin/autom4te.in ($help): Likewise.
* bin/autoupdate.in ($help): Likewise.
* lib/autoconf/status.m4 (_AC_OUTPUT_CONFIG_STATUS): Use
`[OPTION]...', rather than `[OPTIONS]'.  Mention --silent.  Indent
--file correctly.

Signed-off-by: Eric Blake <address@hidden>
---
 ChangeLog              |   18 ++++++++++++++++++
 bin/autoconf.as        |    6 +++---
 bin/autoheader.in      |    2 +-
 bin/autom4te.in        |    2 +-
 bin/autoreconf.in      |    2 +-
 bin/autoscan.in        |    2 +-
 bin/autoupdate.in      |    4 ++--
 bin/ifnames.in         |    2 +-
 doc/autoconf.texi      |   12 +++++++++++-
 doc/install.texi       |   25 ++++++++++++++++++++++++-
 lib/autoconf/status.m4 |    9 +++++----
 11 files changed, 68 insertions(+), 16 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index e39b202..da4e2a2 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,23 @@
 2008-08-26  Eric Blake  <address@hidden>
 
+       Update invocation documentation.
+       * doc/autoconf.texi (autoscan Invocation): Mention --debug.
+       (autoreconf Invocation): Mention -v.
+       (autom4te Invocation): Tie --freeze to -F, not -f.
+       (autoupdate Invocation): Mention --prepend-include.
+       * doc/install.texi (configure Invocation): Mention --help=short,
+       --help=recursive, -n/--no-create, --prefix.  Avoid TABs.
+       * bin/autoscan.in ($help): Omit space before `...'.
+       * bin/ifnames.in ($help): Likewise.
+       * bin/autoconf.as (Usage): Likewise.
+       * bin/autoreconf.in ($help): Likewise.
+       * bin/autoheader.in ($help): Likewise.
+       * bin/autom4te.in ($help): Likewise.
+       * bin/autoupdate.in ($help): Likewise.
+       * lib/autoconf/status.m4 (_AC_OUTPUT_CONFIG_STATUS): Use
+       `[OPTION]...', rather than `[OPTIONS]'.  Mention --silent.  Indent
+       --file correctly.
+
        Don't let frozen __m4_version__ break downgrade to m4 1.4.x.
        * bin/autom4te.in: Adjust comments, now that we rely on 1.4.5+.
        (files_to_options): Avoid inheriting __m4_version__ from frozen
diff --git a/bin/autoconf.as b/bin/autoconf.as
index 5540002..3a25322 100644
--- a/bin/autoconf.as
+++ b/bin/autoconf.as
@@ -24,7 +24,7 @@ m4_divert_push([HEADER-COPYRIGHT])dnl
 m4_divert_pop([HEADER-COPYRIGHT])dnl back to BODY
 
 usage=["\
-Usage: $0 [OPTION] ... [TEMPLATE-FILE]
+Usage: $0 [OPTION]... [TEMPLATE-FILE]
 
 Generate a configuration script from a TEMPLATE-FILE if given, or
 \`configure.ac' if present, or else \`configure.in'.  Output is sent
diff --git a/bin/autoheader.in b/bin/autoheader.in
index 0df6fbb..ab5bfce 100644
--- a/bin/autoheader.in
+++ b/bin/autoheader.in
@@ -61,7 +61,7 @@ my @include;
 
 # $HELP
 # -----
-$help = "Usage: $0 [OPTION] ... [TEMPLATE-FILE]
+$help = "Usage: $0 [OPTION]... [TEMPLATE-FILE]
 
 Create a template file of C \`\#define\' statements for \`configure\' to
 use.  To this end, scan TEMPLATE-FILE, or \`configure.ac\' if present,
diff --git a/bin/autom4te.in b/bin/autom4te.in
index 055abce..50c410c 100644
--- a/bin/autom4te.in
+++ b/bin/autom4te.in
@@ -135,7 +135,7 @@ my %m4_builtin_alternate_name;
 
 # $HELP
 # -----
-$help = "Usage: $0 [OPTION] ... [FILES]
+$help = "Usage: $0 [OPTION]... [FILES]
 
 Run GNU M4 on the FILES, avoiding useless runs.  Output the traces if tracing,
 the frozen file if freezing, otherwise the expansion of the FILES.
diff --git a/bin/autoreconf.in b/bin/autoreconf.in
index 8b067fe..923f8ca 100644
--- a/bin/autoreconf.in
+++ b/bin/autoreconf.in
@@ -55,7 +55,7 @@ use strict;
 
 # $HELP
 # -----
-$help = "Usage: $0 [OPTION] ... [DIRECTORY] ...
+$help = "Usage: $0 [OPTION]... [DIRECTORY]...
 
 Run `autoconf' (and `autoheader', `aclocal', `automake', `autopoint'
 (formerly `gettextize'), and `libtoolize' where appropriate)
diff --git a/bin/autoscan.in b/bin/autoscan.in
index 83fa6fc..18d9ac1 100644
--- a/bin/autoscan.in
+++ b/bin/autoscan.in
@@ -101,7 +101,7 @@ my @include = ('@datadir@');
 
 # $help
 # -----
-$help = "Usage: $0 [OPTION] ... [SRCDIR]
+$help = "Usage: $0 [OPTION]... [SRCDIR]
 
 Examine source files in the directory tree rooted at SRCDIR, or the
 current directory if none is given.  Search the source files for
diff --git a/bin/autoupdate.in b/bin/autoupdate.in
index 644de19..d23048a 100644
--- a/bin/autoupdate.in
+++ b/bin/autoupdate.in
@@ -61,9 +61,9 @@ my $m4 = $ENV{"M4"} || '@M4@';
 
 # $HELP
 # -----
-$help = "Usage: $0 [OPTION] ...  [TEMPLATE-FILE...]
+$help = "Usage: $0 [OPTION]... [TEMPLATE-FILE]...
 
-Update the TEMPLATE-FILE... if given, or `configure.ac' if present,
+Update each TEMPLATE-FILE if given, or `configure.ac' if present,
 or else `configure.in', to the syntax of the current version of
 Autoconf.  The original files are backed up.
 
diff --git a/bin/ifnames.in b/bin/ifnames.in
index 6edc785..5ee70d7 100644
--- a/bin/ifnames.in
+++ b/bin/ifnames.in
@@ -49,7 +49,7 @@ use Autom4te::FileUtils;
 
 # $HELP
 # -----
-$help = "Usage: $0 [OPTION] ...  [FILE] ...
+$help = "Usage: $0 [OPTION]... [FILE]...
 
 Scan all of the C source FILES (or the standard input, if none are
 given) and write to the standard output a sorted list of all the
diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index 75c110e..b996356 100644
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -1335,6 +1335,10 @@ autoscan Invocation
 Print the names of the files it examines and the potentially interesting
 symbols it finds in them.  This output can be voluminous.
 
address@hidden --debug
address@hidden -d
+Don't remove temporary files.
+
 @item address@hidden
 @itemx -I @var{dir}
 Append @var{dir} to the include path.  Multiple invocations accumulate.
@@ -1611,6 +1615,7 @@ autoreconf Invocation
 Print the version number of Autoconf and exit.
 
 @item --verbose
address@hidden -V
 Print the name of each directory @command{autoreconf} examines and the
 commands it runs.  If given two or more times, pass @option{--verbose}
 to subordinate tools that support it.
@@ -9984,7 +9989,7 @@ autom4te Invocation
 @end example
 
 @item --freeze
address@hidden -f
address@hidden -F
 Produce a frozen state file.  @command{autom4te} freezing is stricter
 than M4's: it must produce no warnings, and no output other than empty
 lines (a line with white space is @emph{not} empty) and comments
@@ -18885,6 +18890,11 @@ autoupdate Invocation
 @itemx -I @var{dir}
 Also look for input files in @var{dir}.  Multiple invocations accumulate.
 Directories are browsed from last to first.
+
address@hidden address@hidden
address@hidden -B @var{dir}
+Prepend directory @var{dir} to the search path.  This is used to include
+the language-specific files before any third-party macros.
 @end table
 
 @node Obsolete Macros
diff --git a/doc/install.texi b/doc/install.texi
index 070291c..f6620ec 100644
--- a/doc/install.texi
+++ b/doc/install.texi
@@ -294,7 +294,14 @@ configure Invocation
 @table @option
 @item --help
 @itemx -h
-Print a summary of the options to @command{configure}, and exit.
+Print a summary of all of the options to @command{configure}, and exit.
+
address@hidden --help=short
address@hidden --help=recursive
+Print a summary of the options unique to this package's
address@hidden, and exit.  The @code{short} variant lists options
+used only in the top level, while the @code{recursive} variant lists
+options also present in any nested packages.
 
 @item --version
 @itemx -V
@@ -321,8 +328,24 @@ configure Invocation
 @item address@hidden
 Look for the package's source code in directory @var{dir}.  Usually
 @command{configure} can determine that directory automatically.
+
address@hidden address@hidden
+Use @var{dir} as the installation prefix.  @ref{Installation Names}
+for more details, including other options available for fine-tuning
+the installation locations.
+
address@hidden --no-create
address@hidden -n
+Run the configure checks, but stop before creating any output files.
 @end table
 
 @noindent
 @command{configure} also accepts some other, not widely useful, options.
 Run @samp{configure --help} for more details.
+
address@hidden Local Variables:
address@hidden fill-column: 72
address@hidden ispell-local-dictionary: "american"
address@hidden indent-tabs-mode: nil
address@hidden whitespace-check-buffer-indent: nil
address@hidden End:
diff --git a/lib/autoconf/status.m4 b/lib/autoconf/status.m4
index d9729a3..ddc5f47 100644
--- a/lib/autoconf/status.m4
+++ b/lib/autoconf/status.m4
@@ -1392,19 +1392,20 @@ ac_cs_usage="\
 \`$as_me' instantiates files from templates according to the
 current configuration.
 
-Usage: $[0] [[OPTIONS]] [[FILE]]...
+Usage: $[0] [[OPTION]]... [[FILE]]...
 
   -h, --help       print this help, then exit
   -V, --version    print version number and configuration settings, then exit
-  -q, --quiet      do not print progress messages
+  -q, --quiet, --silent
+[]                   do not print progress messages
   -d, --debug      don't remove temporary files
       --recheck    update $as_me by reconfiguring in the same conditions
 m4_ifdef([_AC_SEEN_CONFIG(FILES)],
-  [AS_HELP_STRING([[--file=FILE[:TEMPLATE]]],
+  [AS_HELP_STRING([[    --file=FILE[:TEMPLATE]]],
     [instantiate the configuration file FILE], [                   ])
 ])dnl
 m4_ifdef([_AC_SEEN_CONFIG(HEADERS)],
-  [AS_HELP_STRING([[--header=FILE[:TEMPLATE]]],
+  [AS_HELP_STRING([[    --header=FILE[:TEMPLATE]]],
     [instantiate the configuration header FILE], [                   ])
 ])dnl
 
-- 
1.6.0