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

[Gail Zacharias]

There are a couple things that DocBook et. al. give us, aside from 
formatting overkill: a chapter/section structure, and indexing (and 
glossaries, etc).

I think the most robust to documentation approach would be something 
along these lines:

- Keep the entire manual in the wiki, one section per page (or 
perhaps one subsection, tbd).

- Maintain a separate page defining the chapter/section structure, 
i.e. listing all the pages that comprise "the manual", grouped into 
sections and chapters.

- Introduce some conventions in the wiki for entering 
definitions.  If anybody felt like python hacking, I suppose we could 
try to make actual extensions to the wiki format, but basically we 
just need some structured (but simple) way to enter definitions that 
would make it possible to automatically identify the function name, 
arguments, and corresponding descriptions.

- Similarly for identifying glossary references.

- Write a simple lisp program that would take the above and produce 
DocBook and/or Latex and/or TexInfo, or whatever we decide produces 
the best output formats (not longer caring about the ugliness of 
their input formats).  Use those to create the html and/or pdf files.

- Check some version of the documentation (i.e. DocBook or Latex or 
TexInfo or html or pdf, tbd) into subversion for released 
versions.  The wiki would always (attempt to) track the trunk.

So, any volunteers?  Maybe we need an ad-hoc doc working group :-)


At 12/11/2009 05:34 AM, Tim Bradshaw wrote:
>On 10 Dec 2009, at 19:11, R. Matthew Emerson wrote:
>
> > 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.
>
>Is there any way to make the wiki *be* the manual? I don't know enough
>about the specific wiki here, but I'm thinking of some approach where
>you construct some kind of view of a lot of wiki pages which
>essentially is the manual (obviously this would not be "all pages" it
>would be some subset).  That's probably a bit less powerful than using
>some dedicated system like DocBook but it means there is a single
>source of information, and it's easier to update as well.
>_______________________________________________
>Openmcl-devel mailing list
>Openmcl-devel at clozure.com
>http://clozure.com/mailman/listinfo/openmcl-devel