diff options
| -rw-r--r-- | ChangeLog | 5 | ||||
| -rw-r--r-- | doc/interp.n | 59 |
2 files changed, 42 insertions, 22 deletions
@@ -1,3 +1,8 @@ +2007-10-30 Donal K. Fellows <donal.k.fellows@man.ac.uk> + + * doc/interp.n: Shorten the basic descriptive text for some interp + subcommands so Solaris nroff doesn't truncate them. [Bug 1822268] + 2007-10-30 Donal K. Fellows <dkf@users.sf.net> * tools/tcltk-man2html.tcl (output-widget-options): Enhance the HTML diff --git a/doc/interp.n b/doc/interp.n index 93ef1c8..ea8dd80 100644 --- a/doc/interp.n +++ b/doc/interp.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. '\" -'\" RCS: @(#) $Id: interp.n,v 1.33 2007/10/29 11:28:50 dkf Exp $ +'\" RCS: @(#) $Id: interp.n,v 1.34 2007/10/30 14:06:40 dkf Exp $ '\" .so man.macros .TH interp n 7.6 Tcl "Tcl Built-In Commands" @@ -14,7 +14,7 @@ .SH NAME interp \- Create and manipulate Tcl interpreters .SH SYNOPSIS -\fBinterp \fIoption \fR?\fIarg arg ...\fR? +\fBinterp \fIsubcommand \fR?\fIarg arg ...\fR? .BE .SH DESCRIPTION .PP @@ -82,7 +82,7 @@ Both restrictions are motivated by safety concerns. The \fBinterp\fR command is used to create, delete, and manipulate slave interpreters, and to share or transfer channels between interpreters. It can have any of several forms, depending -on the \fIoption\fR argument: +on the \fIsubcommand\fR argument: .TP \fBinterp\fR \fBalias\fR \fIsrcPath\fR \fIsrcToken\fR Returns a Tcl list whose elements are the \fItargetCmd\fR and @@ -189,7 +189,7 @@ the slave that find out information about the slave's current state and stack frame. .TP \fBinterp exists \fIpath\fR -Returns \fB1\fR if a slave interpreter by the specified \fIpath\fR +Returns \fB1\fR if a slave interpreter by the specified \fIpath\fR exists in this master, \fB0\fR otherwise. If \fIpath\fR is omitted, the invoking interpreter is used. .TP @@ -222,29 +222,34 @@ Hidden commands are explained in more detail in \fBHIDDEN COMMANDS\fR, below. Returns a list of the names of all hidden commands in the interpreter identified by \fIpath\fR. .TP -\fBinterp\fR \fBinvokehidden\fR \fIpath\fR ?\fB\-namespace\fR \fInamespace\fR? ?\fB\-global\fR? ?\fB\-\|\-\fR? \fIhiddenCmdName\fR ?\fIarg ...\fR? +\fBinterp\fR \fBinvokehidden\fR \fIpath\fR ?\fI\-option ...\fR? \fIhiddenCmdName\fR ?\fIarg ...\fR? Invokes the hidden command \fIhiddenCmdName\fR with the arguments supplied in the interpreter denoted by \fIpath\fR. No substitutions or evaluation -are applied to the arguments. +are applied to the arguments. Three \fI\-option\fRs are supported, all +of which start with \fB\-\fR: \fB\-namespace\fR (which takes a single +argument afterwards, \fInsName\fR), \fB\-global\fR, and \fB\-\|\-\fR. If the \fB\-namespace\fR flag is present, the hidden command is invoked in -the specified namespace in the target interpreter. +the namespace called \fInsName\fR in the target interpreter. If the \fB\-global\fR flag is present, the hidden command is invoked at the global level in the target interpreter; otherwise it is invoked at the current call frame and can access local variables in that and outer call frames. +The \fB\-\|\-\fR flag allows the \fIhiddenCmdName\fR argument to start with a +.QW \- +character, and is otherwise unnecessary. If both the \fB\-namespace\fR and \fB\-global\fR flags are present, the \fB\-namespace\fR flag is ignored. Note that the hidden command will be executed (by default) in the current context stack frame of the \fIpath\fR interpreter. Hidden commands are explained in more detail in \fBHIDDEN COMMANDS\fR, below. .TP -\fBinterp\fR \fBlimit\fR \fIpath\fR \fIlimitType\fR ?\fIoption\fR? ?\fIvalue\fR \fI...\fR? +\fBinterp\fR \fBlimit\fR \fIpath\fR \fIlimitType\fR ?\fI\-option\fR? ?\fIvalue\fR \fI...\fR? .VS 8.5 Sets up, manipulates and queries the configuration of the resource limit \fIlimitType\fR for the interpreter denoted by \fIpath\fR. If -no \fIoption\fR is specified, return the current configuration of the -limit. If \fIoption\fR is the sole argument, return the value of that -option. Otherwise, a list of \fIoption\fR/\fIvalue\fR argument pairs +no \fI\-option\fR is specified, return the current configuration of the +limit. If \fI\-option\fR is the sole argument, return the value of that +option. Otherwise, a list of \fI\-option\fR/\fIvalue\fR argument pairs must supplied. See \fBRESOURCE LIMITS\fR below for a more detailed explanation of what limits and options are supported. .VE 8.5 @@ -398,15 +403,20 @@ For more details on hidden commands, see \fBHIDDEN COMMANDS\fR, below. \fIslave \fBhidden\fR Returns a list of the names of all hidden commands in \fIslave\fR. .TP -\fIslave \fBinvokehidden\fR ?\fB\-namespace\fR \fInamespace\fR? ?\fB\-global\fR ?\fB\-\|\-\fR? \fIhiddenName \fR?\fIarg ..\fR? +\fIslave \fBinvokehidden\fR ?\fI\-option ...\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. +applied to the arguments. Three \fI\-option\fRs are supported, all +of which start with \fB\-\fR: \fB\-namespace\fR (which takes a single +argument afterwards, \fInsName\fR), \fB\-global\fR, and \fB\-\|\-\fR. If the \fB\-namespace\fR flag is given, the hidden command is invoked in the specified namespace in the slave. If the \fB\-global\fR flag is given, the command is invoked at the global level in the slave; otherwise it is invoked at the current call frame and can access local variables in that or outer call frames. +The \fB\-\|\-\fR flag allows the \fIhiddenCmdName\fR argument to start with a +.QW \- +character, and is otherwise unnecessary. If both the \fB\-namespace\fR and \fB\-global\fR flags are given, the \fB\-namespace\fR flag is ignored. Note that the hidden command will be executed (by default) in the @@ -417,13 +427,13 @@ see \fBHIDDEN COMMANDS\fR, below. \fIslave \fBissafe\fR Returns \fB1\fR if the slave interpreter is safe, \fB0\fR otherwise. .TP -\fIslave \fBlimit\fR \fIlimitType\fR ?\fIoption\fR? ?\fIvalue\fR \fI...\fR? +\fIslave \fBlimit\fR \fIlimitType\fR ?\fI\-option\fR? ?\fIvalue\fR \fI...\fR? .VS 8.5 Sets up, manipulates and queries the configuration of the resource -limit \fIlimitType\fR for the slave interpreter. If no \fIoption\fR +limit \fIlimitType\fR for the slave interpreter. If no \fI\-option\fR is specified, return the current configuration of the limit. If -\fIoption\fR is the sole argument, return the value of that option. -Otherwise, a list of \fIoption\fR/\fIvalue\fR argument pairs must +\fI\-option\fR is the sole argument, return the value of that option. +Otherwise, a list of \fI\-option\fR/\fIvalue\fR argument pairs must supplied. See \fBRESOURCE LIMITS\fR below for a more detailed explanation of what limits and options are supported. .VE 8.5 @@ -685,9 +695,10 @@ catch and handle. Every limit has a number of options associated with it, some of which are common across all kinds of limits, and others of which are particular to the kind of limit. +.VE 8.5 .TP \fB\-command\fR -. +.VS 8.5 This option (common for all limit types) specifies (if non-empty) a Tcl script to be executed in the global namespace of the interpreter reading and writing the option when the particular limit in the limited interpreter is exceeded. @@ -697,33 +708,37 @@ reported through the background error mechanism (see \fBBACKGROUND ERROR HANDLING\fR). Note that the callbacks defined by one interpreter are completely isolated from the callbacks defined by another, and that the order in which those callbacks are called is undefined. +.VE 8.5 .TP \fB\-granularity\fR -. +.VS 8.5 This option (common for all limit types) specifies how frequently (out of the points when the Tcl interpreter is in a consistent state where limit checking is possible) that the limit is actually checked. This allows the tuning of how frequently a limit is checked, and hence how often the limit-checking overhead (which may be substantial in the case of time limits) is incurred. +.VE 8.5 .TP \fB\-milliseconds\fR -. +.VS 8.5 This option specifies the number of milliseconds after the moment defined in the \fB\-seconds\fR option that the time limit will fire. It should only ever be specified in conjunction with the \fB\-seconds\fR option (whether it was set previously or is being set this invocation.) +.VE 8.5 .TP \fB\-seconds\fR -. +.VS 8.5 This option specifies the number of seconds after the epoch (see \fBclock seconds\fR) that the time limit for the interpreter will be triggered. The limit will be triggered at the start of the second unless specified at a sub-second level using the \fB\-milliseconds\fR option. This option may be the empty string, which indicates that a time limit is not set for the interpreter. +.VE 8.5 .TP \fB\-value\fR -. +.VS 8.5 This option specifies the number of commands that the interpreter may execute before triggering the command limit. This option may be the empty string, which indicates that a command limit is not set for the interpreter. |