[Openmcl-devel] ccl manual (was Re: trace on recursive functions)

[R. Matthew Emerson]

On Dec 10, 2009, at 11:47 AM, Philippe Sismondi wrote:

> On 2009-12-10, at 10:44 AM, Adlai Chandrasekhar wrote:
> 
>> On Wed, 9 Dec 2009, Philippe Sismondi wrote:
>> 
>>> What must I do to get trace to work as shown in Hyperspec on recursive functions? I only get a report of the first call to a traced function.
>>> 
>> 
>> There's also a page about this on the CCL wiki:
>> 
>> http://trac.clozure.com/ccl/wiki/DebugWithOpenmcl
> 
> I'll make a habit of looking at the wiki.
> 
> Some of the information on the wiki seems pretty fundamental to the use of ccl. Would it not be useful for this information to be in the ccl manual? Perhaps it is just my old-fashioned habits coming to the fore, but I really like to have one or two pdf documents that I can search and annotate when learning a language.

I agree that the manual should be good.

To misuse a chemistry term, the activation energy required to create or edit is wiki page is much lower than that for editing the manual.

The manual is in DocBook, and it is rather painful to edit (at least for me it is).  Emacs's nXML mode keeps me from producing invalid structure, but still, DocBook is big and complicated.

With the wiki, it's easy to just throw something up there.  Eventually, important stuff on the wiki makes it back into the manual, or ought to.  TRACE is one example that made the jump.  Just looking now, I see that the documentation on HEAP-UTILIZATION is another candidate that should make the leap to the manual.

I'd be very happy to receive patches for the manual or Trac tickets for documentation issues.  Any contributions, however minor, would be welcome.

As an aside, it would be really nice if some DocBook savvy person could offer some advice on:
  * what DocBook elements would be best for documenting lisp functions and macros
  * stylesheets for that markup so that the output looks roughly like the entries in CLTL2.

We currently use kind of a mixture; e.g., sometimes we use refentry, sometimes we don't.