diff options
| -rw-r--r-- | doc/re_syntax.n | 2 | ||||
| -rw-r--r-- | doc/refchan.n | 33 | ||||
| -rw-r--r-- | doc/regexp.n | 2 | ||||
| -rw-r--r-- | doc/registry.n | 14 | ||||
| -rw-r--r-- | doc/return.n | 6 | ||||
| -rw-r--r-- | doc/safe.n | 159 | ||||
| -rw-r--r-- | doc/self.n | 9 | ||||
| -rw-r--r-- | doc/socket.n | 4 | ||||
| -rw-r--r-- | doc/string.n | 2 | ||||
| -rw-r--r-- | doc/switch.n | 4 | ||||
| -rw-r--r-- | doc/tclsh.1 | 11 | ||||
| -rw-r--r-- | doc/tcltest.n | 55 | ||||
| -rw-r--r-- | doc/tclvars.n | 17 | ||||
| -rw-r--r-- | doc/tm.n | 5 | ||||
| -rw-r--r-- | doc/trace.n | 7 | ||||
| -rw-r--r-- | doc/upvar.n | 1 | ||||
| -rw-r--r-- | doc/vwait.n | 10 | ||||
| -rw-r--r-- | doc/zipfs.3 | 2 | ||||
| -rw-r--r-- | doc/zipfs.n | 53 | ||||
| -rw-r--r-- | doc/zlib.n | 23 |
20 files changed, 289 insertions, 130 deletions
diff --git a/doc/re_syntax.n b/doc/re_syntax.n index 3aed36d..1ece560 100644 --- a/doc/re_syntax.n +++ b/doc/re_syntax.n @@ -354,7 +354,7 @@ first non-hexadecimal character is encountered, the maximum of eight hexadecimal digits are reached, or an overflow would occur in the maximum value of \fBU+\fI10ffff\fR. .IP \fB\ev\fR 5 -vertical tab, as in C are all available. +vertical tab, as in C .IP \fB\ex\fIhh\fR 5 (where \fIhh\fR is one or two hexadecimal digits) the character whose hexadecimal value is \fB0x\fIhh\fR. diff --git a/doc/refchan.n b/doc/refchan.n index 75c8cd0..b997ddb 100644 --- a/doc/refchan.n +++ b/doc/refchan.n @@ -14,16 +14,16 @@ refchan \- command handler API of reflected channels .nf \fBchan create \fImode cmdPrefix\fR -\fIcmdPrefix \fBblocking\fR \fIchannelId mode\fR -\fIcmdPrefix \fBcget\fR \fIchannelId option\fR -\fIcmdPrefix \fBcgetall\fR \fIchannelId\fR -\fIcmdPrefix \fBconfigure\fR \fIchannelId option value\fR -\fIcmdPrefix \fBfinalize\fR \fIchannelId\fR -\fIcmdPrefix \fBinitialize\fR \fIchannelId mode\fR -\fIcmdPrefix \fBread\fR \fIchannelId count\fR -\fIcmdPrefix \fBseek\fR \fIchannelId offset base\fR -\fIcmdPrefix \fBwatch\fR \fIchannelId eventspec\fR -\fIcmdPrefix \fBwrite\fR \fIchannelId data\fR +\fIcmdPrefix \fBblocking\fI channelId mode\fR +\fIcmdPrefix \fBcget\fI channelId option\fR +\fIcmdPrefix \fBcgetall\fI channelId\fR +\fIcmdPrefix \fBconfigure\fI channelId option value\fR +\fIcmdPrefix \fBfinalize\fI channelId\fR +\fIcmdPrefix \fBinitialize\fI channelId mode\fR +\fIcmdPrefix \fBread\fI channelId count\fR +\fIcmdPrefix \fBseek\fI channelId offset base\fR +\fIcmdPrefix \fBwatch\fI channelId eventspec\fR +\fIcmdPrefix \fBwrite\fI channelId data\fR .fi .BE .SH DESCRIPTION @@ -42,6 +42,7 @@ Of all the possible subcommands, the handler \fImust\fR support \fBinitialize\fR, \fBfinalize\fR, and \fBwatch\fR. Support for the other subcommands is optional. .SS "MANDATORY SUBCOMMANDS" +.\" METHOD: initialize .TP \fIcmdPrefix \fBinitialize \fIchannelId mode\fR . @@ -72,6 +73,7 @@ will usually contain at least one element. The subcommand must throw an error if the chosen mode is not supported by the \fIcmdPrefix\fR. .RE +.\" METHOD: finalize .TP \fIcmdPrefix \fBfinalize \fIchannelId\fR . @@ -94,6 +96,7 @@ treated as (and converted to) an error. This subcommand is not invoked if the creation of the channel was aborted during \fBinitialize\fR (See above). .RE +.\" METHOD: watch .TP \fIcmdPrefix \fBwatch \fIchannelId eventspec\fR . @@ -114,6 +117,7 @@ event which was not listed in the last call to \fBwatch\fR will cause \fBchan postevent\fR to throw an error. .RE .SS "OPTIONAL SUBCOMMANDS" +.\" METHOD: read .TP \fIcmdPrefix \fBread \fIchannelId count\fR . @@ -170,6 +174,7 @@ invocation (usually \fBgets\fR, or \fBread\fR) will appear to have thrown this error. Any exception beyond \fBerror\fR, (e.g.,\ \fBbreak\fR, etc.) is treated as and converted to an error. .RE +.\" METHOD: write .TP \fIcmdPrefix \fBwrite \fIchannelId data\fR . @@ -227,6 +232,7 @@ invocation (usually \fBputs\fR) will appear to have thrown this error. Any exception beyond \fBerror\fR (e.g.,\ \fBbreak\fR, etc.) is treated as and converted to an error. .RE +.\" METHOD: seek .TP \fIcmdPrefix \fBseek \fIchannelId offset base\fR . @@ -263,6 +269,7 @@ The offset/base combination of 0/\fBcurrent\fR signals a \fBchan tell\fR request, i.e.,\ seek nothing relative to the current location, making the new location identical to the current one, which is then returned. .RE +.\" METHOD: configure .TP \fIcmdPrefix \fBconfigure \fIchannelId option value\fR . @@ -282,6 +289,7 @@ If the subcommand throws an error the command which performed the beyond \fBerror\fR (e.g.,\ \fBbreak\fR, etc.) is treated as and converted to an error. .RE +.\" METHOD: cget .TP \fIcmdPrefix \fBcget \fIchannelId option\fR . @@ -297,6 +305,7 @@ If the subcommand throws an error, the command which performed the will appear to have thrown this error. Any exception beyond \fIerror\fR (e.g.,\ \fBbreak\fR, etc.) is treated as and converted to an error. .RE +.\" METHOD: cgetall .TP \fIcmdPrefix \fBcgetall \fIchannelId\fR . @@ -313,6 +322,7 @@ If the subcommand throws an error the command which performed the will appear to have thrown this error. Any exception beyond \fBerror\fR (e.g.,\ \fBbreak\fR, etc.) is treated as and converted to an error. .RE +.\" METHOD: blocking .TP \fIcmdPrefix \fBblocking \fIchannelId mode\fR . @@ -329,8 +339,9 @@ invocation (usually \fBfconfigure\fR or \fBchan configure\fR) will appear to have thrown this error. Any exception beyond \fBerror\fR (e.g.,\ \fBbreak\fR, etc.) is treated as and converted to an error. .RE +.\" METHOD: truncate .TP -\fIcmdPrefix \fBtruncate\fR \fIchannelId length\fR +\fIcmdPrefix \fBtruncate\fI channelId length\fR . This \fIoptional\fR subcommand handles changing the length of the underlying data stream for the channel \fIchannelId\fR. Its length diff --git a/doc/regexp.n b/doc/regexp.n index 7bb97fb..f37ccbe 100644 --- a/doc/regexp.n +++ b/doc/regexp.n @@ -140,7 +140,7 @@ regular expression. Examples are: .RE .\" OPTION: -start .TP 15 -\fB\-start\fR \fIindex\fR +\fB\-start\fI index\fR . Specifies a character index offset into the string to start matching the regular expression at. diff --git a/doc/registry.n b/doc/registry.n index 8a73cc6..4defbad 100644 --- a/doc/registry.n +++ b/doc/registry.n @@ -12,10 +12,11 @@ .SH NAME registry \- Manipulate the Windows registry .SH SYNOPSIS -.sp +.nf \fBpackage require registry 1.3\fR -.sp -\fBregistry \fR?\fI\-mode\fR? \fIoption\fR \fIkeyName\fR ?\fIarg arg ...\fR? + +\fBregistry \fR?\fI\-mode\fR? \fIoption keyName\fR ?\fIarg arg ...\fR? +.fi .BE .SH DESCRIPTION .PP @@ -53,6 +54,7 @@ of the requested operation. \fIOption\fR indicates what to do with the registry key name. Any unique abbreviation for \fIoption\fR is acceptable. The valid options are: +.\" METHOD: broadcast .TP \fBregistry broadcast \fIkeyName\fR ?\fB\-timeout \fImilliseconds\fR? . @@ -79,6 +81,7 @@ set curPath [\fBregistry get\fR $regPath "Path"] \fBregistry broadcast\fR "Environment" .CE .RE +.\" METHOD: delete .TP \fBregistry delete \fIkeyName\fR ?\fIvalueName\fR? . @@ -88,6 +91,7 @@ optional \fIvalueName\fR is omitted, the specified key and any subkeys or values beneath it in the registry hierarchy will be deleted. If the key could not be deleted then an error is generated. If the key did not exist, the command has no effect. +.\" METHOD: get .TP \fBregistry get \fIkeyName valueName\fR . @@ -95,6 +99,7 @@ Returns the data associated with the value \fIvalueName\fR under the key \fIkeyName\fR. If either the key or the value does not exist, then an error is generated. For more details on the format of the returned data, see \fBSUPPORTED TYPES\fR, below. +.\" METHOD: keys .TP \fBregistry keys \fIkeyName\fR ?\fIpattern\fR? . @@ -103,6 +108,7 @@ 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 match\fR. If the specified \fIkeyName\fR does not exist, then an error is generated. +.\" METHOD: set .TP \fBregistry set \fIkeyName\fR ?\fIvalueName data \fR?\fItype\fR?? . @@ -113,12 +119,14 @@ contents of \fIvalueName\fR are set to \fIdata\fR with the type indicated by \fItype\fR. If \fItype\fR is not specified, the type \fBsz\fR is assumed. For more details on the data and type arguments, see \fBSUPPORTED TYPES\fR below. +.\" METHOD: type .TP \fBregistry type \fIkeyName valueName\fR . Returns the type of the value \fIvalueName\fR in the key \fIkeyName\fR. For more information on the possible types, see \fBSUPPORTED TYPES\fR, below. +.\" METHOD: values .TP \fBregistry values \fIkeyName\fR ?\fIpattern\fR? . diff --git a/doc/return.n b/doc/return.n index 36c09c0..9bf1ae2 100644 --- a/doc/return.n +++ b/doc/return.n @@ -13,11 +13,11 @@ .SH NAME return \- Return from a procedure, or set return code of a script .SH SYNOPSIS +.nf \fBreturn \fR?\fIresult\fR? -.sp \fBreturn \fR?\fB\-code \fIcode\fR? ?\fIresult\fR? -.sp \fBreturn \fR?\fIoption value \fR...? ?\fIresult\fR? +.fi .BE .SH DESCRIPTION .PP @@ -54,7 +54,7 @@ of the procedure is 0 (\fBTCL_OK\fR). . Error return: the return code of the procedure is 1 (\fBTCL_ERROR\fR). The procedure command behaves in its calling context as if it -were the command \fBerror\fR \fIresult\fR. See below for additional +were the command \fBerror\fI result\fR. See below for additional options. .TP 13 \fBreturn\fR (or \fB2\fR) @@ -11,28 +11,26 @@ .SH NAME safe \- Creating and manipulating safe interpreters .SH SYNOPSIS +.nf \fB::safe::interpCreate\fR ?\fIchild\fR? ?\fIoptions...\fR? -.sp -\fB::safe::interpInit\fR \fIchild\fR ?\fIoptions...\fR? -.sp -\fB::safe::interpConfigure\fR \fIchild\fR ?\fIoptions...\fR? -.sp -\fB::safe::interpDelete\fR \fIchild\fR -.sp -\fB::safe::interpAddToAccessPath\fR \fIchild\fR \fIdirectory\fR -.sp -\fB::safe::interpFindInAccessPath\fR \fIchild\fR \fIdirectory\fR -.sp +\fB::safe::interpInit\fI child\fR ?\fIoptions...\fR? +\fB::safe::interpConfigure\fI child\fR ?\fIoptions...\fR? +\fB::safe::interpDelete\fI child\fR +\fB::safe::interpAddToAccessPath\fI child directory\fR +\fB::safe::interpFindInAccessPath\fI child directory\fR \fB::safe::setSyncMode\fR ?\fInewValue\fR? -.sp \fB::safe::setLogCmd\fR ?\fIcmd arg...\fR? +.fi .SS OPTIONS -.PP -?\fB\-accessPath\fR \fIpathList\fR? -?\fB\-autoPath\fR \fIpathList\fR? -?\fB\-statics\fR \fIboolean\fR? ?\fB\-noStatics\fR? -?\fB\-nested\fR \fIboolean\fR? ?\fB\-nestedLoadOk\fR? -?\fB\-deleteHook\fR \fIscript\fR? +.nf +?\fB\-accessPath\fI pathList\fR? +?\fB\-autoPath\fI pathList\fR? +?\fB\-statics\fI boolean\fR? +?\fB\-noStatics\fR? +?\fB\-nested\fI boolean\fR? +?\fB\-nestedLoadOk\fR? +?\fB\-deleteHook\fI script\fR? +.fi .BE .SH DESCRIPTION Safe Tcl is a mechanism for executing untrusted Tcl scripts @@ -66,8 +64,10 @@ All commands provided in the parent interpreter by Safe Tcl reside in the \fBsafe\fR namespace. .SH COMMANDS The following commands are provided in the parent interpreter: +.\" COMMAND: interpCreate .TP \fB::safe::interpCreate\fR ?\fIchild\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 \fIoptions\fR. @@ -75,21 +75,27 @@ See the \fBOPTIONS\fR section below for a description of the optional arguments. If the \fIchild\fR argument is omitted, a name will be generated. \fB::safe::interpCreate\fR always returns the interpreter name. -.sp +.RS +.PP The interpreter name \fIchild\fR may include namespace separators, but may not have leading or trailing namespace separators, or excess colon characters in namespace separators. The interpreter name is qualified relative to the global namespace ::, not the namespace in which the \fB::safe::interpCreate\fR command is evaluated. +.RE +.\" COMMAND: interpInit .TP -\fB::safe::interpInit\fR \fIchild\fR ?\fIoptions...\fR? +\fB::safe::interpInit\fI child\fR ?\fIoptions...\fR? +. This command is similar to \fBinterpCreate\fR except it that does not create the safe interpreter. \fIchild\fR must have been created by some other means, like \fBinterp create\fR \fB\-safe\fR. The interpreter name \fIchild\fR may include namespace separators, subject to the same restrictions as for \fBinterpCreate\fR. +.\" COMMAND: interpConfigure .TP -\fB::safe::interpConfigure\fR \fIchild\fR ?\fIoptions...\fR? +\fB::safe::interpConfigure\fI child\fR ?\fIoptions...\fR? +. If no \fIoptions\fR are given, returns the settings for all options for the named safe interpreter as a list of options and their current values for that \fIchild\fR. @@ -115,16 +121,19 @@ set dh [safe::interpConfigure $i0 -del] safe::interpConfigure $i0 -delete {foo bar} -statics 0 .CE .RE +.\" COMMAND: interpDelete .TP -\fB::safe::interpDelete\fR \fIchild\fR +\fB::safe::interpDelete\fI child\fR . Deletes the safe interpreter and cleans up the corresponding parent 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. +.\" COMMAND: interpFindInAccessPath .TP -\fB::safe::interpFindInAccessPath\fR \fIchild\fR \fIdirectory\fR +\fB::safe::interpFindInAccessPath\fI child directory\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. @@ -136,8 +145,10 @@ $child eval [list set tk_library \e [::safe::interpFindInAccessPath $name $tk_library]] .CE .RE +.\" COMMAND: interpAddToAccessPath .TP -\fB::safe::interpAddToAccessPath\fR \fIchild\fR \fIdirectory\fR +\fB::safe::interpAddToAccessPath\fI child directory\fR +. This command adds \fIdirectory\fR to the virtual path maintained for the safe interpreter in the parent, and returns the token that can be used in the safe interpreter to obtain access to files in that directory. @@ -151,8 +162,10 @@ $child eval [list set tk_library \e [::safe::interpAddToAccessPath $name $tk_library]] .CE .RE +.\" COMMAND: setSyncMode .TP \fB::safe::setSyncMode\fR ?\fInewValue\fR? +. This command is used to get or set the "Sync Mode" of the Safe Base. When an argument is supplied, the command returns an error if the argument is not a boolean value, or if any Safe Base interpreters exist. Typically @@ -160,8 +173,10 @@ the value will be set as part of initialization - boolean true for "Sync Mode" on (the default), false for "Sync Mode" off. With "Sync Mode" on, the Safe Base keeps each child interpreter's ::auto_path synchronized with its access path. See the section \fBSYNC MODE\fR below for details. +.\" COMMAND: setLogCmd .TP \fB::safe::setLogCmd\fR ?\fIcmd arg...\fR? +. This command installs a script that will be called when interesting life cycle events occur for a safe interpreter. When called with no arguments, it returns the currently installed script. @@ -204,7 +219,8 @@ non-ambiguous name. Option names are not case sensitive. .\" OPTION: -accessPath .TP -\fB\-accessPath\fR \fIdirectoryList\fR +\fB\-accessPath\fI directoryList\fR +. This option sets the list of directories from which the safe interpreter can \fBsource\fR and \fBload\fR files. If this option is not specified, or if it is given as the @@ -214,7 +230,8 @@ See the section \fBSECURITY\fR below for more detail about virtual paths, tokens and access control. .\" OPTION: -autoPath .TP -\fB\-autoPath\fR \fIdirectoryList\fR +\fB\-autoPath\fI directoryList\fR +. This option sets the list of directories in the safe interpreter's ::auto_path. The option is undefined if the Safe Base has "Sync Mode" on - in that case the safe interpreter's ::auto_path is managed by the Safe @@ -222,7 +239,8 @@ Base and is a tokenized form of its access path. See the section \fBSYNC MODE\fR below for details. .\" OPTION: -statics .TP -\fB\-statics\fR \fIboolean\fR +\fB\-statics\fI boolean\fR +. This option specifies if the safe interpreter will be allowed to load statically linked packages (like \fBload {} Tk\fR). The default value is \fBtrue\fR : @@ -230,12 +248,14 @@ safe interpreters are allowed to load statically linked packages. .\" OPTION: -noStatics .TP \fB\-noStatics\fR +. This option is a convenience shortcut for \fB\-statics false\fR and thus specifies that the safe interpreter will not be allowed to load statically linked packages. .\" OPTION: -nested .TP -\fB\-nested\fR \fIboolean\fR +\fB\-nested\fI boolean\fR +. This option specifies if the safe interpreter will be allowed to load packages into its own sub-interpreters. The default value is \fBfalse\fR : @@ -244,12 +264,14 @@ their own sub-interpreters. .\" OPTION: -nestedLoadOk .TP \fB\-nestedLoadOk\fR +. This option is a convenience shortcut for \fB\-nested true\fR and thus specifies the safe interpreter will be allowed to load packages into its own sub-interpreters. .\" OPTION: -deleteHook .TP -\fB\-deleteHook\fR \fIscript\fR +\fB\-deleteHook\fI script\fR +. When this option is given a non-empty \fIscript\fR, it will be evaluated in the parent with the name of the safe interpreter as an additional argument @@ -260,7 +282,8 @@ The default value (\fB{}\fR) is not to have any deletion call back. .SH ALIASES The following aliases are provided in a safe interpreter: .TP -\fBsource\fR \fIfileName\fR +\fBsource\fI fileName\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 @@ -271,7 +294,8 @@ 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 +\fBload\fI fileName\fR +. The requested file, a shared object file, is dynamically loaded into the safe interpreter if it is found. The filename must contain a token name mentioned in the virtual path for @@ -280,6 +304,7 @@ 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 ?\fIsubcommand args...\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 @@ -287,12 +312,14 @@ subcommands. For more details on what these subcommands do see the manual page for the \fBfile\fR command. .TP \fBencoding\fR ?\fIsubcommand args...\fR? +. The \fBencoding\fR alias provides access to a safe subset of the subcommands of the \fBencoding\fR command; it disallows setting of the system encoding, but allows all other subcommands including \fBsystem\fR to check the current encoding. .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. .SH SECURITY @@ -463,17 +490,17 @@ safe interpreter's ::auto_path will be set to {} (by (by \fB::safe::interpConfigure\fR). If the same command specifies a new value for \fB\-autoPath\fR, it will be applied after the \fB\-accessPath\fR argument has been processed. - +.PP Examples of use with "Sync Mode" off: any of these commands will set the ::auto_path to a tokenized form of its value in the parent interpreter: .RS .PP .CS - safe::interpCreate foo - safe::interpCreate foo -accessPath {} - safe::interpInit bar - safe::interpInit bar -accessPath {} - safe::interpConfigure foo -accessPath {} +safe::interpCreate foo +safe::interpCreate foo -accessPath {} +safe::interpInit bar +safe::interpInit bar -accessPath {} +safe::interpConfigure foo -accessPath {} .CE .RE .PP @@ -483,35 +510,35 @@ own value is also specified: .RS .PP .CS - safe::interpCreate foo -accessPath { - /usr/local/TclHome/lib/tcl8.6 - /usr/local/TclHome/lib/tcl8.6/http1.0 - /usr/local/TclHome/lib/tcl8.6/opt0.4 - /usr/local/TclHome/lib/tcl8.6/msgs - /usr/local/TclHome/lib/tcl8.6/encoding - /usr/local/TclHome/lib - } +safe::interpCreate foo -accessPath { + /usr/local/TclHome/lib/tcl8.7 + /usr/local/TclHome/lib/tcl8.7/http1.0 + /usr/local/TclHome/lib/tcl8.7/opt0.4 + /usr/local/TclHome/lib/tcl8.7/msgs + /usr/local/TclHome/lib/tcl8.7/encoding + /usr/local/TclHome/lib +} - # The child's ::auto_path must be given a suitable value: +# The child's ::auto_path must be given a suitable value: - safe::interpConfigure foo -autoPath { - /usr/local/TclHome/lib/tcl8.6 - /usr/local/TclHome/lib - } +safe::interpConfigure foo -autoPath { + /usr/local/TclHome/lib/tcl8.7 + /usr/local/TclHome/lib +} - # The two commands can be combined: +# The two commands can be combined: - safe::interpCreate foo -accessPath { - /usr/local/TclHome/lib/tcl8.6 - /usr/local/TclHome/lib/tcl8.6/http1.0 - /usr/local/TclHome/lib/tcl8.6/opt0.4 - /usr/local/TclHome/lib/tcl8.6/msgs - /usr/local/TclHome/lib/tcl8.6/encoding - /usr/local/TclHome/lib - } -autoPath { - /usr/local/TclHome/lib/tcl8.6 - /usr/local/TclHome/lib - } +safe::interpCreate foo -accessPath { + /usr/local/TclHome/lib/tcl8.7 + /usr/local/TclHome/lib/tcl8.7/http1.0 + /usr/local/TclHome/lib/tcl8.7/opt0.4 + /usr/local/TclHome/lib/tcl8.7/msgs + /usr/local/TclHome/lib/tcl8.7/encoding + /usr/local/TclHome/lib +} -autoPath { + /usr/local/TclHome/lib/tcl8.7 + /usr/local/TclHome/lib +} .CE .RE .PP @@ -521,11 +548,11 @@ Example of use with "Sync Mode" off: the command .RS .PP .CS - safe::interpAddToAccessPath foo /usr/local/TclHome/lib/extras/Img1.4.11 +safe::interpAddToAccessPath foo /usr/local/TclHome/lib/extras/Img1.4.11 - lassign [safe::interpConfigure foo -autoPath] DUM childAutoPath - lappend childAutoPath /usr/local/TclHome/lib/extras/Img1.4.11 - safe::interpConfigure foo -autoPath $childAutoPath +lassign [safe::interpConfigure foo -autoPath] DUM childAutoPath +lappend childAutoPath /usr/local/TclHome/lib/extras/Img1.4.11 +safe::interpConfigure foo -autoPath $childAutoPath .CE .RE .SH "SEE ALSO" @@ -24,6 +24,7 @@ used to allow the method to discover information about how it was called. It takes an argument, \fIsubcommand\fR, that tells it what sort of information is actually desired; if omitted the result will be the same as if \fBself object\fR was invoked. The supported subcommands are: +.\" METHOD: call .TP \fBself call\fR . @@ -40,6 +41,7 @@ being a \fBmethod\fR), and the second element is an index into the first element's list that indicates which actual implementation is currently executing (the first implementation to execute is always at index 0). +.\" METHOD: caller .TP \fBself caller\fR . @@ -50,6 +52,7 @@ second element is the name of the object on which the containing method was invoked, and the third element is the name of the method (with the strings \fB<constructor>\fR and \fB<destructor>\fR indicating constructors and destructors respectively). +.\" METHOD: class .TP \fBself class\fR . @@ -66,6 +69,7 @@ construct: info object class [\fBself object\fR] .CE .RE +.\" METHOD: filter .TP \fBself filter\fR . @@ -75,17 +79,20 @@ that declared the filter (note that this may be different from the object or class that provided the implementation of the filter), the second element is either \fBobject\fR or \fBclass\fR depending on whether the declaring entity was an object or class, and the third element is the name of the filter. +.\" METHOD: method .TP \fBself method\fR . This returns the name of the current method (with the strings \fB<constructor>\fR and \fB<destructor>\fR indicating constructors and destructors respectively). +.\" METHOD: namespace .TP \fBself namespace\fR . This returns the name of the unique namespace of the object that the method was invoked upon. +.\" METHOD: next .TP \fBself next\fR . @@ -98,10 +105,12 @@ of the method (with the strings \fB<constructor>\fR and \fB<destructor>\fR indicating constructors and destructors respectively). If invoked from a method that is at the end of a call chain, this subcommand returns the empty string. +.\" METHOD: object .TP \fBself object\fR . This returns the name of the object that the method was invoked upon. +.\" METHOD: target .TP \fBself target\fR . diff --git a/doc/socket.n b/doc/socket.n index 8630bea..06d3b5b 100644 --- a/doc/socket.n +++ b/doc/socket.n @@ -12,10 +12,10 @@ .SH NAME socket \- Open a TCP network connection .SH SYNOPSIS -.sp +.nf \fBsocket \fR?\fIoptions\fR? \fIhost port\fR -.sp \fBsocket\fR \fB\-server \fIcommand\fR ?\fIoptions\fR? \fIport\fR +.fi .BE .SH DESCRIPTION .PP diff --git a/doc/string.n b/doc/string.n index 987aeae..681eb2b 100644 --- a/doc/string.n +++ b/doc/string.n @@ -445,8 +445,8 @@ and then apply \fBstring length\fR to that. \fBstring length\fR [encoding convertto utf-8 $theString] .CE .RE -.TP .\" METHOD: wordend +.TP \fBstring wordend \fIstring charIndex\fR . Returns the index of the character just after the last one in the word diff --git a/doc/switch.n b/doc/switch.n index d004c03..61449a9 100644 --- a/doc/switch.n +++ b/doc/switch.n @@ -61,7 +61,7 @@ expression matching Causes comparisons to be handled in a case-insensitive manner. .\" OPTION: -matchvar .TP 10 -\fB\-matchvar\fR \fIvarName\fR +\fB\-matchvar\fI varName\fR . This option (only legal when \fB\-regexp\fR is also specified) specifies the name of a variable into which the list of matches @@ -75,7 +75,7 @@ empty list written to it. This option may be specified at the same time as the \fB\-indexvar\fR option. .\" OPTION: -indexvar .TP 10 -\fB\-indexvar\fR \fIvarName\fR +\fB\-indexvar\fI varName\fR . This option (only legal when \fB\-regexp\fR is also specified) specifies the name of a variable into which the list of indices diff --git a/doc/tclsh.1 b/doc/tclsh.1 index 3ea9eb1..c75076f 100644 --- a/doc/tclsh.1 +++ b/doc/tclsh.1 @@ -96,6 +96,17 @@ its version number as part of the name. This has the advantage of allowing multiple versions of Tcl to exist on the same system at once, but also the disadvantage of making it harder to write scripts that start up uniformly across different versions of Tcl. +.PP +Alternatively, you can use /usr/bin/env to locate tclsh on the path, +like this: +.PP +.CS +\fB#!/usr/bin/env tclsh\fR +.CE +.PP +That has the advantages of being succinct and simple, but the +disadvantage of not being flexible in the face of varying names for +the binary. .SH "VARIABLES" .PP \fBTclsh\fR sets the following global Tcl variables in addition to those diff --git a/doc/tcltest.n b/doc/tcltest.n index 6fbf16b..f78f7a2 100644 --- a/doc/tcltest.n +++ b/doc/tcltest.n @@ -89,8 +89,9 @@ See \fBCREATING TEST SUITES WITH TCLTEST\fR below for an extended example of how to use the commands of \fBtcltest\fR to produce test suites for your Tcl-enabled code. .SH COMMANDS +.\" COMMAND: test .TP -\fBtest\fR \fIname description\fR ?\fI\-option value ...\fR? +\fBtest\fI name description\fR ?\fI\-option value ...\fR? . Defines and possibly runs a test with the name \fIname\fR and description \fIdescription\fR. The name and description of a test @@ -104,17 +105,18 @@ See \fBTESTS\fR below for a complete description of the valid options and how they define a test. The \fBtest\fR command returns an empty string. .TP -\fBtest\fR \fIname description\fR ?\fIconstraints\fR? \fIbody result\fR +\fBtest\fI name description\fR ?\fIconstraints\fR? \fIbody result\fR . This form of \fBtest\fR is provided to support test suites written for version 1 of the \fBtcltest\fR package, and also a simpler interface for a common usage. It is the same as -.QW "\fBtest\fR \fIname description\fB \-constraints \fIconstraints\fB \-body \fIbody\fB \-result \fIresult\fR" . +.QW "\fBtest\fI name description\fB \-constraints \fIconstraints\fB \-body \fIbody\fB \-result \fIresult\fR" . All other options to \fBtest\fR take their default values. When \fIconstraints\fR is omitted, this form of \fBtest\fR can be distinguished from the first because all \fIoption\fRs begin with .QW \- . +.\" COMMAND: loadTestedCommands .TP \fBloadTestedCommands\fR . @@ -124,8 +126,9 @@ Returns the result of that script evaluation, including any error raised by the script. Use this command and the related configuration options to provide the commands to be tested to the interpreter running the test suite. +.\" COMMAND: makeFile .TP -\fBmakeFile\fR \fIcontents name\fR ?\fIdirectory\fR? +\fBmakeFile\fI contents name\fR ?\fIdirectory\fR? . Creates a file named \fIname\fR relative to directory \fIdirectory\fR and write \fIcontents\fR @@ -140,16 +143,18 @@ of \fBcleanupTests\fR, unless it is removed by \fIdirectory\fR is the directory \fBconfigure \-tmpdir\fR. Returns the full path of the file created. Use this command to create any text file required by a test with contents as needed. +.\" COMMAND: removeFile .TP -\fBremoveFile\fR \fIname\fR ?\fIdirectory\fR? +\fBremoveFile\fI name\fR ?\fIdirectory\fR? . Forces the file referenced by \fIname\fR to be removed. This file name should be relative to \fIdirectory\fR. The default value of \fIdirectory\fR is the directory \fBconfigure \-tmpdir\fR. Returns an empty string. Use this command to delete files created by \fBmakeFile\fR. +.\" COMMAND: makeDirectory .TP -\fBmakeDirectory\fR \fIname\fR ?\fIdirectory\fR? +\fBmakeDirectory\fI name\fR ?\fIdirectory\fR? . Creates a directory named \fIname\fR relative to directory \fIdirectory\fR. The directory will be removed by the next evaluation of \fBcleanupTests\fR, @@ -158,8 +163,9 @@ The default value of \fIdirectory\fR is the directory \fBconfigure \-tmpdir\fR. Returns the full path of the directory created. Use this command to create any directories that are required to exist by a test. +.\" COMMAND: removeDirectory .TP -\fBremoveDirectory\fR \fIname\fR ?\fIdirectory\fR? +\fBremoveDirectory\fI name\fR ?\fIdirectory\fR? . Forces the directory referenced by \fIname\fR to be removed. This directory should be relative to \fIdirectory\fR. @@ -167,8 +173,9 @@ The default value of \fIdirectory\fR is the directory \fBconfigure \-tmpdir\fR. Returns an empty string. Use this command to delete any directories created by \fBmakeDirectory\fR. +.\" COMMAND: viewFile .TP -\fBviewFile\fR \fIfile\fR ?\fIdirectory\fR? +\fBviewFile\fI file\fR ?\fIdirectory\fR? . Returns the contents of \fIfile\fR, except for any final newline, just as \fBread \-nonewline\fR would return. @@ -180,6 +187,7 @@ by a test into the result of that test for matching against an expected result. The contents of the file are read using the system encoding, so its usefulness is limited to text files. +.\" COMMAND: cleanupTests .TP \fBcleanupTests\fR . @@ -200,6 +208,7 @@ to \fBoutputChannel\fR. This command also restores the original shell environment, as described by the global \fBenv\fR array. Returns an empty string. .RE +.\" COMMAND: runAllTests .TP \fBrunAllTests\fR . @@ -209,6 +218,7 @@ the configurable options of \fBtcltest\fR. See \fBRUNNING ALL TESTS\fR below for a complete description of the many variations possible with \fBrunAllTests\fR. .SS "CONFIGURATION COMMANDS" +.\" COMMAND: configure .TP \fBconfigure\fR . @@ -238,6 +248,7 @@ then its value is taken as a list of arguments to pass to \fBconfigure\fR. This allows the default values of the configuration options to be set by the environment. .RE +.\" COMMAND: customMatch .TP \fBcustomMatch \fImode script\fR . @@ -252,11 +263,13 @@ is evaluated in the global namespace. The completed script is expected to return a boolean value indicating whether or not the results match. The built-in matching modes of \fBtest\fR are \fBexact\fR, \fBglob\fR, and \fBregexp\fR. +.\" COMMAND: testConstraint .TP \fBtestConstraint \fIconstraint\fR ?\fIboolean\fR? . Sets or returns the boolean value associated with the named \fIconstraint\fR. See \fBTEST CONSTRAINTS\fR below for more information. +.\" COMMAND: interpreter .TP \fBinterpreter\fR ?\fIexecutableName\fR? . @@ -265,6 +278,7 @@ Sets or returns the name of the executable to be \fBexec\fRed by \fBconfigure \-singleproc\fR is false. The default value for \fBinterpreter\fR is the name of the currently running program as returned by \fBinfo nameofexecutable\fR. +.\" COMMAND: outputChannel .TP \fBoutputChannel\fR ?\fIchannelID\fR? . @@ -272,6 +286,7 @@ Sets or returns the output channel ID. This defaults to \fBstdout\fR. Any test that prints test related output should send that output to \fBoutputChannel\fR rather than letting that output default to \fBstdout\fR. +.\" COMMAND: errorChannel .TP \fBerrorChannel\fR ?\fIchannelID\fR? . @@ -280,6 +295,7 @@ Any test that prints error messages should send that output to \fBerrorChannel\fR rather than printing directly to \fBstderr\fR. .SS "SHORTCUT CONFIGURATION COMMANDS" +.\" COMMAND: debug .TP \fBdebug\fR ?\fIlevel\fR? . @@ -290,76 +306,91 @@ Same as . Same as .QW "\fBconfigure \-errfile\fR ?\fIfilename\fR?" . +.\" COMMAND: limitConstraints .TP \fBlimitConstraints\fR ?\fIboolean\fR? . Same as .QW "\fBconfigure \-limitconstraints\fR ?\fIboolean\fR?" . +.\" COMMAND: loadFile .TP \fBloadFile\fR ?\fIfilename\fR? . Same as .QW "\fBconfigure \-loadfile\fR ?\fIfilename\fR?" . +.\" COMMAND: loadScript .TP \fBloadScript\fR ?\fIscript\fR? . Same as .QW "\fBconfigure \-load\fR ?\fIscript\fR?" . +.\" COMMAND: match .TP \fBmatch\fR ?\fIpatternList\fR? . Same as .QW "\fBconfigure \-match\fR ?\fIpatternList\fR?" . +.\" COMMAND: matchDirectories .TP \fBmatchDirectories\fR ?\fIpatternList\fR? . Same as .QW "\fBconfigure \-relateddir\fR ?\fIpatternList\fR?" . +.\" COMMAND: matchFiles .TP \fBmatchFiles\fR ?\fIpatternList\fR? . Same as .QW "\fBconfigure \-file\fR ?\fIpatternList\fR?" . +.\" COMMAND: outputFile .TP \fBoutputFile\fR ?\fIfilename\fR? . Same as .QW "\fBconfigure \-outfile\fR ?\fIfilename\fR?" . +.\" COMMAND: preserveCore .TP \fBpreserveCore\fR ?\fIlevel\fR? . Same as .QW "\fBconfigure \-preservecore\fR ?\fIlevel\fR?" . +.\" COMMAND: singleProcess .TP \fBsingleProcess\fR ?\fIboolean\fR? . Same as .QW "\fBconfigure \-singleproc\fR ?\fIboolean\fR?" . +.\" COMMAND: skip .TP \fBskip\fR ?\fIpatternList\fR? . Same as .QW "\fBconfigure \-skip\fR ?\fIpatternList\fR?" . +.\" COMMAND: skipDirectories .TP \fBskipDirectories\fR ?\fIpatternList\fR? . Same as .QW "\fBconfigure \-asidefromdir\fR ?\fIpatternList\fR?" . +.\" COMMAND: skipFiles .TP \fBskipFiles\fR ?\fIpatternList\fR? . Same as .QW "\fBconfigure \-notfile\fR ?\fIpatternList\fR?" . +.\" COMMAND: temporaryDirectory .TP \fBtemporaryDirectory\fR ?\fIdirectory\fR? . Same as .QW "\fBconfigure \-tmpdir\fR ?\fIdirectory\fR?" . +.\" COMMAND: testsDirectory .TP \fBtestsDirectory\fR ?\fIdirectory\fR? . Same as .QW "\fBconfigure \-testdir\fR ?\fIdirectory\fR?" . +.\" COMMAND: verbose .TP \fBverbose\fR ?\fIlevel\fR? . @@ -372,7 +403,7 @@ alternatives provided by \fBtcltest\fR or \fBTcl\fR itself. They are retained to support existing test suites, but should be avoided in new code. .TP -\fBtest\fR \fIname description optionList\fR +\fBtest\fI name description optionList\fR . This form of \fBtest\fR was provided to enable passing many options spanning several lines to \fBtest\fR as a single @@ -396,6 +427,7 @@ If you insist on using this form, examine the source code of \fBtcltest\fR if you want to know the substitution details, or just enclose the third through last argument to \fBtest\fR in braces and hope for the best. +.\" COMMAND: workingDirectory .TP \fBworkingDirectory\fR ?\fIdirectoryName\fR? . @@ -403,6 +435,7 @@ Sets or returns the current working directory when the test suite is running. The default value for workingDirectory is the directory in which the test suite was launched. The Tcl commands \fBcd\fR and \fBpwd\fR are sufficient replacements. +.\" COMMAND: normalizeMsg .TP \fBnormalizeMsg \fImsg\fR . @@ -414,6 +447,7 @@ is rather imprecise. Tcl offers plenty of string processing commands to modify strings as you wish, and \fBcustomMatch\fR allows flexible matching of actual and expected results. +.\" COMMAND: normalizePath .TP \fBnormalizePath \fIpathVar\fR . @@ -421,6 +455,7 @@ Resolves symlinks in a path, thus creating a path without internal redirection. It is assumed that \fIpathVar\fR is absolute. \fIpathVar\fR is modified in place. The Tcl command \fBfile normalize\fR is a sufficient replacement. +.\" COMMAND: bytestring .TP \fBbytestring \fIstring\fR . @@ -445,7 +480,7 @@ also influence how \fBtest\fR operates. The valid options for \fBtest\fR are summarized: .PP .CS -\fBtest\fR \fIname\fR \fIdescription\fR +\fBtest\fI name description\fR ?\fB\-constraints \fIkeywordList|expression\fR? ?\fB\-setup \fIsetupScript\fR? ?\fB\-body \fItestScript\fR? diff --git a/doc/tclvars.n b/doc/tclvars.n index c883651..6d091c6 100644 --- a/doc/tclvars.n +++ b/doc/tclvars.n @@ -17,6 +17,7 @@ argc, argv, argv0, auto_path, env, errorCode, errorInfo, tcl_interactive, tcl_li The following global variables are created and managed automatically by the Tcl library. Except where noted below, these variables should normally be treated as read-only by application-specific code and by users. +.\" VARIABLE: auto_path .TP \fBauto_path\fR . @@ -36,6 +37,7 @@ Additional variables relating to package management exist. More details are listed in the \fBVARIABLES\fR section of the \fBlibrary\fR manual page. .RE +.\" VARIABLE: env .TP \fBenv\fR . @@ -117,6 +119,7 @@ If existing, it has the same effect as running \fBinterp debug\fR \fB{} -frame 1\fR as the very first command of each new Tcl interpreter. .RE +.\" VARIABLE: errorCode .TP \fBerrorCode\fR . @@ -213,6 +216,7 @@ If none of these methods for setting the error code has been used, the Tcl interpreter will reset the variable to \fBNONE\fR after the next error. .RE +.\" VARIABLE: errorInfo .TP \fBerrorInfo\fR . @@ -223,6 +227,7 @@ identifying the Tcl commands and procedures that were being executed when the most recent error occurred. Its contents take the form of a stack trace showing the various nested Tcl commands that had been invoked at the time of the error. +.\" VARIABLE: tcl_library .TP \fBtcl_library\fR . @@ -245,6 +250,7 @@ If \fBTCL_LIBRARY\fR is not set or doesn't refer to an appropriate directory, then Tcl checks several other directories based on a compiled-in default location, the location of the binary containing the application, and the current working directory. +.\" VARIABLE: tcl_patchLevel .TP \fBtcl_patchLevel\fR . @@ -254,6 +260,7 @@ hold a string giving the current patch level for Tcl, such as \fB8.5b3\fR for the third beta release of Tcl 8.5. The value of this variable is returned by the \fBinfo patchlevel\fR command. +.\" VARIABLE: tcl_pkgPath .TP \fBtcl_pkgPath\fR . @@ -273,6 +280,7 @@ value is added to \fBauto_path\fR at startup; changes to \fBtcl_pkgPath\fR are not reflected in \fBauto_path\fR. If you want Tcl to search additional directories for packages you should add the names of those directories to \fBauto_path\fR, not \fBtcl_pkgPath\fR. +.\" VARIABLE: tcl_platform .TP \fBtcl_platform\fR . @@ -385,6 +393,7 @@ variable. .RS Valid values for \fBtcl_precision\fR range from 0 to 17. .RE +.\" VARIABLE: tcl_rcFileName .TP \fBtcl_rcFileName\fR . @@ -394,6 +403,7 @@ initialization, then the Tcl startup code will check for the existence of this file and \fBsource\fR it if it exists. For example, for \fBwish\fR the variable is set to \fB~/.wishrc\fR for Unix and \fB~/wishrc.tcl\fR for Windows. +.\" VARIABLE: tcl_traceCompile .TP \fBtcl_traceCompile\fR . @@ -413,6 +423,7 @@ This variable and functionality only exist if \fBTCL_COMPILE_DEBUG\fR was defined during Tcl's compilation. .\" tcl::unsupported::disassemble always works, but we don't document it .RE +.\" VARIABLE: tcl_traceExec .TP \fBtcl_traceExec\fR . @@ -439,6 +450,7 @@ and interpreter. This variable and functionality only exist if \fBTCL_COMPILE_DEBUG\fR was defined during Tcl's compilation. .RE +.\" VARIABLE: tcl_wordchars .TP \fBtcl_wordchars\fR . @@ -462,6 +474,7 @@ selecting a word by double-clicking in text in Tk. It is platform dependent. On Windows, it defaults to \fB\es\fR, meaning any Unicode space character. Otherwise it defaults to \fB\eW\fR, which is anything but a Unicode word character (number, letter, or underscore). +.\" VARIABLE: tcl_version .TP \fBtcl_version\fR . @@ -477,20 +490,24 @@ command. The following variables are only guaranteed to exist in \fBtclsh\fR and \fBwish\fR executables; the Tcl library does not define them itself but many Tcl environments do. +.\" VARIABLE: argc .TP 6 \fBargc\fR . The number of arguments to \fBtclsh\fR or \fBwish\fR. +.\" VARIABLE: argv .TP 6 \fBargv\fR . Tcl list of arguments to \fBtclsh\fR or \fBwish\fR. +.\" VARIABLE: argv0 .TP 6 \fBargv0\fR . The script that \fBtclsh\fR or \fBwish\fR started executing (if it was specified) or otherwise the name by which \fBtclsh\fR or \fBwish\fR was invoked. +.\" VARIABLE: tcl_interactive .TP 6 \fBtcl_interactive\fR . @@ -23,6 +23,8 @@ tm \- Facilities for locating and loading of Tcl Modules This document describes the facilities for locating and loading Tcl Modules (see \fBMODULE DEFINITION\fR for the definition of a Tcl Module). The following commands are supported: +.\" COMMAND: path +.\" METHOD: add .TP \fB::tcl::tm::path add \fR?\fIpath\fR...? . @@ -45,16 +47,19 @@ list. As they are added to the front of the list they are searched in reverse order of addition. In other words, the paths added last are looked at first. .RE +.\" METHOD: remove .TP \fB::tcl::tm::path remove \fR?\fIpath\fR...? . Removes the paths from the list of module paths. The command silently ignores all paths which are not on the list. +.\" METHOD: list .TP \fB::tcl::tm::path list\fR . Returns a list containing all registered module paths, in the order that they are searched for modules. +.\" COMMAND: roots .TP \fB::tcl::tm::roots \fR?\fIpath\fR...? . diff --git a/doc/trace.n b/doc/trace.n index 8f3cc3d..3435585 100644 --- a/doc/trace.n +++ b/doc/trace.n @@ -19,13 +19,14 @@ trace \- Monitor variable accesses, command usages and command executions .PP This command causes Tcl commands to be executed whenever certain operations are invoked. The legal \fIoption\fRs (which may be abbreviated) are: +.\" METHOD: add .TP \fBtrace add \fItype name ops\fR ?\fIargs\fR? . Where \fItype\fR is \fBcommand\fR, \fBexecution\fR, or \fBvariable\fR. .RS .TP -\fBtrace add command\fR \fIname ops commandPrefix\fR +\fBtrace add command\fI name ops commandPrefix\fR . Arrange for \fIcommandPrefix\fR to be executed (with additional arguments) whenever command \fIname\fR is modified in one of the ways given by the list @@ -76,7 +77,7 @@ Both \fIoldName\fR and \fInewName\fR are fully qualified with any namespace(s) in which they appear. .RE .TP -\fBtrace add execution\fR \fIname ops commandPrefix\fR +\fBtrace add execution\fI name ops commandPrefix\fR . Arrange for \fIcommandPrefix\fR to be executed (with additional arguments) whenever command \fIname\fR is executed, with traces occurring at the points @@ -310,6 +311,7 @@ but will not remove traces on the overall array. This command returns an empty string. .RE .RE +.\" METHOD: remove .TP \fBtrace remove \fItype name opList commandPrefix\fR . @@ -339,6 +341,7 @@ command given by \fIopList\fR and \fIcommandPrefix\fR, then the trace is removed, so that \fIcommandPrefix\fR will never again be invoked. Returns an empty string. .RE +.\" METHOD: info .TP \fBtrace info \fItype name\fR . diff --git a/doc/upvar.n b/doc/upvar.n index 5d697dd..79f7605 100644 --- a/doc/upvar.n +++ b/doc/upvar.n @@ -14,7 +14,6 @@ upvar \- Create link to variable in a different stack frame .SH SYNOPSIS \fBupvar \fR?\fIlevel\fR? \fIotherVar myVar \fR?\fIotherVar myVar \fR...? .BE - .SH DESCRIPTION .PP This command arranges for one or more local variables in the current diff --git a/doc/vwait.n b/doc/vwait.n index fde41f6..1ff6caa 100644 --- a/doc/vwait.n +++ b/doc/vwait.n @@ -11,7 +11,7 @@ .SH NAME vwait \- Process events until a variable is written .SH SYNOPSIS -\fBvwait\fR \fIvarName\fR +\fBvwait\fI varName\fR .sp \fBvwait\fR ?\fIoptions\fR? ?\fIvarName ...\fR? .BE @@ -69,24 +69,24 @@ Timer handlers are not serviced during the wait operation. Events of the windowing system are not handled during the wait operation. .\" OPTION: -readable .TP -\fB\-readable\fR \fIchannel\fR +\fB\-readable\fI channel\fR . \fIChannel\fR must name a Tcl channel open for reading. If \fIchannel\fR is or becomes readable the wait operation completes. .\" OPTION: -timeout .TP -\fB\-timeout\fR \fImilliseconds\fR +\fB\-timeout\fI milliseconds\fR . The wait operation is constrained to \fImilliseconds\fR. .\" OPTION: -variable .TP -\fB\-variable\fR \fIvarName\fR +\fB\-variable\fI varName\fR . \fIVarName\fR must be the name of a global variable. Writing or unsetting this variable completes the wait operation. .\" OPTION: -writable .TP -\fB\-writable\fR \fIchannel\fR +\fB\-writable\fI channel\fR . \fIChannel\fR must name a Tcl channel open for writing. If \fIchannel\fR is or becomes writable the wait operation completes. diff --git a/doc/zipfs.3 b/doc/zipfs.3 index 0c2773c..31af7d7 100644 --- a/doc/zipfs.3 +++ b/doc/zipfs.3 @@ -14,7 +14,7 @@ TclZipfs_AppHook, TclZipfs_Mount, TclZipfs_MountBuffer, TclZipfs_Unmount \- hand .SH SYNOPSIS .nf const char * -\fBTclZipfs_AppHook(\fIargcPtr, argvPtr\fR) +\fBTclZipfs_AppHook\fR(\fIargcPtr, argvPtr\fR) .sp int \fBTclZipfs_Mount\fR(\fIinterp, zipname, mountpoint, password\fR) diff --git a/doc/zipfs.n b/doc/zipfs.n index dc53ea6..9ac283d 100644 --- a/doc/zipfs.n +++ b/doc/zipfs.n @@ -15,20 +15,20 @@ zipfs \- Mount and work with ZIP files within Tcl .SH SYNOPSIS .nf \fBpackage require tcl::zipfs \fR?\fB1.0\fR? -.sp + \fBzipfs canonical\fR ?\fImountpoint\fR? \fIfilename\fR ?\fIZIPFS\fR? -\fBzipfs exists\fR \fIfilename\fR -\fBzipfs find\fR \fIdirectoryName\fR -\fBzipfs info\fR \fIfilename\fR +\fBzipfs exists\fI filename\fR +\fBzipfs find\fI directoryName\fR +\fBzipfs info\fI filename\fR \fBzipfs list\fR ?(\fB\-glob\fR|\fB\-regexp\fR)? ?\fIpattern\fR? -\fBzipfs lmkimg\fR \fIoutfile inlist\fR ?\fIpassword infile\fR? -\fBzipfs lmkzip\fR \fIoutfile inlist\fR ?\fIpassword\fR? -\fBzipfs mkimg\fR \fIoutfile indir\fR ?\fIstrip\fR? ?\fIpassword\fR? ?\fIinfile\fR? -\fBzipfs mkkey\fR \fIpassword\fR -\fBzipfs mkzip\fR \fIoutfile indir\fR ?\fIstrip\fR? ?\fIpassword\fR? +\fBzipfs lmkimg\fI outfile inlist\fR ?\fIpassword infile\fR? +\fBzipfs lmkzip\fI outfile inlist\fR ?\fIpassword\fR? +\fBzipfs mkimg\fI outfile indir\fR ?\fIstrip\fR? ?\fIpassword\fR? ?\fIinfile\fR? +\fBzipfs mkkey\fI password\fR +\fBzipfs mkzip\fI outfile indir\fR ?\fIstrip\fR? ?\fIpassword\fR? \fBzipfs mount\fR ?\fIzipfile\fR? ?\fImountpoint\fR? ?\fIpassword\fR? \fBzipfs root\fR -\fBzipfs unmount\fR \fImountpoint\fR +\fBzipfs unmount\fI mountpoint\fR .fi '\" The following subcommand is *UNDOCUMENTED* '\" \fBzipfs mount_data\fR ?\fIdata\fR ?\fImountpoint\fR?? @@ -49,6 +49,7 @@ cannot be created. Further, modifications to files are limited to the mounted archive in memory and are not persisted to disk. .PP Paths in mounted archives are case-sensitive on all platforms. +.\" METHOD: canonical .TP \fBzipfs canonical\fR ?\fImountpoint\fR? \fIfilename\fR ?\fIinZipfs\fR? . @@ -57,19 +58,22 @@ mapped into a zipfs mount as its result. If specified, \fImountpoint\fR says within which mount the mapping will be done; if omitted, the main root of the zipfs system is used. The \fIinZipfs\fR argument is a an optional boolean which controls whether to fully canonicalize the name; it defaults to true. +.\" METHOD: exists .TP -\fBzipfs exists\fR \fIfilename\fR +\fBzipfs exists\fI filename\fR . Return 1 if the given filename exists in the mounted zipfs and 0 if it does not. +.\" METHOD: find .TP -\fBzipfs find\fR \fIdirectoryName\fR +\fBzipfs find\fI directoryName\fR . Returns the list of paths under directory \fIdirectoryName\fR which need not be within a zipfs mounted archive. The paths are prefixed with \fIdirectoryName\fR. This command is also used by the \fBzipfs mkzip\fR and \fBzipfs mkimg\fR commands. +.\" METHOD: info .TP -\fBzipfs info\fR \fIfile\fR +\fBzipfs info\fI file\fR . Return information about the given \fIfile\fR in the mounted zipfs. The information consists of: @@ -87,6 +91,7 @@ As a special case, querying the mount point gives the start of the zip data as the offset in (4), which can be used to truncate the zip information from an executable. Querying an ancestor of a mount point will raise an error. .RE +.\" METHOD: list .TP \fBzipfs list\fR ?(\fB\-glob\fR|\fB\-regexp\fR)? ?\fIpattern\fR? . @@ -101,12 +106,13 @@ ordinary characters in the matching. Thus forward slashes should be used as path separators in the pattern. The returned paths only include those actually in the archive and does not include intermediate directories in mount paths. +.\" METHOD: mount .TP \fBzipfs mount\fR .TP -\fBzipfs mount\fR \fImountpoint\fR +\fBzipfs mount\fI mountpoint\fR .TP -\fBzipfs mount\fR \fIzipfile\fR \fImountpoint\fR ?\fIpassword\fR? +\fBzipfs mount\fI zipfile mountpoint\fR ?\fIpassword\fR? .RS .PP The \fBzipfs mount\fR command mounts ZIP archives as Tcl virtual file systems @@ -137,6 +143,7 @@ uses direct access to the OS rather than through Tcl's filesystem API, it will not see the current directory as being inside the mount and will not be able to access the files inside the mount). .RE +.\" METHOD: root .TP \fBzipfs root\fR . @@ -145,6 +152,7 @@ for the current platform. This value is .QW \fB//zipfs:/\fR on most platforms. +.\" METHOD: unmount .TP \fBzipfs unmount \fImountpoint\fR . @@ -154,8 +162,9 @@ there are any files within the mounted archive are open. .SS "ZIP CREATION COMMANDS" This package also provides several commands to aid the creation of ZIP archives as Tcl applications. +.\" METHOD: mkzip .TP -\fBzipfs mkzip\fR \fIoutfile indir\fR ?\fIstrip\fR? ?\fIpassword\fR? +\fBzipfs mkzip\fI outfile indir\fR ?\fIstrip\fR? ?\fIpassword\fR? . Creates a ZIP archive file named \fIoutfile\fR from the contents of the input directory \fIindir\fR (contained regular files only) with optional ZIP @@ -168,8 +177,9 @@ the whole source directory name or the name of its parent directory. \fBCaution:\fR the choice of the \fIindir\fR parameter (less the optional stripped prefix) determines the later root name of the archive's content. .RE +.\" METHOD: mkimg .TP -\fBzipfs mkimg\fR \fIoutfile indir\fR ?\fIstrip\fR? ?\fIpassword\fR? ?\fIinfile\fR? +\fBzipfs mkimg\fI outfile indir\fR ?\fIstrip\fR? ?\fIpassword\fR? ?\fIinfile\fR? . Creates an image (potentially a new executable file) similar to \fBzipfs mkzip\fR; see that command for a description of most parameters to this @@ -208,20 +218,23 @@ archive to the new application. \fBCaution:\fR highly experimental, not usable on Android, only partially tested on Linux and Windows. .RE +.\" METHOD: mkkey .TP -\fBzipfs mkkey\fR \fIpassword\fR +\fBzipfs mkkey\fI password\fR . Given the clear text \fIpassword\fR argument, an obfuscated string version is returned with the same format used in the \fBzipfs mkimg\fR command. +.\" METHOD: lmkimg .TP -\fBzipfs lmkimg\fR \fIoutfile inlist\fR ?\fIpassword infile\fR? +\fBzipfs lmkimg\fI outfile inlist\fR ?\fIpassword infile\fR? . This command is like \fBzipfs mkimg\fR, but instead of an input directory, \fIinlist\fR must be a Tcl list where the odd elements are the names of files to be copied into the archive in the image, and the even elements are their respective names within that archive. +.\" METHOD: lmkzip .TP -\fBzipfs lmkzip\fR \fIoutfile inlist\fR ?\fIpassword\fR? +\fBzipfs lmkzip\fI outfile inlist\fR ?\fIpassword\fR? . This command is like \fBzipfs mkzip\fR, but instead of an input directory, \fIinlist\fR must be a Tcl list where the odd elements are the names of files @@ -21,24 +21,28 @@ The \fBzlib\fR command provides access to the compression and check-summing facilities of the Zlib library by Jean-loup Gailly and Mark Adler. It has the following subcommands. .SS "COMPRESSION SUBCOMMANDS" +.\" METHOD: compress .TP \fBzlib compress\fI string\fR ?\fIlevel\fR? . Returns the zlib-format compressed binary data of the binary string in \fIstring\fR. If present, \fIlevel\fR gives the compression level to use (from 0, which is uncompressed, to 9, maximally compressed). +.\" METHOD: decompress .TP \fBzlib decompress\fI string\fR ?\fIbufferSize\fR? . Returns the uncompressed version of the raw compressed binary data in \fIstring\fR. If present, \fIbufferSize\fR is a hint as to what size of buffer is to be used to receive the data. +.\" METHOD: deflate .TP \fBzlib deflate\fI string\fR ?\fIlevel\fR? . Returns the raw compressed binary data of the binary string in \fIstring\fR. If present, \fIlevel\fR gives the compression level to use (from 0, which is uncompressed, to 9, maximally compressed). +.\" METHOD: gunzip .TP \fBzlib gunzip\fI string\fR ?\fB\-headerVar \fIvarName\fR? . @@ -66,6 +70,7 @@ named by the \fBfilename\fR field was modified. Suitable for use with .IP \fBtype\fR The type of the uncompressed data (\fBbinary\fR or \fBtext\fR) if known. .RE +.\" METHOD: gzip .TP \fBzlib gzip\fI string\fR ?\fB\-level \fIlevel\fR? ?\fB\-header \fIdict\fR? . @@ -92,6 +97,7 @@ will be in the same as is returned by \fBclock seconds\fR or \fBfile mtime\fR. .IP \fBtype\fR The type of the data being compressed, being \fBbinary\fR or \fBtext\fR. .RE +.\" METHOD: inflate .TP \fBzlib inflate\fI string\fR ?\fIbufferSize\fR? . @@ -99,6 +105,7 @@ Returns the uncompressed version of the raw compressed binary data in \fIstring\fR. If present, \fIbufferSize\fR is a hint as to what size of buffer is to be used to receive the data. .SS "CHANNEL SUBCOMMAND" +.\" METHOD: push .TP \fBzlib push\fI mode channel\fR ?\fIoptions ...\fR? . @@ -221,6 +228,7 @@ maximum number of bytes ahead to read from the underlying data source. See above for more information. .RE .SS "STREAMING SUBCOMMAND" +.\" METHOD: stream .TP \fBzlib stream\fI mode\fR ?\fIoptions\fR? . @@ -282,11 +290,13 @@ is correct. .VE .RE .SS "CHECKSUMMING SUBCOMMANDS" +.\" METHOD: adler32 .TP \fBzlib adler32\fI string\fR ?\fIinitValue\fR? . Compute a checksum of binary string \fIstring\fR using the Adler-32 algorithm. If given, \fIinitValue\fR is used to initialize the checksum engine. +.\" METHOD: crc32 .TP \fBzlib crc32\fI string\fR ?\fIinitValue\fR? . @@ -301,6 +311,7 @@ the transformed data. .PP The full set of subcommands supported by a streaming instance command, \fIstream\fR, is as follows: +.\" METHOD: add .TP \fIstream \fBadd\fR ?\fIoption...\fR? \fIdata\fR . @@ -308,47 +319,56 @@ A short-cut for .QW "\fIstream \fBput \fR?\fIoption...\fR? \fIdata\fR" followed by .QW "\fIstream \fBget\fR" . +.\" METHOD: checksum .TP \fIstream \fBchecksum\fR . Returns the checksum of the uncompressed data seen so far by this stream. +.\" METHOD: close .TP \fIstream \fBclose\fR . Deletes this stream and frees up all resources associated with it. +.\" METHOD: eof .TP \fIstream \fBeof\fR . Returns a boolean indicating whether the end of the stream (as determined by the compressed data itself) has been reached. Not all formats support detection of the end of the stream. +.\" METHOD: finalize .TP \fIstream \fBfinalize\fR . A short-cut for .QW "\fIstream \fBput \-finalize {}\fR" . +.\" METHOD: flush .TP \fIstream \fBflush\fR . A short-cut for .QW "\fIstream \fBput \-flush {}\fR" . +.\" METHOD: fullflush .TP \fIstream \fBfullflush\fR . A short-cut for .QW "\fIstream \fBput \-fullflush {}\fR" . +.\" METHOD: get .TP \fIstream \fBget \fR?\fIcount\fR? . Return up to \fIcount\fR bytes from \fIstream\fR's internal buffers with the transformation applied. If \fIcount\fR is omitted, the entire contents of the buffers are returned. -. +.\" METHOD: header +.TP \fIstream \fBheader\fR . Return the gzip header description dictionary extracted from the stream. Only supported for streams created with their \fImode\fR parameter set to \fBgunzip\fR. +.\" METHOD: put .TP \fIstream \fBput\fR ?\fIoption...\fR? \fIdata\fR . @@ -404,6 +424,7 @@ This option is mutually exclusive with the \fB\-finalize\fR and \fB\-flush\fR options. .RE .RE +.\" METHOD: reset .TP \fIstream \fBreset\fR . |