Changeset 14678


Ignore:
Timestamp:
Mar 17, 2011, 12:16:07 PM (9 years ago)
Author:
gb
Message:

Describe the :USE-STANDARD-INITIAL-BINDINGS arg to MAKE-PROCESS as
being deprecated.

Clarify that the :INFERRED (pseudo-)line-termination keyword can
recognize CRLF as well as CR and LF. Consolidate and edit the
stuff that talks about :EXTERNAL-FORMAT and related issues.

Location:
trunk/source/doc/src
Files:
3 edited

Legend:

Unmodified
Added
Removed
  • trunk/source/doc/src/platform-notes.xml

    r13573 r14678  
    11461146                characters until EOF, a #\NewLine is read, or a character EQL to the
    11471147                value of *alternate-line-terminator* is read. In &CCL; for Darwin, the
    1148                 value of this variable is initially #\Return ; in &CCL; for LinuxPPC,
     1148                value of this variable is initially #\Return ; in &CCL; for other OSes,
    11491149                it&#39;s initially NIL.</para>
    11501150             
     
    11641164          </refentry>
    11651165
    1166           <refentry id="k_external-format">
    1167             <indexterm zone="k_external-format">
    1168               <primary>:external-format</primary>
    1169             </indexterm>
    1170 
    1171             <refnamediv>
    1172               <refname>:EXTERNAL-FORMAT</refname>
    1173               <refpurpose></refpurpose>
    1174               <refclass>Keyword Argument</refclass>
    1175             </refnamediv>
    1176 
    1177             <refsect1>
    1178               <title>Description</title>
    1179 
    1180               <para>Per ANSI CL, &CCL; supports the :EXTERNAL-FORMAT keyword
    1181                 argument to the functions OPEN, LOAD, and COMPILE-FILE. This argument is
    1182                 intended to provide a standard way of providing implementation-dependent
    1183                 information about the format of files opened with an element-type of
    1184                 CHARACTER. This argument can meaningfully take on the values :DEFAULT
    1185                 (the default), :MACOS, :UNIX, or :INFERRED in &CCL;.</para>
    1186              
    1187               <para>When defaulted to or specified as :DEFAULT, the format of the file
    1188                 stream is determined by the value of the variable
    1189                 CCL:*DEFAULT-EXTERNAL-FORMAT*. See below.</para>
    1190              
    1191               <para>When specified as :UNIX, all characters are read from and written
    1192                 to files verbatim.</para>
    1193              
    1194               <para>When specified as :MACOS, all #\Return characters read from the
    1195                 file are immediately translated to #\Linefeed (#\Newline); all #\Newline
    1196                 (#\Linefeed) characters are written externally as #\Return characters.</para>
    1197              
    1198               <para>When specified as :INFERRED and the file is open for input, the
    1199                 first buffer-full of input data is examined; if a #\Return character
    1200                 appears in the buffer before the first #\Linefeed, the file stream&#39;s
    1201                 external-format is set to :MACOS; otherwise, it is set to :UNIX.</para>
    1202              
    1203               <para>All other values of :EXTERNAL-FORMAT - and any combinations that
    1204                 don&#39;t make sense, such as trying to infer the format of a
    1205                 newly-created output file stream - are treated as if :UNIX was
    1206                 specified. As mentioned above, the :EXTERNAL-FORMAT argument doesn&#39;t
    1207                 apply to binary file streams.</para>
    1208              
    1209               <para>The translation performed when :MACOS is specified or inferred has
    1210                 a somewhat greater chance of doing the right thing than the
    1211                 *alternate-line-terminator* mechanism does; it probably has a somewhat
    1212                 greater chance of doing the wrong thing, as well.</para>
    1213             </refsect1>
    1214           </refentry>
    1215 
    1216           <refentry id="v_default-external-format">
    1217             <indexterm zone="v_default-external-format">
    1218               <primary>*default-external-format*</primary>
    1219             </indexterm>
    1220            
    1221             <refnamediv>
    1222               <refname>CCL:*DEFAULT-EXTERNAL-FORMAT*</refname>
    1223               <refpurpose></refpurpose>
    1224               <refclass>Variable</refclass>
    1225             </refnamediv>
    1226 
    1227             <refsect1>
    1228               <title>Description</title>
    1229 
    1230               <para>The value of this variable is used when :EXTERNAL-FORMAT is
    1231                 unspecified or specified as :DEFAULT. It can meaningfully be given any
    1232                 of the values :UNIX, :MACOS, or :INFERRED, each of which is interpreted
    1233                 as described above.</para>
    1234              
    1235               <para>Because there&#39;s some risk that unsolicited newline translation
    1236                 could have undesirable consequences, the initial value of this variable
    1237                 in &CCL; is :UNIX.</para>
    1238             </refsect1>
    1239           </refentry>
     1166
     1167
    12401168
    12411169          <refentry id="c_ns-lisp-string">
  • trunk/source/doc/src/threads.xml

    r14528 r14678  
    751751                        DEF-STANDARD-INITIAL-BINDING.  "standard" initial bindings
    752752                        are put into effect before any bindings specified by
    753                         :initial-bindings are.  The default is t.</para>
     753                        :initial-bindings are.  The default is t.
     754
     755                       <emphasis role="strong">This option is deprecated: the correct
     756                      behavior of many &CCL; components depends on thread-local
     757                      bindings of many special variables being in effect.</emphasis></para>
    754758                </listitem>
    755759              </varlistentry>
  • trunk/source/doc/src/using.xml

    r14634 r14678  
    805805    never both.</para>
    806806
    807     <para>EXTERNAL-FORMATs are objects (structures) with three
     807    <para>EXTERNAL-FORMATs are objects (structures) with two
    808808    read-only fields that can be accessed via the functions:
    809     <function>EXTERNAL-FORMAT-DOMAIN</function>,
    810809    <function>EXTERNAL-FORMAT-LINE-TERMINATION</function> and
    811810    <function>EXTERNAL-FORMAT-CHARACTER-ENCODING</function>.</para>
    812811
    813812 
     813    <refentry id="v_default-external-format">
     814        <indexterm zone="v_default-external-format">
     815          <primary>*default-external-format*</primary>
     816        </indexterm>
     817           
     818        <refnamediv>
     819          <refname>CCL:*DEFAULT-EXTERNAL-FORMAT*</refname>
     820          <refpurpose></refpurpose>
     821          <refclass>Variable</refclass>
     822        </refnamediv>
     823
     824        <refsect1>
     825          <title>Description</title>
     826
     827          <para>The value of this variable is used when :EXTERNAL-FORMAT is
     828                unspecified or specified as :DEFAULT. It can
     829                meaningfully be given any value that can be used as an
     830                external-format (except for the value :DEFAULT.)
     831              </para>
     832          <para>The initial value of this variable
     833                in &CCL; is <literal>:UNIX</literal>, which is equivalent to
     834                <literal>(:LINE-TERMINATION :UNIX)</literal>, among other
     835                things.  </para>
     836        </refsect1>
     837    </refentry>
     838
     839    <refentry id="v_default-line-termination">
     840        <indexterm zone="v_default-line-termination">
     841          <primary>*default-line-termination*</primary>
     842        </indexterm>
     843           
     844        <refnamediv>
     845          <refname>CCL:*DEFAULT-LINE-TERMINATION*</refname>
     846          <refpurpose></refpurpose>
     847          <refclass>Variable</refclass>
     848        </refnamediv>
     849
     850        <refsect1>
     851          <title>Description</title>
     852
     853          <para>The value of this variable is used when an external-format
     854                doesn't specify a line-termination convention (or specifies
     855                it as :DEFAULT.) It can meaningfully be given any value
     856                that can be used as a line termination keyword
     857                (see <xref linkend="Line-Termination-Keywords"/>).
     858              </para>
     859          <para>The initial value of this variable
     860                in &CCL; is <literal>:UNIX</literal>.
     861          </para>
     862        </refsect1>
     863    </refentry>
     864
    814865    <refentry id="f_make-external-format">
    815866      <indexterm zone="f_make-external-format">
     
    9691020  and if a <literal>#\Return</literal> character occurs before any
    9701021  <literal>#\Linefeed</literal> character, then the line termination
    971   type is set to <literal>:MACOS</literal>, otherwise it is set to
    972   <literal>:UNIX</literal>.</para>
     1022  type is set to <literal>:WINDOWS</literal> if that
     1023  <literal>#\Return</literal> character is immediately followed by a
     1024  <literal>#\Linefeed</literal> character and to <literal>:MACOS</literal>
     1025  otherwise.  If a <literal>#\Return</literal> character isn't found in
     1026  the buffer or if <literal>#\Return</literal> is preceded by
     1027  <literal>#\Linefeed</literal>, the file's line terminationt type
     1028  is set to <literal>:UNIX</literal>.</para>
    9731029  </sect2>
    9741030 
Note: See TracChangeset for help on using the changeset viewer.