Changeset 8820


Ignore:
Timestamp:
Mar 18, 2008, 1:49:58 PM (11 years ago)
Author:
jaj
Message:

This commit includes support for docbook 4.5, stylesheet changes, and updated documentation.

In order to support docbook 4.5 in nXML mode, I have added a new directory called docbook-rng-4.5 and changed schemas.xml to point to it. This should just work when editing the documentation in EMACS.

The two most obvious changes to the stylesheets are that the table of contents for each chapter now occurs at the beginning of the chapter, and the format for refentries is cleaner and more concise.

I think that we should consistently use refentry elements for all of the definitions of functions, macros, variables, etc. This retains the structured data for the definitions that can be reformatted to have different appearences by the stylesheets. We should also consistently use other docbook elements such as function and varname. I'm not really happy with their appearance right now, but that can be easily tweaked in the stylesheets as long as they are consistently used throughout the documentation.

Location:
trunk/source/doc/src
Files:
13 added
21 edited

Legend:

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

    r8606 r8820  
    11<?xml version="1.0" encoding="utf-8"?>
    2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"[
     2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
    33<!ENTITY rest "<varname>&amp;rest</varname>">
    44<!ENTITY key "<varname>&amp;key</varname>">
     
    77<!ENTITY aux "<varname>&amp;aux</varname>">
    88<!ENTITY allow-other-keys "<varname>&amp;allow-other-keys</varname>">
    9 <!ENTITY CCL "<literal>CCL</literal>">
     9<!ENTITY CCL "Clozure CL">
    1010]>
    1111  <chapter><title>Building &CCL; from its Source Code</title>
  • trunk/source/doc/src/ccl-documentation.xml

    r8693 r8820  
    11<?xml version="1.0" encoding="utf-8"?>
    22<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
    3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"[
     3"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
    44<!ENTITY rest "<varname>&amp;rest</varname>">
    55<!ENTITY key "<varname>&amp;key</varname>">
     
    88<!ENTITY aux "<varname>&amp;aux</varname>">
    99<!ENTITY allow-other-keys "<varname>&amp;allow-other-keys</varname>">
    10 <!ENTITY CCL "<literal>CCL</literal>">
     10<!ENTITY CCL "Clozure CL">
    1111]>
    1212
     
    1515  <title>&CCL; Documentation</title>
    1616 </bookinfo>
    17 
     17<!-- -->
    1818<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
    1919            href="install.xml"/>
  • trunk/source/doc/src/external-process.xml

    r8606 r8820  
    11<?xml version="1.0" encoding="utf-8"?>
    2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
     2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
    33<!ENTITY rest "<varname>&amp;rest</varname>">
    44<!ENTITY key "<varname>&amp;key</varname>">
     
    77<!ENTITY aux "<varname>&amp;aux</varname>">
    88<!ENTITY allow-other-keys "<varname>&amp;allow-other-keys</varname>">
    9 <!ENTITY CCL "<literal>CCL</literal>">
     9<!ENTITY CCL "Clozure CL">
    1010]>
    1111
  • trunk/source/doc/src/ffi.xml

    r8704 r8820  
    11<?xml version="1.0" encoding="utf-8"?>
    2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
     2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
    33          <!ENTITY rest "<varname>&amp;rest</varname>">
    44          <!ENTITY key "<varname>&amp;key</varname>">
  • trunk/source/doc/src/gc.xml

    r8606 r8820  
    11<?xml version="1.0" encoding="utf-8"?>
    2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"[
     2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
    33<!ENTITY rest "<varname>&amp;rest</varname>">
    44<!ENTITY key "<varname>&amp;key</varname>">
  • trunk/source/doc/src/glossary.xml

    r8703 r8820  
    11<?xml version="1.0" encoding="utf-8"?>
    2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
    3           "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"[
     2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
     3          "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
    44          <!ENTITY rest "<varname>&amp;rest</varname>">
    55          <!ENTITY key "<varname>&amp;key</varname>">
     
    88          <!ENTITY aux "<varname>&amp;aux</varname>">
    99          <!ENTITY allow-other-keys "<varname>&amp;allow-other-keys</varname>">
    10           <!ENTITY CCL "<literal>CCL</literal>">
     10          <!ENTITY CCL "Clozure CL">
    1111          ]>
    1212
  • trunk/source/doc/src/ide.xml

    r8797 r8820  
    11<?xml version="1.0" encoding="utf-8"?>
    2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
    3           "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"[
     2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
     3          "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
    44          <!ENTITY rest "<varname>&amp;rest</varname>">
    55          <!ENTITY key "<varname>&amp;key</varname>">
     
    88          <!ENTITY aux "<varname>&amp;aux</varname>">
    99          <!ENTITY allow-other-keys "<varname>&amp;allow-other-keys</varname>">
    10           <!ENTITY CCL "<literal>CCL</literal>">
     10          <!ENTITY CCL "Clozure CL">
    1111          ]>
    1212
  • trunk/source/doc/src/implementation.xml

    r8659 r8820  
    11<?xml version="1.0" encoding="utf-8"?>
    2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"[
     2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
    33<!ENTITY rest "<varname>&amp;rest</varname>">
    44<!ENTITY key "<varname>&amp;key</varname>">
     
    77<!ENTITY aux "<varname>&amp;aux</varname>">
    88<!ENTITY allow-other-keys "<varname>&amp;allow-other-keys</varname>">
    9 <!ENTITY CCL "<literal>CCL</literal>">
     9<!ENTITY CCL "Clozure CL">
    1010]>
    1111  <chapter id="Implementation-Details-of-CCL">
     
    4343      (by definition) rarely occurs.</para>
    4444      <para>Some emulated execution environments (the Rosetta PPC
    45       emulator on x86 versions of OSX) don't provide accurate
     45      emulator on x86 versions of Mac OS X) don't provide accurate
    4646      exception information to exception handling functions. &CCL;
    4747      can't run in such environments.</para>
  • trunk/source/doc/src/install.xml

    r8659 r8820  
    11<?xml version="1.0" encoding="utf-8"?>
    2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
    3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"[
     2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
     3"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
    44<!ENTITY rest "<varname>&amp;rest</varname>">
    55<!ENTITY key "<varname>&amp;key</varname>">
     
    88<!ENTITY aux "<varname>&amp;aux</varname>">
    99<!ENTITY allow-other-keys "<varname>&amp;allow-other-keys</varname>">
    10 <!ENTITY CCL "<literal>CCL</literal>">
     10<!ENTITY CCL "Clozure CL">
    1111]>
    1212
     
    200200      </sect2>
    201201
    202       <sect2><title>The-openmcl-Shell-Script"</title>
    203       <para>&CCL; needs to be able to find the
     202      <sect2 id="The-openmcl-Shell-Script"><title>The openmcl Shell Script"</title>
     203      <para>Clozure CL needs to be able to find the
    204204      <literal>ccl</literal> directory in order to support features
    205205      such as <literal>require</literal> and
  • trunk/source/doc/src/modifying.xml

    r8659 r8820  
    11<?xml version="1.0" encoding="utf-8"?>
    2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
     2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
    33<!ENTITY rest "<varname>&amp;rest</varname>">
    44<!ENTITY key "<varname>&amp;key</varname>">
     
    77<!ENTITY aux "<varname>&amp;aux</varname>">
    88<!ENTITY allow-other-keys "<varname>&amp;allow-other-keys</varname>">
    9 <!ENTITY CCL "<literal>CCL</literal>">
     9<!ENTITY CCL "Clozure CL">
    1010]>
    1111
  • trunk/source/doc/src/mop.xml

    r8606 r8820  
    11<?xml version="1.0" encoding="utf-8"?>
    2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
     2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
    33<!ENTITY rest "<varname>&amp;rest</varname>">
    44<!ENTITY key "<varname>&amp;key</varname>">
     
    77<!ENTITY aux "<varname>&amp;aux</varname>">
    88<!ENTITY allow-other-keys "<varname>&amp;allow-other-keys</varname>">
    9 <!ENTITY CCL "<literal>CCL</literal>">
     9<!ENTITY CCL "Clozure CL">
    1010]>
    1111
  • trunk/source/doc/src/objc-bridge.xml

    r8606 r8820  
    11<?xml version="1.0" encoding="utf-8"?>
    2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"[
     2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
    33<!ENTITY rest "<varname>&amp;rest</varname>">
    44<!ENTITY key "<varname>&amp;key</varname>">
     
    77<!ENTITY aux "<varname>&amp;aux</varname>">
    88<!ENTITY allow-other-keys "<varname>&amp;allow-other-keys</varname>">
    9 <!ENTITY CCL "<literal>CCL</literal>">
     9<!ENTITY CCL "Clozure CL">
    1010]>
    1111  <chapter id="The-Objective-C-Bridge">
  • trunk/source/doc/src/platform-notes.xml

    r8659 r8820  
    11<?xml version="1.0" encoding="utf-8"?>
    2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
     2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
    33<!ENTITY rest "<varname>&amp;rest</varname>">
    44<!ENTITY key "<varname>&amp;key</varname>">
     
    77<!ENTITY aux "<varname>&amp;aux</varname>">
    88<!ENTITY allow-other-keys "<varname>&amp;allow-other-keys</varname>">
    9 <!ENTITY CCL "<literal>CCL</literal>">
     9<!ENTITY CCL "Clozure CL">
    1010]>
    1111
     
    2222      the implementation.</para>
    2323
     24      <sect2 id="differences-between-32-bit-and-64-bit-implementations">
     25        <title>Differences Between 32-bit and 64-bit implementations</title>
     26
     27        <para>Fixnums on 32-bit systems use 30 bits and are in the
     28        range XXX through YYY.  Fixnums on 64-bit systems use 61-bits
     29        and are in the range XXX through YYY. (see <xref
     30        linkend="Tagging-scheme"/>)</para>
     31
     32        <para>Since we have much larger fixnums on 64-bit systems,
     33        <varname>INTERNAL-TIME-UNITS-PER-SECOND</varname> is 1000000
     34        on 64-bit systems but remains 1000 on 32-bit systems.  This
     35        enables much finer grained timing on 64-bit systems.</para>
     36      </sect2>
    2437
    2538      <sect2 id="File-system-case">
     
    3548        opposite assumption would be no more correct than the one
    3649        that's currently made.</para>
    37         <para>Whatever the best solution to this problem turns out to be, there are
    38 some practical considerations. Doing:</para>
     50        <para>Whatever the best solution to this problem turns out to
     51        be, there are some practical considerations. Doing:</para>
    3952        <programlisting>
    4053? (save-application "DPPCCL")
  • trunk/source/doc/src/q-and-a.xml

    r8702 r8820  
    11<?xml version="1.0" encoding="utf-8"?>
    2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"[
     2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
    33<!ENTITY rest "<varname>&amp;rest</varname>">
    44<!ENTITY key "<varname>&amp;key</varname>">
     
    77<!ENTITY aux "<varname>&amp;aux</varname>">
    88<!ENTITY allow-other-keys "<varname>&amp;allow-other-keys</varname>">
    9 <!ENTITY CCL "<literal>CCL</literal>">
     9<!ENTITY CCL "Clozure CL">
    1010]>
    1111  <chapter id="Questions-and-Answers">
  • trunk/source/doc/src/schemas.xml

    r8569 r8820  
    11<locatingRules xmlns="http://thaiopensource.com/ns/locating-rules/1.0">
    22<documentElement prefix="" localName="chapter" typeId="DocBook"/>
     3<typeId id="DocBook" uri="docbook-rng-4.5/docbook.rnc"/>
    34</locatingRules>
  • trunk/source/doc/src/sockets.xml

    r8606 r8820  
    11<?xml version="1.0" encoding="utf-8"?>
    2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
     2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
    33<!ENTITY rest "<varname>&amp;rest</varname>">
    44<!ENTITY key "<varname>&amp;key</varname>">
     
    77<!ENTITY aux "<varname>&amp;aux</varname>">
    88<!ENTITY allow-other-keys "<varname>&amp;allow-other-keys</varname>">
    9 <!ENTITY CCL "<literal>CCL</literal>">
     9<!ENTITY CCL "Clozure CL">
    1010]>
    1111
     
    106106
    107107        <refsynopsisdiv>
    108           <synopsis><function>make-socket</function>
    109           &key; address-family type connect eol format
    110           remote-host remote-port local-host local-port local-filename
    111           remote-filename keepalive reuse-address nodelay broadcast linger
    112           backlog</synopsis>
     108          <synopsis><function>make-socket</function> &key;
     109          address-family type connect eol format remote-host
     110          remote-port local-host local-port local-filename
     111          remote-filename keepalive reuse-address nodelay broadcast
     112          linger backlog input-timeout output-timeout connect-timeout
     113          auto-close deadline</synopsis>
    113114        </refsynopsisdiv>
    114115
     
    300301              </listitem>
    301302            </varlistentry>
     303
     304            <varlistentry>
     305              <term>input-timeout</term>
     306
     307              <listitem>
     308                <para>The number of seconds before an input operation
     309                times out.  Must be a real number between zero and one
     310                million.  If an input operation takes longer than the
     311                specified number of seconds, an
     312                <literal>input-timeout</literal> error is signalled.
     313                (see <xref
     314                linkend="Stream-Timeouts-And-Deadlines"/>)</para>
     315              </listitem>
     316            </varlistentry>
     317
     318            <varlistentry>
     319              <term>output-timeout</term>
     320
     321              <listitem>
     322                <para>The number of seconds before an output operation
     323                times out.  Must be a real number between zero and one
     324                million.  If an output operation takes longer than the
     325                specified number of seconds, an
     326                <literal>output-timeout</literal> error is signalled.
     327                (see <xref
     328                linkend="Stream-Timeouts-And-Deadlines"/>)</para>
     329              </listitem>
     330            </varlistentry>
     331
     332            <varlistentry>
     333              <term>connect-timeout</term>
     334
     335              <listitem>
     336                <para>The number of seconds before a connection
     337                attempt times out. [TODO: what are acceptable values?]
     338                If a connection attempt takes longer than the
     339                specified number of seconds, a
     340                <literal>socket-error</literal> is signalled.  This
     341                can be useful if the specified interval is shorter
     342                than the interval that the OS's socket layer imposes,
     343                which is sometimes a minute or two.</para>
     344              </listitem>
     345            </varlistentry>
     346
     347            <varlistentry>
     348              <term>auto-close</term>
     349
     350              <listitem>
     351                <para>When non-nil, any resulting socket stream will
     352                be closed when the GC can prove that the stream is
     353                unreferenced.  This is done via CCL's termination
     354                mechanism [TODO add xref].</para>
     355              </listitem>
     356            </varlistentry>
     357            <varlistentry>
     358              <term>deadline</term>
     359
     360              <listitem>
     361                <para>Specifies an absolute time in
     362                internal-time-units.  If an I/O operation on the
     363                stream does not complete before the deadline then a
     364                <literal>COMMUNICATION-DEADLINE-EXPIRED</literal>
     365                error is signalled.  A deadline takes precedence over
     366                any input/output timeouts that may be set.  (see <xref
     367                linkend="Stream-Timeouts-And-Deadlines"/>)</para>
     368              </listitem>
     369            </varlistentry>
     370
    302371          </variablelist>
    303372        </refsect1>
  • trunk/source/doc/src/streams.xml

    r8606 r8820  
    11<?xml version="1.0" encoding="utf-8"?>
    2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
     2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
    33<!ENTITY rest "<varname>&amp;rest</varname>">
    44<!ENTITY key "<varname>&amp;key</varname>">
     
    77<!ENTITY aux "<varname>&amp;aux</varname>">
    88<!ENTITY allow-other-keys "<varname>&amp;allow-other-keys</varname>">
    9 <!ENTITY CCL "<literal>CCL</literal>">
     9<!ENTITY CCL "Clozure CL">
    1010]>
    1111
    12   <chapter id="Creating-Your-Own-Stream-Classes-with-Gray-Streams">
     12<chapter id="Streams">
     13  <title>Streams</title>
     14
     15  <sect1 id="CCL-Stream-Extensions">
     16    <title>Stream Extensions</title>
     17    <sect2 id="Stream-Timeouts-And-Deadlines">
     18      <title>Stream Timeouts and Deadlines</title>
     19    <indexterm>
     20      <primary>stream-input-timeout</primary>
     21    </indexterm>
     22    <indexterm>
     23      <primary>stream-output-timeout</primary>
     24    </indexterm>
     25    <indexterm>
     26      <primary>stream-deadline</primary>
     27    </indexterm>
     28    <indexterm>
     29      <primary>input-timeout</primary>
     30    </indexterm>
     31    <indexterm>
     32      <primary>output-timeout</primary>
     33    </indexterm>
     34    <indexterm>
     35      <primary>communication-deadline-expired</primary>
     36    </indexterm>
     37    <para>A stream that is associated with a file descriptor has
     38    attributes and accessors:
     39    <function>STREAM-INPUT-TIMEOUT</function>,
     40    <function>STREAM-OUTPUT-TIMEOUT</function>, and
     41    <function>STREAM-DEADLINE</function>.  All three accessors have
     42    corresponding <function>SETF</function> methods.
     43    <function>STREAM-INPUT-TIMEOUT</function> and
     44    <function>STREAM-OUTPUT-TIMEOUT</function> are specified in
     45    seconds and can be any positive real number less than one million.
     46    When a timeout is set and the corresponding I/O operation takes
     47    longer than the specified interval, an error is signalled.  The
     48    error is <literal>INPUT-TIMEOUT</literal> for input and
     49    <literal>OUTPUT-TIMEOUT</literal> for output.
     50    <literal>STREAM-DEADLINE</literal> specifies an absolute time in
     51    internal-time-units.  If an I/O operation on the stream does not
     52    complete before the deadline then a
     53    <literal>COMMUNICATION-DEADLINE-EXPIRED</literal> error is
     54    signalled.  A deadline takes precedence over any
     55    input/output timeouts that may be set.</para>
     56    </sect2>
     57
     58    <sect2 id="Open-File-Streams">
     59      <title>Open File Streams</title>
     60      <para>Historically, Clozure CL and MCL maintained a list of open
     61      file streams in the value of
     62      <literal>CCL:*OPEN-FILE-STREAMS*</literal>.  This functionality
     63      has been replaced with the thread-safe function:
     64      <literal>CCL:OPEN-FILE-STREAMS</literal> and its two helper
     65      functions: <literal>CCL:NOTE-OPEN-FILE-STREAM</literal> and
     66      <literal>CCL:REMOVE-OPEN-FILE-STREAM</literal>.  Maintaining
     67      this list helps to ensure that streams get closed in an orderly
     68      manner when the lisp exits.</para>
     69
     70      <refentry id="f_open-file-streams">
     71        <indexterm zone="f_open-file-streams">
     72          <primary>open-file-streams</primary>
     73        </indexterm>
     74
     75        <refnamediv>
     76          <refname>OPEN-FILE-STREAMS</refname>
     77          <refpurpose>Returns the list of file streams that are currently open.</refpurpose>
     78          <refclass>Function</refclass>
     79        </refnamediv>
     80
     81        <refsynopsisdiv>
     82          <synopsis>
     83            <function>open-file-streams</function>
     84            => stream-list
     85          </synopsis>
     86        </refsynopsisdiv>
     87
     88        <refsect1>
     89          <title>Values</title>
     90         
     91          <variablelist>
     92            <varlistentry>
     93              <term>stream-list</term>
     94              <listitem>
     95                <para>A list of open file streams.  This is a copy of
     96                an internal list so it may be destructively
     97                modified without ill effect.</para>
     98              </listitem>
     99            </varlistentry>
     100          </variablelist>
     101        </refsect1>
     102
     103        <refsect1>
     104          <title>Description</title>
     105          <para>Returns a list of open file streams.</para>
     106        </refsect1>
     107
     108        <refsect1>
     109          <title>See Also</title>       
     110          <simplelist type="inline">
     111            <member><xref linkend="f_note-open-file-stream"/></member>
     112            <member><xref linkend="f_remove-open-file-stream"/></member>
     113          </simplelist>
     114        </refsect1>
     115      </refentry>
     116
     117      <refentry id="f_note-open-file-stream">
     118        <indexterm zone="f_note-open-file-stream">
     119          <primary>note-open-file-stream</primary>
     120        </indexterm>
     121
     122        <refnamediv>
     123          <refname>NOTE-OPEN-FILE-STREAM</refname>
     124          <refpurpose>Adds a file stream to the internal list of open
     125          file streams that is returned by
     126          <function>note-open-file-stream</function>.</refpurpose>
     127          <refclass>Function</refclass>
     128        </refnamediv>
     129
     130        <refsynopsisdiv>
     131          <synopsis>
     132            <function>note-open-file-stream</function>
     133            file-stream
     134          </synopsis>
     135        </refsynopsisdiv>
     136
     137        <refsect1>
     138          <title>Arguments</title>
     139         
     140          <variablelist>
     141            <varlistentry>
     142              <term>file-stream</term>
     143              <listitem>
     144                <para>A file stream.</para>
     145              </listitem>
     146            </varlistentry>
     147          </variablelist>
     148        </refsect1>
     149
     150        <refsect1>
     151          <title>Description</title>
     152          <para>Adds a file stream to the internal list of open
     153          file streams that is returned by
     154          <function>open-file-streams</function>.  This function is
     155          thread-safe.  It will usually only be called from custom
     156          stream code when a file-stream is created.</para>
     157        </refsect1>
     158
     159        <refsect1>
     160          <title>See Also</title>       
     161          <simplelist type="inline">
     162            <member><xref linkend="f_open-file-streams"/></member>
     163            <member><xref linkend="f_remove-open-file-stream"/></member>
     164          </simplelist>
     165        </refsect1>
     166
     167      </refentry>
     168
     169      <refentry id="f_remove-open-file-stream">
     170        <indexterm zone="f_remove-open-file-stream">
     171          <primary>remove-open-file-stream</primary>
     172        </indexterm>
     173
     174        <refnamediv>
     175          <refname>REMOVE-OPEN-FILE-STREAM</refname>
     176          <refpurpose>Removes file stream from the internal list of open
     177          file streams that is returned by
     178          <function>open-file-streams</function>.</refpurpose>
     179          <refclass>Function</refclass>
     180        </refnamediv>
     181
     182        <refsynopsisdiv>
     183          <synopsis>
     184            <function>remove-open-file-stream</function>
     185            file-stream
     186          </synopsis>
     187        </refsynopsisdiv>
     188
     189        <refsect1>
     190          <title>Arguments</title>
     191         
     192          <variablelist>
     193            <varlistentry>
     194              <term>file-stream</term>
     195              <listitem>
     196                <para>A file stream.</para>
     197              </listitem>
     198            </varlistentry>
     199          </variablelist>
     200        </refsect1>
     201
     202        <refsect1>
     203          <title>Description</title>
     204          <para>Remove file stream from the internal list of open file
     205          streams that is returned by
     206          <function>open-file-streams</function>.  This function is
     207          thread-safe.  It will usually only be called from custom
     208          stream code when a file-stream is closed.</para>
     209        </refsect1>
     210
     211        <refsect1>
     212          <title>See Also</title>       
     213          <simplelist type="inline">
     214            <member><xref linkend="f_open-file-streams"/></member>
     215            <member><xref linkend="f_note-open-file-stream"/></member>
     216          </simplelist>
     217        </refsect1>
     218
     219      </refentry>
     220
     221    </sect2>
     222  </sect1>
     223
     224  <sect1 id="Creating-Your-Own-Stream-Classes-with-Gray-Streams">
    13225    <title>Creating Your Own Stream Classes with Gray Streams</title>
    14226
    15     <sect1 id="Streams-Overview">
     227    <sect2 id="Streams-Overview">
    16228      <title>Overview</title>
    17       <para>This chapter is still being written and revised, because
     229      <para>This sect1 is still being written and revised, because
    18230      it is woefully incomplete.  The dictionary section currently
    19231      only lists a couple functions.  Caveat lector.</para>
     
    31243      <para>Here's a list of some classes which you might wish for
    32244      your new stream class to inherit from:</para>
    33  
     245      
    34246      <simplelist>
    35247        <member>fundamental-stream</member>
     
    146358        <member>stream-filename stream => string</member>
    147359        <member>ccl::select-stream-class instance in-p out-p char-p =>
    148                 class</member>
     360        class</member>
    149361      </simplelist>
    150362      <para>The following functions are standard parts of Common Lisp, but
    151 behave in special ways with regard to Gray streams.</para>
     363      behave in special ways with regard to Gray streams.</para>
    152364      <simplelist>
    153365        <member>open-stream-p stream => generalized-boolean</member>
     
    169381      <para>The following are standard, and do not behave specially
    170382      with regard to Gray streams, but probably should.</para>
    171        <simplelist>
     383      <simplelist>
    172384        <member>stream-external-format</member>
    173385      </simplelist>
    174     </sect1>
    175 
    176     <sect1 id="Extending-READ-SEQUENCE-and-WRITE-SEQUENCE">
     386    </sect2>
     387
     388    <sect2 id="Extending-READ-SEQUENCE-and-WRITE-SEQUENCE">
    177389      <title>Extending READ-SEQUENCE and WRITE-SEQUENCE</title>
    178390
    179       <sect2 id="extending-read-write-overview">
    180         <title>Overview</title>
     391      <sect3 id="extending-read-write-overview">
     392        <title>Overview</title>
    181393        <para>The "Gray Streams" API is based on an informal proposal that was
    182394        made before ANSI CL adopted the READ-SEQUENCE and WRITE-SEQUENCE
     
    185397        knowledge of the stream's internals (e.g., the buffering mechanism it
    186398        uses.)</para>
    187         <para>In the absence of any such knowledge, READ-SEQUENCE and
    188         WRITE-SEQUENCE are effectively just convenient shorthand for a
    189         loop which calls READ-CHAR/READ-BYTE/WRITE-CHAR/WRITE-BYTE as
    190         appropriate. The mechanism described below allows subclasses
    191         of FUNDAMENTAL-STREAM to define more specialized (and
    192         presumably more efficient) behavior.</para>
    193       </sect2>
    194 
    195       <sect2 id="Notes">
     399        <para>In the absence of any such knowledge, READ-SEQUENCE and
     400        WRITE-SEQUENCE are effectively just convenient shorthand for a
     401        loop which calls READ-CHAR/READ-BYTE/WRITE-CHAR/WRITE-BYTE as
     402        appropriate. The mechanism described below allows subclasses
     403        of FUNDAMENTAL-STREAM to define more specialized (and
     404        presumably more efficient) behavior.</para>
     405      </sect3>
     406
     407      <sect3 id="Notes">
    196408        <title>Notes</title>
    197         <para>READ-SEQUENCE and WRITE-SEQUENCE do a certain amount of
    198         sanity-checking and normalization of their arguments before
    199         dispatching to one of the methods above. If an individual
    200         method can't do anything particularly clever, CALL-NEXT-METHOD
    201         can be used to handle the general case.</para>
    202       </sect2>
    203 
    204       <sect2 id="Example">
    205         <title>Example</title>
    206         <programlisting>
    207 (defclass my-string-input-stream (fundamental-character-input-stream)
    208   ((string :initarg :string :accessor my-string-input-stream-string)
    209    (index :initform 0 :accessor my-string-input-stream-index)
    210    (length)))
    211 
    212 (defmethod stream-read-vector ((stream my-string-input-stream) vector start end)
    213   (if (not (typep vector 'simple-base-string))
    214       (call-next-method)
    215       (with-slots (string index length)
    216         (do* ((outpos start (1+ outpos)))
    217              ((or (= outpos end)
    218                   (= index length))
    219               outpos))
    220           (setf (schar vector outpos)
    221                 (schar string index))
    222           (incf index)))))
    223 </programlisting>
    224       </sect2>
    225     </sect1>
    226 
    227     <sect1 id="Multibyte-I-O">
     409        <para>READ-SEQUENCE and WRITE-SEQUENCE do a certain amount of
     410        sanity-checking and normalization of their arguments before
     411        dispatching to one of the methods above. If an individual
     412        method can't do anything particularly clever, CALL-NEXT-METHOD
     413        can be used to handle the general case.</para>
     414      </sect3>
     415
     416      <sect3 id="Example">
     417        <title>Example</title>
     418        <programlisting>
     419          (defclass my-string-input-stream (fundamental-character-input-stream)
     420          ((string :initarg :string :accessor my-string-input-stream-string)
     421          (index :initform 0 :accessor my-string-input-stream-index)
     422          (length)))
     423
     424          (defmethod stream-read-vector ((stream my-string-input-stream) vector start end)
     425          (if (not (typep vector 'simple-base-string))
     426          (call-next-method)
     427          (with-slots (string index length)
     428          (do* ((outpos start (1+ outpos)))
     429          ((or (= outpos end)
     430          (= index length))
     431          outpos))
     432          (setf (schar vector outpos)
     433          (schar string index))
     434          (incf index)))))
     435        </programlisting>
     436      </sect3>
     437    </sect2>
     438
     439    <sect2 id="Multibyte-I-O">
    228440      <title>Multibyte I/O</title>
    229441      <para>All heap-allocated objects in &CCL; that cannot contain
     
    242454      ivector.) For these reasons, these functions are generally less
    243455      safe and more flexible than their ANSI counterparts.</para>
    244     </sect1>
    245 
    246     <sect1 id="Gray-Streams-Dictionary">
     456    </sect2>
     457
     458    <sect2 id="Gray-Streams-Dictionary">
    247459      <title>Gray Streams Dictionary</title>
    248460      <refentry id="f_stream-read-list">
     
    704916          <title>Examples</title>
    705917
    706 <programlisting format="linespecific">;;; Write the contents of a (SIMPLE-ARRAY(UNSIGNED-BYTE 16) 3)
    707 ;;; to a character file stream. Read back the characters.
    708 (let* ((a (make-array 3
    709                      :element-type '(unsigned-byte 16)
    710                      :initial-contents '(26725 27756 28449))))
    711   (with-open-file (s "junk"
    712                    :element-type 'character
    713                    :direction :io
    714                    :if-does-not-exist :create
    715                    :if-exists :supersede)
    716     ;; Write six octets (three elements).
    717     (stream-write-ivector s a 0 6)
    718     ;; Rewind, then read a line
    719     (file-position s 0)
    720     (read-line s)))
    721 
    722 ;;; Write a vector of DOUBLE-FLOATs. Note that (to maintain
    723 ;;; alignment) there are 4 octets of padding before the 0th
    724 ;;; element of a (VECTOR DOUBLE-FLOAT).
    725 ;;; (Note that (= (- arch::misc-dfloat-offset
    726 ;;;                  arch::misc-data-offset) 4))
    727 (defun write-double-float-vector
    728   (stream vector &#38;key (start 0) (end (length vector)))
    729   (check-type vector (vector double-float))
    730   (let* ((start-octet (+ (* start 8)
    731                          (- arch::misc-dfloat-offset
    732                          arch::misc-data-offset)))
    733          (num-octets (* 8 (- end start))))
    734     (stream-write-ivector stream vector start-octet num-octets)))</programlisting>
     918          <programlisting format="linespecific">;;; Write the contents of a (SIMPLE-ARRAY(UNSIGNED-BYTE 16) 3)
     919          ;;; to a character file stream. Read back the characters.
     920          (let* ((a (make-array 3
     921          :element-type '(unsigned-byte 16)
     922          :initial-contents '(26725 27756 28449))))
     923          (with-open-file (s "junk"
     924          :element-type 'character
     925          :direction :io
     926          :if-does-not-exist :create
     927          :if-exists :supersede)
     928          ;; Write six octets (three elements).
     929          (stream-write-ivector s a 0 6)
     930          ;; Rewind, then read a line
     931          (file-position s 0)
     932          (read-line s)))
     933
     934          ;;; Write a vector of DOUBLE-FLOATs. Note that (to maintain
     935          ;;; alignment) there are 4 octets of padding before the 0th
     936          ;;; element of a (VECTOR DOUBLE-FLOAT).
     937          ;;; (Note that (= (- arch::misc-dfloat-offset
     938          ;;;                  arch::misc-data-offset) 4))
     939          (defun write-double-float-vector
     940          (stream vector &#38;key (start 0) (end (length vector)))
     941          (check-type vector (vector double-float))
     942          (let* ((start-octet (+ (* start 8)
     943          (- arch::misc-dfloat-offset
     944          arch::misc-data-offset)))
     945          (num-octets (* 8 (- end start))))
     946          (stream-write-ivector stream vector start-octet num-octets)))</programlisting>
    735947        </refsect1>
    736948      </refentry>
    737     </sect1>
    738   </chapter>
     949    </sect2>
     950  </sect1>
     951</chapter>
  • trunk/source/doc/src/threads.xml

    r8673 r8820  
    11<?xml version="1.0" encoding="utf-8"?>
    2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
     2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
    33<!ENTITY rest "<varname>&amp;rest</varname>">
    44<!ENTITY key "<varname>&amp;key</varname>">
     
    77<!ENTITY aux "<varname>&amp;aux</varname>">
    88<!ENTITY allow-other-keys "<varname>&amp;allow-other-keys</varname>">
    9 <!ENTITY CCL "<literal>CCL</literal>">
     9<!ENTITY CCL "Clozure CL">
    1010]>
    1111
     
    29462946              <term>timeout</term>
    29472947              <listitem>
    2948                 <para>either NIL, or a time interval in seconds.  May be any
    2949                 non-negative real number the <function>floor</function> of
    2950                 which fits in 32 bits.  The default is NIL.</para>
     2948                <para>either NIL or a time interval in milliseconds.  Must be a non-negative integer.  The default is NIL.</para>
    29512949              </listitem>
    29522950            </varlistentry>
     
    30093007
    30103008        <refsynopsisdiv>
    3011           <synopsis><function>process-output-wait</function> fd</synopsis>
     3009          <synopsis><function>process-output-wait</function>
     3010          fd  &optional; timeout</synopsis>
    30123011        </refsynopsisdiv>
    30133012
     
    30243023              </listitem>
    30253024            </varlistentry>
     3025            <varlistentry>
     3026              <term>timeout</term>
     3027              <listitem>
     3028                <para>either NIL or a time interval in milliseconds.  Must be a non-negative integer.  The default is NIL.</para>
     3029              </listitem>
     3030            </varlistentry>
    30263031          </variablelist>
    30273032        </refsect1>
     
    30303035          <title>Description</title>
    30313036
    3032           <para>Wait until output is possible on <varname>fd</varname>.
     3037          <para>Wait until output is possible on <varname>fd</varname> or until <varname>timeout</varname>, if
     3038          it is not NIL, has been exceeded.
    30333039          This uses the <function>select()</function> system call, and is
    30343040          generally a fairly
  • trunk/source/doc/src/using.xml

    r8795 r8820  
    11<?xml version="1.0" encoding="utf-8"?>
    2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
    3           "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"[
     2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
    43          <!ENTITY rest "<varname>&amp;rest</varname>">
    54          <!ENTITY key "<varname>&amp;key</varname>">
     
    87          <!ENTITY aux "<varname>&amp;aux</varname>">
    98          <!ENTITY allow-other-keys "<varname>&amp;allow-other-keys</varname>">
    10           <!ENTITY CCL "<literal>CCL</literal>">
     9          <!ENTITY CCL "Clozure CL">
    1110          ]>
    1211
     
    1716    <para>The Common Lisp standard allows considerable latitude in the
    1817      details of an implementation, and each particular Common Lisp
    19       system has some idiosyncracies. This chapter describes ordinary
     18      system has some idiosyncracies. This chapter describes ordinary <code>foo</code>
    2019      user-level features of &CCL;, including features that may be
    2120      part of the Common Lisp standard, but which may have quirks or
    2221      details in the &CCL; implementation that are not described by
    2322      the standard.</para>
     23
    2424  </sect1>
    2525
    26   <sect1 id="Trace"><title>Trace</title>
    27 
    28     <para>
    29       &CCL;'s tracing facility is invoked by an extended version of the Common Lisp
    30       <varname>trace</varname> macro.  Extensions allow tracing of methods, as well as finer control
    31       over tracing actions.
    32     </para>
    33 
     26  <sect1 id="m_trace0"><title>Trace</title>
     27
     28  <para>
     29    &CCL;'s tracing facility is invoked by an extended version of the Common Lisp
     30    <varname>trace</varname> macro.  Extensions allow tracing of methods, as well as finer control
     31    over tracing actions.
     32  </para>
    3433
    3534    <para>
     
    479478  </sect1>
    480479
    481   <sect1 id="Strings-and-Pathanmes"><title>Strings and Pathnames</title>
    482     <sect2>
    483       <title>OS X (Darwin)</title>
    484 
    485       <para>Clozure CL assumes that pathname strings are decomposed UTF-8.</para>
    486     </sect2>
    487     <sect2>
    488       <title>Linux</title>
    489 
    490       <para>Pathname strings are treated as null-terminated strings
    491         encoded according to the current locale.</para>
    492     </sect2>
    493     <sect2>
    494       <title>FreeBSD</title>
    495 
    496       <para>Pathname strings are treated as null-terminated strings
    497         encoded according to the current locale; a future release may
    498         change this convention to use UTF-8.</para>
    499     </sect2>
     480  <sect1 id="Unicode"><title>Unicode</title>
     481
     482  <para>All characters and strings in Clozure CL fully support Unicode
     483  by using UTF-32. There is only one <literal>CHARACTER</literal> type
     484  and one <literal>STRING</literal> in Clozure CL.  There has been a
     485  lot of discussion about this decision which can be found by
     486  searching the openmcl-devel archives at <ulink
     487  url="http://clozure.com/pipermail/openmcl-devel/"/>.  Suffice it to
     488  say that we decided that the simplicity and speed advantages of
     489  UTF-32 outweigh the space disadvantage.</para>
     490
     491  <sect2><title>Characters</title>
     492  <para>There is one <literal>CHARACTER</literal> type in Clozure CL.
     493  All <literal>CHARACTER</literal>s are <literal>BASE-CHAR</literal>s.
     494  <varname>CHAR-CODE-LIMIT</varname> is now
     495  <literal>#x110000</literal>, which means that all Unicode characters
     496  can be directly represented.  As of Unicode 5.0, only about 100,000
     497  of 1,114,112 possible <literal>CHAR-CODE</literal>s are actually
     498  defined. The function <function>CODE-CHAR</function> knows that
     499  certain ranges of code values (notably
     500  <literal>#xd800</literal>-<literal>#xddff</literal>) will never be
     501  valid character codes and will return <literal>NIL</literal> for
     502  arguments in that range, but may return a non-<literal>NIL</literal>
     503  value (an undefined/non-standard <literal>CHARACTER</literal>
     504  object) for other unassigned code values.</para>
     505  <para>Clozure CL supports character names of the form
     506  <literal>u+xxxx</literal> - where <literal>x</literal> is a sequence
     507  of one or more hex digits.  The value of the hex digits denotes the
     508  code of the character.  The <literal>+</literal> character is
     509  optional, so <literal>#\u+0020</literal>,
     510  <literal>#\U0020</literal>, and <literal>#\U+20</literal> all refer
     511  to the <literal>#\Space</literal> character.</para>
     512  <para>Characters with codes in the range
     513  <literal>#xa0</literal>-<literal>#x7ff</literal> also have symbolic
     514  names These are the names from the Unicode standard with spaces
     515  replaced by underscores.  So
     516  <literal>#\Greek_Capital_Letter_Epsilon</literal> can be used to
     517  refer to the character whose <function>CHAR-CODE</function> is
     518  <literal>#x395</literal>.</para>
     519  </sect2>
     520
     521  <sect2 id="External-Formats"><title>External Formats</title>
     522  <para><function>OPEN</function>, <function>LOAD</function>, and
     523  <function>COMPILE-FILE</function> all take an
     524  <literal>:EXTERNAL-FORMAT</literal> keyword argument.  The value of
     525  <literal>:EXTERNAL-FORMAT</literal> can be
     526  <literal>:DEFAULT</literal> (the default value), a line termination
     527  keyword <xref linkend="Line-Termination-Keywords"/><xref
     528  linkend="k_external-format"/>, a character encoding keyword <xref
     529  linkend="Character-Encodings"/>, a plist with keys:
     530  <literal>:CHARACTER-ENCODING</literal> and
     531  <literal>:LINE-TERMINATION</literal>, or an external-format object
     532  created using <function>CCL::MAKE-EXTERNAL-FORMAT</function>.  If
     533  <literal>:DEFAULT</literal> is specified, then the value of
     534  <varname>CCL:*DEFAULT-EXTERNAL-FORMAT*</varname> is used.  If no
     535  line-termination is specified, then the value of
     536  <varname>CCL:*DEFAULT-LINE-TERMINATION*</varname> is used.  If no
     537  character encoding is specified, then
     538  <varname>CCL:*DEFAULT-FILE-CHARACTER-ENCODING*</varname> is used for
     539  file streams and
     540  <varname>CCL:*DEFAULT-SOCKET-CHARACTER-ENCODING*</varname> is used
     541  for socket streams.  The default, default character encoding is
     542  <literal>NIL</literal> which is a synonym for <literal>:ISO-8859-1</literal>
     543  </para>
     544  </sect2>
     545
     546  <sect2 id="Line-Termination-Keywords"><title>Line Termination Keywords</title>
     547  <para>Line termination keywords indicate which characters are used
     548  to indicate the end of a line.  On input, the external line
     549  termination characters are replaced by <literal>#\Newline</literal>
     550  and on output, <literal>#\Newline</literal>s are converted to the
     551  external line termination characters.</para>
     552  <table id="Line-Termination-Table" frame='all'><title>Line Termination Keywords</title>
     553  <tgroup cols='2' align='left' colsep='1' rowsep='1'>
     554    <thead>
     555      <row>
     556        <entry>keyword</entry>
     557        <entry>character(s)</entry>
     558      </row>
     559    </thead>
     560    <tbody>
     561      <row>
     562        <entry><literal>:UNIX</literal></entry>
     563        <entry><literal>#\Linefeed</literal></entry>
     564      </row>
     565      <row>
     566        <entry><literal>:MACOS</literal></entry>
     567        <entry><literal>#\Return</literal></entry>
     568      </row>
     569      <row>
     570        <entry><literal>:CR</literal></entry>
     571        <entry><literal>#\Return</literal></entry>
     572      </row>
     573      <row>
     574        <entry><literal>:CRLF</literal></entry>
     575        <entry><literal>#\Return #\Linefeed</literal></entry>
     576      </row>
     577      <row>
     578        <entry><literal>:CP/M</literal></entry>
     579        <entry><literal>#\Return #\Linefeed</literal></entry>
     580      </row>
     581      <row>
     582        <entry><literal>:MSDOS</literal></entry>
     583        <entry><literal>#\Return #\Linefeed</literal></entry>
     584      </row>
     585      <row>
     586        <entry><literal>:DOS</literal></entry>
     587        <entry><literal>#\Return #\Linefeed</literal></entry>
     588      </row>
     589      <row>
     590        <entry><literal>:WINDOWS</literal></entry>
     591        <entry><literal>#\Return #\Linefeed</literal></entry>
     592      </row>
     593      <row>
     594        <entry><literal>:INFERRED</literal></entry>
     595        <entry>see below</entry>
     596      </row>
     597      <row>
     598        <entry><literal>:UNICODE</literal></entry>
     599        <entry><literal>#\Line_Separator</literal></entry>
     600      </row>
     601    </tbody>
     602  </tgroup>
     603  </table>
     604  <para><literal>:INFERRED</literal> means try to guess a stream's
     605  line-termination conventions.  It is only useful for
     606  <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>
     607  </sect2>
     608 
     609
     610  <sect2 id="Character-Encodings"><title>Character Encodings</title>
     611  <para>Internally, all characters and strings in Clozure CL are in
     612  UTF-32.  Externally, files or socket streams may encode characters
     613  in a wide variety of ways.  The International Organization for
     614  Standardization, widely known as ISO defines a number of these
     615  character encodings.  Clozure CL implements a number of these
     616  encodings as detailed below.  These encodings are part of the
     617  specification of external formats (see <xref
     618  linkend="External-Formats"/>.  When reading from a stream,
     619  characters are converted from the specified external character
     620  encoding to UTF-32.  When writing to a stream, characters are
     621  converted from UTF-32 to the specified character encoding.  Here is
     622  a list of character encoding keywords used to specify a standard
     623  character encoding.</para>
     624  <variablelist>
     625    <varlistentry><term><literal>:ISO-8859-1</literal></term>
     626       <listitem><para>An 8-bit, fixed-width character encoding in
     627       which all character codes map to their Unicode
     628       equivalents. Intended to support most characters used in most
     629       Western European languages.</para></listitem>
     630     </varlistentry>
     631    <varlistentry><term><literal>:ISO-8859-2</literal></term>
     632       <listitem><para>An 8-bit, fixed-width character encoding in
     633       which codes #x00-#x9f map to their Unicode equivalents and
     634       other codes map to other Unicode character values.  Intended to
     635       provide most characters found in most languages used in
     636       Central/Eastern Europe.</para></listitem>
     637     </varlistentry>
     638    <varlistentry><term><literal>:ISO-8859-3</literal></term>
     639       <listitem><para>An 8-bit, fixed-width character encoding in
     640       which codes #x00-#x9f map to their Unicode equivalents and
     641       other codes map to other Unicode character values.  Intended to
     642       provide most characters found in most languages used in
     643       Southern Europe.</para></listitem>
     644     </varlistentry>
     645    <varlistentry><term><literal>:ISO-8859-4</literal></term>
     646       <listitem><para>An 8-bit, fixed-width character encoding in
     647       which codes #x00-#x9f map to their Unicode equivalents and
     648       other codes map to other Unicode character values.  Intended to
     649       provide most characters found in most languages used in
     650       Northern Europe.</para></listitem>
     651     </varlistentry>
     652    <varlistentry><term><literal>:ISO-8859-5</literal></term>
     653       <listitem><para>An 8-bit, fixed-width character encoding in
     654       which codes #x00-#x9f map to their Unicode equivalents and
     655       other codes map to other Unicode character values.  Intended to
     656       provide most characters found in the Cyrillic
     657       alphabet.</para></listitem>
     658     </varlistentry>
     659    <varlistentry><term><literal>:ISO-8859-6</literal></term>
     660       <listitem><para>An 8-bit, fixed-width character encoding in
     661       which codes #x00-#x9f map to their Unicode equivalents and
     662       other codes map to other Unicode character values.  Intended to
     663       provide most characters found in the Arabic
     664       alphabet.</para></listitem>
     665     </varlistentry>
     666    <varlistentry><term><literal>:ISO-8859-7</literal></term>
     667       <listitem><para>An 8-bit, fixed-width character encoding in
     668       which codes #x00-#x9f map to their Unicode equivalents and
     669       other codes map to other Unicode character values.  Intended to
     670       provide most characters found in the Greek
     671       alphabet.</para></listitem>
     672     </varlistentry>
     673    <varlistentry><term><literal>:ISO-8859-8</literal></term>
     674       <listitem><para>An 8-bit, fixed-width character encoding in
     675       which codes #x00-#x9f map to their Unicode equivalents and
     676       other codes map to other Unicode character values.  Intended to
     677       provide most characters found in the Hebrew
     678       alphabet.</para></listitem>
     679     </varlistentry>
     680    <varlistentry><term><literal>:ISO-8859-9</literal></term>
     681       <listitem><para>An 8-bit, fixed-width character encoding in
     682       which codes #x00-#xcf map to their Unicode equivalents and
     683       other codes map to other Unicode character values.  Intended to
     684       provide most characters found in the Turkish
     685       alphabet.</para></listitem>
     686     </varlistentry>
     687    <varlistentry><term><literal>:ISO-8859-10</literal></term>
     688       <listitem><para>An 8-bit, fixed-width character encoding in
     689       which codes #x00-#x9f map to their Unicode equivalents and
     690       other codes map to other Unicode character values.  Intended to
     691       provide most characters found in Nordic
     692       alphabets.</para></listitem>
     693     </varlistentry>
     694    <varlistentry><term><literal>:ISO-8859-11</literal></term>
     695       <listitem><para>An 8-bit, fixed-width character encoding in
     696       which codes #x00-#x9f map to their Unicode equivalents and
     697       other codes map to other Unicode character values.  Intended to
     698       provide most characters found the Thai
     699       alphabet.</para></listitem>
     700     </varlistentry>
     701    <varlistentry><term><literal>:ISO-8859-13</literal></term>
     702       <listitem><para>An 8-bit, fixed-width character encoding in
     703       which codes #x00-#x9f map to their Unicode equivalents and
     704       other codes map to other Unicode character values.  Intended to
     705       provide most characters found in Baltic
     706       alphabets.</para></listitem>
     707     </varlistentry>
     708    <varlistentry><term><literal>:ISO-8859-14</literal></term>
     709       <listitem><para>An 8-bit, fixed-width character encoding in
     710       which codes #x00-#x9f map to their Unicode equivalents and
     711       other codes map to other Unicode character values.  Intended to
     712       provide most characters found in Celtic
     713       languages.</para></listitem>
     714     </varlistentry>
     715    <varlistentry><term><literal>:ISO-8859-15</literal></term>
     716       <listitem><para>An 8-bit, fixed-width character encoding in
     717       which codes #x00-#x9f map to their Unicode equivalents and
     718       other codes map to other Unicode character values.  Intended to
     719       provide most characters found in Western European languages
     720       (including the Euro sign and some other characters missing from
     721       ISO-8859-1.</para></listitem>
     722     </varlistentry>
     723    <varlistentry><term><literal>:ISO-8859-16</literal></term>
     724       <listitem><para>An 8-bit, fixed-width character encoding in
     725       which codes #x00-#x9f map to their Unicode equivalents and
     726       other codes map to other Unicode character values.  Intended to
     727       provide most characters found in Southeast European
     728       languages.</para></listitem>
     729     </varlistentry>
     730    <varlistentry><term><literal>:MACINTOSH</literal></term>
     731       <listitem><para>An 8-bit, fixed-width character encoding in
     732       which codes #x00-#x7f map to their Unicode equivalents and
     733       other codes map to other Unicode character values.
     734       Traditionally used on Classic MacOS to encode characters used
     735       in western languages.</para></listitem>
     736     </varlistentry>
     737    <varlistentry><term><literal>:UCS-2</literal></term>
     738       <listitem><para>A 16-bit, fixed-length encoding in which
     739       characters with CHAR-CODEs less than #x10000 can be encoded in
     740       a single 16-bit word.  The endianness of the encoded data is
     741       indicated by the endianness of a byte-order-mark character
     742       (#u+feff) prepended to the data; in the absence of such a
     743       character on input, the data is assumed to be in big-endian
     744       order.</para></listitem>
     745     </varlistentry>
     746    <varlistentry><term><literal>:UCS-2BE</literal></term>
     747       <listitem><para>A 16-bit, fixed-length encoding in which
     748       characters with CHAR-CODEs less than #x10000 can be encoded in
     749       a single 16-bit big-endian word. The encoded data is implicitly
     750       big-endian; byte-order-mark characters are not interpreted on
     751       input or prepended to output.</para></listitem>
     752     </varlistentry>
     753    <varlistentry><term><literal>:UCS-2LE</literal></term>
     754       <listitem><para>A 16-bit, fixed-length encoding in which
     755       characters with CHAR-CODEs less than #x10000 can be encoded in
     756       a single 16-bit little-endian word. The encoded data is
     757       implicitly little-endian; byte-order-mark characters are not
     758       interpreted on input or prepended to output.</para></listitem>
     759     </varlistentry>
     760    <varlistentry><term><literal>:US-ASCII</literal></term>
     761       <listitem><para>An 7-bit, fixed-width character encoding in
     762       which all character codes map to their Unicode
     763       equivalents. </para></listitem>
     764     </varlistentry>
     765    <varlistentry><term><literal>:UTF-16</literal></term>
     766       <listitem><para>A 16-bit, variable-length encoding in which
     767       characters with CHAR-CODEs less than #x10000 can be encoded in
     768       a single 16-bit word and characters with larger codes can be
     769       encoded in a pair of 16-bit words.  The endianness of the
     770       encoded data is indicated by the endianness of a
     771       byte-order-mark character (#u+feff) prepended to the data; in
     772       the absence of such a character on input, the data is assumed
     773       to be in big-endian order. Output is written in native
     774       byte-order with a leading byte-order mark.</para></listitem>
     775     </varlistentry>
     776    <varlistentry><term><literal>:UTF-16BE</literal></term>
     777       <listitem><para>A 16-bit, variable-length encoding in which
     778       characters with CHAR-CODEs less than #x10000 can be encoded in
     779       a single 16-bit big-endian word and characters with larger
     780       codes can be encoded in a pair of 16-bit big-endian words.  The
     781       endianness of the encoded data is implicit in the encoding;
     782       byte-order-mark characters are not interpreted on input or
     783       prepended to output.</para></listitem>
     784     </varlistentry>
     785    <varlistentry><term><literal>:UTF-16LE</literal></term>
     786       <listitem><para>A 16-bit, variable-length encoding in which
     787       characters with CHAR-CODEs less than #x10000 can be encoded in
     788       a single 16-bit little-endian word and characters with larger
     789       codes can be encoded in a pair of 16-bit little-endian words.
     790       The endianness of the encoded data is implicit in the encoding;
     791       byte-order-mark characters are not interpreted on input or
     792       prepended to output.</para></listitem>
     793     </varlistentry>
     794    <varlistentry><term><literal>:UTF-32</literal></term>
     795       <listitem><para>A 32-bit, fixed-length encoding in which all
     796       Unicode characters can be encoded in a single 32-bit word.  The
     797       endianness of the encoded data is indicated by the endianness
     798       of a byte-order-mark character (#u+feff) prepended to the data;
     799       in the absence of such a character on input, input data is
     800       assumed to be in big-endian order.  Output is written in native
     801       byte order with a leading byte-order mark.</para></listitem>
     802     </varlistentry>
     803    <varlistentry><term><literal>:UTF-32BE</literal></term>
     804       <listitem><para>A 32-bit, fixed-length encoding in which all
     805       Unicode characters encoded in a single 32-bit word. The encoded
     806       data is implicitly big-endian; byte-order-mark characters are
     807       not interpreted on input or prepended to
     808       output.</para></listitem>
     809     </varlistentry>
     810    <varlistentry><term><literal>:UTF-8</literal></term>
     811       <listitem><para>An 8-bit, variable-length character encoding in
     812       which characters with CHAR-CODEs in the range #x00-#x7f can be
     813       encoded in a single octet; characters with larger code values
     814       can be encoded in 2 to 4 bytes.</para></listitem>
     815     </varlistentry>
     816    <varlistentry><term><literal>:UTF32LE</literal></term>
     817       <listitem><para>A 32-bit, fixed-length encoding in which all
     818       Unicode characters can encoded in a single 32-bit word. The
     819       encoded data is implicitly little-endian; byte-order-mark
     820       characters are not interpreted on input or prepended to
     821       output.</para></listitem>
     822     </varlistentry>
     823  </variablelist>
     824  </sect2>
     825  </sect1>
     826
     827  <sect1 id="Pathanmes"><title>Pathnames</title>
     828
     829  <sect2>
     830    <title>Pathname Expansion</title>
     831    <para>Leading tilde (~) characters in physical pathname namestrings
     832    are expanded in the way that most shells do:</para>
     833   
     834    <para><literal>"~user/..."</literal> can be used to refer to an absolute pathname rooted
     835    at the home directory of the user named "user".</para>
     836   
     837    <para><literal>"~/..."</literal> can be used to refer to an absolute pathname rooted at
     838    the home directory of the current user.</para>
     839  </sect2>
     840
     841  <sect2 id="Predefined-Logical-Hosts"><title>Predefined Logical Hosts</title>
     842
     843  <para>Clozure CL sets up logical pathname translations for logical hosts:  <literal>ccl</literal> and <literal>home</literal></para>
     844
     845  <indexterm><primary>CCL Logical Host</primary></indexterm>
     846  <para>The <literal>CCL</literal> logical host should point to the
     847  <literal>ccl</literal> directory.  It is used for a variety of
     848  purposes by Clozure CL including: locating Clozure CL source code,
     849  <literal>require</literal> and <literal>provide</literal>, accessing
     850  foreign function information, and the Clozure CL build process. It
     851  is set to the value of the environment variable
     852  <varname>CCL_DEFAULT_DIRECTORY</varname>, which is set by the
     853  openmcl shell script <xref linkend="The-openmcl-Shell-Script"/>.  If
     854  <varname>CCL_DEFAULT_DIRECTORY</varname> is not set, then it is set
     855  to the directory containing the current heap image.</para>
     856  </sect2>
     857 
     858 
     859  <sect2>
     860    <title>OS X (Darwin)</title>
     861   
     862    <para>Clozure CL assumes that pathname strings are decomposed UTF-8.</para>
     863  </sect2>
     864  <sect2>
     865    <title>Linux</title>
     866   
     867    <para>Pathname strings are treated as null-terminated strings
     868    encoded according to the current locale.</para>
     869  </sect2>
     870  <sect2>
     871    <title>FreeBSD</title>
     872   
     873    <para>Pathname strings are treated as null-terminated strings
     874    encoded according to the current locale; a future release may
     875    change this convention to use UTF-8.</para>
     876  </sect2>
    500877  </sect1>
    501878
  • trunk/source/doc/src/xsl/refentry.xsl

    r8555 r8820  
    4343            <xsl:call-template name="href.target"/>
    4444          </xsl:attribute>
    45           <xsl:call-template name="refentry.title"/>
    4645        </a>
     46        <strong>[<xsl:value-of select="refnamediv/refclass"/>]</strong><br/>
     47        <code><xsl:apply-templates select="refsynopsisdiv/synopsis/node()"/></code>
     48
    4749      </div>
    4850      <div class="refentrytitle">
     
    5052      </div>
    5153    </p>
     54    <p>
     55      <div>
     56        <xsl:apply-templates select="refsect1"/>
     57      </div>
     58    </p>
     59  </xsl:template>
    5260
    53     <xsl:choose>
    54       <xsl:when test="$onechunk != 0 and parent::*">
    55         <xsl:apply-imports/>
    56       </xsl:when>
    57       <xsl:otherwise>
    58         <xsl:call-template name="process-chunk-element"/>
    59       </xsl:otherwise>
    60     </xsl:choose>
    61   </xsl:template>
    6261
    6362  <xsl:template match="refentry" mode="xref-to">
  • trunk/source/doc/src/xsl/toc-at-end.xsl

    r8555 r8820  
    5858      </xsl:variable>
    5959
    60       <xsl:apply-templates/>
    61       <xsl:call-template name="process.footnotes"/>
    62 
    6360      <xsl:if test="contains($toc.params, 'toc')">
    6461        <xsl:call-template name="component.toc.separator"/>
     
    6764        </xsl:call-template>
    6865      </xsl:if>
     66
     67      <xsl:apply-templates/>
     68      <xsl:call-template name="process.footnotes"/>
     69
    6970    </div>
    7071  </xsl:template>
Note: See TracChangeset for help on using the changeset viewer.