1 files changed, 33 insertions, 21 deletions

diff --git a/tcl/doc/ParseCmd.3 b/tcl/doc/ParseCmd.3
index a9c0fb2e634..407b390a2c7 100644
--- a/tcl/doc/ParseCmd.3
+++ b/tcl/doc/ParseCmd.3
@@ -10,7 +10,7 @@
 .TH Tcl_ParseCommand 3 8.3 Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
-Tcl_ParseCommand, Tcl_ParseExpr, Tcl_ParseBraces, Tcl_ParseQuotedString, Tcl_ParseVarName, Tcl_ParseVar, Tcl_FreeParse, Tcl_EvalTokens \- parse Tcl scripts and expressions
+Tcl_ParseCommand, Tcl_ParseExpr, Tcl_ParseBraces, Tcl_ParseQuotedString, Tcl_ParseVarName, Tcl_ParseVar, Tcl_FreeParse, Tcl_EvalTokens, Tcl_EvalTokensStandard \- parse Tcl scripts and expressions
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -30,22 +30,26 @@ int
 int
 \fBTcl_ParseVarName\fR(\fIinterp, string, numBytes, parsePtr, append\fR)
 .sp
-char *
+CONST char *
 \fBTcl_ParseVar\fR(\fIinterp, string, termPtr\fR)
 .sp
 \fBTcl_FreeParse\fR(\fIusedParsePtr\fR)
 .sp
 Tcl_Obj *
 \fBTcl_EvalTokens\fR(\fIinterp, tokenPtr, numTokens\fR)
+.sp
+Tcl_Obj *
+\fBTcl_EvalTokensStandard\fR(\fIinterp, tokenPtr, numTokens\fR)
 .SH ARGUMENTS
 .AS Tcl_Interp *usedParsePtr
 .AP Tcl_Interp *interp out
-For procedures other than \fBTcl_FreeParse\fR and \fBTcl_EvalTokens\fR,
-used only for error reporting;
+For procedures other than \fBTcl_FreeParse\fR, \fBTcl_EvalTokens\fR
+and \fBTcl_EvalTokensStandard\fR, used only for error reporting;
 if NULL, then no error messages are left after errors.
-For \fBTcl_EvalTokens\fR, determines the context for evaluating the
+For \fBTcl_EvalTokens\fR and \fBTcl_EvalTokensStandard\fR,
+determines the context for evaluating the
 script and also is used for error reporting; must not be NULL.
-.AP char *string in
+.AP "CONST char" *string in
 Pointer to first character in string to parse.
 .AP int numBytes in
 Number of bytes in \fIstring\fR, not including any terminating null
@@ -67,7 +71,7 @@ Any previous information in this structure
 is ignored, unless \fIappend\fR is non-zero in a call to
 \fBTcl_ParseBraces\fR, \fBTcl_ParseQuotedString\fR,
 or \fBTcl_ParseVarName\fR.
-.AP char **termPtr out
+.AP "CONST char" **termPtr out
 If not NULL, points to a location where
 \fBTcl_ParseBraces\fR, \fBTcl_ParseQuotedString\fR, and
 \fBTcl_ParseVar\fR will store a pointer to the character
@@ -125,7 +129,7 @@ with information about the structure of the string
 (see below for details),
 and stores a pointer to the character just after the terminating \fB}\fR
 in the location given by \fI*termPtr\fR.
-If an error occurrs while parsing the string
+If an error occurs while parsing the string
 then \fBTCL_ERROR\fR is returned,
 an error message is left in \fIinterp\fR's result,
 and no information is left at \fI*parsePtr\fR or \fI*termPtr\fR.
@@ -141,7 +145,7 @@ with information about the structure of the string
 (see below for details),
 and stores a pointer to the character just after the terminating \fB"\fR
 in the location given by \fI*termPtr\fR.
-If an error occurrs while parsing the string
+If an error occurs while parsing the string
 then \fBTCL_ERROR\fR is returned,
 an error message is left in \fIinterp\fR's result,
 and no information is left at \fI*parsePtr\fR or \fI*termPtr\fR.
@@ -154,7 +158,7 @@ If a variable name was parsed successfully, \fBTcl_ParseVarName\fR
 returns \fBTCL_OK\fR and fills in the structure pointed to by
 \fIparsePtr\fR with information about the structure of the variable name
 (see below for details).  If an error
-occurrs while parsing the command then \fBTCL_ERROR\fR is returned, an
+occurs while parsing the command then \fBTCL_ERROR\fR is returned, an
 error message is left in \fIinterp\fR's result (if \fIinterp\fR isn't
 NULL), and no information is left at \fI*parsePtr\fR.
 .PP
@@ -178,18 +182,27 @@ These procedures ignore any existing information in
 so if repeated calls are being made to any of them
 then \fBTcl_FreeParse\fR must be invoked once after each call.
 .PP
-\fBTcl_EvalTokens\fR evaluates a sequence of parse tokens from a Tcl_Parse
-structure.  The tokens typically consist
+\fBTcl_EvalTokensStandard\fR evaluates a sequence of parse tokens from
+a Tcl_Parse structure.  The tokens typically consist
 of all the tokens in a word or all the tokens that make up the index for
-a reference to an array variable.  \fBTcl_EvalTokens\fR performs the
-substitutions requested by the tokens, concatenates the
-resulting values, and returns the result in a new Tcl_Obj.  The
-reference count of the object returned as result has been
+a reference to an array variable.  \fBTcl_EvalTokensStandard\fR performs the
+substitutions requested by the tokens and concatenates the
+resulting values. 
+The return value from \fBTcl_EvalTokensStandard\fR is a Tcl completion
+code with one of the values \fBTCL_OK\fR, \fBTCL_ERROR\fR,
+\fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR.
+In addition, a result value or error message is left in \fIinterp\fR's
+result; it can be retrieved using \fBTcl_GetObjResult\fR.
+.PP
+\fBTcl_EvalTokens\fR differs from \fBTcl_EvalTokensStandard\fR only in
+the return convention used: it returns the result in a new Tcl_Obj.
+The reference count of the object returned as result has been
 incremented, so the caller must
 invoke \fBTcl_DecrRefCount\fR when it is finished with the object.
-If an error occurs while evaluating the tokens (such as a reference to
-a non-existent variable) then the return value is NULL and an error
-message is left in \fIinterp\fR's result.
+If an error or other exception occurs while evaluating the tokens
+(such as a reference to a non-existent variable) then the return value
+is NULL and an error message is left in \fIinterp\fR's result. The use
+of \fBTcl_EvalTokens\fR is deprecated.
 
 .SH "TCL_PARSE STRUCTURE"
 .PP
@@ -332,7 +345,7 @@ this includes the sub-tokens for any nested \fBTCL_TOKEN_SUB_EXPR\fR tokens.
 \fBTCL_TOKEN_OPERATOR\fR
 The token describes one operator of an expression
 such as \fB&&\fR or \fBhypot\fR.
-An \fBTCL_TOKEN_OPERATOR\fR token is always preceeded by a
+An \fBTCL_TOKEN_OPERATOR\fR token is always preceded by a
 \fBTCL_TOKEN_SUB_EXPR\fR token
 that describes the operator and its operands;
 the \fBTCL_TOKEN_SUB_EXPR\fR token's \fInumComponents\fR field
@@ -436,4 +449,3 @@ referenced by code outside of these procedures.
 
 .SH KEYWORDS
 backslash substitution, braces, command, expression, parse, token, variable substitution
-