Ignore:
Timestamp:
10/08/16 15:24:23 (14 months ago)
Author:
mevenson
Message:

metadata: publish all artifacts for 1.4.0 simultaneously

Update the README <file:README>, CHANGES <file:CHANGES> and the User
manual <file:doc/manual/> for 1.4.0.

<http://abcl.org/trac/changeset/14891>

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/abcl/doc/manual/abcl.tex

    r14885 r14892  
    99\begin{document}
    1010\title{Armed Bear Common Lisp User Manual}
    11 \date{Version 1.4.0-dev\\
     11\date{Version 1.4.0\\
    1212\smallskip
    13 April 2015}
     13October 2016}
    1414\author{Mark Evenson \and Erik H\"{u}lsmann \and Rudolf Schlatte \and
    1515  Alessio Stalla \and Ville Voutilainen}
     
    1818
    1919\tableofcontents
     20
     21%%Preface to the Fifth edition, abcl-1.4.0
     22\subsection{Preface to the Fifth Edition}
     23
     24\textsc{ABCL} 1.4 consolidates eighteen months of production bugfixes,
     25and substatianally improves the support for invoking external
     26processes via SYS:RUN-PROGRAM.
     27
    2028%%Preface to the Fourth edition, abcl-1.3.
    2129\subsection{Preface to the Fourth Edition}
     
    117125  in a given call frame, and the inability to resume a halted
    118126  computation at an arbitrarily selected call frame.
    119 \item Incomplete streams abstraction, in that \textsc{ABCL} needs
    120   suitable abstraction between \textsc{ANSI} and Gray
    121   streams.  \footnote{The streams could be optimized to the
     127\item Incomplete streams abstraction, in that \textsc{ABCL} needs a
     128  suitable abstraction between \textsc{ANSI} and \textsc{Gray streams}
     129  with a runtime switch for the beyond conforming
     130  behavior.  \footnote{The streams could be optimized to the
    122131    \textsc{JVM} NIO \cite{nio} abstractions at great profit for
    123132    binary byte-level manipulations.}
    124 \item Incomplete documentation (missing docstrings from exported
    125   symbols and the draft status of this user manual).
     133\item Incomplete documentation: source code is missing docstrings from
     134  all exported symbols from the \code{EXTENSIONS}, \code{SYSTEM},
     135  \code{JAVA}, \code{MOP}, and \code{THREADS} packages.  This user
     136  manual is currently in draft status.
    126137\end{itemize}
    127138
     
    133144June 1991 with the ``classpath-exception'' (see the file
    134145\texttt{COPYING} in the source distribution \footnote{See
    135   \url{http://abcl.org/svn/trunk/tags/1.3.0/COPYING}} for
     146  \url{http://abcl.org/svn/trunk/tags/1.4.0/COPYING}} for
    136147the license, term 13 in the same file for the classpath exception).
    137148This license broadly means that you must distribute the sources to
    138 ABCL, including any changes you make, together with a program that
    139 includes ABCL, but that you are not required to distribute the sources
     149\textsc{ABCL}, including any changes you make, together with a program that
     150includes \textsc{ABCL}, but that you are not required to distribute the sources
    140151of the whole program.  Submitting your changes upstream to the ABCL
    141152development team is actively encouraged and very much appreciated, of
     
    149160  in the dark years.}
    150161\item Alan Ruttenberg \texttt{Thanks for JSS.}
     162  \item piso
    151163\item and of course
    152164\emph{Peter Graves}
     
    158170
    159171\textsc{ABCL} is packaged as a single jar file usually named either
    160 \texttt{abcl.jar} or possibly something like \texttt{abcl-1.3.0.jar} if
     172\texttt{abcl.jar} or possibly something like \texttt{abcl-1.4.0.jar} if
    161173using a versioned package on the local filesystem from your system
    162174vendor.  This jar file can be executed from the command line to obtain a
     
    259271
    260272This subsection covers the low-level API available after evaluating
    261 \code{(require 'JAVA)}.  A higher level Java API, developed by Alan
     273\code{(require :java)}.  A higher level Java API, developed by Alan
    262274Ruttenberg, is available in the \code{contrib/} directory and described
    263275later in this document, see Section~\ref{section:jss} on page
     
    809821\subsection{Modifying the JVM CLASSPATH}
    810822
    811 The JAVA:ADD-TO-CLASSPATH generic functions allows one to add the
     823The \code{JAVA:ADD-TO-CLASSPATH} generic functions allows one to add the
    812824specified pathname or list of pathnames to the current classpath
    813 used by ABCL, allowing the dynamic loading of JVM objects:
     825used by ABCL, allowing the dynamic loading of \textsc{JVM} objects:
    814826
    815827\begin{listing-lisp}
     
    817829\end{listing-lisp}
    818830
    819 N.b \code{ADD-TO-CLASSPATH} only affects the classloader used by ABCL
     831N.b \code{ADD-TO-CLASSPATH} only affects the classloader used by \textsc{ABCL}
    820832(the value of the special variable \code{JAVA:*CLASSLOADER*}. It has
    821 no effect on Java code outside ABCL.
     833no effect on \textsc{Java} code outside \textsc{ABCL}.
    822834
    823835\subsection{Creating a synthetic Java Class at Runtime}
     
    833845the \code{THREADS} package.  Most of the abstractions in Doug Lea's
    834846excellent \code{java.util.concurrent} packages may be manipulated
    835 directly via the JSS contrib to great effect.
     847directly via the JSS contrib to great effect \cite{lea-1998}
    836848
    837849% include autogen docs for the THREADS package.
     
    918930\index{URI}
    919931\item Any results of canonicalization procedures performed on the
    920   underlying \textsc{URI} are discarded between resolutions (i.e. the
    921   implementation does not attempt to cache the results of current name
    922   resolution of the representing resource unless it is requested to be
    923   resolved.)  Upon resolution, any canonicalization procedures
    924   followed in resolving the resource (e.g. following redirects) are
    925   discarded.  Users may programatically initiate a new, local
    926   computation of the resolution of the resource by applying the
    927   \code{CL:TRUENAME} function to a \code{EXT:URL-PATHNAME} object.
    928   Depending on the reliability and properties of your local
    929   \textsc{REST} infrastructure, these results may not necessarily be
    930   idempotent over time\footnote {See \cite{evenson2011} for the draft
    931     of the publication of the technical details}.
     932  \textsc{URI} via local or network resolutions are discarded between
     933  attempts (i.e. the implementation does not attempt to cache the
     934  results of current name resolution of the URI for underlying
     935  resource unless it is requested to be resolved.)  Upon resolution,
     936  any canonicalization procedures followed in resolving the resource
     937  (e.g. following redirects) are discarded.  Users may programatically
     938  initiate a new, local computation of the resolution of the resource
     939  by applying the \code{CL:TRUENAME} function to a
     940  \code{EXT:URL-PATHNAME} object.  Depending on the reliability and
     941  properties of your local \textsc{REST} infrastructure, these results
     942  may not necessarily be idempotent over time\footnote {See
     943    \cite{uri-pathname} for the design and implementation notes for
     944    the technical details}.  A future implementation may attempt to
     945  expose an API to observer/customize the content negotiation
     946  initiated during retrieval of the representation of a given
     947  resource, which is currently handled at the application level.
    932948
    933949\end{itemize}
     
    11131129\section{Extensible Sequences}
    11141130
    1115 See Rhodes2007 \cite{RHODES2007} for the design.
    1116 
    11171131The SEQUENCE package fully implements Christopher Rhodes' proposal for
    11181132extensible sequences.  These user extensible sequences are used
     
    11211135\code{java.util.List} contract.
    11221136
     1137
    11231138%% an Example of using java.util.Lisp in Lisp would be nice
    11241139
     
    11271142
    11281143\begin{listing-lisp}
    1129 CL-USER> (require 'java-collections)
     1144CL-USER> (require :java-collections)
    11301145\end{listing-lisp}
    11311146
     
    11341149
    11351150\begin{listing-lisp}
    1136 CL-USER> (require 'extensible-sequences)
     1151CL-USER> (require :extensible-sequences)
    11371152\end{listing-lisp}
    11381153
     
    11401155required.
    11411156
    1142 Note that \code{(require 'java-collections)} must be issued before
     1157Note that \code{(require :java-collections)} must be issued before
    11431158\code{java.util.List} or any subclass is used as a specializer in a \textsc{CLOS}
    11441159method definition (see the section below).
     1160
     1161See Rhodes2007 \cite{RHODES2007} for the an overview of the
     1162abstractions of the \code{java.util.collection} package afforded by
     1163\code{JAVA-COLLECTIONS}.
    11451164
    11461165\section{Extensions to CLOS}
     
    11561175\code{funcallable-standard-class} as metaclass instead of
    11571176\code{standard-class}.
     1177
     1178\textsc{ABCL}'s fidelity to the AMOP specification is codified as part
     1179of Pascal Costanza's \code{closer-mop} \ref{closer-mop} \cite{closer-mop}.
    11581180
    11591181\subsection{Specializing on Java classes}
     
    12031225by the reader as character whose code is specified by the hexadecimal
    12041226digits \emph{\texttt{xxxx}}.  The hexadecimal sequence may be one to four digits
    1205 long.  % Why doesn't ALEXANDRIA work?
     1227long.
     1228
     1229% Why doesn't ALEXANDRIA work?  Good question: Alexandria from
     1230% Quicklisp 2010-10-07 fails a number of tests:
     1231%% Form: (ALEXANDRIA.0.DEV:TYPE= 'LIST '(OR NULL CONS))
     1232%% Expected values: T
     1233%%                  T
     1234%% Actual values: NIL
     1235%%                T.
     1236%% Test ALEXANDRIA-TESTS::TYPE=.3 failed
     1237%% Form: (ALEXANDRIA.0.DEV:TYPE= 'NULL '(AND SYMBOL LIST))
     1238%% Expected values: T
     1239%%                  T
     1240%% Actual values: NIL
     1241%%                NIL.
     1242
    12061243
    12071244Note that this sequence is never output by the implementation.  Instead,
     
    12231260    resolution.  This means, for instance if \code{CL-PPCRE} can be
    12241261    located as a loadable \textsc{ASDF} system \code{(require
    1225       'cl-ppcre)} is equivalent to \code{(asdf:load-system
    1226       'cl-ppcre)}.
     1262      :cl-ppcre)} is equivalent to \code{(asdf:load-system
     1263      :cl-ppcre)}.
    12271264
    12281265  \item{\code{ABCL-CONTRIB}}
     
    12751312\section{ASDF}
    12761313
    1277 asdf-3.1.6 (see \cite{asdf}) is packaged as core component of \textsc{ABCL},
     1314asdf-3.1.7.27 (see \cite{asdf}) is packaged as core component of \textsc{ABCL},
    12781315but not initialized by default, as it relies on the \textsc{CLOS} subsystem
    12791316which can take a bit of time to start \footnote{While this time is
     
    12851322
    12861323\begin{listing-lisp}
    1287 CL-USER> (require 'asdf)
     1324CL-USER> (require :asdf)
    12881325\end{listing-lisp}
    12891326
     
    12921329The \textsc{ABCL} contrib is packaged as a separate jar archive usually named
    12931330\code{abcl-contrib.jar} or possibly something like
    1294 \code{abcl-contrib-1.3.0.jar}.  The contrib jar is not loaded by the
     1331\code{abcl-contrib-1.4.0.jar}.  The contrib jar is not loaded by the
    12951332implementation by default, and must be first intialized by the
    12961333\code{REQUIRE} mechanism before using any specific contrib:
    12971334
    12981335\begin{listing-lisp}
    1299 CL-USER> (require 'abcl-contrib)
     1336CL-USER> (require :abcl-contrib)
    13001337\end{listing-lisp}
    13011338
     
    13791416
    13801417More extensive documentations and examples can be found at
    1381 \url{http://abcl.org/svn/tags/1.3.0/contrib/abcl-asdf/README.markdown}.
     1418\url{http://abcl.org/svn/tags/1.4.0/contrib/abcl-asdf/README.markdown}.
    13821419
    13831420
     
    13911428
    13921429The documentation for this contrib can be found at
    1393 \url{http://abcl.org/svn/tags/1.3.0/contrib/asdf-jar/README.markdown}.
     1430\url{http://abcl.org/svn/tags/1.4.0/contrib/asdf-jar/README.markdown}.
    13941431
    13951432
     
    14161453
    14171454\begin{listing-lisp}
    1418 CL-USER> (require 'abcl-contrib)
     1455CL-USER> (require :abcl-contrib)
    14191456==> ("ABCL-CONTRIB")
    1420 CL-USER> (require 'jss)
     1457CL-USER> (require :jss)
    14211458==> ("JSS")
    14221459CL-USER) (#"getProperties" 'java.lang.System)
     
    14271464
    14281465Some more information on jss can be found in its documentation at
    1429 \url{http://abcl.org/svn/tags/1.3.0/contrib/jss/README.markdown}
     1466\url{http://abcl.org/svn/tags/1.4.0/contrib/jss/README.markdown}
    14301467
    14311468\section{jfli}
     
    14341471The contrib contains a pure-Java version of JFLI.
    14351472
    1436 \url{http://abcl.org/svn/tags/1.3.0/contrib/jfli/README}.
     1473\url{http://abcl.org/svn/tags/1.4.0/contrib/jfli/README}.
    14371474
    14381475
     
    14701507a maintainence release.
    14711508
     1509In October 2016 we blessed the current \textsc{svn} trunk
     1510\url{http://abcl.org/svn/trunk/} as 1.4.0, which includes the
     1511community contributions from Vihbu, Olof, Pipping, and Cyrus.  We
     1512gingerly stepped into current century by establishing \textsc{git}
     1513bridges to the source repository at
     1514\url{https://github.com/easye/abcl/} and
     1515\url{https://gitlab.common-lisp.net/abcl/abcl/} so that pull
     1516requests for enhancements to the implementation many be more easily
     1517facilitated.
     1518
    14721519\appendix
    14731520
Note: See TracChangeset for help on using the changeset viewer.