Changes to m4/doc/m4.texinfo,v [branch-1_4]

[Eric Blake]

CVSROOT:        /sources/m4
Module name:    m4
Branch:         branch-1_4
Changes by:     Eric Blake <ericb>      06/09/07 22:48:15

Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.1.1.1.2.73
retrieving revision 1.1.1.1.2.74
diff -u -b -r1.1.1.1.2.73 -r1.1.1.1.2.74
--- doc/m4.texinfo      6 Sep 2006 03:58:05 -0000       1.1.1.1.2.73
+++ doc/m4.texinfo      7 Sep 2006 22:48:15 -0000       1.1.1.1.2.74
@@ -588,10 +588,12 @@
 name of @file{-} is taken to mean the standard input.  It is
 conventional, but not required, for input files to end in @samp{.m4}.
 
-The input files are read in the sequence given.  The standard input can
-only be read once, so the file name @file{-} should only appear once on
-the command line.  It is an error if an input file ends in the middle of
-argument collection, a comment, or a quoted string.
+The input files are read in the sequence given.  Standard input can be
+read more than once, so the file name @file{-} may appear multiple times
+on the command line; this makes a difference when input is from a
+terminal or other special file type.  It is an error if an input file
+ends in the middle of argument collection, a comment, or a quoted
+string.
 
 If none of the input files invoked @code{m4exit} (@pxref{M4exit}), the
 exit status of @code{m4} will be 0 for success, 1 for general failure
@@ -4109,6 +4111,32 @@
 Note how the expansion of @code{syscmd} keeps the trailing newline of
 the command, as well as using the newline that appeared after the macro.
 
+As an example of @var{shell-command} using the same standard input as
address@hidden, the command line @kbd{echo "m4wrap(\`syscmd(\`cat')')" | m4}
+will tell @code{m4} to read all of its input before executing the
+wrapped text, then hand a valid (albeit emptied) pipe as standard input
+for the @code{cat} subcommand.  Therefore, you should be careful when
+using standard input (either by specifying no files, or by passing
address@hidden as a file name on the command line, @pxref{Invoking m4}), and
+also invoking subcommands via @code{syscmd} or @code{esyscmd} that
+consume data from standard input.
+
address@hidden
address@hidden If the user types the example below with stdin being an
address@hidden interactive terminal, then cat will hang waiting for additional
address@hidden input after m4 has exited.  But the testsuite is using a pipe
address@hidden for stdin.  Hence, we have two versions - the one we feed the
address@hidden testsuite below, and the one we display to the user above that
address@hidden more accurately shows what the testsuite is really doing but
address@hidden which the testsuite cannot parse.
+
address@hidden
+m4wrap(`syscmd(`cat')')
address@hidden
+^D
address@hidden example
address@hidden ignore
+
 @node Esyscmd
 @section Reading the output of commands
 
@@ -4751,6 +4779,11 @@
 @code{m4exit} (@pxref{M4exit}) with a non-numeric argument).
 
 @item
+Some traditional implementations only allow reading standard input
+once, but @acronym{GNU} @code{m4} correctly handles multiple instances
+of @samp{-} on the command line.
+
address@hidden
 @acronym{POSIX} requires @code{m4wrap} (@pxref{M4wrap}) to act in FIFO
 (first-in, first-out) order, but @acronym{GNU} @code{m4} currently uses
 LIFO order.  Furthermore, @acronym{POSIX} states that only the first