More doc fix backporting

1 files changed, 61 insertions, 2 deletions

diff --git a/doc/fconfigure.n b/doc/fconfigure.n
index d903b55..16b81ad 100644
--- a/doc/fconfigure.n
+++ b/doc/fconfigure.n
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-'\" RCS: @(#) $Id: fconfigure.n,v 1.7.2.1 2003/04/18 00:32:34 dkf Exp $
+'\" RCS: @(#) $Id: fconfigure.n,v 1.7.2.2 2004/10/27 12:52:40 dkf Exp $
 '\"
 .so man.macros
 .TH fconfigure n 8.3 Tcl "Tcl Built-In Commands"
@@ -192,7 +192,6 @@ during either input or output.  This mode is typically used on UNIX
 platforms.
 .RE
 .PP
-
 .SH "STANDARD CHANNELS"
 .PP
 The Tcl standard channels (\fBstdin\fR, \fBstdout\fR, and \fBstderr\fR)
@@ -202,6 +201,66 @@ will also support any special option according to their current type.
 If, for example, a Tcl application is started by the \fBinet\fR
 super-server common on Unix system its Tcl standard channels will be
 sockets and thus support the socket options.
+.SH EXAMPLES
+Instruct Tcl to always send output to \fBstdout\fR immediately,
+whether or not it is to a terminal:
+.CS
+\fBfconfigure\fR stdout -buffering none
+.CE
+.PP
+Open a socket and read lines from it without ever blocking the
+processing of other events:
+.CS
+set s [socket some.where.com 12345]
+\fBfconfigure\fR $s -blocking 0
+fileevent $s readable "readMe $s"
+proc readMe chan {
+   if {[gets $chan line] < 0} {
+      if {[eof $chan]} {
+         close $chan
+         return
+      }
+      # Could not read a complete line this time; Tcl's
+      # internal buffering will hold the partial line for us
+      # until some more data is available over the socket.
+   } else {
+      puts stdout $line
+   }
+}
+.CE
+.PP
+Read a PPM-format image from a file:
+.CS
+# Open the file and put it into Unix ASCII mode
+set f [open teapot.ppm]
+\fBfconfigure\fR $f \-encoding ascii \-translation lf
+
+# Get the header
+if {[gets $f] ne "P6"} {
+   error "not a raw\-bits PPM"
+}
+
+# Read lines until we have got non-comment lines
+# that supply us with three decimal values.
+set words {}
+while {[llength $words] < 3} {
+   gets $f line
+   if {[string match "#*" $line]} continue
+   lappend words [eval concat [scan $line %d%d%d]]
+}
+
+# Those words supply the size of the image and its
+# overall depth per channel. Assign to variables.
+foreach {xSize ySize depth} $words {break}
+
+# Now switch to binary mode to pull in the data,
+# one byte per channel (red,green,blue) per pixel.
+\fBfconfigure\fR $f \-translation binary
+set numDataBytes [expr {3 * $xSize * $ySize}]
+set data [read $f $numDataBytes]
+
+close $f
+.CE
 
 .SH "SEE ALSO"
 close(n), flush(n), gets(n), open(n), puts(n), read(n), socket(n),