aboutsummaryrefslogtreecommitdiffstats
path: root/contrib/tcl/doc
diff options
context:
space:
mode:
authorPoul-Henning Kamp <phk@FreeBSD.org>1997-10-01 13:19:13 +0000
committerPoul-Henning Kamp <phk@FreeBSD.org>1997-10-01 13:19:13 +0000
commit539e1e66ff6f99c987c8e03872ddaea5260db8f7 (patch)
treebca582e352640f318b35228d0c250ddde3bd0e0b /contrib/tcl/doc
parent3d33409926539d866dcea9fc5cb14113b312adf0 (diff)
downloadsrc-539e1e66ff6f99c987c8e03872ddaea5260db8f7.tar.gz
src-539e1e66ff6f99c987c8e03872ddaea5260db8f7.zip
Upgrade to 8.0 release.
Notes
Notes: svn path=/vendor/tcl/dist/; revision=30037
Diffstat (limited to 'contrib/tcl/doc')
-rw-r--r--contrib/tcl/doc/CrtInterp.36
-rw-r--r--contrib/tcl/doc/CrtObjCmd.311
-rw-r--r--contrib/tcl/doc/CrtSlave.326
-rw-r--r--contrib/tcl/doc/GetIndex.35
-rw-r--r--contrib/tcl/doc/Object.34
-rw-r--r--contrib/tcl/doc/RecEvalObj.355
-rw-r--r--contrib/tcl/doc/RecordEval.314
-rw-r--r--contrib/tcl/doc/WrongNumArgs.328
-rw-r--r--contrib/tcl/doc/bgerror.n7
-rw-r--r--contrib/tcl/doc/expr.n6
-rw-r--r--contrib/tcl/doc/history.n106
-rw-r--r--contrib/tcl/doc/http.n109
-rw-r--r--contrib/tcl/doc/interp.n62
-rw-r--r--contrib/tcl/doc/namespace.n290
-rw-r--r--contrib/tcl/doc/registry.n10
-rw-r--r--contrib/tcl/doc/rename.n16
-rw-r--r--contrib/tcl/doc/resource.n116
-rw-r--r--contrib/tcl/doc/safe.n529
-rw-r--r--contrib/tcl/doc/tclvars.n80
-rw-r--r--contrib/tcl/doc/uplevel.n20
-rw-r--r--contrib/tcl/doc/upvar.n20
-rw-r--r--contrib/tcl/doc/variable.n20
22 files changed, 857 insertions, 683 deletions
diff --git a/contrib/tcl/doc/CrtInterp.3 b/contrib/tcl/doc/CrtInterp.3
index b50d34e5bae1..bcca39d5def5 100644
--- a/contrib/tcl/doc/CrtInterp.3
+++ b/contrib/tcl/doc/CrtInterp.3
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) CrtInterp.3 1.14 96/03/26 15:14:45
+'\" SCCS: @(#) CrtInterp.3 1.15 97/07/09 14:53:31
'\"
.so man.macros
.TH Tcl_CreateInterp 3 7.5 Tcl "Tcl Library Procedures"
@@ -100,8 +100,8 @@ When a new interpreter is created and used in a call to \fBTcl_Eval\fR,
\fBTcl_Release\fR should be wrapped around all uses of the interpreter.
Remember that it is unsafe to use the interpreter once \fBTcl_Release\fR
has been called. To ensure that the interpreter is properly deleted when
-it is no longer needed, call \fBTcl_InterpDeleted\fB to test if some other
-code already called \fBTcl_DeleteInterp\fB; if not, call
+it is no longer needed, call \fBTcl_InterpDeleted\fR to test if some other
+code already called \fBTcl_DeleteInterp\fR; if not, call
\fBTcl_DeleteInterp\fR before calling \fBTcl_Release\fB in your own code.
Do not call \fBTcl_DeleteInterp\fR on an interpreter for which
\fBTcl_InterpDeleted\fR returns nonzero.
diff --git a/contrib/tcl/doc/CrtObjCmd.3 b/contrib/tcl/doc/CrtObjCmd.3
index e5108894eeea..78fe6f8b7322 100644
--- a/contrib/tcl/doc/CrtObjCmd.3
+++ b/contrib/tcl/doc/CrtObjCmd.3
@@ -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.
'\"
-'\" SCCS: @(#) @(#) CrtObjCmd.3 1.9 97/06/04 17:23:37
+'\" SCCS: @(#) @(#) CrtObjCmd.3 1.10 97/07/31 14:10:38
'\"
.so man.macros
.TH Tcl_CreateObjCommand 3 8.0 Tcl "Tcl Library Procedures"
@@ -54,7 +54,6 @@ The command must not have been deleted.
Pointer to structure containing various information about a
Tcl command.
.BE
-
.SH DESCRIPTION
.PP
\fBTcl_CreateObjCommand\fR defines a new command in \fIinterp\fR
@@ -130,8 +129,8 @@ Call \fBTcl_SetObjResult\fR if you want
to return something from the \fIobjv\fR array.
.PP
\fIDeleteProc\fR will be invoked when (if) \fIname\fR is deleted.
-This can occur through a call to \fBTcl_DeleteCommand\fR
-or \fBTcl_DeleteInterp\fR,
+This can occur through a call to \fBTcl_DeleteCommand\fR,
+\fBTcl_DeleteCommandFromToken\fR, or \fBTcl_DeleteInterp\fR,
or by replacing \fIname\fR in another call to \fBTcl_CreateObjCommand\fR.
\fIDeleteProc\fR is invoked before the command is deleted, and gives the
application an opportunity to release any structures associated
@@ -154,10 +153,10 @@ a built-in command, an application-specific command, or a Tcl procedure.
If \fIname\fR contains any \fB::\fR namespace qualifiers,
the command is deleted from the specified namespace.
.PP
-Given a token returned by \fBTcl_CreateObjCommand\fR
-when the command was created,
+Given a token returned by \fBTcl_CreateObjCommand\fR,
\fBTcl_DeleteCommandFromToken\fR deletes the command
from a command interpreter.
+It will delete a command even if that command has been renamed.
Once the call completes, attempts to invoke the command in
\fIinterp\fR will result in errors.
If the command corresponding to \fItoken\fR
diff --git a/contrib/tcl/doc/CrtSlave.3 b/contrib/tcl/doc/CrtSlave.3
index 3b3d7b82f4b9..fe18a557e472 100644
--- a/contrib/tcl/doc/CrtSlave.3
+++ b/contrib/tcl/doc/CrtSlave.3
@@ -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.
'\"
-'\" SCCS: @(#) CrtSlave.3 1.22 97/06/10 17:52:33
+'\" SCCS: @(#) CrtSlave.3 1.26 97/07/31 18:00:14
'\"
.so man.macros
.TH Tcl_CreateSlave 3 7.6 Tcl "Tcl Library Procedures"
@@ -107,7 +107,8 @@ called function.
.AP char *cmdName in
Name of an exposed command to hide or create.
.AP char *hiddenCmdName in
-Name of a hidden command to create or expose.
+Name under which a hidden command is stored and with which it can be
+exposed or invoked.
.VE
.BE
@@ -187,9 +188,11 @@ returns a pointer to a vector of Tcl_Obj structures instead of a vector of
strings.
.PP
\fBTcl_ExposeCommand\fR moves the command named \fIhiddenCmdName\fR from
-the set of hidden commands to the set of exposed commands, renaming it to
-\fIcmdName\fR. \fIHiddenCmdName\fR must be the name of an existing hidden
-command, or the operation will return \fBTCL_ERROR\fR and deposit an error
+the set of hidden commands to the set of exposed commands, putting
+it under the name
+\fIcmdName\fR.
+\fIHiddenCmdName\fR must be the name of an existing hidden
+command, or the operation will return \fBTCL_ERROR\fR and leave an error
message in the \fIresult\fR field in \fIinterp\fR.
If an exposed command named \fIcmdName\fR already exists,
the operation returns \fBTCL_ERROR\fR and leaves an error message in the
@@ -199,11 +202,18 @@ After executing this command, attempts to use \fIcmdName\fR in a call to
\fBTcl_Eval\fR or with the Tcl \fBeval\fR command will again succeed.
.PP
\fBTcl_HideCommand\fR moves the command named \fIcmdName\fR from the set of
-exposed commands to the set of hidden commands, renaming it to
-\fIhiddenCmdName\fR. \fICmdName\fR must be the name of an existing exposed
+exposed commands to the set of hidden commands, under the name
+\fIhiddenCmdName\fR.
+\fICmdName\fR must be the name of an existing exposed
command, or the operation will return \fBTCL_ERROR\fR and leave an error
message in the object result of \fIinterp\fR.
-If a hidden command named \fIhiddenCmdName\fR already
+Currently both \fIcmdName\fR and \fIhiddenCmdName\fR must not contain
+namespace qualifiers, or the operation will return \fBTCL_ERROR\fR and
+leave an error message in the object result of \fIinterp\fR.
+The \fICmdName\fR will be looked up in the global namespace, and not
+relative to the current namespace, even if the current namespace is not the
+global one.
+If a hidden command whose name is \fIhiddenCmdName\fR already
exists, the operation also returns \fBTCL_ERROR\fR and the \fIresult\fR
field in \fIinterp\fR contains an error message.
If the operation succeeds, it returns \fBTCL_OK\fR.
diff --git a/contrib/tcl/doc/GetIndex.3 b/contrib/tcl/doc/GetIndex.3
index 66782576e2f8..9ca7927836ce 100644
--- a/contrib/tcl/doc/GetIndex.3
+++ b/contrib/tcl/doc/GetIndex.3
@@ -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.
'\"
-'\" SCCS: @(#) @(#) GetIndex.3 1.2 97/02/11 13:25:45
+'\" SCCS: @(#) @(#) GetIndex.3 1.3 97/07/30 16:21:05
'\"
.so man.macros
.TH Tcl_GetIndexFromObj 3 8.0 Tcl "Tcl Library Procedures"
@@ -70,5 +70,8 @@ the matching index immediately without having to redo the lookup
operation. Note: \fBTcl_GetIndexFromObj\fR assumes that the entries
in \fItablePtr\fR are static: they must not change between invocations.
+.SH "SEE ALSO"
+Tcl_WrongNumArgs
+
.SH KEYWORDS
index, object, table lookup
diff --git a/contrib/tcl/doc/Object.3 b/contrib/tcl/doc/Object.3
index e564de9cd907..1fed7a6b7aaf 100644
--- a/contrib/tcl/doc/Object.3
+++ b/contrib/tcl/doc/Object.3
@@ -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.
'\"
-'\" SCCS: @(#) @(#) Object.3 1.9 97/06/13 18:36:20
+'\" SCCS: @(#) @(#) Object.3 1.10 97/07/22 11:40:10
'\"
.so man.macros
.TH Tcl_Obj 3 8.0 Tcl "Tcl Library Procedures"
@@ -309,7 +309,7 @@ by calling \fBTcl_IsShared\fR.
If the object is shared they must copy the object
by using \fBTcl_DuplicateObj\fR;
this returns a new duplicate of the original object
-that has \fIrefCount\fR 1.
+that has \fIrefCount\fR 0.
If the object is not shared,
the command procedure "owns" the object and can safely modify it directly.
For example, the following code appears in the command procedure
diff --git a/contrib/tcl/doc/RecEvalObj.3 b/contrib/tcl/doc/RecEvalObj.3
new file mode 100644
index 000000000000..7f3bdc9d7238
--- /dev/null
+++ b/contrib/tcl/doc/RecEvalObj.3
@@ -0,0 +1,55 @@
+'\"
+'\" Copyright (c) 1997 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+'\" SCCS: SCCS: @(#) RecEvalObj.3 1.1 97/07/29 18:31:21
+'\"
+.so man.macros
+.TH Tcl_RecordAndEvalObj 3 8.0 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_RecordAndEvalObj \- save command on history list before evaluating
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+int
+\fBTcl_RecordAndEvalObj\fR(\fIinterp, cmdPtr, flags\fR)
+.SH ARGUMENTS
+.AS Tcl_Interp *interp;
+.AP Tcl_Interp *interp in
+Tcl interpreter in which to evaluate command.
+.AP Tcl_Obj *cmdPtr in
+Points to a Tcl object containing a command (or sequence of commands)
+to execute.
+.AP int flags in
+An OR'ed combination of flag bits. TCL_NO_EVAL means record the
+command but don't evaluate it. TCL_EVAL_GLOBAL means evaluate
+the command at global level instead of the current stack level.
+.BE
+
+.SH DESCRIPTION
+.PP
+\fBTcl_RecordAndEvalObj\fR is invoked to record a command as an event
+on the history list and then execute it using \fBTcl_EvalObj\fR
+(or \fBTcl_GlobalEvalObj\fR if the TCL_EVAL_GLOBAL bit is set
+in \fIflags\fR).
+It returns a completion code such as TCL_OK just like \fBTcl_EvalObj\fR,
+as well as a result object containing additional information
+(a result value or error message)
+that can be retrieved using \fBTcl_GetObjResult\fR.
+If you don't want the command recorded on the history list then
+you should invoke \fBTcl_EvalObj\fR instead of \fBTcl_RecordAndEvalObj\fR.
+Normally \fBTcl_RecordAndEvalObj\fR is only called with top-level
+commands typed by the user, since the purpose of history is to
+allow the user to re-issue recently-invoked commands.
+If the \fIflags\fR argument contains the TCL_NO_EVAL bit then
+the command is recorded without being evaluated.
+
+.SH "SEE ALSO"
+Tcl_EvalObj, Tcl_GetObjResult
+
+.SH KEYWORDS
+command, event, execute, history, interpreter, object, record
diff --git a/contrib/tcl/doc/RecordEval.3 b/contrib/tcl/doc/RecordEval.3
index 6e6fb27e67dd..17d353dc8b6c 100644
--- a/contrib/tcl/doc/RecordEval.3
+++ b/contrib/tcl/doc/RecordEval.3
@@ -1,11 +1,11 @@
'\"
'\" Copyright (c) 1989-1993 The Regents of the University of California.
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) RecordEval.3 1.17 96/08/26 12:59:47
+'\" SCCS: @(#) RecordEval.3 1.18 97/07/29 18:25:13
'\"
.so man.macros
.TH Tcl_RecordAndEval 3 7.4 Tcl "Tcl Library Procedures"
@@ -17,7 +17,7 @@ Tcl_RecordAndEval \- save command on history list before evaluating
\fB#include <tcl.h>\fR
.sp
int
-\fBTcl_RecordAndEval\fR(\fIinterp, cmd, eval\fR)
+\fBTcl_RecordAndEval\fR(\fIinterp, cmd, flags\fR)
.SH ARGUMENTS
.AS Tcl_Interp *interp;
.AP Tcl_Interp *interp in
@@ -44,6 +44,14 @@ commands typed by the user, since the purpose of history is to
allow the user to re-issue recently-invoked commands.
If the \fIflags\fR argument contains the TCL_NO_EVAL bit then
the command is recorded without being evaluated.
+.PP
+Note that \fBTcl_RecordAndEval\fR has been largely replaced by the
+object-based procedure \fBTcl_RecordAndEvalObj\fR.
+That object-based procedure records and optionally executes
+a command held in a Tcl object instead of a string.
+
+.SH "SEE ALSO"
+Tcl_RecordAndEvalObj
.SH KEYWORDS
command, event, execute, history, interpreter, record
diff --git a/contrib/tcl/doc/WrongNumArgs.3 b/contrib/tcl/doc/WrongNumArgs.3
index 528ebc827511..61b68cefcc3a 100644
--- a/contrib/tcl/doc/WrongNumArgs.3
+++ b/contrib/tcl/doc/WrongNumArgs.3
@@ -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.
'\"
-'\" SCCS: @(#) @(#) WrongNumArgs.3 1.3 97/03/18 11:53:25
+'\" SCCS: @(#) @(#) WrongNumArgs.3 1.5 97/07/30 16:20:07
'\"
.so man.macros
.TH Tcl_WrongNumArgs 3 8.0 Tcl "Tcl Library Procedures"
@@ -30,7 +30,7 @@ Arguments to command that had the wrong number of arguments.
.AP char *message in
Additional error information to print after leading arguments
from \fIobjv\fR. This typically gives the acceptable syntax
-of the command.
+of the command. This argument may be NULL.
.BE
.SH DESCRIPTION
@@ -52,8 +52,28 @@ If \fIobjc\fR is 2, the result will be set to the following string:
.CS
wrong # args: should be "foo bar fileName count"
.CE
-\fIObjc\fR is usually 1, but may be 2 or more for commands like \fBstring\fR
-and the Tk widget commands, which use the first argument as a subcommand.
+\fIObjc\fR is usually 1, but may be 2 or more for commands like
+\fBstring\fR and the Tk widget commands, which use the first argument
+as a subcommand.
+.PP
+Some of the objects in the \fIobjv\fR array may be abbreviations for
+a subcommand. The command
+\fBTcl_GetIndexFromObj\fR will convert the abbreviated string object
+into an \fIindexObject\fR. If an error occurs in the parsing of the
+subcommand we would like to use the full subcommand name rather than
+the abbreviation. If the \fBTcl_WrongNumArgs\fR command finds any
+\fIindexObjects\fR in the \fIobjv\fR array it will use the full subcommand
+name in the error message instead of the abbreviated name that was
+origionally passed in. Using the above example, lets assume that
+\fIbar\fR is actually an abbreviation for \fIbarfly\fR and the object
+is now an indexObject becasue it was passed to
+\fBTcl_GetIndexFromObj\fR. In this case the error message would be:
+.CS
+wrong # args: should be "foo barfly fileName count"
+.CE
+
+.SH "SEE ALSO"
+Tcl_GetIndexFromObj
.SH KEYWORDS
command, error message, wrong number of arguments
diff --git a/contrib/tcl/doc/bgerror.n b/contrib/tcl/doc/bgerror.n
index 6875bcf819a9..9f3e0c1f1c9d 100644
--- a/contrib/tcl/doc/bgerror.n
+++ b/contrib/tcl/doc/bgerror.n
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) bgerror.n 1.3 96/03/25 20:10:12
+'\" SCCS: @(#) bgerror.n 1.5 97/08/04 17:49:35
'\"
.so man.macros
.TH bgerror n 7.5 Tcl "Tcl Built-In Commands"
@@ -58,8 +58,9 @@ However, if \fBbgerror\fR returns with a break exception, then
any remaining errors are skipped without calling \fBbgerror\fR.
.PP
Tcl has no default implementation for \fBbgerror\fR.
-However, in applications using Tk there will be a default
-\fBbgerror\fR procedure that posts a dialog box containing
+However, in applications using Tk there is a default
+\fBbgerror\fR procedure
+which posts a dialog box containing
the error message and offers the user a chance to see a stack
trace showing where the error occurred.
diff --git a/contrib/tcl/doc/expr.n b/contrib/tcl/doc/expr.n
index e7dda17681fd..f4532cc18a7a 100644
--- a/contrib/tcl/doc/expr.n
+++ b/contrib/tcl/doc/expr.n
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) expr.n 1.25 97/04/29 10:11:52
+'\" SCCS: @(#) expr.n 1.27 97/08/12 11:31:30
'\"
.so man.macros
.TH expr n 8.0 Tcl "Tcl Built-In Commands"
@@ -285,6 +285,7 @@ operands could be arbitrary; it's better in these cases to use the
\fBstring compare\fR command instead.
.SH "PERFORMANCE CONSIDERATIONS"
+.VS
.PP
Enclose expressions in braces for the best speed and the smallest
storage requirements.
@@ -315,6 +316,7 @@ The most expensive code is required for
unbraced expressions that contain command substitutions.
These expressions must be implemented by generating new code
each time the expression is executed.
+.VE
.SH KEYWORDS
-arithmetic, boolean, compare, expression
+arithmetic, boolean, compare, expression, fuzzy comparison
diff --git a/contrib/tcl/doc/history.n b/contrib/tcl/doc/history.n
index a93e2fd0c227..e58ea3a770ed 100644
--- a/contrib/tcl/doc/history.n
+++ b/contrib/tcl/doc/history.n
@@ -1,11 +1,11 @@
'\"
'\" Copyright (c) 1993 The Regents of the University of California.
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) history.n 1.6 96/03/25 20:16:25
+'\" SCCS: @(#) history.n 1.11 97/08/07 16:44:49
'\"
.so man.macros
.TH history n "" Tcl "Tcl Built-In Commands"
@@ -29,7 +29,7 @@ A number: if positive, it refers to the event with
that number (all events are numbered starting at 1). If the number
is negative, it selects an event relative to the current event
(\fB\-1\fR refers to the previous event, \fB\-2\fR to the one before that, and
-so on).
+so on). Event \fB0\fP refers to the current event.
.IP [2]
A string: selects the most recent event that matches the string.
An event is considered to match the string either if the string is
@@ -57,10 +57,13 @@ substitution and wish to replace the current event (which invokes the
substitution) with the command created through substitution. The return
value is an empty string.
.TP
+\fBhistory clear\fR
+Erase the history list. The current keep limit is retained.
+The history event numbers are reset.
+.TP
\fBhistory event\fR ?\fIevent\fR?
Returns the value of the event given by \fIevent\fR. \fIEvent\fR
-defaults to \fB\-1\fR. This command causes history revision to occur:
-see below for details.
+defaults to \fB\-1\fR.
.TP
\fBhistory info \fR?\fIcount\fR?
Returns a formatted string (intended for humans to read) giving
@@ -68,10 +71,10 @@ the event number and contents for each of the events in the history
list except the current event. If \fIcount\fR is specified
then only the most recent \fIcount\fR events are returned.
.TP
-\fBhistory keep \fIcount\fR
+\fBhistory keep \fR?\fIcount\fR?
This command may be used to change the size of the history list to
\fIcount\fR events. Initially, 20 events are retained in the history
-list. This command returns an empty string.
+list. If \fIcount\fR is not specified, the current keep limit is returned.
.TP
\fBhistory nextid\fR
Returns the number of the next event to be recorded
@@ -82,87 +85,20 @@ event number in command-line prompts.
Re-executes the command indicated by \fIevent\fR and return its result.
\fIEvent\fR defaults to \fB\-1\fR. This command results in history
revision: see below for details.
-.TP
-\fBhistory substitute \fIold new \fR?\fIevent\fR?
-Retrieves the command given by \fIevent\fR
-(\fB\-1\fR by default), replace any occurrences of \fIold\fR by
-\fInew\fR in the command (only simple character equality is supported;
-no wild cards), execute the resulting command, and return the result
-of that execution. This command results in history
-revision: see below for details.
-.TP
-\fBhistory words \fIselector\fR ?\fIevent\fR?
-Retrieves from the command given by \fIevent\fR (\fB\-1\fR by default)
-the words given by \fIselector\fR, and return those words in a string
-separated by spaces. The \fBselector\fR argument has three forms.
-If it is a single number then it selects the word given by that
-number (\fB0\fR for the command name, \fB1\fR for its first argument,
-and so on). If it consists of two numbers separated by a dash,
-then it selects all the arguments between those two. Otherwise
-\fBselector\fR is treated as a pattern; all words matching that
-pattern (in the sense of \fBstring match\fR) are returned. In
-the numeric forms \fB$\fR may be used
-to select the last word of a command.
-For example, suppose the most recent command in the history list is
-.RS
-.CS
-\fBformat {%s is %d years old} Alice [expr $ageInMonths/12]\fR
-.CE
-Below are some history commands and the results they would produce:
-.DS
-.ta 4c
-.fi
-.UL Command " "
-.UL Result
-.nf
-
-\fBhistory words $ [expr $ageInMonths/12]\fR
-\fBhistory words 1-2 {%s is %d years old} Alice\fR
-\fBhistory words *a*o* {%s is %d years old} [expr $ageInMonths/12]\fR
-.DE
-\fBHistory words\fR results in history revision: see below for details.
-.RE
.SH "HISTORY REVISION"
.PP
-The history options \fBevent\fR, \fBredo\fR, \fBsubstitute\fR,
-and \fBwords\fR result in ``history revision''.
-When one of these options is invoked then the current event
+Pre-8.0 Tcl had a complex history revision mechanism.
+The current mechanism is more limited, and the old
+history operations \fBsubstitute\fP and \fBwords\fP have been removed.
+(As a consolation, the \fBclear\fP operation was added.)
+.PP
+The history option \fBredo\fR results in much simpler ``history revision''.
+When this option is invoked then the most recent event
is modified to eliminate the history command and replace it with
the result of the history command.
-For example, suppose that the most recent command in the history
-list is
-.CS
-\fBset a [expr $b+2]\fR
-.CE
-and suppose that the next command invoked is one of the ones on
-the left side of the table below. The command actually recorded in
-the history event will be the corresponding one on the right side
-of the table.
-.ne 1.5c
-.DS
-.ta 4c
-.fi
-.UL "Command Typed" " "
-.UL "Command Recorded"
-.nf
-
-\fBhistory redo set a [expr $b+2]\fR
-\fBhistory s a b set b [expr $b+2]\fR
-\fBset c [history w 2] set c [expr $b+2]\fR
-.DE
-History revision is needed because event specifiers like \fB\-1\fR
-are only valid at a particular time: once more events have been
-added to the history list a different event specifier would be
-needed.
-History revision occurs even when \fBhistory\fR is invoked
-indirectly from the current event (e.g. a user types a command
-that invokes a Tcl procedure that invokes \fBhistory\fR): the
-top-level command whose execution eventually resulted in a
-\fBhistory\fR command is replaced.
-If you wish to invoke commands like \fBhistory words\fR without
-history revision, you can use \fBhistory event\fR to save the
-current history event and then use \fBhistory change\fR to
-restore it later.
+If you want to redo an event without modifying history, then use
+the \fBevent\fP operation to retrieve some event,
+and the \fBadd\fP operation to add it to history and execute it.
.SH KEYWORDS
-event, history, record, revision
+event, history, record
diff --git a/contrib/tcl/doc/http.n b/contrib/tcl/doc/http.n
index 5a5b2d28b246..36227ce9d354 100644
--- a/contrib/tcl/doc/http.n
+++ b/contrib/tcl/doc/http.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.
'\"
-'\" SCCS: @(#) http.n 1.10 97/06/24 17:15:09
+'\" SCCS: @(#) http.n 1.11 97/08/07 16:45:02
'\"
.so man.macros
.TH "Http" n 8.0 Tcl "Tcl Built-In Commands"
@@ -13,25 +13,25 @@
.SH NAME
Http \- Client-side implementation of the HTTP/1.0 protocol.
.SH SYNOPSIS
-\fBpackage require http ?1.0?\fP
+\fBpackage require http ?2.0?\fP
.sp
-\fBhttp_config \fI?options?\fR
+\fB::http::config \fI?options?\fR
.sp
-\fBhttp_get \fIurl ?options?\fR
+\fB::http::geturl \fIurl ?options?\fR
.sp
-\fBhttp_formatQuery \fIlist\fR
+\fB::http::formatQuery \fIlist\fR
.sp
-\fBhttp_reset \fItoken\fR
+\fB::http::reset \fItoken\fR
.sp
-\fBhttp_wait \fItoken\fR
+\fB::http::wait \fItoken\fR
.sp
-\fBhttp_status \fItoken\fR
+\fB::http::status \fItoken\fR
.sp
-\fBhttp_size \fItoken\fR
+\fB::http::size \fItoken\fR
.sp
-\fBhttp_code \fItoken\fR
+\fB::http::code \fItoken\fR
.sp
-\fBhttp_data \fItoken\fR
+\fB::http::data \fItoken\fR
.BE
.SH DESCRIPTION
@@ -43,26 +43,27 @@ firewalls. The package is compatible with the \fBSafesock\fR security
policy, so it can be used by untrusted applets to do URL fetching from
a restricted set of hosts.
.PP
-The \fBhttp_get\fR procedure does a HTTP transaction.
+The \fB::http::geturl\fR procedure does a HTTP transaction.
Its \fIoptions \fR determine whether a GET, POST, or HEAD transaction
is performed.
-The return value of \fBhttp_get\fR is a token for the transaction.
-The value is also the name of a global array that contains state
+The return value of \fB::http::geturl\fR is a token for the transaction.
+The value is also the name of an array in the ::http namespace
+ that contains state
information about the transaction. The elements of this array are
described in the STATE ARRAY section.
.PP
If the \fB-command\fP option is specified, then
the HTTP operation is done in the background.
-\fBhttp_get\fR returns immediately after generating the
+\fB::http::geturl\fR returns immediately after generating the
HTTP request and the callback is invoked
when the transaction completes. For this to work, the Tcl event loop
must be active. In Tk applications this is always true. For pure-Tcl
-applications, the caller can use \fBhttp_wait\fR after calling
-\fBhttp_get\fR to start the event loop.
+applications, the caller can use \fB::http::wait\fR after calling
+\fB::http::geturl\fR to start the event loop.
.SH COMMANDS
.TP
-\fBhttp_config\fP ?\fIoptions\fR?
-The \fBhttp_config\fR command is used to set and query the name of the
+\fB::http::config\fP ?\fIoptions\fR?
+The \fB::http::config\fR command is used to set and query the name of the
proxy server and port, and the User-Agent name used in the HTTP
requests. If no options are specified, then the current configuration
is returned. If a single argument is specified, then it should be one
@@ -86,7 +87,7 @@ The proxy port number.
.TP
\fB\-proxyfilter\fP \fIcommand\fP
The command is a callback that is made during
-\fBhttp_get\fR
+\fB::http::geturl\fR
to determine if a proxy is required for a given host. One argument, a
host name, is added to \fIcommand\fR when it is invoked. If a proxy
is required, the callback should return a two element list containing
@@ -97,20 +98,20 @@ non-empty.
.TP
\fB\-useragent\fP \fIstring\fP
The value of the User-Agent header in the HTTP request. The default
-is \fB"Tcl http client package 1.0."\fR
+is \fB"Tcl http client package 2.0."\fR
.RE
.TP
-\fBhttp_get\fP \fIurl\fP ?\fIoptions\fP?
-The \fBhttp_get \fR command is the main procedure in the package.
+\fB::http::geturl\fP \fIurl\fP ?\fIoptions\fP?
+The \fB::http::geturl \fR command is the main procedure in the package.
The \fB\-query\fR option causes a POST operation and
the \fB\-validate\fR option causes a HEAD operation;
-otherwise, a GET operation is performed. The \fBhttp_get\fR command
+otherwise, a GET operation is performed. The \fB::http::geturl\fR command
returns a \fItoken\fR value that can be used to get
information about the transaction. See the STATE ARRAY section for
-details. The \fBhttp_get\fR command blocks until the operation
+details. The \fB::http::geturl\fR command blocks until the operation
completes, unless the \fB\-command\fR option specifies a callback
that is invoked when the HTTP transaction completes.
-\fBhttp_get\fR takes several options:
+\fB::http::geturl\fR takes several options:
.RS
.TP
\fB\-blocksize\fP \fIsize\fP
@@ -127,9 +128,9 @@ Copy the URL contents to channel \fIname\fR instead of saving it in
.TP
\fB\-command\fP \fIcallback\fP
Invoke \fIcallback\fP after the HTTP transaction completes.
-This option causes \fBhttp_get\fP to return immediately.
+This option causes \fB::http::geturl\fP to return immediately.
The \fIcallback\fP gets an additional argument that is the \fItoken\fR returned
-from \fBhttp_get\fR. This token is the name of a global array that is
+from \fB::http::geturl\fR. This token is the name of an array that is
described in the STATE ARRAY section. Here is a template for the
callback:
.RS
@@ -145,7 +146,7 @@ proc httpCallback {token} {
Invoke \fIcallback\fP whenever HTTP data is available; if present, nothing
else will be done with the HTTP data. This procedure gets two additional
arguments: the socket for the HTTP data and the \fItoken\fR returned from
-\fBhttp_get\fR. The token is the name of a global array that is described
+\fB::http::geturl\fR. The token is the name of a global array that is described
in the STATE ARRAY section. The procedure is expected to return the number
of bytes read from the socket. Here is a template for the callback:
.RS
@@ -176,7 +177,7 @@ Pragma: no-cache
\fB\-progress\fP \fIcallback\fP
The \fIcallback\fR is made after each transfer of data from the URL.
The callback gets three additional arguments: the \fItoken\fR from
-\fBhttp_get\fR, the expected total size of the contents from the
+\fB::http::geturl\fR, the expected total size of the contents from the
\fBContent-Length\fR meta-data, and the current number of bytes
transferred so far. The expected total size may be unknown, in which
case zero is passed to the callback. Here is a template for the
@@ -190,60 +191,60 @@ proc httpProgress {token total current} {
.RE
.TP
\fB\-query\fP \fIquery\fP
-This flag causes \fBhttp_get\fR to do a POST request that passes the
+This flag causes \fB::http::geturl\fR to do a POST request that passes the
\fIquery\fR to the server. The \fIquery\fR must be a x-url-encoding
-formatted query. The \fBhttp_formatQuery\fR procedure can be used to
+formatted query. The \fB::http::formatQuery\fR procedure can be used to
do the formatting.
.TP
\fB\-timeout\fP \fImilliseconds\fP
-If \fImilliseconds\fR is non-zero, then \fBhttp_get\fR sets up a timeout
+If \fImilliseconds\fR is non-zero, then \fB::http::geturl\fR sets up a timeout
to occur after the specified number of milliseconds.
-A timeout results in a call to \fBhttp_reset\fP and to
+A timeout results in a call to \fB::http::reset\fP and to
the \fB-command\fP callback, if specified.
-The return value of \fBhttp_status\fP is \fBtimeout\fP
+The return value of \fB::http::status\fP is \fBtimeout\fP
after a timeout has occurred.
.TP
\fB\-validate\fP \fIboolean\fP
-If \fIboolean\fR is non-zero, then \fBhttp_get\fR does an HTTP HEAD
+If \fIboolean\fR is non-zero, then \fB::http::geturl\fR does an HTTP HEAD
request. This request returns meta information about the URL, but the
contents are not returned. The meta information is available in the
\fBstate(meta) \fR variable after the transaction. See the STATE
ARRAY section for details.
.RE
.TP
-\fBhttp_formatQuery\fP \fIkey value\fP ?\fIkey value\fP ...?
+\fB::http::formatQuery\fP \fIkey value\fP ?\fIkey value\fP ...?
This procedure does x-url-encoding of query data. It takes an even
number of arguments that are the keys and values of the query. It
encodes the keys and values, and generates one string that has the
proper & and = separators. The result is suitable for the
-\fB\-query\fR value passed to \fBhttp_get\fR.
+\fB\-query\fR value passed to \fB::http::geturl\fR.
.TP
-\fBhttp_reset\fP \fItoken\fP ?\fIwhy\fP?
+\fB::http::reset\fP \fItoken\fP ?\fIwhy\fP?
This command resets the HTTP transaction identified by \fItoken\fR, if
any. This sets the \fBstate(status)\fP value to \fIwhy\fP, which defaults to \fBreset\fR, and then calls the registered \fB\-command\fR callback.
.TP
-\fBhttp_wait\fP \fItoken\fP
+\fB::http::wait\fP \fItoken\fP
This is a convenience procedure that blocks and waits for the
transaction to complete. This only works in trusted code because it
uses \fBvwait\fR.
.TP
-\fBhttp_data\fP \fItoken\fP
+\fB::http::data\fP \fItoken\fP
This is a convenience procedure that returns the \fBbody\fP element
(i.e., the URL data) of the state array.
.TP
-\fBhttp_status\fP \fItoken\fP
+\fB::http::status\fP \fItoken\fP
This is a convenience procedure that returns the \fBstatus\fP element of
the state array.
.TP
-\fBhttp_code\fP \fItoken\fP
+\fB::http::code\fP \fItoken\fP
This is a convenience procedure that returns the \fBhttp\fP element of the
state array.
.TP
-\fBhttp_size\fP \fItoken\fP
+\fB::http::size\fP \fItoken\fP
This is a convenience procedure that returns the \fBcurrentsize\fP
element of the state array.
.SH "STATE ARRAY"
-The \fBhttp_get\fR procedure returns a \fItoken\fR that can be used to
+The \fB::http::geturl\fR procedure returns a \fItoken\fR that can be used to
get to the state of the HTTP transaction in the form of a Tcl array.
Use this construct to create an easy-to-use array variable:
.CS
@@ -254,11 +255,11 @@ The following elements of the array are supported:
.TP
\fBbody\fR
The contents of the URL. This will be empty if the \fB\-channel\fR
-option has been specified. This value is returned by the \fBhttp_data\fP command.
+option has been specified. This value is returned by the \fB::http::data\fP command.
.TP
\fBcurrentsize\fR
The current number of bytes fetched from the URL.
-This value is returned by the \fBhttp_size\fP command.
+This value is returned by the \fB::http::size\fP command.
.TP
\fBerror\fR
If defined, this is the error string seen when the HTTP transaction
@@ -266,7 +267,7 @@ was aborted.
.TP
\fBhttp\fR
The HTTP status reply from the server. This value
-is returned by the \fBhttp_code\fP command. The format of this value is:
+is returned by the \fB::http::code\fP command. The format of this value is:
.RS
.CS
\fIcode string\fP
@@ -297,7 +298,7 @@ The type of the URL contents. Examples include \fBtext/html\fR,
.TP
\fBContent-Length\fR
The advertised size of the contents. The actual size obtained by
-\fBhttp_get\fR is available as \fBstate(size)\fR.
+\fB::http::geturl\fR is available as \fBstate(size)\fR.
.TP
\fBLocation\fR
An alternate URL that contains the requested data.
@@ -320,12 +321,12 @@ The requested URL.
.SH EXAMPLE
.DS
# Copy a URL to a file and print meta-data
-proc Http_Copy { url file {chunk 4096} } {
+proc ::http::copy { url file {chunk 4096} } {
set out [open $file w]
- set token [http_get $url -channel $out -progress HttpProgress \\
+ set token [geturl $url -channel $out -progress ::http::Progress \\
-blocksize $chunk]
close $out
- # This ends the line started by HttpProgress
+ # This ends the line started by http::Progress
puts stderr ""
upvar #0 $token state
set max 0
@@ -336,7 +337,7 @@ proc Http_Copy { url file {chunk 4096} } {
if {[regexp -nocase ^location$ $name]} {
# Handle URL redirects
puts stderr "Location:$value"
- return [Http_Copy [string trim $value] $file $chunk]
+ return [copy [string trim $value] $file $chunk]
}
}
incr max
@@ -346,7 +347,7 @@ proc Http_Copy { url file {chunk 4096} } {
return $token
}
-proc HttpProgress {args} {
+proc ::http::Progress {args} {
puts -nonewline stderr . ; flush stderr
}
diff --git a/contrib/tcl/doc/interp.n b/contrib/tcl/doc/interp.n
index a7dda337b0b8..023681833e0d 100644
--- a/contrib/tcl/doc/interp.n
+++ b/contrib/tcl/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.
'\"
-'\" SCCS: @(#) interp.n 1.29 97/03/06 17:41:39
+'\" SCCS: @(#) interp.n 1.35 97/07/31 18:04:06
'\"
.so man.macros
.TH interp n 7.6 Tcl "Tcl Built-In Commands"
@@ -169,18 +169,29 @@ exists in this master, \fB0\fR otherwise. If \fIpath\fR is omitted, the
invoking interpreter is used.
.VS BR
.TP
-\fBinterp \fBexpose \fIpath\fR \fIhiddenCmdName\fR ?\fIexposedCmdName\fR?
-Makes the hidden command \fIhiddenCmdName\fR exposed, potentially renaming
-it to \fIexposedCmdName\fR, in the interpreter denoted by \fIpath\fR.
+\fBinterp \fBexpose \fIpath\fR \fIhiddenName\fR ?\fIexposedCmdName\fR?
+Makes the hidden command \fIhiddenName\fR exposed, eventually bringing
+it back under a new \fIexposedCmdName\fR name (this name is currently
+accepted only if it is a valid global name space name without any ::),
+in the interpreter
+denoted by \fIpath\fR.
If an exposed command with the targetted name already exists, this command
fails.
Hidden commands are explained in more detail in HIDDEN COMMANDS, below.
.TP
\fBinterp \fBhide \fIpath\fR \fIexposedCmdName\fR ?\fIhiddenCmdName\fR?
-Makes the exposed command \fIexposedCmdName\fR hidden, potentially renaming
-it to \fIhiddenCmdName\fR, in the interpreter denoted by \fIpath\fR.
+Makes the exposed command \fIexposedCmdName\fR hidden, renaming
+it to the hidden command \fIhiddenCmdName\fR, or keeping the same name if
+\fIhiddenCmdName\fR is not given, in the interpreter denoted
+by \fIpath\fR.
If a hidden command with the targetted name already exists, this command
fails.
+Currently both \fIexposedCmdName\fR and \fIhiddenCmdName\fR can
+not contain namespace qualifiers, or an error is raised.
+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.
.TP
\fBinterp \fBhidden \fIpath\fR
@@ -291,25 +302,34 @@ such as the \fBerrorInfo\fR and \fBerrorCode\fR variables, if an
error occurs) is returned to the invoking interpreter.
.VS BR
.TP
-\fIslave \fBexpose \fIhiddenCmdName \fR?\fIexposedCmdName\fR?
-This command exposes the hidden command \fIhiddenCmdName\fR, potentially
-renaming it to \fIexposedCmdName\fR, in \fIslave\fR.
-If an exposed command with the targeted name already exists, this command
+\fIslave \fBexpose \fIhiddenName \fR?\fIexposedCmdName\fR?
+This command exposes the hidden command \fIhiddenName\fR, eventually bringing
+it back under a new \fIexposedCmdName\fR name (this name is currently
+accepted only if it is a valid global name space name without any ::),
+in \fIslave\fR.
+If an exposed command with the targetted name already exists, this command
fails.
For more details on hidden commands, see HIDDEN COMMANDS, below.
.TP
-\fIslave \fBhide \fIexposedCmdName \fR?\fIhiddenCmdName\fR?
-This command hides the exposed command \fIexposedCmdName\fR, potentially
-renaming it to \fIhiddenCmdName\fR, in \fIslave\fR.
-If a hidden command with the targeted name already exists, this command
+\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.
+If a hidden command with the targetted name already exists, this command
fails.
+Currently both \fIexposedCmdName\fR and \fIhiddenCmdName\fR can
+not contain namespace qualifiers, or an error is raised.
+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.
.TP
\fIslave \fBhidden\fR
Returns a list of the names of all hidden commands in \fIslave\fR.
.TP
-\fIslave \fBinvokehidden\fR ?\fB-global\fR \fIhiddenCmdName \fR?\fIarg ..\fR?
-This command invokes the hidden command \fIhiddenCmdName\fR with the
+\fIslave \fBinvokehidden\fR ?\fB-global\fR \fIhiddenName \fR?\fIarg ..\fR?
+This command invokes the hidden command \fIhiddenName\fR with the
supplied arguments, in \fIslave\fR. No substitutions or evaluations are
applied to the arguments.
If the \fB-global\fR flag is given, the command is invoked at the global
@@ -494,11 +514,19 @@ interpreter using \fBinterp expose\fR and \fBinterp hide\fR. The \fBinterp
expose\fR command moves a hidden command to the
set of exposed commands in the interpreter identified by \fIpath\fR,
potentially renaming the command in the process. If an exposed command by
-the targeted name already exists, the operation fails. Similarly,
+the targetted name already exists, the operation fails. Similarly,
\fBinterp hide\fR moves an exposed command to the set of hidden commands in
that interpreter. Safe interpreters are not allowed to move commands
between the set of hidden and exposed commands, in either themselves or
their descendants.
+.PP
+Currently, the names of hidden commands cannot contain namespace
+qualifiers, and you must first rename a command in a namespace to the
+global namespace before you can hide it.
+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.
.VE
.SH CREDITS
.PP
diff --git a/contrib/tcl/doc/namespace.n b/contrib/tcl/doc/namespace.n
index 4be685a7527c..5bf787d87bec 100644
--- a/contrib/tcl/doc/namespace.n
+++ b/contrib/tcl/doc/namespace.n
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) namespace.n 1.8 97/06/20 16:48:18
+'\" SCCS: @(#) namespace.n 1.9 97/08/13 17:08:25
'\"
.so man.macros
.TH namespace n 8.0 Tcl "Tcl Built-In Commands"
@@ -14,7 +14,7 @@
.SH NAME
namespace \- create and manipulate contexts for commands and variables
.SH SYNOPSIS
-\fBnamespace ?\fIsubcommand\fR? ?\fIarg ...\fR?
+\fBnamespace \fR?\fIoption\fR? ?\fIarg ...\fR?
.BE
.SH DESCRIPTION
@@ -23,38 +23,45 @@ The \fBnamespace\fR command lets you create, access, and destroy
separate contexts for commands and variables.
See the section \fBWHAT IS A NAMESPACE?\fR below
for a brief overview of namespaces.
-The legal \fIsubcommand\fR's are listed below.
-Note that you can abbreviate the names of subcommands.
+The legal \fIoption\fR's are listed below.
+Note that you can abbreviate the \fIoption\fR's.
.TP
-\fBnamespace children \fR?\fIname\fR? ?\fIpattern\fR?
+\fBnamespace children \fR?\fInamespace\fR? ?\fIpattern\fR?
Returns a list of all child namespaces that belong to the
-namespace \fIname\fR.
-If \fIname\fR is not specified,
+namespace \fInamespace\fR.
+If \fInamespace\fR is not specified,
then the children are returned for the current namespace.
-This command returns fully-qualified names which start with \fB::\fR.
+This command returns fully-qualified names,
+which start with \fB::\fR.
If the optional \fIpattern\fR is given,
then this command returns only the names that match the glob-style pattern.
The actual pattern used is determined as follows:
a pattern that starts with \fB::\fR is used directly,
-otherwise the namespace \fIname\fR
+otherwise the namespace \fInamespace\fR
(or the fully-qualified name of the current namespace)
is prepended onto the the pattern.
.TP
-\fBnamespace code \fIarg\fR
+\fBnamespace code \fIscript\fR
Captures the current namespace context for later execution
-of the script \fIarg\fR.
-It returns a new Tcl scoped command that can be evaluated later
-to execute \fIarg\fR in the current namespace.
-It is typically used to create callback scripts,
-where the \fIarg\fR argument is a list containing a script.
-The command it produces is equivalent to that produced by
-\fBlist namespace inscope [namespace current] $arg\fR
-If \fIarg\fR is itself a scoped command starting with
-\fBnamespace inscope\fR,
-the result is just \fIarg\fR.
-.br
-.sp
-Extensions like Tk normally execute callback scripts
+of the script \fIscript\fR.
+It returns a new script in which \fIscript\fR has been wrapped
+in a \fBnamespace code\fR command.
+The new script has two important properties.
+First, it can be evaluated in any namespace and will cause
+\fIscript\fR to be evaluated in the current namespace
+(the one where the \fBnamespace code\fR command was invoked).
+Second, additional arguments can be appended to the resulting script
+and they will be passed to \fIscript\fR as additional arguments.
+For example, suppose the command
+\fBset script [namespace code {foo bar}]\fR
+is invoked in namespace \fB::a::b\fR.
+Then \fBeval "$script x y"\fR
+can be executed in any namespace (assuming the value of
+\fBscript\fR has been passed in properly)
+and will have the same effect as the command
+\fBnamespace eval ::a::b {foo bar x y}\fR.
+This command is needed because
+extensions like Tk normally execute callback scripts
in the global namespace.
A scoped command captures a command together with its namespace context
in a way that allows it to be executed properly later.
@@ -67,19 +74,11 @@ The actual name of the global namespace is ``''
(i.e., an empty string),
but this command returns \fB::\fR for the global namespace
as a convenience to programmers.
-Tcl treats ``'' and \fB::\fR as synonyms
-for the name of the global namespace.
-This make it easier to manipulate namespace names
-and ensures that commands like
-\fBset [namespace current]::x\fR
-always work.
.TP
-\fBnamespace delete \fR?\fIname name ...\fR?
-Each namespace \fIname\fR is deleted
+\fBnamespace delete \fR?\fInamespace namespace ...\fR?
+Each namespace \fInamespace\fR is deleted
and all variables, procedures, and child namespaces
contained in the namespace are deleted.
-\fIname\fR may include a sequence of namespace qualifiers
-separated by \fB::\fRs.
If a procedure is currently executing inside the namespace,
the namespace will be kept alive until the procedure returns;
however, the namespace is marked to prevent other code from
@@ -87,42 +86,21 @@ looking it up by name.
If a namespace doesn't exist, this command returns an error.
If no namespace names are given, this command does nothing.
.TP
-\fBnamespace eval\fR \fIname arg\fR ?\fIarg ...\fR?
-Activates a namespace called \fIname\fR and evaluates some code
+\fBnamespace eval\fR \fInamespace arg\fR ?\fIarg ...\fR?
+Activates a namespace called \fInamespace\fR and evaluates some code
in that context.
If the namespace does not already exist, it is created.
-This command is normally used to define the
-commands and variables in a namespace.
If more than one \fIarg\fR argument is specified,
the arguments are concatenated together with a space between each one
-in the same fashion as the \fBconcat\fR command,
+in the same fashion as the \fBeval\fR command,
and the result is evaluated.
.br
.sp
-If a \fBnamespace eval\fR command creates a new namespace \fIname\fR,
-then \fIname\fR determines its parent namespace and
-the new namespace's position in the hierarchy of namespaces.
-If \fIname\fR includes a sequence of namespace qualifiers
-separated by \fB::\fRs,
-it is created as a child of the specified parent namespace;
-otherwise, the namespace is created as a child of the current namespace.
-If \fIname\fR has leading namespace qualifiers
+If \fInamespace\fR has leading namespace qualifiers
and any leading namespaces do not exist,
they are automatically created.
-.br
-.sp
-\fBnamespace eval\fR is another way (besides procedure calls)
-that the Tcl naming context can change.
-It adds a call frame to the stack to represent the namespace context.
-This means each \fBnamespace eval\fR command
-counts as another call level for \fBuplevel\fR and \fBupvar\fR commands.
-For example, \fBinfo level 1\fR will return a list
-describing a command that is either
-the outermost procedure call or the outermost \fBnamespace eval\fR command.
-Also, \fBuplevel #0\fR evaluates a script
-at top-level in the outermost namespace (the global namespace).
.TP
-\fBnamespace export \fR?\fB-clear\fR? ?\fIpattern pattern ...\fR?
+\fBnamespace export \fR?\-\fBclear\fR? ?\fIpattern pattern ...\fR?
Specifies which commands are exported from a namespace.
The exported commands are those that can be later imported
into another namespace using a \fBnamespace import\fR command.
@@ -136,15 +114,15 @@ but it may not include any namespace qualifiers.
That is, the pattern can only specify commands
in the current (exporting) namespace.
Each \fIpattern\fR is appended onto the namespace's list of export patterns.
-If the \fB-clear\fR flag is given,
+If the \-\fBclear\fR flag is given,
the namespace's export pattern list is reset to empty before any
\fIpattern\fR arguments are appended.
-If no \fIpattern\fRs are given and the \fB-clear\fR flag isn't given,
+If no \fIpattern\fRs are given and the \-\fBclear\fR flag isn't given,
this command returns the namespace's current export list.
.TP
\fBnamespace forget \fR?\fIpattern pattern ...\fR?
Removes previously imported commands from a namespace.
-Each \fIpattern\fR is a \fIqualified name\fR like
+Each \fIpattern\fR is a qualified name such as
\fBfoo::x\fR or \fBa::b::p*\fR.
Qualified names contain \fB::\fRs and qualify a name
with the name of one or more namespaces.
@@ -155,10 +133,10 @@ Glob characters may not appear in a namespace name.
This command first finds the matching exported commands.
It then checks whether any of those those commands
were previously imported by the current namespace.
-If so, this command deletes the corresponding imported command.
+If so, this command deletes the corresponding imported commands.
In effect, this un-does the action of a \fBnamespace import\fR command.
.TP
-\fBnamespace import \fR?\fB-force\fR? ?\fIpattern\fR \fIpattern ...\fR?
+\fBnamespace import \fR?\fB\-force\fR? ?\fIpattern\fR \fIpattern ...\fR?
Imports commands into a namespace.
Each \fIpattern\fR is a qualified name like
\fBfoo::x\fR or \fBa::p*\fR.
@@ -167,17 +145,24 @@ and may have glob-style special characters in the command name
at the end of the qualified name.
Glob characters may not appear in a namespace name.
All the commands that match a \fIpattern\fR string
-and which are exported from their namespace
+and which are currently exported from their namespace
are added to the current namespace.
This is done by creating a new command in the current namespace
that points to the exported command in its original namespace;
when the new imported command is called, it invokes the exported command.
This command normally returns an error
if an imported command conflicts with an existing command.
-However, if the \fB-force\fR option is given,
+However, if the \-\fBforce\fR option is given,
imported commands will silently replace existing commands.
+The \fBnamespace import\fR command has snapshot semantics:
+that is, only requested commands that are currently defined
+in the exporting namespace are imported.
+In other words, you can import only the commands that are in a namespace
+at the time when the \fBnamespace import\fR command is executed.
+If another command is defined and exported in this namespace later on,
+it will not be imported.
.TP
-\fBnamespace inscope\fR \fIname arg\fR ?\fIarg ...\fR?
+\fBnamespace inscope\fR \fInamespace arg\fR ?\fIarg ...\fR?
Executes a script in the context of a particular namespace.
This command is not expected to be used directly by programmers;
calls to it are generated implicitly when applications
@@ -195,9 +180,9 @@ is equivalent to
This \fBlappend\fR semantics is important because many callback scripts
are actually prefixes.
.TP
-\fBnamespace origin name\fR
+\fBnamespace origin \fIcommand\fR
Returns the fully-qualified name of the original command
-to which the imported command \fIname\fR refers.
+to which the imported command \fIcommand\fR refers.
When a command is imported into a namespace,
a new command is created in that namespace
that points to the actual command in the exporting namespace.
@@ -206,13 +191,13 @@ If a command is imported into a sequence of namespaces
just imports the command from the previous namespace,
this command returns the fully-qualified name of the original command
in the first namespace, \fIa\fR.
-If \fIname\fR does not refer to an imported command,
+If \fIcommand\fR does not refer to an imported command,
the command's own fully-qualified name is returned.
.TP
-\fBnamespace parent\fR ?\fIname\fR?
+\fBnamespace parent\fR ?\fInamespace\fR?
Returns the fully-qualified name of the parent namespace
-for namespace \fIname\fR.
-If \fIname\fR is not specified,
+for namespace \fInamespace\fR.
+If \fInamespace\fR is not specified,
the fully-qualified name of the current namespace's parent is returned.
.TP
\fBnamespace qualifiers\fR \fIstring\fR
@@ -236,7 +221,7 @@ This command is the complement of the \fBnamespace qualifiers\fR command.
It does not check whether the namespace names are, in fact,
the names of currently defined namespaces.
.TP
-\fBnamespace which\fR ?\fB-command\fR? ?\fB-variable\fR? \fIname\fR
+\fBnamespace which\fR ?\-\fBcommand\fR? ?\-\fBvariable\fR? \fIname\fR
Looks up \fIname\fR as either a command or variable
and returns its fully-qualified name.
For example, if \fIname\fR does not exist in the current namespace
@@ -274,7 +259,7 @@ the procedure \fBBump\fR.
The commands and variables in this namespace are separate from
other commands and variables in the same program.
If there is a command named \fBBump\fR in the global namespace,
-for example, it will not interfere with the command \fBBump\fR
+for example, it will be different from the command \fBBump\fR
in the \fBCounter\fR namespace.
.PP
Namespace variables resemble global variables in Tcl.
@@ -283,8 +268,8 @@ but can be accessed in a procedure via the \fBvariable\fR command,
as shown in the example above.
.PP
Namespaces are dynamic.
-You can add and delete commands and variables at any time.
-So you can build up the contents of a
+You can add and delete commands and variables at any time,
+so you can build up the contents of a
namespace over time using a series of \fBnamespace eval\fR commands.
For example, the following series of commands has the same effect
as the namespace definition shown above:
@@ -312,66 +297,37 @@ Namespaces can have other namespaces within them,
so they nest hierarchically.
A nested namespace is encapsulated inside its parent namespace
and can not interfere with other namespaces.
-If namespaces are used to represent packages,
-this feature lets one package contain its own copy of another package.
.SH "QUALIFIED NAMES"
-Procedures execute in the context of the namespace that contains them.
-So in the following namespace,
-.CS
-\fBnamespace eval Counter {
- namespace export Bump Reset
- variable num 0
-
- proc Bump {{by 1}} {
- variable num
- return [incr num $by]
- }
- proc Reset {} {
- variable num
- set num 0
- }
-}\fR
-.CE
-procedures like \fBBump\fR and \fBReset\fR execute in the context of
-namespace \fBCounter\fR.
.PP
-In this context, you can access the commands and variables that
-reside in the namespace using simple names.
-In the example above,
-we access the \fBnum\fR variable with the command \fBvariable num\fR.
-(We can't use \fBglobal num\fR since that would only
-look up \fBnum\fR in the global namespace.)
-We can access the \fBBump\fR and \fBReset\fR procedures in
-another procedure like this:
-.CS
-\fBnamespace eval Counter {
- namespace export Rebump
- proc Rebump {{by 1}} {
- Reset
- Bump $by
- }
-}\fR
-.CE
-This is the real benefit of namespaces.
-The commands and variables in a namespace fit together as a module.
+Each namespace has a textual name such as
+\fBhistory\fR or \fB::safe::interp\fR.
+Since namespaces may nest,
+qualified names are used to refer to
+commands, variables, and child namespaces contained inside namespaces.
+Qualified names are similar to the hierarchical path names for
+Unix files or Tk widgets,
+except that \fB::\fR is used as the separator
+instead of \fB/\fR or \fB.\fR.
+The topmost or global namespace has the name ``'' (i.e., an empty string),
+although \fB::\fR is a synonym.
+As an example, the name \fB::safe::interp::create\fR
+refers to the command \fBcreate\fR in the namespace \fBinterp\fR
+that is a child of of namespace \fB::safe\fR,
+which in turn is a child of the global namespace \fB::\fR.
.PP
If you want to access commands and variables from another namespace,
you must use some extra syntax.
Names must be qualified by the namespace that contains them.
-The \fB::\fR string acts as a separator
-between the various qualifiers in a name.
From the global namespace,
we might access the \fBCounter\fR procedures like this:
.CS
\fBCounter::Bump 5
-Counter::Reset
-Counter::Rebump 10\fR
+Counter::Reset\fR
.CE
We could access the current count like this:
.CS
-\fBputs "count = $Counter::num"
-set Counter::num 35\fR
+\fBputs "count = $Counter::num"\fR
.CE
When one namespace contains another, you may need more than one
qualifier to reach its elements.
@@ -381,23 +337,6 @@ from the global namespace like this:
.CS
\fBFoo::Counter::Bump 3\fR
.CE
-You can think of namespaces like directories in a file system.
-When you are sitting in a particular directory context,
-you can access files with simple names.
-But from another context, you must use a proper path name.
-A name like \fBFoo::Counter::Bump\fR
-is just like a file name \fBFoo/Counter/Bump\fR,
-except that we have used \fB::\fR instead of \fB/\fR as the separator.
-Just as the file system has a root directory \fB/\fR,
-all namespaces are rooted in the global namespace named \fB::\fR.
-So all names can be given with an absolute path that begins with \fB::\fR.
-For example, we can say:
-.CS
-\fB::Foo::Counter::Bump 3\fR
-.CE
-With this name, you can be sure that you'll get the \fBBump\fR procedure
-in the \fBCounter\fR namespace, in the \fBFoo\fR namespace, in the global
-namespace\-no matter what the current namespace context may be.
.PP
You can also use qualified names when you create and rename commands.
For example, you could add a procedure to the \fBFoo\fR
@@ -412,8 +351,9 @@ And you could move the same procedure to another namespace like this:
.PP
There are a few remaining points about qualified names
that we should cover.
-\fB::\fR is disallowed in both simple command and variable names except
-as a namespace separator.
+Namespaces have nonempty names except for the global namespace.
+\fB::\fR is disallowed in simple command, variable, and namespace names
+except as a namespace separator.
Extra \fB:\fRs in a qualified name are ignored;
that is, two or more \fB:\fRs are treated as a namespace separator.
A trailing \fB::\fR in a qualified variable or command name
@@ -471,27 +411,15 @@ You can use the \fBnamespace which\fR command to clear up any question
about name resolution.
For example, the command:
.CS
-\fBnamespace eval Foo::Debug {namespace which -variable traceLevel}\fR
+\fBnamespace eval Foo::Debug {namespace which \-variable traceLevel}\fR
.CE
returns \fB::traceLevel\fR.
On the other hand, the command,
.CS
-\fBnamespace eval Foo {namespace which -variable traceLevel}\fR
+\fBnamespace eval Foo {namespace which \-variable traceLevel}\fR
.CE
returns \fB::Foo::traceLevel\fR.
.PP
-Although Tcl always follows the
-``look in the current then in the global namespace''
-rule for variables and commands,
-there is a question of how to resolve a
-qualified name like \fBfoo::bar::cmd\fR.
-A relative name like this might resolve to either
-\fB[namespace current]::foo::bar::cmd\fR
-or to \fB::foo::bar::cmd\fR.
-If \fBcmd\fR does not appear in \fB[namespace current]::foo::bar\fR
-but does appear in \fB::foo::bar\fR,
-Tcl assumes it refers to the latter command.
-.PP
As mentioned above,
namespace names are looked up differently
than the names of variables and commands.
@@ -508,7 +436,7 @@ by the name resolution rule above,
you can access the element.
.PP
You can access a namespace variable
-within a procedure in the same namespace
+from a procedure in the same namespace
by using the \fBvariable\fR command.
Much like the \fBglobal\fR command,
this creates a local link to the namespace variable.
@@ -529,7 +457,7 @@ For example, suppose that all of the commands in a package
like BLT are contained in a namespace called \fBBlt\fR.
Then you might access these commands like this:
.CS
-\fBBlt::graph .g -background red
+\fBBlt::graph .g \-background red
Blt::table . .g 0,0\fR
.CE
If you use the \fBgraph\fR and \fBtable\fR commands frequently,
@@ -539,12 +467,16 @@ like this:
.CS
\fBnamespace import Blt::*\fR
.CE
-This adds all commands from the \fBBlt\fR namespace into the current
-namespace context, so you can write code like this:
+This adds all exported commands from the \fBBlt\fR namespace
+into the current namespace context, so you can write code like this:
.CS
-\fBgraph .g -background red
+\fBgraph .g \-background red
table . .g 0,0\fR
.CE
+The \fBnamespace import\fR command only imports commands
+from a namespace that that namespace exported
+with a \fBnamespace export\fR command.
+.PP
Importing \fIevery\fR command from a namespace is generally
a bad idea since you don't know what you will get.
It is better to import just the specific commands you need.
@@ -555,23 +487,15 @@ For example, the command
imports only the \fBgraph\fR and \fBtable\fR commands into the
current context.
.PP
-The \fBnamespace import\fR command has snapshot semantics:
-that is, only requested commands that are currently defined
-in the exporting namespace are imported.
-In other words, you can import only the commands that are in a namespace
-like \fBBlt\fR at the time when the \fBnamespace import\fR command is
-executed. If another command appears in this namespace later on, it
-will not be imported.
-.PP
If you try to import a command that already exists, you will get an
error. This prevents you from importing the same command from two
different packages. But from time to time (perhaps when debugging),
you may want to get around this restriction. You may want to
reissue the \fBnamespace import\fR command to pick up new commands
that have appeared in a namespace. In that case, you can use the
-\fB-force\fR option, and existing commands will be silently overwritten:
+\fB\-force\fR option, and existing commands will be silently overwritten:
.CS
-\fBnamespace import -force Blt::graph Blt::table\fR
+\fBnamespace import \-force Blt::graph Blt::table\fR
.CE
If for some reason, you want to stop using the imported commands,
you can remove them with an \fBnamespace forget\fR command, like this:
@@ -632,30 +556,6 @@ may be imported by other namespaces.
If a \fBnamespace import\fR command specifies a command
that is not exported, the command is not imported.
-.SH "SCOPED VALUES"
-.PP
-Extensions like Tk execute ordinary code fragments in the global
-namespace.
-A scoped command captures a script together with
-its namespace in a way that allows it to be executed properly later.
-It is needed, for example, to wrap up script
-when a Tk widget is used within a namespace.
-It is also needed for commands such as \fBafter\fR that
-execute a script at the global level at some future time.
-If a \fBafter\fR command is executed in a namespace,
-a \fBnamespace code\fR command is needed to ensure
-its script executes in the correct context:
-.CS
-\fBnamespace eval Foo {
- variable v 123
- proc report {msg} {
- puts "$msg"
- }
-
- after 2000 [namespace code {report "Hello World, v = $v"}]
-}\fR
-.CE
-
.SH "SEE ALSO"
variable(n)
diff --git a/contrib/tcl/doc/registry.n b/contrib/tcl/doc/registry.n
index 6e35f2dab528..52c2e4e17a2b 100644
--- a/contrib/tcl/doc/registry.n
+++ b/contrib/tcl/doc/registry.n
@@ -1,7 +1,10 @@
'\"
-'\" Copyright (c) 1997 by Sun Microsystems, Inc. All rights reserved.
+'\" Copyright (c) 1997 Sun Microsystems, Inc.
'\"
-'\" SCCS: @(#) registry.n 1.3 97/06/23 14:41:04
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+'\" SCCS: @(#) registry.n 1.5 97/08/11 19:33:27
'\"
.so man.macros
.TH registry n 8.0 Tcl "Tcl Built-In Commands"
@@ -65,7 +68,8 @@ data, see SUPPORTED TYPES, below.
If \fIpattern\fR isn't specified, returns a list of names of all the
subkeys of \fIkeyName\fR. If \fIpattern\fR is specified, only those
names matching \fIpattern\fR are returned. Matching is determined
-using the same rules as for \fBstring\fR \fBmatch\fR.
+using the same rules as for \fBstring\fR \fBmatch\fR. If the
+specified \fIkeyName\fR does not exist, then an error is generated.
.TP
\fBregistry set \fIkeyName\fR ?\fIvalueName data \fR?\fItype\fR??
.
diff --git a/contrib/tcl/doc/rename.n b/contrib/tcl/doc/rename.n
index a3e185d9ba30..8962bd0ed6b1 100644
--- a/contrib/tcl/doc/rename.n
+++ b/contrib/tcl/doc/rename.n
@@ -1,11 +1,11 @@
'\"
'\" Copyright (c) 1993 The Regents of the University of California.
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) rename.n 1.5 96/03/25 20:22:11
+'\" SCCS: @(#) rename.n 1.6 97/07/30 17:37:26
'\"
.so man.macros
.TH rename n "" Tcl "Tcl Built-In Commands"
@@ -20,9 +20,13 @@ rename \- Rename or delete a command
.SH DESCRIPTION
.PP
Rename the command that used to be called \fIoldName\fR so that it
-is now called \fInewName\fR. If \fInewName\fR is an empty string
-then \fIoldName\fR is deleted. The \fBrename\fR command
-returns an empty string as result.
+is now called \fInewName\fR.
+If \fInewName\fR is an empty string then \fIoldName\fR is deleted.
+\fIoldName\fR and \fInewName\fR may include namespace qualifiers
+(names of containing namespaces).
+If a command is renamed into a different namespace,
+future invocations of it will execute in the new namespace.
+The \fBrename\fR command returns an empty string as result.
.SH KEYWORDS
-command, delete, rename
+command, delete, namespace, rename
diff --git a/contrib/tcl/doc/resource.n b/contrib/tcl/doc/resource.n
new file mode 100644
index 000000000000..1ccd50cc065d
--- /dev/null
+++ b/contrib/tcl/doc/resource.n
@@ -0,0 +1,116 @@
+'\"
+'\" Copyright (c) 1997 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" SCCS: @(#) resource.n 1.3 97/07/25 10:24:23
+'\"
+.so man.macros
+.TH resource n 8.0 Tcl "Tcl Built-In Commands"
+.BS
+'\" Note: do not modify the .SH NAME line immediately below!
+.SH NAME
+resource \- Manipulate Macintosh resources
+.SH SYNOPSIS
+\fBresource \fIoption\fR ?\fIarg arg ...\fR?
+.BE
+
+.SH DESCRIPTION
+.PP
+The \fBresource\fR command provides some generic operations for
+dealing with Macintosh resources. This command is only supported on
+the Macintosh platform. Each Macintosh file consists of two
+\fIforks\fR: a \fIdata\fR fork and a \fIresource\fR fork. You use the
+normal open, puts, close, etc. commands to manipulate the data fork.
+You must use this command, however, to interact with the resource
+fork. \fIOption\fR indicates what resource command to perform. Any
+unique abbreviation for \fIoption\fR is acceptable. The valid options
+are:
+.TP
+\fBresource close \fIrsrcRef\fR
+Closes the given resource reference (obtained from \fBresource
+open\fR). Resources from that resource file will no longer be
+available.
+.TP
+\fBresource list \fIresourceType\fR ?\fIresourceRef\fR?
+List all of the resources ids of type \fIresourceType\fR (see RESOURCE
+TYPES below). If \fIresourceRef\fR is specified then the command will
+limit the search to that particular resource file. Otherwise, all
+resource files currently opened by the application will be searched.
+A Tcl list of either the resource name's or resource id's of the found
+resources will be returned. See the RESOURCE IDS section below for
+more details about what a resource id is.
+.TP
+\fBresource open \fIfileName\fR ?\fIpermissions\fR?
+Open the resource for the file \fIfileName\fR. Standard file
+permissions may also be specified (see the manual entry for \fBopen\fR
+for details). A resource reference (\fIresourceRef\fR) is returned
+that can be used by the other resource commands. An error can occur
+if the file doesn't exist or the file does not have a resource fork.
+However, if you open the file with write permissions the file and/or
+resource fork will be created instead of generating an error.
+.TP
+\fBresource read \fIresourceType\fR \fIresourceId\fR ?\fIresourceRef\fR?
+Read the entire resource of type \fIresourceType\fR (see RESOURCE
+TYPES below) and the name or id of \fIresourceId\fR (see RESOURCE IDS
+below) into memory and return the result. If \fIresourceRef\fR is
+specified we limit our search to that resource file, otherwise we
+search all open resource forks in the application. It is important to
+note that most Macintosh resource use a binary format and the data
+returned from this command may have embedded NULLs or other non-ASCII
+data.
+.TP
+\fBresource types ?\fIresourceRef\fR?
+This command returns a Tcl list of all resource types (see RESOURCE
+TYPES below) found in the resource file pointed to by
+\fIresourceRef\fR. If \fIresourceRef\fR is not specified it will
+return all the resource types found in every resource file currently
+opened by the application.
+.TP
+\fBresource write\fR ?\fIoptions\fR? \fIresourceType\fR \fIdata\fR
+This command will write the passed in \fIdata\fR as a new resource of
+type \fIresourceType\fR (see RESOURCE TYPES below). Several options
+are available that describe where and how the resource is stored.
+.RS
+.TP
+\fB\-id\fR \fIresourceId\fR
+If the \fB-id\fR option is given the id \fIresourceId\fR (see RESOURCE
+IDS below) is used for the new resource, otherwise a unique id will be
+generated that will not conflict with any existing resource. However,
+the id must be a number - to specify a name use the \fB\-name\fR option.
+.TP
+\fB\-name\fR \fIresourceName\fR
+If \fB-name\fR is specified the resource will be named
+\fIresourceName\fR, otherwise it will have the empty string as the
+name.
+.TP
+\fB\-file\fR \fIresourceRef\fR
+If the \fB-file\fR option is specified then the resource will be
+written in the file pointed to by \fIresourceRef\fR, otherwise the
+most resently open resource will be used.
+.RE
+
+.SH "RESOURCE TYPES"
+Resource types are defined as a four character string that is then
+mapped to an underlying id. For example, \fBTEXT\fR refers to the
+Macintosh resource type for text. The type \fBSTR#\fR is a list of
+counted strings. All Macintosh resources must be of some type. See
+Macintosh documentation for a more complete list of resource types
+that are commonly used.
+
+.SH "RESOURCE IDS"
+For this command the notion of a resource id actually refers to two
+ideas in Macintosh resources. Every place you can use a resource Id
+you can use either the resource name or a resource number. Names are
+always searched or returned in preference to numbers. For example,
+the \fBresource list\fR command will return names if they exist or
+numbers if the name is NULL.
+
+.SH "SEE ALSO"
+open
+
+.SH "PORTABILITY ISSUES"
+The resource command is only available on Macintosh.
+
+.SH KEYWORDS
+open, resource
diff --git a/contrib/tcl/doc/safe.n b/contrib/tcl/doc/safe.n
index acc50ed7a18e..03adf0f38b63 100644
--- a/contrib/tcl/doc/safe.n
+++ b/contrib/tcl/doc/safe.n
@@ -4,300 +4,299 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) safe.n 1.10 97/03/24 09:21:12
+'\" SCCS: @(#) safe.n 1.3 97/08/13 12:44:45
'\"
.so man.macros
-.TH "Safe Tcl" n 7.7 Tcl "Tcl Built-In Commands"
+.TH "Safe Tcl" n 8.0 Tcl "Tcl Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
-Safe Tcl \- A mechanism for managing security policies.
+Safe Base \- A mechanism for creating and manipulating safe interpreters.
.SH SYNOPSIS
-.nf
-\fBtcl_safeCreateInterp\fR \fIslave\fR
+.PP
+\fB::safe::interpCreate\fR ?\fIslave\fR? ?\fIoptions...\fR?
+.sp
+\fB::safe::interpInit\fR \fIslave\fR ?\fIoptions...\fR?
.sp
-\fBtcl_safeInitInterp\fR \fIslave\fR
+\fB::safe::interpConfigure\fR \fIslave\fR ?\fIoptions...\fR?
.sp
-\fBtcl_safeDeleteInterp\fR \fIslave\fR
+\fB::safe::interpDelete\fR \fIslave\fR
.sp
-\fIpolicy\fB_policyInit\fR \fIslave\fR
+\fB::safe::interpAddToAccessPath\fR \fIslave\fR \fIdirectory\fR
.sp
-\fIpolicy\fB_policyFinalize\fR \fIslave\fR
-.fi
+\fB::safe::interpFindInAccessPath\fR \fIslave\fR \fIdirectory\fR
+.sp
+\fB::safe::setLogCmd\fR ?\fIcmd arg...\fR?
+.SH OPTIONS
+.PP
+?\fB\-accessPath\fR \fIpathList\fR? ?\fB\-noStatics\fR? ?\fB\-nestedLoadOk\fR? ?\fB\-deleteHook\fR \fIscript\fR?
.BE
.SH DESCRIPTION
+Safe Tcl is a mechanism for executing untrusted Tcl scripts
+safely and for providing mediated access by such scripts to
+potentially dangerous functionality.
.PP
-This manual entry describes \fBSafe Tcl\fR, a mechanism and collection of
-library procedures for managing security policies. \fBSafe Tcl\fR is used
-in \fBapplications\fR that want to provide a flexible, extensible safe
-hosting environment for untrusted guest scripts, \fBtclets\fR. It
-provides a mechanism to ensure that tclets cannot harm the hosting
-application, and a way to extend limited degrees of trust to such tclets,
-to allow them to have access to unsafe features.
+The Safe Base ensures that untrusted Tcl scripts cannot harm the
+hosting application.
+The Safe Base prevents integrity and privacy attacks. Untrusted Tcl
+scripts are prevented from corrupting the state of the hosting
+application or computer. Untrusted scripts are also prevented from
+disclosing information stored on the hosting computer or in the
+hosting application to any party.
.PP
-The content of this manual entry is of interest to four different
-audiences: authors of tclets will primarily be interested in the sections
-on the \fBSAFE BASE\fR and on \fBUSING SAFE TCL IN TCLETS\fR.
-Application authors will find relevant information in the section on
-\fBUSING SAFE TCL IN APPLICATIONS\fR. To create a new security
-policy, e.g. to enable tclets to have access to a new feature, read the
-section on \fBWRITING SECURITY POLICIES\fB. Finally, system administrators
-and people installing \fBSafe Tcl\fR will find useful information in the
-section on \fBINSTALLING SECURITY POLICIES\fR.
+The Safe Base allows a master interpreter to create safe, restricted
+interpreters that contain a set of predefined aliases for the \fBsource\fR,
+\fBload\fR, \fBfile\fR and \fBexit\fR commands and
+are able to use the auto-loading and package mechanisms.
.PP
-\fBSecurity policies\fR are collections of procedures, aliases, hidden
-commands and variable settings that together implement a controlled way for
-an application to allow a tclet to have restricted access to unsafe features.
-For a complete description of aliases, hidden commands and how to use
-multiple interpreters in an application, see the manual entry for the
-\fBinterp\fR command.
+No knowledge of the file system structure is leaked to the
+safe interpreter, because it has access only to a virtualized path
+containing tokens. When the safe interpreter requests to source a file, it
+uses the token in the virtual path as part of the file name to source; the
+master interpreter translates the token into a real directory name and
+executes the requested operation.
+Different levels of security can be selected by using the optional flags
+of the commands described below.
.PP
-Packaging collections of features into security policies has several
-advantages: First, it allows these collections to have names. This
-facilitates the formation of a common, agreed upon, understanding of what
-features are included in each policy. Second, it enables a reasoned
-approach to developing extensions that make restricted features available
-to untrusted tclets.
-Third, because the feature set is delineated clearly, a security policy can
-be subjected to analysis to determine what risks it exposes its user to.
+All commands provided in the master interpreter by the Safe Base reside in
+the \fBsafe\fR namespace.
+\fB::safe::interpCreate\fR creates a new safe interpreter with options,
+described in the section \fBOPTIONS\fR.
+The return value is the name of the new safe interpreter created.
+\fB::safe::interpInit\fR is similar to \fB::safe::interpCreate\fR except that
+it requires as its first argument the name of a safe interpreter that was
+previously created directly using the \fBinterp\fR command.
+\fB::safe::interpDelete\fR deletes the interpreter named by its argument.
+\fB::safe::interpConfigure\fR can be used to set or get options for the named
+safe interpreters; the options are described in the section \fBOPTIONS\fR.
.PP
-The \fBSafe Tcl\fR approach to safe execution of untrusted code is further
-discussed in \fBThe Safe\-Tcl Security Model\fR
-(http://www.sunlabs.com/people/john.ousterhout/SafeTcl.ps).
-This paper provides a detailed discussion of the underlying
-motivations and philosophy, and compares the \fBSafe Tcl\fR model with
-other current efforts.
-
-.SH "SAFE BASE"
-.PP
-This section describes the environment in which tclets start execution in
-an application using \fBSafe Tcl\fR. This environment is known as the
-\fBSafe Base\fR, as it provides the basis on which further security
-policies are built.
+A virtual path is maintained in the master interpreter for each safe
+interpreter created by \fB::safe::interpCreate\fR or initialized by
+\fB::safe::interpInit\fR.
+The path maps tokens accessible in the safe interpreter into real path
+names on the local file system.
+This prevents safe interpreters from gaining knowledge about the
+structure of the file system of the host on which the interpeter is
+executing.
+When a token is used in a safe interpreter in a request to source or
+load a file, the token is translated to a real path name and the file to be
+sourced or loaded is located on the file system.
+The safe interpreter never gains knowledge of the actual path name under
+which the file is stored on the file system.
+Commands are provided in the master interpreter to manipulate the virtual
+path for a safe interpreter.
+\fB::safe::interpConfigure\fR can be used to set a new path for a safe
+interpreter.
+\fB::safe::interpAddToAccessPath\fR adds a directory to the virtual path for
+the named safe interpreter and returns the token by which that directory
+will be accessible in the safe interpreter.
+\fB::safe::interpFindInAccessPath\fR finds the
+requested directory in the virtual path for the named safe interpreter and
+returns the token by which that directory can be accessed in the safe
+interpreter.
+If the path is not found, an error is raised.
.PP
-When a tclet starts execution in an environment using \fBSafe Tcl\fR,
-its interpreter will contain aliases for the following commands:
-.DS
-.ta 1.2i 2.4i 3.6i
-\fBexit file load source
-tclPkgUnknown\fR
-.DE
-The \fBexit\fR alias terminates the execution of the
-invoking slave.
-\fBFile\fR allows access to a subset of the sub\-commands of the full
-\fBfile\fR command.
-\fBload\fR and \fBsource\fR make extensions available to the tclet in a
-controlled manner.
-The \fBtclPkgUnknown\fR alias allows the application to interpose on
-\fBpackage require\fR invocations by the tclet.
+\fB::safe::setLogCommand\fR installs a script to be called when interesting
+life cycle events happen.
+This script will be called with one argument, a string describing the event.
+.SH ALIASES
.PP
-The following \fBTcl\fR commands are hidden in the Safe Base:
-.DS
-.ta 1.2i 2.4i 3.6i
-\fBcd exec exit fconfigure
-file glob load open
-pwd socket source vwait\fR
-.DE
+The following aliases are provided in a safe interpreter:
+.TP
+\fBsource\fB \fIfileName\fR
+The requested file, a Tcl source file, is sourced into the safe interpreter
+if it is found.
+The \fBsource\fR alias can only source files from directories in
+the virtual path for the safe interpreter. The \fBsource\fR alias requires
+the safe interpreter to
+use one of the token names in its virtual path to denote the directory in
+which the file to be sourced can be found.
+See the section on \fBSECURITY\fR for more discussion of restrictions on
+valid filenames.
+.TP
+\fBload\fR \fIfileName\fR
+The requested file, a shared object file, in dynamically loaded into the
+safe interpreter if it is found.
+The filename must contain a token name mentioned in the virtual path for
+the safe interpreter for it to be found successfully.
+Additionally, the shared object file must contain a safe entry point; see
+the manual page for the \fBload\fR command for more details.
+.TP
+\fBfile\fR ?\fIoptions\fR?
+The \fBfile\fR alias provides access to a safe subset of the subcommands of
+the \fBfile\fR command; it allows only \fBdirname\fR, \fBjoin\fR,
+\fBextension\fR, \fBroot\fR, \fBtail\fR, \fBpathname\fR and \fBsplit\fR
+subcommands. For more details on what these subcommands do see the manual
+page for the \fBfile\fR command.
+.TP
+\fBexit\fR
+The calling interpreter is deleted and its computation is stopped, but the
+Tcl process in which this interpreter exists is not terminated.
.PP
-A tclet can also request to load packages using \fBpackage require\fR.
-Please read the manual page on the \fBpackage\fR and \fBload\fR commands
-for a discussion of package loading and special restrictions on loading
-into safe interpreters.
+.SH COMMANDS
.PP
-Tclets can use auto-loading to obtain the definitions for procedures as
-needed. The auto-loading mechanism in the Safe Base supports tclIndex files
-generated by \fBauto_mkindex\fR Version 2 and later.
+The following commands are provided in the master interpreter:
+.TP
+\fB::safe::interpCreate\fR ?\fIslave\fR? ?\fIoptions...\fR?
+Creates a safe interpreter, installs the aliases described in the section
+\fBALIASES\fR and initializes the auto-loading and package mechanism as
+specified by the supplied \fBoptions\fR.
+See the \fBOPTIONS\fR section below for a description of the common
+optional arguments.
+If the \fIslave\fR argument is omitted, a name will be generated.
+\fB::safe::interpCreate\fR always returns the interpreter name.
+.TP
+\fB::safe::interpInit\fR \fIslave\fR ?\fIoptions...\fR?
+This command is similar to \fBinterpCreate\fR except it that does not
+create the safe interpreter. \fIslave\fR must have been created by some
+other means, like \fB::interp create \-safe\fR.
+.TP
+\fB::safe::interpConfigure\fR \fIslave\fR ?\fIoptions...\fR?
+If no \fIoptions\fR are given, returns the settings for all options for the
+named safe interpreter.
+If \fIoptions\fR are supplied, sets the options for the named safe
+interpreter. See the section on \fBOPTIONS\fR below.
+.TP
+\fB::safe::interpDelete\fR \fIslave\fR
+Deletes the safe interpreter and cleans up the corresponding
+master interpreter data structures.
+If a \fIdeletehook\fR script was specified for this interpreter it is
+evaluated before the interpreter is deleted, with the name of the
+interpreter as an additional argument.
+.TP
+\fB::safe::interpFindInAccessPath\fR \fIslave\fR \fIdirectory\fR
+This command finds and returns the token for the real directory
+\fIdirectory\fR in the safe interpreter's current virtual access path.
+It generates an error if the directory is not found.
+Example of use:
+.CS
+$slave eval [list set tk_library [::safe::interpFindInAccessPath $name $tk_library]]
+.CE
+.TP
+\fB::safe::interpAddToAccessPath\fR \fIslave\fR \fIdirectory\fR
+This command adds \fIdirectory\fR to the virtual path maintained for the
+safe interpreter in the master, and returns the token that can be used in
+the safe interpreter to obtain access to files in that directory.
+If the directory is already in the virtual path, it only returns the token
+without adding the directory to the virtual path again.
+Example of use:
+.CS
+$slave eval [list set tk_library [::safe::interpAddToAccessPath $name $tk_library]]
+.CE
+.TP
+\fB::safe::setLogCmd\fR ?\fIcmd arg...\fR?
+This command installs a script that will be called when interesting
+lifecycle events occur for a safe interpreter.
+When called with no arguments, it returns the currently installed script.
+When called with one argument, an empty string, the currently installed
+script is removed and logging is turned off.
+The script will be invoked with one additional argument, a string
+describing the event of interest.
+The main purpose is to help in debugging safe interpreters.
+Using this facility you can get complete error messages while the safe
+interpreter gets only generic error messages.
+This prevents a safe interpreter from seeing messages about failures
+and other events that might contain sensitive information such as real
+directory names.
+.RS
+Example of use:
+.CS
+::safe::setLogCmd puts stderr
+.CE
+Below is the output of a sample session in which a safe interpreter
+attempted to source a file not found in its virtual access path.
+Note that the safe interpreter only received an error message saying that
+the file was not found:
+.CS
+NOTICE for slave interp10 : Created
+NOTICE for slave interp10 : Setting accessPath=(/foo/bar) staticsok=1 nestedok=0 deletehook=()
+NOTICE for slave interp10 : auto_path in interp10 has been set to {$p(:0:)}
+ERROR for slave interp10 : /foo/bar/init.tcl: no such file or directory
+.CE
+.RE
-.SH "USING SAFE TCL IN TCLETS"
-.PP
-Tclets start executing in the environment described in the previous
-section, on the \fBSAFE BASE\fR. If they need access to unsafe features,
-tclets can request to use a named security policy by invoking \fBpackage
-require\fR with the policy name. If the request is denied by the
-application's master interpreter, an error is returned.
-A tclet can \fBcatch\fR the error and request to use a different named
-policy, until a request is granted.
-.PP
-A tclet can only use one security policy during its lifetime. Once an
-invocation of \fBpackage require\fR to load a security policy succeeds,
-Safe Tcl prevents subsequent invocations of \fBpackage require\fR from
-succeeding if the requested package is a security policy. There is also no
-mechanism for a tclet to stop using a security policy, once it is loaded.
-Invocations of \fBpackage require\fR to load other packages unrelated to
-security policies will still succeed.
-.PP
-These restrictions are designed to prevent a tclet from composing security
-policies either concurrently or sequentially, in ways not supported or
-forseen by the authors of the policies. Allowing such composition would
-expose the application to unknown security risks, because a security policy
-that is safe in isolation is not necessarily safe when used in conjunction
-with other security policies.
-For example, a security policy that allows read\-only access to the local
-file system can not disclose private data belonging to the application if
-it does not have access to network communication commands such as
-\fBsocket\fR. However, when used in conjunction with another security
-policy that enables the \fBsocket\fR command, this policy is no longer
-safe.
+.SH OPTIONS
+The following options are common to
+\fB::safe::interpCreate\fR, \fB::safe::interpInit\fR,
+and \fB::safe::interpConfigure\fR.
+Any option name can be abbreviated to its minimal
+non-ambiguous name.
+Option names are not case sensitive.
+.TP
+\fB\-accessPath\fR ?\fIdirectoryList\fR?
+This option sets the list of directories from which the safe interpreter
+can \fBsource\fR and \fBload\fR files, and returns a list of tokens that
+will allow the safe interpreter access to these directories.
+If a value for \fBdirectoryList\fR is not given, or if it is given as the
+empty list, the safe interpreter will use the same directories than its
+master for auto-loading.
+See the section \fBSECURITY\fR below for more detail about virtual paths,
+tokens and access control.
+.TP
+\fB\-noStatics\fR
+This option specifies that the safe interpreter will not be allowed
+to load statically linked packages (like \fBload {} Tk\fR).
+The default is that safe interpreters are allowed to load statically linked
+packages.
+.TP
+\fB\-nestedLoadOk\fR
+This option specifies that the safe interpreter will be allowed
+to load packages into its own subinterpreters.
+The default is that safe interpreters are not allowed to load packages into
+their own subinterpreters.
+.TP
+\fB\-deleteHook\fR ?\fIscript\fR?
+If \fIscript\fR is given, it is evaluated in the master with the name of
+the safe interpreter as an additional argument just before deleting the
+safe interpreter.
+If no value is given for \fIscript\fR any currently installed deletion hook
+script for that safe interpreter is removed; it will no longer be called
+when the interpreter is deleted.
+There is no deletion hook script installed by default.
-.SH "USING SAFE TCL IN APPLICATIONS"
-.PP
-An application using Safe Tcl is usually structured as one or more unsafe
-interpreters in which trusted code belonging to the application is
-executed. Each such \fBmaster interpreter\fR controls one or more safe
-\fBslave interpreters\fR in which tclets are executed.
-Tclets communicate with their master interpreter via the aliases provided
-by the Safe Base and via additional mechanisms installed by each security
-policy.
-This section describes the procedures an application invokes to use Safe
-Tcl and to manage slave interpreters.
-.PP
-An application invokes \fBtcl_safeCreateInterp\fR \fIslave\fR to create a
-new slave interpreter; this new interpreter will contain the aliases
-provided by the Safe Base. A new command named \fBslave\fR is also created
-in the invoking interpreter, to allow the application to manipulate the new
-slave interpreter.
-.PP
-An application can use \fBtcl_safeInitInterp\fR \fIslave\fR to initialize
-an existing slave interpreter with the Safe-Tcl security policy mechanism.
-This procedure is useful when an application already has a safe slave
-interpreter created with \fBinterp create -safe\fR and wishes to enable it
-to use security policies.
-.PP
-An application should invoke \fBtcl_safeDeleteInterp\fR \fIslave\fR to
-delete an interpreter previously created by \fBtcl_safeCreateInterp\fR. This
-procedure terminates the execution of the tclet in the \fIslave\fR
-interpreter and cleans up associated state maintained by the Safe Tcl
-mechanism.
-.PP
-Security policies are installed on the file system of the system on which
-the application is executing. Security policies are found in the
-\fIpolicies\fR sub-directories of directories mentioned in the
-application's \fBauto_path\fR, and in sub-directories of these
-\fIpolicies\fR directories.
+.SH SECURITY
.PP
-Safe Tcl will invoke, on behalf of an application, additional procedures
-provided by individual security policies to manage the lifecycle of those
-policies. These additional procedures are described in the next section.
+The Safe Base does not attempt to completely prevent annoyance and
+denial of service attacks. These forms of attack prevent the
+application or user from temporarily using the computer to perform
+useful work, for example by consuming all available CPU time or
+all available screen real estate.
+These attacks, while agravating, are deemed to be of lesser importance
+in general than integrity and privacy attacks that the Safe Base
+is to prevent.
-.SH "WRITING SECURITY POLICIES"
+The commands available in a safe interpreter, in addition to
+the safe set as defined in \fBinterp\fR manual page, are mediated aliases
+for \fBsource\fR, \fBload\fR, \fBexit\fR, and a safe subset of \fBfile\fR.
+The safe interpreter can also auto-load code and it can request to load
+packages.
+Because some of these commands access the local file system, there is a
+potential for information leakage about its directory structure.
+To prevent this, commands which take file names as arguments in a safe
+interpreter use tokens instead of the real directory names.
+These tokens are translated to the real directory name while a request to,
+e.g., source a file is mediated by the master interpreter.
.PP
-Writing a security policy is a complex effort that should not be undertaken
-lightly. It involves careful design, exhaustive testing, public review and
-analysis and continuous debugging.
-In addition to considering what features a security policy should provide,
-the implementer has to constantly keep in mind the security risks to which
-an application using the policy may be exposed.
-Actively considering each feature to see if it can be used to compromise an
-application will help to minimize the chance of a security mishap later on.
+To further prevent potential information leakage from sensitive files that
+are accidentally included in the set of files that can be sourced by a safe
+interpreter, the \fBsource\fR alias is restricted so that it can only
+source files with names that have the extension \fB.tcl\fR, that contain
+only one dot and that are forteen characters long or shorter.
.PP
-A security policy is a Tcl script or a shared library that is loaded into
-an unsafe master interpreter.
-A security policy consists of two parts: a \fBmanagement\fR part, concerned
-with installing the policy into safe slaves and cleaning up after a slave
-is destroyed, and a \fBruntime\fR part, concerned with actually
-implementing the features of the policy.
-.PP
-The management part of a security policy consists of two Tcl procedures or
-commands, one for installing the security policy features into a safe
-slave, and the other for cleaning up any associated state when a slave is
-destroyed.
-The names of these procedures or commands are \fIpolicy\fB_policyInit\fR
-and \fIpolicy\fB_policyFinalize, where \fIpolicy\fR is the name of the
-policy as used by the slave interpreter in the \fBpackage require\fR
-invocation.
-.PP
-The policy initialization procedure \fIpolicy\fB_policyInit\fR called in
-the master interpreter with one argument, the name of the slave
-interpreter, when a slave requests to use the \fIpolicy\fR security policy.
-Error returns indicate that the slave was denied permission to use this
-policy; the error is propagated back to the slave interpreter. Successful
-return indicates that the policy is now available in the requesting slave.
-If it decides to allow the slave to use the requested policy,
-\fIpolicy\fB_policyInit\fR should install new aliases and command into the
-slave, initialize variables both in the master interpreter and in the
-slave, and do any other initialization work to make the policy features
-available in the slave.
-Policy initialization procedures may also perform other tasks, such as
-creating policy specific state data for the new slave using this policy.
-.PP
-Policy initialization procedures should be careful to leave a clean state
-in the slave interpreter if a failure occurs during initialization; the
-rule is that if an error is returned, no changes in any variables,
-procedures or aliases should be detectable in the slave.
-For example, if use of a security policy requires creation
-of a socket to a remote host at initialization time, and if that host is
-not accessible, all aliases created in the slave to use the policy
-should be removed. Otherwise, these aliases might open security holes when
-used in conjunction with another security policy subsequently requested by
-the slave. Without this, a malicious tclet could purposely cause a failure
-during initialization in one security policy and compose features provided
-by that policy in an unsafe manner with another security policy requested
-later.
-.PP
-When an application invokes \fBtcl_safeDeleteInterp\fR to delete a slave
-interpreter, the policy finalization procedure
-\fIpolicy\fB_policyFinalize\fR for the policy in use by the slave is called.
-It receives one argument, the name of the slave interpreter being deleted.
-This procedure should ensure that subsequently if a slave by the
-same name is re\-created, the new slave will be able to use this policy.
-It may also wish to remove any policy specific state data created by
-\fIpolicy\fB_policyInit\fR.
-.PP
-During initialization, a number of aliases may be created in the slave;
-when these aliases are invoke, they cause commands defined in the master to
-execute. The runtime part of a security policy consists of implementations
-of all the target commands that handle the invocation of aliases in the
-slave. Because these commands execute in a trusted interpreter, they have
-full access to all the capabilities of Tcl and any extensions loaded into
-the master interpreter.
-.PP
-A security policy must provide a \fBtclIndex\fR file in addition to files
-containing Tcl procedures and shared libraries implementing the policy.
-To generate a \fBtclIndex\fR file, use the Tcl command \fBauto_mkindex\fR
-which is described in the manual page for the Tcl library.
-
-.SH "INSTALLING SECURITY POLICIES"
-.PP
-Safe Tcl uses a platform dependent mechanism for obtaining the initial
-setting for the search path for finding security policies.
-On \fBUnix\fR, the environment variable \fBTCL_POLICY_PATH\fR is consulted.
-On \fBWin32\fR systems and on \fBMacOS\fR there is currently no mechanism
-provided to obtain the initial value; each application should provide its
-own mechanism for obtaining the initial search path. Such mechanisms will
-be provided shortly.
-.PP
-The search path is searched in reverse order of the order in which entries
-appear. Thus, if two or more policies by the same name occur in the path,
-the last policy by that name will be used by Safe Tcl.
-This enable system administrators to install system wide security policies
-in a centralized directory and then require users to include that directory
-as the last component in the search path. Doing so will ensure that system
-wide policies are used in preference of policies installed by individual
-users.
-.PP
-To install a policy, create a sub\-directory of one of the directories
-mentioned in the policy search path, and copy all the files comprising the
-policy into the new directory.
-Applications should be able, in most situations, to use the newly available
-policy immediately, without having to restart.
-If a security policy uses the same name as a regular package, a \fBpackage
-require\fR invocation in a slave interpreter will preferentially use the
-security policy over the regular package.
-However, if a security policy is installed after the first invocation of
-\fBpackage require\fR in an application, and a regular package exists by
-the same name, the security policy will not be available for use in that
-application. In this case you must restart the application for the policy
-to become available.
-
-.SH CREDITS
-.PP
-The security policy mechanism extends and expands on the Safe-Tcl prototype
-first implemented by Nathaniel Borenstein and Marshall Rose.
+The default value of the Tcl variable \fBauto_path\fR in a safe interpreter
+is a virtualized token list for the directories in the value of its
+master's \fBauto_path\fR variable and their immediate subdirectories.
+The first token in this list is also assigned to the Tcl varibale
+\fBtcl_library\fR in the safe interpreter.
+You can always specify a more
+restrictive path for which sub directories will never be searched by
+explicitly specifying your directory list with the \fB\-accessPath\fR flag
+instead of relying on this default mechanism.
.SH "SEE ALSO"
interp(n), library(n), load(n), package(n), source(n), unknown(n)
-
+
.SH KEYWORDS
-alias, auto\-loading, auto_mkindex, load, master interpreter, security
-policy, safe interpreter, slave interpreter, source
+alias, auto\-loading, auto_mkindex, load, master interpreter, safe
+interpreter, slave interpreter, source
diff --git a/contrib/tcl/doc/tclvars.n b/contrib/tcl/doc/tclvars.n
index 9270fcf0c899..9a7fa6ca2b34 100644
--- a/contrib/tcl/doc/tclvars.n
+++ b/contrib/tcl/doc/tclvars.n
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) tclvars.n 1.30 97/05/02 13:06:45
+'\" SCCS: @(#) tclvars.n 1.33 97/08/13 17:50:20
'\"
.so man.macros
.TH tclvars n 8.0 Tcl "Tcl Built-In Commands"
@@ -44,6 +44,64 @@ PATH variable could be exported by the operating system as ``path'',
support many special cases. All other environment variables inherited by
Tcl are left unmodified.
.RE
+.RS
+On the Macintosh, the environment variable is constructed by Tcl as no
+global environment variable exists. The environment variables that
+are created for Tcl include:
+.TP
+\fBLOGIN\fR
+This holds the Chooser name of the Macintosh.
+.TP
+\fBUSER\fR
+This also holds the Chooser name of the Macintosh.
+.TP
+\fBSYS_FOLDER\fR
+The path to the system directory.
+.TP
+\fBAPPLE_M_FOLDER\fR
+The path to the Apple Menu directory.
+.TP
+\fBCP_FOLDER\fR
+The path to the control panels directory.
+.TP
+\fBDESK_FOLDER\fR
+The path to the desk top directory.
+.TP
+\fBEXT_FOLDER\fR
+The path to the system extensions directory.
+.TP
+\fBPREF_FOLDER\fR
+The path to the preferences directory.
+.TP
+\fBPRINT_MON_FOLDER\fR
+The path to the print monitor directory.
+.TP
+\fBSHARED_TRASH_FOLDER\fR
+The path to the network trash directory.
+.TP
+\fBTRASH_FOLDER\fR
+The path to the trash directory.
+.TP
+\fBSTART_UP_FOLDER\fR
+The path to the start up directory.
+.TP
+\fBPWD\fR
+The path to the application's default directory.
+.PP
+You can also create your own environment variables for the Macintosh.
+A file named \fITcl Environment Variables\fR may be placed in the
+preferences folder in the Mac system folder. Each line of this file
+should be of the form \fIVAR_NAME=var_data\fR.
+.PP
+The last alternative is to place environment variables in a 'STR#'
+resource named \fITcl Environment Variables\fR of the application. This
+is considered a little more ``Mac like'' than a Unix style Environment
+Variable file. Each entry in the 'STR#' resource has the same format
+as above. The source code file \fItclMacEnv.c\fR contains the
+implementation of the env mechanisms. This file contains many
+#define's that allow customization of the env mechanisms to fit your
+applications needs.
+.RE
.TP
\fBerrorCode\fR
After an error has occurred, this variable will be set to hold
@@ -213,15 +271,21 @@ general operating environment of the machine.
.TP
\fBtcl_precision\fR
.VS
-In Tcl versions before 8.0, this variable controlled the
-number of significant digits to include when converting floating-point
-values to strings.
-If the variable was not set then 6 digits were included.
+This variable controls the number of digits to generate
+when converting floating-point values to strings. It defaults
+to 12.
17 digits is ``perfect'' for IEEE floating-point in that it allows
double-precision values to be converted to strings and back to
-binary with no loss of precision.
-As of Tcl 8.0 this variable is ignored and all conversions use the
-full 17 digits.
+binary with no loss of information. However, using 17 digits prevents
+any rounding, which produces longer, less intuitive results. For example,
+\fBexpr 1.4\fR returns 1.3999999999999999 with \fBtcl_precision\fR
+set to 17, vs. 1.4 if \fBtcl_precision\fR is 12.
+.RS
+All interpreters in a process share a single \fBtcl_precision\fR value:
+changing it in one interpreter will affect all other interpreters as
+well. However, safe interpreters are not allowed to modify the
+variable.
+.RE
.VE
.TP
\fBtcl_rcFileName\fR
diff --git a/contrib/tcl/doc/uplevel.n b/contrib/tcl/doc/uplevel.n
index 574900e8c07c..0332ca1c103a 100644
--- a/contrib/tcl/doc/uplevel.n
+++ b/contrib/tcl/doc/uplevel.n
@@ -1,11 +1,11 @@
'\"
'\" Copyright (c) 1993 The Regents of the University of California.
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) uplevel.n 1.7 96/03/25 20:26:46
+'\" SCCS: @(#) uplevel.n 1.8 97/08/13 13:41:36
'\"
.so man.macros
.TH uplevel n "" Tcl "Tcl Built-In Commands"
@@ -61,6 +61,20 @@ be used to obtain the level of the current procedure.
\fBUplevel\fR makes it possible to implement new control
constructs as Tcl procedures (for example, \fBuplevel\fR could
be used to implement the \fBwhile\fR construct as a Tcl procedure).
+.PP
+\fBnamespace eval\fR is another way (besides procedure calls)
+that the Tcl naming context can change.
+It adds a call frame to the stack to represent the namespace context.
+This means each \fBnamespace eval\fR command
+counts as another call level for \fBuplevel\fR and \fBupvar\fR commands.
+For example, \fBinfo level 1\fR will return a list
+describing a command that is either
+the outermost procedure call or the outermost \fBnamespace eval\fR command.
+Also, \fBuplevel #0\fR evaluates a script
+at top-level in the outermost namespace (the global namespace).
+
+.SH "SEE ALSO"
+namespace(n)
.SH KEYWORDS
-context, stack frame, variables
+context, level, namespace, stack frame, variables
diff --git a/contrib/tcl/doc/upvar.n b/contrib/tcl/doc/upvar.n
index e6e47ce0e5b0..1920d37bd7f8 100644
--- a/contrib/tcl/doc/upvar.n
+++ b/contrib/tcl/doc/upvar.n
@@ -1,11 +1,11 @@
'\"
'\" Copyright (c) 1993 The Regents of the University of California.
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) upvar.n 1.15 96/08/26 13:00:19
+'\" SCCS: @(#) upvar.n 1.16 97/08/13 13:43:34
'\"
.so man.macros
.TH upvar n "" Tcl "Tcl Built-In Commands"
@@ -57,6 +57,17 @@ Although \fBadd2\fR could have been implemented using \fBuplevel\fR
instead of \fBupvar\fR, \fBupvar\fR makes it simpler for \fBadd2\fR
to access the variable in the caller's procedure frame.
.PP
+\fBnamespace eval\fR is another way (besides procedure calls)
+that the Tcl naming context can change.
+It adds a call frame to the stack to represent the namespace context.
+This means each \fBnamespace eval\fR command
+counts as another call level for \fBuplevel\fR and \fBupvar\fR commands.
+For example, \fBinfo level 1\fR will return a list
+describing a command that is either
+the outermost procedure call or the outermost \fBnamespace eval\fR command.
+Also, \fBuplevel #0\fR evaluates a script
+at top-level in the outermost namespace (the global namespace).
+.PP
.VS
If an upvar variable is unset (e.g. \fBx\fR in \fBadd2\fR above), the
\fBunset\fR operation affects the variable it is linked to, not the
@@ -74,5 +85,8 @@ invoked). In particular, if the array is \fBenv\fR, then changes
made to \fImyVar\fR will not be passed to subprocesses correctly.
.VE
+.SH "SEE ALSO"
+namespace(n)
+
.SH KEYWORDS
-context, frame, global, level, procedure, variable
+context, frame, global, level, namespace, procedure, variable
diff --git a/contrib/tcl/doc/variable.n b/contrib/tcl/doc/variable.n
index 1475d47b5976..186e40fd97b6 100644
--- a/contrib/tcl/doc/variable.n
+++ b/contrib/tcl/doc/variable.n
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" SCCS: @(#) variable.n 1.2 97/05/18 15:20:28
+'\" SCCS: @(#) variable.n 1.4 97/08/13 16:57:57
'\"
.so man.macros
.TH variable n 8.0 Tcl "Tcl Built-In Commands"
@@ -25,9 +25,13 @@ within a namespace.
Each variable \fIname\fR is initialized with \fIvalue\fR.
The \fIvalue\fR for the last variable is optional.
.PP
-If a variable \fIname\fR does not exist,
-it is created and given the optional \fIvalue\fR.
-If it already exists, it is simply set to the optional \fIvalue\fR.
+If a variable \fIname\fR does not exist, it is created.
+In this case, if \fIvalue\fR is specified,
+it is assigned to the newly created variable.
+If no \fIvalue\fR is specified, the new variable is left undefined.
+If the variable already exists,
+it is set to \fIvalue\fR if \fIvalue\fR is specified
+or left unchanged if no \fIvalue\fR is given.
Normally, \fIname\fR is unqualified
(does not include the names of any containing namespaces),
and the variable is created in the current namespace.
@@ -51,14 +55,6 @@ and the initialization \fIvalue\fR should be left off.
After the variable has been declared,
elements within the array can be set using ordinary
\fBset\fR or \fBarray\fR commands.
-.PP
-It is generally best to provide a \fIvalue\fR to initialize each variable,
-or to initialize it immediately after the \fBvariable\fR command.
-This is because a namespace variable declared by a \fBvariable\fR command
-is not actually created until it is given a value.
-A declared but not yet initialized namespace variable
-will not appear in the output of an \fBinfo vars\fR command,
-for example.
.SH "SEE ALSO"
global(n), namespace(n)