* doc/AddErrInfo.3: Docs for Tcl_(Get|Set)ReturnOptions. [TIP 227]

        * doc/AddErrInfo.3:
        * doc/Async.3:          Documentation updates to replace references
        * doc/BackgdErr.3:      to global variable ::errorInfo and ::errorCode
        * doc/SaveResult.3:     and to the ::bgerror command with references
        * doc/after.n:          to their preferred replacements, the
        * doc/bgerror.n:        -errorinfo and -errorcode return options,
        * doc/error.n:          the Tcl_*InterpState routines, and the
        * doc/exec.n:           [interp bgerror] command.
        * doc/exit.n:
        * doc/fileevent.n:
        * doc/interp.n:
        * doc/return.n:
        * doc/tclvars.n:
        * doc/update.n:

1 files changed, 28 insertions, 22 deletions

diff --git a/doc/error.n b/doc/error.n
index 35bad4d..72cbf52 100644
--- a/doc/error.n
+++ b/doc/error.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: error.n,v 1.6 2004/10/27 09:36:58 dkf Exp $
+'\" RCS: @(#) $Id: error.n,v 1.7 2004/11/20 00:17:31 dgp Exp $
 '\" 
 .so man.macros
 .TH error n "" Tcl "Tcl Built-In Commands"
@@ -23,36 +23,42 @@ Returns a \fBTCL_ERROR\fR code, which causes command interpretation to be
 unwound.  \fIMessage\fR is a string that is returned to the application
 to indicate what went wrong.
 .PP
-If the \fIinfo\fR argument is provided and is non-empty,
-it is used to initialize the global variable \fBerrorInfo\fR.
-\fBerrorInfo\fR is used to accumulate a stack trace of what
-was in progress when an error occurred; as nested commands unwind,
-the Tcl interpreter adds information to \fBerrorInfo\fR.  If the
-\fIinfo\fR argument is present, it is used to initialize
-\fBerrorInfo\fR and the first increment of unwind information
-will not be added by the Tcl interpreter.  In other
+The \fB-errorinfo\fB return option of an interpreter is used
+to accumulate a stack trace of what was in progress when an
+error occurred; as nested commands unwind,
+the Tcl interpreter adds information to the \fB-errorinfo\fR
+return option.  If the \fIinfo\fR argument is present, it is
+used to initialize the \fB-errorinfo\fR return options and
+the first increment of unwind information
+will not be added by the Tcl interpreter.  
+In other
 words, the command containing the \fBerror\fR command will not appear
-in \fBerrorInfo\fR; in its place will be \fIinfo\fR.
-This feature is most useful in conjunction with the \fBcatch\fR command:
+in the stack trace; in its place will be \fIinfo\fR.
+Historically, this feature had been most useful in conjunction
+with the \fBcatch\fR command:
 if a caught error cannot be handled successfully, \fIinfo\fR can be used
 to return a stack trace reflecting the original point of occurrence
 of the error:
 .CS
 \fBcatch {...} errMsg
-set savedInfo $errorInfo
+set savedInfo $::errorInfo
 \&...
 error $errMsg $savedInfo\fR
 .CE
+When working with Tcl 8.5 or later, the following code
+should be used instead:
+.CS
+\fBcatch {...} errMsg options
+\&...
+return -options $options $errMsg\fR
+.CE
 .PP
 If the \fIcode\fR argument is present, then its value is stored
-in the \fBerrorCode\fR global variable.  This variable is intended
-to hold a machine-readable description of the error in cases where
-such information is available; see the \fBtclvars\fR manual
-page for information on the proper format for the variable.
-If the \fIcode\fR argument is not
-present, then \fBerrorCode\fR is automatically reset to
-``NONE'' by the Tcl interpreter as part of processing the
-error generated by the command.
+in the \fB-errorcode\fR return option.  The \fB-errorcode\fR
+return option is intended to hold a machine-readable description
+of the error in cases where such information is available; see
+the \fBreturn\fR manual page for information on the proper format
+for this option's value.
 .SH EXAMPLE
 Generate an error if a basic mathematical operation fails:
 .CS
@@ -62,7 +68,7 @@ if {1+2 != 3} {
 .CE
 
 .SH "SEE ALSO"
-catch(n), return(n), tclvars(n)
+catch(n), return(n)
 
 .SH KEYWORDS
-error, errorCode, errorInfo
+error