Merge 8.7

1 files changed, 145 insertions, 25 deletions

diff --git a/doc/zipfs.n b/doc/zipfs.n
index 705faa1..9ed136d 100644
--- a/doc/zipfs.n
+++ b/doc/zipfs.n
@@ -16,10 +16,13 @@ zipfs \- Mount and work with ZIP files within Tcl
 .nf
 \fBpackage require zipfs \fR?\fB1.0\fR?
 .sp
+\fBzipfs canonical\fR ?\fImntpnt\fR? \fIfilename\fR ?\fIZIPFS\fR?
 \fBzipfs exists\fR \fIfilename\fR
-\fBzipfs find\fR \fIdir\fR
+\fBzipfs find\fR \fIdirectoryName\fR
 \fBzipfs info\fR \fIfilename\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?
@@ -27,21 +30,34 @@ zipfs \- Mount and work with ZIP files within Tcl
 \fBzipfs root\fR
 \fBzipfs unmount\fR \fImountpoint\fR
 .fi
+'\" The following subcommands are *UNDOCUMENTED* (the list here is not documentation)
+'\" \fBzipfs mount_data\fR ?\fImountpoint\fR? ?\fIdata\fR?
+'\" \fBzipfs tcl_library\fR
 .BE
 .SH DESCRIPTION
 .PP
 The \fBzipfs\fR command (the sole public command provided by the built-in
 package with the same name) provides Tcl with the ability to mount the
-contents of a ZIP file as a virtual file system.
+contents of a ZIP archive file as a virtual file system. ZIP archives support
+simple encryption, sufficient to prevent casual inspection of their contents
+but not able to prevent access by even a moderately determined attacker.
+.TP
+\fBzipfs canonical\fR ?\fImountpoint\fR? \fIfilename\fR ?\fIinZipfs\fR?
+.
+This takes the name of a file, \fIfilename\fR, and produces where it would be
+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 canonicalise the name; it defaults to true.
 .TP
 \fBzipfs exists\fR \fIfilename\fR
 .
 Return 1 if the given filename exists in the mounted zipfs and 0 if it does not.
 .TP
-\fBzipfs find\fR \fIdir\fR
+\fBzipfs find\fR \fIdirectoryName\fR
 .
-Recursively lists files including and below the directory \fIdir\fR.  The
-result list consists of relative path names starting from the given
+Recursively lists files including and below the directory \fIdirectoryName\fR.
+The result list consists of relative path names starting from the given
 directory. This command is also used by the \fBzipfs mkzip\fR and \fBzipfs
 mkimg\fR commands.
 .TP
@@ -79,6 +95,13 @@ in \fIzipfile\fR will appear to Tcl to be regular files at the mount point.
 With no \fIzipfile\fR, returns the zipfile mounted at \fImountpoint\fR.  With
 no \fImountpoint\fR, return all zipfile/mount pairs.  If \fImountpoint\fR is
 specified as an empty string, mount on file path.
+.PP
+\fBNB:\fR because the current working directory is a concept maintained by the
+operating system, using \fBcd\fR into a mounted archive will only work in the
+current process, and then not entirely consistently (e.g., if a shared library
+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
 .TP
 \fBzipfs root\fR
@@ -97,40 +120,137 @@ Unmounts a previously mounted ZIP archive mounted to \fImountpoint\fR.
 This package also provides several commands to aid the creation of ZIP
 archives as Tcl applications.
 .TP
+\fBzipfs mkzip\fR \fIoutfile 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
+password \fIpassword\fR. While processing the files below \fIindir\fR the
+optional file name prefix given in \fIstrip\fR is stripped off the beginning
+of the respective file name.  When stripping, it is common to remove either
+the whole source directory name or the name of its parent directory.
+.RS
+.PP
+\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
+.TP
 \fBzipfs mkimg\fR \fIoutfile indir\fR ?\fIstrip\fR? ?\fIpassword\fR? ?\fIinfile\fR?
 .
 Creates an image (potentially a new executable file) similar to \fBzipfs
-mkzip\fR. 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 \fIpassword\fR parameter is not empty, an obfuscated version
-of that password is placed between the image and ZIP chunks of the output file
-and the contents of the ZIP chunk are protected with that password.
+mkzip\fR; see that command for a description of most parameters to this
+command, as they behave identically here.
 .RS
 .PP
-Caution: highly experimental, not usable on Android, only partially tested on
-Linux and Windows.
+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
+\fIpassword\fR parameter is not empty, 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
+password.
+.PP
+If there is a file, \fBmain.tcl\fR, in the root directory of the resulting
+archive and the image file that the archive is attached to is a \fBtclsh\fR
+(or \fBwish\fR) instance (true by default, but depends on your configuration),
+then the resulting image is an executable that will \fBsource\fR the script in
+that \fBmain.tcl\fR after mounting the ZIP archive, and will \fBexit\fR once
+that script has been executed.
+.PP
+\fBCaution:\fR highly experimental, not usable on Android, only partially
+tested on Linux and Windows.
 .RE
 .TP
 \fBzipfs mkkey\fR \fIpassword\fR
 .
-For the clear text \fIpassword\fR argument, an obfuscated string version is
+Given the clear text \fIpassword\fR argument, an obfuscated string version is
 returned with the same format used in the \fBzipfs mkimg\fR command.
 .TP
-\fBzipfs mkzip\fR \fIoutfile indir\fR ?\fIstrip\fR? ?\fIpassword\fR?
+\fBzipfs lmkimg\fR \fIoutfile inlist\fR ?\fIpassword infile\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
-password \fIpassword\fR. While processing the files below \fIindir\fR the
-optional file name prefix given in \fIstrip\fR is stripped off the beginning
-of the respective file name.
-.RS
+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.
+.TP
+\fBzipfs lmkzip\fR \fIoutfile 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
+to be copied into the archive, and the even elements are their respective
+names within that archive.
+.SH "EXAMPLES"
 .PP
-Caution: the choice of the \fIindir\fR parameter (less the optional stripped
-prefix) determines the later root name of the archive's content.
-.RE
+Mounting an ZIP archive as an application directory and running code out of it
+before unmounting it again:
+.PP
+.CS
+set zip myApp.zip
+set base [file join [\fbzipfs root\fR] myApp]
+
+\fBzipfs mount\fR $base $zip
+# $base now has the contents of myApp.zip
+
+source [file join $base app.tcl]
+# use the contents, load libraries from it, etc...
+
+\fBzipfs unmount\fR $zip
+.CE
+.PP
+Creating a ZIP archive, given that a directory exists containing the content
+to put in the archive. Note that the source directory is given twice, in order
+to strip the exterior directory name from each filename in the archive.
+.PP
+.CS
+set sourceDirectory [file normalize myApp]
+set targetZip myApp.zip
+
+\fBzipfs mkzip\fR $targetZip $sourceDirectory $sourceDirectory
+.CE
+.PP
+Encryption can be applied to ZIP archives by providing a password when
+building the ZIP and when mounting it.
+.PP
+.CS
+set zip myApp.zip
+set sourceDir [file normalize myApp]
+set password "hunter2"
+set base [file join [\fbzipfs root\fR] myApp]
+
+# Create with password
+\fBzipfs mkzip\fR $targetZip $sourceDir $sourceDir $password
+
+# Mount with password
+\fBzipfs mount\fR $base $zip $password
+.CE
+.PP
+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.
+.PP
+.CS
+set appDir [file normalize myApp]
+set img "myApp.bin"
+set password "hunter2"
+
+# Create some simple content to define a basic application
+file mkdir $appDir
+set f [open $appDir/main.tcl]
+puts $f {
+    puts "Hi. This is [info script]"
+}
+close $f
+
+# Create the executable
+\fBzipfs mkimg\fR $img $appDir $appDir $password
+
+# Launch the executable, printing its output to stdout
+exec $img >@stdout
+#    prints: \fI Hi. This is //zipfs:/app/main.tcl\fR
+.CE
+'\" WANTED: How to use the passwords
+'\" WANTED: How to package an application
 .SH "SEE ALSO"
-tclsh(1), file(n), zlib(n)
+tclsh(1), file(n), zipfs(3), zlib(n)
 .SH "KEYWORDS"
 compress, filesystem, zip
 '\" Local Variables: