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

2 files changed, 62 insertions, 3 deletions

diff --git a/doc/exec.n b/doc/exec.n
index e40b596..89c6413 100644
--- a/doc/exec.n
+++ b/doc/exec.n
@@ -23,6 +23,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
@@ -369,6 +373,7 @@ The \fBexec\fR command is fully functional and works as described.
 Here are some examples of the use of the \fBexec\fR command on Unix.
 .PP
 To execute a simple program and get its result:
+.PP
 .CS
 \fBexec\fR uname -a
 .CE
@@ -376,6 +381,7 @@ To execute a simple program and get its result:
 To execute a program that can return a non-zero result, you should
 wrap the call to \fBexec\fR in \fBcatch\fR and check the contents
 of the \fB\-errorcode\fR return option if you have an error:
+.PP
 .CS
 set status 0
 if {[catch {\fBexec\fR grep foo bar.txt} results options]} {
@@ -391,10 +397,13 @@ if {[catch {\fBexec\fR grep foo bar.txt} results options]} {
 When translating a command from a Unix shell invocation, care should
 be taken over the fact that single quote characters have no special
 significance to Tcl.  Thus:
+.PP
 .CS
 awk '{sum += $1} END {print sum}' numbers.list
 .CE
+.PP
 would be translated into something like:
+.PP
 .CS
 \fBexec\fR awk {{sum += $1} END {print sum}} numbers.list
 .CE
@@ -403,6 +412,7 @@ If you are converting invocations involving shell globbing, you should
 remember that Tcl does not handle globbing or expand things into
 multiple arguments by default.  Instead you should write things like
 this:
+.PP
 .CS
 \fBexec\fR ls -l {*}[glob *.tcl]
 .CE
@@ -411,26 +421,41 @@ Here are some examples of the use of the \fBexec\fR command on Windows.
 .PP
 To start an instance of \fInotepad\fR editing a file without waiting
 for the user to finish editing the file:
+.PP
 .CS
 \fBexec\fR notepad myfile.txt &
 .CE
 .PP
 To print a text file using \fInotepad\fR:
+.PP
 .CS
 \fBexec\fR notepad /p myfile.txt
 .CE
 .PP
+To print a text file in a directory other than the current one using
+\fInotepad\fR, you need to use \fBfile nativename\fR to convert the name into
+a form that will be understood by the other program:
+.PP
+.CS
+\fBexec\fR notepad /p [file nativename some/dir/myfile.txt]
+.CE
+.PP
 If a program calls other programs, such as is common with compilers,
 then you may need to resort to batch files to hide the console windows
 that sometimes pop up:
+.PP
 .CS
 \fBexec\fR cmp.bat somefile.c -o somefile
 .CE
+.PP
 With the file \fIcmp.bat\fR looking something like:
+.PP
 .CS
 @gcc %*
 .CE
+.PP
 or like another variant using single parameters:
+.PP
 .CS
 @gcc %1 %2 %3 %4 %5 %6 %7 %8 %9
 .CE
@@ -448,6 +473,7 @@ applies especially when you want to run
 commands like
 \fIdir\fR from a Tcl script (if you just want to list filenames, use
 the \fBglob\fR command.)  To do that, use this:
+.PP
 .CS
 \fBexec\fR {*}[auto_execok dir] *.tcl
 .CE
diff --git a/doc/open.n b/doc/open.n
index a9da946..844433e 100644
--- a/doc/open.n
+++ b/doc/open.n
@@ -68,7 +68,7 @@ reading or writing of binary data.
 .VE 8.5
 .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
@@ -351,7 +351,13 @@ pipe is closed.  These problems only occur because both Tcl and the child
 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.  
+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
@@ -376,8 +382,23 @@ input, but is redirected from a file, then the above problem does not occur.
 See the \fBPORTABILITY ISSUES\fR section of the \fBexec\fR command for
 additional information not specific to command pipelines about executing
 applications on the various platforms
-.SH "EXAMPLE"
+.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
 .CS
 set fl [\fBopen\fR "| ls this_file_does_not_exist"]
 set data [read $fl]
@@ -385,6 +406,18 @@ if {[catch {close $fl} err]} {
     puts "ls command failed: $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
 .SH "SEE ALSO"
 file(n), close(n), filename(n), fconfigure(n), gets(n), read(n),
 puts(n), exec(n), pid(n), fopen(3)