Diff of /internals.xmlf [b20a97] .. [d0e0b7] Maximize Restore

  Switch to side-by-side view

--- a/internals.xmlf
+++ b/internals.xmlf
@@ -1,5 +1,9 @@
-<?xml version="1.0"?><!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
-<book lang="en"><part id="part.internals"><title>Internals</title>
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE book [
+<!ENTITY % eclent SYSTEM "ecl.ent">
+%eclent;
+]>
+<book xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en"><part xml:id="part.internals"><title>Internals</title>
 <partintro>
  <para>&ECL; is an implementation of the Common-Lisp language that is based on a kernel
  written in C plus a set of libraries written in Common-Lisp. The kernel includes a
@@ -27,12 +31,12 @@
  efficiency.</para>
 </partintro>
 
-<chapter id="Building-programs">
+<chapter xml:id="Building-programs">
  <title>Building programs</title>
  <para>In this section we describe how you can use &ECL; to build programs and
  loadable extensions that you can later on distribute to other people.</para>
 
- <section id="Internals-What-can-ECL-do-">
+ <section xml:id="Internals-What-can-ECL-do-">
   <title>What can &ECL; do?</title>
   <para>Some day for some reasons you will be in the need to distribute code that
   has been developed using &ECL;. In the following sections we will describe
@@ -102,7 +106,7 @@
   <!--  -->
  </section>
 
- <section id="Internals-Compiling-files">
+ <section xml:id="Internals-Compiling-files">
   <title>Compiling files</title>
   <para>&ECL; supports two types of compilation. One is bytecodes compilation. This
   process is performed on-the-fly, as you load source files with lisp code. This
@@ -137,7 +141,7 @@
   <!--  -->
  </section>
 
- <section id="Internals-Building-standalone-executables">
+ <section xml:id="Internals-Building-standalone-executables">
   <title>Building standalone executables</title>
   <para>To build an executable you need a working &ECL; image with the
   compiler. The function to build customized images is
@@ -145,7 +149,7 @@
   follows. Care should be taken that <replaceable>image-name</replaceable> differs from any
   filename in <replaceable>lisp-files</replaceable>.</para>
   <blockquote>
-   <screen><indexterm role="fn"><primary>c:build-program</primary></indexterm>&mdash; Function: <function>c:build-program</function> <varname>{</varname><varname>image-name</varname> <varname>&amp;key</varname> <varname>lisp-files</varname> <varname>ld-flags</varname> <varname>prologue-code</varname> <varname>epilogue-code</varname><varname>}</varname></screen>
+   <screen><indexterm role="fn"><primary>c:build-program</primary></indexterm>&#151; Function: <function>c:build-program</function> <varname>{</varname><varname>image-name</varname> <varname>&amp;key</varname> <varname>lisp-files</varname> <varname>ld-flags</varname> <varname>prologue-code</varname> <varname>epilogue-code</varname><varname>}</varname></screen>
    <para>This function builds a lisp image up from the core lisp library, plus all
    components listed in <replaceable>lisp-files</replaceable>.  Each component is either:</para>
    <itemizedlist mark="bullet">
@@ -172,14 +176,14 @@
   <!--  -->
  </section>
 
- <section id="Internals-Building-libraries">
+ <section xml:id="Internals-Building-libraries">
   <title>Building libraries</title>
   <para>To build a library you proceed more or less the same way as with standalone
   executables. There are two different functions depending on whether you need
   to build static or shared libraries.</para>
   <blockquote>
-   <screen><indexterm role="fn"><primary>c:build-static-library</primary></indexterm>&mdash; Function: <function>c:build-static-library</function> <varname>{</varname><varname>library-name</varname> <varname>&amp;key</varname> <varname>lisp-files</varname> <varname>prologue-code</varname> <varname>epilogue-code</varname> <varname>init-name</varname><varname>}</varname></screen>
-   <screen><indexterm role="fn"><primary>c:build-shared-library</primary></indexterm>&mdash; Function: <function>c:build-shared-library</function> <varname>{</varname><varname>library-name</varname> <varname>&amp;key</varname> <varname>lisp-files</varname> <varname>prologue-code</varname> <varname>epilogue-code</varname> <varname>ld-flags</varname> <varname>init-name</varname><varname>}</varname></screen>
+   <screen><indexterm role="fn"><primary>c:build-static-library</primary></indexterm>&#151; Function: <function>c:build-static-library</function> <varname>{</varname><varname>library-name</varname> <varname>&amp;key</varname> <varname>lisp-files</varname> <varname>prologue-code</varname> <varname>epilogue-code</varname> <varname>init-name</varname><varname>}</varname></screen>
+   <screen><indexterm role="fn"><primary>c:build-shared-library</primary></indexterm>&#151; Function: <function>c:build-shared-library</function> <varname>{</varname><varname>library-name</varname> <varname>&amp;key</varname> <varname>lisp-files</varname> <varname>prologue-code</varname> <varname>epilogue-code</varname> <varname>ld-flags</varname> <varname>init-name</varname><varname>}</varname></screen>
    <para>This function builds a library file up from the object files listed in
    <replaceable>lisp-files</replaceable>. Each of the arguments to <replaceable>lisp-file</replaceable> must name a single
    object file produced with <literal>compile-file</literal>.</para>
@@ -207,10 +211,10 @@
   <!--  -->
  </section>
 
- <section id="Internals-File-names">
+ <section xml:id="Internals-File-names">
   <title>File names</title>
   <blockquote>
-   <screen><indexterm role="fn"><primary>compile-file-pathname</primary></indexterm>&mdash; Function: <function>compile-file-pathname</function> <varname>{</varname><varname>filename-base</varname> <varname>&amp;key</varname> <varname>output-file</varname> <varname>type</varname><varname>}</varname></screen>
+   <screen><indexterm role="fn"><primary>compile-file-pathname</primary></indexterm>&#151; Function: <function>compile-file-pathname</function> <varname>{</varname><varname>filename-base</varname> <varname>&amp;key</varname> <varname>output-file</varname> <varname>type</varname><varname>}</varname></screen>
    <para>When compiling lisp files, creating libraries, etc, a number of files are
    produced which are of interest for the user or programmer. However, the name
    of these files will change from system to system. The purpose of the function
@@ -267,7 +271,7 @@
   <!--  -->
  </section>
 
- <section id="Internals-Compiler-examples">
+ <section xml:id="Internals-Compiler-examples">
   <title>Compiler examples</title>
   <section>
    <title>The <filename>hello.lisp</filename> file</title>
@@ -317,7 +321,7 @@
     ;;; End of Pass 1.
     ;;; Calling the C compiler...
     ;;; Invoking external command: gcc -O2 -march=i686 -pipe -fomit-frame-pointer -fPIC -fstrict-aliasing -Dlinux -O "-I/usr/lib/ecl/" -w -c "hello.c" -o "hello.o"
-    ;;; Invoking external command: gcc -o "hello.fas" -L"/usr/lib/ecl/" "hello.o"  -Wl,&ndash;rpath,/usr/lib/ecl/ -shared   -lecl -lgmp -lgc -ldl -lm
+    ;;; Invoking external command: gcc -o "hello.fas" -L"/usr/lib/ecl/" "hello.o"  -Wl,&#x2013;rpath,/usr/lib/ecl/ -shared   -lecl -lgmp -lgc -ldl -lm
     ;;; OPTIMIZE levels: Safety=2, Space=0, Speed=3
     ;;; Finished compiling hello.lisp.
     #P"hello.fas"
@@ -352,7 +356,7 @@
    instruction.<screen>
    &gt; <lineannotation>(c:build-program "myecl" :lisp-files '("hello.o"))</lineannotation>
    ;;; Invoking external command: gcc -O2 -march=i686 -pipe -fomit-frame-pointer -fPIC -fstrict-aliasing -Dlinux -O "-I/usr/lib/ecl/" -w -c "myecl.c" -o "myecl.o"
-   ;;; Invoking external command: gcc -o "myecl" -L"/usr/lib/ecl/" "myecl.o" "hello.o"  -Wl,&ndash;rpath,/usr/lib/ecl/  -lecl -lgmp -lgc -ldl -lm
+   ;;; Invoking external command: gcc -o "myecl" -L"/usr/lib/ecl/" "myecl.o" "hello.o"  -Wl,&#x2013;rpath,/usr/lib/ecl/  -lecl -lgmp -lgc -ldl -lm
    #P"myecl"
    Top level.
    </screen>Now you can execute this program from your favorite shell.</para>
@@ -388,7 +392,7 @@
    instruction.<screen>
    &gt; (c:build-fasl "myecl" :lisp-files '("hello.o"))
    ;;; Invoking external command: gcc -O2 -march=i686 -pipe -fomit-frame-pointer -fPIC -fstrict-aliasing -Dlinux -O "-I/usr/lib/ecl/" -w -c "myecl.c" -o "myecl.o"
-   ;;; Invoking external command: gcc -o "libmyecl.so" -L"/usr/lib/ecl/" "myecl.o" "hello.o"  -Wl,&ndash;rpath,/usr/lib/ecl/ -shared   -lecl -lgmp -lgc -ldl -lm
+   ;;; Invoking external command: gcc -o "libmyecl.so" -L"/usr/lib/ecl/" "myecl.o" "hello.o"  -Wl,&#x2013;rpath,/usr/lib/ecl/ -shared   -lecl -lgmp -lgc -ldl -lm
    #P"libmyecl.so"
    </screen>Now you can load this extension from any &ECL; image, even those you produce
    with <literal>c:build-program</literal>.</para>
@@ -404,12 +408,12 @@
  </section>
 </chapter>
 
-<chapter id="Lisp-objects">
+<chapter xml:id="Lisp-objects">
  <title>Manipulating Lisp objects</title>
  <para>If you want to extend, fix or simply customize &ECL; for your own needs,
  you should understand how the implementation works.</para>
 
- <section id="Internals-Objects-representation">
+ <section xml:id="Internals-Objects-representation">
   <title>Objects representation</title>
   <para>In &ECL; a lisp object is represented by a type called <literal>cl_object</literal>. This
   type is a word which is long enough to host both an integer and a pointer. The
@@ -455,7 +459,7 @@
   <para>There is one important function which tells the type of an object, plus several
   macros which group several tests.</para>
   <blockquote>
-   <screen><indexterm role="tp"><primary>cl_object</primary></indexterm>&mdash; C type: <structname>cl_object</structname></screen>
+   <screen><indexterm role="tp"><primary>cl_object</primary></indexterm>&#151; C type: <structname>cl_object</structname></screen>
    <para>This is the type of a lisp object. For your C/C++ program, a <literal>cl_object</literal>
    can be either a fixnum, a character, or a pointer to a union of structures (See
    the header <filename>object.h</filename>). The actual interpretation of that object can be
@@ -479,7 +483,7 @@
    how to use the different fields of a <literal>cl_object</literal> pointer.</para>
   </blockquote>
   <blockquote>
-   <screen><indexterm role="tp"><primary>cl_type</primary></indexterm>&mdash; C type: <structname>cl_type</structname></screen>
+   <screen><indexterm role="tp"><primary>cl_type</primary></indexterm>&#151; C type: <structname>cl_type</structname></screen>
    <para>Enumeration type which distinguishes the different types of lisp objects.  The
    most important values are t_cons, t_fixnum, t_character, t_bignum, t_ratio,
    t_singlefloat, t_doublefloat, t_complex, t_symbol, t_package, t_hashtable,
@@ -488,32 +492,32 @@
    t_thread.</para>
   </blockquote>
   <blockquote>
-   <screen><indexterm role="fn"><primary>type_of</primary></indexterm>&mdash; Function: <returnvalue>cl_type</returnvalue> <function>type_of</function> (<type>cl_object</type> <varname>O</varname>)</screen>
+   <screen><indexterm role="fn"><primary>type_of</primary></indexterm>&#151; Function: <returnvalue>cl_type</returnvalue> <function>type_of</function> (<type>cl_object</type> <varname>O</varname>)</screen>
    <para>If <replaceable>O</replaceable> is a valid lisp object, <literal>type_of(<replaceable>O</replaceable>)</literal> returns an integer
    denoting the type that lisp object. That integer is one of the values of the
    enumeration type <literal>cl_type</literal>.</para>
   </blockquote>
   <blockquote>
-   <screen><indexterm role="fn"><primary>FIXNUMP</primary></indexterm>&mdash; Function: <returnvalue>bool</returnvalue> <function>FIXNUMP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
-   <screen><indexterm role="fn"><primary>CHARACTERP</primary></indexterm>&mdash; Function: <returnvalue>bool</returnvalue> <function>CHARACTERP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
-   <screen><indexterm role="fn"><primary>CONSP</primary></indexterm>&mdash; Function: <returnvalue>bool</returnvalue> <function>CONSP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
-   <screen><indexterm role="fn"><primary>LISTP</primary></indexterm>&mdash; Function: <returnvalue>bool</returnvalue> <function>LISTP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
-   <screen><indexterm role="fn"><primary>ATOM</primary></indexterm>&mdash; Function: <returnvalue>bool</returnvalue> <function>ATOM</function> (<type>cl_object</type> <varname>o</varname>)</screen>
-   <screen><indexterm role="fn"><primary>ARRAYP</primary></indexterm>&mdash; Function: <returnvalue>bool</returnvalue> <function>ARRAYP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
-   <screen><indexterm role="fn"><primary>VECTORP</primary></indexterm>&mdash; Function: <returnvalue>bool</returnvalue> <function>VECTORP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
-   <screen><indexterm role="fn"><primary>STRINGP</primary></indexterm>&mdash; Function: <returnvalue>bool</returnvalue> <function>STRINGP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
+   <screen><indexterm role="fn"><primary>FIXNUMP</primary></indexterm>&#151; Function: <returnvalue>bool</returnvalue> <function>FIXNUMP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
+   <screen><indexterm role="fn"><primary>CHARACTERP</primary></indexterm>&#151; Function: <returnvalue>bool</returnvalue> <function>CHARACTERP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
+   <screen><indexterm role="fn"><primary>CONSP</primary></indexterm>&#151; Function: <returnvalue>bool</returnvalue> <function>CONSP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
+   <screen><indexterm role="fn"><primary>LISTP</primary></indexterm>&#151; Function: <returnvalue>bool</returnvalue> <function>LISTP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
+   <screen><indexterm role="fn"><primary>ATOM</primary></indexterm>&#151; Function: <returnvalue>bool</returnvalue> <function>ATOM</function> (<type>cl_object</type> <varname>o</varname>)</screen>
+   <screen><indexterm role="fn"><primary>ARRAYP</primary></indexterm>&#151; Function: <returnvalue>bool</returnvalue> <function>ARRAYP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
+   <screen><indexterm role="fn"><primary>VECTORP</primary></indexterm>&#151; Function: <returnvalue>bool</returnvalue> <function>VECTORP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
+   <screen><indexterm role="fn"><primary>STRINGP</primary></indexterm>&#151; Function: <returnvalue>bool</returnvalue> <function>STRINGP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
    <para>Different macros that check whether <replaceable>o</replaceable> belongs to the specified type.
    These checks have been optimized, and are preferred over several calls to
    <literal>type_of</literal>.</para>
   </blockquote>
   <blockquote>
-   <screen><indexterm role="fn"><primary>IMMEDIATE</primary></indexterm>&mdash; Function: <returnvalue>bool</returnvalue> <function>IMMEDIATE</function> (<type>cl_object</type> <varname>o</varname>)</screen>
+   <screen><indexterm role="fn"><primary>IMMEDIATE</primary></indexterm>&#151; Function: <returnvalue>bool</returnvalue> <function>IMMEDIATE</function> (<type>cl_object</type> <varname>o</varname>)</screen>
    <para>Tells whether <replaceable>o</replaceable> is an immediate datatype.</para>
   </blockquote>
   <!--  -->
  </section>
 
- <section id="Internals-Constructing-objects">
+ <section xml:id="Internals-Constructing-objects">
   <title>Constructing objects</title>
   <para>On each of the following sections we will document the standard interface for
   building objects of different types. For some objects, though, it is too
@@ -530,8 +534,8 @@
   <para role="continues">The first way makes use of a C or Lisp string to construct an object. The two
   functions you need to know are the following ones.</para>
   <blockquote>
-   <screen><indexterm role="fn"><primary>c_string_to_object</primary></indexterm>&mdash; Function: <returnvalue>cl_object</returnvalue> <function>c_string_to_object</function> (<type>const</type> <varname>char</varname> <type>*</type><varname>s</varname>)</screen>
-   <screen><indexterm role="fn"><primary>string_to_object</primary></indexterm>&mdash; Function: <returnvalue>cl_object</returnvalue> <function>string_to_object</function> (<type>cl_object</type> <varname>o</varname>)</screen>
+   <screen><indexterm role="fn"><primary>c_string_to_object</primary></indexterm>&#151; Function: <returnvalue>cl_object</returnvalue> <function>c_string_to_object</function> (<type>const</type> <varname>char</varname> <type>*</type><varname>s</varname>)</screen>
+   <screen><indexterm role="fn"><primary>string_to_object</primary></indexterm>&#151; Function: <returnvalue>cl_object</returnvalue> <function>string_to_object</function> (<type>cl_object</type> <varname>o</varname>)</screen>
    <para><literal>c_string_to_object</literal> builds a lisp object from a C string which contains a
    suitable representation of a lisp object. <literal>string_to_object</literal> performs the
    same task, but uses a lisp string, and therefore it is less useful. Two
@@ -548,7 +552,7 @@
   <!--  -->
  </section>
 
- <section id="Internals-Integers">
+ <section xml:id="Internals-Integers">
   <title>Integers</title>
   <para>Common-Lisp distinguishes two types of integer types: bignums and fixnums. A
   fixnum is a small integer, which ideally occupies only a word of memory and
@@ -563,81 +567,81 @@
   take up a variable amount of memory and the GNU Multiprecision Library is
   required to create, manipulate and calculate with them.</para>
   <blockquote>
-   <screen><indexterm role="tp"><primary>cl_fixnum</primary></indexterm>&mdash; C type: <structname>cl_fixnum</structname></screen>
+   <screen><indexterm role="tp"><primary>cl_fixnum</primary></indexterm>&#151; C type: <structname>cl_fixnum</structname></screen>
    <para>This is a C signed integer type capable of holding a whole fixnum without any
    loss of precision. The opposite is not true, and you may create a
    <literal>cl_fixnum</literal> which exceeds the limits of a fixnum and should be stored as a
    bignum.</para>
   </blockquote>
   <blockquote>
-   <screen><indexterm role="tp"><primary>cl_index</primary></indexterm>&mdash; C type: <structname>cl_index</structname></screen>
+   <screen><indexterm role="tp"><primary>cl_index</primary></indexterm>&#151; C type: <structname>cl_index</structname></screen>
    <para>This is a C unsigned integer type capable of holding a nonnegative fixnum without
    loss of precision. Typically, a <literal>cl_index</literal> is used as an index into an array,
    or into a proper list, etc.</para>
   </blockquote>
   <blockquote>
-   <screen><indexterm role="vr"><primary>MOST_NEGATIVE_FIXNUM</primary></indexterm>&mdash; Constant: <varname>MOST_NEGATIVE_FIXNUM</varname></screen>
-   <screen><indexterm role="vr"><primary>MOST_POSITIVE_FIXNUM</primary></indexterm>&mdash; Constant: <varname>MOST_POSITIVE_FIXNUM</varname></screen>
+   <screen><indexterm role="vr"><primary>MOST_NEGATIVE_FIXNUM</primary></indexterm>&#151; Constant: <varname>MOST_NEGATIVE_FIXNUM</varname></screen>
+   <screen><indexterm role="vr"><primary>MOST_POSITIVE_FIXNUM</primary></indexterm>&#151; Constant: <varname>MOST_POSITIVE_FIXNUM</varname></screen>
    <para>These constants mark the limits of a fixnum.</para>
   </blockquote>
   <blockquote>
-   <screen><indexterm role="fn"><primary>FIXNUM_MINUSP</primary></indexterm>&mdash; Function: <returnvalue>bool</returnvalue> <function>FIXNUM_MINUSP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
-   <screen><indexterm role="fn"><primary>FIXNUM_PLUSP</primary></indexterm>&mdash; Function: <returnvalue>bool</returnvalue> <function>FIXNUM_PLUSP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
+   <screen><indexterm role="fn"><primary>FIXNUM_MINUSP</primary></indexterm>&#151; Function: <returnvalue>bool</returnvalue> <function>FIXNUM_MINUSP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
+   <screen><indexterm role="fn"><primary>FIXNUM_PLUSP</primary></indexterm>&#151; Function: <returnvalue>bool</returnvalue> <function>FIXNUM_PLUSP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
    <para>These functions perform the checks (<replaceable>o</replaceable> &lt; 0) and (0 &lt;= <replaceable>o</replaceable>),
    respectively.</para>
   </blockquote>
   <blockquote>
-   <screen><indexterm role="fn"><primary>MAKE_FIXNUM</primary></indexterm>&mdash; Function: <returnvalue>cl_object</returnvalue> <function>MAKE_FIXNUM</function> (<type>cl_fixnum</type> <varname>n</varname>)</screen>
-   <screen><indexterm role="fn"><primary>fix</primary></indexterm>&mdash; Function: <returnvalue>cl_fixnum</returnvalue> <function>fix</function> (<type>cl_object</type> <varname>o</varname>)</screen>
+   <screen><indexterm role="fn"><primary>MAKE_FIXNUM</primary></indexterm>&#151; Function: <returnvalue>cl_object</returnvalue> <function>MAKE_FIXNUM</function> (<type>cl_fixnum</type> <varname>n</varname>)</screen>
+   <screen><indexterm role="fn"><primary>fix</primary></indexterm>&#151; Function: <returnvalue>cl_fixnum</returnvalue> <function>fix</function> (<type>cl_object</type> <varname>o</varname>)</screen>
    <para><literal>MAKE_FIXNUM</literal> and <literal>fix</literal> convert from an integer to a lisp object
    of fixnum type and vice versa. These functions no not check their arguments.</para>
   </blockquote>
   <blockquote>
-   <screen><indexterm role="fn"><primary>fixint</primary></indexterm>&mdash; Function: <returnvalue>cl_fixnum</returnvalue> <function>fixint</function> (<type>cl_object</type> <varname>o</varname>)</screen>
+   <screen><indexterm role="fn"><primary>fixint</primary></indexterm>&#151; Function: <returnvalue>cl_fixnum</returnvalue> <function>fixint</function> (<type>cl_object</type> <varname>o</varname>)</screen>
    <para>Converts a lisp fixnum to a C integer of the appropriate size. Signals an error
    if <replaceable>o</replaceable> is not of fixnum type.</para>
   </blockquote>
   <blockquote>
-   <screen><indexterm role="fn"><primary>fixnnint</primary></indexterm>&mdash; Function: <returnvalue>cl_index</returnvalue> <function>fixnnint</function> (<type>cl_object</type> <varname>o</varname>)</screen>
+   <screen><indexterm role="fn"><primary>fixnnint</primary></indexterm>&#151; Function: <returnvalue>cl_index</returnvalue> <function>fixnnint</function> (<type>cl_object</type> <varname>o</varname>)</screen>
    <para>Similar to <literal>fixint</literal> but also ensures that <replaceable>o</replaceable> is not negative.</para>
   </blockquote>
   <!--  -->
  </section>
 
- <section id="Internals-Characters">
+ <section xml:id="Internals-Characters">
   <title>Characters</title>
   <para>&ECL; has only one type of characters, which fits in the C type <literal>char</literal>.
   The following constants and functions operate on characters.</para>
   <blockquote>
-   <screen><indexterm role="vr"><primary>CHAR_CODE_LIMIT</primary></indexterm>&mdash; Constant: <varname>CHAR_CODE_LIMIT</varname></screen>
+   <screen><indexterm role="vr"><primary>CHAR_CODE_LIMIT</primary></indexterm>&#151; Constant: <varname>CHAR_CODE_LIMIT</varname></screen>
    <para>Each character is assigned an integer code which ranges from 0 to
    (<replaceable>CHAR_CODE_LIMIT</replaceable>-1).</para>
   </blockquote>
   <blockquote>
-   <screen><indexterm role="fn"><primary>CHAR_CODE</primary></indexterm>&mdash; Function: <returnvalue>cl_fixnum</returnvalue> <function>CHAR_CODE</function> (<type>cl_object</type> <varname>o</varname>)</screen>
-   <screen><indexterm role="fn"><primary>char_code</primary></indexterm>&mdash; Function: <returnvalue>cl_fixnum</returnvalue> <function>char_code</function> (<type>cl_object</type> <varname>o</varname>)</screen>
+   <screen><indexterm role="fn"><primary>CHAR_CODE</primary></indexterm>&#151; Function: <returnvalue>cl_fixnum</returnvalue> <function>CHAR_CODE</function> (<type>cl_object</type> <varname>o</varname>)</screen>
+   <screen><indexterm role="fn"><primary>char_code</primary></indexterm>&#151; Function: <returnvalue>cl_fixnum</returnvalue> <function>char_code</function> (<type>cl_object</type> <varname>o</varname>)</screen>
    <para>Returns the integer code associated to a lisp character. Only <literal>char_code</literal>
    checks its arguments.</para>
   </blockquote>
   <blockquote>
-   <screen><indexterm role="fn"><primary>CODE_CHAR</primary></indexterm>&mdash; Function: <returnvalue>cl_object</returnvalue> <function>CODE_CHAR</function> (<type>cl_fixnum</type> <varname>o</varname>)</screen>
+   <screen><indexterm role="fn"><primary>CODE_CHAR</primary></indexterm>&#151; Function: <returnvalue>cl_object</returnvalue> <function>CODE_CHAR</function> (<type>cl_fixnum</type> <varname>o</varname>)</screen>
    <para>Returns the lisp character associated to an integer code. It does not check
    its arguments.</para>
   </blockquote>
   <blockquote>
-   <screen><indexterm role="fn"><primary>coerce_to_character</primary></indexterm>&mdash; Function: <returnvalue>cl_object</returnvalue> <function>coerce_to_character</function> (<type>cl_object</type> <varname>o</varname>)</screen>
+   <screen><indexterm role="fn"><primary>coerce_to_character</primary></indexterm>&#151; Function: <returnvalue>cl_object</returnvalue> <function>coerce_to_character</function> (<type>cl_object</type> <varname>o</varname>)</screen>
    <para>Coerces a lisp object to type character. Valid arguments are a character,
    or a string designator of length 1. In all other cases an error is signaled.</para>
   </blockquote>
   <blockquote>
-   <screen><indexterm role="fn"><primary>char_eq</primary></indexterm>&mdash; Function: <returnvalue>bool</returnvalue> <function>char_eq</function> (<type>cl_object</type> <varname>x</varname>, <type>cl_object</type> <varname>y</varname>)</screen>
-   <screen><indexterm role="fn"><primary>char_equal</primary></indexterm>&mdash; Function: <returnvalue>bool</returnvalue> <function>char_equal</function> (<type>cl_object</type> <varname>x</varname>, <type>cl_object</type> <varname>y</varname>)</screen>
+   <screen><indexterm role="fn"><primary>char_eq</primary></indexterm>&#151; Function: <returnvalue>bool</returnvalue> <function>char_eq</function> (<type>cl_object</type> <varname>x</varname>, <type>cl_object</type> <varname>y</varname>)</screen>
+   <screen><indexterm role="fn"><primary>char_equal</primary></indexterm>&#151; Function: <returnvalue>bool</returnvalue> <function>char_equal</function> (<type>cl_object</type> <varname>x</varname>, <type>cl_object</type> <varname>y</varname>)</screen>
    <para>Compare two characters for equality. <literal>char_eq</literal> take case into account and
    <literal>char_equal</literal> ignores it.</para>
   </blockquote>
   <blockquote>
-   <screen><indexterm role="fn"><primary>char_cmp</primary></indexterm>&mdash; Function: <returnvalue>int</returnvalue> <function>char_cmp</function> (<type>cl_object</type> <varname>x</varname>, <type>cl_object</type> <varname>y</varname>)</screen>
-   <screen><indexterm role="fn"><primary>char_compare</primary></indexterm>&mdash; Function: <returnvalue>int</returnvalue> <function>char_compare</function> (<type>cl_object</type> <varname>x</varname>, <type>cl_object</type> <varname>y</varname>)</screen>
+   <screen><indexterm role="fn"><primary>char_cmp</primary></indexterm>&#151; Function: <returnvalue>int</returnvalue> <function>char_cmp</function> (<type>cl_object</type> <varname>x</varname>, <type>cl_object</type> <varname>y</varname>)</screen>
+   <screen><indexterm role="fn"><primary>char_compare</primary></indexterm>&#151; Function: <returnvalue>int</returnvalue> <function>char_compare</function> (<type>cl_object</type> <varname>x</varname>, <type>cl_object</type> <varname>y</varname>)</screen>
    <para>Compare the relative order of two characters. <literal>char_cmp</literal> takes care of
    case and <literal>char_compare</literal> converts all characters to uppercase before
    comparing them.</para>
@@ -645,7 +649,7 @@
   <!--  -->
  </section>
 
- <section id="Internals-Arrays">
+ <section xml:id="Internals-Arrays">
   <title>Arrays</title>
   <para>An array is an aggregate of data of a common type, which can be accessed with
   one or more nonnegative indices. &ECL; stores arrays as a C structure with a
@@ -772,7 +776,7 @@
    </varlistentry>
   </variablelist>
   <blockquote>
-   <screen><indexterm role="fn"><primary>array_elttype</primary></indexterm>&mdash; Function: <returnvalue>cl_elttype</returnvalue> <function>array_elttype</function> (<type>cl_object</type> <varname>o</varname>)</screen>
+   <screen><indexterm role="fn"><primary>array_elttype</primary></indexterm>&#151; Function: <returnvalue>cl_elttype</returnvalue> <function>array_elttype</function> (<type>cl_object</type> <varname>o</varname>)</screen>
    <para>Returns the element type of the array <replaceable>o</replaceable>, which can be a string, a
    bitvector, vector, or a multidimensional array. For example, the code
    <literal>array_elttype(c_string_to_object("\"AAA\""))</literal> returns <literal>aet_ch</literal>,
@@ -780,8 +784,8 @@
    <literal>aet_object</literal>.</para>
   </blockquote>
   <blockquote>
-   <screen><indexterm role="fn"><primary>aref</primary></indexterm>&mdash; Function: <returnvalue>cl_object</returnvalue> <function>aref</function> (<type>cl_object</type> <varname>array</varname>, <type>cl_index</type> <varname>index</varname>)</screen>
-   <screen><indexterm role="fn"><primary>aset</primary></indexterm>&mdash; Function: <returnvalue>cl_object</returnvalue> <function>aset</function> (<type>cl_object</type> <varname>array</varname>, <type>cl_index</type> <varname>index</varname>, <type>cl_object</type> <varname>value</varname>)</screen>
+   <screen><indexterm role="fn"><primary>aref</primary></indexterm>&#151; Function: <returnvalue>cl_object</returnvalue> <function>aref</function> (<type>cl_object</type> <varname>array</varname>, <type>cl_index</type> <varname>index</varname>)</screen>
+   <screen><indexterm role="fn"><primary>aset</primary></indexterm>&#151; Function: <returnvalue>cl_object</returnvalue> <function>aset</function> (<type>cl_object</type> <varname>array</varname>, <type>cl_index</type> <varname>index</varname>, <type>cl_object</type> <varname>value</varname>)</screen>
    <para>These functions are used to retrieve and set the elements of an array. The
    elements are accessed with one index, <replaceable>index</replaceable>, as in the lisp function
    <literal>ROW-MAJOR-AREF</literal>. For example</para>
@@ -794,8 +798,8 @@
    </screen>
   </blockquote>
   <blockquote>
-   <screen><indexterm role="fn"><primary>aref1</primary></indexterm>&mdash; Function: <returnvalue>cl_object</returnvalue> <function>aref1</function> (<type>cl_object</type> <varname>vector</varname>, <type>cl_index</type> <varname>index</varname>)</screen>
-   <screen><indexterm role="fn"><primary>aset1</primary></indexterm>&mdash; Function: <returnvalue>cl_object</returnvalue> <function>aset1</function> (<type>cl_object</type> <varname>vector</varname>, <type>cl_index</type> <varname>index</varname>, <type>cl_object</type> <varname>value</varname>)</screen>
+   <screen><indexterm role="fn"><primary>aref1</primary></indexterm>&#151; Function: <returnvalue>cl_object</returnvalue> <function>aref1</function> (<type>cl_object</type> <varname>vector</varname>, <type>cl_index</type> <varname>index</varname>)</screen>
+   <screen><indexterm role="fn"><primary>aset1</primary></indexterm>&#151; Function: <returnvalue>cl_object</returnvalue> <function>aset1</function> (<type>cl_object</type> <varname>vector</varname>, <type>cl_index</type> <varname>index</varname>, <type>cl_object</type> <varname>value</varname>)</screen>
    <para>These functions are similar to <literal>aref</literal> and <literal>aset</literal>, but they operate on
    vectors.</para>
    <screen>
@@ -809,7 +813,7 @@
   <!--  -->
  </section>
 
- <section id="Internals-Strings">
+ <section xml:id="Internals-Strings">
   <title>Strings</title>
   <para>A string, both in Common-Lisp and in &ECL; is nothing but a vector of
   characters. Therefore, almost everything mentioned in the section of arrays
@@ -846,8 +850,8 @@
    </varlistentry>
   </variablelist>
   <blockquote>
-   <screen><indexterm role="fn"><primary>make_simple_string</primary></indexterm>&mdash; Function: <returnvalue>cl_object</returnvalue> <function>make_simple_string</function> (<type>char</type> <varname>*</varname><varname>s</varname>)</screen>
-   <screen><indexterm role="fn"><primary>make_string_copy</primary></indexterm>&mdash; Function: <returnvalue>cl_object</returnvalue> <function>make_string_copy</function> (<type>char</type> <varname>*</varname><varname>s</varname>)</screen>
+   <screen><indexterm role="fn"><primary>make_simple_string</primary></indexterm>&#151; Function: <returnvalue>cl_object</returnvalue> <function>make_simple_string</function> (<type>char</type> <varname>*</varname><varname>s</varname>)</screen>
+   <screen><indexterm role="fn"><primary>make_string_copy</primary></indexterm>&#151; Function: <returnvalue>cl_object</returnvalue> <function>make_string_copy</function> (<type>char</type> <varname>*</varname><varname>s</varname>)</screen>
    <para>Both routines build a lisp string from a C string. <literal>make_string_copy</literal>
    allocates new space and copies the content of the string to
    it. <literal>make_simple_string</literal> simply uses the memory pointed by <replaceable>s</replaceable>, which
@@ -856,32 +860,32 @@
   </blockquote>
  </section>
 
- <section id="Internals-Bitvectors">
+ <section xml:id="Internals-Bitvectors">
   <title>Bitvectors</title>
  </section>
 
- <section id="Internals-Streams">
+ <section xml:id="Internals-Streams">
   <title>Streams</title>
  </section>
 
- <section id="Internals-Structures">
+ <section xml:id="Internals-Structures">
   <title>Structures</title>
  </section>
 
- <section id="Internals-Instances">
+ <section xml:id="Internals-Instances">
   <title>Instances</title>
   <!--  -->
  </section>
 
- <section id="Internals-Bytecodes">
+ <section xml:id="Internals-Bytecodes">
   <title>Bytecodes</title>
   <para>A bytecodes object is a lisp object with a piece of code that can be
   interpreted. The objects of type <literal>t_bytecode</literal> are implicitly constructed
   by a call to <literal>eval</literal>, but can also be explicitly constructed with the
   <literal>make_lambda</literal> function.</para>
   <blockquote>
-   <screen><indexterm role="fn"><primary>cl_safe_eval</primary></indexterm>&mdash; Function: <returnvalue>cl_object</returnvalue> <function>cl_safe_eval</function> (<type>cl_object</type> <varname>form</varname>, <type>cl_object</type> <varname>env</varname>, <type>cl_object</type> <varname>err_value</varname></screen>
-   <screen><indexterm role="fn"><primary>cl_eval</primary></indexterm>&mdash; Function: <returnvalue>cl_object</returnvalue> <function>cl_eval</function> (<type>cl_object</type> <varname>form</varname>)</screen>
+   <screen><indexterm role="fn"><primary>cl_safe_eval</primary></indexterm>&#151; Function: <returnvalue>cl_object</returnvalue> <function>cl_safe_eval</function> (<type>cl_object</type> <varname>form</varname>, <type>cl_object</type> <varname>env</varname>, <type>cl_object</type> <varname>err_value</varname></screen>
+   <screen><indexterm role="fn"><primary>cl_eval</primary></indexterm>&#151; Function: <returnvalue>cl_object</returnvalue> <function>cl_eval</function> (<type>cl_object</type> <varname>form</varname>)</screen>
    <para><literal>cl_safe_eval</literal> evaluates <replaceable>form</replaceable> in the lexical environment <replaceable>env</replaceable>,
    which can be <replaceable>nil</replaceable>. Before evaluating it, the expression <replaceable>form</replaceable> must
    be bytecompiled. <literal>cl_eval</literal> is the equivalent of <literal>cl_safe_eval</literal> but
@@ -894,7 +898,7 @@
    </screen>
   </blockquote>
   <blockquote>
-   <screen><indexterm role="fn"><primary>si_make_lambda</primary></indexterm>&mdash; Function: <returnvalue>cl_object</returnvalue> <function>si_make_lambda</function> (<type>cl_object</type> <varname>name</varname>, <type>cl_object</type> <varname>def</varname>)</screen>
+   <screen><indexterm role="fn"><primary>si_make_lambda</primary></indexterm>&#151; Function: <returnvalue>cl_object</returnvalue> <function>si_make_lambda</function> (<type>cl_object</type> <varname>name</varname>, <type>cl_object</type> <varname>def</varname>)</screen>
    <para>Builds an interpreted lisp function with name given by the symbol <replaceable>name</replaceable>
    and body given by <replaceable>def</replaceable>. For instance, we would achieve the equivalent of</para>
    <programlisting>
@@ -922,9 +926,9 @@
  </section>
 </chapter>
 
-<chapter id="Internals-the-interpreter">
+<chapter xml:id="Internals-the-interpreter">
  <title>The interpreter</title>
- <section id="Internals-ECL-stacks">
+ <section xml:id="Internals-ECL-stacks">
   <title>&ECL; stacks</title>
   <para>&ECL; uses the following stacks:</para>
   <variablelist>
@@ -957,7 +961,7 @@
   </variablelist>
  </section>
 
- <section id="Internals-Procedure-Call-Conventions">
+ <section xml:id="Internals-Procedure-Call-Conventions">
   <title>Procedure Call Conventions</title>
   <para>&ECL; employs standard C calling conventions to achieve efficiency and
   interoperability with other languages.
@@ -1005,7 +1009,7 @@
   </screen>
  </section>
 
- <section id="Internals-The-lexical-environment">
+ <section xml:id="Internals-The-lexical-environment">
   <title>The lexical environment</title>
   <para>The &ECL; interpreter uses two A-lists (Association lists) to
   represent lexical environments.</para>
@@ -1023,7 +1027,7 @@
   used to recover the lexical environment.</para>
  </section>
 
- <section id="Internals-The-interpreter-stack">
+ <section xml:id="Internals-The-interpreter-stack">
   <title>The interpreter stack</title>
   <para>The bytecodes interpreter uses a stack of its own to save and restore values
   from intermediate calculations. This Forth-like data stack is also used in
@@ -1116,9 +1120,9 @@
  </section>
 </chapter>
 
-<chapter id="Internals-the-compiler">
+<chapter xml:id="Internals-the-compiler">
  <title>The compiler</title>
- <section id="Internals-The-compiler-translates-to-C">
+ <section xml:id="Internals-The-compiler-translates-to-C">
   <title>The compiler translates to C</title>
   <para>The &ECL; compiler is essentially a translator from Common-Lisp to C.  Given
   a Lisp source file, the compiler first generates three intermediate
@@ -1174,7 +1178,7 @@
   </itemizedlist>
  </section>
 
- <section id="Internals-The-compiler-mimics-human-C-programmer">
+ <section xml:id="Internals-The-compiler-mimics-human-C-programmer">
   <title>The compiler mimics human C programmer</title>
   <para>The format of the intermediate C code generated by the &ECL; compiler is the
   same as the hand-coded C code of the &ECL; source programs.  For example,
@@ -1231,7 +1235,7 @@
   </screen>
  </section>
 
- <section id="Internals-Implementation-of-Compiled-Closures">
+ <section xml:id="Internals-Implementation-of-Compiled-Closures">
   <title>Implementation of Compiled Closures</title>
   <para>The &ECL; compiler takes two passes before it invokes the C
   compiler.  The major role of the first pass is to detect function
@@ -1244,7 +1248,7 @@
   <para>Ordinarily, lexical variables in a compiled function <emphasis>f</emphasis>
   are allocated on the C stack.  However, if a lexical variable is
   to be enclosed in function closures, it is allocated on a list, called
-  the &ldquo;environment list&rdquo;, which is local to <emphasis>f</emphasis>.  In addition, a
+  the ��environment list��, which is local to <emphasis>f</emphasis>.  In addition, a
   local variable is created which points to the lexical
   variable's location (within the environment list), so that
   the variable may be accessed through an indirection rather than by list
@@ -1299,7 +1303,7 @@
   ]]></screen>
  </section>
 
- <section id="Internals-Use-of-Declarations-to-Improve-Efficiency">
+ <section xml:id="Internals-Use-of-Declarations-to-Improve-Efficiency">
   <title>Use of Declarations to Improve Efficiency</title>
   <para>Declarations, especially  type  and  function  declarations,
   increase the efficiency of the compiled code.  For example, for the
@@ -1339,7 +1343,7 @@
   </screen>
  </section>
 
- <section id="Internals-Inspecting-generated-C-code">
+ <section xml:id="Internals-Inspecting-generated-C-code">
   <title>Inspecting generated C code</title>
   <para>Common-Lisp defines a function disassemble, which is
   supposed to disassemble a compiled function and to display the
@@ -1370,7 +1374,7 @@
  </section>
 </chapter>
 
-<chapter id="Porting-ECL">
+<chapter xml:id="Porting-ECL">
  <title>Porting &ECL;</title>
  <para>To port &ECL; to a new architecture, the following steps are required:</para>
  <orderedlist numeration="arabic">