r2784: *** empty log message ***

[uffi.git] / doc / intro.sgml

diff --git a/doc/intro.sgml b/doc/intro.sgml
index df58ab6683625a9f0144e945f97ab212b7cbd7f5..35e2ba5294e8781264a63f811b0ae9aab36b1bee 100644 (file)
--- a/doc/intro.sgml
+++ b/doc/intro.sgml
@@ -38,25 +38,68 @@ particular C-library.
 
   <sect1>
     <title>Supported Implementations</title> 
-    <para> The primary tested and supported platforms for &uffi; are: 
+    <para>The primary tested and supported platforms for &uffi; are: 
     </para>
     <itemizedlist mark="opencircle">
-      <listitem><para>&acl; v6.1 on Redhat Linux 7.2 and Microsoft Windows.</para></listitem>
-      <listitem><para>&lw; v4.2 on Redhat Linux 7.2 and Microsoft Windows.</para></listitem>
-      <listitem><para>&cmucl; 18c on Redhat Linux 7.2.</para></listitem>
+      <listitem><para>&acl; v6.2 on Debian GNU/Linux
+FreeBSD 4.5, Solaris v2.8, and Microsoft Windows XP.</para></listitem>
+      <listitem><para>&lw; v4.2 on Debian GNU/Linux and Microsoft Windows XP.</para></listitem>
+      <listitem><para>&cmucl; 18d-pre on Debian GNU/Linux, FreeBSD 4.5, and Solaris 2.8</para></listitem>
+    </itemizedlist>
+    <para>Beta code is included with &uffi; for
+    </para>
+    <itemizedlist mark="opencircle">
+      <listitem><para>&openmcl; and &mcl; with MacOSX</para></listitem>
     </itemizedlist>
   </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>