Changeset 13628

Timestamp:

10/13/11 05:05:20 (11 years ago)

Author:

Mark Evenson

Message:

Adjustments to voice and presentation in the manual.

File:

• trunk/abcl/doc/manual/abcl.tex (modified) (10 diffs)

trunk/abcl/doc/manual/abcl.tex

@@ -6 +6 @@
 \begin{document}
 \title{A Manual for Armed Bear Common Lisp}
-\date{October 2, 2011}
+\date{October 13, 2011}
 \author{Mark~Evenson, Erik~Huelsmann, Alessio~Stalla, Ville~Voutilainen}
 
@@ -22 +22 @@
 \chapter{Running}
 
-ABCL is packaged as a single jar file usually named either
+\textsc{ABCL} is packaged as a single jar file usually named either
 ``abcl.jar'' or something like``abcl-0.28.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
-(org.armedbear.lisp.Main) for excution:
+(\code{org.armedbear.lisp.Main}) for excution:
 
 \begin{listing-shell}
@@ -47 +47 @@
 \section{Options}
 
-ABCL supports the following options:
+ABCL supports the following command line options:
 
 \begin{verbatim}
@@ -88 +88 @@
 
 \section{ANSI Common Lisp}
-ABCL is currently a non-conforming ANSI Common Lisp implementation due
+\textsc{ABCL} is currently a non-conforming ANSI Common Lisp implementation due
 to the following issues:
 
 \begin{itemize}
-  \item Missing statement of conformance in accompanying documentation
   \item The generic function signatures of the DOCUMENTATION symbol do
     not match the CLHS.
@@ -101 +100 @@
 
 \section{Contemporary Common Lisp}
-In addition to ANSI conformance, ABCL strives to implement features
+In addition to ANSI conformance, \textsc{ABCL} strives to implement features
 expected of a contemporary Common Lisp.
 \begin{itemize}
@@ -124 +123 @@
 \section{Lisp to Java}
 
-ABCL offers a number of mechanisms to interact with Java from
-its lisp environment. It allows calling methods (and static methods) of
-Java objects, manipulation of fields and static fields and construction
-of new Java objects.
-
-When calling Java routines, some values will automatically be converted
-by the FFI from Lisp values to Java values. These conversions typically
-apply to strings, integers and floats. Other values need to be converted
-to their Java equivalents by the programmer before calling the Java
-object method. Java values returned to Lisp are also generally converted
-back to their Lisp counterparts. Some operators make an exception to this
-rule and do not perform any conversion; those are the ``raw'' counterparts
-of certain FFI functions and are recognizable by their name ending with
-\code{-RAW}.
+\textsc{ABCL} offers a number of mechanisms to interact with Java from its
+Lisp environment. It allows calling both instance and static methods
+of Java objects, manipulation of instance and static fields on Java
+objects, and construction of new Java objects.
+
+When calling Java routines, some values will automatically be
+converted by the FFI \footnote{FFI stands for Foreign Function
+  Interface which is the term of art which describes how a Lisp
+  implementation encapsulates invocation in other languages.}  from
+Lisp values to Java values. These conversions typically apply to
+strings, integers and floats. Other values need to be converted to
+their Java equivalents by the programmer before calling the Java
+object method. Java values returned to Lisp are also generally
+converted back to their Lisp counterparts. Some operators make an
+exception to this rule and do not perform any conversion; those are
+the ``raw'' counterparts of certain FFI functions and are recognizable
+by their name ending with \code{-RAW}.
 
 \subsection{Lowlevel Java API}
@@ -143 +145 @@
 There's a higher level Java API defined in the
 \ref{topic:Higher level Java API: JSS}(JSS package) which is available
-in the contrib/ directory. This package is described later in this
+in the \code{contrib/} directory. This package is described later in this
 document.  This section covers the lower level API directly available
 after evaluating \code{(require 'JAVA)}.
@@ -190 +192 @@
 \subsubsection{Dynamic dispatch: caveats}
 
-Dynamic dispatch is performed by using the Java reflection API. Generally
-it works fine, but there are corner cases where the API does not correctly
-reflect all the details involved in calling a Java method. An example is
-the following Java code:
+Dynamic dispatch is performed by using the Java reflection
+API \footnote{The Java reflection API is found in the
+  \code{java.lang.reflect} package}. Generally the dispatch works
+fine, but there are corner cases where the API does not correctly
+reflect all the details involved in calling a Java method. An example
+is the following Java code:
 
 \begin{listing-java}
@@ -202 +206 @@
 \end{listing-java}
 
-even though the method \code{hasMoreElements} is public in \code{Enumeration},
+even though the method \code{hasMoreElements()} is public in \code{Enumeration},
 the above code fails with
 
@@ -228 +232 @@
 except that the dynamic dispatch part is not shown.
 
-To avoid such pitfalls, all Java objects in ABCL carry an extra
+To avoid such pitfalls, all Java objects in \textsc{ABCL} carry an extra
 field representing the ``intended class'' of the object. That is the class
 that is used first by \code{JAVA:JCALL} and similar to resolve methods;