From 7d9c0d45104c9a45be14e237f237702154f75cc9 Mon Sep 17 00:00:00 2001
From: Christophe Rhodes <csr21@cantab.net>
Date: Wed, 11 Nov 2009 18:20:34 +0000
Subject: [PATCH] 1.0.32.24: document stream external-formats and :replacement
 option

---
 doc/manual/ffi.texinfo       |    1 +
 doc/manual/make-tempfiles.sh |   13 +++++++++++
 doc/manual/sbcl.texinfo      |    2 +-
 doc/manual/streams.texinfo   |   53 +++++++++++++++++++++++++++++++++++++++---
 version.lisp-expr            |    2 +-
 5 files changed, 66 insertions(+), 5 deletions(-)

diff --git a/doc/manual/ffi.texinfo b/doc/manual/ffi.texinfo
index b65b2bc..f00e23d 100644
--- a/doc/manual/ffi.texinfo
+++ b/doc/manual/ffi.texinfo
@@ -283,6 +283,7 @@ types to declare that no useful value is returned.  Using
 return zero values.
 
 @item
+@cindex External formats
 The foreign type specifier @code{(sb-alien:c-string &key external-format
 element-type)} is similar to @code{(* char)}, but is interpreted as a
 null-terminated string, and is automatically converted into a Lisp
diff --git a/doc/manual/make-tempfiles.sh b/doc/manual/make-tempfiles.sh
index 2f7fc38..be2abf0 100644
--- a/doc/manual/make-tempfiles.sh
+++ b/doc/manual/make-tempfiles.sh
@@ -72,3 +72,16 @@ then
 else
     cp package-locks-basic.texinfo package-locks.texi-temp
 fi
+
+echo /creating encodings.texi-temp
+$SBCL <<EOF
+(with-open-file (s "encodings.texi-temp" :direction :output :if-exists :supersede)
+  (let (result)
+    (sb-int:dohash ((key val) sb-impl::*external-formats*)
+      (pushnew (sb-impl::ef-names val) result :test #'equal))
+    (setq result (sort result #'string< :key #'car))
+    (format s "@table @code~%~%")
+    (loop for (cname . names) in result
+          do (format s "@item ~S~%~{@code{~S}~^, ~}~%~%" cname names))
+    (format s "@end table~%")))
+EOF
diff --git a/doc/manual/sbcl.texinfo b/doc/manual/sbcl.texinfo
index fa2bac5..02bd67d 100644
--- a/doc/manual/sbcl.texinfo
+++ b/doc/manual/sbcl.texinfo
@@ -81,7 +81,7 @@ provided with absolutely no warranty. See the @file{COPYING} and
 * Beyond the ANSI Standard::    
 * Foreign Function Interface::  
 * Pathnames::
-* Extensible Streams::          
+* Streams::          
 * Package Locks::               
 * Threading::
 * Timers::
diff --git a/doc/manual/streams.texinfo b/doc/manual/streams.texinfo
index 243ccf4..521384d 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 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 open 
+@findex 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
 
diff --git a/version.lisp-expr b/version.lisp-expr
index fcb1f10..4ebf1e4 100644
--- a/version.lisp-expr
+++ b/version.lisp-expr
@@ -17,4 +17,4 @@
 ;;; checkins which aren't released. (And occasionally for internal
 ;;; versions, especially for internal versions off the main CVS
 ;;; branch, it gets hairier, e.g. "0.pre7.14.flaky4.13".)
-"1.0.32.23"
+"1.0.32.24"
-- 
1.7.10.4