Re: Change FILE to TAG in help text displayed by config.status

[Ralf Wildenhues]

Hi John, Eric,

thanks for the bug report.

* John Calcote wrote on Sat, Apr 18, 2009 at 01:31:18AM CEST:
> When you enter './config.status --help' at the command line, you get:
>
>    $ ./config.status --help
>    `config.status' instantiates files from templates according to the
>    current configuration.
>
>    Usage: ./config.status [OPTION]... [FILE]...
>    ...
>
> The 'Usage' line above should read:
>
>    Usage: ./config.status [OPTION]... [TAG]...
>
> in order to be consistent with the documentation in the manual. The use  
> of file in this location can also be somewhat confusing relative to  
> other uses of the term FILE in this same help text. For example, in the  
> --file and --header options:
>
>    ...
>          --file=FILE[:TEMPLATE]
>                       instantiate the configuration file FILE
>          --header=FILE[:TEMPLATE]
>                       instantiate the configuration header FILE
>    ...
>
> A user might confuse the use of FILE in the Usage line with the use of  
> FILE in these options.

Well, it's not a big problem if those two are confused with each other,
as in the normal use case (where FILE has been listed in some
AC_CONFIG_FILES macro), you can use FILE and --file=FILE synonymously.

Still, you do have a point in that the documentation could be a bit more
consistent.  Here's my try at it.  What do you think about this?

Cheers,
Ralf

2009-04-18  Ralf Wildenhues  <address@hidden>

        Improve and clarify `config.status' usage documentation.
        * doc/autoconf.texi (config.status Invocation): Fix markup in
        synopsis.  Use `tag' instead of `file' notation for the
        non-option arguments, to be consistent with the documentation
        of the AC_CONFIG_* macros.
        * lib/autoconf/status.m4 (_AC_OUTPUT_CONFIG_STATUS): Likewise,
        use `tag' notation for non-option arguments.
        Report by John Calcote.

diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index 38b0972..81e0619 100644
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -20047,12 +20047,14 @@ config.status Invocation
 
 Synopsis:
 @example
-./config.status @address@hidden address@hidden@dots{}]
+./config.status @address@hidden @address@hidden
 @end example
 
-It configures the @var{files}; if none are specified, all the templates
-are instantiated.  The files must be specified without their
-dependencies, as in
+It configures the @var{tag}s; if none are specified, all the templates
+are instantiated.  A @var{tag} specifies a file, or tag associated with
+some other configuration action by a @code{AC_CONFIG_FOOS} macro
+(@pxref{Configuration Actions}).  The files must be specified without
+their dependencies, as in
 
 @example
 ./config.status foobar
diff --git a/lib/autoconf/status.m4 b/lib/autoconf/status.m4
index 72e6893..a8ab3e2 100644
--- a/lib/autoconf/status.m4
+++ b/lib/autoconf/status.m4
@@ -1395,10 +1395,11 @@ _ACEOF
 
 cat >>$CONFIG_STATUS <<\_ACEOF || ac_write_fail=1
 ac_cs_usage="\
-\`$as_me' instantiates files from templates according to the
-current configuration.
+\`$as_me' instantiates files and other configuration actions
+from templates according to the current configuration.  Unless the files
+and actions are specified as TAGs, all are instantiated by default.
 
-Usage: $[0] [[OPTION]]... [[FILE]]...
+Usage: $[0] [[OPTION]]... [[TAG]]...
 
   -h, --help       print this help, then exit
   -V, --version    print version number and configuration settings, then exit