Document the zlib command. Not yet complete!

1 files changed, 102 insertions, 0 deletions

diff --git a/doc/zlib.n b/doc/zlib.n
new file mode 100644
index 0000000..256efec
--- /dev/null
+++ b/doc/zlib.n
@@ -0,0 +1,102 @@
+'\"
+'\" Copyright (c) 2008 Donal K. Fellows
+'\"
+'\" 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.1 2008/12/11 16:50:51 dkf Exp $
+'\" 
+.so man.macros
+.TH zlib n 8.6 Tcl "Tcl Built-In Commands"
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+zlib \- compression and decompression operations
+.SH SYNOPSIS
+.nf
+\fBzlib \fIsubcommand arg ...\fR
+.fi
+.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?
+.
+.TP
+\fBzlib compress\fI string\fR ?\fIlevel\fR?
+.
+.TP
+\fBzlib crc32\fI string\fR ?\fIinitValue\fR?
+.
+.TP
+\fBzlib decompress\fI string\fR ?\fIbufferSize\fR?
+.
+.TP
+\fBzlib deflate\fI string\fR ?\fIlevel\fR?
+.
+.TP
+\fBzlib gunzip\fI string\fR ?\fIbufferSize\fR?
+.
+.TP
+\fBzlib gzip\fI string\fR ?\fIlevel\fR?
+.
+.TP
+\fBzlib inflate\fI string\fR ?\fIbufferSize\fR?
+.
+.TP
+\fBzlib stack\fI channel\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:
+.RS
+.TP
+\fBzlib stream compress\fR
+.
+.TP
+\fBzlib stream decompress\fR
+.
+.TP
+\fBzlib stream deflate\fR
+.
+.TP
+\fBzlib stream gunzip\fR
+.
+.TP
+\fBzlib stream gzip\fR
+.
+.TP
+\fBzlib stream inflate\fR
+.
+.RE
+.TP
+\fBzlib unstack\fI channel\fR
+.
+Reverses the effects of \fBzlib stack\fR on the channel called \fIchannel\fR.
+.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]]
+.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]]
+.CE
+.SH "SEE ALSO"
+binary(n), chan(n), encoding(n)
+.SH "KEYWORDS"
+compress, decompress, deflate, gzip, inflate
+'\" Local Variables:
+'\" mode: nroff
+'\" End: