[armedbear-cvs] r13628 - trunk/abcl/doc/manual

[mevenson at common-lisp.net]

Author: mevenson
Date: Wed Oct 12 22:05:20 2011
New Revision: 13628

Log:
Adjustments to voice and presentation in the manual.

Modified:
   trunk/abcl/doc/manual/abcl.tex

Modified: trunk/abcl/doc/manual/abcl.tex
==============================================================================
--- trunk/abcl/doc/manual/abcl.tex	Wed Oct 12 22:05:05 2011	(r13627)
+++ trunk/abcl/doc/manual/abcl.tex	Wed Oct 12 22:05:20 2011	(r13628)
@@ -5,7 +5,7 @@
 
 \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}
 
 \maketitle
@@ -21,12 +21,12 @@
 
 \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}
   cmd$ java -jar abcl.jar
@@ -46,7 +46,7 @@
 
 \section{Options}
 
-ABCL supports the following options:
+ABCL supports the following command line options:
 
 \begin{verbatim}
 --help
@@ -87,11 +87,10 @@
 \chapter{Conformance}
 
 \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.
 \end{itemize}
@@ -100,7 +99,7 @@
 implementation.  Any other behavior should be reported as a bug.
 
 \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}
   \item Incomplete (A)MOP 
@@ -123,26 +122,29 @@
 
 \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}
 
 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)}.
 
@@ -189,10 +191,12 @@
 
 \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}
 ZipFile jar = new ZipFile("/path/to/some.jar");
@@ -201,7 +205,7 @@
 method.invoke(els);
 \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
 
 \begin{listing-java}
@@ -227,7 +231,7 @@
 
 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;
 the actual class of the object is only tried if the method is not found