doc merge

[Eric Blake]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

A simple patch while waiting for any review on my bigger extended argument
patch - merge more doc sections from the branch:

2007-03-01  Eric Blake  <address@hidden>

        * doc/m4.texinfo (Syscmd, Esyscmd): Merge more doc sections.

- --
Don't work too hard, make some time for fun as well!

Eric Blake             address@hidden
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.5 (Cygwin)
Comment: Public key at home.comcast.net/~ericblake/eblake.gpg
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFF5uLN84KuGfSFAYARAuyfAKDZdAd2nyMC9y2OIxyLDVkg/y5BcACfQVHc
tbaqGLuhnQfvkLtA+VhZec4=
=yzFo
-----END PGP SIGNATURE-----

Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.98
diff -u -p -r1.98 m4.texinfo
--- doc/m4.texinfo      28 Feb 2007 21:31:12 -0000      1.98
+++ doc/m4.texinfo      1 Mar 2007 14:24:52 -0000
@@ -6351,19 +6351,19 @@ mpeval(`-1 >>> 1')
 @node Shell commands
 @chapter Macros for running shell commands
 
address@hidden UNIX commands, running
 @cindex executing shell commands
 @cindex running shell commands
 @cindex shell commands, running
address@hidden UNIX commands, running
 @cindex commands, running shell
 There are a few builtin macros in @code{m4} that allow you to run shell
 commands from within @code{m4}.
 
 Note that the definition of a valid shell command is system dependent.
-On UNIX systems, this is the typical @code{/bin/sh}.  But on other
+On UNIX systems, this is the typical @command{/bin/sh}.  But on other
 systems, such as native Windows, the shell has a different syntax of
 commands that it understands.  Some examples in this chapter assume
address@hidden/bin/sh}, and also demonstrate how to quit early with a known
address@hidden/bin/sh}, and also demonstrate how to quit early with a known
 exit value if this is not the case.
 
 @menu
@@ -6377,6 +6377,8 @@ exit value if this is not the case.
 
 @node Platform macros
 @section Determining the platform
+
address@hidden platform macros
 Sometimes it is desirable for an input file to know which platform
 @code{m4} is running on.  @acronym{GNU} @code{m4} provides several
 macros that are predefined to expand to the empty string; checking for
@@ -6425,16 +6427,17 @@ provided
 @node Syscmd
 @section Executing simple commands
 
+Any shell command can be executed, using @code{syscmd}:
+
 @deffn {Builtin (m4)} syscmd (@var{shell-command})
-Any shell command can be executed, using @code{syscmd}, which executes
address@hidden as a shell command.
+Executes @var{shell-command} as a shell command.
 
 The expansion of @code{syscmd} is void, @emph{not} the output from
 @var{shell-command}!  Output or error messages from @var{shell-command}
 are not read by @code{m4}.  @xref{Esyscmd}, if you need to process the
 command output.
 
-Prior to executing the command, @code{m4} flushes its output buffers.
+Prior to executing the command, @code{m4} flushes its buffers.
 The default standard input, output and error of @var{shell-command} are
 the same as those of @code{m4}.
 
@@ -6442,7 +6445,7 @@ When the @option{--safer} option (@pxref
 m4}) is in effect, @code{syscmd} results in an error, since otherwise an
 input file could execute arbitrary code.
 
-The builtin macro @code{syscmd} is recognized only when given arguments.
+The macro @code{syscmd} is recognized only with parameters.
 @end deffn
 
 @example
@@ -6456,6 +6459,33 @@ syscmd(`echo foo')
 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.
 
+The following is an example of @var{shell-command} using the same
+standard input as @code{m4}:
+
address@hidden The testsuite does not know how to parse pipes from the
address@hidden texinfo.  Fortunately, there are other tests in the testsuite
address@hidden that test this same feature.
address@hidden ignore
address@hidden
+$ @kbd{echo "m4wrap(\`syscmd(\`cat')')" | m4}
address@hidden
address@hidden example
+
+It tells @code{m4} to read all of its input before executing the wrapped
+text, then hands a valid (albeit emptied) pipe as standard input for the
address@hidden subcommand.  Therefore, you should be careful when using
+standard input (either by specifying no files, or by passing @samp{-} as
+a file name on the command line, @pxref{Command line files, , Invoking
+m4}), and also invoking subcommands via @code{syscmd} or @code{esyscmd}
+that consume data from standard input.  When standard input is a
+seekable file, the subprocess will pick up with the next character not
+yet processed by @code{m4}; when it is a pipe or other non-seekable
+file, there is no guarantee how much data will already be buffered by
address@hidden and thus unavailable to the child.
+
+Following is an example of how potentially unsafe actions can be
+suppressed.
+
 @comment options: --safer
 @comment status: 1
 @example
@@ -6469,17 +6499,26 @@ syscmd(`echo hi')
 @section Reading the output of commands
 
 @cindex @acronym{GNU} extensions
address@hidden {Builtin (gnu)} esyscmd (@var{shell-command})
 If you want @code{m4} to read the output of a shell command, use
address@hidden, which expands to the standard output of the shell
-command @var{shell-command}.
address@hidden:
 
-Prior to executing the command, @code{m4} flushes its output buffers.
address@hidden {Builtin (gnu)} esyscmd (@var{shell-command})
+Expands to the standard output of the shell command
address@hidden
+
+Prior to executing the command, @code{m4} flushes its buffers.
 The default standard input and standard error of @var{shell-command} are
 the same as those of @code{m4}.  The error output of @var{shell-command}
 is not a part of the expansion: it will appear along with the error
 output of @code{m4}.
 
+When the @option{--safer} option (@pxref{Operation modes, , Invoking
+m4}) is in effect, @code{esyscmd} results in an error, since otherwise
+an input file could execute arbitrary code.
+
+The macro @code{esyscmd} is recognized only with parameters.
address@hidden deffn
+
 @example
 define(`foo', `FOO')
 @result{}
@@ -6491,13 +6530,9 @@ esyscmd(`echo foo')
 Note how the expansion of @code{esyscmd} keeps the trailing newline of
 the command, as well as using the newline that appeared after the macro.
 
-When the @option{--safer} option (@pxref{Operation modes, , Invoking
-m4}) is in effect, @code{esyscmd} results in an error, since otherwise
-an input file could execute arbitrary code.
-
-The builtin macro @code{esyscmd} is recognized only when given
-arguments.
address@hidden deffn
+Just as with @code{syscmd}, care must be exercised when sharing standard
+input between @code{m4} and the child process of @code{esyscmd}.
+Likewise, potentially unsafe actions can be suppressed.
 
 @comment options: --safer
 @comment status: 1