[Openmcl-devel] documentation update

[R. Matthew Emerson]

CCL's DocBook format documentation has been languishing.  I myself find that editing DocBook is just too painful to contemplate;  I know Gary shares that opinion, and I believe that opinion is generally shared by everyone who works on CCL.

Gail came up with a tool called CCLDoc.  See http://trac.clozure.com/ccldoc.  She converted the DocBook documentation into CCLDoc, and I hacked up some code to convert the CCLDoc to HTML and to LaTeX.

I've been going through the documentation, editing the CCLDoc representation of it for style and trying to bring it more up-to-date.  It's a big job, and there's much more to do, but I'm hopeful that we'll find CCLDoc to be more usable for us than DocBook has been.  The big plus to CCLDoc is that the document is represented as a lisp data structure, and we can examine and transform it with lisp.

Appearance-wise, I think the HTML version is looking relatively decent.  I'm not an expert at CSS, so if anyone has suggestions for improvements (or patches), that would be welcome.

http://www.clozure.com/~rme/ccl.html

The LaTeX converter is still a little incomplete, but the current output looks promising.

http://www.clozure.com/~rme/ccl.pdf

If you happen to want to try out CCLDoc yourself, here's how to do that:

1. Install Quicklisp.
2. cd ~/quicklisp/local-projects/
3. svn co http://svn.clozure.com/publicsvn/ccldoc/trunk ccldoc

Now, start lisp.

? (load "home:quicklisp;setup")
? (ql:quickload :ccldoc)
? :cd "~/quicklisp/local-projects/ccldoc/ccl-documentation"
? (in-package :ccldoc)
? (defparameter *d* (load-document "ccl-documentation.ccldoc"))
? (output-html *d* "ccl.html")

If you want to mess with TeX, do (output-latex *d* "ccl.tex") and process the ccl.tex file with xelatex.

Anyway, I'm planning to replace the existing http://ccl.clozure.com/ccl-documentation.html with this updated documentation pretty soon.

Of course, any constructive feedback would be appreciated.

Yes, we're probably reinventing the wheel yet another time.  Yes, I probably am an idiot for not using tool X, Y, or Z.  Flame me about it in private mail if you must, but please spare the list.