Move TIP#285 routines out of Tcl_Eval(3) into their own manpage.

4 files changed, 78 insertions, 48 deletions

diff --git a/ChangeLog b/ChangeLog
index a01a097..bde4771 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2009-11-01  Joe English  <jenglish@users.sourceforge.net>
+
+	* doc/Eval.3, doc/Cancel.3: Move TIP#285 routines out of 
+	Tcl_Eval(3) into their own manpage.
+
 2009-10-31  Donal K. Fellows  <dkf@users.sf.net>
 
 	* generic/tclBasic.c (ExprRoundFunc): [Bug 2889593]: Correctly report
diff --git a/doc/Cancel.3 b/doc/Cancel.3
new file mode 100644
index 0000000..8c95e07
--- /dev/null
+++ b/doc/Cancel.3
@@ -0,0 +1,66 @@
+'\" Copyright (c) 2006-2008 Joe Mistachkin.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+'\" RCS: @(#) $Id: Cancel.3,v 1.1 2009/11/01 18:15:40 jenglish Exp $
+'\" 
+.so man.macros
+.TH Tcl_Cancel 3 8.6 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_CancelEval, Tcl_Canceled \- cancel Tcl scripts
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+int
+\fBTcl_CancelEval\fR(\fIinterp, clientData, flags\fR)
+.sp
+int
+\fBTcl_Canceled\fR(\fIinterp, flags\fR)
+.SH ARGUMENTS
+.AP Tcl_Interp *interp in
+Interpreter in which to cancel the script.
+.AP int flags in
+ORed combination of flag bits that specify additional options.
+For \fBTcl_CancelEval\fR, only \fBTCL_CANCEL_UNWIND\fR is currently
+supported.  For \fBTcl_Canceled\fR, only \fBTCL_LEAVE_ERR_MSG\fR and
+\fBTCL_CANCEL_UNWIND\fR are currently supported.
+.AP ClientData clientData in
+Currently, reserved for future use.
+It should be set to NULL.
+.BE
+.SH DESCRIPTION
+\fBTcl_CancelEval\fR cancels or unwinds the script in progress soon after
+the next invocation of asynchronous handlers, causing \fBTCL_ERROR\fR to be
+the return code for that script.  This function is thread-safe and may be
+called from any thread in the process.
+.PP
+\fBTcl_Canceled\fR checks if the script in progress has been canceled and
+returns \fBTCL_ERROR\fR if it has.  Otherwise, \fBTCL_OK\fR is returned.
+Extensions can use this function to check to see if they should abort a long
+running command.  This function is thread sensitive and may only be called
+from the thread the interpreter was created in.
+.SH "FLAG BITS"
+Any ORed combination of the following values may be used for the
+\fIflags\fR argument to procedures such as \fBTcl_CancelEval\fR:
+.TP 23
+\fBTCL_CANCEL_UNWIND\fR
+This flag is used by \fBTcl_CancelEval\fR and \fBTcl_Canceled\fR.
+For \fBTcl_CancelEval\fR, if this flag is set, the script in progress 
+is canceled and the evaluation stack for the interpreter is unwound.
+For \fBTcl_Canceled\fR, if this flag is set, the script in progress 
+is considered to be canceled only if the evaluation stack for the 
+interpreter is being unwound.
+.TP 23
+\fBTCL_LEAVE_ERR_MSG\fR
+This flag is only used by \fBTcl_Canceled\fR; it is ignored by
+other procedures.  If an error is returned and this bit is set in
+\fIflags\fR, then an error message will be left in the interpreter's
+result, where it can be retrieved with \fBTcl_GetObjResult\fR or
+\fBTcl_GetStringResult\fR.  If this flag bit is not set then no error
+message is left and the interpreter's result will not be modified.
+.SH "SEE ALSO"
+TIP 285
+.SH KEYWORDS
+cancel, unwind
diff --git a/doc/Eval.3 b/doc/Eval.3
index 313406c..efd82ad 100644
--- a/doc/Eval.3
+++ b/doc/Eval.3
@@ -2,18 +2,17 @@
 '\" Copyright (c) 1989-1993 The Regents of the University of California.
 '\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
 '\" Copyright (c) 2000 Scriptics Corporation.
-'\" Copyright (c) 2006-2008 Joe Mistachkin.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: Eval.3,v 1.28 2008/06/13 05:45:07 mistachkin Exp $
+'\" RCS: @(#) $Id: Eval.3,v 1.29 2009/11/01 18:15:40 jenglish Exp $
 '\" 
 .so man.macros
-.TH Tcl_Eval 3 8.6 Tcl "Tcl Library Procedures"
+.TH Tcl_Eval 3 8.1 Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
-Tcl_EvalObjEx, Tcl_EvalFile, Tcl_EvalObjv, Tcl_Eval, Tcl_EvalEx, Tcl_GlobalEval, Tcl_GlobalEvalObj, Tcl_VarEval, Tcl_VarEvalVA, Tcl_CancelEval, Tcl_Canceled \- execute and cancel Tcl scripts
+Tcl_EvalObjEx, Tcl_EvalFile, Tcl_EvalObjv, Tcl_Eval, Tcl_EvalEx, Tcl_GlobalEval, Tcl_GlobalEvalObj, Tcl_VarEval, Tcl_VarEvalVA \- execute Tcl scripts
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -44,25 +43,16 @@ int
 .sp
 int
 \fBTcl_VarEvalVA\fR(\fIinterp, argList\fR)
-.sp
-int
-\fBTcl_CancelEval\fR(\fIinterp, clientData, flags\fR)
-.sp
-int
-\fBTcl_Canceled\fR(\fIinterp, flags\fR)
 .SH ARGUMENTS
 .AS Tcl_Interp **termPtr
 .AP Tcl_Interp *interp in
-Interpreter in which to execute or cancel the script.  The interpreter's
-result is modified to hold the result or error message from the script.
+Interpreter in which to execute the script.  The interpreter's result is
+modified to hold the result or error message from the script.
 .AP Tcl_Obj *objPtr in
 A Tcl object containing the script to execute.
 .AP int flags in
 ORed combination of flag bits that specify additional options.
 \fBTCL_EVAL_GLOBAL\fR and \fBTCL_EVAL_DIRECT\fR are currently supported.
-For \fBTcl_CancelEval\fR, only \fBTCL_CANCEL_UNWIND\fR is currently
-supported.  For \fBTcl_Canceled\fR, only \fBTCL_LEAVE_ERR_MSG\fR and
-\fBTCL_CANCEL_UNWIND\fR are currently supported.
 .AP "const char" *fileName in
 Name of a file containing a Tcl script.
 .AP int objc in
@@ -82,9 +72,6 @@ String forming part of a Tcl script.
 .AP va_list argList in
 An argument list which must have been initialized using
 \fBva_start\fR, and cleared using \fBva_end\fR.
-.AP ClientData clientData in
-Currently, reserved for future use.
-It should be set to NULL.
 .BE
 
 .SH DESCRIPTION
@@ -172,17 +159,6 @@ of arguments.  \fBTcl_VarEval\fR is now deprecated.
 \fBTcl_VarEvalVA\fR is the same as \fBTcl_VarEval\fR except that
 instead of taking a variable number of arguments it takes an argument
 list. Like \fBTcl_VarEval\fR, \fBTcl_VarEvalVA\fR is deprecated.
-.PP
-\fBTcl_CancelEval\fR cancels or unwinds the script in progress soon after
-the next invocation of asynchronous handlers, causing \fBTCL_ERROR\fR to be
-the return code for that script.  This function is thread-safe and may be
-called from any thread in the process.
-.PP
-\fBTcl_Canceled\fR checks if the script in progress has been canceled and
-returns \fBTCL_ERROR\fR if it has.  Otherwise, \fBTCL_OK\fR is returned.
-Extensions can use this function to check to see if they should abort a long
-running command.  This function is thread sensitive and may only be called
-from the thread the interpreter was created in.
 
 .SH "FLAG BITS"
 Any ORed combination of the following values may be used for the
@@ -203,22 +179,6 @@ If this flag is set, the script is processed at global level.  This
 means that it is evaluated in the global namespace and its variable
 context consists of global variables only (it ignores any Tcl
 procedures at are active).
-.TP 23
-\fBTCL_CANCEL_UNWIND\fR
-This flag is only used by \fBTcl_CancelEval\fR and \fBTcl_Canceled\fR;
-it is ignored by other procedures.  For \fBTcl_CancelEval\fR, if this
-flag is set, the script in progress is canceled and the evaluation
-stack for the interpreter is unwound.  For \fBTcl_Canceled\fR, if this
-flag is set, the script in progress is considered to be canceled only
-if the evaluation stack for the interpreter is being unwound.
-.TP 23
-\fBTCL_LEAVE_ERR_MSG\fR
-This flag is only used by \fBTcl_Canceled\fR; it is ignored by
-other procedures.  If an error is returned and this bit is set in
-\fIflags\fR, then an error message will be left in the interpreter's
-result, where it can be retrieved with \fBTcl_GetObjResult\fR or
-\fBTcl_GetStringResult\fR.  If this flag bit is not set then no error
-message is left and the interpreter's result will not be modified.
 
 .SH "MISCELLANEOUS DETAILS"
 .PP
@@ -247,4 +207,4 @@ This means that top-level applications should never see a return code
 from \fBTcl_EvalObjEx\fR other then \fBTCL_OK\fR or \fBTCL_ERROR\fR.
 
 .SH KEYWORDS
-cancel, execute, file, global, object, result, script, unwind
+execute, file, global, object, result, script
diff --git a/doc/NRE.3 b/doc/NRE.3
index 633733f..94d2ba2 100644
--- a/doc/NRE.3
+++ b/doc/NRE.3
@@ -1,11 +1,10 @@
 .\"
 .\" Copyright (c) 2008 by Kevin B. Eknny.
 .\"
-
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: NRE.3,v 1.5 2009/11/01 13:00:07 dkf Exp $
+'\" RCS: @(#) $Id: NRE.3,v 1.6 2009/11/01 18:15:40 jenglish Exp $
 '\" 
 .so man.macros
 .TH NRE 3 8.6 Tcl "Tcl Library Procedures"