[2152292]: Corrected implementation of uuencode handling to support line length

indicator bytes.

***POTENTIAL INCOMPATIBILITY***
Existing code that was using the old versions and working around the
limitations will now need to do far less. The -maxlen option now has strict
limits on the range of supported lengths; this is a limitation of the format
itself.

1 files changed, 21 insertions, 5 deletions

diff --git a/doc/binary.n b/doc/binary.n
index a40afe6..cbbebd1 100644
--- a/doc/binary.n
+++ b/doc/binary.n
@@ -36,6 +36,13 @@ The \fBbinary encode\fR and \fBbinary decode\fR subcommands convert
 binary data to or from string encodings such as base64 (used in MIME
 messages for example).
 .VE 8.6
+.PP
+Note that other operations on binary data, such as taking a subsequence of it,
+getting its length, or reinterpreting it as a string in some encoding, are
+done by other Tcl commands (respectively \fBstring range\fR,
+\fBstring length\fR and \fBencoding convertfrom\fR in the example cases).  A
+binary string in Tcl is merely one where all the characters it contains are in
+the range \eu0000\-\eu00FF.
 .SH "BINARY ENCODE AND DECODE"
 .VS 8.6
 .PP
@@ -95,13 +102,14 @@ between Unix systems and on USENET, but is less common these days, having been
 largely superseded 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!
+During encoding, the following options are supported (though changing them may
+produce files that other implementations of decoders cannot process):
 .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.
+\fIlength\fR characters. By default, lines are split every 61 characters, and
+this must be in the range 3 to 85 due to limitations in the encoding.
 .TP
 \fB\-wrapchar \fIcharacter\fR
 .
@@ -114,7 +122,11 @@ During decoding, the following options are supported:
 .TP
 \fB\-strict\fR
 .
-Instructs the decoder to throw an error if it encounters whitespace characters. Otherwise it ignores them.
+Instructs the decoder to throw an error if it encounters unexpected whitespace
+characters. Otherwise it ignores them.
+.PP
+Note that neither the encoder nor the decoder handle the header and footer of
+the uuencode format.
 .RE
 .VE 8.6
 .SH "BINARY FORMAT"
@@ -855,6 +867,7 @@ architectures, use their textual representation (as produced by
 .PP
 This is a procedure to write a Tcl string to a binary-encoded channel as
 UTF-8 data preceded by a length word:
+.PP
 .CS
 proc \fIwriteString\fR {channel string} {
     set data [encoding convertto utf-8 $string]
@@ -865,6 +878,7 @@ proc \fIwriteString\fR {channel string} {
 .PP
 This procedure reads a string from a channel that was written by the
 previously presented \fIwriteString\fR procedure:
+.PP
 .CS
 proc \fIreadString\fR {channel} {
     if {![\fBbinary scan\fR [read $channel 4] I length]} {
@@ -877,6 +891,7 @@ proc \fIreadString\fR {channel} {
 .PP
 This converts the contents of a file (named in the variable \fIfilename\fR) to
 base64 and prints them:
+.PP
 .CS
 set f [open $filename rb]
 set data [read $f]
@@ -884,9 +899,10 @@ close $f
 puts [\fBbinary encode\fR base64 \-maxlen 64 $data]
 .CE
 .SH "SEE ALSO"
-format(n), scan(n), tcl_platform(n)
+encoding(n), format(n), scan(n), string(n), tcl_platform(n)
 .SH KEYWORDS
 binary, format, scan
 '\" Local Variables:
 '\" mode: nroff
+'\" fill-column: 78
 '\" End: