* 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, 18 insertions, 14 deletions

diff --git a/doc/BackgdErr.3 b/doc/BackgdErr.3
index 1ac84c4..315e3b9 100644
--- a/doc/BackgdErr.3
+++ b/doc/BackgdErr.3
@@ -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: BackgdErr.3,v 1.3 2000/04/14 23:01:48 hobbs Exp $
+'\" RCS: @(#) $Id: BackgdErr.3,v 1.4 2004/11/20 00:17:31 dgp Exp $
 '\" 
 .so man.macros
 .TH Tcl_BackgroundError 3 7.5 Tcl "Tcl Library Procedures"
@@ -34,25 +34,29 @@ In these cases the code calls \fBTcl_BackgroundError\fR with an
 \fIinterp\fR argument identifying the interpreter in which the
 error occurred.  At the time \fBTcl_BackgroundError\fR is invoked,
 the interpreter's result is expected to contain an error message.
-\fBTcl_BackgroundError\fR will invoke the \fBbgerror\fR
-Tcl command to report the error in an application-specific fashion.
-If no \fBbgerror\fR command exists, or if it returns with an error condition,
-then \fBTcl_BackgroundError\fR reports the error itself by printing
-a message on the standard error file.
+\fBTcl_BackgroundError\fR will invoke the command registered
+in that interpreter to handle background errors by the
+\fBinterp bgerror\fR command.
+The registered handler command is meant to report the error
+in an application-specific fashion.  The handler command
+receives two arguments, the result of the interp, and the
+return options of the interp at the time the error occurred.
+If the application registers no handler command, the default
+handler command will attempt to call \fBbgerror\fR to report
+the error.  If an error condition arises while invoking the
+handler command, then \fBTcl_BackgroundError\fR reports the
+error itself by printing a message on the standard error file.
 .PP
-\fBTcl_BackgroundError\fR does not invoke \fBbgerror\fR immediately
+\fBTcl_BackgroundError\fR does not invoke the handler command immediately
 because this could potentially interfere with scripts that are in process
 at the time the error occurred.
-Instead, it invokes \fBbgerror\fR later as an idle callback.
-\fBTcl_BackgroundError\fR saves the values of the \fBerrorInfo\fR and
-\fBerrorCode\fR variables and restores these values just before
-invoking \fBbgerror\fR.
+Instead, it invokes the handler command later as an idle callback.
 .PP
 It is possible for many background errors to accumulate before
-\fBbgerror\fR is invoked.  When this happens, each of the errors
-is processed in order.  However, if \fBbgerror\fR returns a
+the handler command is invoked.  When this happens, each of the errors
+is processed in order.  However, if the handle command returns a
 break exception, then all remaining error reports for the
 interpreter are skipped.
 
 .SH KEYWORDS
-background, bgerror, error
+background, bgerror, error, interp