[Openmcl-devel] documentation update

[R. Matthew Emerson]

On Nov 11, 2014, at 3:10 PM, Ron Garret <ron at flownet.com> wrote:

> I think the new docs look great!  Even the PDF is pretty decent.  The only thing I’d change is to shrink the fonts a wee bit.
> 
> Where can we find the ccldoc sources of the CCL docs?  I looked in the current SVN trunk but couldn’t find them.

The documentation is currently part of a separate CCLDoc repository, and is not part of the main CCL repository.  I'm thinking that they will probably remain separate, because ccldoc has some library dependencies, and I think the CCL repository should be standalone, but maybe I'm wrong about that.

Browse the ccldoc sources for the manual at http://trac.clozure.com/ccldoc/browser/trunk/ccl-documentation or look for them in ~/quicklisp/local-projects/ccldoc/ccl-documentation/ if you used my instructions to check out a copy from Subversion.

The ccldoc sources for the manual are sometimes ugly, because they were converted automatically from DocBook.  I clean them up a little as I edit, but I don't want to go too crazy with that because it's still possible that we might want to re-pretty-print the sources by some automatic process.


> 
> On Nov 11, 2014, at 11:49 AM, R. Matthew Emerson <rme at clozure.com> wrote:
> 
>> 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.