Clean & integrate force_command.

[exim.git] / doc / doc-docbook / spec.xfpt

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index c3994a79cb194f6dbaaac270875440f4dc1e646c..4a9b3b9550fc0d8dce1f6537140463996bb0ed0e 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -21712,11 +21712,14 @@ inserted in the argument list at that point &'as a separate argument'&. This
 avoids any problems with spaces or shell metacharacters, and is of use when a
 &(pipe)& transport is handling groups of addresses in a batch.
 
-If &(force_command)& is enabled on the transport, Special handling takes place
+If &%force_command%& is enabled on the transport, Special handling takes place
 for an argument that consists of precisely the text &`$address_pipe`&.  It
-is handled much like &`$pipe_addresses`& above.  It is expanded and each
+is handled similarly to &$pipe_addresses$& above.  It is expanded and each
 argument is inserted in the argument list at that point
-&'as a separate argument'&.
+&'as a separate argument'&.  The &`$address_pipe`& item does not need to be
+the only item in the argument; in fact, if it were then &%force_command%&
+should behave as a no-op.  Rather, it should be used to adjust the command
+run while preserving the argument vector separation.
 
 After splitting up into arguments and expansion, the resulting command is run
 in a subprocess directly from the transport, &'not'& under a shell. The
@@ -21883,6 +21886,10 @@ command = /usr/bin/remote_exec myhost -- $address_pipe
 force_command
 .endd
 
+Note that &$address_pipe$& is handled specially in &%command%& when
+&%force_command%& is set, expanding out to the original argument vector as
+separate items, similarly to a Unix shell &`"$@"`& construct.
+
 .option ignore_status pipe boolean false
 If this option is true, the status returned by the subprocess that is set up to
 run the command is ignored, and Exim behaves as if zero had been returned.