X-Git-Url: http://repo.macrolet.net/gitweb/?a=blobdiff_plain;f=doc%2Fmanual%2Fstreams.texinfo;h=c1c8ceb12e673279c1cc7bc568a7b8186275206d;hb=d84e1dbbbf11e76663cfaa0b1a5b7591f39f01b6;hp=ddb0003955c1e2077958463b089bf07ca6526dba;hpb=16b425bf18dff8a43b70776f45f3d59741535356;p=sbcl.git

diff --git a/doc/manual/streams.texinfo b/doc/manual/streams.texinfo
index ddb0003..c1c8ceb 100644
--- a/doc/manual/streams.texinfo
+++ b/doc/manual/streams.texinfo
@@ -1,8 +1,19 @@
-@node Extensible Streams
+@node Streams
 @comment  node-name,  next,  previous,  up
-@chapter Extensible Streams
+@chapter Streams
 
-SBCL supports various extensions of ANSI Common Lisp streams.
+Streams which read or write Lisp character data from or to the outside
+world -- files, sockets or other external entities -- require the
+specification of a conversion between the external, binary data and the
+Lisp characters.  In ANSI Common Lisp, this is done by specifying the
+@code{:external-format} argument when the stream is created.  The major
+information required is an @emph{encoding}, specified by a keyword
+naming that encoding; however, it is also possible to specify
+refinements to that encoding as additional options to the external
+format designator.
+
+In addition, SBCL supports various extensions of ANSI Common Lisp
+streams:
 
 @table @strong
 @item Bivalent Streams
@@ -20,11 +31,47 @@ of the Franz Allegro simple-streams proposal.
 @end table
 
 @menu
+* External Formats::
 * Bivalent Streams::
 * Gray Streams::                
 * Simple Streams::              
 @end menu
 
+@node External Formats
+@section External Formats
+@cindex External formats
+
+@findex @cl{stream-external-format}
+The encodings supported by SBCL as external formats are named by
+keyword.  Each encoding has a canonical name, which will be encoding
+returned by @code{stream-external-format}, and a number of aliases for
+convenience, as shown in the table below:
+
+@include encodings.texi-temp
+
+@findex @cl{open}
+@findex @cl{with-open-file}
+In situations where an external file format designator is required, such
+as the @code{:external-format} argument in calls to @code{open} or
+@code{with-open-file}, users may supply the name of an encoding to
+denote the external format which is applying that encoding to Lisp
+characters.
+
+In addition to the basic encoding for an external format, options
+controlling various special cases may be passed, by using a list (whose
+first element must be an encoding name and whose rest is a plist) as an
+external file format designator.  At present, the only supported key in
+the plist is @code{:replacement}, where the corresponding value is a
+string designator which is used as a replacement when an encoding or
+decoding error happens, handling those errors without user intervention;
+for example:
+@lisp
+(with-open-file (i pathname :external-format '(:utf-8 :replacement #\?))
+  (read-line i))
+@end lisp
+will read the first line of @var{pathname}, replacing any invalid utf-8
+sequences with question marks.
+ 
 @node Bivalent Streams
 @section Bivalent Streams
 
@@ -105,7 +152,7 @@ of fundamental-stream.
 
 @include fun-common-lisp-stream-element-type.texinfo
 @include fun-common-lisp-close.texinfo
-
+@include fun-sb-gray-stream-file-position.texinfo