summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAndy Wingo <wingo@pobox.com>2011-08-18 11:13:34 +0200
committerAndy Wingo <wingo@pobox.com>2011-08-18 11:13:34 +0200
commit5261e74281b1150e3b2594c92e571d8887a4900d (patch)
tree282b39d10c4bdd8d987ec8b46e00072f7cec19df
parent81bda963e969db7e2ecc878982286daa5b0aacff (diff)
downloadguile-5261e74281b1150e3b2594c92e571d8887a4900d.tar.gz
reword open-file docs
* doc/ref/api-io.texi (File Ports): Refactor open-file docs. Thanks to Bake Timmons for the report.
-rw-r--r--doc/ref/api-io.texi44
1 files changed, 22 insertions, 22 deletions
diff --git a/doc/ref/api-io.texi b/doc/ref/api-io.texi
index 19c066530..afcde579d 100644
--- a/doc/ref/api-io.texi
+++ b/doc/ref/api-io.texi
@@ -838,34 +838,34 @@ setvbuf}
Add line-buffering to the port. The port output buffer will be
automatically flushed whenever a newline character is written.
@item b
-Use binary mode. On DOS systems the default text mode converts CR+LF
-in the file to newline for the program, whereas binary mode reads and
-writes all bytes unchanged. On Unix-like systems there is no such
-distinction, text files already contain just newlines and no
-conversion is ever made. The @code{b} flag is accepted on all
-systems, but has no effect on Unix-like systems.
-
-(For reference, Guile leaves text versus binary up to the C library,
-@code{b} here just adds @code{O_BINARY} to the underlying @code{open}
-call, when that flag is available.)
-
-Also, open the file using the 8-bit character encoding "ISO-8859-1",
-ignoring any coding declaration or port encoding.
-
-Note that, when reading or writing binary data with ports, the
-bytevector ports in the @code{(rnrs io ports)} module are preferred,
-as they return vectors, and not strings (@pxref{R6RS I/O Ports}).
+Use binary mode, ensuring that each byte in the file will be read as one
+Scheme character.
+
+To provide this property, the file will be opened with the 8-bit
+character encoding "ISO-8859-1", ignoring any coding declaration or port
+encoding. @xref{Ports}, for more information on port encodings.
+
+Note that while it is possible to read and write binary data as
+characters or strings, it is usually better to treat bytes as octets,
+and byte sequences as bytevectors. @xref{R6RS Binary Input}, and
+@ref{R6RS Binary Output}, for more.
+
+This option had another historical meaning, for DOS compatibility: in
+the default (textual) mode, DOS reads a CR-LF sequence as one LF byte.
+The @code{b} flag prevents this from happening, adding @code{O_BINARY}
+to the underlying @code{open} call. Still, the flag is generally useful
+because of its port encoding ramifications.
@end table
If a file cannot be opened with the access
requested, @code{open-file} throws an exception.
When the file is opened, this procedure will scan for a coding
-declaration (@pxref{Character Encoding of Source Files}). If present
-will use that encoding for interpreting the file. Otherwise, the
-port's encoding will be used. To suppress this behavior, open
-the file in binary mode and then set the port encoding explicitly
-using @code{set-port-encoding!}.
+declaration (@pxref{Character Encoding of Source Files}). If a coding
+declaration is found, it will be used to interpret the file. Otherwise,
+the port's encoding will be used. To suppress this behavior, open the
+file in binary mode and then set the port encoding explicitly using
+@code{set-port-encoding!}.
In theory we could create read/write ports which were buffered
in one direction only. However this isn't included in the