summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authordkf <donal.k.fellows@manchester.ac.uk>2010-02-10 16:12:11 (GMT)
committerdkf <donal.k.fellows@manchester.ac.uk>2010-02-10 16:12:11 (GMT)
commit4b0dfd608991970784e6307be9a228fdc90a3a7c (patch)
treecc01d8a5c675deaeacf5ada16045982cf6a06992
parente53c72ec7777ca400d4295c0be106a5c4260ee84 (diff)
downloadtcl-4b0dfd608991970784e6307be9a228fdc90a3a7c.zip
tcl-4b0dfd608991970784e6307be9a228fdc90a3a7c.tar.gz
tcl-4b0dfd608991970784e6307be9a228fdc90a3a7c.tar.bz2
Improvements to zlib documentation (and formatting of it).
-rw-r--r--doc/TclZlib.369
-rw-r--r--doc/zlib.n6
-rwxr-xr-xtools/tcltk-man2html.tcl6
3 files changed, 71 insertions, 10 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.
diff --git a/doc/zlib.n b/doc/zlib.n
index 48182bc..6c2af2f 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.7 2009/01/24 00:03:18 dkf Exp $
+'\" RCS: @(#) $Id: zlib.n,v 1.8 2010/02/10 16:12:11 dkf Exp $
'\"
.so man.macros
.TH zlib n 8.6 Tcl "Tcl Built-In Commands"
@@ -75,8 +75,8 @@ The size of the uncompressed data.
\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.
+named by the \fBfilename\fR field was modified. Suitable for use with
+\fBclock format\fR.
.TP
\fBtype\fR
.
diff --git a/tools/tcltk-man2html.tcl b/tools/tcltk-man2html.tcl
index 1827ae4..7af1512 100755
--- a/tools/tcltk-man2html.tcl
+++ b/tools/tcltk-man2html.tcl
@@ -18,9 +18,9 @@ package require Tcl 8.6
# Copyright (c) 1995-1997 Roger E. Critchlow Jr
# Copyright (c) 2004-2010 Donal K. Fellows
#
-# CVS: $Id: tcltk-man2html.tcl,v 1.44 2010/01/14 18:43:38 dkf Exp $
+# CVS: $Id: tcltk-man2html.tcl,v 1.45 2010/02/10 16:12:11 dkf Exp $
-regexp {\d+\.\d+} {$Revision: 1.44 $} ::Version
+regexp {\d+\.\d+} {$Revision: 1.45 $} ::Version
set ::CSSFILE "docs.css"
##
@@ -813,6 +813,7 @@ array set exclude_refs_map {
clock.n {next}
history.n {exec}
next.n {unknown}
+ zlib.n {binary filename text}
canvas.n {bitmap text}
checkbutton.n {image}
clipboard.n {string}
@@ -838,6 +839,7 @@ array set exclude_refs_map {
ttk_spinbox.n {format}
ttk_treeview.n {text open}
ttk_widget.n {image text variable}
+ TclZlib.3 {binary filename text}
}
array set exclude_when_followed_by_map {
canvas.n {