summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorhypnotoad <yoda@etoyoc.com>2014-09-03 10:50:06 (GMT)
committerhypnotoad <yoda@etoyoc.com>2014-09-03 10:50:06 (GMT)
commit8d1d673760dab89fb53dc4ef0f4366c432e80bd5 (patch)
treeab49f604f637be2def316ed3c4fae13ac0f18515 /doc
parentcd9922f497673e31b6fffa759cff4c869927b7fb (diff)
downloadtcl-8d1d673760dab89fb53dc4ef0f4366c432e80bd5.zip
tcl-8d1d673760dab89fb53dc4ef0f4366c432e80bd5.tar.gz
tcl-8d1d673760dab89fb53dc4ef0f4366c432e80bd5.tar.bz2
Backported dkf's documentation effort to the main core_zip_vfs branch
Diffstat (limited to 'doc')
-rw-r--r--doc/tclsh.19
-rw-r--r--doc/zvfs.n114
2 files changed, 123 insertions, 0 deletions
diff --git a/doc/tclsh.1 b/doc/tclsh.1
index 6ed5eb6..25d97c5 100644
--- a/doc/tclsh.1
+++ b/doc/tclsh.1
@@ -143,6 +143,15 @@ incomplete commands.
.SH "STANDARD CHANNELS"
.PP
See \fBTcl_StandardChannels\fR for more explanations.
+.SH ZIPVFS
+.PP
+When a zipfile is concatenated to the end of a \fBtclsh\fR, on
+startup the contents of the zip archive will be mounted as the
+virtual file system /zvfs. If a top level directory tcl8.6 is
+present in the zip archive, it will become the directory loaded
+as 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 handing.
.SH "SEE ALSO"
auto_path(n), encoding(n), env(n), fconfigure(n)
.SH KEYWORDS
diff --git a/doc/zvfs.n b/doc/zvfs.n
new file mode 100644
index 0000000..f2ad9aa
--- /dev/null
+++ b/doc/zvfs.n
@@ -0,0 +1,114 @@
+'\"
+'\" Copyright (c) 2014 Sean Woods
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.TH zvfs n 0.1 Zvfs "Zvfs Commands"
+.so man.macros
+.BS
+'\" Note: do not modify the .SH NAME line immediately below!
+.SH NAME
+zvfs \- Mount and work with ZIP files within Tcl
+.SH SYNOPSIS
+.nf
+\fBpackage require zvfs \fR?\fB0.1\fR?
+.sp
+\fB::zvfs::add\fR ?\fB\-fconfigure \fIoptpairs...\fR? \fIarchive file1\fR ?\fIfile2 ...\fR?
+\fB::zvfs::append\fR \fIarchive\fR ?\fIsource destination\fR? ?\fIsource destination...\fR?
+\fB::zvfs::dump\fR \fIzipfile\fR
+\fB::zvfs::exists\fR \fIfilename\fR
+\fB::zvfs::info\fR \fIfile\fR
+\fB::zvfs::list\fR ?\fB\-glob\fR|\fB\-regexp\fR? ?\fIpattern\fR?
+\fB::zvfs::mount ?\fIarchive\fR? ?\fImountpoint\fR?
+\fB::zvfs::start\fR \fIzipfile\fR
+\fB::zvfs::unmount \fIarchive\fR
+.fi
+.BE
+.SH DESCRIPTION
+.PP
+The \fBzvfs\fR package provides tcl with the ability to manipulate
+the contents of a zip file archive as a virtual file system.
+.TP
+\fB::zvfs::mount ?\fIarchive\fR? ?\fImountpoint\fR?
+.
+The \fB::zvfs::mount\fR procedure mounts a zipfile as a VFS.
+After this command
+executes, files contained in the ZIP archive, \fIarchive\fR, will appear to Tcl to be
+regular files at the mount point.
+.RS
+.PP
+With no \fImountpoint\fR, returns the mount point for \fIarchive\fR. With no \fIarchive\fR,
+return all archive/mount pairs. If \fImountpoint\fR is specified as an empty
+string, mount on file path.
+.RE
+.TP
+\fB::zvfs::unmount \fIarchive\fR
+.
+Unmounts a previously mounted zip, \fIarchive\fR.
+.TP
+\fB::zvfs::append\fR \fIarchive\fR ?\fIsource destination\fR? ?\fIsource destination...\fR?
+.
+This command reads \fIsource\fR files and appends them (using the name
+\fIdestination\fR) to the zip archive named \fIarchive\fR. A new zip archive is created
+if it does not already exist. If \fIarchive\fR refers to a file which exists but
+is not a zip archive, then this command turns \fIarchive\fR into a zip archive by
+appending the necessary records and the table of contents. Treat all files
+as binary.
+.RS
+.PP
+Note: No duplicate checking is done, so multiple occurances of the same file is
+allowed.
+.RE
+.TP
+\fB::zvfs::add\fR ?\fB\-fconfigure \fIoptpairs...\fR? \fIarchive file1\fR ?\fIfile2 ...\fR?
+.
+This command is similar to \fBzvfs::append\fR in that it adds files to the zip archive
+named \fIarchive\fR, however file names are relative the current directory. In
+addition, \fBfconfigure\fR is used to apply option pairs to set upon opening of
+each file. Otherwise, default translation is allowed for those file
+extensions listed in the \fB::zvfs::auto_ext\fR variable. Binary translation will be
+used for unknown extensions.
+.RS
+.PP
+NOTE: Use
+.QW "\fB\-fconfigure {}\fR"
+to use auto translation for all.
+.RE
+.TP
+\fB::zvfs::exists\fR \fIfilename\fR
+.
+Return TRUE if the given filename exists in the mounted ZVFS and FALSE if it does
+not.
+.TP
+\fB::zvfs::info\fR \fIfile\fR
+.
+Return information about the given file in the mounted ZVFS. The information
+consists of (1) the name of the ZIP archive that contains the file, (2) the
+size of the file after decompressions, (3) the compressed size of the file,
+and (4) the offset of the compressed data in the archive.
+.RS
+.PP
+Note: querying the mount point gives the start of zip data offset in (4),
+which can be used to truncate the zip info off an executable.
+.RE
+.TP
+\fB::zvfs::list\fR ?\fB\-glob\fR|\fB\-regexp\fR? ?\fIpattern\fR?
+.
+Return a list of all files in the mounted ZVFS. The order of the names in the list
+is arbitrary.
+.TP
+\fB::zvfs::dump\fR \fIzipfile\fR
+.
+Describe the contents of a zip.
+.TP
+\fB::zvfs::start\fR \fIzipfile\fR
+.
+This command strips returns the offset of zip data.
+.SH "SEE ALSO"
+tclsh(1), file(n), zlib(n)
+.SH "KEYWORDS"
+compress, filesystem, zip
+'\" Local Variables:
+'\" mode: nroff
+'\" End: