* doc/autoconf.texi (Quadrigraphs): Document `@&t@'.

(testsuite Scripts): There is no such thing as `atconfig.in'.
And actually one diagram is missing: test suite runtime.

diff --git a/ChangeLog b/ChangeLog
index 0391a6bd65b642c52aba3f2aeb2c4d8cfc423353..3101cc6d0ac2d9eefe09f05baf4ae655571e8c4c 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2001-08-31  Akim Demaille  <akim@epita.fr>
+
+       * doc/autoconf.texi (Quadrigraphs): Document `@&t@'.
+       (testsuite Scripts): There is no such thing as `atconfig.in'.
+       And actually one diagram is missing: test suite runtime.
+
 2001-08-31  Akim Demaille  <akim@epita.fr>
 
        * lib/Autom4te/General.pm (&find_file): Browse the includes in the

diff --git a/bin/autom4te.in b/bin/autom4te.in
index 1382bdb65ae453f5c39f11fcd03089872c7154d4..c501b41d8f026a031ab17b02ce0ac101d5c1adc2 100644 (file)
--- a/bin/autom4te.in
+++ b/bin/autom4te.in
@@ -673,26 +673,7 @@ sub handle_output ($$)
            if /$forbidden/o && !/$allowed/o && ! exists $prohibited{$_};
        }
 
-      # Performed *last*: the empty quadrigraph.  Handling it last
-      # makes it possible to generate quadrigraphs, e.g. `@<@&t@:@'
-      # produces `@<:@'.  In addition, it provides a means to
-      # explicitly allow some *occurrences* of forbidden patterns.
-      #
-      # The use of `@&t@' was suggested by Paul Eggert:
-      #
-      # ``I should give some credit to the @&t@ pun.  The "&" is my
-      # own invention, but the "t" came from the source code of the
-      # ALGOL68C compiler, written by Steve Bourne (of Bourne shell
-      # fame), and which used "mt" to denote the empty string.  In C,
-      # it would have looked like something like this:
-      #
-      # char const mt[] = "";
-      #
-      # but of course the source code was written in Algol 68.
-      #
-      # I don't know where he got "mt" from: it could have been his
-      # own invention, and I suppose it could have been a common pun
-      # around the Cambridge University computer lab at the time.''
+      # Performed *last*: the empty quadrigraph.
       $res =~ s/\@&t\@//g;
 
       print $out "$res\n";

diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index f60919c62a0ed2834de329551b9457701b2a5e57..0f1336b70ed1db86b9f95f25f3e7cbbbebcea2a8 100644 (file)
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -6508,6 +6508,7 @@ it's an exception that should be avoided in Autoconf.
 @cindex @samp{@@:>@@}
 @cindex @samp{@@S|@@}
 @cindex @samp{@@%:@@}
+@cindex @samp{@@&t@@}
 
 When writing an autoconf macro you may occasionally need to generate
 special characters that are difficult to express with the standard
@@ -6528,13 +6529,53 @@ You can work around this problem by using one of the following
 @samp{$}
 @item @@%:@@
 @samp{#}
+@item @@&t@@
+Expands to nothing.
 @end table
 
 Quadrigraphs are replaced at a late stage of the translation process,
 after @command{m4} is run, so they do not get in the way of M4 quoting.
-For example, the string @samp{[^@@<:@@]}, if properly quoted, will
-appear as @samp{[^[]} in the @code{configure} script.
+For example, the string @samp{^@@<:@@}, independently of its quotation,
+will appear as @samp{^[} in the output.
 
+The empty quadrigraph can be used:
+
+@itemize @minus
+@item to mark explicitly trailing spaces
+
+Trailing spaces are smashed by @command{autom4te}.  This is a feature.
+
+@item to produce other quadrigraphs
+
+For instance @samp{@@<@@&t@@:@@} produces @samp{@@<:@@}.
+
+@item to escape @emph{occurrences} of forbidden patterns
+
+For instance you might want to mention @code{AC_FOO} is a comment, while
+still being sure that @command{autom4te} will still catch unexpanded
+@samp{AC_*}.  Then write @samp{AC@@&t@@_FOO}.
+@end itemize
+
+The name @samp{@@&t@@} was suggested by Paul Eggert:
+
+@quotation
+I should give some credit to the @samp{@@&t@@} pun.  The @samp{&} is my
+own invention, but the @samp{t} came from the source code of the
+@sc{algol68c} compiler, written by Steve Bourne (of Bourne shell fame),
+and which used @samp{mt} to denote the empty string.  In C, it would
+have looked like something like:
+
+@example
+char const mt[] = "";
+@end example
+
+@noindent
+but of course the source code was written in Algol 68.
+
+I don't know where he got @samp{mt} from: it could have been his own
+invention, and I suppose it could have been a common pun around the
+Cambridge University computer lab at the time.
+@end quotation
 
 @node Quotation Rule Of Thumb
 @subsection Quotation Rule Of Thumb
@@ -7444,7 +7485,7 @@ Robert Lipe:
 
 @quotation
 This is exactly the problem.  While most (at least most System V's) do
-have a bourne shell that accepts shell functions most vendor
+have a Bourne shell that accepts shell functions most vendor
 @command{/bin/sh} programs are not the @sc{posix} shell.
 
 So while most modern systems do have a shell _somewhere_ that meets the
@@ -11282,16 +11323,16 @@ out of validation.
 The automatic generation of debugging scripts for failed test has the
 purpose of easing the chase for bugs.
 
-@c FIXME: This is not accurate today: we have a single atconfig.in.
 It often happens in practice that individual tests in the validation
 suite need to get information coming out of the configuration process.
 Some of this information, common for all validation suites, is provided
-through the file @file{atconfig.in}, which your package should distribute
-verbatim, unchanged.  For configuration informations which your testing
-environment specifically needs, you might prepare an optionnal file named
-@file{atlocal.in}.  The configuration process produces @file{atconfig}
-and @file{atlocal} out of these two input files, and these two produced
-files are automatically read by the @file{testsuite} script.
+through the file @file{atconfig}, automatically created by
+@code{AC_CONFIG_TESTDIR}.  For configuration informations which your
+testing environment specifically needs, you might prepare an optionnal
+file named @file{atlocal.in}.  The configuration process produces
+@file{atconfig} and @file{atlocal} out of these two input files, and
+these two produced files are automatically read by the @file{testsuite}
+script.
 
 Here is a diagram showing the relationship between files.
 
@@ -11306,13 +11347,22 @@ testsuite.at --> autom4te* --> testsuite
 Files used in configuring a software package:
 
 @example
-atconfig.in                                        testsuite.log
-    |                                                   ^
-    v                    .-> atconfig --.               |
-    +--> config.status* -+              +-> testsuite* -+
-    ^                    `-> [atlocal] -'               |
-    |                                                   v
-[atlocal.in]                                       debug-@var{nn}.sh*
+                                     .-> atconfig
+                                    /
+[atlocal.in] -->  config.status* --<
+                                    \
+                                     `-> [atlocal]
+@end example
+
+@noindent
+Files created during the test suite execution:
+
+@example
+atconfig -->.                    .--> testsuite.log
+             \                  /
+              >-- testsuite* --<
+             /                  \
+[atlocal] ->'                    `--> [debug-@var{nn}.sh*]
 @end example
 
 @node Writing testsuite.at