From 3329ef058527a8da6bd82989598b9b34e85dfe07 Mon Sep 17 00:00:00 2001
From: dkf <donal.k.fellows@manchester.ac.uk>
Date: Thu, 11 Dec 2008 16:50:51 +0000
Subject: Document the zlib command. Not yet complete!

---
 ChangeLog  |   4 +++
 doc/zlib.n | 102 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 106 insertions(+)
 create mode 100644 doc/zlib.n

diff --git a/ChangeLog b/ChangeLog
index e6bafec..86f4048 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2008-12-11  Donal K. Fellows  <dkf@users.sf.net>
+
+	* doc/zlib.n: Added a start at the documentation. Still very rough.
+
 2008-12-11  Jan Nijtmans  <nijtmans@users.sf.net>
 
 	* win/Makefile.in: fix Windows build (mingw) for TIP #234 implementation
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:
-- 
cgit v0.12