exec.n documentation: add chapter about MS-Windows quoting.

1 files changed, 39 insertions, 0 deletions

diff --git a/doc/exec.n b/doc/exec.n
index 9421eb1..6d94c06 100644
--- a/doc/exec.n
+++ b/doc/exec.n
@@ -234,6 +234,45 @@ processor (\fBcmd.exe /c\fR), because this causes truncation of command-line
 (also the argument chain) on the first newline character.
 But it works properly with an executable (using CommandLineToArgv, etc).
 .PP
+\fBArgument quoting\fR
+.RS
+The arguments of the \fBexec\fR command are mapped to the arguments of the called
+program. Additional quote characters (\fB"\fR) are automatically  added around
+arguments if expected. Special characters are escaped by inserting backslash
+characters.
+.PP
+The MS-Windows environment does execute programs mentioned in the arguments and
+called batch files (conspec) replace environment variables, which may have side
+effects (vulnerabilities) or break any already existing quoting (for example,
+if the environment variable contains a special character like a \fB"\fR).
+Examples are:
+.CS
+% exec my-echo.cmd {test&whoami}
+  test
+  mylogin
+% exec my-echo.cmd "ENV X:%X%"
+  ENV X: CONTENT OF X
+.CE
+The following formatting is automatically performed on any
+argument item:
+.IP \(bu 3
+Avoid subprogram execution:
+Any special character argument containing a special character (\fB&\fR, \fB|\fR,
+\fB^\fR, \fB<\fR, \fB>\fR, \fB!\fR, \fB(\fR, \fB)\fR, \fB(\fR, \fB%\fR)
+is automatically enclosed in quotes (\fB"\fR). Any data quote is escaped by
+insertion of backslash characters.
+.IP \(bu 3
+Avoid environment variable replacement:
+Any appearence of environment variable reference (\fB%\fR) is individually quoted
+by \fB"\fR.
+.PP
+TCL 8.6.10 refined this quoting by adding quoting for data quotes and individual
+quoting of "\fB%\fR".
+This may break present scripts which rely on the replacement functionality of
+environment variables.
+A solution with command parameters is envisaged for a future release of TCL.
+.RE
+.PP
 The Tk console text widget does not provide real standard IO capabilities.
 Under Tk, when redirecting from standard input, all applications will see an
 immediate end-of-file; information redirected to standard output or standard