X-Git-Url: http://git.kpe.io/?a=blobdiff_plain;f=doc%2Fintro.sgml;h=6f8b9b6f7e02744127624e191c9d62fc9e5b8183;hb=a831d46a26cd75fe1d6884191a3a08b54185138b;hp=23b4c7c8c27f51f02d7a6ab5afabc62e53be6f1d;hpb=d5d0bfb15f7a30ac5398211708f5f5d9d4a95e04;p=uffi.git

diff --git a/doc/intro.sgml b/doc/intro.sgml
index 23b4c7c..6f8b9b6 100644
--- a/doc/intro.sgml
+++ b/doc/intro.sgml
@@ -5,8 +5,8 @@
   <sect1>
     <title>Purpose</title>
     <para> This reference guide describes
-      &uffi;, a Lisp package that provides persistent cross-implementation
-      support of C-language compatible libraries.
+      &uffi;, a package that provides a cross-implementation
+      interface from Common Lisp to C-language compatible libraries.
     </para>
   </sect1>
 
@@ -16,10 +16,12 @@
     <para>
       Every Common Lisp implementation has
       a method for interfacing to C-language compatible
-      libraries. Unfortunately, these method vary widely amongst
-      implementations. Currently, to support multiple implementations,
-      developers must write a different interface library for each Common
-      Lisp implementation.
+      libraries. These methods are often termed a 
+      <emphasis>Foreign Function Library Interface</emphasis>
+      (&ffi;). Unfortunately, these methods vary widely
+      amongst
+      implementations, thus preventing the writing of a portable FFI to a 
+particular C-library. 
     </para>
     <para>
       &uffi; gathers a common subset of functionality between Common Lisp
@@ -46,15 +48,52 @@
   </sect1>
 
     <sect1>
-      <title>Design Overview</title>
-      <para>
-	&uffi; was designed as a cross-implementation compatible 
-	<emphasis>Foreign Function Interface</emphasis>. Necessarily,
-	only a common subset of functionality can be
-	provided. Likewise, not every optimization for that a specific
-	implementation provides can be supported. Wherever possible,
-	though, implementation-specific optimizations are invoked.
-      </para> 
+      <title>Design</title>
+      <sect2>
+	<title>Overview</title>
+	<para>
+	  &uffi; was designed as a cross-implementation 
+	  compatible <emphasis>Foreign Function Interface</emphasis>.
+	  Necessarily,
+	  only a common subset of functionality can be
+	  provided. Likewise, not every optimization for that a specific
+	  implementation provides can be supported. Wherever possible,
+	  though, implementation-specific optimizations are invoked.
+	</para> 
+      </sect2>
+
+      <sect2>
+	<title>Priorities</title>
+	<para>
+	  The design of &uffi; is dictated by the order of these priorities:
+	</para>
+	<itemizedlist>
+	  <listitem>
+	    <para>
+	      Code using &uffi; must operate correctly on all
+	      supported implementations.
+	    </para>
+	  </listitem>
+	  <listitem>
+	    <para>
+	      Take advantage of implementation-specific optimizations. Ideally, 
+	      there will not a situation where an implementation-specific
+	      &ffi; will be chosen due to lack of optimizations in &uffi;.
+	    </para>
+	  </listitem>
+	  <listitem>
+	    <para>Provide a simple interface to developers using
+&uffi;.  This priority is quite a bit lower than the above priorities.
+This lower priority is manifest by programmers having to pass types in
+pointer and array dereferencing, needing to use
+<constant>cstring</constant> wrapper functions, and the use of
+ensure-char-character and ensure-char-integer functions. My hope is
+that the developer inconvenience will be outweighed by the generation
+of optimized code that is cross-implementation compatible.
+	    </para>
+	  </listitem>
+	</itemizedlist>
+      </sect2>
     </sect1>
 
 </chapter>