CMUCL commit: src/docs/cmu-user (unicode.tex)

[Raymond Toy]

    Date: Tuesday, August 3, 2010 @ 23:39:07
  Author: rtoy
    Path: /project/cmucl/cvsroot/src/docs/cmu-user

Modified: unicode.tex

o Document the parameters to OPEN that are specific to Unicode.
o Document LIST-ALL-EXTERNAL-FORMATS and DESCRIBE-EXTERNAL-FORMAT. 


-------------+
 unicode.tex |   66 ++++++++++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 58 insertions(+), 8 deletions(-)


Index: src/docs/cmu-user/unicode.tex
diff -u src/docs/cmu-user/unicode.tex:1.11 src/docs/cmu-user/unicode.tex:1.12
--- src/docs/cmu-user/unicode.tex:1.11	Mon Jul 12 09:58:42 2010
+++ src/docs/cmu-user/unicode.tex	Tue Aug  3 23:39:07 2010
@@ -80,14 +80,6 @@
 parameter to specify the format.  The default external format is
 \kwd{default}. 
 
-\begin{defun}{stream:}{set-system-external-format}{\var{terminal} \ampoptional{} \var{filenames}}
-  This function changes the external format used for
-  \var{*standard-input*}, \var{*standard-output*}, and
-  \var{*standard-error*} to the external format specified by
-  \var{terminal}.  Additionally, the Unix file name encoding can be
-  set to the value specified by \var{filenames} if non-\nil.
-\end{defun}
-
 \subsection{Available External Formats}
 
 The available external formats are listed below in
@@ -451,8 +443,66 @@
 \file{ext-formats:unidata.bin}.  If this file is not found, Unicode
 support is severely reduced; you can only use ASCII characters.
 
+\begin{defun}{}{open}{\args \var{filename} \amprest \var{options}
+    \keys{\kwd{direction} \kwd{element-type} \kwd{if-exists}
+      \kwd{if-does-not-exist} \morekeys \kwd{class} \kwd{mapped}
+      \kwd{input-handle} \kwd{output-handle}
+      \yetmorekeys \kwd{external-format} \kwd{decoding-error}
+      \kwd{encoding-error}}
+
+    The main options are covered elsewhere.  Here we describe the
+    options specific to Unicode.  The option \kwd{external-format}
+    specifies the external format to use for reading and writing the
+    file.  The external format is a keyword.
+
+    The options \kwd{decoding-error} and \kwd{encoding-error} are used
+    to specify how encoding and decoding errors are handled.  The
+    default value on \nil means the external format handles errors
+    itself and typically replaces invalid sequences with the Unicode
+    replacement character.
+
+    Otherwise, the value for \code{decoding-error} is either a
+    character, a symbol or a function.  If a character is
+    specified. it is used as the replacement character for any invalid
+    decoding.  If a symbol or a function is given, it must be a
+    function of three arguments: a message string to be printed, the
+    offending octet, and the number of octets read.  If the function
+    returns, it should return two values: the code point to use as the
+    replacement character and the number of octets read.  In addition,
+    \true{} may be specified.  This indicates that a continuable error
+    is signaled, which, if continued, the Unicode replacement
+    character is used.
+
+    For \code{encoding-error}, a character, symbol, or function can be
+    specified, like \code{decoding-error}, with the same meaning.  The
+    function, however, takes two arguments:  a format message string
+    and the incorrect codepoint.  If the function returns, it should
+    be the replacement codepoint.
+\end{defun}    
+      
 \subsubsection{Utilities}
 
+\begin{defun}{stream:}{set-system-external-format}{\var{terminal} \ampoptional{} \var{filenames}}
+  This function changes the external format used for
+  \var{*standard-input*}, \var{*standard-output*}, and
+  \var{*standard-error*} to the external format specified by
+  \var{terminal}.  Additionally, the Unix file name encoding can be
+  set to the value specified by \var{filenames} if non-\nil.
+\end{defun}
+
+\begin{defun}{extensions:}{list-all-external-formats}{}
+  list all of the vailable external formats.  A list is returned where
+  each element is a list of the external format name and a list of
+  aliases for the format.  No distinction is made between external
+  formats and composing external formats.
+\end{defun}
+
+\begin{defun}{extensions:}{describe-external-format}{external-format}
+  Print a description of the given \var{external-format}.  This may
+  cause the external format to be loaded (silently) if it is not
+  already loaded.
+\end{defun}
+
 Since strings are UTF-16 and hence may contain surrogate pairs, some
 utility functions are provided to make access easier.