Backport many doc fixes

1 files changed, 19 insertions, 2 deletions

diff --git a/doc/close.n b/doc/close.n
index 501d282..28fe971 100644
--- a/doc/close.n
+++ b/doc/close.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: close.n,v 1.4 2001/09/14 19:20:40 andreas_kupries Exp $
+'\" RCS: @(#) $Id: close.n,v 1.4.8.1 2004/10/27 09:35:38 dkf Exp $
 '\" 
 .so man.macros
 .TH close n 7.5 Tcl "Tcl Built-In Commands"
@@ -59,7 +59,24 @@ that all output is correctly flushed before the process exits.
 .VE
 .PP
 The command returns an empty string, and may generate an error if
-an error occurs while flushing output.
+an error occurs while flushing output.  If a command in a command
+pipeline created with \fBopen\fR returns an error, \fBclose\fR
+generates an error (similar to the \fBexec\fR command.)
+.SH EXAMPLE
+This illustrates how you can use Tcl to ensure that files get closed
+even when errors happen by combining \fBcatch\fR, \fBclose\fR and
+\fBreturn\fR:
+.CS
+proc withOpenFile {filename channelVar script} {
+    upvar 1 $channelVar chan
+    set chan [open $filename]
+    catch {
+        uplevel 1 $script
+    } result options
+    \fBclose\fR $chan
+    return -options $options $result
+}
+.CE
 
 .SH "SEE ALSO"
 file(n), open(n), socket(n), eof(n), Tcl_StandardChannels(3)