Changeset 13438

Timestamp:

08/05/11 09:30:50 (12 years ago)

Author:

Mark Evenson

Message:

Manual renders to pdf via pdflatex.

Location:

trunk/abcl/doc/manual

Files:

• abcl.sty (moved) (moved from trunk/abcl/doc/manual/index.tex) (2 diffs)
• abcl.tex (modified) (22 diffs)
• java.tex (modified) (1 diff)

trunk/abcl/doc/manual/abcl.sty

@@ -4 +4 @@
 % leaving the manual itself as much as a pure content to be
 % comfortably read and modified with a text editor.
-
-\documentclass[10pt]{article}
 
 \usepackage{color,hyperref}
@@ -22 +20 @@
 
 
-\newenvironment{xx}[1]%
-               {\begin{lstlisting} }%
-               {\end{lstlisting}}
+\lstnewenvironment{listing-java}
+ {\lstset{language=Java}}
+ {}
+
+
+\lstnewenvironment{listing-lisp}
+ {\lstset{language=Lisp}}
+ {}
 
 \usepackage{verbatim}
 
+\ProvidesPackage{abcl}

trunk/abcl/doc/manual/abcl.tex

@@ +1 @@
+% -*- mode: latex; -*-
 % http://en.wikibooks.org/wiki/LaTeX/
-\include{index}
+\documentclass[10pt]{book}
+\usepackage{abcl}
 
 \begin{document}
 \title{A Manual for Armed Bear Common Lisp}
 \date{August 4, 2011}
-\author{Mark Evenson, Erik Huelsmann, Alessio Stallo, Ville Voutilainen}
-
-\section{Introduction}
+\author{Mark~Evenson, Erik~Huelsmann, Alessio~Stallo, Ville~Voutilainen}
+
+\maketitle
+
+\chapter{Introduction}
 
 Armed Bear is a mostly conforming implementation of the ANSI Common
@@ -16 +20 @@
 This manual corresponds to abcl-0.27.0, as yet unreleased.
 
-
-\section{Interaction with host JVM}
+\chapter{Conformance}
+
+
+\section{ANSI Common Lisp}
+ABCL is currently a non-conforming ANSI Common Lisp implementation due
+to the following (known) issues:
+
+\begin{itemize}
+  \item Lack of long form of DEFINE-METHOD-COMBINATION
+  \item Missing statement of conformance in accompanying documentation
+\end{itemize}
+
+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, ABCL strives to implement features
+expected of a contemporary Common Lisp.
+\begin{itemize}
+  \item Incomplete MOP 
+    % N.B. 
+    % TODO go through AMOP with symbols, starting by looking for
+    % matching function signature.
+    % XXX is this really blocking ANSI conformance?  Answer: we have
+    % to start with such a ``census'' to determine what we have.
+  \item Incomplete Gray Streams
+\end{itemize}
+
+\chapter{Interaction with host JVM}
 
 % describe calling Java from Lisp, and calling Lisp from Java,
@@ -24 +55 @@
 % that are more comforable with Lisp
 
-\subsection{Lisp to Java}
+\section{Lisp to Java}
 
 ABCL offers a number of mechanisms to manipulate Java libraries from
@@ -43 +74 @@
 \end{itemize}
 
-\subsection{Lisp from Java}
+\section{Lisp from Java}
 
 Manipulation of the Lisp API is currently lacking a stable interface,
@@ -60 +91 @@
 \end{itemize}
 
-\subsubsection{Lisp FFI}
+\subsection{Lisp FFI}
 
 FFI stands for "Foreign Function Interface" which is the phase which
@@ -69 +100 @@
 needs to be "Interfaced".
 
-\subsubsection{Calling Lisp from Java}
+\subsection{Calling Lisp from Java}
 
 Note: As the entire ABCL Lisp system resides in the org.armedbear.lisp
@@ -76 +107 @@
 statement would be
 
-\lstset{language=Java}
-\begin{lstlisting}
+\begin{listing-java}
   import org.armedbear.lisp.*;
-\end{lstliting}
+\end{listing-java}
 
 to potentially import all the JVM symbol from the `org.armedbear.lisp'
@@ -87 +117 @@
 started by calling the static method `Interpreter.createInstance()`.
 
-\begin{code}[java]
+\begin{listing-java}
   Interpreter interpreter = Interpreter.createInstance();
-\end{code}
+\end{listing-java}
 
 If this method has already been invoked in the lifetime of the current
@@ -103 +133 @@
 \end{code}
 
-
 The Lisp \code{eval} primitive may be simply passed strings for evaluation,
 as follows
 
-\begin{code}[java]
+\begin{listing-java}
   String line = "(load \"file.lisp\")";
   LispObject result = interpreter.eval(line);
-\end{code}
+\end{listing-java}
 
 Notice that all possible return values from an arbitrary Lisp
@@ -119 +148 @@
 (c.f. [Introspecting a LispObject])
 
-Using ``EVAL'' involves the Lisp interpreter.  Lisp functions may be
-directly invoked by Java method calls as follows.  One simply locates
-the package containing the symbol, then obtains a reference to the
-symbol, and then invokes the `execute()` method with the desired
-parameters.
-
-\begin{code}[java]
+Using \code{eval} involves the Lisp interpreter.  Lisp functions may
+be directly invoked by Java method calls as follows.  One simply
+locates the package containing the symbol, then obtains a reference to
+the symbol, and then invokes the \code{execute()} method with the
+desired parameters.
+
+\begin{listing-java}
     interpreter.eval("(defun foo (msg) (format nil \"You told me '~A'~%\" msg))");
     Package pkg = Packages.findPackage("CL-USER");
@@ -134 +163 @@
     // How to get the "naked string value"?
     System.out.println("The result was " + result.writeToString()); 
-\end{code}
+\end{listing-java}
 
 If one is calling an primitive function in the CL package the syntax
@@ -141 +170 @@
 tell if a `LispObject` contains a reference to a symbol.
 
-\begin{code}[java]
+\begin{listing-java}
     boolean nullp(LispObject object) {
       LispObject result = Primitives.NULL.execute(object);
@@ -149 +178 @@
       return true;
    }
-\end{code}
-
-\paragraph{Introspecting a LispObject}
+\end{listing-java}
+
+\subsubsection{Introspecting a LispObject}
 \label{topic:Introspecting a LispObject}
 
@@ -158 +187 @@
 into semantics that Java can meaniningfully deal with.
 
-\paragraph{LispObject as \code{boolean}}
+\subsubsection{LispObject as \code{boolean}}
 
 If the LispObject a generalized boolean values, one can use
 \code{getBooleanValue()} to convert to Java:
 
-\begin{code}[java]
+\begin{listing-java}
      LispObject object = Symbol.NIL;
      boolean javaValue = object.getBooleanValue();
-\end{code}
+\end{listing-java}
 
 Although since in Lisp, any value other than NIL means "true", the
 use of Java equality it quite a bit easier and more optimal:
 
-\begin{code}[java]
+\begin{listing-java}
     boolean javaValue = (object != Symbol.NIL);
-\end{code}
+\end{listing-java}
 
 \paragraph{LispObject is a list}
@@ -181 +210 @@
 iteration.
 
-\begin{code}[java]
+\begin{listing-java}
     LispObject result = interpreter.eval("'(1 2 4 5)");
     if (result instanceof Cons) {
@@ -187 +216 @@
       ...
     }
-\end{code}
+\end{listing-java}
     
 A more Lispy way to iterated down a list is to use the `cdr()` access
 function just as like one would traverse a list in Lisp:;
 
-\begin{code}[java]
+\begin{listing-java}
     LispObject result = interpreter.eval("'(1 2 4 5)");
     while (result != Symbol.NIL) {
@@ -198 +227 @@
       result = result.cdr();
     }
-\end{code}
-
-
-\subsection{JAVA}
+\end{listing-java}
+
+
+\section{Java}
 
 % include autogen docs for the JAVA package.
-
-\section{ANSI Common Lisp Conformance}
-
-ABCL is currently a non-conforming ANSI Common Lisp implementation due
-to the following (known) issues:
-
-\begin{itemize}
-  \item Lack of long form of DEFINE-METHOD-COMBINATION
-  \item Missing statement of conformance in accompanying documentation
-  \item Incomplete MOP 
-    % TODO go through AMOP with symbols, starting by looking for
-    % matching function signature.
-    % XXX is this really blocking ANSI conformance?  Answer: we have
-    % to start with such a ``census'' to determine what we have.
-\end{itemize}
-
-ABCL aims to be be a fully conforming ANSI Common Lisp
-implementation.  Any other behavior should be reported as a bug.
+\include{java}
+
+\section{Multithreading}
+
+% TODO document the THREADS package.
+\include{threads}
 
 \section{Extensions}
@@ -233 +250 @@
 \include{extensions}
 
-\subsection{Beyond ANSI}
+\chapter{Beyond ANSI}
 
 Naturally, in striving to be a useful contemporary Common Lisp
@@ -240 +257 @@
 in working with the hosting JVM.
 
-\subsubsection{Extensions to CLOS}
+\section{Extensions to CLOS}
 
 There is an additional syntax for specializing the parameter of a
@@ -251 +268 @@
 object
 
-\begin{code}[lisp]
-(defmethod print-object ((coll (java:jclass "java.util.Collection")) stream)
-\ldots
-\end{code}
+\begin{listing-lisp}
+(defmethod print-object ((coll (java:jclass "java.util.Collection"))
+                         stream)
+  ;;; ...
+)
+\end{listing-lisp}
 
 If the class had been loaded via a classloader other than the original
@@ -260 +279 @@
 classloader as an optional third argument.
 
-\begin{code}[lisp]
-(defmethod print-object ((device-id (java:jclass "dto.nbi.service.hdm.alcatel.com.nNBIDeviceID" 
-                                    (\#"getBaseLoader" cl-user::*classpath-manager*)))
-\ldots
-\end{code}
-
-\subsubsection{Extensions to the Reader}
+\begin{listing-lisp}
+
+(defparameter *other-classloader*
+  (jcall "getBaseLoader" cl-user::*classpath-manager*))
+  
+(defmethod print-object ((device-id (java:jclass "dto.nbi.service.hdm.alcatel.com.NBIDeviceID" *other-classloader*))
+                         stream)
+  ;;; ...
+)
+\end{listing-lisp}
+
+\section{Extensions to the Reader}
 
 We implement a special hexadecimal escape sequence for specifying
@@ -279 +303 @@
 code is greater than 0x00ff.
 
-\section{Multithreading}
-
-% TODO document the THREADS package.
-\include{threads}
-
-\section{History}
+\chapter{History}
 
 ABCL was originally the extension language for the J editor, which was

trunk/abcl/doc/manual/java.tex

@@ -1 +1 @@
 \begin{verbatim}
+
 %JGET-PROPERTY-VALUE
   Function: Gets a JavaBeans property on JAVA-OBJECT.
+
 %JSET-PROPERTY-VALUE
   Function: Sets a JavaBean property on JAVA-OBJECT.
-*JAVA-OBJECT-TO-STRING-LENGTH*
-  Variable: Length to truncate toString() PRINT-OBJECT output for an otherwise unspecialized JAVA-OBJECT.  Can be set to NIL to indicate no limit.
+
+*JAVA-OBJECT-TO-STRING-LENGTH* 
+ Variable: Length to truncate toString()
+ PRINT-OBJECT output for an otherwise unspecialized JAVA-OBJECT.  Can
+ be set to NIL to indicate no limit.
+
 ADD-TO-CLASSPATH
   Function: (not documented)
+
 CHAIN
   Function: (not documented)
+
 DESCRIBE-JAVA-OBJECT
   Function: (not documented)
+
 DUMP-CLASSPATH
   Function: (not documented)
+
 ENSURE-JAVA-CLASS
   Function: (not documented)
+
 ENSURE-JAVA-OBJECT
   Function: Ensures OBJ is wrapped in a JAVA-OBJECT, wrapping it if necessary.
+
 GET-DEFAULT-CLASSLOADER
   Function: (not documented)
+
 JARRAY-COMPONENT-TYPE
   Function: Returns the component type of the array type ATYPE
+
 JARRAY-LENGTH
   Function: (not documented)
+
 JARRAY-REF
-  Function: Dereferences the Java array JAVA-ARRAY using the given INDICIES, coercing the result into a Lisp object, if possible.
+ Function: Dereferences the Java array JAVA-ARRAY using the given
+ INDICIES, coercing the result into a Lisp object, if possible.
+
 JARRAY-REF-RAW
-  Function: Dereference the Java array JAVA-ARRAY using the given INDICIES. Does not attempt to coerce the result into a Lisp object.
+ Function: Dereference the Java array JAVA-ARRAY using the given
+ INDICIES. Does not attempt to coerce the result into a Lisp object.
+
 JARRAY-SET
   Function: Stores NEW-VALUE at the given index in JAVA-ARRAY.
+
 JAVA-CLASS
   Class: (not documented)
+
 JAVA-EXCEPTION
   Class: (not documented)
+
 JAVA-EXCEPTION-CAUSE
   Function: Returns the cause of JAVA-EXCEPTION. (The cause is the Java Throwable
+
 JAVA-OBJECT
   Class: (not documented)
+
 JAVA-OBJECT-P
   Function: Returns T if OBJECT is a JAVA-OBJECT.
+
 JCALL
-  Function: Invokes the Java method METHOD-REF on INSTANCE with arguments ARGS, coercing the result into a Lisp object, if possible.
+ Function: Invokes the Java method METHOD-REF on INSTANCE with
+ arguments ARGS, coercing the result into a Lisp object, if possible.
+
 JCALL-RAW
-  Function: Invokes the Java method METHOD-REF on INSTANCE with arguments ARGS. Does not attempt to coerce the result into a Lisp object.
+ Function: Invokes the Java method METHOD-REF on INSTANCE with
+ arguments ARGS. Does not attempt to coerce the result into a Lisp
+ object.
+
 JCLASS
-  Function: Returns a reference to the Java class designated by NAME-OR-CLASS-REF. If the CLASS-LOADER parameter is passed, the class is resolved with respect to the given ClassLoader.
+ Function: Returns a reference to the Java class designated by
+ NAME-OR-CLASS-REF. If the CLASS-LOADER parameter is passed, the class
+ is resolved with respect to the given ClassLoader.
+
 JCLASS-ARRAY-P
   Function: Returns T if CLASS is an array class
+
 JCLASS-CONSTRUCTORS
   Function: Returns a vector of constructors for CLASS
+
 JCLASS-FIELD
   Function: Returns the field named FIELD-NAME of CLASS
+
 JCLASS-FIELDS
-  Function: Returns a vector of all (or just the declared/public, if DECLARED/PUBLIC is true) fields of CLASS
+  Function: Returns a vector of all (or just the declared/public, if
+  DECLARED/PUBLIC is true) fields of CLASS
+
 JCLASS-INTERFACE-P
   Function: Returns T if CLASS is an interface
+
 JCLASS-INTERFACES
   Function: Returns the vector of interfaces of CLASS
+
 JCLASS-METHODS
-  Function: Return a vector of all (or just the declared/public, if DECLARED/PUBLIC is true) methods of CLASS
+  Function: Return a vector of all (or just the declared/public, if
+ DECLARED/PUBLIC is true) methods of CLASS
+
 JCLASS-NAME
   Function: When called with one argument, returns the name of the Java class
+
 JCLASS-OF
   Function: (not documented)
+
 JCLASS-SUPERCLASS
   Function: Returns the superclass of CLASS, or NIL if it hasn't got one
+
 JCLASS-SUPERCLASS-P
   Function: Returns T if CLASS-1 is a superclass or interface of CLASS-2
+
 JCOERCE
-  Function: Attempts to coerce OBJECT into a JavaObject of class INTENDED-CLASS.  Raises a TYPE-ERROR if no conversion is possible.
+  Function: Attempts to coerce OBJECT into a JavaObject of class
+ INTENDED-CLASS.  Raises a TYPE-ERROR if no conversion is possible.
+
 JCONSTRUCTOR
-  Function: Returns a reference to the Java constructor of CLASS-REF with the given PARAMETER-CLASS-REFS.
+  Function: Returns a reference to the Java constructor of CLASS-REF
+  with the given PARAMETER-CLASS-REFS.
+
 JCONSTRUCTOR-PARAMS
   Function: Returns a vector of parameter types (Java classes) for CONSTRUCTOR
+
 JEQUAL
   Function: Compares obj1 with obj2 using java.lang.Object.equals()
+
 JFIELD
   Function: Retrieves or modifies a field in a Java class or instance.
+
 JFIELD-NAME
   Function: Returns the name of FIELD as a Lisp string
+
 JFIELD-RAW
   Function: Retrieves or modifies a field in a Java class or instance. Does not
+
 JFIELD-TYPE
   Function: Returns the type (Java class) of FIELD
+
 JINSTANCE-OF-P
   Function: OBJ is an instance of CLASS (or one of its subclasses)
+
 JINTERFACE-IMPLEMENTATION
   Function: Creates and returns an implementation of a Java interface with
+
 JMAKE-INVOCATION-HANDLER
   Function: (not documented)
+
 JMAKE-PROXY
   Function: (not documented)
+
 JMEMBER-PROTECTED-P
   Function: MEMBER is a protected member of its declaring class
+
 JMEMBER-PUBLIC-P
   Function: MEMBER is a public member of its declaring class
+
 JMEMBER-STATIC-P
   Function: MEMBER is a static member of its declaring class
+
 JMETHOD
-  Function: Returns a reference to the Java method METHOD-NAME of CLASS-REF with the given PARAMETER-CLASS-REFS.
+  Function: Returns a reference to the Java method METHOD-NAME of
+  CLASS-REF with the given PARAMETER-CLASS-REFS.
+
 JMETHOD-LET
   Function: (not documented)
+
 JMETHOD-NAME
   Function: Returns the name of METHOD as a Lisp string
+
 JMETHOD-PARAMS
   Function: Returns a vector of parameter types (Java classes) for METHOD
+
 JMETHOD-RETURN-TYPE
   Function: Returns the result type (Java class) of the METHOD
+
 JNEW
   Function: Invokes the Java constructor CONSTRUCTOR with the arguments ARGS.
+
 JNEW-ARRAY
   Function: Creates a new Java array of type ELEMENT-TYPE, with the given DIMENSIONS.
+
 JNEW-ARRAY-FROM-ARRAY
   Function: Returns a new Java array with base type ELEMENT-TYPE (a string or a class-ref)
+
 JNEW-ARRAY-FROM-LIST
   Function: (not documented)
+
 JNEW-RUNTIME-CLASS
   Function: (not documented)
+
 JNULL-REF-P
   Function: Returns a non-NIL value when the JAVA-OBJECT `object` is `null`,
+
 JOBJECT-CLASS
   Function: Returns the Java class that OBJ belongs to
+
 JOBJECT-LISP-VALUE
   Function: Attempts to coerce JAVA-OBJECT into a Lisp object.
+
 JPROPERTY-VALUE
   Function: (not documented)
+
 JREDEFINE-METHOD
   Function: (not documented)
+
 JREGISTER-HANDLER
   Function: (not documented)
+
 JRESOLVE-METHOD
-  Function: Finds the most specific Java method METHOD-NAME on INSTANCE applicable to arguments ARGS. Returns NIL if no suitable method is found. The algorithm used for resolution is the same used by JCALL when it is called with a string as the first parameter (METHOD-REF).
+  Function: Finds the most specific Java method METHOD-NAME on
+  INSTANCE applicable to arguments ARGS. Returns NIL if no suitable
+  method is found. The algorithm used for resolution is the same used
+  by JCALL when it is called with a string as the first parameter
+ (METHOD-REF).
+
 JRUN-EXCEPTION-PROTECTED
-  Function: Invokes the function CLOSURE and returns the result.  Signals an error if stack or heap exhaustion occurs.
+  Function: Invokes the function CLOSURE and returns the result.
+  Signals an error if stack or heap exhaustion occurs.
+
 JRUNTIME-CLASS-EXISTS-P
   Function: (not documented)
+
 JSTATIC
   Function: Invokes the static method METHOD on class CLASS with ARGS.
+
 JSTATIC-RAW
-  Function: Invokes the static method METHOD on class CLASS with ARGS. Does not attempt to coerce the arguments or result into a Lisp object.
+  Function: Invokes the static method METHOD on class CLASS with
+  ARGS. Does not attempt to coerce the arguments or result into a Lisp
+  object.
+
 MAKE-CLASSLOADER
   Function: (not documented)
+
 MAKE-IMMEDIATE-OBJECT
   Function: Attempts to coerce a given Lisp object into a java-object of the
+
 REGISTER-JAVA-EXCEPTION
-  Function: Registers the Java Throwable named by the symbol EXCEPTION-NAME as the condition designated by CONDITION-SYMBOL.  Returns T if successful, NIL if not.
+  Function: Registers the Java Throwable named by the symbol
+  EXCEPTION-NAME as the condition designated by CONDITION-SYMBOL.
+  Returns T if successful, NIL if not.
+
 UNREGISTER-JAVA-EXCEPTION
   Function: Unregisters the Java Throwable EXCEPTION-NAME previously registered by REGISTER-JAVA-EXCEPTION.
+
 \end{verbatim}