75-fyi-doc-empty.patch

[Akim Demaille]

Index: ChangeLog
from  Akim Demaille  <address@hidden>

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

Index: bin/autom4te.in
--- bin/autom4te.in Fri, 31 Aug 2001 13:05:00 +0200 akim
+++ bin/autom4te.in Fri, 31 Aug 2001 13:52:29 +0200 akim
@@ -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";
Index: doc/autoconf.texi
--- doc/autoconf.texi Fri, 31 Aug 2001 13:30:13 +0200 akim
+++ doc/autoconf.texi Fri, 31 Aug 2001 14:06:48 +0200 akim
@@ -6508,6 +6508,7 @@ @node Quadrigraphs
 @cindex @samp{@@:>@@}
 @cindex @samp{@@S|@@}
 @cindex @samp{@@%:@@}
address@hidden @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 @@ @node Quadrigraphs
 @samp{$}
 @item @@%:@@
 @samp{#}
address@hidden @@&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:
+
address@hidden @minus
address@hidden to mark explicitly trailing spaces
+
+Trailing spaces are smashed by @command{autom4te}.  This is a feature.
+
address@hidden to produce other quadrigraphs
+
+For instance @samp{@@<@@&t@@:@@} produces @samp{@@<:@@}.
+
address@hidden 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
address@hidden  Then write @samp{AC@@&t@@_FOO}.
address@hidden itemize
+
+The name @samp{@@&t@@} was suggested by Paul Eggert:
+
address@hidden
+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
address@hidden 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:
+
address@hidden
+char const mt[] = "";
address@hidden example
+
address@hidden
+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.
address@hidden quotation

 @node Quotation Rule Of Thumb
 @subsection Quotation Rule Of Thumb
@@ -7444,7 +7485,7 @@ reading:

 @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 @@ @node testsuite Scripts
 The automatic generation of debugging scripts for failed test has the
 purpose of easing the chase for bugs.

address@hidden 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
address@hidden  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
address@hidden  For configuration informations which your
+testing environment specifically needs, you might prepare an optionnal
+file named @file{atlocal.in}.  The configuration process produces
address@hidden 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 @@ @node testsuite Scripts
 Files used in configuring a software package:

 @example
-atconfig.in                                        testsuite.log
-    |                                                   ^
-    v                    .-> atconfig --.               |
-    +--> config.status* -+              +-> testsuite* -+
-    ^                    `-> [atlocal] -'               |
-    |                                                   v
-[atlocal.in]                                       address@hidden
+                                     .-> atconfig
+                                    /
+[atlocal.in] -->  config.status* --<
+                                    \
+                                     `-> [atlocal]
address@hidden example
+
address@hidden
+Files created during the test suite execution:
+
address@hidden
+atconfig -->.                    .--> testsuite.log
+             \                  /
+              >-- testsuite* --<
+             /                  \
+[atlocal] ->'                    `--> address@hidden
 @end example

 @node Writing testsuite.at