Also improved [fcopy] docs

1 files changed, 24 insertions, 13 deletions

diff --git a/doc/fcopy.n b/doc/fcopy.n
index a90cc7b..a97950b 100644
--- a/doc/fcopy.n
+++ b/doc/fcopy.n
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: fcopy.n,v 1.4 2004/09/06 09:44:56 dkf Exp $
+'\" RCS: @(#) $Id: fcopy.n,v 1.5 2005/04/13 11:06:27 dkf Exp $
 '\" 
 .so man.macros
 .TH fcopy n 8.0 Tcl "Tcl Built-In Commands"
@@ -72,12 +72,15 @@ Only the number of bytes written to \fIoutchan\fR is reported,
 either as the return value of a synchronous \fBfcopy\fP or
 as the argument to the callback for an asynchronous \fBfcopy\fP.
 .PP
-\fBFcopy\fR obeys the encodings configured for the channels. This
+\fBFcopy\fR obeys the encodings and character translations configured
+for the channels. This
 means that the incoming characters are converted internally first
 UTF-8 and then into the encoding of the channel \fBfcopy\fR writes
 to. See the manual entry for \fBfconfigure\fR for details on the
-\fB\-encoding\fR option. No conversion is done if both channels are
-set to encoding "binary". If only the output channel is set to
+\fB\-encoding\fR and \fB\-translation\fR options. No conversion is
+done if both channels are
+set to encoding "binary" and have matching translations. If only the
+output channel is set to
 encoding "binary" the system will write the internal UTF-8
 representation of the incoming characters. If only the input channel
 is set to encoding "binary" the system will assume that the incoming
@@ -85,9 +88,19 @@ bytes are valid UTF-8 characters and convert them according to the
 output encoding. The behaviour of the system for bytes which are not
 valid UTF-8 characters is undefined in this case.
 
-.SH EXAMPLE
+.SH EXAMPLES
 .PP
-This first example shows how the callback gets
+The first example transfers the contents of one channel exactly to
+another. Note that when copying one file to another, it is better to
+use \fBfile copy\fR which also copies file metadata (e.g. the file
+access permissions) where possible.
+.DS
+fconfigure $in -translation binary
+fconfigure $out -translation binary
+\fBfcopy\fR $in $out
+.DE
+.PP
+This second example shows how the callback gets
 passed the number of bytes transferred.
 It also uses vwait to put the application into the event loop.
 Of course, this simplified example could be done without the command 
@@ -104,12 +117,11 @@ proc Cleanup {in out bytes {error {}}} {
 }
 set in [open $file1]
 set out [socket $server $port]
-fcopy $in $out -command [list Cleanup $in $out]
+\fBfcopy\fR $in $out -command [list Cleanup $in $out]
 vwait total
-
 .DE
 .PP
-The second example copies in chunks and tests for end of file
+The third example copies in chunks and tests for end of file
 in the command callback
 .DS
 proc CopyMore {in out chunk bytes {error {}}} {
@@ -120,7 +132,7 @@ proc CopyMore {in out chunk bytes {error {}}} {
 	close $in
 	close $out
     } else {
-	fcopy $in $out -command [list CopyMore $in $out $chunk] \\
+	\fBfcopy\fR $in $out -command [list CopyMore $in $out $chunk] \\
 	    -size $chunk
     }
 }
@@ -128,13 +140,12 @@ set in [open $file1]
 set out [socket $server $port]
 set chunk 1024
 set total 0
-fcopy $in $out -command [list CopyMore $in $out $chunk] -size $chunk
+\fBfcopy\fR $in $out -command [list CopyMore $in $out $chunk] -size $chunk
 vwait done
-
 .DE
 
 .SH "SEE ALSO"
-eof(n), fblocked(n), fconfigure(n)
+eof(n), fblocked(n), fconfigure(n), file(n)
 
 .SH KEYWORDS
 blocking, channel, end of line, end of file, nonblocking, read, translation