Improvements to zlib documentation (and formatting of it).

1 files changed, 64 insertions, 5 deletions

diff --git a/doc/TclZlib.3 b/doc/TclZlib.3
index 42d82b5..43ec0a8 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.4 2008/12/27 00:04:17 dkf Exp $
+'\" RCS: @(#) $Id: TclZlib.3,v 1.5 2010/02/10 16:12:11 dkf Exp $
 '\" 
 .so man.macros
 .TH TclZlib 3 8.6 Tcl "Tcl Library Procedures"
@@ -77,7 +77,9 @@ A dictionary that contains, or which will be updated to contain, a description
 of the gzip header associated with the compressed data. Only useful when the
 \fIformat\fR is \fBTCL_ZLIB_FORMAT_GZIP\fR or \fBTCL_ZLIB_FORMAT_AUTO\fR. If
 a NULL is passed, a default header will be used on compression and the header
-will be ignored (apart from integrity checks) on decompression.
+will be ignored (apart from integrity checks) on decompression. See the
+section \fBGZIP OPTIONS DICTIONARY\fR for details about the contents of this
+dictionary.
 .AP "unsigned int" initValue in
 The initial value for the checksum algorithm.
 .AP "unsigned char" *bytes in
@@ -129,14 +131,17 @@ checksum = \fBTcl_ZlibCRC32\fR(\fBTcl_ZlibCRC32\fR(0,NULL,0), data, length);
 linked to a Tcl command, according to its arguments, and provides an abstract
 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.
+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.
 .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
 \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.
+passed to it will have the data bytes appended to it. Internally to the
+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
@@ -144,7 +149,61 @@ whether the end of the uncompressed data has been reached.
 .PP
 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.
+equivalent (when such a command exists).
+.SH "GZIP OPTIONS DICTIONARY"
+.PP
+The \fIdictObj\fR parameter to \fBTcl_ZlibDeflate\fR, \fBTcl_ZlibInflate\fR
+and \fBTcl_ZlibStreamInit\fR is used to pass a dictionary of options about
+that is used to describe the gzip header in the compressed data. When creating
+compressed data, the dictionary is read and when unpacking compressed data the
+dictionary is written (in which case the \fIdictObj\fR parameter must refer to
+an unshared dictionary object).
+.PP
+The following fields in the dictionary object are understood. All other fields
+are ignored. No field is required when creating a gzip-format stream.
+.TP
+\fBcomment\fR
+.
+This holds the comment field of the header, if present. If absent, no comment
+was supplied (on decompression) or will be created (on compression).
+.TP
+\fBcrc\fR
+.
+A boolean value describing whether a CRC of the header is computed. Note that
+the \fBgzip\fR program does \fInot\fR use or allow a CRC on the header.
+.TP
+\fBfilename\fR
+.
+The name of the file that held the uncompressed data. This should not contain
+any directory separators, and should be sanitized before use on decompression
+with \fBfile tail\fR.
+.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. On compression, if this
+is absent then the field will be set to the
+.QW unknown
+value.
+.TP
+\fBsize\fR
+.
+The size of the uncompressed data. This is ignored on compression; the size
+of the data compressed depends on how much data is supplied to the
+compression engine.
+.TP
+\fBtime\fR
+.
+The time field from the header if non-zero, expected to be the time that the
+file named by the \fBfilename\fR field was modified. Suitable for use with
+\fBclock format\fR. On creation, the right value to use is that from
+\fBclock seconds\fR or \fBfile mtime\fR.
+.TP
+\fBtype\fR
+.
+The type of the uncompressed data (either \fBbinary\fR or \fBtext\fR) if
+known.
 .SH "PORTABILITY NOTES"
 These functions will fail gracefully if Tcl is not linked with the zlib
 library.