summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authordkf <donal.k.fellows@manchester.ac.uk>2008-10-07 22:31:41 (GMT)
committerdkf <donal.k.fellows@manchester.ac.uk>2008-10-07 22:31:41 (GMT)
commit7d339460289a90d64c36b4ed7fcb390572efb438 (patch)
tree4b38d56cdc9819230369b81e5aedbda6b815f0bb
parent094983988742832968355fbb8724e2f1f75059c8 (diff)
downloadtcl-7d339460289a90d64c36b4ed7fcb390572efb438.zip
tcl-7d339460289a90d64c36b4ed7fcb390572efb438.tar.gz
tcl-7d339460289a90d64c36b4ed7fcb390572efb438.tar.bz2
Added better docs of [binary encode] and [binary decode]
-rw-r--r--ChangeLog5
-rw-r--r--doc/binary.n96
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: