[exim-cvs] Enhance documentation of ${run command parsing.

Commit:     c13d09b8d3277897243fd25df73718da35cd4e1c
Parent:     581d7beee57968255234fa6b25b62042152cb826
Author:     Todd Lyons <tlyons@???>
AuthorDate: Thu Jul 3 08:32:48 2014 -0700
Committer:  Todd Lyons <tlyons@???>
CommitDate: Thu Jul 3 08:32:48 2014 -0700

    Enhance documentation of ${run command parsing.
---
 doc/doc-docbook/spec.xfpt |   19 ++++++++++++++++---
 doc/doc-txt/ChangeLog     |    4 ++++
 2 files changed, 20 insertions(+), 3 deletions(-)

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index a1422b0..795d3a1 100644
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -9597,11 +9597,24 @@ expansion item above.
         {*&<&'string2'&>&*}}*&"
 .cindex "expansion" "running a command"
 .cindex "&%run%& expansion item"
-The command and its arguments are first expanded separately, and then the
-command is run in a separate process, but under the same uid and gid. As in
-other command executions from Exim, a shell is not used by default. If you want
+.new
+The command and its arguments are first expanded as one string. The string is
+split apart into individual arguments by spaces, and then the command is run
+in a separate process, but under the same uid and gid.  As in other command
+executions from Exim, a shell is not used by default. If the command requires
 a shell, you must explicitly code it.

+Since the arguments are split by spaces, when there is a variable expansion
+which has an empty result, it will cause the situation that the argument will
+simply be omitted when the program is actually executed by Exim. If the
+script/program requires a specific number of arguments and the expanded
+variable could possibly result in this empty expansion, the variable must be
+quoted. This is more difficult if the expanded variable itself could result
+in a string containing quotes, because it would with the quotes around the
+command arguments. A possible guard against this is to wrap the variable in
+the &%sg%& operator to change any quote marks to some other character.
+.wen
+
 The standard input for the command exists, but is empty. The standard output
 and standard error are set to the same file descriptor.
 .cindex "return code" "from &%run%& expansion"
diff --git a/doc/doc-txt/ChangeLog b/doc/doc-txt/ChangeLog
index 40a2443..83a0663 100644
--- a/doc/doc-txt/ChangeLog
+++ b/doc/doc-txt/ChangeLog
@@ -138,6 +138,10 @@ TF/03 Fix udpsend. The ip_connectedsocket() function's socket type
 TL/13 Bug 1495: Exiqgrep check if -C config file specified on cli exists
       and is readable.  Patch from Andrew Colin Kissa.

+TL/14 Enhance documentation of ${run expansion and how it parses the
+      commandline after expansion, particularly in the case when an
+      unquoted variable expansion results in an empty value.
+