Diff of /internals.xmlf [f587e9] .. [9e7c20] Maximize Restore

  Switch to side-by-side view

--- a/internals.xmlf
+++ b/internals.xmlf
@@ -1,9 +1,5 @@
-<?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>
+<?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>
 <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
@@ -31,12 +27,12 @@
  efficiency.</para>
 </partintro>
 
-<chapter xml:id="Building-programs">
+<chapter 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 xml:id="Internals-What-can-ECL-do-">
+ <section 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
@@ -106,7 +102,7 @@
   <!--  -->
  </section>
 
- <section xml:id="Internals-Compiling-files">
+ <section 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
@@ -141,7 +137,7 @@
   <!--  -->
  </section>
 
- <section xml:id="Internals-Building-standalone-executables">
+ <section 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
@@ -149,7 +145,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> 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>&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>
    <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">
@@ -176,14 +172,14 @@
   <!--  -->
  </section>
 
- <section xml:id="Internals-Building-libraries">
+ <section 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> 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> 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>&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>
    <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>
@@ -198,23 +194,15 @@
    their purpose is to link C/C++ extensions into the library.</para>
    <para><replaceable>init-name</replaceable> gives the initialization function of the library a
    user-specified name. Thus a the generated library may be used and/or
-   linked to a C application.
-   The recommended way to invoke <replaceable>init-name</replaceable> is following:
-   <programlisting>
-    cl_object the_block = read_VV(OBJNULL, init_FOO /* function name specified by init-name */);
-   </programlisting>
-   Be sure to call <literal>cl_boot</literal> before the invocation of <replaceable>init-name</replaceable>.
-   In order to avoid that the returned object is garbage collected,
-   you should keep the result of <literal>read_VV</literal> in a local variable.
-   </para>
+   linked to a C application.</para>
   </blockquote>
   <!--  -->
  </section>
 
- <section xml:id="Internals-File-names">
+ <section id="Internals-File-names">
   <title>File names</title>
   <blockquote>
-   <screen><indexterm role="fn"><primary>compile-file-pathname</primary></indexterm> 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>&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>
    <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
@@ -271,7 +259,7 @@
   <!--  -->
  </section>
 
- <section xml:id="Internals-Compiler-examples">
+ <section id="Internals-Compiler-examples">
   <title>Compiler examples</title>
   <section>
    <title>The <filename>hello.lisp</filename> file</title>
@@ -321,7 +309,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,&#x2013;rpath,/usr/lib/ecl/ -shared   -lecl -lgmp -lgc -ldl -lm
+    ;;; 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
     ;;; OPTIMIZE levels: Safety=2, Space=0, Speed=3
     ;;; Finished compiling hello.lisp.
     #P"hello.fas"
@@ -356,7 +344,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,&#x2013;rpath,/usr/lib/ecl/  -lecl -lgmp -lgc -ldl -lm
+   ;;; 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
    #P"myecl"
    Top level.
    </screen>Now you can execute this program from your favorite shell.</para>
@@ -392,7 +380,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,&#x2013;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,&ndash;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>
@@ -408,12 +396,12 @@
  </section>
 </chapter>
 
-<chapter xml:id="Lisp-objects">
+<chapter 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 xml:id="Internals-Objects-representation">
+ <section 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
@@ -459,31 +447,31 @@
   <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> C type: <structname>cl_object</structname></screen>
+   <screen><indexterm role="tp"><primary>cl_object</primary></indexterm>&mdash; 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
-   guessed with the macro <literal>ecl_t_of</literal>.</para>
+   guessed with the macro <literal>type_of</literal>.</para>
    <para>For example, if <replaceable>x</replaceable> is of type <literal>cl_object</literal>, and it is of type fixnum,
    we may retrieve its value</para>
    <screen>
-    if (ecl_t_of(x) == t_fixnum)
+    if (type_of(x) == t_fixnum)
     printf("Integer value: %d\n", fix(x));
    </screen>
    <para role="continues">If <replaceable>x</replaceable> is of type <literal>cl_object</literal> and it does not contain an immediate
    datatype, you may inspect the cell associated to the lisp object using <replaceable>x</replaceable>
    as a pointer. For example,</para>
    <screen>
-    if (ecl_t_of(x) == t_cons)
+    if (type_of(x) == t_cons)
     printf("CAR = %x, CDR = %x\n", x-&gt;cons.car, x-&gt;cons.cdr);
-    else if (ecl_t_of(x) == t_string)
+    else if (type_of(x) == t_string)
     printf("String: %s\n", x-&gt;string.self);
    </screen>
    <para role="continues">You should see the following sections and the header <filename>object.h</filename> to learn
    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> C type: <structname>cl_type</structname></screen>
+   <screen><indexterm role="tp"><primary>cl_type</primary></indexterm>&mdash; 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,
@@ -492,32 +480,32 @@
    t_thread.</para>
   </blockquote>
   <blockquote>
-   <screen><indexterm role="fn"><primary>ecl_t_of</primary></indexterm> Function: <returnvalue>cl_type</returnvalue> <function>ecl_t_of</function> (<type>cl_object</type> <varname>O</varname>)</screen>
-   <para>If <replaceable>O</replaceable> is a valid lisp object, <literal>ecl_t_of(<replaceable>O</replaceable>)</literal> returns an integer
+   <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>
+   <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> Function: <returnvalue>bool</returnvalue> <function>FIXNUMP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
-   <screen><indexterm role="fn"><primary>CHARACTERP</primary></indexterm> Function: <returnvalue>bool</returnvalue> <function>CHARACTERP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
-   <screen><indexterm role="fn"><primary>CONSP</primary></indexterm> Function: <returnvalue>bool</returnvalue> <function>CONSP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
-   <screen><indexterm role="fn"><primary>LISTP</primary></indexterm> Function: <returnvalue>bool</returnvalue> <function>LISTP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
-   <screen><indexterm role="fn"><primary>ATOM</primary></indexterm> Function: <returnvalue>bool</returnvalue> <function>ATOM</function> (<type>cl_object</type> <varname>o</varname>)</screen>
-   <screen><indexterm role="fn"><primary>ARRAYP</primary></indexterm> Function: <returnvalue>bool</returnvalue> <function>ARRAYP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
-   <screen><indexterm role="fn"><primary>VECTORP</primary></indexterm> Function: <returnvalue>bool</returnvalue> <function>VECTORP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
-   <screen><indexterm role="fn"><primary>STRINGP</primary></indexterm> Function: <returnvalue>bool</returnvalue> <function>STRINGP</function> (<type>cl_object</type> <varname>o</varname>)</screen>
+   <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>
    <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>ecl_t_of</literal>.</para>
-  </blockquote>
-  <blockquote>
-   <screen><indexterm role="fn"><primary>IMMEDIATE</primary></indexterm> Function: <returnvalue>bool</returnvalue> <function>IMMEDIATE</function> (<type>cl_object</type> <varname>o</varname>)</screen>
+   <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>
    <para>Tells whether <replaceable>o</replaceable> is an immediate datatype.</para>
   </blockquote>
   <!--  -->
  </section>
 
- <section xml:id="Internals-Constructing-objects">
+ <section 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
@@ -534,8 +522,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> 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> 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>&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>
    <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
@@ -552,7 +540,7 @@
   <!--  -->
  </section>
 
- <section xml:id="Internals-Integers">
+ <section 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
@@ -567,81 +555,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> C type: <structname>cl_fixnum</structname></screen>
+   <screen><indexterm role="tp"><primary>cl_fixnum</primary></indexterm>&mdash; 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> C type: <structname>cl_index</structname></screen>
+   <screen><indexterm role="tp"><primary>cl_index</primary></indexterm>&mdash; 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> Constant: <varname>MOST_NEGATIVE_FIXNUM</varname></screen>
-   <screen><indexterm role="vr"><primary>MOST_POSITIVE_FIXNUM</primary></indexterm> Constant: <varname>MOST_POSITIVE_FIXNUM</varname></screen>
+   <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>
    <para>These constants mark the limits of a fixnum.</para>
   </blockquote>
   <blockquote>
-   <screen><indexterm role="fn"><primary>FIXNUM_MINUSP</primary></indexterm> 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> 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>&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>
    <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> 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> 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>&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>
    <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> Function: <returnvalue>cl_fixnum</returnvalue> <function>fixint</function> (<type>cl_object</type> <varname>o</varname>)</screen>
+   <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>
    <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> Function: <returnvalue>cl_index</returnvalue> <function>fixnnint</function> (<type>cl_object</type> <varname>o</varname>)</screen>
+   <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>
    <para>Similar to <literal>fixint</literal> but also ensures that <replaceable>o</replaceable> is not negative.</para>
   </blockquote>
   <!--  -->
  </section>
 
- <section xml:id="Internals-Characters">
+ <section 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> Constant: <varname>CHAR_CODE_LIMIT</varname></screen>
+   <screen><indexterm role="vr"><primary>CHAR_CODE_LIMIT</primary></indexterm>&mdash; 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> 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> 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>&mdash; 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> 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>&mdash; 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> 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>&mdash; 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> 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> 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>&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>
    <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> 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> 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>&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>
    <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>
@@ -649,7 +637,7 @@
   <!--  -->
  </section>
 
- <section xml:id="Internals-Arrays">
+ <section 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
@@ -776,7 +764,7 @@
    </varlistentry>
   </variablelist>
   <blockquote>
-   <screen><indexterm role="fn"><primary>array_elttype</primary></indexterm> 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>&mdash; 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>,
@@ -784,8 +772,8 @@
    <literal>aet_object</literal>.</para>
   </blockquote>
   <blockquote>
-   <screen><indexterm role="fn"><primary>aref</primary></indexterm> 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> 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>&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>
    <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>
@@ -798,8 +786,8 @@
    </screen>
   </blockquote>
   <blockquote>
-   <screen><indexterm role="fn"><primary>aref1</primary></indexterm> 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> 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>&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>
    <para>These functions are similar to <literal>aref</literal> and <literal>aset</literal>, but they operate on
    vectors.</para>
    <screen>
@@ -813,7 +801,7 @@
   <!--  -->
  </section>
 
- <section xml:id="Internals-Strings">
+ <section 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
@@ -850,8 +838,8 @@
    </varlistentry>
   </variablelist>
   <blockquote>
-   <screen><indexterm role="fn"><primary>make_simple_string</primary></indexterm> 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> 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>&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>
    <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
@@ -860,32 +848,32 @@
   </blockquote>
  </section>
 
- <section xml:id="Internals-Bitvectors">
+ <section id="Internals-Bitvectors">
   <title>Bitvectors</title>
  </section>
 
- <section xml:id="Internals-Streams">
+ <section id="Internals-Streams">
   <title>Streams</title>
  </section>
 
- <section xml:id="Internals-Structures">
+ <section id="Internals-Structures">
   <title>Structures</title>
  </section>
 
- <section xml:id="Internals-Instances">
+ <section id="Internals-Instances">
   <title>Instances</title>
   <!--  -->
  </section>
 
- <section xml:id="Internals-Bytecodes">
+ <section 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> 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> 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>&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>
    <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
@@ -898,7 +886,7 @@
    </screen>
   </blockquote>
   <blockquote>
-   <screen><indexterm role="fn"><primary>si_make_lambda</primary></indexterm> 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>&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>
    <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>
@@ -926,9 +914,9 @@
  </section>
 </chapter>
 
-<chapter xml:id="Internals-the-interpreter">
+<chapter id="Internals-the-interpreter">
  <title>The interpreter</title>
- <section xml:id="Internals-ECL-stacks">
+ <section id="Internals-ECL-stacks">
   <title>&ECL; stacks</title>
   <para>&ECL; uses the following stacks:</para>
   <variablelist>
@@ -961,7 +949,7 @@
   </variablelist>
  </section>
 
- <section xml:id="Internals-Procedure-Call-Conventions">
+ <section 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.
@@ -1009,7 +997,7 @@
   </screen>
  </section>
 
- <section xml:id="Internals-The-lexical-environment">
+ <section 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>
@@ -1027,7 +1015,7 @@
   used to recover the lexical environment.</para>
  </section>
 
- <section xml:id="Internals-The-interpreter-stack">
+ <section 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
@@ -1120,9 +1108,9 @@
  </section>
 </chapter>
 
-<chapter xml:id="Internals-the-compiler">
+<chapter id="Internals-the-compiler">
  <title>The compiler</title>
- <section xml:id="Internals-The-compiler-translates-to-C">
+ <section 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
@@ -1178,7 +1166,7 @@
   </itemizedlist>
  </section>
 
- <section xml:id="Internals-The-compiler-mimics-human-C-programmer">
+ <section 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,
@@ -1235,7 +1223,7 @@
   </screen>
  </section>
 
- <section xml:id="Internals-Implementation-of-Compiled-Closures">
+ <section 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
@@ -1248,7 +1236,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 "environment list", which is local to <emphasis>f</emphasis>.  In addition, a
+  the &ldquo;environment list&rdquo;, 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
@@ -1303,7 +1291,7 @@
   ]]></screen>
  </section>
 
- <section xml:id="Internals-Use-of-Declarations-to-Improve-Efficiency">
+ <section 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
@@ -1343,7 +1331,7 @@
   </screen>
  </section>
 
- <section xml:id="Internals-Inspecting-generated-C-code">
+ <section 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
@@ -1372,9 +1360,279 @@
    }
   </screen></para>
  </section>
+
+ <section id="Internals-Embedding-C-code">
+  <title>Embedding C code in lisp source</title>
+  <para>There are several mechanism to integrate C code within &ECL;, but
+  everything is built around two functions that allow the user to embed
+  arbitrary C/C++ code into Lisp source code.</para>
+  <para>The two mechanisms are the <literal>Clines</literal> and the <literal>c-inline</literal> special
+  forms. The first one permits to insert code in the intermediate C/C++ file
+  generated by the &ECL; compiler. Such a form outputs no value and takes
+  no arguments, except a series of strings which are inserted literally,
+  such as <literal>#include</literal> or <literal>#define</literal> statements, function definitions, etc.</para>
+  <blockquote>
+   <screen><indexterm role="fn"><primary>Clines</primary></indexterm>&mdash; Macro: <function>Clines</function> <varname>{</varname><varname>{</varname><varname>string</varname><varname>}</varname><varname>*</varname><varname>}</varname></screen>
+   <para>When the &ECL; compiler encounters a macro form <literal>(Clines <replaceable>string1
+   ...  stringn</replaceable>)</literal>, it simply outputs the <replaceable>strings</replaceable> into the c-file.  The
+   arguments are not evaluated and each argument must be a string.  Each
+   <replaceable>string</replaceable> may consist of any number of lines, and separate lines in the
+   <replaceable>string</replaceable> are placed in separate lines in the c-file.  In addition, each
+   <replaceable>string</replaceable> opens a fresh line in the c-file, i.e., the first character in the
+   <replaceable>string</replaceable> is placed at the first column of a line.  Therefore, C-language
+   preprocessor commands such as <literal>#define</literal> and <literal>#include</literal> will be
+   recognized as such by the C compiler, if the ' # ' sign appears as the first
+   character of the <replaceable>string</replaceable> or as the first character of a line within the
+   <replaceable>string</replaceable>.</para>
+   <para>When interpreted, a <literal>Clines</literal> macro form expands to ().</para>
+  </blockquote>
+  <programlisting>(use-package "FFI")
+
+  (Clines
+  "   int tak(x, y, z)                       "
+  "   int x, y, z;                           "
+  "   {   if (y &gt;= x) return(z);             "
+  "       else return(tak(tak(x-1, y, z),    "
+  "                       tak(y-1, z, x),    "
+  "                       tak(z-1, x, y)));  "
+  "   }                                      "
+  )
+
+  (defun tak (x y z)
+  (c-inline (x y z) (:int :int :int) :int
+  "tak(#0,#1,#2)" :one-liner t))
+  </programlisting>
+  <para>The second mechanism, which you already appreciate in the example above, is the
+  <literal>c-inline</literal> special form. This powerful method allows the user to insert C
+  code which is evaluated, and which can accept values and return values from and
+  to the Lisp world, with an automatic convertion taking place in both directions.</para>
+  <blockquote>
+   <screen><indexterm role="fn"><primary>c-inline</primary></indexterm>&mdash; Macro: <function>c-inline</function> <varname>{</varname><varname>args-list</varname> <varname>arg-C-types</varname> <varname>output-C-type</varname> <varname>C-expr</varname> <varname>&amp;key</varname> (<varname>side-effects</varname> <varname><literal>T</literal></varname>) (<varname>one-liner</varname> <varname><literal>T</literal></varname>)<varname>}</varname></screen>
+   <para><literal>c-inline</literal> is a special form that can only be used in compiled
+   code.  For all purposes it behaves as a Lisp form, which takes the
+   arguments given in <replaceable>args-list</replaceable> and produces a single value. Behind
+   the curtains, the arguments of <replaceable>args-list</replaceable> (which can be any valid
+   Lisp form) are coerced to the the C types given in <replaceable>arg-C-types</replaceable>,
+   passed to the C expression <replaceable>C-expr</replaceable>, and coerced back to Lisp
+   using the C type <replaceable>output-C-type</replaceable> as a guide.  Multiple return
+   values can be returned by setting <replaceable>output-C-type</replaceable> to <literal>(values
+   type-1 type-2 ...)</literal>.</para>
+   <para><replaceable>C-expr</replaceable> is a string containing C code and maybe some special
+   escape codes.  First, the arguments of the form may be retrieved as
+   <literal>#0</literal>, <literal>#1</literal>, etc.  Second, if the <literal>c-inline</literal> form is a
+   one-line C expression (That is, <replaceable>one-liner</replaceable> is true), then the
+   whole expression is interpreted as the output value. But if the code,
+   on the other hand, is a multiline expression (<replaceable>one-liner</replaceable> is
+   false), the form has to be output using <literal>@(return)
+   =...</literal>. Multiple values are returned as <literal>@(return 0)=... ;
+   @(return 1)=...;</literal>. Finally, Lisp constants may be used in the C code
+   making use of the prefix <literal>@</literal>.</para>
+   <programlisting>
+    (use-package "FFI")
+
+    (Clines "
+    #include &lt;math.h&gt;
+
+    double foo (double x, double y) {
+    return sinh(x) * y;
+    }")
+
+    (defvar *a*
+    (c-inline (1.23) (:double) :double
+    "foo(#0,1.44)"
+    :side-effects nil
+    :one-liner t))
+
+    (defvar *b*
+    (c-inline (1.23) (:double) :double
+    "{cl_object x = symbol_value(@*a*);
+    @(return) = foo(#0,object_to_float(x));}"
+    :side-effects nil
+    :one-liner nil))
+   </programlisting>
+  </blockquote>
+ </section>
+
+ <section id="Internals-The-C-language-interface">
+  <title>The C language interface</title>
+  <para>Using these special forms <literal>clines</literal> and <literal>c-inline</literal>, plus the ability to
+  handle pointers to foreign data, we have built a rather complete FFI for
+  interfacing with the C world. This interface is compatible with the UFFI
+  specification, which can be found in the web. We recommend you to grab the
+  documentation from this package and read it carefully. All examples should
+  run unmodified under &ECL; (Of course, you do not need to download UFFI
+  itself, as everything is already implemented in &ECL;.</para>
+  <para>However, because &ECL; provides some additional functionality which escapes the
+  UFFI, and also for compatibility with older versions of the &ECL; environment,
+  we provide additional toplevel forms, which are listed in the next section.</para>
+ </section>
+
+ <section id="Internals-The-old-C-language-interface">
+  <title>The old C language interface</title>
+  <para>In this section we list several macros and toplevel forms which are provided
+  either for convenience or for compatibility with older versions of &ECL;.
+  You should avoid using them when the UFFI-compatible interface provides
+  similar functionality.</para>
+  <para>We define some terminology here which is used throughout this Section. A
+  <emphasis>C-id</emphasis> is either a Lisp string consisting of a valid C-language
+  identifier, or a Lisp symbol whose print-name, with all its alphabetic
+  characters turned into lower case, is a valid C identifier.  Thus the symbol
+  <literal>foo</literal> is equivalent to the string <literal>"foo"</literal> when used as a C-id.
+  Similarly, a <emphasis>C-expr</emphasis> is a string that may be regarded as a
+  C-language expression.  A <emphasis>C-type</emphasis> is one of the Lisp symbols
+  <literal>:int, :char, :float, :double,...</literal> and <literal>:object</literal>.
+  Each corresponds to a data type in the C language; <literal>:object</literal> is
+  the type of Lisp object and other C-types are primitive data types in C.</para>
+  <blockquote>
+   <screen><indexterm role="fn"><primary>defentry</primary></indexterm>&mdash; Macro: <function>defentry</function> <varname>{</varname><varname>function</varname> <varname>parameter-list</varname> <varname>C-function</varname><varname>}</varname></screen>
+   <para><literal>defentry</literal> defines a Lisp function whose body consists of the calling
+   sequence to a C-language function. <replaceable>function</replaceable> is the name of the Lisp
+   function to be defined, and <replaceable>C-function</replaceable> specifies the C function to be
+   invoked. <replaceable>C-function</replaceable> must be either a list <literal>(<replaceable>type C-id</replaceable>)</literal> or
+   <replaceable>C-id</replaceable>, where <replaceable>type</replaceable> and <replaceable>C-id</replaceable> are the type and the name of the C
+   function. <replaceable>type</replaceable> must be a C-type or the symbol <literal>void</literal> which means
+   that the C function returns no value.  <literal>(object <replaceable>C-id</replaceable>)</literal> may be
+   abbreviated as <replaceable>C-id</replaceable>.  <replaceable>parameter-list</replaceable> is a list of C-types for the
+   parameters of the C function.  For example, the following <literal>defentry</literal> form
+   defines a Lisp function <literal>tak</literal> from which the C function <literal>tak</literal> above
+   is called.</para>
+  </blockquote>
+  <programlisting>(defentry tak (:int :int :int) (:int tak))
+  </programlisting>
+  <para>The Lisp function <literal>tak</literal> defined by this <literal>defentry</literal> form requires
+  three arguments.  The arguments are converted to <literal>int</literal> values before they
+  are passed to the C function.  On return from the C function, the returned
+  <literal>int</literal> value is converted to a Lisp integer (actually a fixnum) and this
+  fixnum will be returned as the value of the Lisp function.  See below for type
+  conversion between Lisp and the C language.</para>
+  <para>A <literal>defentry</literal> form is treated in the above way only when it appears as a
+  top-level form of a Lisp source file.  Otherwise, a <literal>defentry</literal> form
+  expands to ().</para>
+  <blockquote>
+   <screen><indexterm role="fn"><primary>defla</primary></indexterm>&mdash; Macro: <function>defla</function> <varname>{</varname><varname>name</varname> <varname>lambda-list</varname> <varname>{</varname><varname>declaration</varname> <varname>|</varname> <varname>doc-string</varname><varname>}</varname><varname>*</varname><varname>}</varname></screen>
+   <para>When interpreted, <literal>defla</literal> is exactly the same as <literal>defun</literal>.  That is,
+   <literal>(defla <replaceable>name lambda-list .  body</replaceable>)</literal> expands to <literal>(defun <replaceable>name
+   lambda-list .  body</replaceable>)</literal>.  However, <literal>defla</literal> forms are completely ignored by
+   the compiler; no C-language code will be generated for <literal>defla</literal> forms.  The
+   primary use of <literal>defla</literal> is to define a Lisp function in two ways within a
+   single Lisp source file; one in the C language and the other in Lisp.
+   <literal>defla</literal> is short for <emphasis>DEF</emphasis>ine <emphasis>L</emphasis>isp <emphasis>A</emphasis>lternative.</para>
+  </blockquote>
+  <para>Suppose you have a Lisp source file whose contents are:</para>
+  <programlisting>(use-package "FFI")
+
+  ;;; C version of TAK.
+  (Clines "
+
+  int tak(x, y, z)
+  int x, y, z;
+  {      if (y &gt;= x) return(z);
+  else return(tak(tak(x-1, y, z),
+  tak(y-1, z, x),
+  tak(z-1, x, y)));
+  }
+  "
+  )
+
+  ;;;  TAK calls the C function tak defined above.
+  (defentry tak (:int :int :int) (:int tak))
+  ;;;  The alternative Lisp definition of TAK.
+  (defla tak (x y z)
+  (if (&gt;= y x)
+  z
+  (tak (tak (1- x) y z)
+  (tak (1- y) z x)
+  (tak (1- z) x y))))
+  </programlisting>
+  <para>When this file is loaded into &ECL;, the interpreter uses the Lisp version of
+  the <literal>tak</literal> definition.  Once this file has been compiled, and when the
+  generated fasl file is loaded into &ECL;, a function call to <literal>tak</literal> is
+  actually the call to the C version of <literal>tak</literal>.</para>
+  <blockquote>
+   <screen><indexterm role="fn"><primary>defCbody</primary></indexterm>&mdash; Function: <function>defCbody</function> <varname>name args-types result-type C-expr</varname></screen>
+
+   <para>The &ECL; compiler produces a function named
+   <replaceable>name</replaceable> with as many arguments as
+   <replaceable>arg-types</replaceable>.  The
+   <replaceable>C-expr</replaceable> is an arbitrary C expression where the
+   arguments to the function are denoted by
+   <literal>#</literal><replaceable>i</replaceable>, where
+   <replaceable>i</replaceable> is the integer corresponding to the argument
+   position.  The <replaceable>args-types</replaceable> is the list of
+   Common-Lisp types of the arguments to the function, while
+   <replaceable>result-type</replaceable> is the Common-Lisp type of the
+   result.  The actual arguments are coerced to the required types before
+   executing the <replaceable>C-expr</replaceable> and the result is
+   converted into a Lisp object.  <literal>defCbody</literal> is ignored by
+   the interpreter.</para>
+
+  </blockquote>
+  <para>For example, the logical AND of two integers could be defined as:</para>
+  <programlisting>(defCbody logand (fixnum fixnum) fixnum "(#0) &amp; (#1)")
+  </programlisting>
+  <blockquote>
+   <screen><indexterm role="fn"><primary>definline</primary></indexterm>&mdash; Function: <function>definline</function> <varname>{</varname><varname>name</varname> <varname>args-types</varname> <varname>result-type</varname> <varname>C-expr</varname><varname>}</varname></screen>
+   <para><literal>definline</literal> behaves exactly as <literal>defCbody</literal>.  Moreover, after a
+   <literal>definline</literal> definition has been supplied, the &ECL; compiler will expand
+   inline any call to function <replaceable>name</replaceable> into code corresponding to the C
+   language expression <replaceable>C-expr</replaceable>, provided that the actual arguments are of the
+   specified type.  If the actual arguments cannot be coerced to those types, the
+   inline expansion is not performed.  <literal>definline</literal> is ignored by the
+   interpreter.</para>
+  </blockquote>
+  <para>For example, a function to access the n-th byte of a string and return it as an
+  integer can be defined as follows:</para>
+  <programlisting>(definline aref-byte (string fixnum) fixnum
+  "(#0)-&gt;ust.ust_self[#1]")
+  </programlisting>
+  <para>The definitions of the C data structures used to represent \clisp objects can
+  be found in file <literal>ecl.h</literal> in the directory <literal>"src/h"</literal> of the source
+  distribution.</para>
+  <para>&ECL; converts a Lisp object into a C-language data by using the Common-Lisp
+  function <literal>coerce</literal>: For the C-type <literal>int</literal> (or <literal>char</literal>), the object
+  is first coerced to a Lisp integer and the least significant 32-bit (or 8-bit)
+  field is used as the C <literal>int</literal> (or <literal>char</literal>).  For the C-type
+  <literal>float</literal> (or <literal>double</literal>), the object is coerced to a single-float (or a
+  double-float) and this value is used as the <literal>C float</literal> (or <literal>double</literal>).
+  Conversion from a C data into a Lisp object is obvious: <literal>C char, int,
+  float,</literal> and <literal>double</literal> become the equivalent Lisp <literal>character</literal>,
+  <literal>fixnum</literal>, <literal>single-float</literal>, and <literal>double-float</literal>, respectively.</para>
+  <para>Here we list the complete syntax of <literal>Clines</literal>, <literal>defentry</literal>,
+  <literal>definline</literal> and <literal>defCbody</literal> macro forms.</para>
+  <screen><![CDATA[
+  Clines-form:
+  (Clines @{string@}*)
+
+  defentry-form:
+  (defentry symbol (@{C-type@}*)
+  @{C-function-name | (@{C-type | void@} C-function-name)@})
+
+  defCbody-form:
+  (defCbody symbol (@{type@}*) type C-expr)
+
+  definline-form:
+  (defCbody symbol (@{type@}*) type C-expr)
+
+  C-function-name:
+  @{ string | symbol @}
+  C-expr:
+  string
+  C-type:
+  @{ object | int | char | float | double @}
+  ]]></screen>
+  <!--  -->
+ </section>
 </chapter>
 
-<chapter xml:id="Porting-ECL">
+<chapter id="The-Garbage-Collector">
+ <title>The Garbage Collector</title>
+ <para>Using &ECL; in existing application sometimes involves keeping Lisp
+ objects where the garbage collector normally cannot see them.</para>
+ <!-- FIXME: Complete this... -->
+ <!--  -->
+</chapter>
+
+<chapter id="Porting-ECL">
  <title>Porting &ECL;</title>
  <para>To port &ECL; to a new architecture, the following steps are required:</para>
  <orderedlist numeration="arabic">
@@ -1384,19 +1642,15 @@
   <listitem>
    <para>Ensure that the Boehm-Weiser garbage collector is supported by that
    architecture. Alternatively, port ECL's own garbage collector
-   <filename>src/c/alloc.d</filename> and <filename>src/c/gbc.d</filename> to
-   that platform.</para>
+   <filename>src/c/alloc.d</filename> and <filename>src/c/gbc.d</filename> to that platform.</para>
   </listitem>
   <listitem>
-   <para>Fix <filename>src/aclocal.in</filename>,
-   <filename>src/h/config.h.in</filename> and
-   <filename>src/h/ecl.h</filename> so that they supply flags for the new
-   host machine.</para>
+   <para>Fix <filename>src/aclocal.in</filename>, <filename>src/h/ecl.h</filename> and <filename>src/h/ecl-cmp.h</filename>
+   so that they supply flags for the new host machine.</para>
   </listitem>
   <listitem>
-   <para>Fix the machine dependent code in <filename>src/c/</filename>. The
-   most critical parts are in the <filename>unix*.d</filename> and
-   <filename>thread*.d</filename> files.</para>
+   <para>Fix the machine dependent code in <filename>src/c/</filename>. The most critical
+   parts are in the <filename>unix*</filename> and <filename>thread*</filename> files.</para>
   </listitem>
   <listitem>
    <para>Compile as in any other platform.</para>