More doc fix backporting

1 files changed, 80 insertions, 46 deletions

diff --git a/doc/interp.n b/doc/interp.n
index ac8adfb..a118e50 100644
--- a/doc/interp.n
+++ b/doc/interp.n
@@ -4,7 +4,7 @@
 '\" 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.9 2002/07/01 18:24:39 jenglish Exp $
+'\" RCS: @(#) $Id: interp.n,v 1.9.2.1 2004/10/27 12:52:40 dkf Exp $
 '\" 
 .so man.macros
 .TH interp n 7.6 Tcl "Tcl Built-In Commands"
@@ -48,15 +48,16 @@ application's environment. For example, all IO channel creation
 commands and subprocess creation commands are made inaccessible to safe
 interpreters.
 .VS
-See SAFE INTERPRETERS below for more information on
+See \fBSAFE INTERPRETERS\fR below for more information on
 what features are present in a safe interpreter.
 The dangerous functionality is not removed from the safe interpreter;
 instead, it is \fIhidden\fR, so that only trusted interpreters can obtain
 access to it. For a detailed explanation of hidden commands, see
-HIDDEN COMMANDS, below.
+\fBHIDDEN COMMANDS\fR, below.
 The alias mechanism can be used for protected communication (analogous to a
-kernel call) between a slave interpreter and its master. See ALIAS
-INVOCATION, below, for more details on how the alias mechanism works.
+kernel call) between a slave interpreter and its master. 
+See \fBALIAS INVOCATION\fR, below, for more details 
+on how the alias mechanism works.
 .VE
 .PP
 A qualified interpreter name is a proper Tcl lists containing a subset of its
@@ -74,27 +75,24 @@ it is impossible to refer to a master (ancestor) interpreter by name in a
 slave interpreter except through aliases. Also, there is no global name by
 which one can refer to the first interpreter created in an application.
 Both restrictions are motivated by safety concerns.
-
-.VS
 .SH "THE INTERP COMMAND"
 .PP
-.VE
 The \fBinterp\fR command is used to create, delete, and manipulate
 slave interpreters, and to share or transfer
 channels between interpreters.  It can have any of several forms, depending
 on the \fIoption\fR argument:
 .TP
-\fBinterp\fR \fBalias\fR \fIsrcPath\fR \fIsrcCmd\fR
+\fBinterp\fR \fBalias\fR \fIsrcPath\fR \fIsrcToken\fR
 Returns a Tcl list whose elements are the \fItargetCmd\fR and
-\fIarg\fRs associated with the alias named \fIsrcCmd\fR
-(all of these are the values specified when the alias was
-created; it is possible that the actual source command in the
-slave is different from \fIsrcCmd\fR if it was renamed).
+\fIarg\fRs associated with the alias represented by \fIsrcToken\fR
+(this is the value returned when the alias was
+created; it is possible that the name of the source command in the
+slave is different from \fIsrcToken\fR).
 .TP
-\fBinterp\fR \fBalias\fR \fIsrcPath\fR \fIsrcCmd\fR \fB{}\fR
-Deletes the alias for \fIsrcCmd\fR in the slave interpreter identified by
+\fBinterp\fR \fBalias\fR \fIsrcPath\fR \fIsrcToken\fR \fB{}\fR
+Deletes the alias for \fIsrcToken\fR in the slave interpreter identified by
 \fIsrcPath\fR.
-\fIsrcCmd\fR refers to the name under which the alias
+\fIsrcToken\fR refers to the value returned when the alias
 was created;  if the source command has been renamed, the renamed
 command will be deleted.
 .TP
@@ -119,12 +117,18 @@ in the invocation of \fIsrcCmd\fR.
 already exist; it is not created by this command.
 The alias arranges for the given target command to be invoked
 in the target interpreter whenever the given source command is
-invoked in the source interpreter.  See ALIAS INVOCATION below for
-more details.
+invoked in the source interpreter.  See \fBALIAS INVOCATION\fR below for
+more details. 
+The command returns a token that uniquely identifies the command created
+\fIsrcCmd\fR, even if the command is renamed afterwards. The token may but
+does not have to be equal to \fIsrcCmd\fR.
 .TP
 \fBinterp\fR \fBaliases \fR?\fIpath\fR?
-This command returns a Tcl list of the names of all the source commands for
-aliases defined in the interpreter identified by \fIpath\fR.
+This command returns a Tcl list of the tokens of all the source commands for
+aliases defined in the interpreter identified by \fIpath\fR. The tokens
+correspond to the values returned when 
+the aliases were created (which may not be the same 
+as the current names of the commands).
 .TP
 \fBinterp\fR \fBcreate \fR?\fB\-safe\fR? ?\fB\-\|\-\fR? ?\fIpath\fR?
 Creates a slave interpreter identified by \fIpath\fR and a new command,
@@ -164,6 +168,11 @@ a Tcl script in the slave interpreter identified by \fIpath\fR. The result
 of this evaluation (including error information such as the \fBerrorInfo\fR
 and \fBerrorCode\fR variables, if an error occurs) is returned to the
 invoking interpreter.
+Note that the script will be executed in the current context stack frame of the
+\fIpath\fR interpreter; this is so that the implementations (in a master
+interpreter) of aliases in a slave interpreter can execute scripts in
+the slave that find out information about the slave's current state
+and stack frame.
 .TP
 \fBinterp exists \fIpath\fR
 Returns  \fB1\fR if a slave interpreter by the specified \fIpath\fR
@@ -179,7 +188,7 @@ in the interpreter
 denoted by \fIpath\fR.
 If an exposed command with the targeted name already exists, this command
 fails.
-Hidden commands are explained in more detail in HIDDEN COMMANDS, below.
+Hidden commands are explained in more detail in \fBHIDDEN COMMANDS\fR, below.
 .TP
 \fBinterp\fR \fBhide\fR \fIpath\fR \fIexposedCmdName\fR ?\fIhiddenCmdName\fR?
 Makes the exposed command \fIexposedCmdName\fR hidden, renaming
@@ -194,7 +203,7 @@ Commands to be hidden by \fBinterp hide\fR are looked up in the global
 namespace even if the current namespace is not the global one. This
 prevents slaves from fooling a master interpreter into hiding the wrong
 command, by making the current namespace be different from the global one.
-Hidden commands are explained in more detail in HIDDEN COMMANDS, below.
+Hidden commands are explained in more detail in \fBHIDDEN COMMANDS\fR, below.
 .TP
 \fBinterp\fR \fBhidden\fR \fIpath\fR
 Returns a list of the names of all hidden commands in the interpreter
@@ -208,7 +217,7 @@ If the \fB-global\fR flag is present, the hidden command is invoked at the
 global level in the target interpreter; otherwise it is invoked at the
 current call frame and can access local variables in that and outer call
 frames.
-Hidden commands are explained in more detail in HIDDEN COMMANDS, below.
+Hidden commands are explained in more detail in \fBHIDDEN COMMANDS\fR, below.
 .VE
 .TP
 \fBinterp issafe\fR ?\fIpath\fR?
@@ -269,7 +278,6 @@ The target command does not have to be defined at the time of this invocation.
 Causes the IO channel identified by \fIchannelId\fR to become available in
 the interpreter identified by \fIdestPath\fR and unavailable in the
 interpreter identified by \fIsrcPath\fR.
-
 .SH "SLAVE COMMAND"
 .PP
 For each slave interpreter created with the \fBinterp\fR command, a
@@ -285,22 +293,21 @@ and the \fIarg\fRs determine the exact behavior of the command.
 The valid forms of this command are:
 .TP
 \fIslave \fBaliases\fR
-Returns a Tcl list whose elements are the names of all the
-aliases in \fIslave\fR.  The names returned are the \fIsrcCmd\fR
-values used when the aliases were created (which may not be the same
-as the current names of the commands, if they have been
-renamed).
+Returns a Tcl list whose elements are the tokens of all the
+aliases in \fIslave\fR.  The tokens correspond to the values returned when
+the aliases were created (which may not be the same 
+as the current names of the commands).
 .TP
-\fIslave \fBalias \fIsrcCmd\fR
+\fIslave \fBalias \fIsrcToken\fR
 Returns a Tcl list whose elements are the \fItargetCmd\fR and
-\fIarg\fRs associated with the alias named \fIsrcCmd\fR
-(all of these are the values specified when the alias was
+\fIarg\fRs associated with the alias represented by \fIsrcToken\fR
+(this is the value returned when the alias was
 created; it is possible that the actual source command in the
-slave is different from \fIsrcCmd\fR if it was renamed).
+slave is different from \fIsrcToken\fR).
 .TP
-\fIslave \fBalias \fIsrcCmd \fB{}\fR
-Deletes the alias for \fIsrcCmd\fR in the slave interpreter.
-\fIsrcCmd\fR refers to the name under which the alias
+\fIslave \fBalias \fIsrcToken \fB{}\fR
+Deletes the alias for \fIsrcToken\fR in the slave interpreter.
+\fIsrcToken\fR refers to the value returned when the alias
 was created;  if the source command has been renamed, the renamed
 command will be deleted.
 .TP
@@ -310,7 +317,10 @@ in \fIslave\fR, \fItargetCmd\fR is invoked in the master.
 The \fIarg\fR arguments will be passed to \fItargetCmd\fR as additional
 arguments, prepended before any arguments passed in the invocation of
 \fIsrcCmd\fR.
-See ALIAS INVOCATION below for details.
+See \fBALIAS INVOCATION\fR below for details.
+The command returns a token that uniquely identifies the command created
+\fIsrcCmd\fR, even if the command is renamed afterwards. The token may but
+does not have to be equal to \fIsrcCmd\fR.
 .TP
 \fIslave \fBeval \fIarg \fR?\fIarg ..\fR?
 This command concatenates all of the \fIarg\fR arguments in
@@ -319,6 +329,11 @@ the resulting string as a Tcl script in \fIslave\fR.
 The result of this evaluation (including error information
 such as the \fBerrorInfo\fR and \fBerrorCode\fR variables, if an
 error occurs) is returned to the invoking interpreter.
+Note that the script will be executed in the current context stack frame
+of \fIslave\fR; this is so that the implementations (in a master
+interpreter) of aliases in a slave interpreter can execute scripts in
+the slave that find out information about the slave's current state
+and stack frame.
 .VS "" BR
 .TP
 \fIslave \fBexpose \fIhiddenName \fR?\fIexposedCmdName\fR?
@@ -328,12 +343,12 @@ accepted only if it is a valid global name space name without any ::),
 in \fIslave\fR.
 If an exposed command with the targeted name already exists, this command
 fails.
-For more details on hidden commands, see HIDDEN COMMANDS, below.
+For more details on hidden commands, see \fBHIDDEN COMMANDS\fR, below.
 .TP
 \fIslave \fBhide \fIexposedCmdName\fR ?\fIhiddenCmdName\fR?
 This command hides the exposed command \fIexposedCmdName\fR, renaming it to 
 the hidden command \fIhiddenCmdName\fR, or keeping the same name if the
-the argument is not given, in the \fIslave\fR interpreter.
+argument is not given, in the \fIslave\fR interpreter.
 If a hidden command with the targeted name already exists, this command
 fails.
 Currently both \fIexposedCmdName\fR and \fIhiddenCmdName\fR can 
@@ -342,7 +357,7 @@ Commands to be hidden are looked up in the global
 namespace even if the current namespace is not the global one. This
 prevents slaves from fooling a master interpreter into hiding the wrong
 command, by making the current namespace be different from the global one.
-For more details on hidden commands, see HIDDEN COMMANDS, below.
+For more details on hidden commands, see \fBHIDDEN COMMANDS\fR, below.
 .TP
 \fIslave \fBhidden\fR
 Returns a list of the names of all hidden commands in \fIslave\fR.
@@ -354,8 +369,8 @@ applied to the arguments.
 If the \fB-global\fR flag is given, the command is invoked at the global
 level in the slave; otherwise it is invoked at the current call frame and
 can access local variables in that or outer call frames.
-For more details on hidden commands, see HIDDEN
-COMMANDS, below.
+For more details on hidden commands,
+see \fBHIDDEN COMMANDS\fR, below.
 .VE
 .TP
 \fIslave \fBissafe\fR
@@ -433,7 +448,7 @@ creates a safe interpreter:
 .DS
 .ta 1.2i 2.4i 3.6i
 \fBcd	encoding	exec	exit
-fconfigure file	glob	load
+fconfigure	file	glob	load
 open	pwd	socket	source\fR
 .DE
 These commands can be recreated later as Tcl procedures or aliases, or
@@ -487,7 +502,6 @@ management of extensions for safety see the manual entries for
 .PP
 A safe interpreter may not alter the recursion limit of any interpreter,
 including itself.
-
 .SH "ALIAS INVOCATION"
 .PP
 The alias mechanism has been carefully designed so that it can
@@ -528,7 +542,6 @@ evaluated or substituted, since this would provide an escape
 mechanism whereby the slave interpreter could execute arbitrary
 code in the master.  This in turn would compromise the security
 of the system.
-
 .VS
 .SH "HIDDEN COMMANDS"
 .PP
@@ -571,7 +584,7 @@ handling an alias invocation, great care must be taken to avoid evaluating
 any arguments passed in through the alias invocation.
 Otherwise, malicious slave interpreters could cause a trusted master
 interpreter to execute dangerous commands on their behalf. See the section
-on ALIAS INVOCATION for a more complete discussion of this topic.
+on \fBALIAS INVOCATION\fR for a more complete discussion of this topic.
 To help avoid this problem, no substitutions or evaluations are
 applied to arguments of \fBinterp invokehidden\fR.
 .PP
@@ -602,6 +615,27 @@ command, by making the current namespace be different from the global one.
 .PP
 This mechanism is based on the Safe-Tcl prototype implemented
 by Nathaniel Borenstein and Marshall Rose.
+.SH EXAMPLES
+Creating and using an alias for a command in the current interpreter:
+.CS
+\fBinterp\fR alias {} getIndex {} lsearch {alpha beta gamma delta}
+set idx [getIndex delta]
+.CE
+.PP
+Executing an arbitrary command in a safe interpreter where every
+invokation of \fBlappend\fR is logged:
+.CS
+set i [\fBinterp\fR create -safe]
+\fBinterp\fR hide $i lappend
+\fBinterp\fR alias $i lappend {} loggedLappend $i
+proc loggedLappend {i args} {
+   puts "logged invokation of lappend $args"
+   # Be extremely careful about command construction
+   eval [linsert $args 0 \\
+         \fBinterp\fR invokehidden $i lappend]
+}
+\fBinterp\fR eval $i $someUntrustedScript
+.CE
 
 .SH "SEE ALSO"
 load(n), safe(n), Tcl_CreateSlave(3)