r8185: convert programlisting to screen

diff --git a/doc/bookinfo.xml b/doc/bookinfo.xml
index 0ae614266c10961f31b0f9948ae44797ac52ee34..42044c34a542ec7cba986d8bd1758f3dfebec5c1 100644 (file)
--- a/doc/bookinfo.xml
+++ b/doc/bookinfo.xml
@@ -49,25 +49,27 @@
        </para>
       </listitem>
       <listitem>
-       <para><application>Allegro CL</application>&reg; is a registered
+       <para>
+         <application>Allegro CL</application>&reg; is a registered
          trademark of Franz Inc.
        </para>
       </listitem>
       <listitem>
-       <para><application>Lispworks</application>&reg; is a registered
+       <para>
+         <application>Lispworks</application>&reg; is a registered
          trademark of Xanalys Inc.
        </para>
       </listitem>
       <listitem>
-       <para><application>Microsoft
-         Windows</application>&reg; is a registered trademark of
-         Microsoft Inc.
+       <para>
+         <application>Microsoft Windows</application>&reg; is a
+         registered trademark of Microsoft Inc.
        </para>
       </listitem>
       <listitem>
-       <para>Other brand or
-         product names are the registered trademarks or trademarks of
-         their respective holders.
+       <para>
+         Other brand or product names are the registered trademarks
+         or trademarks of their respective holders.
        </para>
       </listitem>
     </itemizedlist>

diff --git a/doc/notes.xml b/doc/notes.xml
index 139267ebc454a98c80b6e3b17f2906ba59aca3e7..7d6d366cbe3175fc024d906bd525cc19a235c2a4 100644 (file)
--- a/doc/notes.xml
+++ b/doc/notes.xml
@@ -81,12 +81,12 @@
       <para>
        Here is an example that should both methods being used for
        maximum cross-implementation optimization:
-       <programlisting>
+       <screen>
 (uffi:def-type the-struct-type-def the-struct-type)
 (let ((a-foreign-struct (allocate-foreign-object 'the-struct-type)))
   (declare 'the-struct-type-def a-foreign-struct)
   (get-slot-value a-foreign-struct 'the-struct-type 'field-name))
-       </programlisting>
+       </screen>
       </para>
     </sect2>
   </sect1>

diff --git a/doc/ref_aggregate.xml b/doc/ref_aggregate.xml
index 75c384f592887aac0a66794b4d1b49f8459b6ebf..5aa86441135946ce540b3f5896fe97622c63b6ee 100644 (file)
--- a/doc/ref_aggregate.xml
+++ b/doc/ref_aggregate.xml
@@ -70,7 +70,7 @@ a foreign type with the name <parameter>name</parameter> of type
       </refsect1>
       <refsect1>
        <title>Examples</title>
-       <programlisting>
+       <screen>
 (def-enum abc (:a :b :c)) 
 ;; Creates constants abc#a (1), abc#b (2), abc#c (3) and defines
 ;; the foreign type "abc" to be :int
@@ -78,7 +78,7 @@ a foreign type with the name <parameter>name</parameter> of type
 (def-enum efoo (:e1 (:e2 10) :e3) :separator-string "-")
 ;; Creates constants efoo-e1 (1), efoo-e2 (10), efoo-e3 (11) and defines
 ;; the foreign type efoo to be :int
-       </programlisting>
+       </screen>
       </refsect1>
       <refsect1>
        <title>Side Effects</title>
@@ -138,12 +138,12 @@ structure. It's type is <constant>:pointer-self</constant>.
       </refsect1>
       <refsect1>
        <title>Examples</title>
-       <programlisting>
+       <screen>
 (def-struct foo (a :unsigned-int) 
                 (b (* :char)) 
                 (c (:array :int 10)) 
                 (next :pointer-self))
-       </programlisting>
+       </screen>
       </refsect1>
       <refsect1>
        <title>Side Effects</title>
@@ -214,9 +214,9 @@ structure. It's type is <constant>:pointer-self</constant>.
       </refsect1>
       <refsect1>
        <title>Examples</title>
-       <programlisting>
+       <screen>
 (get-slot-value foo-ptr 'foo-structure 'field-name)
-       </programlisting>
+       </screen>
       </refsect1>
       <refsect1>
        <title>Side Effects</title>
@@ -287,9 +287,9 @@ structure. It's type is <constant>:pointer-self</constant>.
       </refsect1>
       <refsect1>
        <title>Examples</title>
-       <programlisting>
+       <screen>
 (get-slot-pointer foo-ptr 'foo-structure 'my-char-ptr)
-       </programlisting>
+       </screen>
       </refsect1>
       <refsect1>
        <title>Side Effects</title>
@@ -346,9 +346,9 @@ structure. It's type is <constant>:pointer-self</constant>.
       </refsect1>
       <refsect1>
        <title>Examples</title>
-       <programlisting>
+       <screen>
 (def-array-pointer byte-array-pointer :unsigned-char)
-       </programlisting>
+       </screen>
       </refsect1>
       <refsect1>
        <title>Side Effects</title>
@@ -420,14 +420,14 @@ the array.
       </refsect1>
       <refsect1>
        <title>Examples</title>
-       <programlisting>
+       <screen>
 (def-array-pointer ca :char)
 (let ((fs (convert-to-foreign-string "ab")))
    (values (null-char-p (deref-array fs 'ca 0))
            (null-char-p (deref-array fs 'ca 2))))
 => &nil;
    &t;
-       </programlisting>
+       </screen>
       </refsect1>
       <refsect1>
        <title>Notes</title>
@@ -491,7 +491,7 @@ the array.
       </refsect1>
       <refsect1>
        <title>Examples</title>
-       <programlisting>
+       <screen>
 (def-union test-union
   (a-char :char)
   (an-int :int))
@@ -502,7 +502,7 @@ the array.
     (ensure-char-character (get-slot-value u 'test-union 'a-char))
     (free-foreign-object u)))
 => #\A
-       </programlisting>
+       </screen>
       </refsect1>
       <refsect1>
        <title>Side Effects</title>

diff --git a/doc/ref_declare.xml b/doc/ref_declare.xml
index 1e40da6c8dc8150141028466a7863c61f543c79d..ddbd818170d927f4e3f2885a07f07c17bff76bdd 100644 (file)
--- a/doc/ref_declare.xml
+++ b/doc/ref_declare.xml
@@ -57,13 +57,13 @@
     </refsect1>
     <refsect1>
       <title>Examples</title>
-      <programlisting>
+      <screen>
 (def-type char-ptr '(* :char))
 ...
 (defun foo (ptr)
 (declare (type char-ptr ptr))
 ...
-      </programlisting>
+      </screen>
     </refsect1>
     <refsect1>
       <title>Side Effects</title>

diff --git a/doc/ref_func_libr.xml b/doc/ref_func_libr.xml
index 0e48d59fde91c7f4e790040115a5dea1d56f5e3b..7a366dbfdb6372ce2635ad6aea8b82f65fa9e1ad 100644 (file)
--- a/doc/ref_func_libr.xml
+++ b/doc/ref_func_libr.xml
@@ -61,12 +61,12 @@ foreign function. If <constant>:void</constant> indicates module does not return
       </refsect1>
       <refsect1>
        <title>Examples</title>
-       <programlisting>
+       <screen>
 (def-function "gethostname" 
   ((name (* :unsigned-char))
    (len :int))
   :returning :int)
-       </programlisting>
+       </screen>
       </refsect1>
       <refsect1>
        <title>Side Effects</title>
@@ -150,12 +150,12 @@ a session. A library can be reloaded by using the <symbol>:force-load</symbol> k
       </refsect1>
       <refsect1>
        <title>Examples</title>
-       <programlisting>
+       <screen>
   (load-foreign-library #p"/usr/lib/libmysqlclient.so" 
                         :module "mysql" 
                         :supporting-libraries '("c"))
     => T
-       </programlisting>
+       </screen>
       </refsect1>
       <refsect1>
        <title>Side Effects</title>
@@ -234,13 +234,13 @@ the path of the first found file.
       </refsect1>
       <refsect1>
        <title>Examples</title>
-       <programlisting>
+       <screen>
 (find-foreign-library '("libmysqlclient" "libmysql")
     '("/opt/mysql/lib/mysql/" "/usr/local/lib/" "/usr/lib/" "/mysql/lib/opt/")
     :types '("so" "dll")
     :drive-letters '("C" "D" "E"))
 => #P"D:\\mysql\\lib\\opt\\libmysql.dll"
-       </programlisting>
+       </screen>
       </refsect1>
       <refsect1>
        <title>Side Effects</title>

diff --git a/doc/ref_object.xml b/doc/ref_object.xml
index 226f0be98f122c358d2d47da22375981e8655f5e..893121977c95277d0fdfbedd3eecfe24a039ff7a 100644 (file)
--- a/doc/ref_object.xml
+++ b/doc/ref_object.xml
@@ -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>
@@ -710,7 +710,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 +721,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 +796,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 +809,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 +835,7 @@ value of a variable in foreign code.
 
 (foo)
   => 4
-</programlisting>
+</screen>
 </refsect2>
       </refsect1>
       <refsect1>

diff --git a/doc/ref_primitive.xml b/doc/ref_primitive.xml
index 8ab12862d53a4548df46f9fb4dd8a5a104a90324..eed908c0bdb8bc8e7f4e8607acdff6ec37f16137 100644 (file)
--- a/doc/ref_primitive.xml
+++ b/doc/ref_primitive.xml
@@ -126,10 +126,10 @@
     </refsect1>
     <refsect1>
       <title>Examples</title>
-      <programlisting>
+      <screen>
 (def-constant pi2 (* 2 pi))
 (def-constant exported-pi2 (* 2 pi) :export t)
-      </programlisting>
+      </screen>
     </refsect1>
     <refsect1>
       <title>Side Effects</title>
@@ -185,11 +185,11 @@
     </refsect1>
     <refsect1>
       <title>Examples</title>
-      <programlisting>
+      <screen>
 (def-foreign-type my-generic-pointer :pointer-void)
 (def-foreign-type a-double-float :double-float)
 (def-foreign-type char-ptr (* :char))
-      </programlisting>
+      </screen>
     </refsect1>
     <refsect1>
       <title>Side Effects</title>
@@ -253,14 +253,14 @@
     </refsect1>
     <refsect1>
       <title>Examples</title>
-      <programlisting>
+      <screen>
 (def-array-pointer ca :unsigned-char)
 (let ((fs (convert-to-foreign-string "ab")))
       (values (null-char-p (deref-array fs 'ca 0))
       (null-char-p (deref-array fs 'ca 2))))
 => &nil;
    &t;
-      </programlisting>
+      </screen>
     </refsect1>
     <refsect1>
       <title>Side Effects</title>

diff --git a/doc/ref_string.xml b/doc/ref_string.xml
index 19416145ccefe4b19b778c3b13df52ad7092b38e..d488e12b38c7e76cedb4d6453760d673be7cb227 100644 (file)
--- a/doc/ref_string.xml
+++ b/doc/ref_string.xml
@@ -6,42 +6,41 @@
 ]>
 
 <reference id="strings">
-      <title>Strings</title>
-<partintro>
-<title>Overview</title>
-<para>
-
-         &uffi; has functions to two types of
-<varname>C</varname>-compatible
-         strings: <emphasis>cstring</emphasis> and
-<emphasis>foreign</emphasis> strings.
-
-cstrings are used <emphasis>only</emphasis> as parameters to and from
-functions. In some implementations a cstring is not a foreign type but
-rather the Lisp string itself. On other platforms a cstring is a newly
-allocated foreign vector for storing characters. The following is an
-example of using cstrings to both send and return a value.  
-</para>
-
-<programlisting>
+  <title>Strings</title>
+  <partintro>
+    <title>Overview</title>
+    <para>
+      &uffi; has functions to two types of <varname>C</varname>-compatible
+      strings: <emphasis>cstring</emphasis> and <emphasis>foreign</emphasis>
+      strings.  cstrings are used <emphasis>only</emphasis> as parameters to
+      and from functions. In some implementations a cstring is not a foreign
+      type but rather the Lisp string itself. On other platforms a cstring
+      is a newly allocated foreign vector for storing characters. The
+      following is an example of using cstrings to both send and return a
+      value.
+    </para>
+    
+    <screen>
 (uffi:def-function ("getenv" c-getenv) 
-    ((name :cstring))
-  :returning :cstring)
+   ((name :cstring))
+   :returning :cstring)
 
 (defun my-getenv (key)
   "Returns an environment variable, or NIL if it does not exist"
   (check-type key string)
   (uffi:with-cstring (key-native key)
     (uffi:convert-from-cstring (c-getenv key-native))))
-</programlisting>
+    </screen>
 
-<para> In contrast, foreign strings are always a foreign vector of
-characters which have memory allocated. Thus, if you need to allocate
-memory to hold the return value of a string, you must use a foreign
-string and not a cstring.  The following is an example of using a foreign
-string for a return value.  </para>
+    <para>
+      In contrast, foreign strings are always a foreign vector of
+      characters which have memory allocated. Thus, if you need to
+      allocate memory to hold the return value of a string, you must
+      use a foreign string and not a cstring.  The following is an
+      example of using a foreign string for a return value.
+    </para>
 
-<programlisting>
+    <screen>
 (uffi:def-function ("gethostname" c-gethostname)
     ((name (* :unsigned-char))
      (len :int))
@@ -56,14 +55,16 @@ string for a return value.  </para>
     (uffi:free-foreign-object name)
     (unless (zerop result-code)
       (error "gethostname() failed."))))
-</programlisting>
+    </screen>
 
-<para>  Foreign functions that return pointers to freshly allocated
-strings should in general not return cstrings, but foreign strings.
-(There is no portable way to release such cstrings from Lisp.)  The
-following is an example of handling such a function.  </para>
+    <para>
+      Foreign functions that return pointers to freshly allocated
+      strings should in general not return cstrings, but foreign
+      strings. (There is no portable way to release such cstrings from
+      Lisp.) The following is an example of handling such a function.
+    </para>
 
-<programlisting>
+    <screen>
 (uffi:def-function ("readline" c-readline)
     ((prompt :cstring))
   :returning (* :char))
@@ -75,21 +76,23 @@ following is an example of handling such a function.  </para>
              (str (convert-from-foreign-string c-str)))
         (uffi:free-foreign-object c-str)
         str)))
-</programlisting>
-
-</partintro>
-
+    </screen>
+    
+  </partintro>
+  
     <refentry id="convert-from-cstring">
       <refnamediv>
        <refname>convert-from-cstring</refname>
-       <refpurpose>Converts a cstring to a Lisp string.
-       </refpurpose>
+       <refpurpose>Converts a cstring to a Lisp string.</refpurpose>
        <refclass>Macro</refclass>
       </refnamediv>
       <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>
-         <function>convert-from-cstring</function> <replaceable>cstring</replaceable> => <returnvalue>string</returnvalue>
+         <function>convert-from-cstring</function>
+         <replaceable>cstring</replaceable> 
+         => 
+         <returnvalue>string</returnvalue>
        </synopsis>
       </refsynopsisdiv>
       <refsect1>
@@ -115,8 +118,8 @@ following is an example of handling such a function.  </para>
        <title>Description</title>
        <para>
          Converts a Lisp string to a <constant>cstring</constant>. This is
-most often used when processing the results of a foreign function
-that returns a cstring.
+         most often used when processing the results of a foreign function
+         that returns a cstring.
        </para>
       </refsect1>
       <refsect1>
@@ -131,161 +134,163 @@ that returns a cstring.
        <title>Exceptional Situations</title>
        <para>None.</para>
       </refsect1>
-    </refentry>
-
-
-    <refentry id="convert-to-cstring">
-      <refnamediv>
-       <refname>convert-to-cstring</refname>
-       <refpurpose>Converts a Lisp string to a cstring.
-       </refpurpose>
-       <refclass>Macro</refclass>
-      </refnamediv>
-      <refsynopsisdiv>
-       <title>Syntax</title>
-       <synopsis>
-         <function>convert-to-cstring</function> <replaceable>string</replaceable> => <returnvalue>cstring</returnvalue>
-       </synopsis>
-      </refsynopsisdiv>
-      <refsect1>
-       <title>Arguments and Values</title>
-       <variablelist>
-         <varlistentry>
-           <term><parameter>string</parameter></term>
-           <listitem>
-             <para>A Lisp string.
-             </para>
-           </listitem>
-         </varlistentry>
-         <varlistentry>
-           <term><returnvalue>cstring</returnvalue></term>
-           <listitem>
-             <para>A cstring.
-             </para>
-           </listitem>
-         </varlistentry>
-       </variablelist>
-      </refsect1>
-      <refsect1>
-       <title>Description</title>
-       <para>
-         Converts a Lisp string to a
-         <varname>cstring</varname>. The
-         <varname>cstring</varname> should be freed with
-         <function>free-cstring</function>.
-       </para>
-      </refsect1>
-      <refsect1>
-       <title>Side Effects</title>
-       <para>On some implementations, this function allocates memory.</para>
-      </refsect1>
-      <refsect1>
-       <title>Affected by</title>
-       <para>None.</para>
-      </refsect1>
-      <refsect1>
-       <title>Exceptional Situations</title>
-       <para>None.</para>
-      </refsect1>
-    </refentry>
-
-
-    <refentry id="free-cstring">
-      <refnamediv>
-       <refname>free-cstring</refname>
-       <refpurpose>Free memory used by cstring.
-       </refpurpose>
-       <refclass>Macro</refclass>
-      </refnamediv>
-      <refsynopsisdiv>
-       <title>Syntax</title>
-       <synopsis>
-         <function>free-cstring</function> <replaceable>cstring</replaceable>
-       </synopsis>
-      </refsynopsisdiv>
-      <refsect1>
-       <title>Arguments and Values</title>
-       <variablelist>
-         <varlistentry>
-           <term><parameter>cstring</parameter></term>
-           <listitem>
-             <para>A cstring.
-             </para>
-           </listitem>
-         </varlistentry>
-       </variablelist>
-      </refsect1>
-      <refsect1>
-       <title>Description</title>
-       <para>
-         Frees any memory possibly allocated by
-         <function>convert-to-cstring</function>. On some implementions, a cstring is just the Lisp string itself.
-       </para>
-      </refsect1>
-      <refsect1>
-       <title>Side Effects</title>
-       <para>None.</para>
-      </refsect1>
-      <refsect1>
-       <title>Affected by</title>
-       <para>None.</para>
-      </refsect1>
-      <refsect1>
-       <title>Exceptional Situations</title>
-       <para>None.</para>
-      </refsect1>
-    </refentry>
-
-
-    <refentry id="with-cstring">
-      <refnamediv>
-       <refname>with-cstring</refname>
-       <refpurpose>Binds a newly created cstring.
-       </refpurpose>
-       <refclass>Macro</refclass>
-      </refnamediv>
-      <refsynopsisdiv>
-       <title>Syntax</title>
-       <synopsis>
-         <function>with-cstring</function> <replaceable>(cstring string) {body}</replaceable>
-       </synopsis>
-      </refsynopsisdiv>
-      <refsect1>
-       <title>Arguments and Values</title>
-       <variablelist>
-         <varlistentry>
-           <term><parameter>cstring</parameter></term>
-           <listitem>
-             <para>A symbol naming the cstring to be created.
-             </para>
-           </listitem>
-         </varlistentry>
-         <varlistentry>
-           <term><parameter>string</parameter></term>
-           <listitem>
-             <para>A Lisp string that will be translated to a cstring.
-             </para>
-           </listitem>
-         </varlistentry>
-         <varlistentry>
-           <term><parameter>body</parameter></term>
-           <listitem>
-             <para>The body of where the cstring will be bound.
-             </para>
-           </listitem>
-         </varlistentry>
-       </variablelist>
-      </refsect1>
-      <refsect1>
-       <title>Description</title>
-       <para>
-         Binds a symbol to a cstring created from conversion of a string. Automatically frees the <varname>cstring</varname>.
-       </para>
-      </refsect1>
-      <refsect1>
-       <title>Examples</title>
-       <para>
-           <programlisting>
+  </refentry>
+  
+  
+  <refentry id="convert-to-cstring">
+    <refnamediv>
+      <refname>convert-to-cstring</refname>
+      <refpurpose>Converts a Lisp string to a cstring.</refpurpose>
+      <refclass>Macro</refclass>
+    </refnamediv>
+    <refsynopsisdiv>
+      <title>Syntax</title>
+      <synopsis>
+       <function>convert-to-cstring</function> 
+       <replaceable>string</replaceable>
+       =>
+       <returnvalue>cstring</returnvalue>
+      </synopsis>
+    </refsynopsisdiv>
+    <refsect1>
+      <title>Arguments and Values</title>
+      <variablelist>
+       <varlistentry>
+         <term><parameter>string</parameter></term>
+         <listitem>
+           <para>A Lisp string.
+           </para>
+         </listitem>
+       </varlistentry>
+       <varlistentry>
+         <term><returnvalue>cstring</returnvalue></term>
+         <listitem>
+           <para>A cstring.
+           </para>
+         </listitem>
+       </varlistentry>
+      </variablelist>
+    </refsect1>
+    <refsect1>
+      <title>Description</title>
+      <para>
+       Converts a Lisp string to a <varname>cstring</varname>. The
+       <varname>cstring</varname> should be freed with
+       <function>free-cstring</function>.
+      </para>
+    </refsect1>
+    <refsect1>
+      <title>Side Effects</title>
+      <para>On some implementations, this function allocates memory.</para>
+    </refsect1>
+    <refsect1>
+      <title>Affected by</title>
+      <para>None.</para>
+    </refsect1>
+    <refsect1>
+      <title>Exceptional Situations</title>
+      <para>None.</para>
+    </refsect1>
+  </refentry>
+  
+  
+  <refentry id="free-cstring">
+    <refnamediv>
+      <refname>free-cstring</refname>
+      <refpurpose>Free memory used by cstring.
+      </refpurpose>
+      <refclass>Macro</refclass>
+    </refnamediv>
+    <refsynopsisdiv>
+      <title>Syntax</title>
+      <synopsis>
+       <function>free-cstring</function> <replaceable>cstring</replaceable>
+      </synopsis>
+    </refsynopsisdiv>
+    <refsect1>
+      <title>Arguments and Values</title>
+      <variablelist>
+       <varlistentry>
+         <term><parameter>cstring</parameter></term>
+         <listitem>
+           <para>A cstring.
+           </para>
+         </listitem>
+       </varlistentry>
+      </variablelist>
+    </refsect1>
+    <refsect1>
+      <title>Description</title>
+      <para>
+       Frees any memory possibly allocated by
+       <function>convert-to-cstring</function>. On some implementions, a cstring is just the Lisp string itself.
+      </para>
+    </refsect1>
+    <refsect1>
+      <title>Side Effects</title>
+      <para>None.</para>
+    </refsect1>
+    <refsect1>
+      <title>Affected by</title>
+      <para>None.</para>
+    </refsect1>
+    <refsect1>
+      <title>Exceptional Situations</title>
+      <para>None.</para>
+    </refsect1>
+  </refentry>
+  
+  
+  <refentry id="with-cstring">
+    <refnamediv>
+      <refname>with-cstring</refname>
+      <refpurpose>Binds a newly created cstring.</refpurpose>
+      <refclass>Macro</refclass>
+    </refnamediv>
+    <refsynopsisdiv>
+      <title>Syntax</title>
+      <synopsis>
+       <function>with-cstring</function>
+       <replaceable>(cstring string) {body}</replaceable>
+      </synopsis>
+    </refsynopsisdiv>
+    <refsect1>
+      <title>Arguments and Values</title>
+      <variablelist>
+       <varlistentry>
+         <term><parameter>cstring</parameter></term>
+         <listitem>
+           <para>A symbol naming the cstring to be created.
+           </para>
+         </listitem>
+       </varlistentry>
+       <varlistentry>
+         <term><parameter>string</parameter></term>
+         <listitem>
+           <para>A Lisp string that will be translated to a cstring.
+           </para>
+         </listitem>
+       </varlistentry>
+       <varlistentry>
+         <term><parameter>body</parameter></term>
+         <listitem>
+           <para>The body of where the cstring will be bound.
+           </para>
+         </listitem>
+       </varlistentry>
+      </variablelist>
+    </refsect1>
+    <refsect1>
+      <title>Description</title>
+      <para>
+       Binds a symbol to a cstring created from conversion of a
+       string. Automatically frees the <varname>cstring</varname>.
+      </para>
+    </refsect1>
+    <refsect1>
+      <title>Examples</title>
+      <para>
+       <screen>
 (def-function ("getenv" c-getenv) 
    ((name :cstring))
    :returning :cstring)
@@ -295,209 +300,213 @@ that returns a cstring.
   (check-type key string)
   (with-cstring (key-cstring key)
     (convert-from-cstring (c-getenv key-cstring))))
-           </programlisting>
-         </para>
-       </refsect1>
-      <refsect1>
-       <title>Side Effects</title>
-       <para>None.</para>
-      </refsect1>
-      <refsect1>
-       <title>Affected by</title>
-       <para>None.</para>
-      </refsect1>
-      <refsect1>
-       <title>Exceptional Situations</title>
-       <para>None.</para>
-      </refsect1>
-    </refentry>
-
-
-    <refentry id="convert-from-foreign-string">
-      <refnamediv>
-       <refname>convert-from-foreign-string</refname>
-       <refpurpose>Converts a foreign string into a Lisp string.
-       </refpurpose>
-       <refclass>Macro</refclass>
-      </refnamediv>
-      <refsynopsisdiv>
-       <title>Syntax</title>
-       <synopsis>
-         <function>convert-from-foreign-string</function> <replaceable>foreign-string &amp;key length null-terminated-p</replaceable> => <returnvalue>string</returnvalue>
-       </synopsis>
-      </refsynopsisdiv>
-      <refsect1>
-       <title>Arguments and Values</title>
-       <variablelist>
-         <varlistentry>
-           <term><parameter>foreign-string</parameter></term>
-           <listitem>
-             <para>A foreign string.
-             </para>
-           </listitem>
-         </varlistentry>
-         <varlistentry>
-           <term><parameter>length</parameter></term>
-           <listitem>
-             <para>The length of the foreign string to
-convert. The default is the length of the string until a &null;
-character is reached.
-             </para>
-           </listitem>
-         </varlistentry>
-         <varlistentry>
-           <term><parameter>null-terminated-p</parameter></term>
-           <listitem>
-             <para>A boolean flag with a default value of &t; When true,
-the string is converted until the first &null; character is reached.
-             </para>
-           </listitem>
-         </varlistentry>
-         <varlistentry>
-           <term><returnvalue>string</returnvalue></term>
-           <listitem>
-             <para>A Lisp string.
-             </para>
-           </listitem>
-         </varlistentry>
-       </variablelist>
-      </refsect1>
-      <refsect1>
-       <title>Description</title>
-       <para>
-         Returns a Lisp string from a foreign string. 
-Can translated ASCII and binary strings.
-       </para>
-      </refsect1>
-      <refsect1>
-       <title>Side Effects</title>
-       <para>None.</para>
-      </refsect1>
-      <refsect1>
-       <title>Affected by</title>
-       <para>None.</para>
-      </refsect1>
-      <refsect1>
-       <title>Exceptional Situations</title>
-       <para>None.</para>
-      </refsect1>
-    </refentry>
-
-
-    <refentry id="convert-to-foreign-string">
-      <refnamediv>
-       <refname>convert-to-foreign-string</refname>
-       <refpurpose>Converts a Lisp string to a foreign string.
-       </refpurpose>
-       <refclass>Macro</refclass>
-      </refnamediv>
-      <refsynopsisdiv>
-       <title>Syntax</title>
-       <synopsis>
-         <function>convert-to-foreign-string</function> <replaceable>string</replaceable> => <returnvalue>foreign-string</returnvalue>
-       </synopsis>
-      </refsynopsisdiv>
-      <refsect1>
-       <title>Arguments and Values</title>
-       <variablelist>
-         <varlistentry>
-           <term><parameter>string</parameter></term>
-           <listitem>
-             <para>A Lisp string.
-             </para>
-           </listitem>
-         </varlistentry>
-         <varlistentry>
-           <term><returnvalue>foreign-string</returnvalue></term>
-           <listitem>
-             <para>A foreign string.
-             </para>
-           </listitem>
-         </varlistentry>
-       </variablelist>
-      </refsect1>
-      <refsect1>
-       <title>Description</title>
-       <para>
-         Converts a Lisp string to a foreign string. Memory should be
-         freed with <function>free-foreign-object</function>.
-       </para>
-      </refsect1>
-      <refsect1>
-       <title>Side Effects</title>
-       <para>None.</para>
-      </refsect1>
-      <refsect1>
-       <title>Affected by</title>
-       <para>None.</para>
-      </refsect1>
-      <refsect1>
-       <title>Exceptional Situations</title>
-       <para>None.</para>
-      </refsect1>
-    </refentry>
-
-
-
-    <refentry id="allocate-foreign-string">
-      <refnamediv>
-       <refname>allocate-foreign-string</refname>
-       <refpurpose>Allocates space for a foreign string.
-       </refpurpose>
-       <refclass>Macro</refclass>
-      </refnamediv>
-      <refsynopsisdiv>
-       <title>Syntax</title>
-       <synopsis>
-         <function>allocate-foreign-string</function> <replaceable>size &amp;key unsigned</replaceable> => <returnvalue>foreign-string</returnvalue>
-       </synopsis>
-      </refsynopsisdiv>
-      <refsect1>
-       <title>Arguments and Values</title>
-       <variablelist>
-         <varlistentry>
-           <term><parameter>size</parameter></term>
-           <listitem>
-             <para>The size of the space to be allocated in bytes.
-             </para>
-           </listitem>
-         </varlistentry>
-         <varlistentry>
-           <term><parameter>unsigned</parameter></term>
-           <listitem>
-             <para>A boolean flag with a default value of &t;. When true,
-marks the pointer as an <constant>:unsigned-char</constant>.
-             </para>
-           </listitem>
-         </varlistentry>
-         <varlistentry>
-           <term><returnvalue>foreign-string</returnvalue></term>
-           <listitem>
-             <para>A foreign string which has undefined contents.
-             </para>
-           </listitem>
-         </varlistentry>
-       </variablelist>
-      </refsect1>
-      <refsect1>
-       <title>Description</title>
-       <para>
-         Allocates space for a foreign string. Memory should
-         be freed with <function>free-foreign-object</function>.
-       </para>
-      </refsect1>
-      <refsect1>
-       <title>Side Effects</title>
-       <para>None.</para>
-      </refsect1>
-      <refsect1>
-       <title>Affected by</title>
-       <para>None.</para>
-      </refsect1>
-      <refsect1>
-       <title>Exceptional Situations</title>
-       <para>None.</para>
-      </refsect1>
-    </refentry>
-
-  </reference>
+       </screen>
+      </para>
+    </refsect1>
+    <refsect1>
+      <title>Side Effects</title>
+      <para>None.</para>
+    </refsect1>
+    <refsect1>
+      <title>Affected by</title>
+      <para>None.</para>
+    </refsect1>
+    <refsect1>
+      <title>Exceptional Situations</title>
+      <para>None.</para>
+    </refsect1>
+  </refentry>
+  
+  
+  <refentry id="convert-from-foreign-string">
+    <refnamediv>
+      <refname>convert-from-foreign-string</refname>
+      <refpurpose>Converts a foreign string into a Lisp string.</refpurpose>
+      <refclass>Macro</refclass>
+    </refnamediv>
+    <refsynopsisdiv>
+      <title>Syntax</title>
+      <synopsis>
+       <function>convert-from-foreign-string</function>
+       <replaceable>foreign-string &amp;key length null-terminated-p</replaceable>
+       =>
+       <returnvalue>string</returnvalue>
+      </synopsis>
+    </refsynopsisdiv>
+    <refsect1>
+      <title>Arguments and Values</title>
+      <variablelist>
+       <varlistentry>
+         <term><parameter>foreign-string</parameter></term>
+         <listitem>
+           <para>A foreign string.
+           </para>
+         </listitem>
+       </varlistentry>
+       <varlistentry>
+         <term><parameter>length</parameter></term>
+         <listitem>
+           <para>The length of the foreign string to convert. The
+           default is the length of the string until a &null;
+           character is reached.
+           </para>
+         </listitem>
+       </varlistentry>
+       <varlistentry>
+         <term><parameter>null-terminated-p</parameter></term>
+         <listitem>
+           <para>A boolean flag with a default value of &t; When true,
+           the string is converted until the first &null; character is reached.
+           </para>
+         </listitem>
+       </varlistentry>
+       <varlistentry>
+         <term><returnvalue>string</returnvalue></term>
+         <listitem>
+           <para>A Lisp string.
+           </para>
+         </listitem>
+       </varlistentry>
+      </variablelist>
+    </refsect1>
+    <refsect1>
+      <title>Description</title>
+      <para>
+       Returns a Lisp string from a foreign string. 
+       Can translated ASCII and binary strings.
+      </para>
+    </refsect1>
+    <refsect1>
+      <title>Side Effects</title>
+      <para>None.</para>
+    </refsect1>
+    <refsect1>
+      <title>Affected by</title>
+      <para>None.</para>
+    </refsect1>
+    <refsect1>
+      <title>Exceptional Situations</title>
+      <para>None.</para>
+    </refsect1>
+  </refentry>
+  
+  
+  <refentry id="convert-to-foreign-string">
+    <refnamediv>
+      <refname>convert-to-foreign-string</refname>
+      <refpurpose>Converts a Lisp string to a foreign string.
+      </refpurpose>
+      <refclass>Macro</refclass>
+    </refnamediv>
+    <refsynopsisdiv>
+      <title>Syntax</title>
+      <synopsis>
+       <function>convert-to-foreign-string</function>
+       <replaceable>string</replaceable> =>
+       <returnvalue>foreign-string</returnvalue>
+      </synopsis>
+    </refsynopsisdiv>
+    <refsect1>
+      <title>Arguments and Values</title>
+      <variablelist>
+       <varlistentry>
+         <term><parameter>string</parameter></term>
+         <listitem>
+           <para>A Lisp string.
+           </para>
+         </listitem>
+       </varlistentry>
+       <varlistentry>
+         <term><returnvalue>foreign-string</returnvalue></term>
+         <listitem>
+           <para>A foreign string.
+           </para>
+         </listitem>
+       </varlistentry>
+      </variablelist>
+    </refsect1>
+    <refsect1>
+      <title>Description</title>
+      <para>
+       Converts a Lisp string to a foreign string. Memory should be
+       freed with <function>free-foreign-object</function>.
+      </para>
+    </refsect1>
+    <refsect1>
+      <title>Side Effects</title>
+      <para>None.</para>
+    </refsect1>
+    <refsect1>
+      <title>Affected by</title>
+      <para>None.</para>
+    </refsect1>
+    <refsect1>
+      <title>Exceptional Situations</title>
+      <para>None.</para>
+    </refsect1>
+  </refentry>
+  
+  <refentry id="allocate-foreign-string">
+    <refnamediv>
+      <refname>allocate-foreign-string</refname>
+      <refpurpose>Allocates space for a foreign string.
+      </refpurpose>
+      <refclass>Macro</refclass>
+    </refnamediv>
+    <refsynopsisdiv>
+      <title>Syntax</title>
+      <synopsis>
+       <function>allocate-foreign-string</function> <replaceable>size
+       &amp;key unsigned</replaceable> =>
+       <returnvalue>foreign-string</returnvalue>
+      </synopsis>
+    </refsynopsisdiv>
+    <refsect1>
+      <title>Arguments and Values</title>
+      <variablelist>
+       <varlistentry>
+         <term><parameter>size</parameter></term>
+         <listitem>
+           <para>The size of the space to be allocated in bytes.
+           </para>
+         </listitem>
+       </varlistentry>
+       <varlistentry>
+         <term><parameter>unsigned</parameter></term>
+         <listitem>
+           <para>A boolean flag with a default value of &t;. When true,
+           marks the pointer as an <constant>:unsigned-char</constant>.
+           </para>
+         </listitem>
+       </varlistentry>
+       <varlistentry>
+         <term><returnvalue>foreign-string</returnvalue></term>
+         <listitem>
+           <para>A foreign string which has undefined contents.
+           </para>
+         </listitem>
+       </varlistentry>
+      </variablelist>
+    </refsect1>
+    <refsect1>
+      <title>Description</title>
+      <para>
+       Allocates space for a foreign string. Memory should
+       be freed with <function>free-foreign-object</function>.
+      </para>
+    </refsect1>
+    <refsect1>
+      <title>Side Effects</title>
+      <para>None.</para>
+    </refsect1>
+    <refsect1>
+      <title>Affected by</title>
+      <para>None.</para>
+    </refsect1>
+    <refsect1>
+      <title>Exceptional Situations</title>
+      <para>None.</para>
+    </refsect1>
+  </refentry>
+  
+</reference>