Improve documentation for exec and open, especially in relation to binary pipelines

2 files changed, 38 insertions, 1 deletions

diff --git a/doc/exec.n b/doc/exec.n
index 373b980..3cfc29d 100644
--- a/doc/exec.n
+++ b/doc/exec.n
@@ -22,6 +22,10 @@ of one or more subprocesses to execute.
 The arguments take the form of a standard shell pipeline
 where each \fIarg\fR becomes one word of a command, and
 each distinct command becomes a subprocess.
+The result of the command is the standard output of the final subprocess in
+the pipeline, interpreted using the system \fBencoding\fR; to use any other
+encoding (especially including binary data), the pipeline must be
+\fBopen\fRed, configured and read explicitly.
 .PP
 If the initial arguments to \fBexec\fR start with \fB\-\fR then
 they are treated as command-line switches and are not part
@@ -411,7 +415,9 @@ With the file \fIcmp.bat\fR looking something like:
 .CS
 @gcc %*
 .CE
+.PP
 or like another variant using single parameters:
+.PP
 .CS
 @gcc %1 %2 %3 %4 %5 %6 %7 %8 %9
 .CE
diff --git a/doc/open.n b/doc/open.n
index b0d9781..c7c8cf6 100644
--- a/doc/open.n
+++ b/doc/open.n
@@ -72,7 +72,7 @@ indicate that the opened channel should be configured as if with the
 reading or writing of binary data.
 .PP
 In the second form, \fIaccess\fR consists of a list of any of the
-following flags, all of which have the standard POSIX meanings.
+following flags, most of which have the standard POSIX meanings.
 One of the flags must be either \fBRDONLY\fR, \fBWRONLY\fR or \fBRDWR\fR.
 .TP 15
 \fBRDONLY\fR
@@ -453,6 +453,12 @@ application are competing for the console at the same time.  If the command
 pipeline is started from a script, so that Tcl is not accessing the console,
 or if the command pipeline does not use standard input or output, but is
 redirected from or to a file, then the above problems do not occur.
+.PP
+Files opened in the
+.QW \fBa\fR
+mode or with the \fBAPPEND\fR flag set are implemented by seeking immediately
+before each write, which is not an atomic operation and does not carry the
+guarantee of strict appending that is present on POSIX platforms.
 .RE
 .TP
 \fBUnix\fR\0\0\0\0\0\0\0
@@ -527,6 +533,19 @@ Note that the equivalent options exist on Unix, but are on the serial channel
 type.
 .VE "8.7, TIP 160"
 .SH "EXAMPLES"
+Open a file for writing, forcing it to be created and raising an error if it
+already exists.
+.PP
+.CS
+set myNewFile [\fBopen\fR filename.txt {WRONLY CREAT EXCL}]
+.CE
+.PP
+Open a file for writing as a log file.
+.PP
+.CS
+set myLogFile [\fBopen\fR filename.log "a"]
+fconfigure $myLogFile -buffering line
+.CE
 .PP
 Open a command pipeline and catch any errors:
 .PP
@@ -538,6 +557,18 @@ if {[catch {close $fl} err]} {
 }
 .CE
 .PP
+Open a command pipeline and read binary data from it. Note the unusual form
+with
+.QW |[list
+that handles non-trivial edge cases with arguments that potentially have
+spaces in.
+.PP
+.CS
+set fl [\fBopen\fR |[list create_image_data $input] "rb"]
+set binData [read $fl]
+close $fl
+.CE
+.PP
 .VS "8.7, TIP 160"
 Read a password securely from the user (assuming that the script is being run
 interactively):