* doc/AddErrInfo.3: Documented Tcl_(Set|Get)ErrorLine (TIP 336).

        * doc/CrtCommand.3:     Various other documentation updates to
        * doc/CrtInterp.3:      reflect the lack of access to Tcl_Interp fields
        * doc/Interp.3:         by default.
        * doc/SetResult.3:
        * doc/tcl.decls:

1 files changed, 19 insertions, 4 deletions

diff --git a/doc/AddErrInfo.3 b/doc/AddErrInfo.3
index 0de0a0f..ae136ce 100644
--- a/doc/AddErrInfo.3
+++ b/doc/AddErrInfo.3
@@ -5,13 +5,13 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: AddErrInfo.3,v 1.23 2008/10/17 10:22:25 dkf Exp $
+'\" RCS: @(#) $Id: AddErrInfo.3,v 1.24 2008/12/15 18:33:24 dgp Exp $
 '\" 
 .so man.macros
 .TH Tcl_AddErrorInfo 3 8.5 Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
-Tcl_GetReturnOptions, Tcl_SetReturnOptions, Tcl_AddErrorInfo, Tcl_AppendObjToErrorInfo, Tcl_AddObjErrorInfo, Tcl_SetObjErrorCode, Tcl_SetErrorCode, Tcl_SetErrorCodeVA, Tcl_PosixError, Tcl_LogCommandInfo \- retrieve or record information about errors and other return options
+Tcl_GetReturnOptions, Tcl_SetReturnOptions, Tcl_AddErrorInfo, Tcl_AppendObjToErrorInfo, Tcl_AddObjErrorInfo, Tcl_SetObjErrorCode, Tcl_SetErrorCode, Tcl_SetErrorCodeVA, Tcl_SetErrorLine, Tcl_GetErrorLine, Tcl_PosixError, Tcl_LogCommandInfo \- retrieve or record information about errors and other return options
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -34,6 +34,10 @@ int
 .sp
 \fBTcl_SetErrorCodeVA\fR(\fIinterp, argList\fR)
 .sp
+\fBTcl_GetErrorLine\fR(\fIinterp\fR)
+.sp
+\fBTcl_SetErrorLine\fR(\fIinterp, lineNum\fR)
+.sp
 const char *
 \fBTcl_PosixError\fR(\fIinterp\fR)
 .sp
@@ -70,6 +74,8 @@ Last \fIelement\fR argument must be NULL.
 .AP va_list argList in
 An argument list which must have been initialized using
 \fBva_start\fR, and cleared using \fBva_end\fR.
+.AP int lineNum
+The line number of a script where an error occurred.
 .AP "const char" *script in
 Pointer to first character in script containing command (must be <= command)
 .AP "const char" *command in
@@ -157,8 +163,12 @@ to set any collection of return options, there are a handful
 of return options that are very frequently used.  Most 
 notably the \fB\-errorinfo\fR and \fB\-errorcode\fR return
 options should be set properly when the command procedure
-of a command returns \fBTCL_ERROR\fR.  Tcl provides several
-simpler interfaces to more directly set these return options.
+of a command returns \fBTCL_ERROR\fR.  The \fB\-errorline\fR
+return option is also read by commands that evaluate scripts
+and wish to supply detailed error location information in 
+the stack trace text they append to the \fB\-errorinfo\fR option.
+Tcl provides several simpler interfaces to more directly set
+these return options.
 .PP
 The \fB\-errorinfo\fR option holds a stack trace of the
 operations that were in progress when an error occurred,
@@ -235,6 +245,11 @@ record instead of an object. Otherwise, it is similar to
 \fBTcl_SetErrorCodeVA\fR is the same as \fBTcl_SetErrorCode\fR except that
 instead of taking a variable number of arguments it takes an argument list.
 .PP
+The procedure \fBTcl_GetErrorLine\fR is used to read the integer value
+of the \fB\-errorline\fR return option without the overhead of a full
+call to \fBTcl_GetReturnOptions\fR.  Likewise, \fBTcl_SetErrorLine\fR
+sets the \fB\-errorline\fR return option value.
+.PP
 \fBTcl_PosixError\fR
 sets the \fB\-errorcode\fR variable after an error in a POSIX kernel call.
 It reads the value of the \fBerrno\fR C variable and calls