[Openmcl-devel] ccl manual (was Re: trace on recursive functions)
alms at clozure.com
Fri Dec 11 07:26:17 PST 2009
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
> Openmcl-devel mailing list
> Openmcl-devel at clozure.com
More information about the Openmcl-devel