1 files changed, 23 insertions, 33 deletions
diff --git a/doc/loadTk.n b/doc/loadTk.n
index 16e3532..bd06f44 100644
--- a/doc/loadTk.n
+++ b/doc/loadTk.n
@@ -13,7 +13,7 @@
 .SH NAME
 loadTk \- Load Tk into a safe interpreter.
 .SH SYNOPSIS
-\fB::safe::loadTk \fIslave\fR ?\fB\-use\fR \fIwindowId\fR?
+\fB::safe::loadTk \fIslave\fR ?\fB\-use\fR \fIwindowId\fR? ?\fB\-display\fR \fIdisplayName\fR? 
 .BE
 
 Safe Tk is based on Safe Tcl, which provides a mechanism 
@@ -31,9 +31,15 @@ The command returns the name of the safe interpreter.
 If \fB\-use\fR is specified, the window identified by the specified system
 dependent identifier \fIwindowId\fR is used to contain the \fB``.''\fR
 window of the safe interpreter; it can be any valid id, eventually 
-referencing a window belonging to another application.
-Otherwise, a new toplevel window is created for the \fB``.''\fR window of
-the safe interpreter.
+referencing a window belonging to another application. As a convenience,
+if the window you plan to use is a Tk Window of the application you
+can use the window name (eg: \fB.x.y\fR) instead of its window Id 
+(\fB[winfo id .x.y]\fR).
+When \fB\-use\fR is not specified,
+a new toplevel window is created for the \fB``.''\fR window of
+the safe interpreter. On X11 if you want the embedded window
+to use another display than the default one, specify it with
+\fB\-display\fR.
 See the \fBSECURITY ISSUES\fR section below for implementation details.
 
 .SH SECURITY ISSUES
@@ -41,42 +47,26 @@ See the \fBSECURITY ISSUES\fR section below for implementation details.
 Please read the \fBsafe\fR manual page for Tcl to learn about the basic
 security considerations for Safe Tcl.
 .PP
-Information in the safe interpreter should never be trusted for security
-purposes.
-However, because Tk initialization of the safe interpreter do use 
-local information, it is unsafe if the safe interpreter 
-could have gained control before Tk is loaded.
-This will be fixed in an upcoming release, by making Tk initialization in a
-safe interpreter use only information found in the interpreter's master
-instead of relying on the (un)safe interpreter state.
-.PP
-You should therefore use \fBsafe::loadTk $slave\fR as soon as possible
-after \fBsafe::interpCreate\fR and before any code is evaluated in the safe
-interpreter.
-The preferred sequence is:
-.CS
-set slave [::safe::loadTk [::safe::interpCreate]]
-.CE
-If you want to prevent safe interpreters from loading Tk entirely, you
-should create the interpreter as follows:
-.CS
-::safe::interpCreate \-nostatics \-accesspath \fI{directories...}\fR
-.CE
-and you must also insure that the virtual access path \fIdirectories\fR for
-the interpreter does not contain a dynamically loadable version of Tk.
-.PP
 \fB::safe::loadTk\fR adds the value of \fBtk_library\fR taken from the master
 interpreter to the virtual access path of the safe interpreter so that
 auto-loading will work in the safe interpreter.
-It also sets \fBenv(DISPLAY)\fR in the safe interpreter to the value of
-\fBenv(DISPLAY)\fR in the master interpreter, if it exists.
-Finally, it sets the slave's Tcl variable \fBargv\fR to \fB\-use\fR 
-\fIwindowId\fR in the safe interpreter.
-
+.PP
+.PP
+Tk initialization is now safe with respect to not trusting
+the slave's state for startup. \fB::safe::loadTk\fR
+registers the slave's name so
+when the Tk initialization (\fBTk_SafeInit\fR) is called
+and in turn calls the master's \fB::safe::InitTk\fR it will
+return the desired \fBargv\fR equivalent (\fB\-use\fR 
+\fIwindowId\fR, correct \fB\-display\fR, etc...).
+.PP
 When \fB\-use\fR is not used, the new toplevel created is specially
 decorated so the user is always aware that the user interface presented comes
 from a potentially unsafe code and can easily delete the corresponding
 interpreter.
+.PP
+On X11, conflicting \fB\-use\fR and \fB\-display\fR are likely
+to generate a fatal X error.
 
 .SH "SEE ALSO"
 safe(n), interp(n), library(n), load(n), package(n), source(n), unknown(n)