From 8d9ce4e810889737f23e242c6ff3ba20c6d78c0d Mon Sep 17 00:00:00 2001
From: Liam Healy <liam@thinkpad.local>
Date: Sun, 31 Aug 2008 22:57:15 -0400
Subject: [PATCH] Updated documentation

Updated the documentation to reflect changes in the new branch with
foreign-friendly arrays.  This is now better reflective or the current
definitions, but work needs to be done.  Added a dependency that was
missing: matrix exponential needs special functions to define sf-mode.
---
 documentation/development.html   |  25 +++-----
 documentation/documentation.html | 100 +++++++++++++++++++++----------
 documentation/index.html         |  31 +++-------
 gsll.asd                         |   4 +-
 init/conditions.lisp             |  10 +++-
 5 files changed, 97 insertions(+), 73 deletions(-)

diff --git a/documentation/development.html b/documentation/development.html
index c855b75a..7bc19d03 100644
--- a/documentation/development.html
+++ b/documentation/development.html
@@ -39,11 +39,6 @@
   equivalent probably won't be done, unless there is a need to have it
   present for some other GSL functionality that isn't present in CL.
   </li>
-  <li>Data types that are not defined in Common Lisp portably (such as
- uint) may not be well supported.  Others may be added but it
- may be difficult to do so in a portable way.  There are several
- macros to help with the definitions.
- </li>
   </ul>
 
  <h3>Status</h3>
@@ -60,18 +55,16 @@
   particularly known failures.
   It is possible that the library API will change but probably not
    substantially; most of the remaining work is to fix bugs.
-   <p>
-   Wishlist features include:<ul>
-  <li>Native vectors like <code>sb-sys:vector-sap</code> in SBCL.
-  </ul>
-
 
  <h3>Contributions</h3>
- Contributions to the development of GSLL are welcome; see
- the <a href="http://trac.common-lisp.net/gsll">Trac page</a> .
- This make take the form of bug reports and fixes, suggestions for new
- interface design, or of porting the remaining unported functions.
-   The supplied macros
+ Contributions to the development of GSLL are welcome; the primary
+ way to get started is by posting to the
+ <a href="http://common-lisp.net/cgi-bin/mailman/listinfo/gsll-devel">mailing
+  list</a>; also see
+  the <a href="http://trac.common-lisp.net/gsll">Trac page</a>.  A
+  contribution may take the form of bug reports and fixes, suggestions
+  for new interface design, porting the remaining unported
+  functions, testing on a new platform or compiler.  The supplied macros
    <code>defmfun</code> and <code>defmpar</code>
    define virtually all of the interface functions and variables
    respectively, which simplifies the process of porting. 
@@ -96,7 +89,7 @@ See <a href="documentation.html">documentation</a> regarding known failures.
     <hr>
     <address><a href="mailto:gsll-devel@common-lisp.net">Liam Healy</a></address>
     <small>
-       Time-stamp: <2008-03-08 11:07:51EST development.html>
+       Time-stamp: <2008-08-31 20:14:05EDT development.html>
        </small>
 <!-- hhmts end -->
  </div>
diff --git a/documentation/documentation.html b/documentation/documentation.html
index fb4ef587..8afcb5b6 100644
--- a/documentation/documentation.html
+++ b/documentation/documentation.html
@@ -62,18 +62,15 @@ href="http://www.lispworks.com/documentation/HyperSpec/Body/s_let_l.htm#letST">l
 with the additional feature that if the init-form is one of GSL objects
 
 <pre>
-acceleration basis-spline block-complex block-double-float block-fixnum
-block-single-float chebyshev combination complex-workspace
+acceleration basis-spline chebyshev combination complex-workspace
 discrete-random eigen-herm eigen-hermv eigen-symm eigen-symmv
 fdfsolver fit-workspace fminimizer fsolver hankel histogram
 integration-workspace interpolation levin levin-truncated
-matrix-complex matrix-double-float matrix-fixnum
-matrix-single-float mfdfminimizer mfdfsolver mfminimizer mfsolver
+matrix-* mfdfminimizer mfdfsolver mfminimizer mfsolver
 monte-carlo-miser monte-carlo-plain monte-carlo-vegas
 nonlinear-fdffit nonlinear-ffit permutation
 quasi-random-number-generator random-number-generator spline
-vector-complex vector-double-float vector-fixnum
-vector-single-float wavelet wavelet-workspace
+vector-* wavelet wavelet-workspace
 </pre>
 the appropriate object will be allocated and bound to the variable,
 optionally set, and then freed when the body of the let is exited.
@@ -82,28 +79,70 @@ are functions whose symbols are exported so that an arglist prompt
 will be visible; however, the function should not be used outside a
 <code>letm</code> binding.
 
- <h3>Data: vectors, matrices, etc.</h3>
+ <h3>Data: vectors and matrices</h3>
  <div class="content">
  <p>
- Collectively, vectors, matrices, histograms and the like are called
- <i>data</i>.  There are many different types of vectors and matrices
- supported by GSL, but GSLL has implemented only a few of these:
- complex, double-float, single-float, and fixnum, because those types
- are defined by the Common Lisp standard.
- <p>FIXME Vectors and matrices can be converted to and from their Lisp
- counterparts with <code>data</code> and <code>(setf data)</code>.
- Setting the GSL value to a Lisp value at initialization
- can be done within the <code>letm</code> by giving the Lisp value as
- the first argument after the type, for example
+ Collectively vectors and matrices and are called
+ <i>data</i>.  GSLL supports all element types that are supported by
+ CFFI, the CL implementation, and GSL.  This list is
+ available in the variable <code>*array-element-types*</code>.
+ These arrays are <i>foreign-friendly</i>, meaning that 
+ on platforms that support it (currently only SBCL), the contents are
+ directly available to the GSL functions without copying between the
+ Lisp area and the C area of memory.
+ <p>
+ Common Lisp arrays should be created with <code>make-array*</code>;
+ the syntax is similar to Common Lisp's <code>make-array</code>
+ except that the second argument <code>element-type</code> is
+ mandatory.  If this function is used, the resultant array is
+ foreign friendly.  It can then be used as an argument in the letm
+ binding.  Alternatively, a literal array can be created in the letm
+ binding using the macros <code>a</code> (non-evaluating)
+ or <code>a*</code> (evaluating).
+ <p>
+ Classes of vectors and matrices are names by appending the element
+ type as hypenated words to "vector" or "matrix".  The following table
+ shows the classes available on SBCL on an amd64 platform.
+ <center>
+  <table border=5 frame=all cellpadding=4 cellspacing=4 cols=6>
+    <caption align=top>Element types, vector and matrix
+    classes</caption>
+    <thead>
+      <tr><th>Element type<td><b>Vector class name</b><td><b>Matrix class name</b>
+    </thead>
+	<tbody>
+	  <tr><td>single-float<td>vector-single-float<td>matrix-single-float
+	  <tr><td>double-float<td>vector-double-float<td>matrix-double-float
+	  <tr><td>(complex single-float)<td>vector-complex-single-float<td>matrix-complex-single-float
+	  <tr><td>(complex double-float)<td>vector-complex-double-float<td>matrix-complex-double-float
+	  <tr><td>(signed-byte 8)<td>vector-signed-byte-8<td>matrix-signed-byte-8
+	  <tr><td>(unsigned-byte 8)<td>vector-unsigned-byte-8<td>matrix-unsigned-byte-8
+	  <tr><td>(signed-byte 16)<td>vector-signed-byte-16<td>matrix-signed-byte-16
+	  <tr><td>(unsigned-byte 16)<td>vector-unsigned-byte-16<td>matrix-unsigned-byte-16
+	  <tr><td>(signed-byte 32)<td>vector-signed-byte-32<td>matrix-signed-byte-32
+	  <tr><td>(unsigned-byte 32)<td>vector-unsigned-byte-32<td>matrix-unsigned-byte-32
+	  <tr><td>(signed-byte 64)<td>vector-signed-byte-64<td>matrix-signed-byte-64
+	  <tr><td>(unsigned-byte 64)<td>vector-unsigned-byte-64<td>matrix-unsigned-byte-64
+	</tbody>
+      </table>
+    </center>
+              
+<p>
+ The class name serves as the binding form in the letm.  For example,
+ the following form sums two vectors:
 <pre>
-(letm ((vec (vector-double-float (a -3.21d0 1.0d0 12.8d0))))
-   (???? vec))
+(letm ((vec1 (vector-double-float (a -3.21d0 1.0d0 12.8d0)))
+       (vec2 (vector-double-float (a -1.88d0 -1.0d0 4.1d0))))
+   (m+ vec1 vec2))
+#&lt;VECTOR-DOUBLE-FLOAT #(-5.09d0 0.0d0 16.9d0)&gt;
 </pre>
 <p>
- Individual elements of data may be accessed with <code>maref</code>,
- either directly or in a <code>setf</code>.
- The macro #'a is a convenience for the specification of an array
- with literal content.
+ Individual elements are obtained using <code>maref</code> (analogous
+ to Lisp's <code>aref</code>), and are set
+ with <code>setf maref</code>.  A complete CL array may
+ be extracted with the function <code>#'cl-array</code>.  This array
+ may subsequently be used in later GSL functions by providing it as
+ the argument in the letm binding.
 </p>
 
  <h3>Status</h3>
@@ -113,14 +152,11 @@ will be visible; however, the function should not be used outside a
  on particular chapters:
 <ul>
 <base href="http://www.gnu.org/software/gsl/manual/html_node/">
-<li><a href="Vectors-and-Matrices.html">Vectors and Matrices</a>
-	are done for integer, real, double, complex.
-	 Subvectors and views don't work.  Other element types may be
-        difficult to port due to lack of CL definition.
-<li>Functions that provide file input and output to files are not tested and
- likely will need other definitions (perhaps in C) to function
- properly, unless CFFI and the CL platform provide C stream
- compatibility.
+  <li>Reading and writing through the GSL library is not supported due
+  to lack of support for foreign streams in Lisp.</li>
+  <li>For <a href="Vectors-and-Matrices.html">Vectors and Matrices</a>,
+	 subvectors and views are not defined.  In many functions, the
+	 stride is pre-set to 1. 
 <li><a href="BLAS-Support.html">BLAS</a> is completed, but with only very
  limited testing.
  <li><a href="Fast-Fourier-Transforms.html">FFTs</a> have not been done
@@ -154,7 +190,7 @@ gamma-randist, negative-binomial.
     <address><a href="mailto:gsll-devel@common-lisp.net">Liam Healy</a></address>
 <!-- hhmts start -->
     <small>
-      Time-stamp: <2008-08-31 17:21:56EDT documentation.html>
+      Time-stamp: <2008-08-31 18:40:51EDT documentation.html>
       </small>
 <!-- hhmts end -->
  </div>
diff --git a/documentation/index.html b/documentation/index.html
index ebaf0144..9b5528ff 100644
--- a/documentation/index.html
+++ b/documentation/index.html
@@ -84,15 +84,16 @@ Input domain error |m| > 1.0 in elljac.c at line 46
         <ul>
         <li><a href="http://www.gnu.org/software/gsl/">GSL</a></li>
         <li><a href="http://common-lisp.net/project/cffi/">CFFI</a>
-        (Note: you will need a version <i>newer</i> than the current version
-	0.9.2. Use the darcs repository, a newer tarball, or Debian
-	testing/unstable.)</li>
+	  (Version 0.10.0 or newer,
+	  or <a href="http://packages.debian.org/lenny/cl-cffi">the
+	  version in Debian/lenny</a>)
+	</li>
         <li><a href="http://www.cliki.net/asdf">ASDF</a>
           </ul>
       <p>
-        In <a href="http://www.debian.org">Debian</a> unstable or testing,
+        In <a href="http://www.debian.org">Debian</a> Lenny (5.0) or newer,
         the following should work:</p>
-      <blockquote><pre>apt-get install <a
+      <blockquote><pre>aptitude install <a
         href="http://packages.debian.org/lenny/libgsl0ldbl">libgsl0ldbl</a> <a href="http://packages.debian.org/lenny/cl-cffi">cl-cffi</a></pre></blockquote>
       (asdf is automatically installed with your CL implementation).
       Once your CL implementation is running, do
@@ -111,20 +112,6 @@ Input domain error |m| > 1.0 in elljac.c at line 46
  <div class="content">
  <p>You may browse or download as follows:</p>
  <ul>
- <li><a href="http://subversion.tigris.org/">Subversion</a>:
-	  Repository at
-	  svn://common-lisp.net/project/gsll/svn/trunk.  For
-	  example, 
-<pre>
-svn list svn://common-lisp.net/project/gsll/svn/trunk
-svn checkout svn://common-lisp.net/project/gsll/svn/trunk gsll
-</pre>
- <li>Web:
-	<a href="http://trac.common-lisp.net/gsll/browser/trunk">browse</a>
-	using Trac.
- <li>Git: Thanks to Leonardo Varuzza, who is maintaining a 
- <a href="http://www.lambdatau.com/git/gsll.git">git mirror</a>
- of the Subversion repository.
  </ul>
  <p>Due to frequent changes, no tarballs are yet available.</p>
  </div>
@@ -144,12 +131,12 @@ svn checkout svn://common-lisp.net/project/gsll/svn/trunk gsll
 
  <h3>Similar or related projects from others</h3>
   <div class="content">
-  A partial automatically-generated interface to GSL is provided in <a
-  href="http://common-lisp.net/project/cl-gsl/">cl-gsl</a>.
   A Matlab-like array syntax and plotting is provided by
   <a href="http://nlisp.info/">NLISP</a> which might work well with
   GSLL.  Other numerical mathematics software for Lisp may be found 
   <a href="http://www.cliki.net/Mathematics">on Clicki</a>. 
+  A partial interface to GSL is provided in <a
+  href="http://common-lisp.net/project/cl-gsl/">cl-gsl</a>.
   </div>
 
  <div class="footer">
@@ -158,7 +145,7 @@ svn checkout svn://common-lisp.net/project/gsll/svn/trunk gsll
 <!-- Created: Feb 25 2005 -->
 <!-- hhmts start -->
     <small>
-       Time-stamp: <2008-03-27 23:08:11EDT index.html>
+       Time-stamp: <2008-08-31 22:54:34EDT index.html>
        </small>
 <!-- hhmts end -->
  </div>
diff --git a/gsll.asd b/gsll.asd
index d3dcf438..352ca80c 100644
--- a/gsll.asd
+++ b/gsll.asd
@@ -1,6 +1,6 @@
 ;; Definition of GSLL system 
 ;; Liam Healy
-;; Time-stamp: <2008-08-31 12:49:38EDT gsll.asd>
+;; Time-stamp: <2008-08-31 22:50:22EDT gsll.asd>
 ;; $Id$
 
 (asdf:defsystem "gsll"
@@ -78,7 +78,7 @@
 	     (:file "zeta" :depends-on (return-structures))))
    (:file "sorting" :depends-on (init data))
    (:module linear-algebra
-	    :depends-on (init data)
+	    :depends-on (init data special-functions)
 	    :components
 	    ((:file "blas1")
 	     (:file "blas2")
diff --git a/init/conditions.lisp b/init/conditions.lisp
index 9eb44bd0..9e5086b6 100644
--- a/init/conditions.lisp
+++ b/init/conditions.lisp
@@ -1,6 +1,6 @@
 ;; GSL errors                                
 ;; Liam Healy Sat Mar  4 2006 - 18:33
-;; Time-stamp: <2008-03-27 23:07:29EDT conditions.lisp>
+;; Time-stamp: <2008-08-31 22:52:09EDT conditions.lisp>
 ;; $Id$
 
 (in-package :gsl)
@@ -26,6 +26,14 @@
   (:documentation
    "A condition that has been signalled by the GNU Scientific Library."))
 
+#|
+;;; This makes the printing of the condition object more informative,
+;;; but also overrides the :report which I don't want to do.
+(defmethod print-object ((object gsl-condition) stream)
+  (print-unreadable-object (object stream :type t :identity t) 
+    (format stream "~a (GSL condition)" (error-text object))))
+|#
+
 (defparameter *errorno-keyword* nil)
 
 (defmacro define-gsl-condition (keyword number text)
-- 
GitLab