[armedbear-devel] abcl-1.0 -- The Manual

[Mark Evenson]

We have always informally answered the question as to when ABCL would deserve a 1.0 release number when it was a conforming ANSI implementation.  Since we are more or less ANSI complete at this point from a feature standpoint with the recent implementation of the long form of DEFINE-METHOD-COMBINATION, it makes
some sense to push for an ABCL 1.0 release which we could potentially
announce at ECLM 2011, since Erik, Alessio, and I will attend.

The [CLHS outlines the requirements for conforming implementation][1] as including

[…]
1.5.1.2 Documentation of Implementation-Dependent Features

1.5.1.3 Documentation of Extensions
[…] 
1.5.1.5 Conformance Statement
[…]

[1]: http://www.lispworks.com/documentation/HyperSpec/Body/01_ea.htm

To this end, I started an [ABCL manual written in LaTex][2].  With LaTeX we have the ability to include diagrams rather easily, something that despite Texinfo's claims to the contrary, I think should not be prohibited in documentation.  I have not found a suitable LaTex2HTML translator (although many exist), but would probably approach this as a problem to be addressed after we produce an initial manual.

[2]: http://trac.common-lisp.net/armedbear/browser/trunk/abcl/doc/manual

To render the manual in PDF, install [TeX Live 2011][3], and simply issue
 
    cmd$ pdflatex abcl.tex

in a the manual directory.

[3]: http://www.tug.org/texlive/

The structure of the manual is roughly in place, from which I have been cribbing ideas from the [SBCL][4] and [CCL][5] manuals

[4]: http://www.sbcl.org/manual/
[5]: http://ccl.clozure.com/ccl-documentation.html

but have still not committed to a final structure. 

I have started to create LaTeX macros in 'abcl.sty' to create an environment in which contributors can work on the manual without necessarily understanding that much of LaTeX by creating a semantics/presentation layer.  Currently, this mostly consists of ways of marking up text as being Lisp, Java, or Shell source code.  I plan to at least to produce a method to indicate that text refers to a given Lisp symbol in a given package so a reasonable cross referencing system can produce an index and page references.

A tension exists in the current effort between being a manual, and a tutorial with examples.  I would propose we concentrate on the manual aspects, while allowing inclusion of examples as the existing text gives a pretty reasonable introduction to extending ABCL via Java that would be a shame to lose.  But I could be persuaded to remove or move to an appendix if we wanted to emphasize concision.

Since TeX easily allows comments in documents with '%' characters, one can find various notes and ideas present in the current document to bring one up to speed on what I have in mind.

I intend to document the JAVA, EXTENSIONS, and SYSTEM packages by adding doctstrings to out implementation for all exported symbols, following the convention that there should be a short synopsis statement for the function as the first sentence, followed by a newline, followed by more explicit text.  I intend to write a Lisp tool that "scrapes" these docstrings from a live ABCL process, transforming into the appropriate LaTeX source which we would then include in the manual.  This isn't sufficient but necessary in my opinion to meet the criteria of documenting implementation dependent features.  If someone wished to help, getting our exported docstrings in order would be a task somewhat orthogonal to the production of the manual.

So, I would invite potential contributors to the manual to look at the source, build the PDF version, and consider what sections they would like to tackle.  Then we can divide this manual up into sections by file, so people can work somewhat in isolation.  As an informal deadline, I think we should have a plan in place by October 1 to have a chance of finishing things by ECLM 2011.


--
"A screaming comes across the sky.  It has happened before, but there is nothing to compare to it now."