More zlib documentation improvements.

2 files changed, 59 insertions, 20 deletions

diff --git a/doc/TclZlib.3 b/doc/TclZlib.3
index 43ec0a8..6d5ec7f 100644
--- a/doc/TclZlib.3
+++ b/doc/TclZlib.3
@@ -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: TclZlib.3,v 1.5 2010/02/10 16:12:11 dkf Exp $
+'\" RCS: @(#) $Id: TclZlib.3,v 1.6 2010/02/10 23:17:06 dkf Exp $
 '\" 
 .so man.macros
 .TH TclZlib 3 8.6 Tcl "Tcl Library Procedures"
@@ -16,10 +16,10 @@ Tcl_ZlibAdler32, Tcl_ZlibCRC32, Tcl_ZlibDeflate, Tcl_ZlibInflate, Tcl_ZlibStream
 .nf
 #include <tcl.h>
 .sp
-Tcl_Obj *
+int
 \fBTcl_ZlibDeflate\fR(\fIinterp, format, dataObj, level, dictObj\fR)
 .sp
-Tcl_Obj *
+int
 \fBTcl_ZlibInflate\fR(\fIinterp, format, dataObj, dictObj\fR)
 .sp
 unsigned int
@@ -41,6 +41,9 @@ int
 \fBTcl_ZlibStreamClose\fR(\fIzshandle\fR)
 .sp
 int
+\fBTcl_ZlibStreamReset\fR(\fIzshandle\fR)
+.sp
+int
 \fBTcl_ZlibStreamChecksum\fR(\fIzshandle\fR)
 .sp
 int
@@ -112,19 +115,33 @@ bytes from the stream's buffers.
 These functions form the interface from the Tcl library to the Zlib
 library by Jean-loup Gailly and Mark Adler.
 .PP
-\fBTcl_ZlibDeflate\fR and \fBTcl_ZlibInflate\fR compress and decompress data
-respectively. Upon success, they leave the resulting compressed or
-decompressed data in a byte-array object that is the Tcl interpreter's
-result. Note that the \fIdictObj\fR parameter is only used when the
-\fIformat\fR parameter is \fBTCL_ZLIB_FORMAT_GZIP\fR or
-\fBTCL_ZLIB_FORMAT_AUTO\fR.
+\fBTcl_ZlibDeflate\fR and \fBTcl_ZlibInflate\fR respectively compress and
+decompress the data contained in the \fIdataObj\fR argument, according to the
+\fIformat\fR and, for compression, \fIlevel\fR arguments. The dictionary in
+the \fIdictObj\fR parameter is used to convey additional header information
+about the compressed data when the compression format supports it; currently,
+the dictionary is only used when the \fIformat\fR parameter is
+\fBTCL_ZLIB_FORMAT_GZIP\fR or \fBTCL_ZLIB_FORMAT_AUTO\fR. For details of the
+contents of the dictionary, see the \fBGZIP OPTIONS DICTIONARY\fR section
+below. Upon success, both functions leave the resulting compressed or
+decompressed data in a byte-array object that is the Tcl interpreter's result;
+the returned value is a standard Tcl result code.
 .PP
 \fBTcl_ZlibAdler32\fR and \fBTcl_ZlibCRC32\fR compute checksums on arrays of
-bytes. Typical usage is:
+bytes, returning the computed checksum. Checksums are computed incrementally,
+allowing data to be processed one block at a time, but this requires the
+caller to maintain the current checksum and pass it in as the \fIinitValue\fR
+parameter; the initial value to use for this can be obtained by using NULL for
+the \fIbytes\fR parameter instead of a pointer to the array of bytes to
+compute the checksum over. Thus, typical usage in the single data block case
+is like this:
 .PP
 .CS
 checksum = \fBTcl_ZlibCRC32\fR(\fBTcl_ZlibCRC32\fR(0,NULL,0), data, length);
 .CE
+.PP
+Note that the Adler-32 algorithm is not a real checksum, but instead is a
+related type of hash that works best on longer data.
 .SS "ZLIB STREAMS"
 .PP
 \fBTcl_ZlibStreamInit\fR creates a compressing or decompressing stream that is
@@ -133,11 +150,20 @@ token for the stream and returns a normal Tcl result code;
 \fBTcl_ZlibStreamGetCommandName\fR returns the name of that command given the
 stream token, or NULL if the stream has no command. Streams are not designed
 to be thread-safe; each stream should only ever be used from the thread that
-created it.
+created it. When working with gzip streams, a dictionary (fields as given in
+the \fBGZIP OPTIONS DICTIONARY\fR section below) can be given via the
+\fIdictObj\fR parameter that on compression allows control over the generated
+headers, and on decompression allows discovery of the existing headers. Note
+that the dictionary will be written to on decompression once sufficient data
+has been read to have a complete header. This means that the dictionary must
+be an unshared object in that case; a blank object created with
+\fBTcl_NewObj\fR is suggested.
 .PP
 Once a stream has been constructed, \fBTcl_ZlibStreamPut\fR is used to add
 data to the stream and \fBTcl_ZlibStreamGet\fR is used to retrieve data from
-the stream after processing. Both return normal Tcl result codes. With
+the stream after processing. Both return normal Tcl result codes and leave an
+error message in the result of the interpreter that the stream is registered
+with in the error case (if such a registration has been performed). With
 \fBTcl_ZlibStreamPut\fR, the data buffer object passed to it should not be
 modified afterwards. With \fBTcl_ZlibStreamGet\fR, the data buffer object
 passed to it will have the data bytes appended to it. Internally to the
@@ -145,8 +171,14 @@ stream, data is kept compressed so as to minimize the cost of buffer space.
 .PP
 \fBTcl_ZlibStreamChecksum\fR returns the checksum computed over the
 uncompressed data according to the format, and \fBTcl_ZlibStreamEof\fR returns
-whether the end of the uncompressed data has been reached.
+a boolean value indicating whether the end of the uncompressed data has been
+reached.
 .PP
+If you wish to clear a stream and reuse it for a new compression or
+decompression action, \fBTcl_ZlibStreamReset\fR will do this and return a
+normal Tcl result code to indicate whether it was successful; if the stream is
+registered with an interpreter, an error message will be left in the
+interpreter result when this function returns TCL_ERROR.
 Finally, \fBTcl_ZlibStreamClose\fR will clean up the stream and delete the
 associated command: using \fBTcl_DeleteCommand\fR on the stream's command is
 equivalent (when such a command exists).
diff --git a/doc/zlib.n b/doc/zlib.n
index 6c2af2f..f633cea 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.8 2010/02/10 16:12:11 dkf Exp $
+'\" RCS: @(#) $Id: zlib.n,v 1.9 2010/02/10 23:17:06 dkf Exp $
 '\" 
 .so man.macros
 .TH zlib n 8.6 Tcl "Tcl Built-In Commands"
@@ -126,9 +126,9 @@ The type of the data being compressed, being \fBbinary\fR or \fBtext\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"
+.SS "CHANNEL SUBCOMMAND"
 .TP
-\fBzlib push\fI mode channel\fR ?\fIoptions ...\fR
+\fBzlib push\fI mode channel\fR ?\fIoptions ...\fR?
 .
 Pushes a compressing or decompressing transformation onto the channel
 \fIchannel\fR.
@@ -167,7 +167,10 @@ gzip-format data on \fIchannel\fR, which must be writable.
 The transformation will be a decompressing transformation that reads raw
 compressed data from \fIchannel\fR, which must be readable.
 .PP
-The following options may be set when creating a transformation:
+The following options may be set when creating a transformation via
+the
+.QW "\fIoptions ...\fR"
+to the \fBzlib push\fR command:
 .TP
 \fB\-header\fI dictionary\fR
 .
@@ -184,15 +187,18 @@ How hard to compress the data. Must be an integer from 0 (uncompressed) to 9
 '\"The maximum number of bytes ahead to read.
 '\"\fITODO: not yet implemented!\fR
 .PP
-Both compressing and decompressing channel transformations add extra options
-that may be accessed through \fBchan configure\fR. These are:
+Both compressing and decompressing channel transformations add extra
+configuration options that may be accessed through \fBchan configure\fR. Each
+option is either a read-only or a write-only option. The options are:
 .TP
 \fB\-flush\fI type\fR
 .
 This write-only operation flushes the current state of the compressor to the
 underlying channel. It is only valid for compressing transformations. The
 \fItype\fR must be either \fBsync\fR or \fBfull\fR for a normal flush or an
-expensive flush respectively. Note that flushing degrades compression.
+expensive flush respectively. Flushing degrades the compression ratio, but
+makes it easier for a decompressor to recover more of the file in the case of
+data corruption.
 .TP
 \fB\-checksum\fR
 .
@@ -207,6 +213,7 @@ This read-only option, only valid for decompressing transforms that are
 processing gzip-format data, returns the dictionary describing the header read
 off the data stream.
 .RE
+.SS "STREAMING SUBCOMMAND"
 .TP
 \fBzlib stream\fI mode\fR ?\fIlevel\fR?
 .