Yet more doc update backporting

1 files changed, 21 insertions, 4 deletions

diff --git a/doc/open.n b/doc/open.n
index 9ef9754..4322dde 100644
--- a/doc/open.n
+++ b/doc/open.n
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: open.n,v 1.16.2.1 2003/04/18 00:32:34 dkf Exp $
+'\" RCS: @(#) $Id: open.n,v 1.16.2.2 2004/10/27 14:23:57 dkf Exp $
 '\" 
 .so man.macros
 .TH open n 8.3 Tcl "Tcl Built-In Commands"
@@ -132,7 +132,15 @@ standard input for the pipeline is taken from the current standard
 input unless overridden by the command.
 The id of the spawned process is accessible through the \fBpid\fR
 command, using the channel id returned by \fBopen\fR as argument.
-
+.PP
+If the command (or one of the commands) executed in the command
+pipeline returns an error (according to the definition in \fBexec\fR),
+a Tcl error is generated when \fBclose\fR is called on the channel
+(similar to the \fBclose\fR command.)
+.PP
+It is often useful to use the \fBfileevent\fR command with pipelines
+so other processing may happen at the same time as running the command
+in the background.
 .VS 8.4
 .SH "SERIAL COMMUNICATIONS"
 .PP
@@ -333,7 +341,7 @@ between the real console, if one is present, and a command pipeline that uses
 standard input or output.  If a command pipeline is opened for reading, some
 of the lines entered at the console will be sent to the command pipeline and
 some will be sent to the Tcl evaluator.  If a command pipeline is opened for
-writing, keystrokes entered into the console are not visible until the the
+writing, keystrokes entered into the console are not visible until the
 pipe is closed.  This behavior occurs whether the command pipeline is
 executing 16-bit or 32-bit applications.  These problems only occur because
 both Tcl and the child application are competing for the console at
@@ -356,7 +364,7 @@ standard input or output.  If a command pipeline is opened for reading from
 a 32-bit application, some of the keystrokes entered at the console will be
 sent to the command pipeline and some will be sent to the Tcl evaluator.  If
 a command pipeline is opened for writing to a 32-bit application, no output
-is visible on the console until the the pipe is closed.  These problems only
+is visible on the console until the 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
@@ -399,6 +407,15 @@ input, but is redirected from a file, then the above problem does not occur.
 See the PORTABILITY ISSUES section of the \fBexec\fR command for additional
 information not specific to command pipelines about executing
 applications on the various platforms
+.SH "EXAMPLE"
+Open a command pipeline and catch any errors:
+.CS
+set fl [\fBopen\fR "| ls this_file_does_not_exist"]
+set data [read $fl]
+if {[catch {close $fl} err]} {
+    puts "ls command failed: $err"
+}
+.CE
 
 .SH "SEE ALSO"
 file(n), close(n), filename(n), fconfigure(n), gets(n), read(n),