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

[Andrew Shalit]

I think this is a great idea.

On Dec 11, 2009, at 10:01 AM, Gail Zacharias wrote:

> 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
> 
> _______________________________________________
> Openmcl-devel mailing list
> Openmcl-devel at clozure.com
> http://clozure.com/mailman/listinfo/openmcl-devel