[Openmcl-devel] documentation update

Wed Nov 12 19:57:51 PST 2014

Hi,

For what little it's worth...

We've recently developed a documentation tool for ACL2 source code
called XDOC.  You can see the web-based version here:

   http://fv.centtech.com/acl2/latest/doc/?topic=ACL2____TOP

I don't know if it makes any sense at all to consider using this tool
for the CCL documentation.  It may be too ACL2-specific to use easily
for Common Lisp, for instance.  But it'd be interesting to think about
what it would take to extend it to be able to document normal Common
Lisp code.

Regardless of whether it's worth using, it may have some good ideas
that would carry over well to Lisp documentation systems.  For
instance, you can do cool things with macros that can generate
documentation.  When we do a "defaggregate" macro (similar to a
defstruct in Lisp) it produces nice API documentation for the
structure, its accessors, and the make/change macros that get
generated, and you can extend this documentation easily without having
to say stupid boilerplate things like "This is a structure with fields
X, Y, and Z."  Similarly there are some fancy macros that define
"typed" functions that make it really easy to document the arguments
and return values, without Javadoc-like repetition of what the
arguments are, etc.

Anyway, there's a paper about it here that gives a good overview, if
you think this sounds at all promising.

   http://eptcs.web.cse.unsw.edu.au/paper.cgi?ACL22014.2

Another thing that might be worth reading is a description of the
Scribble documentation system for Racket.  It's really cool:

   http://www.ccs.neu.edu/racket/pubs/icfp09-fbf.pdf

Cheers,
Jared

On Tue, Nov 11, 2014 at 2:17 PM, R. Matthew Emerson <rme at clozure.com> wrote:
>
> 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.
>
> _______________________________________________
> Openmcl-devel mailing list
> Openmcl-devel at clozure.com
> https://lists.clozure.com/mailman/listinfo/openmcl-devel

-- 
Jared C. Davis <jared at cs.utexas.edu>
11410 Windermere Meadows
Austin, TX 78759
http://www.cs.utexas.edu/users/jared/