[Openmcl-cvs-notifications] r8993 - in /trunk/source/doc/src: build.xml install.xml modifying.xml streams.xml templates/ templates/function threads.xml using.xml xsl/directory-fixes.xsl xsl/openmcl.xsl xsl/refentry.xsl
jaj at clozure.com
jaj at clozure.com
Thu Apr 3 01:14:05 EDT 2008
Author: jaj
Date: Thu Apr 3 01:14:05 2008
New Revision: 8993
Log:
Update documentation in many places.
Add templates directory and template for function entry. In nXML mode do a =
c-x c-i to insert a template for function definitions.
Fix stylesheet so that xrefs work and refentries other than functions work.
Don't include directory-fixes.xsl. There is no openmcl.css, and I'm not su=
re that we need one.
Added:
trunk/source/doc/src/templates/
trunk/source/doc/src/templates/function
Modified:
trunk/source/doc/src/build.xml
trunk/source/doc/src/install.xml
trunk/source/doc/src/modifying.xml
trunk/source/doc/src/streams.xml
trunk/source/doc/src/threads.xml
trunk/source/doc/src/using.xml
trunk/source/doc/src/xsl/directory-fixes.xsl
trunk/source/doc/src/xsl/openmcl.xsl
trunk/source/doc/src/xsl/refentry.xsl
Modified: trunk/source/doc/src/build.xml
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D
--- trunk/source/doc/src/build.xml (original)
+++ trunk/source/doc/src/build.xml Thu Apr 3 01:14:05 2008
@@ -34,7 +34,7 @@
challenging and experimental way to build, and is not described
here.</para>
=
- <sect1 id=3D"building-definitions"><title>building definitions</title>
+ <sect1 id=3D"building-definitions"><title>Building Definitions</title>
<para>The following terms are used in subsequent sections; it
may be helpful to refer to these definitions.</para>
=
Modified: trunk/source/doc/src/install.xml
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D
--- trunk/source/doc/src/install.xml (original)
+++ trunk/source/doc/src/install.xml Thu Apr 3 01:14:05 2008
@@ -76,7 +76,8 @@
minimum.</para>
</sect2>
=
- <sect2><title>LinuxX8664</title> =
+ <sect2><title>Linux
+X8664</title> =
=
<para>Version 1.1 and later of &CCL; runs on relatively
recent Linux distributions for the x86-64 architecture. It
@@ -123,7 +124,7 @@
processor.</para>
=
<para>&CCL; hasn't been tested under Darwin proper, but
- &CCL; doesn't intentionally use any MacOS X features beyond
+ &CCL; doesn't intentionally use any Mac OS X features beyond
the Darwin subset and therefore it seems likely that &CCL;
would run on PPC Darwin versions that correspond to recent OSX
versions.</para>
@@ -144,60 +145,106 @@
</sect2>
</sect1>
=
- <sect1><title>Installation</title>
- <para>Installing &CCL; consists of</para>
- <orderedlist> =
- <listitem>
- <para>Downloading an appropriate distribution of &CCL;;</para>
- </listitem>
- <listitem>
- <para>If necessary, extracting the archive somewhere on your
- computer;</para>
- </listitem>
- <listitem>
- <para>Configuring a shell script so &CCL; can locate
- necessary library files and other auxiliary files.</para>
- </listitem>
- </orderedlist>
-
- <sect2><title>Downloading and untarring &CCL; binary source
- releases</title> <para> &CCL; releases and snapshots are
- distributed as tarballs (compressed tar archives).</para>
-
- <para>Tarballs of version 1.0 for supported platforms are
- available from the download page of the &CCL; website.</para>
-
- <para>Tarballs of the latest development snapshots of version
- 1.1, along with release notes, are available from the testing
- directory on Clozure.com.</para>
- <para>Both the release and snapshot archives contain a directory
- named <literal>ccl</literal>, which in turn contains a number of
- files and subdirectories. The <literal>ccl</literal> directory
- can reside anywhere in the filesystem, assuming appropriate
- permissions. If you wanted the <literal>ccl</literal> directory
- to reside in <literal>``~/openmcl/ccl''</literal> and the
- directory <literal>``~/openmcl/''</literal> already existed, you
- could do anything equivalent to:</para>
+
+ <sect1><title>Obtaining Clozure CL</title>
+ <para>There two main ways to obtain Clozure CL. For Mac OS X,
+ there are disk images that can be used to install Clozure CL in
+ the usual Macintosh way. For other OSes (or for Mac OS X),
+ Subversion is the best way to obtain Clozure CL. Tarballs are
+ available for those who prefer them, but Subversion is simpler
+ and more flexible.</para>
+
+ <para> There are three popular ways to use Clozure CL: as a
+ stand-alone double-clickable application (Mac OS X only), as a
+ command-line application, or with EMACS and SLIME. These are
+ described in the following sections.</para>
+
+ <sect2><title>The Mac Way</title>
+ <para>If you are using Mac OS X then Clozure CL can be installed
+ and used in the usual Macintosh way. A disk image is downloaded
+ and mounted, then Clozure CL is dragged to the Applications
+ folder. After that you can double-click on the Clozure CL
+ application to run it. The disk images are found at <ulink
+ url=3D"ftp://clozure.com/pub/testing/"/> </para>
+
+ <para>In order to locate Clozure CL source code (and for other
+ reasons <xref linkend=3D"Predefined-Logical-Hosts"/>) the
+ <literal>ccl</literal> directory should either be in the same
+ directory as the Clozure CL application, or the Clozure CL
+ application should be in the <literal>ccl</literal> directory.
+ If you use a shell, then the
+ <varname>CCL_DEFAULT_DIRECTORY</varname> environment variable
+ can be set to explicitly indicate the location of the
+ <literal>ccl</literal> directory.</para>
+ </sect2>
+ =
+
+ <sect2><title>Getting Clozure CL with Subversion</title>
+ <para>It is very easy to download, install, and build Clozure CL
+ using Subversion. This is the preferred way to get either the
+ latest, or a specific version of Clozure CL (unless you're
+ using the Mac Way). Subversion is a source code control system
+ that is in wide usage. Most modern OSes come with subversion
+ pre-installed. A complete, buildable and runnable set of Clozure
+ CL sources and binaries can be retrieved by doing one subversion
+ checkout.</para>
+
+ <para>First, make sure that Subversion is installed on your
+ system. Bring up a command line shell and type:
<programlisting>
-shell> cd ~/openmcl
-shell> tar xvzf <emphasis>path-to-downloaded-openmcl-archive.tar.gz</em=
phasis>
+ <![CDATA[
+shell> svn]]>
+ </programlisting> =
+ If Subversion is installed, it will say something like:
+ <programlisting>
+ <![CDATA[
+Type 'svn help' for usage]]>
</programlisting>
- <para><emphasis>Important Note for Macintosh Users:</emphasis>
- Double-clicking the archive in the Finder may work, but it also
- may have unintended side-effects. In some versions of the Mac
- OS double-clicking an archive will invoke Stuffit, which may try
- to replace linefeeds with carriage returns as it extracts
- files. Also, tar can be used to merge the archive contents into
- an existing <literal>ccl</literal> directory, whereas
- double-clicking in the Finder will create a new directory named
- <literal>ccl 2</literal> (or <literal>ccl 3</literal>, or...)
- Bottom line is that you're better off using tar from the
- shell.</para>
-
- <para>Once the <literal>ccl</literal> directory is installed,
- it's necessary to install and configure a shell script
- distributed with &CCL; before using it.</para>
- </sect2>
+ If Subversion is not installed, it will say something
+ like:
+ <programlisting>
+ <![CDATA[
+-bash: svn: command not found]]>
+ </programlisting>
+ If subversion is not installed, you'll need to figure out how to
+ install it on your OS.</para>
+
+ <para>Create the directory where Clozure CL will live, <literal>cd</l=
iteral> to that directory, then type a Subversion checkout command. For ex=
ample:
+
+ <programlisting>
+ <![CDATA[
+joe:~> mkdir ccl
+joe:~> cd ccl
+joe:ccl> svn co svn+ssh://svn.clozure.com/usr/local/publicsvn/openmcl]]>
+ </programlisting>
+ Once the checkout is complete you can build Clozure CL by doing:
+ <programlisting>
+ <![CDATA[
+joe:ccl> ./dx86cl64
+Welcome to Clozure Common Lisp Version 1.2 (DarwinX8664)!
+? (rebuild-ccl :full t)
+<lots of compilation output>
+? (quit)
+joe:ccl>]]>
+ </programlisting>
+ </para>
+ </sect2>
+
+ <sect2><title>Tarballs</title>
+ <para>Tarballs are available at <ulink
+ url=3D"ftp://clozure.com/pub/testing/"/>. These should be
+ downloaded and extracted onto your local disk. Then a shell
+ script should be edited to set
+ <varname>CCL_DEFAULT_DIRECTORY</varname> and start up the
+ appropriate Clozure CL kernel. <xref
+ linkend=3D"The-openmcl-Shell-Script"/> </para>
+ </sect2>
+ </sect1>
+
+ <sect1><title>Command Line Set Up</title>
+ <para>Sometimes it is convenient to use Clozure CL from a Unix
+ shell command line. This is especially true when using Clozure CL
+ as a way to run Common Lisp utilities.</para>
=
<sect2 id=3D"The-openmcl-Shell-Script"><title>The openmcl Shell Scri=
pt</title>
<para>&CCL; needs to be able to find the
@@ -299,7 +346,8 @@
<literal>ccl64</literal> will run a 64-bit session.
</para>
</sect2>
- <sect2 id=3D"Personal-Customization-with-the-Init-File">
+ </sect1>
+ <sect1 id=3D"Personal-Customization-with-the-Init-File">
<title>Personal Customization with the Init File</title>
<para>By default &CCL; will try to load the file
<literal>"home:openmcl-init.lisp"</literal> or the compiled
@@ -320,47 +368,137 @@
packages which you use frequently.</para>
<para>To suppress the loading of this init-file, invoke &CCL; with=
the
<literal>--no-init</literal> option.</para>
- </sect2>
-
- <sect2 id=3D"Some--hopefully--useful-options">
- <title>Some (hopefully) useful options</title>
- <para> The exact set of command-line arguments accepted by
- &CCL; may vary slightly from release to release;
- <literal>openmcl --help</literal> will provide a definitive
- (if somewhat terse) summary of the options accepted by the
- current implementation and then exit. Some of those options
- are described below.</para>
+ </sect1>
+
+ <sect1 id=3D"Command-Line-Options">
+ <title>Command Line Options</title>
+ <para>When using Clozure CL from the command line, these
+ options may be used to modify its behavior. The exact set of
+ Clozure CL command-line arguments may vary per platform and
+ slowly changes over time. The current set of command line
+ options may be retrieved by using the
+ <literal>--help</literal> option.</para>
<itemizedlist>
<listitem>
- <para>-S (or --stack-size). Specify the size of the initial process
- stack.</para>
- </listitem>
-
- <listitem>
- <para>-b (or --batch). Execute in "batch mode". End-of-file
- from *STANDARD-INPUT* will cause &CCL; to exit, as will attempts to
+ <para><literal>-h</literal> (or
+ <literal>--help</literal>). Provides a definitive (if
+ somewhat terse) summary of the command line options
+ accepted by the Clozure CL implementation and then
+ exits.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>-V</literal> (or
+ <literal>--version</literal>). Prints the version of
+ Clozure CL then exits. This is the same thing that is
+ returned by
+ <function>LISP-APPLICATION-VERSION</function>.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>-K</literal>
+ <parameter>character-encoding-name</parameter> (or
+ <literal>--terminal-encoding</literal>
+ <parameter>character-encoding-name</parameter>).
+ Specifies the character encoding to use for
+ <varname>*TERMINAL-IO*</varname> (see <xref
+ linkend=3D"Character-Encodings"/>). Specifically, the
+ <parameter>character-encoding-name</parameter> string
+ is uppercased and interned in the KEYWORD package. If an
+ encoding named by that keyword exists,
+ <varname>CCL:*TERMINAL-CHARACTER-ENCODING-NAME*</varname> is set to =
the name
+ of that encoding. <varname>CCL:*TERMINAL-CHARACTER-ENCODING-NAME*</=
varname> defaults to <literal>NIL</literal>, which
+ is a synonym for <literal>:ISO-8859-1</literal>.</para>
+ <para>For example:
+ <programlisting>
+ <![CDATA[shell> ccl -K utf-8]]>
+ </programlisting>
+ will have the effect of making the standard CL streams use
+ <literal>:UTF-8</literal> as their character
+ encoding.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>-n</literal> (or
+ <literal>--no-init</literal>). If this option is given,
+ the init file is not loaded. This is useful if &CCL; is
+ being invoked by a shell script which should not be
+ affected by whatever customizations a user might have in
+ place.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>-e</literal> <parameter>form</parameter>
+ (or <literal>--eval</literal>). An expression is read (via
+ <function>READ-FROM-STRING</function>) from the string
+ <parameter>form</parameter> and evaluated. If
+ <parameter>form</parameter> contains shell metacharacters,
+ it may be necessary to escape or quote them to prevent the
+ shell from interpreting them.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>-l</literal> <parameter>path</parameter>
+ (or <literal>--load</literal>
+ <parameter>path</parameter>). Loads file specified by
+ <parameter>path</parameter>.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>-T</literal> <parameter>n</parameter> (or
+ <literal>--set-lisp-heap-gc-threshold</literal>
+ <parameter>n</parameter>). Sets the Lisp gc threshold to
+ <parameter>n</parameter>. (see <xref
+ linkend=3D"GC-Page-reclamation-policy"/></para>
+ </listitem>
+
+ <listitem>
+ <para><literal>-Q</literal> (or
+ <literal>--quiet</literal>). Suppresses printing of
+ heralds and prompts when the <literal>--batch</literal>
+ command line option is specified.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>-R</literal> <parameter>n</parameter> (or
+ <literal>--heap-reserve</literal>). Reserves
+ <parameter>n</parameter> bytes for heap expansion. The
+ default is <literal> 549755813888</literal>. (see <xref
+ linkend=3D"Heap-space-allocation"/>)</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>-S</literal> <parameter>n</parameter> (or
+ <literal>--stack-size</literal> <parameter>n</parameter>). Sets the s=
ize of the
+ initial control stack to <parameter>n</parameter>. (see <xref
+ linkend=3D"Thread-Stack-Sizes"/>)</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>-Z</literal> <parameter>n</parameter> (or
+ <literal>--thread-stack-size</literal>
+ <parameter>n</parameter>). Sets the size of the first
+ thread's stack to <parameter>n</parameter>. (see <xref
+ linkend=3D"Thread-Stack-Sizes"/>)</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>-b</literal> (or <literal>--batch</literal>). Execute =
in "batch mode". End-of-file
+ from <varname>*STANDARD-INPUT*</varname> will cause &CCL; to exit, as=
will attempts to
enter a break loop.</para>
</listitem>
=
<listitem>
- <para>-n (or --no-init). If this option is given, the init file
- is not loaded. This is useful if &CCL; is being invoked by a
- shell script which should not be affected by whatever
- customizations a user might have in place.
- </para>
- </listitem>
-
- <listitem>
- <para>-e <form> (or --eval <form>). An expression is
- read (via READ-FROM-STRING from the string <form> and
- evaluated. If <form> contains shell metacharacters, it may be
- necessary to escape or quote them to prevent the shell from
- interpreting them.</para>
- </listitem>
-
- <listitem>
- <para>-l >path> (or --load <path>). Executes (load
- "<path>").</para>
+ <para><literal>--no-sigtrap</literal> An obscure option for running u=
nder GDB.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>-I</literal>
+ <parameter>image-name</parameter> (or
+ <literal>--image-name</literal>
+ <parameter>image-name</parameter>). Specifies the image
+ name for the kernel to load. Defaults to the kernel name
+ with ".image" appended.</para>
</listitem>
</itemizedlist>
=
@@ -370,8 +508,7 @@
the command line, after the init file (if there is one) is
loaded and before the toplevel read-eval-print loop is
entered.</para>
- </sect2>
- </sect1>
+ </sect1>
=
<sect1 id=3D"Using-CCL-with-GNU-Emacs-and-SLIME">
<title>Using &CCL; with GNU Emacs and SLIME</title>
Modified: trunk/source/doc/src/modifying.xml
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D
--- trunk/source/doc/src/modifying.xml (original)
+++ trunk/source/doc/src/modifying.xml Thu Apr 3 01:14:05 2008
@@ -72,8 +72,8 @@
redefinition; that may be useful in some cases.</para>
</sect1>
=
- <sect1 id=3D"Debugging-facilities-in-the-lisp-kernel">
- <title>Debugging facilities in the lisp kernel</title>
+ <sect1 id=3D"kernel-debugger">
+ <title>The Kernel Debugger</title>
<para> In a perfect world, something like this couldn't
happen:</para>
<programlisting>
Modified: trunk/source/doc/src/streams.xml
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D
--- trunk/source/doc/src/streams.xml (original)
+++ trunk/source/doc/src/streams.xml Thu Apr 3 01:14:05 2008
@@ -14,6 +14,140 @@
=
<sect1 id=3D"CCL-Stream-Extensions">
<title>Stream Extensions</title>
+
+ <sect2><title>Stream External Encoding</title>
+ <para>Clozure CL streams have an external-encoding attribute that
+ may be read using
+ <function>STREAM-EXTERNAL-ENCODING</function> and set using <function>=
(SETF
+ STREAM-EXTERNAL-ENCODING)</function>.
+ </para>
+ </sect2>
+
+ <sect2 id=3D"Additional-Open-Keywords">
+ <title>Additional keywords for OPEN and MAKE-SOCKET</title>
+ <para><function>OPEN</function> and
+ <function>MAKE-SOCKET</function> have each been extended to take
+ the additional keyword arguments: <literal>:CLASS</literal>,
+ <literal>:SHARING</literal>, and
+ <literal>:BASIC</literal>.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><literal>:CLASS</literal></term>
+ <listitem>
+ <para>A symbol that names the desired class of the stream.
+ The specified class must inherit from
+ <literal>FILE-STREAM</literal> for
+ <function>OPEN</function>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>:SHARING</literal></term>
+ <listitem>
+ <para>Specifies how a stream can be used by multiple
+ threads. The possible values are:
+ <literal>:PRIVATE</literal>, <literal>:LOCK</literal> and
+ <literal>:EXTERNAL</literal>. <literal>:PRIVATE</literal> is
+ the default. <literal>NIL</literal> is also accepted as a
+ synonym for <literal>:EXTERNAL</literal>.</para>
+ <variablelist>
+ <varlistentry>
+ <term><literal>:PRIVATE</literal></term>
+ <listitem>
+ <para>Specifies that the stream can only be accessed
+ by the thread that created it. This is the default.
+ (There was some discussion on openmcl-devel about the
+ idea of "transferring ownership" of a stream; this has
+ not yet been implemented.) Attempts to do I/O on a
+ stream with :PRIVATE sharing from a thread other than
+ the stream's owner yield an error.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>:LOCK</literal></term>
+ <listitem>
+ <para>Specifies that all access to the stream require
+ the calling thread to obtain a lock. There are
+ separate "read" and "write" locks for IO streams.
+ This makes it possible for instance, for one thread to
+ read from such a stream while another thread writes to
+ it. (see also <xref linkend=3D"f_make-read-write-lock"/>
+ <xref linkend=3D"m_with-read-lock"/> <xref
+ linkend=3D"m_with-write-lock"/>)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>:EXTERNAL</literal></term>
+ <listitem>
+ <para>Specifies that I/O primitives enforce no access
+ protocol. This may be appropriate for some types of
+ application which can control stream access via
+ application-level protocols. Note that since even the
+ act of reading from a stream changes its internal
+ state (and simultaneous access from multiple threads
+ can therefore lead to corruption of that state), some
+ care must be taken in the design of such protocols.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>:BASIC</literal></term>
+ <listitem>
+ <para>A boolean that indicates whether or not the stream is
+ a Gray stream, i.e. whether or not the stream is an instance
+ of <literal>FUNDAMENTAL-STREAM</literal> or
+ <literal>CCL::BASIC-STREAM</literal>(see <xref
+ linkend=3D"Basic-Versus-Fundamental-Streams"/>). Defaults to
+ <literal>T</literal>.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </sect2>
+
+ <sect2 id=3D"Basic-Versus-Fundamental-Streams">
+ <title>Basic Versus Fundamental Streams</title>
+ <para>Gray streams (see <xref
+ linkend=3D"Creating-Your-Own-Stream-Classes-with-Gray-Streams"/>)
+ all inherit from <literal>FUNDAMENTAL-STREAM</literal> whereas
+ basic streams inherit from <literal>CCL::BASIC-STREAM</literal>.
+ The tradeoff between FUNDAMENTAL and BASIC streams is entirely
+ between flexibility and performance, potential or actual. I/O
+ primitives can recognize BASIC-STREAMs and exploit knowledge of
+ implementation details. FUNDAMENTAL stream classes can be
+ subclassed and extended in a standard way (the Gray streams
+ protocol).</para>
+
+ <para>For existing stream classes (FILE-STREAMs, SOCKETs, and
+ the internal CCL::FD-STREAM classes used to implement file
+ streams and sockets), a lot of code can be shared between the
+ FUNDAMENTAL and BASIC implementations. The biggest difference
+ should be that that code can be reached from I/O primitives like
+ READ-CHAR without going through some steps that're there to
+ support generality and extensibility, and skipping those steps
+ when that support isn't needed can improve I/O performance.
+ </para>
+
+ <para>The Gray stream method
+ <function>STREAM-READ-CHAR</function> should work on appropriate
+ <literal>BASIC-STREAM</literal>s. (There may still be cases
+ where such methods are undefined; such cases should be
+ considered bugs.) It is not guaranteed that Gray stream methods
+ would ever be called by I/O primitives to read a character from
+ a <literal>BASIC-STREAM</literal>, though there are still cases
+ where this happens.</para>
+
+ <para>A simple loop reading 2M characters from a text file runs
+ about 10X faster when the file is opened the new defaults
+ <literal>(:SHARING :PRIVATE :BASIC T)</literal> than it had
+ before these changes were made. That sounds good, until one
+ realizes that the "equivalent" C loop can be about 10X faster
+ still ...</para>
+ </sect2>
+
+
<sect2 id=3D"Stream-Timeouts-And-Deadlines">
<title>Stream Timeouts and Deadlines</title>
<indexterm>
Added: trunk/source/doc/src/templates/function
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D
--- trunk/source/doc/src/templates/function (added)
+++ trunk/source/doc/src/templates/function Thu Apr 3 01:14:05 2008
@@ -1,0 +1,59 @@
+
+ <refentry id=3D"f_[fn-name]">
+ <indexterm zone=3D"f_[fn-name]">
+ <primary>[fn-name]</primary>
+ </indexterm>
+
+ <refnamediv>
+ <refname>[FN-NAME]</refname>
+ <refpurpose>[function purpose]</refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <synopsis>
+ <function>[fn-name]</function>
+ [arg] &key; [keyword-arg]
+ =3D> [result]
+ </synopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Arguments and Values</title>
+ =
+ <variablelist>
+ <varlistentry>
+ <term>[arg]</term>
+ <listitem>
+ <para>[description]</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>[keyword-arg]</term>
+ <listitem>
+ <para>[description]</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>[result]</term>
+ <listitem>
+ <para>[description]</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para>[description]</para>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ =
+ <simplelist type=3D"inline">
+ <member><xref linkend=3D"[ref-id]"/></member>
+ </simplelist>
+ </refsect1>
+ </refentry>
Modified: trunk/source/doc/src/threads.xml
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D
--- trunk/source/doc/src/threads.xml (original)
+++ trunk/source/doc/src/threads.xml Thu Apr 3 01:14:05 2008
@@ -167,7 +167,7 @@
=
<sect1 id=3D"Implementation-Decisions-and-Open-Questions">
<title>Implementation Decisions and Open Questions</title>
- <sect2>
+ <sect2 id=3D"Thread-Stack-Sizes">
<title>Thread Stack Sizes</title>
<para>When you use MAKE-PROCESS to create a thread, you can
specify a stack size. &CCL; does not impose a limit on the stack
Modified: trunk/source/doc/src/using.xml
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D
--- trunk/source/doc/src/using.xml (original)
+++ trunk/source/doc/src/using.xml Thu Apr 3 01:14:05 2008
@@ -476,356 +476,632 @@
<command><varname id=3D"trace-bar-frequency">CCL:*TRACE-BAR-FREQUENC=
Y*</varname> [Variable]</command>
</para>
=
- <para>By default, this is nil. If non-nil it should be a integer, and =
the default entry and exit messages will print a | instead of space every t=
his many levels of indentation.</para>
+ <para>By default, this is nil. If non-nil it should be a integer,
+ and the default entry and exit messages will print a | instead of
+ space every this many levels of indentation.</para>
=
=
</sect1>
=
<sect1 id=3D"Unicode"><title>Unicode</title>
=
- <para>All characters and strings in &CCL; fully support Unicode
- by using UTF-32. There is only one <literal>CHARACTER</literal> type
- and one <literal>STRING</literal> in &CCL;. There has been a
- lot of discussion about this decision which can be found by
- searching the openmcl-devel archives at <ulink
- url=3D"http://clozure.com=
/pipermail/openmcl-devel/"/>. Suffice it to
- say that we decided that the simplicity and speed advantages of
- UTF-32 outweigh the space disadvantage.</para>
-
- <sect2><title>Characters</title>
- <para>There is one <literal>CHARACTER</literal> type in &CCL;.
- All <literal>CHARACTER</literal>s are <literal>BASE-CHAR</literal>=
s.
- <varname>CHAR-CODE-LIMIT</varname> is now
- <literal>#x110000</literal>, which means that all Unicode characte=
rs
- can be directly represented. As of Unicode 5.0, only about 100,000
- of 1,114,112 possible <literal>CHAR-CODE</literal>s are actually
- defined. The function <function>CODE-CHAR</function> knows that
- certain ranges of code values (notably
- <literal>#xd800</literal>-<literal>#xddff</literal>) will never be
- valid character codes and will return <literal>NIL</literal> for
- arguments in that range, but may return a non-<literal>NIL</litera=
l>
- value (an undefined/non-standard <literal>CHARACTER</literal>
- object) for other unassigned code values.</para>
- <para>&CCL; supports character names of the form
- <literal>u+xxxx</literal> - where <literal>x</literal> is a sequen=
ce
- of one or more hex digits. The value of the hex digits denotes the
- code of the character. The <literal>+</literal> character is
- optional, so <literal>#\u+0020</literal>,
- <literal>#\U0020</literal>, and <literal>#\U+20</literal> all refer
- to the <literal>#\Space</literal> character.</para>
- <para>Characters with codes in the range
- <literal>#xa0</literal>-<literal>#x7ff</literal> also have symbolic
- names These are the names from the Unicode standard with spaces
- replaced by underscores. So
- <literal>#\Greek_Capital_Letter_Epsilon</literal> can be used to
- refer to the character whose <function>CHAR-CODE</function> is
- <literal>#x395</literal>.</para>
- </sect2>
-
- <sect2 id=3D"External-Formats"><title>External Formats</title>
- <para><function>OPEN</function>, <function>LOAD</function>, and
- <function>COMPILE-FILE</function> all take an
- <literal>:EXTERNAL-FORMAT</literal> keyword argument. The value of
- <literal>:EXTERNAL-FORMAT</literal> can be
- <literal>:DEFAULT</literal> (the default value), a line termination
- keyword <xref linkend=3D"Line-Termination-Keywords"/><xref
- linkend=3D"k=
_external-format"/>, a character encoding keyword <xref
- =
linkend=3D"Character-Enc=
odings"/>, a plist with keys:
- <literal>:CHARACTER-ENCODING</literal> and
- <literal>:LINE-TERMINATION</literal>, or an external-format object
- created using <function>CCL::MAKE-EXTERNAL-FORMAT</function>. If
- <literal>:DEFAULT</literal> is specified, then the value of
- <varname>CCL:*DEFAULT-EXTERNAL-FORMAT*</varname> is used. If no
- line-termination is specified, then the value of
- <varname>CCL:*DEFAULT-LINE-TERMINATION*</varname> is used. If no
- character encoding is specified, then
- <varname>CCL:*DEFAULT-FILE-CHARACTER-ENCODING*</varname> is used f=
or
- file streams and
- <varname>CCL:*DEFAULT-SOCKET-CHARACTER-ENCODING*</varname> is used
- for socket streams. The default, default character encoding is
- <literal>NIL</literal> which is a synonym for <literal>:ISO-8859-1=
</literal>
- </para>
- </sect2>
-
- <sect2 id=3D"Line-Termination-Keywords"><title>Line Termination Keywor=
ds</title>
- <para>Line termination keywords indicate which characters are used
- to indicate the end of a line. On input, the external line
- termination characters are replaced by <literal>#\Newline</literal>
- and on output, <literal>#\Newline</literal>s are converted to the
- external line termination characters.</para>
- <table id=3D"Line-Termination-Table" frame=3D'all'><title>Line Termi=
nation Keywords</title>
- <tgroup cols=3D'2' align=3D'left' colsep=3D'1' rowsep=3D'1'>
- <thead>
- <row>
- <entry>keyword</entry>
- <entry>character(s)</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><literal>:UNIX</literal></entry>
- <entry><literal>#\Linefeed</literal></entry>
- </row>
- <row>
- <entry><literal>:MACOS</literal></entry>
- <entry><literal>#\Return</literal></entry>
- </row>
- <row>
- <entry><literal>:CR</literal></entry>
- <entry><literal>#\Return</literal></entry>
- </row>
- <row>
- <entry><literal>:CRLF</literal></entry>
- <entry><literal>#\Return #\Linefeed</literal></entry>
- </row>
- <row>
- <entry><literal>:CP/M</literal></entry>
- <entry><literal>#\Return #\Linefeed</literal></entry>
- </row>
- <row>
- <entry><literal>:MSDOS</literal></entry>
- <entry><literal>#\Return #\Linefeed</literal></entry>
- </row>
- <row>
- <entry><literal>:DOS</literal></entry>
- <entry><literal>#\Return #\Linefeed</literal></entry>
- </row>
- <row>
- <entry><literal>:WINDOWS</literal></entry>
- <entry><literal>#\Return #\Linefeed</literal></entry>
- </row>
- <row>
- <entry><literal>:INFERRED</literal></entry>
- <entry>see below</entry>
- </row>
- <row>
- <entry><literal>:UNICODE</literal></entry>
- <entry><literal>#\Line_Separator</literal></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <para><literal>:INFERRED</literal> means try to guess a stream's
- line-termination conventions. It is only useful for
- <literal>FILE-STREAM</literal>s that are open for <literal>:INPUT<=
/literal> or <literal>:IO</literal>. The first buffer full of data is exam=
ined, and if a <literal>#\Return</literal> character occurs before any <lit=
eral>#\Linefeed</literal> character, then the line termination type is set =
to <literal>:MACOS</literal>, otherwise it is set to <literal>:UNIX</litera=
l>.</para>
- </sect2>
- =
-
- <sect2 id=3D"Character-Encodings"><title>Character Encodings</title>
- <para>Internally, all characters and strings in &CCL; are in
- UTF-32. Externally, files or socket streams may encode characters
- in a wide variety of ways. The International Organization for
- Standardization, widely known as ISO defines a number of these
- character encodings. &CCL; implements a number of these
- encodings as detailed below. These encodings are part of the
- specification of external formats (see <xref
- linkend=3D"External-Form=
ats"/>. When reading from a stream,
- characters are converted from the specified external character
- encoding to UTF-32. When writing to a stream, characters are
- converted from UTF-32 to the specified character encoding. Here is
- a list of character encoding keywords used to specify a standard
- character encoding.</para>
- <variablelist>
- <varlistentry><term><literal>:ISO-8859-1</literal></term>
- <listitem><para>An 8-bit, fixed-width character encoding in
- which all character codes map to their Unicode
- equivalents. Intended to support most characters used in most
- Western European languages.</para></listitem>
- </varlistentry>
- <varlistentry><term><literal>:ISO-8859-2</literal></term>
- <listitem><para>An 8-bit, fixed-width character encoding in
- which codes #x00-#x9f map to their Unicode equivalents and
- other codes map to other Unicode character values. Intended=
to
- provide most characters found in most languages used in
- Central/Eastern Europe.</para></listitem>
- </varlistentry>
- <varlistentry><term><literal>:ISO-8859-3</literal></term>
- <listitem><para>An 8-bit, fixed-width character encoding in
- which codes #x00-#x9f map to their Unicode equivalents and
- other codes map to other Unicode character values. Intended=
to
- provide most characters found in most languages used in
- Southern Europe.</para></listitem>
- </varlistentry>
- <varlistentry><term><literal>:ISO-8859-4</literal></term>
- <listitem><para>An 8-bit, fixed-width character encoding in
- which codes #x00-#x9f map to their Unicode equivalents and
- other codes map to other Unicode character values. Intended=
to
- provide most characters found in most languages used in
- Northern Europe.</para></listitem>
- </varlistentry>
- <varlistentry><term><literal>:ISO-8859-5</literal></term>
- <listitem><para>An 8-bit, fixed-width character encoding in
- which codes #x00-#x9f map to their Unicode equivalents and
- other codes map to other Unicode character values. Intended=
to
- provide most characters found in the Cyrillic
- alphabet.</para></listitem>
- </varlistentry>
- <varlistentry><term><literal>:ISO-8859-6</literal></term>
- <listitem><para>An 8-bit, fixed-width character encoding in
- which codes #x00-#x9f map to their Unicode equivalents and
- other codes map to other Unicode character values. Intended=
to
- provide most characters found in the Arabic
- alphabet.</para></listitem>
- </varlistentry>
- <varlistentry><term><literal>:ISO-8859-7</literal></term>
- <listitem><para>An 8-bit, fixed-width character encoding in
- which codes #x00-#x9f map to their Unicode equivalents and
- other codes map to other Unicode character values. Intended=
to
- provide most characters found in the Greek
- alphabet.</para></listitem>
- </varlistentry>
- <varlistentry><term><literal>:ISO-8859-8</literal></term>
- <listitem><para>An 8-bit, fixed-width character encoding in
- which codes #x00-#x9f map to their Unicode equivalents and
- other codes map to other Unicode character values. Intended=
to
- provide most characters found in the Hebrew
- alphabet.</para></listitem>
- </varlistentry>
- <varlistentry><term><literal>:ISO-8859-9</literal></term>
- <listitem><para>An 8-bit, fixed-width character encoding in
- which codes #x00-#xcf map to their Unicode equivalents and
- other codes map to other Unicode character values. Intended=
to
- provide most characters found in the Turkish
- alphabet.</para></listitem>
- </varlistentry>
- <varlistentry><term><literal>:ISO-8859-10</literal></term>
- <listitem><para>An 8-bit, fixed-width character encoding in
- which codes #x00-#x9f map to their Unicode equivalents and
- other codes map to other Unicode character values. Intended=
to
- provide most characters found in Nordic
- alphabets.</para></listitem>
- </varlistentry>
- <varlistentry><term><literal>:ISO-8859-11</literal></term>
- <listitem><para>An 8-bit, fixed-width character encoding in
- which codes #x00-#x9f map to their Unicode equivalents and
- other codes map to other Unicode character values. Intended=
to
- provide most characters found the Thai
- alphabet.</para></listitem>
- </varlistentry>
- <varlistentry><term><literal>:ISO-8859-13</literal></term>
- <listitem><para>An 8-bit, fixed-width character encoding in
- which codes #x00-#x9f map to their Unicode equivalents and
- other codes map to other Unicode character values. Intended=
to
- provide most characters found in Baltic
- alphabets.</para></listitem>
- </varlistentry>
- <varlistentry><term><literal>:ISO-8859-14</literal></term>
- <listitem><para>An 8-bit, fixed-width character encoding in
- which codes #x00-#x9f map to their Unicode equivalents and
- other codes map to other Unicode character values. Intended=
to
- provide most characters found in Celtic
- languages.</para></listitem>
- </varlistentry>
- <varlistentry><term><literal>:ISO-8859-15</literal></term>
- <listitem><para>An 8-bit, fixed-width character encoding in
- which codes #x00-#x9f map to their Unicode equivalents and
- other codes map to other Unicode character values. Intended=
to
- provide most characters found in Western European languages
- (including the Euro sign and some other characters missing f=
rom
- ISO-8859-1.</para></listitem>
- </varlistentry>
- <varlistentry><term><literal>:ISO-8859-16</literal></term>
- <listitem><para>An 8-bit, fixed-width character encoding in
- which codes #x00-#x9f map to their Unicode equivalents and
- other codes map to other Unicode character values. Intended=
to
- provide most characters found in Southeast European
- languages.</para></listitem>
- </varlistentry>
- <varlistentry><term><literal>:MACINTOSH</literal></term>
- <listitem><para>An 8-bit, fixed-width character encoding in
- which codes #x00-#x7f map to their Unicode equivalents and
- other codes map to other Unicode character values.
- Traditionally used on Classic MacOS to encode characters used
- in western languages.</para></listitem>
- </varlistentry>
- <varlistentry><term><literal>:UCS-2</literal></term>
- <listitem><para>A 16-bit, fixed-length encoding in which
- characters with CHAR-CODEs less than #x10000 can be encoded =
in
- a single 16-bit word. The endianness of the encoded data is
- indicated by the endianness of a byte-order-mark character
- (#u+feff) prepended to the data; in the absence of such a
- character on input, the data is assumed to be in big-endian
- order.</para></listitem>
- </varlistentry>
- <varlistentry><term><literal>:UCS-2BE</literal></term>
- <listitem><para>A 16-bit, fixed-length encoding in which
- characters with CHAR-CODEs less than #x10000 can be encoded =
in
- a single 16-bit big-endian word. The encoded data is implici=
tly
- big-endian; byte-order-mark characters are not interpreted on
- input or prepended to output.</para></listitem>
- </varlistentry>
- <varlistentry><term><literal>:UCS-2LE</literal></term>
- <listitem><para>A 16-bit, fixed-length encoding in which
- characters with CHAR-CODEs less than #x10000 can be encoded =
in
- a single 16-bit little-endian word. The encoded data is
- implicitly little-endian; byte-order-mark characters are not
- interpreted on input or prepended to output.</para></listite=
m>
- </varlistentry>
- <varlistentry><term><literal>:US-ASCII</literal></term>
- <listitem><para>An 7-bit, fixed-width character encoding in
- which all character codes map to their Unicode
- equivalents. </para></listitem>
- </varlistentry>
- <varlistentry><term><literal>:UTF-16</literal></term>
- <listitem><para>A 16-bit, variable-length encoding in which
- characters with CHAR-CODEs less than #x10000 can be encoded =
in
- a single 16-bit word and characters with larger codes can be
- encoded in a pair of 16-bit words. The endianness of the
- encoded data is indicated by the endianness of a
- byte-order-mark character (#u+feff) prepended to the data; in
- the absence of such a character on input, the data is assumed
- to be in big-endian order. Output is written in native
- byte-order with a leading byte-order mark.</para></listitem>
- </varlistentry>
- <varlistentry><term><literal>:UTF-16BE</literal></term>
- <listitem><para>A 16-bit, variable-length encoding in which
- characters with CHAR-CODEs less than #x10000 can be encoded =
in
- a single 16-bit big-endian word and characters with larger
- codes can be encoded in a pair of 16-bit big-endian words. =
The
- endianness of the encoded data is implicit in the encoding;
- byte-order-mark characters are not interpreted on input or
- prepended to output.</para></listitem>
- </varlistentry>
- <varlistentry><term><literal>:UTF-16LE</literal></term>
- <listitem><para>A 16-bit, variable-length encoding in which
- characters with CHAR-CODEs less than #x10000 can be encoded =
in
- a single 16-bit little-endian word and characters with larger
- codes can be encoded in a pair of 16-bit little-endian words.
- The endianness of the encoded data is implicit in the encodi=
ng;
- byte-order-mark characters are not interpreted on input or
- prepended to output.</para></listitem>
- </varlistentry>
- <varlistentry><term><literal>:UTF-32</literal></term>
- <listitem><para>A 32-bit, fixed-length encoding in which all
- Unicode characters can be encoded in a single 32-bit word. =
The
- endianness of the encoded data is indicated by the endianness
- of a byte-order-mark character (#u+feff) prepended to the da=
ta;
- in the absence of such a character on input, input data is
- assumed to be in big-endian order. Output is written in nat=
ive
- byte order with a leading byte-order mark.</para></listitem>
- </varlistentry>
- <varlistentry><term><literal>:UTF-32BE</literal></term>
- <listitem><para>A 32-bit, fixed-length encoding in which all
- Unicode characters encoded in a single 32-bit word. The enco=
ded
- data is implicitly big-endian; byte-order-mark characters are
- not interpreted on input or prepended to
- output.</para></listitem>
- </varlistentry>
- <varlistentry><term><literal>:UTF-8</literal></term>
- <listitem><para>An 8-bit, variable-length character encoding in
- which characters with CHAR-CODEs in the range #x00-#x7f can =
be
- encoded in a single octet; characters with larger code values
- can be encoded in 2 to 4 bytes.</para></listitem>
- </varlistentry>
- <varlistentry><term><literal>:UTF32LE</literal></term>
- <listitem><para>A 32-bit, fixed-length encoding in which all
- Unicode characters can encoded in a single 32-bit word. The
- encoded data is implicitly little-endian; byte-order-mark
- characters are not interpreted on input or prepended to
- output.</para></listitem>
- </varlistentry>
- </variablelist>
- </sect2>
+ <para>All characters and strings in &CCL; fully support Unicode by
+ using UTF-32. There is only one <literal>CHARACTER</literal> type
+ and one <literal>STRING</literal> type in &CCL;. There has been a
+ lot of discussion about this decision which can be found by
+ searching the openmcl-devel archives at <ulink
+ url=3D"http://clozure.com/pipermail/openmcl-devel/"/>. Suffice it
+ to say that we decided that the simplicity and speed advantages of
+ only supporting UTF-32 outweigh the space disadvantage.</para>
+
+
+
+ <sect2><title>Characters</title>
+ <para>There is one <literal>CHARACTER</literal> type in &CCL;.
+ All <literal>CHARACTER</literal>s are
+ <literal>BASE-CHAR</literal>s. <varname>CHAR-CODE-LIMIT</varname>
+ is now <literal>#x110000</literal>, which means that all Unicode
+ characters can be directly represented. As of Unicode 5.0, only
+ about 100,000 of 1,114,112 possible <literal>CHAR-CODE</literal>s
+ are actually defined. The function <function>CODE-CHAR</function>
+ knows that certain ranges of code values (notably
+ <literal>#xd800</literal>-<literal>#xddff</literal>) will never be
+ valid character codes and will return <literal>NIL</literal> for
+ arguments in that range, but may return a
+ non-<literal>NIL</literal> value (an undefined/non-standard
+ <literal>CHARACTER</literal> object) for other unassigned code
+ values.</para>
+
+ <para>&CCL; supports character names of the form
+ <literal>u+xxxx</literal> - where <literal>x</literal> is a
+ sequence of one or more hex digits. The value of the hex digits
+ denotes the code of the character. The <literal>+</literal>
+ character is optional, so <literal>#\u+0020</literal>,
+ <literal>#\U0020</literal>, and <literal>#\U+20</literal> all
+ refer to the <literal>#\Space</literal> character.</para>
+
+ <para>Characters with codes in the range
+ <literal>#xa0</literal>-<literal>#x7ff</literal> also have
+ symbolic names These are the names from the Unicode standard with
+ spaces replaced by underscores. So
+ <literal>#\Greek_Capital_Letter_Epsilon</literal> can be used to
+ refer to the character whose <function>CHAR-CODE</function> is
+ <literal>#x395</literal>. To see the complete list of supported
+ character names, look just below the definition for
+ <function>register-character-name</function> in
+ <literal>ccl:level-1;l1-reader.lisp</literal> see the complete
+ list of char</para>
+ </sect2>
+
+
+ <sect2 id=3D"External-Formats"><title>External Formats</title>
+ <para><function>OPEN</function>, <function>LOAD</function>, and
+ <function>COMPILE-FILE</function> all take an
+ <literal>:EXTERNAL-FORMAT</literal> keyword argument. The value
+ of <literal>:EXTERNAL-FORMAT</literal> can be
+ <literal>:DEFAULT</literal> (the default value), a line
+ termination keyword (see <xref
+ linkend=3D"Line-Termination-Keywords"/>), a character encoding
+ keyword (see <xref linkend=3D"Character-Encodings"/>), an
+ external-format object created using
+ <function>CCL::MAKE-EXTERNAL-FORMAT</function>(see <xref
+ linkend=3D"f_make-external-format"/>), or a plist with keys:
+ <literal>:DOMAIN</literal>, <literal>:CHARACTER-ENCODING</literal>
+ and <literal>:LINE-TERMINATION</literal>. If
+ <parameter>argument</parameter> is a plist, the result of
+ <literal>(APPLY #'MAKE-EXTERNAL-FORMAT
+ <parameter>argument</parameter>)</literal> will be used.</para>
+
+ <para>If <literal>:DEFAULT</literal> is specified, then the value
+ of <varname>CCL:*DEFAULT-EXTERNAL-FORMAT*</varname> is used. If
+ no line-termination is specified, then the value of
+ <varname>CCL:*DEFAULT-LINE-TERMINATION*</varname> is used, which
+ defaults to <literal>:UNIX</literal>. If no character encoding is
+ specified, then
+ <varname>CCL:*DEFAULT-FILE-CHARACTER-ENCODING*</varname> is used
+ for file streams and
+ <varname>CCL:*DEFAULT-SOCKET-CHARACTER-ENCODING*</varname> is used
+ for socket streams. The default, default character encoding is
+ <literal>NIL</literal> which is a synonym for
+ <literal>:ISO-8859-1</literal>.</para>
+
+ <para>Note that the set of keywords used to denote
+ CHARACTER-ENCODINGs and the set of keywords used to denote
+ line-termination conventions is disjoint: a keyword denotes at
+ most a character encoding or a line termination convention, but
+ never both.</para>
+
+ <para>EXTERNAL-FORMATs are objects (structures) with three
+ read-only fields that can be accessed via the functions:
+ <function>EXTERNAL-FORMAT-DOMAIN</function>,
+ <function>EXTERNAL-FORMAT-LINE-TERMINATION</function> and
+ <function>EXTERNAL-FORMAT-CHARACTER-ENCODING</function>.</para>
+
+ =
+ <refentry id=3D"f_make-external-format">
+ <indexterm zone=3D"f_make-external-format">
+ <primary>make-external-format</primary>
+ </indexterm>
+ =
+ <refnamediv>
+ <refname>MAKE-EXTERNAL-FORMAT</refname>
+ <refpurpose>Either creates a new external format object, or
+ return an existing one with the same specified slot
+ values.</refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <synopsis>
+ <function>make-external-format</function>
+ &key; domain character-encoding line-termination
+ =3D> external-format
+ </synopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Arguments and Values</title>
+ =
+ <variablelist>
+ <varlistentry>
+ <term>domain</term>
+ <listitem>
+ <para>This is used to indicate where the external
+ format is to be used. Its value can be almost
+ anything. It defaults to <literal>NIL</literal>.
+ There are two domains that have a pre-defined meaning in
+ Clozure CL: <literal>:FILE</literal> indicates
+ encoding for a file in the file system and
+ <literal>:SOCKET</literal> indicates i/o to/from a
+ socket. The value of <parameter>domain</parameter>
+ affects the default values for
+ <parameter>character-encoding</parameter> and
+ <parameter>line-termination</parameter>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>character-encoding</term>
+ <listitem>
+ <para>A keyword that specifies the character encoding
+ for the external format. <xref
+ linkend=3D"Character-Encodings"/>. Defaults to
+ <literal>:DEFAULT</literal> which means if
+ <parameter>domain</parameter> is
+ <literal>:FILE</literal> use the value of the variable
+ <varname>CCL:*DEFAULT-FILE-CHARACTER-ENCODING*</varname>
+ and if <parameter>domain</parameter> is
+ <literal>:SOCKET</literal>, use the value of the
+ variable
+ <varname>CCL:*DEFAULT-SOCKET-CHARACTER-ENCODING*</varname>.
+ The initial value of both of these variables is
+ <literal>NIL</literal>, which means the
+ <literal>:ISO-8859-1</literal> encoding.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>line-termination</term>
+ <listitem>
+ <para>A keyword that indicates a line termination
+ keyword <xref linkend=3D"Line-Termination-Keywords"/>.
+ Defaults to <literal>:DEFAULT</literal> which means
+ use the value of the variable
+ <varname>CCL:*DEFAULT-LINE-TERMINATION*</varname>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>[result]</term>
+ <listitem>
+ <para>[description]</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ =
+ <refsect1>
+ <title>Description</title>
+ =
+ <para>Despite the function's name, it doesn't necessarily
+ create a new, unique EXTERNAL-FORMAT object: two calls to
+ MAKE-EXTERNAL-FORMAT with the same arguments made in the
+ same dynamic environment will return the same (eq) object.
+ </para>
+ </refsect1>
+ </refentry>
+
+ </sect2>
+
+ <sect2 id=3D"Line-Termination-Keywords"><title>Line Termination Keywords=
</title>
+ <para>Line termination keywords indicate which characters are used
+ to indicate the end of a line. On input, the external line
+ termination characters are replaced by <literal>#\Newline</literal>
+ and on output, <literal>#\Newline</literal>s are converted to the
+ external line termination characters.</para>
+ <table id=3D"Line-Termination-Table" frame=3D'all'><title>Line Terminati=
on Keywords</title>
+ <tgroup cols=3D'2' align=3D'left' colsep=3D'1' rowsep=3D'1'>
+ <thead>
+ <row>
+ <entry>keyword</entry>
+ <entry>character(s)</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>:UNIX</literal></entry>
+ <entry><literal>#\Linefeed</literal></entry>
+ </row>
+ <row>
+ <entry><literal>:MACOS</literal></entry>
+ <entry><literal>#\Return</literal></entry>
+ </row>
+ <row>
+ <entry><literal>:CR</literal></entry>
+ <entry><literal>#\Return</literal></entry>
+ </row>
+ <row>
+ <entry><literal>:CRLF</literal></entry>
+ <entry><literal>#\Return #\Linefeed</literal></entry>
+ </row>
+ <row>
+ <entry><literal>:CP/M</literal></entry>
+ <entry><literal>#\Return #\Linefeed</literal></entry>
+ </row>
+ <row>
+ <entry><literal>:MSDOS</literal></entry>
+ <entry><literal>#\Return #\Linefeed</literal></entry>
+ </row>
+ <row>
+ <entry><literal>:DOS</literal></entry>
+ <entry><literal>#\Return #\Linefeed</literal></entry>
+ </row>
+ <row>
+ <entry><literal>:WINDOWS</literal></entry>
+ <entry><literal>#\Return #\Linefeed</literal></entry>
+ </row>
+ <row>
+ <entry><literal>:INFERRED</literal></entry>
+ <entry>see below</entry>
+ </row>
+ <row>
+ <entry><literal>:UNICODE</literal></entry>
+ <entry><literal>#\Line_Separator</literal></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para><literal>:INFERRED</literal> means that a stream's
+ line-termination convention is determined by looking at the contents
+ of a file. It is only useful for <literal>FILE-STREAM</literal>s
+ that're open for <literal>:INPUT</literal> or
+ <literal>:IO</literal>. The first buffer full of data is examined,
+ and if a <literal>#\Return</literal> character occurs before any
+ <literal>#\Linefeed</literal> character, then the line termination
+ type is set to <literal>:MACOS</literal>, otherwise it is set to
+ <literal>:UNIX</literal>.</para>
+ </sect2>
+ =
+
+
+ <sect2 id=3D"Character-Encodings"><title>Character Encodings</title>
+ <para>Internally, all characters and strings in &CCL; are in
+ UTF-32. Externally, files or socket streams may encode characters
+ in a wide variety of ways. The International Organization for
+ Standardization, widely known as ISO, defines many of these
+ character encodings. &CCL; implements some of these encodings as
+ detailed below. These encodings are part of the specification of
+ external formats <xref linkend=3D"External-Formats"/>. When reading
+ from a stream, characters are converted from the specified
+ external character encoding to UTF-32. When writing to a stream,
+ characters are converted from UTF-32 to the specified character
+ encoding.</para>
+
+ <para>Internally, CHARACTER-ENCODINGs are objects (structures)
+ that are named by character encoding keywords (:ISO-8859-1,
+ :UTF-8, etc.). The structures contain attributes of the encoding
+ and functions used to encode/decode external data, but unless
+ you're trying to define or debug an encoding there's little reason
+ to know much about the CHARACTER-ENCODING objects and it's usually
+ preferable to refer to a character encoding by its name.
+ </para>
+
+ <para>
+ </para>
+
+ <sect3><title>Encoding Problems</title>
+ <para>On output to streams with character encodings that can
+ encode the full range of Unicode - and on input from any stream
+ - "unencodable characters" are represented using the Unicode
+ #\Replacement_Character (=3D #\U+fffd); the presence of such a
+ character usually indicates that something got lost in
+ translation. Either data wasn't encoded properly or there was a
+ bug in the decoding process.</para>
+ </sect3>
+
+ <sect3><title>Byte Order Marks</title>
+ <para>The endianness of a character encoding is sometimes
+ explicit, and sometimes not. For example,
+ <literal>:UTF-16BE</literal> indicates big-endian, but
+ <literal>:UTF-16</literal> does not specify endianness. A byte
+ order mark is a special character that may appear at the
+ beginning of a stream of encoded characters to specify the
+ endianness of a multi-byte character encoding. (It may also be
+ used with UTF-8 character encodings, where it is simply used to
+ indicate that the encoding is UTF-8.)</para>
+
+ <para>Clozure CL will write a byte order mark as the first
+ character of a file or socket stream when the endianness of the
+ character encoding is not explicit. Clozure CL also expects a
+ byte order mark on input from streams where the endianness is
+ not explicit. If a byte order mark is missing from input data,
+ that data is assumed to be in big-endian order.</para>
+
+ <para>A byte order mark from a UTF-8 encoded input stream is not
+ treated specially and and will just appear as normal character
+ from the input stream. It is probably a good idea to skip over
+ this character.</para>
+ </sect3>
+
+ <sect3><title><function>DESCRIBE-CHARACTER-ENCODINGS</function></title>
+ <para>The set of character encodings supported by Clozure CL can be
+ retrieved by calling
+ <function>CCL:DESCRIBE-CHARACTER-ENCODINGS</function>.</para>
+
+
+ <refentry id=3D"f_describe-character-encodings">
+ <indexterm zone=3D"f_describe-character-encodings">
+ <primary>[fn-name]</primary>
+ </indexterm>
+
+ <refnamediv>
+ <refname>DESCRIBE-CHARACTER-ENCODINGS</refname>
+ <refpurpose>Writes descriptions of defined character
+ encodings to <varname>*terminal-io*</varname>.</refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <synopsis>
+ <function>describe-character-encodings</function>
+ </synopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para>Writes descriptions of all defined character encodings
+ to <varname>*terminal-io*</varname>. These descriptions
+ include the names of the encoding's aliases and a doc string
+ which briefly describes each encoding's properties and
+ intended use.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ =
+ <simplelist type=3D"inline">
+ <member><xref linkend=3D"Character-Encodings"/></member>
+ <member><xref linkend=3D"External-Formats"/></member>
+ <member><xref linkend=3D"Supported-Character-Encodings"/></member>
+ </simplelist>
+ </refsect1>
+ </refentry>
+ </sect3>
+
+ <sect3 id=3D"Supported-Character-Encodings"><title>Supported Character E=
ncodings</title>
+ <para>The list of supported encodings is reproduced here. Most
+ encodings have aliases, e.g. the encoding named
+ <literal>:ISO-8859-1</literal> can also be referred to by the
+ names <literal>:LATIN1</literal> and <literal>:IBM819</literal>,
+ among others. Where possible, the keywordized name of an
+ encoding is equivalent to the preferred MIME charset name (and
+ the aliases are all registered IANA charset names.)</para>
+
+ <variablelist>
+ <varlistentry><term><literal>:ISO-8859-1</literal></term>
+ <listitem><para>An 8-bit, fixed-width character encoding in
+ which all character codes map to their Unicode
+ equivalents. Intended to support most characters used in most
+ Western European languages.</para>
+ <para>Clozure CL uses ISO-8859-1 encoding for
+ <varname>*TERMINAL-IO*</varname> and for all streams whose
+ EXTERNAL-FORMAT isn't explicitly specified. The default for
+ <varname>*TERMINAL-IO*</varname> can be set via the
+ <literal>-K</literal> command-line argument (see <xref
+ linkend=3D"Command-Line-Options"/>).
+ </para>
+ <para>ISO-8859-1 just covers the first 256 Unicode code
+ points, where the first 128 code points are equivalent to
+ US-ASCII. That should be pretty much equivalent to what
+ earliers versions of Clozure CL did that only supported 8-bit chara=
cters,
+ but it may not be optimal for users working in a particular
+ locale.</para>
+ <para>Aliases: <literal>:ISO_8859-1, :LATIN1, :L1,
+ :IBM819, :CP819, :CSISOLATIN1</literal></para></listitem>
+ </varlistentry>
+ <varlistentry><term><literal>:ISO-8859-2</literal></term>
+ <listitem><para>An 8-bit, fixed-width character encoding in
+ which codes #x00-#x9f map to their Unicode equivalents and
+ other codes map to other Unicode character values. Intended to
+ provide most characters found in most languages used in
+ Central/Eastern Europe.</para>
+ <para>Aliases: <literal>:ISO_8859-2, :LATIN-2, :L2,
+ :CSISOLATIN2</literal></para></listitem>
+ </varlistentry>
+ <varlistentry><term><literal>:ISO-8859-3</literal></term>
+ <listitem><para>An 8-bit, fixed-width character encoding in
+ which codes #x00-#x9f map to their Unicode equivalents and
+ other codes map to other Unicode character values. Intended to
+ provide most characters found in most languages used in
+ Southern Europe.</para>
+ <para>Aliases: <literal>:ISO_8859-3, :LATIN,3 :L3,
+ :CSISOLATIN3</literal></para></listitem>
+ </varlistentry>
+ <varlistentry><term><literal>:ISO-8859-4</literal></term>
+ <listitem><para>An 8-bit, fixed-width character encoding in
+ which codes #x00-#x9f map to their Unicode equivalents and
+ other codes map to other Unicode character values. Intended to
+ provide most characters found in most languages used in
+ Northern Europe.</para>
+ <para>Aliases: <literal>:ISO_8859-4, :LATIN4, :L4, :CSISOLATIN4</li=
teral></para></listitem>
+ </varlistentry>
+ <varlistentry><term><literal>:ISO-8859-5</literal></term>
+ <listitem><para>An 8-bit, fixed-width character encoding in
+ which codes #x00-#x9f map to their Unicode equivalents and
+ other codes map to other Unicode character values. Intended to
+ provide most characters found in the Cyrillic
+ alphabet.</para>
+ <para>Aliases: <literal>:ISO_8859-5, :CYRILLIC, :CSISOLATINCYRILLIC,
+ :ISO-IR-144</literal></para></listitem>
+ </varlistentry>
+ <varlistentry><term><literal>:ISO-8859-6</literal></term>
+ <listitem><para>An 8-bit, fixed-width character encoding in
+ which codes #x00-#x9f map to their Unicode equivalents and
+ other codes map to other Unicode character values. Intended to
+ provide most characters found in the Arabic
+ alphabet.</para>
+ <para>Aliases: <literal>:ISO_8859-6, :ARABIC, :CSISOLATINARABIC,
+ :ISO-IR-127</literal></para></listitem>
+ </varlistentry>
+ <varlistentry><term><literal>:ISO-8859-7</literal></term>
+ <listitem><para>An 8-bit, fixed-width character encoding in
+ which codes #x00-#x9f map to their Unicode equivalents and
+ other codes map to other Unicode character values. Intended to
+ provide most characters found in the Greek
+ alphabet.</para>
+ <para>Aliases: <literal>:ISO_8859-7, :GREEK, :GREEK8, :CSISOLATINGR=
EEK,
+ :ISO-IR-126, :ELOT_928, :ECMA-118</literal></para></listitem>
+ </varlistentry>
+ <varlistentry><term><literal>:ISO-8859-8</literal></term>
+ <listitem><para>An 8-bit, fixed-width character encoding in
+ which codes #x00-#x9f map to their Unicode equivalents and
+ other codes map to other Unicode character values. Intended to
+ provide most characters found in the Hebrew
+ alphabet.</para>
+ <para>Aliases: <literal>:ISO_8859-8, :HEBREW, :CSISOLATINHEBREW,
+ :ISO-IR-138</literal></para></listitem>
+ </varlistentry>
+ <varlistentry><term><literal>:ISO-8859-9</literal></term>
+ <listitem><para>An 8-bit, fixed-width character encoding in
+ which codes #x00-#xcf map to their Unicode equivalents and
+ other codes map to other Unicode character values. Intended to
+ provide most characters found in the Turkish
+ alphabet.</para>
+ <para>Aliases: <literal>:ISO_8859-9, :LATIN5, :CSISOLATIN5,
+ :ISO-IR-148</literal></para></listitem>
+ </varlistentry>
+ <varlistentry><term><literal>:ISO-8859-10</literal></term>
+ <listitem><para>An 8-bit, fixed-width character encoding in
+ which codes #x00-#x9f map to their Unicode equivalents and
+ other codes map to other Unicode character values. Intended to
+ provide most characters found in Nordic
+ alphabets.</para>
+ <para>Aliases: <literal>:ISO_8859-10, :LATIN6, :CSISOLATIN6,
+ :ISO-IR-157</literal></para></listitem>
+ </varlistentry>
+ <varlistentry><term><literal>:ISO-8859-11</literal></term>
+ <listitem><para>An 8-bit, fixed-width character encoding in
+ which codes #x00-#x9f map to their Unicode equivalents and
+ other codes map to other Unicode character values. Intended to
+ provide most characters found the Thai
+ alphabet.</para></listitem>
+ </varlistentry>
+ <varlistentry><term><literal>:ISO-8859-13</literal></term>
+ <listitem><para>An 8-bit, fixed-width character encoding in
+ which codes #x00-#x9f map to their Unicode equivalents and
+ other codes map to other Unicode character values. Intended to
+ provide most characters found in Baltic
+ alphabets.</para></listitem>
+ </varlistentry>
+ <varlistentry><term><literal>:ISO-8859-14</literal></term>
+ <listitem><para>An 8-bit, fixed-width character encoding in
+ which codes #x00-#x9f map to their Unicode equivalents and
+ other codes map to other Unicode character values. Intended to
+ provide most characters found in Celtic
+ languages.</para>
+ <para>Aliases: <literal>:ISO_8859-14, :ISO-IR-199, :LATIN8, :L8,
+ :ISO-CELTIC</literal></para></listitem>
+ </varlistentry>
+ <varlistentry><term><literal>:ISO-8859-15</literal></term>
+ <listitem><para>An 8-bit, fixed-width character encoding in
+ which codes #x00-#x9f map to their Unicode equivalents and
+ other codes map to other Unicode character values. Intended to
+ provide most characters found in Western European languages
+ (including the Euro sign and some other characters missing from
+ ISO-8859-1.</para>
+ <para>Aliases: <literal>:ISO_8859-15, :LATIN9</literal></para></lis=
titem>
+ </varlistentry>
+ <varlistentry><term><literal>:ISO-8859-16</literal></term>
+ <listitem><para>An 8-bit, fixed-width character encoding in
+ which codes #x00-#x9f map to their Unicode equivalents and
+ other codes map to other Unicode character values. Intended to
+ provide most characters found in Southeast European
+ languages.</para>
+ <para>Aliases: <literal>:ISO_8859-16, :ISO-IR-199, :LATIN8, :L8,
+ :ISO-CELTIC</literal></para></listitem>
+ </varlistentry>
+ <varlistentry><term><literal>:MACINTOSH</literal></term>
+ <listitem><para>An 8-bit, fixed-width character encoding in
+ which codes #x00-#x7f map to their Unicode equivalents and
+ other codes map to other Unicode character values.
+ Traditionally used on Classic MacOS to encode characters used
+ in western languages.</para>
+ <para>Aliases: <literal>:MACOS-ROMAN, :MACOSROMAN, :MAC-ROMAN,
+ :MACROMAN</literal></para></listitem>
+ </varlistentry>
+ <varlistentry><term><literal>:UCS-2</literal></term>
+ <listitem><para>A 16-bit, fixed-length encoding in which
+ characters with CHAR-CODEs less than #x10000 can be encoded in
+ a single 16-bit word. The endianness of the encoded data is
+ indicated by the endianness of a byte-order-mark character
+ (#u+feff) prepended to the data; in the absence of such a
+ character on input, the data is assumed to be in big-endian
+ order.</para></listitem>
+ </varlistentry>
+ <varlistentry><term><literal>:UCS-2BE</literal></term>
+ <listitem><para>A 16-bit, fixed-length encoding in which
+ characters with CHAR-CODEs less than #x10000 can be encoded in
+ a single 16-bit big-endian word. The encoded data is implicitly
+ big-endian; byte-order-mark characters are not interpreted on
+ input or prepended to output.</para></listitem>
+ </varlistentry>
+ <varlistentry><term><literal>:UCS-2LE</literal></term>
+ <listitem><para>A 16-bit, fixed-length encoding in which
+ characters with CHAR-CODEs less than #x10000 can be encoded in
+ a single 16-bit little-endian word. The encoded data is
+ implicitly little-endian; byte-order-mark characters are not
+ interpreted on input or prepended to output.</para></listitem>
+ </varlistentry>
+ <varlistentry><term><literal>:US-ASCII</literal></term>
+ <listitem><para>An 7-bit, fixed-width character encoding in
+ which all character codes map to their Unicode
+ equivalents. </para>
+ <para>Aliases: <literal>:CSASCII, :CP63,7 :IBM637, :US,
+ :ISO646-US, :ASCII, :ISO-IR-6</literal></para></listitem>
+ </varlistentry>
+ <varlistentry><term><literal>:UTF-16</literal></term>
+ <listitem><para>A 16-bit, variable-length encoding in which
+ characters with CHAR-CODEs less than #x10000 can be encoded in
+ a single 16-bit word and characters with larger codes can be
+ encoded in a pair of 16-bit words. The endianness of the
+ encoded data is indicated by the endianness of a
+ byte-order-mark character (#u+feff) prepended to the data; in
+ the absence of such a character on input, the data is assumed
+ to be in big-endian order. Output is written in native
+ byte-order with a leading byte-order mark.</para></listitem>
+ </varlistentry>
+ <varlistentry><term><literal>:UTF-16BE</literal></term>
+ <listitem><para>A 16-bit, variable-length encoding in which
+ characters with CHAR-CODEs less than #x10000 can be encoded in
+ a single 16-bit big-endian word and characters with larger
+ codes can be encoded in a pair of 16-bit big-endian words. The
+ endianness of the encoded data is implicit in the encoding;
+ byte-order-mark characters are not interpreted on input or
+ prepended to output.</para></listitem>
+ </varlistentry>
+ <varlistentry><term><literal>:UTF-16LE</literal></term>
+ <listitem><para>A 16-bit, variable-length encoding in which
+ characters with CHAR-CODEs less than #x10000 can be encoded in
+ a single 16-bit little-endian word and characters with larger
+ codes can be encoded in a pair of 16-bit little-endian words.
+ The endianness of the encoded data is implicit in the encoding;
+ byte-order-mark characters are not interpreted on input or
+ prepended to output.</para></listitem>
+ </varlistentry>
+ <varlistentry><term><literal>:UTF-32</literal></term>
+ <listitem><para>A 32-bit, fixed-length encoding in which all
+ Unicode characters can be encoded in a single 32-bit word. The
+ endianness of the encoded data is indicated by the endianness
+ of a byte-order-mark character (#u+feff) prepended to the data;
+ in the absence of such a character on input, input data is
+ assumed to be in big-endian order. Output is written in native
+ byte order with a leading byte-order mark.</para>
+ <para>Alias: <literal>:UTF-4</literal></para></listitem>
+ </varlistentry>
+ <varlistentry><term><literal>:UTF-32BE</literal></term>
+ <listitem><para>A 32-bit, fixed-length encoding in which all
+ Unicode characters encoded in a single 32-bit word. The encoded
+ data is implicitly big-endian; byte-order-mark characters are
+ not interpreted on input or prepended to
+ output.</para>
+ <para>Alias: <literal>:UCS-4BE</literal></para></listitem>
+ </varlistentry>
+ <varlistentry><term><literal>:UTF-8</literal></term>
+ <listitem><para>An 8-bit, variable-length character encoding in
+ which characters with CHAR-CODEs in the range #x00-#x7f can be
+ encoded in a single octet; characters with larger code values
+ can be encoded in 2 to 4 bytes.</para></listitem>
+ </varlistentry>
+ <varlistentry><term><literal>:UTF32LE</literal></term>
+ <listitem><para>A 32-bit, fixed-length encoding in which all
+ Unicode characters can encoded in a single 32-bit word. The
+ encoded data is implicitly little-endian; byte-order-mark
+ characters are not interpreted on input or prepended to
+ output.</para>
+ <para>Alias: <literal>:UCS-4LE</literal></para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+ </sect2>
+
</sect1>
=
<sect1 id=3D"Pathanmes"><title>Pathnames</title>
@@ -1112,10 +1388,10 @@
=
<!-- =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D -->
<sect1 id=3D"Saving-Applications">
- <indexterm zone=3D"Saving-Applications">
- <primary>save-application</primary>
- </indexterm>
<title>Saving Applications</title>
+ <indexterm zone=3D"Saving-Applications">
+ <primary>save-application</primary>
+ </indexterm>
=
<para>&CCL; provides the
function <literal>CCL:SAVE-APPLICATION</literal>, which creates a fi=
le
Modified: trunk/source/doc/src/xsl/directory-fixes.xsl
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D
--- trunk/source/doc/src/xsl/directory-fixes.xsl (original)
+++ trunk/source/doc/src/xsl/directory-fixes.xsl Thu Apr 3 01:14:05 2008
@@ -24,12 +24,7 @@
</xsl:call-template>
</xsl:param>
=
- <xsl:param name=3D"html.stylesheet">
- <xsl:value-of select=3D"$openmcl.base"/>
- <xsl:text>openmcl.css</xsl:text>
- </xsl:param>
-
- <!-- Be aware that href.target.uri cannot be defined in this file,
+ <!-- Be aware that href.target.uri cannot be defined in this file,
because it would be overridden by the definition in
optional-onechunk.xsl. -->
=
Modified: trunk/source/doc/src/xsl/openmcl.xsl
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D
--- trunk/source/doc/src/xsl/openmcl.xsl (original)
+++ trunk/source/doc/src/xsl/openmcl.xsl Thu Apr 3 01:14:05 2008
@@ -16,7 +16,6 @@
<!-- xsl:include href=3D"site-navigator.xsl"/ -->
<xsl:include href=3D"footer.xsl"/>
<xsl:include href=3D"minor-customizations.xsl"/>
- <xsl:include href=3D"directory-fixes.xsl"/>
<xsl:include href=3D"optional-onechunk.xsl"/>
=
<xsl:include href=3D"http://docbook.sourceforge.net/release/xsl/current/=
html/chunk-code.xsl"/>
Modified: trunk/source/doc/src/xsl/refentry.xsl
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D
--- trunk/source/doc/src/xsl/refentry.xsl (original)
+++ trunk/source/doc/src/xsl/refentry.xsl Thu Apr 3 01:14:05 2008
@@ -39,13 +39,19 @@
<p>
<div class=3D"refentrytitle">
<a>
- <xsl:attribute name=3D"href">
- <xsl:call-template name=3D"href.target"/>
+ <xsl:attribute name=3D"id">
+ <xsl:value-of select=3D"@id"/>
</xsl:attribute>
</a>
<strong>[<xsl:value-of select=3D"refnamediv/refclass"/>]</strong><br/>
- <code><xsl:apply-templates select=3D"refsynopsisdiv/synopsis/node()"/></c=
ode>
-
+ <xsl:choose>
+ <xsl:when test=3D"refsynopsisdiv/synopsis">
+ <code><xsl:apply-templates select=3D"refsynopsisdiv/synopsis/node()"/=
></code>
+ </xsl:when>
+ <xsl:otherwise>
+ <code><xsl:value-of select=3D"refnamediv/refname"/></code>
+ </xsl:otherwise>
+ </xsl:choose>
</div>
<div class=3D"refentrytitle">
<xsl:value-of select=3D"refnamediv/refpurpose"/>
More information about the Openmcl-cvs-notifications
mailing list