r11214: 2006-10-10 Kevin Rosenberg (kevin@rosenberg.net)

[uffi.git] / doc / ref_object.xml

diff --git a/doc/ref_object.xml b/doc/ref_object.xml
index ef6b1215dc2b1c0a6132e6b8c6726e076d798c37..ed76892089168cf6c95f8d66003b8b605dce86c2 100644 (file)
--- a/doc/ref_object.xml
+++ b/doc/ref_object.xml
@@ -1,7 +1,7 @@
-<?xml version='1.0' ?>   <!-- -*- DocBook -*- -->
+<?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-               "file:///usr/share/sgml/docbook/dtd/xml/4.2/docbookx.dtd" [
-<!ENTITY % myents SYSTEM "entities.xml">
+               "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+<!ENTITY % myents SYSTEM "entities.inc">
 %myents;
 ]>
 
@@ -64,11 +64,11 @@ array of <parameter>type</parameter> that is <parameter>size</parameter> members
       </refsect1>
       <refsect1>
        <title>Examples</title>
-       <programlisting>
+       <screen>
 (def-struct ab (a :int) (b :double))
 (allocate-foreign-object 'ab)
 => #&lt;ptr&gt;
-       </programlisting>
+       </screen>
       </refsect1>
       <refsect1>
        <title>Side Effects</title>
@@ -181,14 +181,14 @@ much better with static allocation.
       </refsect1>
       <refsect1>
        <title>Examples</title>
-       <programlisting>
+       <screen>
 (defun gethostname2 ()
   "Returns the hostname"
   (uffi:with-foreign-object (name '(:array :unsigned-char 256))
     (if (zerop (c-gethostname (uffi:char-array-to-pointer name) 256))
        (uffi:convert-from-foreign-string name)
        (error "gethostname() failed."))))
-       </programlisting>
+       </screen>
       </refsect1>
       <refsect1>
        <title>Side Effects</title>
@@ -238,12 +238,12 @@ much better with static allocation.
       <refsect1>
        <title>Examples</title>
        <para>
-<programlisting>
+<screen>
 (size-of-foreign-object :unsigned-byte)
 => 1
 (size-of-foreign-object 'my-100-byte-vector-type)
 => 100
-</programlisting>
+</screen>
         </para>
       </refsect1>
       <refsect1>
@@ -360,14 +360,14 @@ much better with static allocation.
       <refsect1>
        <title>Examples</title>
        <para>
-<programlisting>
+<screen>
 (let ((intp (allocate-foreign-object :int)))
   (setf (deref-pointer intp :int) 10)
   (prog1
     (deref-pointer intp :int)
     (free-foreign-object intp)))
 => 10
-</programlisting>
+</screen>
        </para>
       </refsect1>
       <refsect1>
@@ -436,13 +436,13 @@ pointers are a lisp character.
       <refsect1>
        <title>Examples</title>
        <para>
-<programlisting>
+<screen>
 (let ((fs (convert-to-foreign-string "a")))
   (prog1 
     (ensure-char-character (deref-pointer fs :char))
     (free-foreign-object fs)))
 => #\a
-</programlisting>
+</screen>
        </para>
       </refsect1>
       <refsect1>
@@ -504,13 +504,13 @@ an integer.
       <refsect1>
        <title>Examples</title>
        <para>
-<programlisting>
+<screen>
 (let ((fs (convert-to-foreign-string "a")))
   (prog1 
     (ensure-char-integer (deref-pointer fs :char))
     (free-foreign-object fs)))
 => 96
-</programlisting>
+</screen>
        </para>
       </refsect1>
       <refsect1>
@@ -667,6 +667,13 @@ if a cstring returned by a function is &null;.
       <refsect1>
        <title>Arguments and Values</title>
        <variablelist>
+         <varlistentry>
+           <term><parameter>binding-name</parameter></term>
+           <listitem>
+             <para>A symbol which will be bound to the casted object.
+             </para>
+           </listitem>
+         </varlistentry>
          <varlistentry>
            <term><parameter>ptr</parameter></term>
            <listitem>
@@ -693,12 +700,9 @@ if a cstring returned by a function is &null;.
       <refsect1>
        <title>Description</title>
        <para>
-  Executes BODY with POINTER cast to be a pointer to type TYPE. If
-  BINDING-NAME is provided the cast pointer will be bound to this
-  name during the execution of BODY. If BINDING-NAME is not provided
-  POINTER must be a name bound to the pointer which should be
-  cast. This name will be bound to the cast pointer during the
-  execution of BODY.
+  Executes BODY with POINTER cast to be a pointer to type TYPE.
+  BINDING-NAME is will be bound to this value during the execution of
+  BODY.
 
   This is a no-op in AllegroCL but will wrap BODY in a LET form if
   BINDING-NAME is provided.
@@ -710,7 +714,7 @@ if a cstring returned by a function is &null;.
       </refsect1>
       <refsect1>
        <title>Examples</title>
-<programlisting>
+<screen>
 (with-foreign-object (size :int)
    ;; FOO is a foreign function returning a :POINTER-VOID
    (let ((memory (foo size)))
@@ -721,7 +725,7 @@ if a cstring returned by a function is &null;.
            (dotimes (i (deref-pointer size :int))
             (do-something-with
               (deref-array memory '(:array :unsigned-byte) i)))))))
-</programlisting>
+</screen>
       </refsect1>
       <refsect1>
        <title>Side Effects</title>
@@ -796,7 +800,7 @@ value of a variable in foreign code.
        <title>Examples</title>
        <refsect2>
        <title>C code</title>
-<programlisting>
+<screen>
   int baz = 3;
 
   typedef struct {
@@ -809,11 +813,11 @@ value of a variable in foreign code.
   int foo () {
     return baz;
   }
-</programlisting>
+</screen>
 </refsect2>
 <refsect2>
 <title>Lisp code</title>
-<programlisting>
+<screen>
   (uffi:def-struct foo-struct
     (x :int)
     (y :double))
@@ -835,7 +839,7 @@ value of a variable in foreign code.
 
 (foo)
   => 4
-</programlisting>
+</screen>
 </refsect2>
       </refsect1>
       <refsect1>