Many improvements to docs

1 files changed, 222 insertions, 27 deletions

diff --git a/doc/zlib.n b/doc/zlib.n
index d1f1eed..8937e78 100644
--- a/doc/zlib.n
+++ b/doc/zlib.n
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: zlib.n,v 1.2 2008/12/12 16:34:45 dkf Exp $
+'\" RCS: @(#) $Id: zlib.n,v 1.3 2008/12/13 09:19:06 dkf Exp $
 '\" 
 .so man.macros
 .TH zlib n 8.6 Tcl "Tcl Built-In Commands"
@@ -19,35 +19,69 @@ zlib \- compression and decompression operations
 .BE
 .SH DESCRIPTION
 .PP
-The \fBzlib\fR command provides access to the compression facilities of the
-Zlib library. It has the following subcommands
-.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.
+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"
 .TP
 \fBzlib compress\fI string\fR ?\fIlevel\fR?
 .
-.TP
-\fBzlib crc32\fI string\fR ?\fIinitValue\fR?
-.
-Compute a checksum of binary string \fIstring\fR using the CRC-32 algorithm.
-If given, \fIinitValue\fR is used to initialize the checksum engine.
+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).
 .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.
 .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).
 .TP
 \fBzlib gunzip\fI string\fR ?\fB\-headerVar \fIvarName\fR?
 .
 Return the uncompressed contents of binary string \fIstring\fR, which must
 have been in gzip format. If \fB\-headerVar\fR is given, store a dictionary
 describing the contents of the gzip header in the variable called
-\fIvarName\fR.
-'\" TODO: describe dict fields
+\fIvarName\fR. The keys of the dictionary that may be present are:
+.RS
+.TP
+\fBcomment\fR
+.
+The comment field from the header, if present.
+.TP
+\fBcrc\fR
+.
+A boolean value describing whether a CRC of the header is computed.
+.TP
+\fBfilename\fR
+.
+The filename field from the header, if present.
+.TP
+\fBos\fR
+.
+The operating system type code field from the header (if not the
+QW unknown
+value). See RFC 1952 for the meaning of these codes.
+.TP
+\fBsize\fR
+.
+The size of the uncompressed data.
+.TP
+\fBtime\fR
+.
+The time field from the header if non-zero, expected to be time that the file
+named by the \fBfilename\fR field was modified. Suitable for use with \fBclock
+format\fR.
+.TP
+\fBtype\fR
+.
+The type of the uncompressed data (\fBbinary\fR or \fBtext\fR) if known.
+.RE
 .TP
 \fBzlib gzip\fI string\fR ?\fB\-level \fIlevel\fR? ?\fB\-header \fIdict\fR? 
 .
@@ -55,61 +89,222 @@ Return the compressed contents of binary string \fIstring\fR in gzip format.
 If \fB\-level\fR is given, \fIlevel\fR gives the compression level to use
 (from 0, which is uncompressed, to 9, maximally compressed). If \fB\-header\fR
 is given, \fIdict\fR is a dictionary containing values used for the gzip
-header.
-'\" TODO: describe dict fields
+header. The following keys may be defined:
+.RS
+.TP
+\fBcomment\fR
+.
+Add the given comment to the header of the gzip-format data.
+.TP
+\fBcrc\fR
+.
+A boolean saying whether to compute a CRC of the header. Note that if the data
+is to be interchanged with the \fBgzip\fR program, a header CRC should
+\fInot\fR be computed.
+.TP
+\fBfilename\fR
+.
+The name of the file that the data to be compressed came from.
+.TP
+\fBos\fR
+.
+The operating system type code, which should be one of the values described in
+RFC 1952.
+.TP
+\fBtime\fR
+.
+The time that the file named in the \fBfilename\fR key was last modified. This
+will be in the same as is returned by \fBclock seconds\fR or \fBfile mtime\fR.
+.TP
+\fBtype\fR
+.
+The type of the data being compressed, being \fBbinary\fR or \fBtext\fR.
+.RE
 .TP
 \fBzlib inflate\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.
+.SS "STREAMING AND CHANNEL SUBCOMMANDS"
 .TP
-\fBzlib stack\fI channel\fR
+\fBzlib push\fI mode channel\fR ?\fIoptions ...\fR
 .
+\fITODO: not yet implemented!\fR
 .TP
 \fBzlib stream\fI mode\fR ?\fIlevel\fR?
 .
 Creates a streaming compression or decompression command based on the
 \fImode\fR, and return the name of the command. For a description of how that
-command works, see \fBSTREAMING COMMAND\fR below. The following modes are
-supported:
+command works, see \fBSTREAMING INSTANCE COMMAND\fR below. The following modes
+are supported:
 .RS
 .TP
-\fBzlib stream compress\fR
+\fBzlib stream compress\fR ?\fIlevel\fR?
 .
+The stream will be a compressing stream that produces zlib-format output,
+using compression level \fIlevel\fR (if specified) which will be an integer
+from 0 to 9.
 .TP
 \fBzlib stream decompress\fR
 .
+The stream will be a decompressing stream that takes zlib-format input and
+produces uncompressed output.
 .TP
-\fBzlib stream deflate\fR
+\fBzlib stream deflate\fR ?\fIlevel\fR?
 .
+The stream will be a compressing stream that produces raw output, using
+compression level \fIlevel\fR (if specified) which will be an integer from 0
+to 9.
 .TP
 \fBzlib stream gunzip\fR
 .
+The stream will be a decompressing stream that takes gzip-format input and
+produces uncompressed output.
 .TP
-\fBzlib stream gzip\fR
+\fBzlib stream gzip\fR ?\fIlevel\fR?
 .
+The stream will be a compressing stream that produces gzip-format output,
+using compression level \fIlevel\fR (if specified) which will be an integer
+from 0 to 9.
+'\" TODO: Header dictionary!
 .TP
 \fBzlib stream inflate\fR
 .
+The stream will be a decompressing stream that takes raw compressed input and
+produces uncompressed output.
+.RE
+.SS "CHECKSUMMING SUBCOMMANDS"
+.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.
+.TP
+\fBzlib crc32\fI string\fR ?\fIinitValue\fR?
+.
+Compute a checksum of binary string \fIstring\fR using the CRC-32 algorithm.
+If given, \fIinitValue\fR is used to initialize the checksum engine.
+.SH "STREAMING INSTANCE COMMAND"
+.PP
+Streaming compression instance commands are produced by the \fBzlib stream\fR
+command. They are used by calling their \fBput\fR subcommand one or more times
+to load data in, and their \fBget\fR subcommand one or more times to extract
+the transformed data.
+.PP
+The full set of subcommands supported by a streaming instance command,
+\fIstream\fR, is as follows:
+.TP
+\fIstream \fBadd\fR ?\fIoption\fR? \Idata\fR
+.
+A short-cut for
+.QW "\fIstream \fBput \fIoption data\fR"
+followed by
+.QW "\fIstream \fBget\fR" .
+.TP
+\fIstream \fBadler32\fR
+.
+'\" Change name?
+Returns the checksum of the uncompressed data seen so far by this stream.
+.TP
+\fIstream \fBclose\fR
+.
+Deletes this stream and frees up all resources associated with it.
+.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.
+.TP
+\fIstream \fBfinalize\fR
+.
+A short-cut for
+.QW "\fIstream \fBput \-finalize {}\fR" .
+.TP
+\fIstream \fBflush\fR
+.
+A short-cut for
+.QW "\fIstream \fBput \-flush {}\fR" .
+.TP
+\fIstream \fBfullflush\fR
+.
+A short-cut for
+.QW "\fIstream \fBput \-fullflush {}\fR" .
+.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.
+.TP
+\fIstream \fBput\fR ?\fIoption\fR? \fIdata\fR
+.
+Append the contents of the binary string \fIdata\fR to \fIstream\fR's internal
+buffers while applying the transformation. If present, \fIoption\fR must be
+one of the following (or an unambiguous prefix) which are used to modify the
+way in which the transformation is applied:
+.RS
+.TP
+\fB\-finalize\fR
+.
+Mark the stream as finished, ensuring that all bytes have been wholly
+compressed or decompressed. For gzip streams, this also ensures that the
+footer is written to the stream. The stream will need to be reset before
+having more data written to it after this, though data can still be read out
+of the stream with the \fBget\fR subcommand.
+.TP
+\fB\-flush\fR
+.
+Ensure that a decompressor consuming the bytes that the current (compressing)
+stream is producing will be able to produce all the bytes that have been
+compressed so far, at some performance penalty.
+.TP
+\fB\-fullflush\fR
+.
+Ensure that not only can a decompressor handle all the bytes produced so far
+(as with \fB\-flush\fR above) but also that it can restart from this point if
+it detects that the stream is partially corrupt. This incurs a substantial
+performance penalty.
 .RE
 .TP
-\fBzlib unstack\fI channel\fR
+\fIstream \fBreset\fR
 .
-Reverses the effects of \fBzlib stack\fR on the channel called \fIchannel\fR.
+Puts any stream, including those that have been finalized or that have reached
+eof, back into a state where it can process more data. Throws away all
+internally buffered data.
 .SH EXAMPLES
 .PP
 To compress a Tcl string, it should be first converted to a particular charset
 encoding since the \fBzlib\fR command always operates on binary strings.
 .PP
 .CS
-set compressed [\fBzlib deflate\fR [encoding convertto utf8 $string]]
+set binData [encoding convertto utf-8 $string]
+set compData [\fBzlib compress\fR $binData]
 .CE
 .PP
 When converting back, it is also important to reverse the charset encoding:
 .PP
 .CS
-set string [encoding convertfrom utf8 [\fBzlib inflate\fR $compressed]]
+set binData [\fBzlib decompress\fR $compData]
+set string [encoding convertfrom utf-8 $binData]
+.CE
+.PP
+The compression operation from above can also be done with streams, which is
+especially helpful when you want to accumulate the data by stages:
+.PP
+.CS
+set strm [\fBzlib stream\fR compress]
+$\fIstrm \fBput\fR [encoding convertto utf-8 $string]
+# ...
+$\fIstrm \fBfinalize\fR
+set compData [$\fIstrm \fBget\fR]
+$\fIstrm \fBclose\fR
 .CE
 .SH "SEE ALSO"
 binary(n), chan(n), encoding(n)
+.br
+RFC1950 \- RFC1952
 .SH "KEYWORDS"
 compress, decompress, deflate, gzip, inflate
 '\" Local Variables: