merged tcl 8.1 branch back into the main trunk

1 files changed, 46 insertions, 16 deletions

diff --git a/doc/catch.n b/doc/catch.n
index 17b5c1d..23771f9 100644
--- a/doc/catch.n
+++ b/doc/catch.n
@@ -5,10 +5,10 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: catch.n,v 1.2 1998/09/14 18:39:51 stanton Exp $
+'\" RCS: @(#) $Id: catch.n,v 1.3 1999/04/16 00:46:34 stanton Exp $
 '\" 
 .so man.macros
-.TH catch n "" Tcl "Tcl Built-In Commands"
+.TH catch n "8.0" Tcl "Tcl Built-In Commands"
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -19,22 +19,52 @@ catch \- Evaluate script and trap exceptional returns
 
 .SH DESCRIPTION
 .PP
-The \fBcatch\fR command may be used to prevent errors from aborting
-command interpretation.  \fBCatch\fR calls the Tcl interpreter recursively
-to execute \fIscript\fR, and always returns a TCL_OK code, regardless of
-any errors that might occur while executing \fIscript\fR.  The return
-value from \fBcatch\fR is a decimal string giving the
-code returned by the Tcl interpreter after executing \fIscript\fR.
-This will be \fB0\fR (TCL_OK) if there were no errors in \fIscript\fR;
-otherwise
-it will have a non-zero value corresponding to one of the exceptional
-return codes (see tcl.h for the definitions of code values).  If the
-\fIvarName\fR argument is given, then it gives the name of a variable;
-\fBcatch\fR will set the variable to the string returned
-from \fIscript\fR (either a result or an error message).
+The \fBcatch\fR command may be used to prevent errors from aborting command
+interpretation.  \fBCatch\fR calls the Tcl interpreter recursively to
+execute \fIscript\fR, and always returns without raising an error,
+regardless of any errors that might occur while executing \fIscript\fR.
+.PP
+If \fIscript\fR raises an error, \fBcatch\fR will return a non-zero integer
+value corresponding to one of the exceptional return codes (see tcl.h
+for the definitions of code values).  If the \fIvarName\fR argument is
+given, then the variable it names is set to the error message from
+interpreting \fIscript\fR.
+.PP
+If \fIscript\fR does not raise an error, \fBcatch\fR will return 0
+(TCL_OK) and set the variable to the value returned from \fIscript\fR.
 .PP
 Note that \fBcatch\fR catches all exceptions, including those
-generated by \fBbreak\fR and \fBcontinue\fR as well as errors.
+generated by \fBbreak\fR and \fBcontinue\fR as well as errors.  The
+only errors that are not caught are syntax errors found when the
+script is compiled.  This is because the catch command only catches
+errors during runtime.  When the catch statement is compiled, the
+script is compiled as well and any syntax errors will generate a Tcl
+error. 
+
+.SH EXAMPLES
+
+The \fBcatch\fR command may be used in an \fBif\fR to branch based on
+the success of a script.
+
+.DS
+.CS
+if { [catch {open $someFile w} fid] } {
+    puts stderr "Could not open $someFile for writing\\n$fid"
+    exit 1
+}
+.CE
+.DE
+The \fBcatch\fR command will not catch compiled syntax errors.  The
+first time proc \fBfoo\fR is called, the body will be compiled and a
+Tcl error will be generated. 
+
+.DS
+.CS
+proc foo {} {
+    catch {expr {1 +- }}
+}
+.CE
+.DE
 
 .SH KEYWORDS
 catch, error