Changeset 8993


Ignore:
Timestamp:
Apr 3, 2008, 5:14:05 AM (11 years ago)
Author:
jaj
Message:

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 sure that we need one.

Location:
trunk/source/doc/src
Files:
2 added
9 edited

Legend:

Unmodified
Added
Removed
  • trunk/source/doc/src/build.xml

    r8820 r8993  
    3535    here.</para>
    3636
    37     <sect1 id="building-definitions"><title>building definitions</title>
     37    <sect1 id="building-definitions"><title>Building Definitions</title>
    3838      <para>The following terms are used in subsequent sections; it
    3939      may be helpful to refer to these definitions.</para>
  • trunk/source/doc/src/install.xml

    r8981 r8993  
    7777      </sect2>
    7878
    79       <sect2><title>LinuxX8664</title>
     79      <sect2><title>Linux
     80X8664</title>
    8081
    8182        <para>Version 1.1 and later of &CCL; runs on relatively
     
    124125
    125126        <para>&CCL; hasn't been tested under Darwin proper, but
    126         &CCL; doesn't intentionally use any MacOS X features beyond
     127        &CCL; doesn't intentionally use any Mac OS X features beyond
    127128        the Darwin subset and therefore it seems likely that &CCL;
    128129        would run on PPC Darwin versions that correspond to recent OSX
     
    145146    </sect1>
    146147
    147     <sect1><title>Installation</title>
    148       <para>Installing &CCL; consists of</para>
    149       <orderedlist>
    150         <listitem>
    151           <para>Downloading an appropriate distribution of &CCL;;</para>
    152         </listitem>
    153         <listitem>
    154           <para>If necessary, extracting the archive somewhere on your
    155           computer;</para>
    156         </listitem>
    157         <listitem>
    158           <para>Configuring a shell script so &CCL; can locate
    159           necessary library files and other auxiliary files.</para>
    160         </listitem>
    161       </orderedlist>
    162 
    163       <sect2><title>Downloading and untarring &CCL; binary source
    164       releases</title> <para> &CCL; releases and snapshots are
    165       distributed as tarballs (compressed tar archives).</para>
    166 
    167       <para>Tarballs of version 1.0 for supported platforms are
    168       available from the download page of the &CCL; website.</para>
    169 
    170       <para>Tarballs of the latest development snapshots of version
    171       1.1, along with release notes, are available from the testing
    172       directory on Clozure.com.</para>
    173       <para>Both the release and snapshot archives contain a directory
    174       named <literal>ccl</literal>, which in turn contains a number of
    175       files and subdirectories.  The <literal>ccl</literal> directory
    176       can reside anywhere in the filesystem, assuming appropriate
    177       permissions. If you wanted the <literal>ccl</literal> directory
    178       to reside in <literal>``~/openmcl/ccl''</literal> and the
    179       directory <literal>``~/openmcl/''</literal> already existed, you
    180       could do anything equivalent to:</para>
     148
     149    <sect1><title>Obtaining Clozure CL</title>
     150      <para>There two main ways to obtain Clozure CL.  For Mac OS X,
     151      there are disk images that can be used to install Clozure CL in
     152      the usual Macintosh way.  For other OSes (or for Mac OS X),
     153      Subversion is the best way to obtain Clozure CL.  Tarballs are
     154      available for those who prefer them, but Subversion is simpler
     155      and more flexible.</para>
     156
     157      <para> There are three popular ways to use Clozure CL: as a
     158      stand-alone double-clickable application (Mac OS X only), as a
     159      command-line application, or with EMACS and SLIME.  These are
     160      described in the following sections.</para>
     161
     162    <sect2><title>The Mac Way</title>
     163      <para>If you are using Mac OS X then Clozure CL can be installed
     164      and used in the usual Macintosh way.  A disk image is downloaded
     165      and mounted, then Clozure CL is dragged to the Applications
     166      folder.  After that you can double-click on the Clozure CL
     167      application to run it.  The disk images are found at <ulink
     168      url="ftp://clozure.com/pub/testing/"/> </para>
     169
     170      <para>In order to locate Clozure CL source code (and for other
     171      reasons <xref linkend="Predefined-Logical-Hosts"/>) the
     172      <literal>ccl</literal> directory should either be in the same
     173      directory as the Clozure CL application, or the Clozure CL
     174      application should be in the <literal>ccl</literal> directory.
     175      If you use a shell, then the
     176      <varname>CCL_DEFAULT_DIRECTORY</varname> environment variable
     177      can be set to explicitly indicate the location of the
     178      <literal>ccl</literal> directory.</para>
     179    </sect2>
     180 
     181
     182    <sect2><title>Getting Clozure CL with Subversion</title>
     183      <para>It is very easy to download, install, and build Clozure CL
     184      using Subversion.  This is the preferred way to get either the
     185      latest, or a specific version of Clozure CL (unless you're
     186      using the Mac Way).  Subversion is a source code control system
     187      that is in wide usage.  Most modern OSes come with subversion
     188      pre-installed. A complete, buildable and runnable set of Clozure
     189      CL sources and binaries can be retrieved by doing one subversion
     190      checkout.</para>
     191
     192      <para>First, make sure that Subversion is installed on your
     193      system.  Bring up a command line shell and type:
    181194      <programlisting>
    182 shell&gt; cd ~/openmcl
    183 shell&gt; tar xvzf <emphasis>path-to-downloaded-openmcl-archive.tar.gz</emphasis>
     195        <![CDATA[
     196shell> svn]]>
     197      </programlisting>
     198      If Subversion is installed, it will say something like:
     199      <programlisting>
     200        <![CDATA[
     201Type 'svn help' for usage]]>
    184202      </programlisting>
    185       <para><emphasis>Important Note for Macintosh Users:</emphasis>
    186       Double-clicking the archive in the Finder may work, but it also
    187       may have unintended side-effects.  In some versions of the Mac
    188       OS double-clicking an archive will invoke Stuffit, which may try
    189       to replace linefeeds with carriage returns as it extracts
    190       files. Also, tar can be used to merge the archive contents into
    191       an existing <literal>ccl</literal> directory, whereas
    192       double-clicking in the Finder will create a new directory named
    193       <literal>ccl 2</literal> (or <literal>ccl 3</literal>, or...)
    194       Bottom line is that you're better off using tar from the
    195       shell.</para>
    196 
    197       <para>Once the <literal>ccl</literal> directory is installed,
    198       it's necessary to install and configure a shell script
    199       distributed with &CCL; before using it.</para>
    200       </sect2>
     203      If Subversion is not installed, it will say something
     204      like:
     205      <programlisting>
     206        <![CDATA[
     207-bash: svn: command not found]]>
     208      </programlisting>
     209      If subversion is not installed, you'll need to figure out how to
     210     install it on your OS.</para>
     211
     212     <para>Create the directory where Clozure CL will live, <literal>cd</literal> to that directory, then type a Subversion checkout command.  For example:
     213
     214      <programlisting>
     215        <![CDATA[
     216joe:~> mkdir ccl
     217joe:~> cd ccl
     218joe:ccl> svn co svn+ssh://svn.clozure.com/usr/local/publicsvn/openmcl]]>
     219      </programlisting>
     220      Once the checkout is complete you can build Clozure CL by doing:
     221      <programlisting>
     222        <![CDATA[
     223joe:ccl> ./dx86cl64
     224Welcome to Clozure Common Lisp Version 1.2  (DarwinX8664)!
     225? (rebuild-ccl :full t)
     226<lots of compilation output>
     227? (quit)
     228joe:ccl>]]>
     229      </programlisting>
     230      </para>
     231    </sect2>
     232
     233    <sect2><title>Tarballs</title>
     234      <para>Tarballs are available at <ulink
     235      url="ftp://clozure.com/pub/testing/"/>.  These should be
     236      downloaded and extracted onto your local disk.  Then a shell
     237      script should be edited to set
     238      <varname>CCL_DEFAULT_DIRECTORY</varname> and start up the
     239      appropriate Clozure CL kernel. <xref
     240      linkend="The-openmcl-Shell-Script"/> </para>
     241    </sect2>
     242    </sect1>
     243
     244    <sect1><title>Command Line Set Up</title>
     245    <para>Sometimes it is convenient to use Clozure CL from a Unix
     246    shell command line.  This is especially true when using Clozure CL
     247    as a way to run Common Lisp utilities.</para>
    201248
    202249      <sect2 id="The-openmcl-Shell-Script"><title>The openmcl Shell Script</title>
     
    300347        </para>
    301348      </sect2>
    302       <sect2 id="Personal-Customization-with-the-Init-File">
     349    </sect1>
     350      <sect1 id="Personal-Customization-with-the-Init-File">
    303351        <title>Personal Customization with the Init File</title>
    304352        <para>By default &CCL; will try to load the file
     
    321369        <para>To suppress the loading of this init-file, invoke &CCL; with the
    322370<literal>--no-init</literal> option.</para>
    323       </sect2>
    324 
    325       <sect2 id="Some--hopefully--useful-options">
    326         <title>Some (hopefully) useful options</title>
    327         <para> The exact set of command-line arguments accepted by
    328         &CCL; may vary slightly from release to release;
    329         <literal>openmcl --help</literal> will provide a definitive
    330         (if somewhat terse) summary of the options accepted by the
    331         current implementation and then exit. Some of those options
    332         are described below.</para>
     371      </sect1>
     372
     373      <sect1 id="Command-Line-Options">
     374        <title>Command Line Options</title>
     375        <para>When using Clozure CL from the command line, these
     376        options may be used to modify its behavior.  The exact set of
     377        Clozure CL command-line arguments may vary per platform and
     378        slowly changes over time.  The current set of command line
     379        options may be retrieved by using the
     380        <literal>--help</literal> option.</para>
    333381        <itemizedlist>
    334382          <listitem>
    335             <para>-S (or --stack-size). Specify the size of the initial process
    336             stack.</para>
    337           </listitem>
    338 
    339           <listitem>
    340             <para>-b (or --batch). Execute in &#34;batch mode&#34;. End-of-file
    341             from *STANDARD-INPUT* will cause &CCL; to exit, as will attempts to
     383            <para><literal>-h</literal> (or
     384            <literal>--help</literal>).  Provides a definitive (if
     385            somewhat terse) summary of the command line options
     386            accepted by the Clozure CL implementation and then
     387            exits.</para>
     388          </listitem>
     389
     390          <listitem>
     391            <para><literal>-V</literal> (or
     392            <literal>--version</literal>).  Prints the version of
     393            Clozure CL then exits.  This is the same thing that is
     394            returned by
     395            <function>LISP-APPLICATION-VERSION</function>.</para>
     396          </listitem>
     397
     398          <listitem>
     399            <para><literal>-K</literal>
     400            <parameter>character-encoding-name</parameter> (or
     401            <literal>--terminal-encoding</literal>
     402            <parameter>character-encoding-name</parameter>).
     403            Specifies the character encoding to use for
     404            <varname>*TERMINAL-IO*</varname> (see <xref
     405            linkend="Character-Encodings"/>).  Specifically, the
     406            <parameter>character-encoding-name</parameter> string
     407            is uppercased and interned in the KEYWORD package. If an
     408            encoding named by that keyword exists,
     409             <varname>CCL:*TERMINAL-CHARACTER-ENCODING-NAME*</varname> is set to the name
     410            of that encoding.   <varname>CCL:*TERMINAL-CHARACTER-ENCODING-NAME*</varname> defaults to <literal>NIL</literal>, which
     411            is a synonym for <literal>:ISO-8859-1</literal>.</para>
     412            <para>For example:
     413            <programlisting>
     414              <![CDATA[shell> ccl -K utf-8]]>
     415            </programlisting>
     416            will have the effect of making the standard CL streams use
     417            <literal>:UTF-8</literal> as their character
     418            encoding.</para>
     419          </listitem>
     420
     421          <listitem>
     422            <para><literal>-n</literal> (or
     423            <literal>--no-init</literal>). If this option is given,
     424            the init file is not loaded.  This is useful if &CCL; is
     425            being invoked by a shell script which should not be
     426            affected by whatever customizations a user might have in
     427            place.</para>
     428          </listitem>
     429
     430          <listitem>
     431            <para><literal>-e</literal> <parameter>form</parameter>
     432            (or <literal>--eval</literal>). An expression is read (via
     433            <function>READ-FROM-STRING</function>) from the string
     434            <parameter>form</parameter> and evaluated. If
     435            <parameter>form</parameter> contains shell metacharacters,
     436            it may be necessary to escape or quote them to prevent the
     437            shell from interpreting them.</para>
     438          </listitem>
     439
     440          <listitem>
     441            <para><literal>-l</literal> <parameter>path</parameter>
     442            (or <literal>--load</literal>
     443            <parameter>path</parameter>). Loads file specified by
     444            <parameter>path</parameter>.</para>
     445          </listitem>
     446
     447          <listitem>
     448            <para><literal>-T</literal> <parameter>n</parameter> (or
     449            <literal>--set-lisp-heap-gc-threshold</literal>
     450            <parameter>n</parameter>).  Sets the Lisp gc threshold to
     451            <parameter>n</parameter>. (see <xref
     452            linkend="GC-Page-reclamation-policy"/></para>
     453          </listitem>
     454
     455          <listitem>
     456            <para><literal>-Q</literal> (or
     457            <literal>--quiet</literal>). Suppresses printing of
     458            heralds and prompts when the <literal>--batch</literal>
     459            command line option is specified.</para>
     460          </listitem>
     461
     462          <listitem>
     463            <para><literal>-R</literal> <parameter>n</parameter> (or
     464            <literal>--heap-reserve</literal>). Reserves
     465            <parameter>n</parameter> bytes for heap expansion.  The
     466            default is <literal> 549755813888</literal>.  (see <xref
     467            linkend="Heap-space-allocation"/>)</para>
     468          </listitem>
     469
     470          <listitem>
     471            <para><literal>-S</literal> <parameter>n</parameter> (or
     472            <literal>--stack-size</literal> <parameter>n</parameter>). Sets the size of the
     473            initial control stack to <parameter>n</parameter>. (see <xref
     474            linkend="Thread-Stack-Sizes"/>)</para>
     475          </listitem>
     476
     477          <listitem>
     478            <para><literal>-Z</literal> <parameter>n</parameter> (or
     479            <literal>--thread-stack-size</literal>
     480            <parameter>n</parameter>). Sets the size of the first
     481            thread's stack to <parameter>n</parameter>. (see <xref
     482            linkend="Thread-Stack-Sizes"/>)</para>
     483          </listitem>
     484
     485          <listitem>
     486            <para><literal>-b</literal> (or <literal>--batch</literal>). Execute in "batch mode". End-of-file
     487            from <varname>*STANDARD-INPUT*</varname> will cause &CCL; to exit, as will attempts to
    342488            enter a break loop.</para>
    343489          </listitem>
    344490
    345491          <listitem>
    346             <para>-n (or --no-init). If this option is given, the init file
    347             is not loaded.  This is useful if &CCL; is being invoked by a
    348             shell script which should not be affected by whatever
    349             customizations a user might have in place.
    350             </para>
    351           </listitem>
    352 
    353           <listitem>
    354             <para>-e &#60;form&#62; (or --eval &#60;form&#62;). An expression is
    355             read (via READ-FROM-STRING from the string &#60;form&#62; and
    356             evaluated. If &#60;form&#62; contains shell metacharacters, it may be
    357             necessary to escape or quote them to prevent the shell from
    358             interpreting them.</para>
    359           </listitem>
    360 
    361           <listitem>
    362             <para>-l &#62;path&#62; (or --load &#60;path&#62;). Executes (load
    363             &#34;&#60;path&#62;&#34;).</para>
     492            <para><literal>--no-sigtrap</literal> An obscure option for running under GDB.</para>
     493          </listitem>
     494
     495          <listitem>
     496            <para><literal>-I</literal>
     497            <parameter>image-name</parameter> (or
     498            <literal>--image-name</literal>
     499            <parameter>image-name</parameter>). Specifies the image
     500            name for the kernel to load.  Defaults to the kernel name
     501            with ".image" appended.</para>
    364502          </listitem>
    365503        </itemizedlist>
     
    371509        loaded and before the toplevel read-eval-print loop is
    372510        entered.</para>
    373       </sect2>
    374     </sect1>
     511      </sect1>
    375512
    376513    <sect1 id="Using-CCL-with-GNU-Emacs-and-SLIME">
  • trunk/source/doc/src/modifying.xml

    r8981 r8993  
    7373    </sect1>
    7474
    75     <sect1 id="Debugging-facilities-in-the-lisp-kernel">
    76       <title>Debugging facilities in the lisp kernel</title>
     75    <sect1 id="kernel-debugger">
     76      <title>The Kernel Debugger</title>
    7777      <para> In a perfect world, something like this couldn't
    7878      happen:</para>
  • trunk/source/doc/src/streams.xml

    r8981 r8993  
    1515  <sect1 id="CCL-Stream-Extensions">
    1616    <title>Stream Extensions</title>
     17
     18    <sect2><title>Stream External Encoding</title>
     19    <para>Clozure CL streams have an external-encoding attribute that
     20    may be read using
     21    <function>STREAM-EXTERNAL-ENCODING</function> and set using <function>(SETF
     22    STREAM-EXTERNAL-ENCODING)</function>.
     23    </para>
     24    </sect2>
     25
     26    <sect2 id="Additional-Open-Keywords">
     27      <title>Additional keywords for OPEN and MAKE-SOCKET</title>
     28      <para><function>OPEN</function> and
     29      <function>MAKE-SOCKET</function> have each been extended to take
     30      the additional keyword arguments: <literal>:CLASS</literal>,
     31      <literal>:SHARING</literal>, and
     32      <literal>:BASIC</literal>.</para>
     33
     34    <variablelist>
     35      <varlistentry>
     36        <term><literal>:CLASS</literal></term>
     37        <listitem>
     38          <para>A symbol that names the desired class of the stream.
     39          The specified class must inherit from
     40          <literal>FILE-STREAM</literal> for
     41          <function>OPEN</function>.</para>
     42        </listitem>
     43      </varlistentry>
     44      <varlistentry>
     45        <term><literal>:SHARING</literal></term>
     46        <listitem>
     47          <para>Specifies how a stream can be used by multiple
     48          threads.  The possible values are:
     49          <literal>:PRIVATE</literal>, <literal>:LOCK</literal> and
     50          <literal>:EXTERNAL</literal>. <literal>:PRIVATE</literal> is
     51          the default.  <literal>NIL</literal> is also accepted as a
     52          synonym for <literal>:EXTERNAL</literal>.</para>
     53          <variablelist>
     54            <varlistentry>
     55              <term><literal>:PRIVATE</literal></term>
     56              <listitem>
     57                <para>Specifies that the stream can only be accessed
     58                by the thread that created it.  This is the default.
     59                (There was some discussion on openmcl-devel about the
     60                idea of "transferring ownership" of a stream; this has
     61                not yet been implemented.)  Attempts to do I/O on a
     62                stream with :PRIVATE sharing from a thread other than
     63                the stream's owner yield an error.</para>
     64              </listitem>
     65            </varlistentry>
     66            <varlistentry>
     67              <term><literal>:LOCK</literal></term>
     68              <listitem>
     69                <para>Specifies that all access to the stream require
     70                the calling thread to obtain a lock. There are
     71                separate "read" and "write" locks for IO streams.
     72                This makes it possible for instance, for one thread to
     73                read from such a stream while another thread writes to
     74                it.  (see also <xref linkend="f_make-read-write-lock"/>
     75                <xref linkend="m_with-read-lock"/> <xref
     76                linkend="m_with-write-lock"/>)</para>
     77              </listitem>
     78            </varlistentry>
     79            <varlistentry>
     80              <term><literal>:EXTERNAL</literal></term>
     81              <listitem>
     82                <para>Specifies that I/O primitives enforce no access
     83                protocol.  This may be appropriate for some types of
     84                application which can control stream access via
     85                application-level protocols.  Note that since even the
     86                act of reading from a stream changes its internal
     87                state (and simultaneous access from multiple threads
     88                can therefore lead to corruption of that state), some
     89                care must be taken in the design of such protocols.</para>
     90              </listitem>
     91            </varlistentry>
     92          </variablelist>
     93        </listitem>
     94      </varlistentry>
     95      <varlistentry>
     96        <term><literal>:BASIC</literal></term>
     97        <listitem>
     98          <para>A boolean that indicates whether or not the stream is
     99          a Gray stream, i.e. whether or not the stream is an instance
     100          of <literal>FUNDAMENTAL-STREAM</literal> or
     101          <literal>CCL::BASIC-STREAM</literal>(see <xref
     102          linkend="Basic-Versus-Fundamental-Streams"/>).  Defaults to
     103          <literal>T</literal>.</para>
     104        </listitem>
     105      </varlistentry>
     106    </variablelist>
     107
     108    </sect2>
     109
     110    <sect2 id="Basic-Versus-Fundamental-Streams">
     111      <title>Basic Versus Fundamental Streams</title>
     112      <para>Gray streams (see <xref
     113      linkend="Creating-Your-Own-Stream-Classes-with-Gray-Streams"/>)
     114      all inherit from <literal>FUNDAMENTAL-STREAM</literal> whereas
     115      basic streams inherit from <literal>CCL::BASIC-STREAM</literal>.
     116      The tradeoff between FUNDAMENTAL and BASIC streams is entirely
     117      between flexibility and performance, potential or actual.  I/O
     118      primitives can recognize BASIC-STREAMs and exploit knowledge of
     119      implementation details. FUNDAMENTAL stream classes can be
     120      subclassed and extended in a standard way (the Gray streams
     121      protocol).</para>
     122
     123      <para>For existing stream classes (FILE-STREAMs, SOCKETs, and
     124      the internal CCL::FD-STREAM classes used to implement file
     125      streams and sockets), a lot of code can be shared between the
     126      FUNDAMENTAL and BASIC implementations.  The biggest difference
     127      should be that that code can be reached from I/O primitives like
     128      READ-CHAR without going through some steps that're there to
     129      support generality and extensibility, and skipping those steps
     130      when that support isn't needed can improve I/O performance.
     131      </para>
     132
     133      <para>The Gray stream method
     134      <function>STREAM-READ-CHAR</function> should work on appropriate
     135      <literal>BASIC-STREAM</literal>s.  (There may still be cases
     136      where such methods are undefined; such cases should be
     137      considered bugs.)  It is not guaranteed that Gray stream methods
     138      would ever be called by I/O primitives to read a character from
     139      a <literal>BASIC-STREAM</literal>, though there are still cases
     140      where this happens.</para>
     141
     142      <para>A simple loop reading 2M characters from a text file runs
     143      about 10X faster when the file is opened the new defaults
     144      <literal>(:SHARING :PRIVATE :BASIC T)</literal> than it had
     145      before these changes were made.  That sounds good, until one
     146      realizes that the "equivalent" C loop can be about 10X faster
     147      still ...</para>
     148    </sect2>
     149
     150
    17151    <sect2 id="Stream-Timeouts-And-Deadlines">
    18152      <title>Stream Timeouts and Deadlines</title>
  • trunk/source/doc/src/threads.xml

    r8981 r8993  
    168168  <sect1 id="Implementation-Decisions-and-Open-Questions">
    169169    <title>Implementation Decisions and Open Questions</title>
    170     <sect2>
     170    <sect2 id="Thread-Stack-Sizes">
    171171      <title>Thread Stack Sizes</title>
    172172      <para>When you use MAKE-PROCESS to create a thread, you can
  • trunk/source/doc/src/using.xml

    r8981 r8993  
    477477    </para>
    478478
    479     <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>
     479    <para>By default, this is nil. If non-nil it should be a integer,
     480    and the default entry and exit messages will print a | instead of
     481    space every this many levels of indentation.</para>
    480482
    481483
     
    484486  <sect1 id="Unicode"><title>Unicode</title>
    485487
    486     <para>All characters and strings in &CCL; fully support Unicode
    487       by using UTF-32. There is only one <literal>CHARACTER</literal> type
    488       and one <literal>STRING</literal> in &CCL;.  There has been a
    489       lot of discussion about this decision which can be found by
    490       searching the openmcl-devel archives at <ulink
    491                                                  url="http://clozure.com/pipermail/openmcl-devel/"/>.  Suffice it to
    492       say that we decided that the simplicity and speed advantages of
    493       UTF-32 outweigh the space disadvantage.</para>
    494 
    495     <sect2><title>Characters</title>
    496       <para>There is one <literal>CHARACTER</literal> type in &CCL;.
    497         All <literal>CHARACTER</literal>s are <literal>BASE-CHAR</literal>s.
    498         <varname>CHAR-CODE-LIMIT</varname> is now
    499         <literal>#x110000</literal>, which means that all Unicode characters
    500         can be directly represented.  As of Unicode 5.0, only about 100,000
    501         of 1,114,112 possible <literal>CHAR-CODE</literal>s are actually
    502         defined. The function <function>CODE-CHAR</function> knows that
    503         certain ranges of code values (notably
    504         <literal>#xd800</literal>-<literal>#xddff</literal>) will never be
    505         valid character codes and will return <literal>NIL</literal> for
    506         arguments in that range, but may return a non-<literal>NIL</literal>
    507         value (an undefined/non-standard <literal>CHARACTER</literal>
    508         object) for other unassigned code values.</para>
    509       <para>&CCL; supports character names of the form
    510         <literal>u+xxxx</literal> - where <literal>x</literal> is a sequence
    511         of one or more hex digits.  The value of the hex digits denotes the
    512         code of the character.  The <literal>+</literal> character is
    513         optional, so <literal>#\u+0020</literal>,
    514         <literal>#\U0020</literal>, and <literal>#\U+20</literal> all refer
    515         to the <literal>#\Space</literal> character.</para>
    516       <para>Characters with codes in the range
    517         <literal>#xa0</literal>-<literal>#x7ff</literal> also have symbolic
    518         names These are the names from the Unicode standard with spaces
    519         replaced by underscores.  So
    520         <literal>#\Greek_Capital_Letter_Epsilon</literal> can be used to
    521         refer to the character whose <function>CHAR-CODE</function> is
    522         <literal>#x395</literal>.</para>
    523     </sect2>
    524 
    525     <sect2 id="External-Formats"><title>External Formats</title>
    526       <para><function>OPEN</function>, <function>LOAD</function>, and
    527         <function>COMPILE-FILE</function> all take an
    528         <literal>:EXTERNAL-FORMAT</literal> keyword argument.  The value of
    529         <literal>:EXTERNAL-FORMAT</literal> can be
    530         <literal>:DEFAULT</literal> (the default value), a line termination
    531         keyword <xref linkend="Line-Termination-Keywords"/><xref
    532                                                               linkend="k_external-format"/>, a character encoding keyword <xref
    533                                                                                                                              linkend="Character-Encodings"/>, a plist with keys:
    534         <literal>:CHARACTER-ENCODING</literal> and
    535         <literal>:LINE-TERMINATION</literal>, or an external-format object
    536         created using <function>CCL::MAKE-EXTERNAL-FORMAT</function>.  If
    537         <literal>:DEFAULT</literal> is specified, then the value of
    538         <varname>CCL:*DEFAULT-EXTERNAL-FORMAT*</varname> is used.  If no
    539         line-termination is specified, then the value of
    540         <varname>CCL:*DEFAULT-LINE-TERMINATION*</varname> is used.  If no
    541         character encoding is specified, then
    542         <varname>CCL:*DEFAULT-FILE-CHARACTER-ENCODING*</varname> is used for
    543         file streams and
    544         <varname>CCL:*DEFAULT-SOCKET-CHARACTER-ENCODING*</varname> is used
    545         for socket streams.  The default, default character encoding is
    546         <literal>NIL</literal> which is a synonym for <literal>:ISO-8859-1</literal>
    547       </para>
    548     </sect2>
    549 
    550     <sect2 id="Line-Termination-Keywords"><title>Line Termination Keywords</title>
    551       <para>Line termination keywords indicate which characters are used
    552         to indicate the end of a line.  On input, the external line
    553         termination characters are replaced by <literal>#\Newline</literal>
    554         and on output, <literal>#\Newline</literal>s are converted to the
    555         external line termination characters.</para>
    556       <table id="Line-Termination-Table" frame='all'><title>Line Termination Keywords</title>
    557         <tgroup cols='2' align='left' colsep='1' rowsep='1'>
    558           <thead>
    559             <row>
    560                   <entry>keyword</entry>
    561                   <entry>character(s)</entry>
    562             </row>
    563           </thead>
    564           <tbody>
    565             <row>
    566                   <entry><literal>:UNIX</literal></entry>
    567                   <entry><literal>#\Linefeed</literal></entry>
    568             </row>
    569             <row>
    570                   <entry><literal>:MACOS</literal></entry>
    571                   <entry><literal>#\Return</literal></entry>
    572             </row>
    573             <row>
    574                   <entry><literal>:CR</literal></entry>
    575                   <entry><literal>#\Return</literal></entry>
    576             </row>
    577             <row>
    578                   <entry><literal>:CRLF</literal></entry>
    579                   <entry><literal>#\Return #\Linefeed</literal></entry>
    580             </row>
    581             <row>
    582                   <entry><literal>:CP/M</literal></entry>
    583                   <entry><literal>#\Return #\Linefeed</literal></entry>
    584             </row>
    585             <row>
    586                   <entry><literal>:MSDOS</literal></entry>
    587                   <entry><literal>#\Return #\Linefeed</literal></entry>
    588             </row>
    589             <row>
    590                   <entry><literal>:DOS</literal></entry>
    591                   <entry><literal>#\Return #\Linefeed</literal></entry>
    592             </row>
    593             <row>
    594                   <entry><literal>:WINDOWS</literal></entry>
    595                   <entry><literal>#\Return #\Linefeed</literal></entry>
    596             </row>
    597             <row>
    598                   <entry><literal>:INFERRED</literal></entry>
    599                   <entry>see below</entry>
    600             </row>
    601             <row>
    602                   <entry><literal>:UNICODE</literal></entry>
    603                   <entry><literal>#\Line_Separator</literal></entry>
    604             </row>
    605           </tbody>
    606         </tgroup>
    607       </table>
    608       <para><literal>:INFERRED</literal> means try to guess a stream's
    609         line-termination conventions.  It is only useful for
    610         <literal>FILE-STREAM</literal>s that are 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>
    611     </sect2>
    612    
    613 
    614     <sect2 id="Character-Encodings"><title>Character Encodings</title>
    615       <para>Internally, all characters and strings in &CCL; are in
    616         UTF-32.  Externally, files or socket streams may encode characters
    617         in a wide variety of ways.  The International Organization for
    618         Standardization, widely known as ISO defines a number of these
    619         character encodings.  &CCL; implements a number of these
    620         encodings as detailed below.  These encodings are part of the
    621         specification of external formats (see <xref
    622                                                   linkend="External-Formats"/>.  When reading from a stream,
    623         characters are converted from the specified external character
    624         encoding to UTF-32.  When writing to a stream, characters are
    625         converted from UTF-32 to the specified character encoding.  Here is
    626         a list of character encoding keywords used to specify a standard
    627         character encoding.</para>
    628       <variablelist>
    629         <varlistentry><term><literal>:ISO-8859-1</literal></term>
    630           <listitem><para>An 8-bit, fixed-width character encoding in
    631               which all character codes map to their Unicode
    632               equivalents. Intended to support most characters used in most
    633               Western European languages.</para></listitem>
    634         </varlistentry>
    635         <varlistentry><term><literal>:ISO-8859-2</literal></term>
    636           <listitem><para>An 8-bit, fixed-width character encoding in
    637               which codes #x00-#x9f map to their Unicode equivalents and
    638               other codes map to other Unicode character values.  Intended to
    639               provide most characters found in most languages used in
    640               Central/Eastern Europe.</para></listitem>
    641         </varlistentry>
    642         <varlistentry><term><literal>:ISO-8859-3</literal></term>
    643           <listitem><para>An 8-bit, fixed-width character encoding in
    644               which codes #x00-#x9f map to their Unicode equivalents and
    645               other codes map to other Unicode character values.  Intended to
    646               provide most characters found in most languages used in
    647               Southern Europe.</para></listitem>
    648         </varlistentry>
    649         <varlistentry><term><literal>:ISO-8859-4</literal></term>
    650           <listitem><para>An 8-bit, fixed-width character encoding in
    651               which codes #x00-#x9f map to their Unicode equivalents and
    652               other codes map to other Unicode character values.  Intended to
    653               provide most characters found in most languages used in
    654               Northern Europe.</para></listitem>
    655         </varlistentry>
    656         <varlistentry><term><literal>:ISO-8859-5</literal></term>
    657           <listitem><para>An 8-bit, fixed-width character encoding in
    658               which codes #x00-#x9f map to their Unicode equivalents and
    659               other codes map to other Unicode character values.  Intended to
    660               provide most characters found in the Cyrillic
    661               alphabet.</para></listitem>
    662         </varlistentry>
    663         <varlistentry><term><literal>:ISO-8859-6</literal></term>
    664           <listitem><para>An 8-bit, fixed-width character encoding in
    665               which codes #x00-#x9f map to their Unicode equivalents and
    666               other codes map to other Unicode character values.  Intended to
    667               provide most characters found in the Arabic
    668               alphabet.</para></listitem>
    669         </varlistentry>
    670         <varlistentry><term><literal>:ISO-8859-7</literal></term>
    671           <listitem><para>An 8-bit, fixed-width character encoding in
    672               which codes #x00-#x9f map to their Unicode equivalents and
    673               other codes map to other Unicode character values.  Intended to
    674               provide most characters found in the Greek
    675               alphabet.</para></listitem>
    676         </varlistentry>
    677         <varlistentry><term><literal>:ISO-8859-8</literal></term>
    678           <listitem><para>An 8-bit, fixed-width character encoding in
    679               which codes #x00-#x9f map to their Unicode equivalents and
    680               other codes map to other Unicode character values.  Intended to
    681               provide most characters found in the Hebrew
    682               alphabet.</para></listitem>
    683         </varlistentry>
    684         <varlistentry><term><literal>:ISO-8859-9</literal></term>
    685           <listitem><para>An 8-bit, fixed-width character encoding in
    686               which codes #x00-#xcf map to their Unicode equivalents and
    687               other codes map to other Unicode character values.  Intended to
    688               provide most characters found in the Turkish
    689               alphabet.</para></listitem>
    690         </varlistentry>
    691         <varlistentry><term><literal>:ISO-8859-10</literal></term>
    692           <listitem><para>An 8-bit, fixed-width character encoding in
    693               which codes #x00-#x9f map to their Unicode equivalents and
    694               other codes map to other Unicode character values.  Intended to
    695               provide most characters found in Nordic
    696               alphabets.</para></listitem>
    697         </varlistentry>
    698         <varlistentry><term><literal>:ISO-8859-11</literal></term>
    699           <listitem><para>An 8-bit, fixed-width character encoding in
    700               which codes #x00-#x9f map to their Unicode equivalents and
    701               other codes map to other Unicode character values.  Intended to
    702               provide most characters found the Thai
    703               alphabet.</para></listitem>
    704         </varlistentry>
    705         <varlistentry><term><literal>:ISO-8859-13</literal></term>
    706           <listitem><para>An 8-bit, fixed-width character encoding in
    707               which codes #x00-#x9f map to their Unicode equivalents and
    708               other codes map to other Unicode character values.  Intended to
    709               provide most characters found in Baltic
    710               alphabets.</para></listitem>
    711         </varlistentry>
    712         <varlistentry><term><literal>:ISO-8859-14</literal></term>
    713           <listitem><para>An 8-bit, fixed-width character encoding in
    714               which codes #x00-#x9f map to their Unicode equivalents and
    715               other codes map to other Unicode character values.  Intended to
    716               provide most characters found in Celtic
    717               languages.</para></listitem>
    718         </varlistentry>
    719         <varlistentry><term><literal>:ISO-8859-15</literal></term>
    720           <listitem><para>An 8-bit, fixed-width character encoding in
    721               which codes #x00-#x9f map to their Unicode equivalents and
    722               other codes map to other Unicode character values.  Intended to
    723               provide most characters found in Western European languages
    724               (including the Euro sign and some other characters missing from
    725               ISO-8859-1.</para></listitem>
    726         </varlistentry>
    727         <varlistentry><term><literal>:ISO-8859-16</literal></term>
    728           <listitem><para>An 8-bit, fixed-width character encoding in
    729               which codes #x00-#x9f map to their Unicode equivalents and
    730               other codes map to other Unicode character values.  Intended to
    731               provide most characters found in Southeast European
    732               languages.</para></listitem>
    733         </varlistentry>
    734         <varlistentry><term><literal>:MACINTOSH</literal></term>
    735           <listitem><para>An 8-bit, fixed-width character encoding in
    736               which codes #x00-#x7f map to their Unicode equivalents and
    737               other codes map to other Unicode character values.
    738               Traditionally used on Classic MacOS to encode characters used
    739               in western languages.</para></listitem>
    740         </varlistentry>
    741         <varlistentry><term><literal>:UCS-2</literal></term>
    742           <listitem><para>A 16-bit, fixed-length encoding in which
    743               characters with CHAR-CODEs less than #x10000 can be encoded in
    744               a single 16-bit word.  The endianness of the encoded data is
    745               indicated by the endianness of a byte-order-mark character
    746               (#u+feff) prepended to the data; in the absence of such a
    747               character on input, the data is assumed to be in big-endian
    748               order.</para></listitem>
    749         </varlistentry>
    750         <varlistentry><term><literal>:UCS-2BE</literal></term>
    751           <listitem><para>A 16-bit, fixed-length encoding in which
    752               characters with CHAR-CODEs less than #x10000 can be encoded in
    753               a single 16-bit big-endian word. The encoded data is implicitly
    754               big-endian; byte-order-mark characters are not interpreted on
    755               input or prepended to output.</para></listitem>
    756         </varlistentry>
    757         <varlistentry><term><literal>:UCS-2LE</literal></term>
    758           <listitem><para>A 16-bit, fixed-length encoding in which
    759               characters with CHAR-CODEs less than #x10000 can be encoded in
    760               a single 16-bit little-endian word. The encoded data is
    761               implicitly little-endian; byte-order-mark characters are not
    762               interpreted on input or prepended to output.</para></listitem>
    763         </varlistentry>
    764         <varlistentry><term><literal>:US-ASCII</literal></term>
    765           <listitem><para>An 7-bit, fixed-width character encoding in
    766               which all character codes map to their Unicode
    767               equivalents. </para></listitem>
    768         </varlistentry>
    769         <varlistentry><term><literal>:UTF-16</literal></term>
    770           <listitem><para>A 16-bit, variable-length encoding in which
    771               characters with CHAR-CODEs less than #x10000 can be encoded in
    772               a single 16-bit word and characters with larger codes can be
    773               encoded in a pair of 16-bit words.  The endianness of the
    774               encoded data is indicated by the endianness of a
    775               byte-order-mark character (#u+feff) prepended to the data; in
    776               the absence of such a character on input, the data is assumed
    777               to be in big-endian order. Output is written in native
    778               byte-order with a leading byte-order mark.</para></listitem>
    779         </varlistentry>
    780         <varlistentry><term><literal>:UTF-16BE</literal></term>
    781           <listitem><para>A 16-bit, variable-length encoding in which
    782               characters with CHAR-CODEs less than #x10000 can be encoded in
    783               a single 16-bit big-endian word and characters with larger
    784               codes can be encoded in a pair of 16-bit big-endian words.  The
    785               endianness of the encoded data is implicit in the encoding;
    786               byte-order-mark characters are not interpreted on input or
    787               prepended to output.</para></listitem>
    788         </varlistentry>
    789         <varlistentry><term><literal>:UTF-16LE</literal></term>
    790           <listitem><para>A 16-bit, variable-length encoding in which
    791               characters with CHAR-CODEs less than #x10000 can be encoded in
    792               a single 16-bit little-endian word and characters with larger
    793               codes can be encoded in a pair of 16-bit little-endian words.
    794               The endianness of the encoded data is implicit in the encoding;
    795               byte-order-mark characters are not interpreted on input or
    796               prepended to output.</para></listitem>
    797         </varlistentry>
    798         <varlistentry><term><literal>:UTF-32</literal></term>
    799           <listitem><para>A 32-bit, fixed-length encoding in which all
    800               Unicode characters can be encoded in a single 32-bit word.  The
    801               endianness of the encoded data is indicated by the endianness
    802               of a byte-order-mark character (#u+feff) prepended to the data;
    803               in the absence of such a character on input, input data is
    804               assumed to be in big-endian order.  Output is written in native
    805               byte order with a leading byte-order mark.</para></listitem>
    806         </varlistentry>
    807         <varlistentry><term><literal>:UTF-32BE</literal></term>
    808           <listitem><para>A 32-bit, fixed-length encoding in which all
    809               Unicode characters encoded in a single 32-bit word. The encoded
    810               data is implicitly big-endian; byte-order-mark characters are
    811               not interpreted on input or prepended to
    812               output.</para></listitem>
    813         </varlistentry>
    814         <varlistentry><term><literal>:UTF-8</literal></term>
    815           <listitem><para>An 8-bit, variable-length character encoding in
    816               which characters with CHAR-CODEs in the range #x00-#x7f can be
    817               encoded in a single octet; characters with larger code values
    818               can be encoded in 2 to 4 bytes.</para></listitem>
    819         </varlistentry>
    820         <varlistentry><term><literal>:UTF32LE</literal></term>
    821           <listitem><para>A 32-bit, fixed-length encoding in which all
    822               Unicode characters can encoded in a single 32-bit word. The
    823               encoded data is implicitly little-endian; byte-order-mark
    824               characters are not interpreted on input or prepended to
    825               output.</para></listitem>
    826         </varlistentry>
    827       </variablelist>
    828     </sect2>
     488    <para>All characters and strings in &CCL; fully support Unicode by
     489    using UTF-32. There is only one <literal>CHARACTER</literal> type
     490    and one <literal>STRING</literal> type in &CCL;.  There has been a
     491    lot of discussion about this decision which can be found by
     492    searching the openmcl-devel archives at <ulink
     493    url="http://clozure.com/pipermail/openmcl-devel/"/>.  Suffice it
     494    to say that we decided that the simplicity and speed advantages of
     495    only supporting UTF-32 outweigh the space disadvantage.</para>
     496
     497
     498
     499  <sect2><title>Characters</title>
     500    <para>There is one <literal>CHARACTER</literal> type in &CCL;.
     501    All <literal>CHARACTER</literal>s are
     502    <literal>BASE-CHAR</literal>s.  <varname>CHAR-CODE-LIMIT</varname>
     503    is now <literal>#x110000</literal>, which means that all Unicode
     504    characters can be directly represented.  As of Unicode 5.0, only
     505    about 100,000 of 1,114,112 possible <literal>CHAR-CODE</literal>s
     506    are actually defined. The function <function>CODE-CHAR</function>
     507    knows that certain ranges of code values (notably
     508    <literal>#xd800</literal>-<literal>#xddff</literal>) will never be
     509    valid character codes and will return <literal>NIL</literal> for
     510    arguments in that range, but may return a
     511    non-<literal>NIL</literal> value (an undefined/non-standard
     512    <literal>CHARACTER</literal> object) for other unassigned code
     513    values.</para>
     514
     515    <para>&CCL; supports character names of the form
     516    <literal>u+xxxx</literal> - where <literal>x</literal> is a
     517    sequence of one or more hex digits.  The value of the hex digits
     518    denotes the code of the character.  The <literal>+</literal>
     519    character is optional, so <literal>#\u+0020</literal>,
     520    <literal>#\U0020</literal>, and <literal>#\U+20</literal> all
     521    refer to the <literal>#\Space</literal> character.</para>
     522
     523    <para>Characters with codes in the range
     524    <literal>#xa0</literal>-<literal>#x7ff</literal> also have
     525    symbolic names These are the names from the Unicode standard with
     526    spaces replaced by underscores.  So
     527    <literal>#\Greek_Capital_Letter_Epsilon</literal> can be used to
     528    refer to the character whose <function>CHAR-CODE</function> is
     529    <literal>#x395</literal>.  To see the complete list of supported
     530    character names, look just below the definition for
     531    <function>register-character-name</function> in
     532    <literal>ccl:level-1;l1-reader.lisp</literal> see the complete
     533    list of char</para>
     534  </sect2>
     535
     536
     537  <sect2 id="External-Formats"><title>External Formats</title>
     538    <para><function>OPEN</function>, <function>LOAD</function>, and
     539    <function>COMPILE-FILE</function> all take an
     540    <literal>:EXTERNAL-FORMAT</literal> keyword argument.  The value
     541    of <literal>:EXTERNAL-FORMAT</literal> can be
     542    <literal>:DEFAULT</literal> (the default value), a line
     543    termination keyword (see <xref
     544    linkend="Line-Termination-Keywords"/>), a character encoding
     545    keyword (see <xref linkend="Character-Encodings"/>), an
     546    external-format object created using
     547    <function>CCL::MAKE-EXTERNAL-FORMAT</function>(see <xref
     548    linkend="f_make-external-format"/>), or a plist with keys:
     549    <literal>:DOMAIN</literal>, <literal>:CHARACTER-ENCODING</literal>
     550    and <literal>:LINE-TERMINATION</literal>.  If
     551    <parameter>argument</parameter> is a plist, the result of
     552    <literal>(APPLY #'MAKE-EXTERNAL-FORMAT
     553    <parameter>argument</parameter>)</literal> will be used.</para>
     554
     555    <para>If <literal>:DEFAULT</literal> is specified, then the value
     556    of <varname>CCL:*DEFAULT-EXTERNAL-FORMAT*</varname> is used.  If
     557    no line-termination is specified, then the value of
     558    <varname>CCL:*DEFAULT-LINE-TERMINATION*</varname> is used, which
     559    defaults to <literal>:UNIX</literal>.  If no character encoding is
     560    specified, then
     561    <varname>CCL:*DEFAULT-FILE-CHARACTER-ENCODING*</varname> is used
     562    for file streams and
     563    <varname>CCL:*DEFAULT-SOCKET-CHARACTER-ENCODING*</varname> is used
     564    for socket streams.  The default, default character encoding is
     565    <literal>NIL</literal> which is a synonym for
     566    <literal>:ISO-8859-1</literal>.</para>
     567
     568    <para>Note that the set of keywords used to denote
     569    CHARACTER-ENCODINGs and the set of keywords used to denote
     570    line-termination conventions is disjoint: a keyword denotes at
     571    most a character encoding or a line termination convention, but
     572    never both.</para>
     573
     574    <para>EXTERNAL-FORMATs are objects (structures) with three
     575    read-only fields that can be accessed via the functions:
     576    <function>EXTERNAL-FORMAT-DOMAIN</function>,
     577    <function>EXTERNAL-FORMAT-LINE-TERMINATION</function> and
     578    <function>EXTERNAL-FORMAT-CHARACTER-ENCODING</function>.</para>
     579
     580 
     581    <refentry id="f_make-external-format">
     582      <indexterm zone="f_make-external-format">
     583        <primary>make-external-format</primary>
     584      </indexterm>
     585     
     586      <refnamediv>
     587        <refname>MAKE-EXTERNAL-FORMAT</refname>
     588        <refpurpose>Either creates a new external format object, or
     589        return an existing one with the same specified slot
     590        values.</refpurpose>
     591        <refclass>Function</refclass>
     592      </refnamediv>
     593
     594      <refsynopsisdiv>
     595        <synopsis>
     596          <function>make-external-format</function>
     597          &key; domain character-encoding line-termination
     598          => external-format
     599        </synopsis>
     600      </refsynopsisdiv>
     601
     602      <refsect1>
     603        <title>Arguments and Values</title>
     604       
     605        <variablelist>
     606          <varlistentry>
     607            <term>domain</term>
     608            <listitem>
     609              <para>This is used to indicate where the external
     610              format is to be used.  Its value can be almost
     611              anything.  It defaults to <literal>NIL</literal>.
     612              There are two domains that have a pre-defined meaning in
     613              Clozure CL: <literal>:FILE</literal> indicates
     614              encoding for a file in the file system and
     615              <literal>:SOCKET</literal> indicates i/o to/from a
     616              socket.  The value of <parameter>domain</parameter>
     617              affects the default values for
     618              <parameter>character-encoding</parameter> and
     619              <parameter>line-termination</parameter>.</para>
     620            </listitem>
     621          </varlistentry>
     622          <varlistentry>
     623            <term>character-encoding</term>
     624            <listitem>
     625              <para>A keyword that specifies the character encoding
     626              for the external format. <xref
     627              linkend="Character-Encodings"/>.  Defaults to
     628              <literal>:DEFAULT</literal> which means if
     629              <parameter>domain</parameter> is
     630              <literal>:FILE</literal> use the value of the variable
     631              <varname>CCL:*DEFAULT-FILE-CHARACTER-ENCODING*</varname>
     632              and if <parameter>domain</parameter> is
     633              <literal>:SOCKET</literal>, use the value of the
     634              variable
     635              <varname>CCL:*DEFAULT-SOCKET-CHARACTER-ENCODING*</varname>.
     636              The initial value of both of these variables is
     637              <literal>NIL</literal>, which means the
     638              <literal>:ISO-8859-1</literal> encoding.</para>
     639            </listitem>
     640          </varlistentry>
     641          <varlistentry>
     642            <term>line-termination</term>
     643            <listitem>
     644              <para>A keyword that indicates a line termination
     645              keyword <xref linkend="Line-Termination-Keywords"/>.
     646              Defaults to <literal>:DEFAULT</literal> which means
     647              use the value of the variable
     648              <varname>CCL:*DEFAULT-LINE-TERMINATION*</varname>.</para>
     649            </listitem>
     650          </varlistentry>
     651          <varlistentry>
     652            <term>[result]</term>
     653            <listitem>
     654              <para>[description]</para>
     655            </listitem>
     656          </varlistentry>
     657        </variablelist>
     658      </refsect1>
     659     
     660      <refsect1>
     661        <title>Description</title>
     662       
     663        <para>Despite the function's name, it doesn't necessarily
     664        create a new, unique EXTERNAL-FORMAT object: two calls to
     665        MAKE-EXTERNAL-FORMAT with the same arguments made in the
     666        same dynamic environment will return the same (eq) object.
     667        </para>
     668      </refsect1>
     669    </refentry>
     670
     671  </sect2>
     672
     673  <sect2 id="Line-Termination-Keywords"><title>Line Termination Keywords</title>
     674  <para>Line termination keywords indicate which characters are used
     675  to indicate the end of a line.  On input, the external line
     676  termination characters are replaced by <literal>#\Newline</literal>
     677  and on output, <literal>#\Newline</literal>s are converted to the
     678  external line termination characters.</para>
     679  <table id="Line-Termination-Table" frame='all'><title>Line Termination Keywords</title>
     680  <tgroup cols='2' align='left' colsep='1' rowsep='1'>
     681    <thead>
     682      <row>
     683        <entry>keyword</entry>
     684        <entry>character(s)</entry>
     685      </row>
     686    </thead>
     687    <tbody>
     688      <row>
     689        <entry><literal>:UNIX</literal></entry>
     690        <entry><literal>#\Linefeed</literal></entry>
     691      </row>
     692      <row>
     693        <entry><literal>:MACOS</literal></entry>
     694        <entry><literal>#\Return</literal></entry>
     695      </row>
     696      <row>
     697        <entry><literal>:CR</literal></entry>
     698        <entry><literal>#\Return</literal></entry>
     699      </row>
     700      <row>
     701        <entry><literal>:CRLF</literal></entry>
     702        <entry><literal>#\Return #\Linefeed</literal></entry>
     703      </row>
     704      <row>
     705        <entry><literal>:CP/M</literal></entry>
     706        <entry><literal>#\Return #\Linefeed</literal></entry>
     707      </row>
     708      <row>
     709        <entry><literal>:MSDOS</literal></entry>
     710        <entry><literal>#\Return #\Linefeed</literal></entry>
     711      </row>
     712      <row>
     713        <entry><literal>:DOS</literal></entry>
     714        <entry><literal>#\Return #\Linefeed</literal></entry>
     715      </row>
     716      <row>
     717        <entry><literal>:WINDOWS</literal></entry>
     718        <entry><literal>#\Return #\Linefeed</literal></entry>
     719      </row>
     720      <row>
     721        <entry><literal>:INFERRED</literal></entry>
     722        <entry>see below</entry>
     723      </row>
     724      <row>
     725        <entry><literal>:UNICODE</literal></entry>
     726        <entry><literal>#\Line_Separator</literal></entry>
     727      </row>
     728    </tbody>
     729  </tgroup>
     730  </table>
     731  <para><literal>:INFERRED</literal> means that a stream's
     732  line-termination convention is determined by looking at the contents
     733  of a file.  It is only useful for <literal>FILE-STREAM</literal>s
     734  that're open for <literal>:INPUT</literal> or
     735  <literal>:IO</literal>.  The first buffer full of data is examined,
     736  and if a <literal>#\Return</literal> character occurs before any
     737  <literal>#\Linefeed</literal> character, then the line termination
     738  type is set to <literal>:MACOS</literal>, otherwise it is set to
     739  <literal>:UNIX</literal>.</para>
     740  </sect2>
     741 
     742
     743
     744  <sect2 id="Character-Encodings"><title>Character Encodings</title>
     745    <para>Internally, all characters and strings in &CCL; are in
     746    UTF-32.  Externally, files or socket streams may encode characters
     747    in a wide variety of ways.  The International Organization for
     748    Standardization, widely known as ISO, defines many of these
     749    character encodings.  &CCL; implements some of these encodings as
     750    detailed below.  These encodings are part of the specification of
     751    external formats <xref linkend="External-Formats"/>.  When reading
     752    from a stream, characters are converted from the specified
     753    external character encoding to UTF-32.  When writing to a stream,
     754    characters are converted from UTF-32 to the specified character
     755    encoding.</para>
     756
     757    <para>Internally, CHARACTER-ENCODINGs are objects (structures)
     758    that are named by character encoding keywords (:ISO-8859-1,
     759    :UTF-8, etc.).  The structures contain attributes of the encoding
     760    and functions used to encode/decode external data, but unless
     761    you're trying to define or debug an encoding there's little reason
     762    to know much about the CHARACTER-ENCODING objects and it's usually
     763    preferable to refer to a character encoding by its name.
     764    </para>
     765
     766    <para>
     767    </para>
     768
     769    <sect3><title>Encoding Problems</title>
     770      <para>On output to streams with character encodings that can
     771      encode the full range of Unicode - and on input from any stream
     772      - "unencodable characters" are represented using the Unicode
     773      #\Replacement_Character (= #\U+fffd); the presence of such a
     774      character usually indicates that something got lost in
     775      translation.  Either data wasn't encoded properly or there was a
     776      bug in the decoding process.</para>
     777    </sect3>
     778
     779    <sect3><title>Byte Order Marks</title>
     780      <para>The endianness of a character encoding is sometimes
     781      explicit, and sometimes not.  For example,
     782      <literal>:UTF-16BE</literal> indicates big-endian, but
     783      <literal>:UTF-16</literal> does not specify endianness.  A byte
     784      order mark is a special character that may appear at the
     785      beginning of a stream of encoded characters to specify the
     786      endianness of a multi-byte character encoding.  (It may also be
     787      used with UTF-8 character encodings, where it is simply used to
     788      indicate that the encoding is UTF-8.)</para>
     789
     790      <para>Clozure CL will write a byte order mark as the first
     791      character of a file or socket stream when the endianness of the
     792      character encoding is not explicit.  Clozure CL also expects a
     793      byte order mark on input from streams where the endianness is
     794      not explicit. If a byte order mark is missing from input data,
     795      that data is assumed to be in big-endian order.</para>
     796
     797      <para>A byte order mark from a UTF-8 encoded input stream is not
     798      treated specially and and will just appear as normal character
     799      from the input stream.  It is probably a good idea to skip over
     800      this character.</para>
     801    </sect3>
     802
     803  <sect3><title><function>DESCRIBE-CHARACTER-ENCODINGS</function></title>
     804    <para>The set of character encodings supported by Clozure CL can be
     805    retrieved by calling
     806    <function>CCL:DESCRIBE-CHARACTER-ENCODINGS</function>.</para>
     807
     808
     809      <refentry id="f_describe-character-encodings">
     810        <indexterm zone="f_describe-character-encodings">
     811          <primary>[fn-name]</primary>
     812        </indexterm>
     813
     814        <refnamediv>
     815          <refname>DESCRIBE-CHARACTER-ENCODINGS</refname>
     816          <refpurpose>Writes descriptions of defined character
     817          encodings to <varname>*terminal-io*</varname>.</refpurpose>
     818          <refclass>Function</refclass>
     819        </refnamediv>
     820
     821        <refsynopsisdiv>
     822          <synopsis>
     823            <function>describe-character-encodings</function>
     824          </synopsis>
     825        </refsynopsisdiv>
     826
     827        <refsect1>
     828          <title>Description</title>
     829
     830          <para>Writes descriptions of all defined character encodings
     831          to <varname>*terminal-io*</varname>.  These descriptions
     832          include the names of the encoding's aliases and a doc string
     833          which briefly describes each encoding's properties and
     834          intended use.</para>
     835        </refsect1>
     836
     837        <refsect1>
     838          <title>See Also</title>
     839         
     840          <simplelist type="inline">
     841            <member><xref linkend="Character-Encodings"/></member>
     842            <member><xref linkend="External-Formats"/></member>
     843            <member><xref linkend="Supported-Character-Encodings"/></member>
     844          </simplelist>
     845        </refsect1>
     846      </refentry>
     847  </sect3>
     848
     849  <sect3 id="Supported-Character-Encodings"><title>Supported Character Encodings</title>
     850     <para>The list of supported encodings is reproduced here.  Most
     851     encodings have aliases, e.g. the encoding named
     852     <literal>:ISO-8859-1</literal> can also be referred to by the
     853     names <literal>:LATIN1</literal> and <literal>:IBM819</literal>,
     854     among others.  Where possible, the keywordized name of an
     855     encoding is equivalent to the preferred MIME charset name (and
     856     the aliases are all registered IANA charset names.)</para>
     857
     858  <variablelist>
     859    <varlistentry><term><literal>:ISO-8859-1</literal></term>
     860       <listitem><para>An 8-bit, fixed-width character encoding in
     861       which all character codes map to their Unicode
     862       equivalents. Intended to support most characters used in most
     863       Western European languages.</para>
     864       <para>Clozure CL uses ISO-8859-1 encoding for
     865       <varname>*TERMINAL-IO*</varname> and for all streams whose
     866       EXTERNAL-FORMAT isn't explicitly specified.  The default for
     867       <varname>*TERMINAL-IO*</varname> can be set via the
     868       <literal>-K</literal> command-line argument (see <xref
     869       linkend="Command-Line-Options"/>).
     870       </para>
     871       <para>ISO-8859-1 just covers the first 256 Unicode code
     872       points, where the first 128 code points are equivalent to
     873       US-ASCII.  That should be pretty much equivalent to what
     874       earliers versions of Clozure CL did that only supported 8-bit characters,
     875       but it may not be optimal for users working in a particular
     876       locale.</para>
     877       <para>Aliases: <literal>:ISO_8859-1, :LATIN1, :L1,
     878       :IBM819, :CP819, :CSISOLATIN1</literal></para></listitem>
     879     </varlistentry>
     880    <varlistentry><term><literal>:ISO-8859-2</literal></term>
     881       <listitem><para>An 8-bit, fixed-width character encoding in
     882       which codes #x00-#x9f map to their Unicode equivalents and
     883       other codes map to other Unicode character values.  Intended to
     884       provide most characters found in most languages used in
     885       Central/Eastern Europe.</para>
     886       <para>Aliases: <literal>:ISO_8859-2, :LATIN-2, :L2,
     887       :CSISOLATIN2</literal></para></listitem>
     888     </varlistentry>
     889    <varlistentry><term><literal>:ISO-8859-3</literal></term>
     890       <listitem><para>An 8-bit, fixed-width character encoding in
     891       which codes #x00-#x9f map to their Unicode equivalents and
     892       other codes map to other Unicode character values.  Intended to
     893       provide most characters found in most languages used in
     894       Southern Europe.</para>
     895       <para>Aliases: <literal>:ISO_8859-3, :LATIN,3 :L3,
     896       :CSISOLATIN3</literal></para></listitem>
     897     </varlistentry>
     898    <varlistentry><term><literal>:ISO-8859-4</literal></term>
     899       <listitem><para>An 8-bit, fixed-width character encoding in
     900       which codes #x00-#x9f map to their Unicode equivalents and
     901       other codes map to other Unicode character values.  Intended to
     902       provide most characters found in most languages used in
     903       Northern Europe.</para>
     904       <para>Aliases: <literal>:ISO_8859-4, :LATIN4, :L4, :CSISOLATIN4</literal></para></listitem>
     905     </varlistentry>
     906    <varlistentry><term><literal>:ISO-8859-5</literal></term>
     907       <listitem><para>An 8-bit, fixed-width character encoding in
     908       which codes #x00-#x9f map to their Unicode equivalents and
     909       other codes map to other Unicode character values.  Intended to
     910       provide most characters found in the Cyrillic
     911       alphabet.</para>
     912       <para>Aliases: <literal>:ISO_8859-5, :CYRILLIC, :CSISOLATINCYRILLIC,
     913       :ISO-IR-144</literal></para></listitem>
     914     </varlistentry>
     915    <varlistentry><term><literal>:ISO-8859-6</literal></term>
     916       <listitem><para>An 8-bit, fixed-width character encoding in
     917       which codes #x00-#x9f map to their Unicode equivalents and
     918       other codes map to other Unicode character values.  Intended to
     919       provide most characters found in the Arabic
     920       alphabet.</para>
     921       <para>Aliases: <literal>:ISO_8859-6, :ARABIC, :CSISOLATINARABIC,
     922       :ISO-IR-127</literal></para></listitem>
     923     </varlistentry>
     924    <varlistentry><term><literal>:ISO-8859-7</literal></term>
     925       <listitem><para>An 8-bit, fixed-width character encoding in
     926       which codes #x00-#x9f map to their Unicode equivalents and
     927       other codes map to other Unicode character values.  Intended to
     928       provide most characters found in the Greek
     929       alphabet.</para>
     930       <para>Aliases: <literal>:ISO_8859-7, :GREEK, :GREEK8, :CSISOLATINGREEK,
     931       :ISO-IR-126, :ELOT_928, :ECMA-118</literal></para></listitem>
     932     </varlistentry>
     933    <varlistentry><term><literal>:ISO-8859-8</literal></term>
     934       <listitem><para>An 8-bit, fixed-width character encoding in
     935       which codes #x00-#x9f map to their Unicode equivalents and
     936       other codes map to other Unicode character values.  Intended to
     937       provide most characters found in the Hebrew
     938       alphabet.</para>
     939       <para>Aliases: <literal>:ISO_8859-8, :HEBREW, :CSISOLATINHEBREW,
     940       :ISO-IR-138</literal></para></listitem>
     941     </varlistentry>
     942    <varlistentry><term><literal>:ISO-8859-9</literal></term>
     943       <listitem><para>An 8-bit, fixed-width character encoding in
     944       which codes #x00-#xcf map to their Unicode equivalents and
     945       other codes map to other Unicode character values.  Intended to
     946       provide most characters found in the Turkish
     947       alphabet.</para>
     948       <para>Aliases: <literal>:ISO_8859-9, :LATIN5, :CSISOLATIN5,
     949       :ISO-IR-148</literal></para></listitem>
     950     </varlistentry>
     951    <varlistentry><term><literal>:ISO-8859-10</literal></term>
     952       <listitem><para>An 8-bit, fixed-width character encoding in
     953       which codes #x00-#x9f map to their Unicode equivalents and
     954       other codes map to other Unicode character values.  Intended to
     955       provide most characters found in Nordic
     956       alphabets.</para>
     957       <para>Aliases: <literal>:ISO_8859-10, :LATIN6, :CSISOLATIN6,
     958       :ISO-IR-157</literal></para></listitem>
     959     </varlistentry>
     960    <varlistentry><term><literal>:ISO-8859-11</literal></term>
     961       <listitem><para>An 8-bit, fixed-width character encoding in
     962       which codes #x00-#x9f map to their Unicode equivalents and
     963       other codes map to other Unicode character values.  Intended to
     964       provide most characters found the Thai
     965       alphabet.</para></listitem>
     966     </varlistentry>
     967    <varlistentry><term><literal>:ISO-8859-13</literal></term>
     968       <listitem><para>An 8-bit, fixed-width character encoding in
     969       which codes #x00-#x9f map to their Unicode equivalents and
     970       other codes map to other Unicode character values.  Intended to
     971       provide most characters found in Baltic
     972       alphabets.</para></listitem>
     973     </varlistentry>
     974    <varlistentry><term><literal>:ISO-8859-14</literal></term>
     975       <listitem><para>An 8-bit, fixed-width character encoding in
     976       which codes #x00-#x9f map to their Unicode equivalents and
     977       other codes map to other Unicode character values.  Intended to
     978       provide most characters found in Celtic
     979       languages.</para>
     980       <para>Aliases: <literal>:ISO_8859-14, :ISO-IR-199, :LATIN8, :L8,
     981       :ISO-CELTIC</literal></para></listitem>
     982     </varlistentry>
     983    <varlistentry><term><literal>:ISO-8859-15</literal></term>
     984       <listitem><para>An 8-bit, fixed-width character encoding in
     985       which codes #x00-#x9f map to their Unicode equivalents and
     986       other codes map to other Unicode character values.  Intended to
     987       provide most characters found in Western European languages
     988       (including the Euro sign and some other characters missing from
     989       ISO-8859-1.</para>
     990       <para>Aliases: <literal>:ISO_8859-15, :LATIN9</literal></para></listitem>
     991     </varlistentry>
     992    <varlistentry><term><literal>:ISO-8859-16</literal></term>
     993       <listitem><para>An 8-bit, fixed-width character encoding in
     994       which codes #x00-#x9f map to their Unicode equivalents and
     995       other codes map to other Unicode character values.  Intended to
     996       provide most characters found in Southeast European
     997       languages.</para>
     998       <para>Aliases: <literal>:ISO_8859-16, :ISO-IR-199, :LATIN8, :L8,
     999       :ISO-CELTIC</literal></para></listitem>
     1000     </varlistentry>
     1001    <varlistentry><term><literal>:MACINTOSH</literal></term>
     1002       <listitem><para>An 8-bit, fixed-width character encoding in
     1003       which codes #x00-#x7f map to their Unicode equivalents and
     1004       other codes map to other Unicode character values.
     1005       Traditionally used on Classic MacOS to encode characters used
     1006       in western languages.</para>
     1007       <para>Aliases: <literal>:MACOS-ROMAN, :MACOSROMAN, :MAC-ROMAN,
     1008       :MACROMAN</literal></para></listitem>
     1009     </varlistentry>
     1010    <varlistentry><term><literal>:UCS-2</literal></term>
     1011       <listitem><para>A 16-bit, fixed-length encoding in which
     1012       characters with CHAR-CODEs less than #x10000 can be encoded in
     1013       a single 16-bit word.  The endianness of the encoded data is
     1014       indicated by the endianness of a byte-order-mark character
     1015       (#u+feff) prepended to the data; in the absence of such a
     1016       character on input, the data is assumed to be in big-endian
     1017       order.</para></listitem>
     1018     </varlistentry>
     1019    <varlistentry><term><literal>:UCS-2BE</literal></term>
     1020       <listitem><para>A 16-bit, fixed-length encoding in which
     1021       characters with CHAR-CODEs less than #x10000 can be encoded in
     1022       a single 16-bit big-endian word. The encoded data is implicitly
     1023       big-endian; byte-order-mark characters are not interpreted on
     1024       input or prepended to output.</para></listitem>
     1025     </varlistentry>
     1026    <varlistentry><term><literal>:UCS-2LE</literal></term>
     1027       <listitem><para>A 16-bit, fixed-length encoding in which
     1028       characters with CHAR-CODEs less than #x10000 can be encoded in
     1029       a single 16-bit little-endian word. The encoded data is
     1030       implicitly little-endian; byte-order-mark characters are not
     1031       interpreted on input or prepended to output.</para></listitem>
     1032     </varlistentry>
     1033    <varlistentry><term><literal>:US-ASCII</literal></term>
     1034       <listitem><para>An 7-bit, fixed-width character encoding in
     1035       which all character codes map to their Unicode
     1036       equivalents. </para>
     1037       <para>Aliases: <literal>:CSASCII, :CP63,7 :IBM637, :US,
     1038       :ISO646-US, :ASCII, :ISO-IR-6</literal></para></listitem>
     1039     </varlistentry>
     1040    <varlistentry><term><literal>:UTF-16</literal></term>
     1041       <listitem><para>A 16-bit, variable-length encoding in which
     1042       characters with CHAR-CODEs less than #x10000 can be encoded in
     1043       a single 16-bit word and characters with larger codes can be
     1044       encoded in a pair of 16-bit words.  The endianness of the
     1045       encoded data is indicated by the endianness of a
     1046       byte-order-mark character (#u+feff) prepended to the data; in
     1047       the absence of such a character on input, the data is assumed
     1048       to be in big-endian order. Output is written in native
     1049       byte-order with a leading byte-order mark.</para></listitem>
     1050     </varlistentry>
     1051    <varlistentry><term><literal>:UTF-16BE</literal></term>
     1052       <listitem><para>A 16-bit, variable-length encoding in which
     1053       characters with CHAR-CODEs less than #x10000 can be encoded in
     1054       a single 16-bit big-endian word and characters with larger
     1055       codes can be encoded in a pair of 16-bit big-endian words.  The
     1056       endianness of the encoded data is implicit in the encoding;
     1057       byte-order-mark characters are not interpreted on input or
     1058       prepended to output.</para></listitem>
     1059     </varlistentry>
     1060    <varlistentry><term><literal>:UTF-16LE</literal></term>
     1061       <listitem><para>A 16-bit, variable-length encoding in which
     1062       characters with CHAR-CODEs less than #x10000 can be encoded in
     1063       a single 16-bit little-endian word and characters with larger
     1064       codes can be encoded in a pair of 16-bit little-endian words.
     1065       The endianness of the encoded data is implicit in the encoding;
     1066       byte-order-mark characters are not interpreted on input or
     1067       prepended to output.</para></listitem>
     1068     </varlistentry>
     1069    <varlistentry><term><literal>:UTF-32</literal></term>
     1070       <listitem><para>A 32-bit, fixed-length encoding in which all
     1071       Unicode characters can be encoded in a single 32-bit word.  The
     1072       endianness of the encoded data is indicated by the endianness
     1073       of a byte-order-mark character (#u+feff) prepended to the data;
     1074       in the absence of such a character on input, input data is
     1075       assumed to be in big-endian order.  Output is written in native
     1076       byte order with a leading byte-order mark.</para>
     1077       <para>Alias: <literal>:UTF-4</literal></para></listitem>
     1078     </varlistentry>
     1079    <varlistentry><term><literal>:UTF-32BE</literal></term>
     1080       <listitem><para>A 32-bit, fixed-length encoding in which all
     1081       Unicode characters encoded in a single 32-bit word. The encoded
     1082       data is implicitly big-endian; byte-order-mark characters are
     1083       not interpreted on input or prepended to
     1084       output.</para>
     1085       <para>Alias: <literal>:UCS-4BE</literal></para></listitem>
     1086     </varlistentry>
     1087    <varlistentry><term><literal>:UTF-8</literal></term>
     1088       <listitem><para>An 8-bit, variable-length character encoding in
     1089       which characters with CHAR-CODEs in the range #x00-#x7f can be
     1090       encoded in a single octet; characters with larger code values
     1091       can be encoded in 2 to 4 bytes.</para></listitem>
     1092     </varlistentry>
     1093    <varlistentry><term><literal>:UTF32LE</literal></term>
     1094       <listitem><para>A 32-bit, fixed-length encoding in which all
     1095       Unicode characters can encoded in a single 32-bit word. The
     1096       encoded data is implicitly little-endian; byte-order-mark
     1097       characters are not interpreted on input or prepended to
     1098       output.</para>
     1099       <para>Alias: <literal>:UCS-4LE</literal></para></listitem>
     1100     </varlistentry>
     1101  </variablelist>
     1102    </sect3>
     1103  </sect2>
     1104
    8291105  </sect1>
    8301106
     
    11131389  <!-- ============================================================ -->
    11141390  <sect1 id="Saving-Applications">
    1115         <indexterm zone="Saving-Applications">
    1116           <primary>save-application</primary>
    1117         </indexterm>
    11181391    <title>Saving Applications</title>
     1392    <indexterm zone="Saving-Applications">
     1393      <primary>save-application</primary>
     1394    </indexterm>
    11191395
    11201396    <para>&CCL; provides the
  • trunk/source/doc/src/xsl/directory-fixes.xsl

    r8555 r8993  
    2525  </xsl:param>
    2626
    27   <xsl:param name="html.stylesheet">
    28     <xsl:value-of select="$openmcl.base"/>
    29     <xsl:text>openmcl.css</xsl:text>
    30   </xsl:param>
    31 
    32   <!-- Be aware that href.target.uri cannot be defined in this file,
     27   <!-- Be aware that href.target.uri cannot be defined in this file,
    3328       because it would be overridden by the definition in
    3429       optional-onechunk.xsl. -->
  • trunk/source/doc/src/xsl/openmcl.xsl

    r8555 r8993  
    1717  <xsl:include href="footer.xsl"/>
    1818  <xsl:include href="minor-customizations.xsl"/>
    19   <xsl:include href="directory-fixes.xsl"/>
    2019  <xsl:include href="optional-onechunk.xsl"/>
    2120
  • trunk/source/doc/src/xsl/refentry.xsl

    r8820 r8993  
    4040      <div class="refentrytitle">
    4141        <a>
    42           <xsl:attribute name="href">
    43             <xsl:call-template name="href.target"/>
     42          <xsl:attribute name="id">
     43            <xsl:value-of select="@id"/>
    4444          </xsl:attribute>
    4545        </a>
    4646        <strong>[<xsl:value-of select="refnamediv/refclass"/>]</strong><br/>
    47         <code><xsl:apply-templates select="refsynopsisdiv/synopsis/node()"/></code>
    48 
     47        <xsl:choose>
     48          <xsl:when test="refsynopsisdiv/synopsis">
     49            <code><xsl:apply-templates select="refsynopsisdiv/synopsis/node()"/></code>
     50          </xsl:when>
     51          <xsl:otherwise>
     52            <code><xsl:value-of select="refnamediv/refname"/></code>
     53          </xsl:otherwise>
     54        </xsl:choose>
    4955      </div>
    5056      <div class="refentrytitle">
Note: See TracChangeset for help on using the changeset viewer.