From 9074073bfc98c1f2ab6319966a4078eaae162c26 Mon Sep 17 00:00:00 2001 From: "jan.nijtmans" Date: Mon, 2 Sep 2024 11:22:51 +0000 Subject: cherrypicked typos, errors and clarifications from the documentation-cleanup-for-transition branch (those marked as 'Fix:') --- doc/ChnlStack.3 | 7 +++---- doc/CrtChnlHdlr.3 | 15 ++++++--------- doc/apply.n | 8 ++++---- doc/prefix.n | 15 +++++++++------ doc/re_syntax.n | 2 -- doc/tclsh.1 | 6 +++--- doc/zipfs.n | 17 +++++++++++++---- 7 files changed, 38 insertions(+), 32 deletions(-) diff --git a/doc/ChnlStack.3 b/doc/ChnlStack.3 index b046cd2..1278340 100644 --- a/doc/ChnlStack.3 +++ b/doc/ChnlStack.3 @@ -11,7 +11,6 @@ Tcl_StackChannel, Tcl_UnstackChannel, Tcl_GetStackedChannel, Tcl_GetTopChannel \- manipulate stacked I/O channels .SH SYNOPSIS .nf -.nf \fB#include \fR .sp Tcl_Channel @@ -25,14 +24,14 @@ Tcl_Channel .sp Tcl_Channel \fBTcl_GetTopChannel\fR(\fIchannel\fR) -.sp +.fi .SH ARGUMENTS .AS Tcl_ChannelType clientData .AP Tcl_Interp *interp in Interpreter for error reporting. .AP "const Tcl_ChannelType" *typePtr in The new channel I/O procedures to use for \fIchannel\fR. -.AP ClientData clientData in +.AP void *clientData in Arbitrary one-word value to pass to channel I/O procedures. .AP int mask in Conditions under which \fIchannel\fR will be used: OR-ed combination of @@ -91,7 +90,7 @@ channels the supplied channel is part of. channels which is just below the supplied channel. .SH "SEE ALSO" -Notifier(3), Tcl_CreateChannel(3), Tcl_OpenFileChannel(3), vwait(n). +Notifier(3), Tcl_CreateChannel(3), Tcl_OpenFileChannel(3), vwait(n) .SH KEYWORDS channel, compression diff --git a/doc/CrtChnlHdlr.3 b/doc/CrtChnlHdlr.3 index 0ecd3c9..cd817d1 100644 --- a/doc/CrtChnlHdlr.3 +++ b/doc/CrtChnlHdlr.3 @@ -12,15 +12,12 @@ Tcl_CreateChannelHandler, Tcl_DeleteChannelHandler \- call a procedure when a channel becomes readable or writable .SH SYNOPSIS .nf -.nf \fB#include \fR .sp -void \fBTcl_CreateChannelHandler\fR(\fIchannel, mask, proc, clientData\fR) .sp -void \fBTcl_DeleteChannelHandler\fR(\fIchannel, proc, clientData\fR) -.sp +.fi .SH ARGUMENTS .AS Tcl_ChannelProc clientData .AP Tcl_Channel channel in @@ -29,10 +26,10 @@ Tcl channel such as returned by \fBTcl_CreateChannel\fR. Conditions under which \fIproc\fR should be called: OR-ed combination of \fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR and \fBTCL_EXCEPTION\fR. Specify a zero value to temporarily disable an existing handler. -.AP Tcl_FileProc *proc in +.AP Tcl_ChannelProc *proc in Procedure to invoke whenever the channel indicated by \fIchannel\fR meets the conditions specified by \fImask\fR. -.AP ClientData clientData in +.AP void *clientData in Arbitrary one-word value to pass to \fIproc\fR. .BE .SH DESCRIPTION @@ -48,7 +45,7 @@ what it means for a channel to be readable or writable. .PP .CS typedef void \fBTcl_ChannelProc\fR( - ClientData \fIclientData\fR, + void *\fIclientData\fR, int \fImask\fR); .CE .PP @@ -84,6 +81,6 @@ is invoked. For this reason it may be useful to use nonblocking I/O on channels for which there are event handlers. .SH "SEE ALSO" -Notifier(3), Tcl_CreateChannel(3), Tcl_OpenFileChannel(3), vwait(n). +Notifier(3), Tcl_CreateChannel(3), Tcl_OpenFileChannel(3), vwait(n) .SH KEYWORDS -blocking, callback, channel, events, handler, nonblocking. +blocking, callback, channel, events, handler, nonblocking diff --git a/doc/apply.n b/doc/apply.n index aeb2227..be22361 100644 --- a/doc/apply.n +++ b/doc/apply.n @@ -44,18 +44,18 @@ interpreted relative to the global namespace even if its name does not start with .QW :: . .PP -The semantics of \fBapply\fR can also be described by: +The semantics of \fBapply\fR can also be described by approximately this: .PP .CS proc apply {fun args} { set len [llength $fun] if {($len < 2) || ($len > 3)} { - error "can't interpret \e"$fun\e" as anonymous function" + error "can't interpret \e"$fun\e" as anonymous function" } lassign $fun argList body ns set name ::$ns::[getGloballyUniqueName] set body0 { - rename [lindex [info level 0] 0] {} + rename [lindex [info level 0] 0] {} } proc $name $argList ${body0}$body set code [catch {uplevel 1 $name $args} res opt] @@ -96,7 +96,7 @@ set vbl abc .SH "SEE ALSO" proc(n), uplevel(n) .SH KEYWORDS -anonymous function, argument, lambda, procedure, +anonymous function, argument, lambda, procedure '\" Local Variables: '\" mode: nroff '\" End: diff --git a/doc/prefix.n b/doc/prefix.n index 309bfef..16049f3 100644 --- a/doc/prefix.n +++ b/doc/prefix.n @@ -12,8 +12,8 @@ tcl::prefix \- facilities for prefix matching .SH SYNOPSIS .nf -\fB::tcl::prefix all\fR \fItable string\fR -\fB::tcl::prefix longest\fR \fItable string\fR +\fB::tcl::prefix all\fI table string\fR +\fB::tcl::prefix longest\fI table string\fR \fB::tcl::prefix match\fR ?\fIoption ...\fR? \fItable string\fR .fi .BE @@ -21,25 +21,28 @@ tcl::prefix \- facilities for prefix matching .PP This document describes commands looking up a prefix in a list of strings. The following commands are supported: +.\" METHOD: all .TP -\fB::tcl::prefix all\fR \fItable string\fR +\fB::tcl::prefix all\fI table string\fR . Returns a list of all elements in \fItable\fR that begin with the prefix \fIstring\fR. +.\" METHOD: longest .TP -\fB::tcl::prefix longest\fR \fItable string\fR +\fB::tcl::prefix longest\fI table string\fR . Returns the longest common prefix of all elements in \fItable\fR that begin with the prefix \fIstring\fR. +.\" METHOD: match .TP -\fB::tcl::prefix match\fR ?\fIoptions\fR? \fItable string\fR +\fB::tcl::prefix match\fR ?\fIoption ...\fR? \fItable string\fR . If \fIstring\fR equals one element in \fItable\fR or is a prefix to exactly one element, the matched element is returned. If not, the result depends on the \fB\-error\fR option. (It is recommended that the \fItable\fR be sorted before use with this subcommand, so that the list of matches presented in the error message also becomes sorted, though this is not strictly necessary for -the operation of this subcommand itself.) +the operation of this subcommand itself.) The following options are supported: .RS .\" OPTION: -exact .TP diff --git a/doc/re_syntax.n b/doc/re_syntax.n index 1ece560..b214349 100644 --- a/doc/re_syntax.n +++ b/doc/re_syntax.n @@ -6,8 +6,6 @@ '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .so man.macros -.ie '\w'o''\w'\C'^o''' .ds qo \C'^o' -.el .ds qo u .TH re_syntax n "8.1" Tcl "Tcl Built-In Commands" .BS .SH NAME diff --git a/doc/tclsh.1 b/doc/tclsh.1 index 894b21e..1060fa2 100644 --- a/doc/tclsh.1 +++ b/doc/tclsh.1 @@ -166,9 +166,9 @@ VFS. If a file named \fBmain.tcl\fR is present in the top level directory of the zip archive, it will be sourced instead of tclsh's normal command line handing. If a top level directory \fBtcl_library\fR is present in the zip archive, it will become the directory loaded as -env(TCL_LIBRARY). If the file \fBtcl_library/init.tcl\fR is present in the zip -archive, the \fBtcl_library\fR global variable in the initial Tcl interpreter -is set to \fBapp/tcl_library\fR. +env(TCL_LIBRARY). If a file named \fBmain.tcl\fR is present in the top +level directory of the zip archive, it will be sourced instead of the +shell's normal command line handling. .PP Only one zipfile can be concatenated to the end of executable image (tclsh, or wish). However, if multiple zipfiles are diff --git a/doc/zipfs.n b/doc/zipfs.n index 2cf00aa..b0189f6 100644 --- a/doc/zipfs.n +++ b/doc/zipfs.n @@ -185,12 +185,14 @@ stripped prefix) determines the later root name of the archive's content. . Creates an image (potentially a new executable file) similar to \fBzipfs mkzip\fR; see that command for a description of most parameters to this -command, as they behave identically here. +command, as they behave identically here. If \fIoutfile\fR exists, it will +be silently overwritten. .RS .PP If the \fIinfile\fR parameter is specified, this file is prepended in front of the ZIP archive, otherwise the file returned by \fBinfo nameofexecutable\fR -(i.e., the executable file of the running process) is used. If the +(i.e., the executable file of the running process, +typically \fBwish\fR or \fBtclsh\fR) is used. If the \fIpassword\fR parameter is not the empty string, an obfuscated version of that password (see \fBzipfs mkkey\fR) is placed between the image and ZIP chunks of the output file and the contents of the ZIP chunk are protected with that @@ -289,6 +291,10 @@ set base [file join [\fBzipfs root\fR] myApp] \fBzipfs mount\fR $zip $base $password .CE .PP +The following example creates an executable application by appending a ZIP archive +to the tclsh file it was called from and storing the resulting executable in +the file +.QW myApp.bin . When creating an executable image with a password, the password is placed within the executable in a shrouded form so that the application can read files inside the embedded ZIP archive yet casual inspection cannot read it. @@ -300,15 +306,18 @@ set password "hunter2" # Create some simple content to define a basic application file mkdir $appDir -set f [open $appDir/main.tcl] +set f [open $appDir/main.tcl w] puts $f { puts "Hi. This is [info script]" } close $f -# Create the executable +# Create the executable application \fBzipfs mkimg\fR $img $appDir $appDir $password +# remove the now obsolete temporary appDir folder +file delete -force $appDir + # Launch the executable, printing its output to stdout exec $img >@stdout # prints the following line assuming [zipfs root] returns "//zipfs:/": -- cgit v0.12