integrated documentation patch

1 files changed, 29 insertions, 15 deletions

diff --git a/doc/catch.n b/doc/catch.n
index 4afd314..3883b84 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.1.2.1 1998/09/24 23:58:29 stanton Exp $
+'\" RCS: @(#) $Id: catch.n,v 1.1.2.2 1998/11/09 22:52:44 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,36 @@ 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.
 
+.SH EXAMPLE
+
+\fBcatch\fR 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
+
 .SH KEYWORDS
 catch, error