Changeset 13646

Timestamp:

10/20/11 23:55:27 (12 years ago)

Author:

Mark Evenson

Message:

Getting out the burrs.

File:

• branches/1.0.x/abcl/doc/manual/abcl.tex (modified) (12 diffs)

branches/1.0.x/abcl/doc/manual/abcl.tex

@@ -18 +18 @@
 
 \subsection{Version}
-This manual corresponds to abcl-1.0.0, release on October 22, 2011.
+This manual corresponds to abcl-1.0.0, released on October 22, 2011.
 
 \chapter{Running}
 
 \textsc{ABCL} is packaged as a single jar file usually named either
-``abcl.jar'' or possibly``abcl-1.0.0.jar'' if you are using a
-versioned package from your system vendor.  This byte archive can be
-executed under the control of a suitable JVM by using the ``-jar''
-option to parse the manifest, and select the named class
+``abcl.jar'' or possibly``abcl-1.0.0.jar'' if one is using a versioned
+package from your system vendor.  This byte archive can be executed
+under the control of a suitable JVM by using the ``-jar'' option to
+parse the manifest, and select the named class
 (\code{org.armedbear.lisp.Main}) for execution:
 
 \begin{listing-shell}
-  cmd\$ java -jar abcl.jar
+  cmd$ java -jar abcl.jar
 \end{listing-shell}
 
@@ -42 +42 @@
 
 \begin{listing-shell}
-  cmd\$ abcl
+  cmd$ abcl
 \end{listing-shell}
 
@@ -97 +97 @@
 \end{itemize}
 
-ABCL aims to be be a fully conforming ANSI Common Lisp
-implementation.  Any other behavior should be reported as a bug.
+ABCL aims to be be a fully conforming ANSI Common Lisp implementation.
+Any other behavior should be reported as a bug.
 
 \section{Contemporary Common Lisp}
 In addition to ANSI conformance, \textsc{ABCL} strives to implement features
 expected of a contemporary Common Lisp.
+
+\subsection{Deficiencies}
+The following known problems detract from \textsc{ABCL} being a proper
+contemporary Comon Lisp.
 \begin{itemize}
-  \item Incomplete (A)MOP 
+  \item Incomplete (A)MOP \footnote{Another Metaobject Protocol} 
     % N.B. 
     % TODO go through AMOP with symbols, starting by looking for
@@ -110 +114 @@
     % XXX is this really blocking ANSI conformance?  Answer: we have
     % to start with such a ``census'' to determine what we have.
-  \item Incomplete Streams:  need suitable abstraction between ANSI
-    and Gray streams.
+  \item Incomplete streams work, in that \textsc{ABCL} needs suitable
+    abstraction between ANSI and Gray streams.
     
 \end{itemize}
 
-\chapter{Interaction with host JVM}
+\chapter{Interaction with Hosting JVM}
 
 % describe calling Java from Lisp, and calling Lisp from Java,
@@ -121 +125 @@
 % audience into those who are more comfortable with Java, and those
 % that are more comforable with Lisp
+
+The Armedbear Common Lisp implementation is hosted on a Java Virtual
+Machine.  This chapter describes the mechanisms by which the
+implementation interacts with that hosting mechanism.
 
 \section{Lisp to Java}
@@ -177 +185 @@
 returned.
 
-Once you have a reference to the method, you can call it using \code{JAVA:JCALL},
-which takes the method as the first argument. The second argument is the
-object instance to call the method on, or \code{NIL} in case of a static method.
-Any remaining parameters are used as the remaining arguments for the call.
+Once one has a reference to the method, one may invoke it using
+\code{JAVA:JCALL}, which takes the method as the first argument. The
+second argument is the object instance to call the method on, or
+\code{NIL} in case of a static method.  Any remaining parameters are
+used as the remaining arguments for the call.
 
 \subsubsection{Calling Java object methods: dynamic dispatch}
@@ -574 +583 @@
 \subsubsection{Compilation}
 
-AbclScriptEngine implements the javax.script.Compilable
+AbclScriptEngine implements the \code{javax.script.Compilable}
 interface. Currently it only supports compilation using temporary
 files. Compiled code, returned as an instance of
@@ -669 +678 @@
 \end{listing-lisp}
 
-NB \code{add-to-classpath} only affects the classloader used by ABCL
+N.b \code{add-to-classpath} only affects the classloader used by ABCL
 (the value of the special variable \code{JAVA:*CLASSLOADER*}. It has
 no effect on Java code outside ABCL.
@@ -680 +689 @@
 \section{THREADS}
 
-Multithreading
+The extensions for handling multithreaded execution are collected in
+the \code{THREADS} package.  Most of the abstractions in Doug Lea's
+excellent \code{java.util.concurrent} packages may be manipulated
+directly via the JSS contrib to great effect.
 
 \subsection{API}
@@ -730 +742 @@
 representation is defined to be the NAMESTRING of the Pathname.
 
-PATHNAME : URL-PATHNAME : JAR-PATHNAME
-
-Both URL-PATHNAME and JAR-PATHNAME may be used anu where will a
-PATHNAME is accepted witht the following caveats
-
-A stream obtained via OPEN on a URL-PATHNAME cannot be the target of
-write operations.
-
-No canonicalization is performed on the underlying URI (i.e. the
+\begin{verbatim}
+  JAR-PATHNAME isa URL-PATHNAME isa PATHNAME
+\end{verbatim}
+
+Both URL-PATHNAME and JAR-PATHNAME may be used anywhere a PATHNAME is
+accepted with the following caveats:
+
+\begin{itemize}
+
+\item A stream obtained via OPEN on a URL-PATHNAME cannot be the
+  target of write operations.
+
+\item No canonicalization is performed on the underlying URI (i.e. the
 implementation does not attempt to compute the current name of the
 representing resource unless it is requested to be resolved.)  Upon
 resolution, any cannoicalization procedures followed in resolving the
 resource (e.g. following redirects) are discarded.  
+
+\end{itemize}
 
 The implementation of URL-PATHNAME allows the ABCL user to laod dynamically
@@ -864 +882 @@
 \textsc{CLASS-FILE-DIRECTORY} and \textsc{MVN}.
 
+
+
+\subsection{ABCL-ASDF Examples}
+
+\begin{listing-lisp}
+    ;;;; -*- Mode: LISP -*-
+    (in-package :asdf)
+
+    (defsystem :log4j
+      :components ((:mvn "log4j/log4j" 
+                    :version "1.4.9")))
+\end{listing-lisp}
+
+\subsection{abcl-asdf API}
+
+We define an API as consisting of the following ASDF classes:
+
+\textsc{JAR-DIRECTORY}, \textsc{JAR-FILE}, and
+\textsc{CLASS-FILE-DIRECTORY} for JVM artifacts that have a currently
+valid pathname representation
+
+And the MVN and IRI classes descend from ASDF-COMPONENT, but do not
+directly have a filesystem location.
+
+For use outside of ASDF, we currently define one method,
+\textsc{RESOLVE-DEPENDENCIES} which locates, downloads, caches, and then loads
+into the currently executing JVM process all recursive dependencies
+annotated in the Maven pom.xml graph.
+
+\subsection{ABCL-ASDF Example 2}
+
+Bypassing ASDF, one can directly issue requests for the Maven
+artifacts to be downloaded
+
+\begin{listing-lisp}
+    CL-USER> (abcl-asdf:resolve-dependencies "com.google.gwt" "gwt-user")
+    WARNING: Using LATEST for unspecified version.
+    "/Users/evenson/.m2/repository/com/google/gwt/gwt-user/2.4.0-rc1/gwt-user-2.4.0-rc1.jar:/Users/evenson/.m2/repository/javax/validation/validation-api/1.0.0.GA/validation-api-1.0.0.GA.jar:/Users/evenson/.m2/repository/javax/validation/validation-api/1.0.0.GA/validation-api-1.0.0.GA-sources.jar"
+\end{listing-lisp}
+
+To actually load the dependency, use the JAVA:ADD-TO-CLASSPATH generic
+function:
+
+\begin{listing-lisp}
+    CL-USER> (java:add-to-classpath (abcl-asdf:resolve-dependencies "com.google.gwt" "gwt-user"))
+\end{listing-lisp}
+
+Notice that all recursive dependencies have been located and installed
+locally from the network as well.
+
+
 \section{asdf-jar}
 
@@ -870 +939 @@
 systems the code in this package will recursively package all the
 required source and fasls in a jar archive.
-
-
-
-\subsection{ABCL-ASDF Examples}
-
-\begin{listing-lisp}
-    ;;;; -*- Mode: LISP -*-
-    (in-package :asdf)
-
-    (defsystem :log4j
-      :components ((:mvn "log4j/log4j" 
-                    :version "1.4.9")))
-\end{listing-lisp}
-
-\subsection{abcl-asdf API}
-
-We define an API as consisting of the following ASDF classes:
-
-\textsc{JAR-DIRECTORY}, \textsc{JAR-FILE}, and
-\textsc{CLASS-FILE-DIRECTORY} for JVM artifacts that have a currently
-valid pathname representation
-
-And the MVN and IRI classes descend from ASDF-COMPONENT, but do not
-directly have a filesystem location.
-
-For use outside of ASDF, we currently define one method,
-\textsc{RESOLVE-DEPENDENCIES} which locates, downloads, caches, and then loads
-into the currently executing JVM process all recursive dependencies
-annotated in the Maven pom.xml graph.
-
-\subsection{ABCL-ASDF Example 2}
-
-Bypassing ASDF, one can directly issue requests for the Maven
-artifacts to be downloaded
-
-\begin{listing-lisp}
-    CL-USER> (abcl-asdf:resolve-dependencies "com.google.gwt" "gwt-user")
-    WARNING: Using LATEST for unspecified version.
-    "/Users/evenson/.m2/repository/com/google/gwt/gwt-user/2.4.0-rc1/gwt-user-2.4.0-rc1.jar:/Users/evenson/.m2/repository/javax/validation/validation-api/1.0.0.GA/validation-api-1.0.0.GA.jar:/Users/evenson/.m2/repository/javax/validation/validation-api/1.0.0.GA/validation-api-1.0.0.GA-sources.jar"
-\end{listing-lisp}
-
-To actually load the dependency, use the JAVA:ADD-TO-CLASSPATH generic
-function:
-
-\begin{listing-lisp}
-    CL-USER> (java:add-to-classpath (abcl-asdf:resolve-dependencies "com.google.gwt" "gwt-user"))
-\end{listing-lisp}
-
-Notice that all recursive dependencies have been located and installed
-locally from the network as well.
 
 \section{jss}