1 files changed, 72 insertions, 21 deletions
diff --git a/doc/interp.n b/doc/interp.n
index 8e06fd3..92113a6 100644
--- a/doc/interp.n
+++ b/doc/interp.n
@@ -6,10 +6,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: interp.n,v 1.42 2008/12/09 20:16:29 dgp Exp $
-'\" 
-.so man.macros
 .TH interp n 8.6 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -63,10 +61,18 @@ on how the alias mechanism works.
 A qualified interpreter name is a proper Tcl lists containing a subset of its
 ancestors in the interpreter hierarchy, terminated by the string naming the
 interpreter in its immediate master. Interpreter names are relative to the
-interpreter in which they are used. For example, if \fBa\fR is a slave of
-the current interpreter and it has a slave \fBa1\fR, which in turn has a
-slave \fBa11\fR, the qualified name of \fBa11\fR in \fBa\fR is the list
-\fBa1 a11\fR.
+interpreter in which they are used. For example, if
+.QW \fBa\fR
+is a slave of the current interpreter and it has a slave
+.QW \fBa1\fR ,
+which in turn has a slave
+.QW \fBa11\fR ,
+the qualified name of
+.QW \fBa11\fR
+in
+.QW \fBa\fR
+is the list
+.QW "\fBa1 a11\fR" .
 .PP
 The \fBinterp\fR command, described below, accepts qualified interpreter
 names as arguments; the interpreter in which the command is being evaluated
@@ -110,10 +116,12 @@ invoking the command.
 interpreter.  For example,
 .QW "\fBa b\fR"
 identifies an interpreter
-\fBb\fR, which is a slave of interpreter \fBa\fR, which is a slave
-of the invoking interpreter.  An empty list specifies the interpreter
-invoking the command.  \fIsrcCmd\fR gives the name of a new
-command, which will be created in the source interpreter.
+.QW \fBb\fR ,
+which is a slave of interpreter
+.QW \fBa\fR ,
+which is a slave of the invoking interpreter.  An empty list specifies
+the interpreter invoking the command.  \fIsrcCmd\fR gives the name of
+a new command, which will be created in the source interpreter.
 \fITargetPath\fR and \fItargetCmd\fR specify a target interpreter
 and command, and the \fIarg\fR arguments, if any, specify additional
 arguments to \fItargetCmd\fR which are prepended to any arguments specified
@@ -186,6 +194,48 @@ given name already exists in this master.
 The initial recursion limit of the slave interpreter is set to the
 current recursion limit of its parent interpreter.
 .TP
+\fBinterp\fR \fBdebug \fIpath\fR ?\fB\-frame\fR ?\fIbool\fR??
+.
+Controls whether frame-level stack information is captured in the
+slave interpreter identified by \fIpath\fR.  If no arguments are
+given, option and current setting are returned.  If \fB\-frame\fR
+is given, the debug setting is set to the given boolean if provided
+and the current setting is returned.
+This only effects the output of \fBinfo frame\fR, in that exact
+frame-level information for command invocation at the bytecode level
+is only captured with this setting on.
+.RS
+.PP
+For example, with code like
+.PP
+.CS
+\fBproc\fR mycontrol {... script} {
+  ...
+  \fBuplevel\fR 1 $script
+  ...
+}
+
+\fBproc\fR dosomething {...} {
+  ...
+  mycontrol {
+    somecode
+  }
+}
+.CE
+.PP
+the standard setting will provide a relative line number for the
+command \fBsomecode\fR and the relevant frame will be of type
+\fBeval\fR. With frame-debug active on the other hand the tracking
+extends so far that the system will be able to determine the file and
+absolute line number of this command, and return a frame of type
+\fBsource\fR. This more exact information is paid for with slower
+execution of all commands.
+.PP
+Note that once it is on, this flag cannot be switched back off: such
+attempts are silently ignored. This is needed to maintain the
+consistency of the underlying interpreter's state.
+.RE
+.TP
 \fBinterp\fR \fBdelete \fR?\fIpath ...?\fR
 .
 Deletes zero or more interpreters given by the optional \fIpath\fR
@@ -296,7 +346,7 @@ already trusted.
 Returns the maximum allowable nesting depth for the interpreter
 specified by \fIpath\fR.  If \fInewlimit\fR is specified,
 the interpreter recursion limit will be set so that nesting
-of more than \fInewlimit\fR calls to \fBTcl_Eval()\fR
+of more than \fInewlimit\fR calls to \fBTcl_Eval\fR
 and related procedures in that interpreter will return an error.
 The \fInewlimit\fR value is also returned.
 The \fInewlimit\fR value must be a positive integer between 1 and the
@@ -748,9 +798,10 @@ This option (common for all limit types) specifies (if non-empty) a Tcl script
 to be executed in the global namespace of the interpreter reading and writing
 the option when the particular limit in the limited interpreter is exceeded.
 The callback may modify the limit on the interpreter if it wishes the limited
-interpreter to continue executing. If the callback generates an exception, it is
-reported through the background exception mechanism (see \fBBACKGROUND EXCEPTION
-HANDLING\fR). Note that the callbacks defined by one interpreter are
+interpreter to continue executing. If the callback generates an exception, it
+is reported through the background exception mechanism (see
+\fBBACKGROUND EXCEPTION HANDLING\fR).
+Note that the callbacks defined by one interpreter are
 completely isolated from the callbacks defined by another, and that the order
 in which those callbacks are called is undefined.
 .TP
@@ -831,8 +882,8 @@ set i [\fBinterp create\fR -safe]
 \fBinterp hide\fR $i lappend
 \fBinterp alias\fR $i lappend {} loggedLappend $i
 proc loggedLappend {i args} {
-   puts "logged invocation of lappend $args"
-   \fBinterp invokehidden\fR $i lappend {*}$args
+    puts "logged invocation of lappend $args"
+    \fBinterp invokehidden\fR $i lappend {*}$args
 }
 \fBinterp eval\fR $i $someUntrustedScript
 .CE
@@ -844,10 +895,10 @@ terminates.
 set i [\fBinterp create\fR]
 \fBinterp limit\fR $i command -value 1000
 \fBinterp eval\fR $i {
-   set x 0
-   while {1} {
-      puts "Counting up... [incr x]"
-   }
+    set x 0
+    while {1} {
+        puts "Counting up... [incr x]"
+    }
 }
 .CE
 .SH "SEE ALSO"