Added better docs of [binary encode] and [binary decode]

2 files changed, 99 insertions, 2 deletions

diff --git a/ChangeLog b/ChangeLog
index 86ab1dc..5bc3901 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2008-10-07  Donal K. Fellows  <dkf@users.sf.net>
+
+	* doc/binary.n: Added better documentation of the [binary encode] and
+	[binary decode] subcommands.
+
 2008-10-07  Miguel Sofer  <msofer@users.sf.net>
 
 	* generic/tclBasic.c:      Move [tailcall], [coroutine] and 
diff --git a/doc/binary.n b/doc/binary.n
index a850205..b3147cb 100644
--- a/doc/binary.n
+++ b/doc/binary.n
@@ -1,10 +1,11 @@
 '\"
 '\" Copyright (c) 1997 by Sun Microsystems, Inc.
+'\" Copyright (c) 2008 by 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: binary.n,v 1.40 2008/09/10 22:48:41 dkf Exp $
+'\" RCS: @(#) $Id: binary.n,v 1.41 2008/10/07 22:31:42 dkf Exp $
 '\" 
 .so man.macros
 .TH binary n 8.0 Tcl "Tcl Built-In Commands"
@@ -40,7 +41,86 @@ messages for example).
 .SH "BINARY ENCODE AND DECODE"
 .VS 8.6
 .PP
-\fIFIXME!\fR
+When encoding binary data as a readable string, the starting binary data is
+passed to the \fBbinary encode\fR command, together with the name of the
+encoding to use and any encoding-specific options desired. Data which has been
+encoded can be converted back to binary form using \fBbinary decode\fR. The
+following formats and options are supported.
+.TP
+\fBbase64\fR
+.
+The \fBbase64\fB binary encoding is commonly used in mail messages and XML
+documents, and uses mostly upper and lower case letters and digits. It has the
+distinction of being able to be rewrapped arbitrarily without losing
+information.
+.RS
+.PP
+During encoding, the following options are supported:
+.TP
+\fB\-maxlen \fIlength\fR
+.
+Indicates that the output should be split into lines of no more than
+\fIlength\fR characters. By default, lines are not split.
+.TP
+\fB\-wrapchar \fIcharacter\fR
+.
+Indicates that, when lines are split because of the \fB\-maxlen\fR option,
+\fIcharacter\fR should be used to separate lines. By default, this is a
+newline character,
+.QW \en .
+.PP
+During decoding, the following options are supported:
+.TP
+\fB\-strict\fR
+.
+Instructs the decoder to throw an error if it encounters any characters that
+are not strictly part of the encoding itself. Otherwise it ignores them.
+.RE
+.TP
+\fBhex\fR
+.
+The \fBhex\fR binary encoding converts each byte to a pair of hexadecimal
+digits in big-endian form.
+.RS
+.PP
+No options are supported during encoding. During decoding, the following
+options are supported:
+.TP
+\fB\-strict\fR
+.
+Instructs the decoder to throw an error if it encounters any characters that
+are not strictly part of the encoding itself. Otherwise it ignores them.
+.RE
+.TP
+\fBuuencode\fR
+.
+The \fBuuencode\fR binary encoding used to be common for transfer of data
+between Unix systems and on USENET, but is less common these days, having been
+largely superceded by the \fBbase64\fR binary encoding.
+.RS
+.PP
+During encoding, the following options are supported:
+'\" This is wrong! The uuencode format had more complexity than this!
+.TP
+\fB\-maxlen \fIlength\fR
+.
+Indicates that the output should be split into lines of no more than
+\fIlength\fR characters. By default, lines are not split.
+.TP
+\fB\-wrapchar \fIcharacter\fR
+.
+Indicates that, when lines are split because of the \fB\-maxlen\fR option,
+\fIcharacter\fR should be used to separate lines. By default, this is a
+newline character,
+.QW \en .
+.PP
+During decoding, the following options are supported:
+.TP
+\fB\-strict\fR
+.
+Instructs the decoder to throw an error if it encounters any characters that
+are not strictly part of the encoding itself. Otherwise it ignores them.
+.RE
 .VE 8.6
 .SH "BINARY FORMAT"
 .PP
@@ -798,7 +878,19 @@ proc \fIreadString\fR {channel} {
     return [encoding convertfrom utf-8 $data]
 }
 .CE
+.PP
+This converts the contents of a file (named in the variable \fIfilename\fR) to
+base64 and prints them:
+.CS
+set f [open $filename rb]
+set data [read $f]
+close $f
+puts [\fBbinary encode\fR base64 \-maxlen 64 $data]
+.CE
 .SH "SEE ALSO"
 format(n), scan(n), tclvars(n)
 .SH KEYWORDS
 binary, format, scan
+'\" Local Variables:
+'\" mode: nroff
+'\" End: