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

[Robert Goldman]

Alexander Repenning wrote:
> Sounds like we are converging towards the wiki idea. I really like it.
> For the Scalable Game Design project we have started to use media wiki.
> It works really great and has quickly become an important community
> tool. Our users seem to like it. Media wiki is also used for wikipedia,
> meaning, its pretty powerful and immediately usable by people how have
> contributed to the wikipedia before. 
> 
> I think generating the wiki from a source may not be a good idea as the
> whole point of the wiki is to give a group of people a mechanism of
> input and collaborative editing. Of course, if you have some existing
> documentation it would make sense to generate the first version of the
> wiki but then the wiki becomes the data base. If we agree that there is
> ANY place for people to add and edit information then this would suggest
> that the wiki should remain the prime source of the information. An
> output only wiki would make no sense. The moment when you allow input
> then synchronization with a source document will sooner or later become
> an unresolvable nightmare. 
> 
> If you have concerns with output: mediawiki has all kinds of tools to
> batch create pdfs, then there is wiki on stick to dump an entire wiki
> onto a USB stick. Also, media wiki includes easy to use categorization
> tools to automatically create tables of content, indices etc. You can
> define templates including styles, e.g., a method definition template.
> 
> The big question is simply if the CCL documentation is conceptualized as
> either a collective effort or just something that Clozure is producing
> for its users. Given the open source nature of CCL itself it would seem
> that an open documentation approach would be the best match to support
> the community. If that is the case then a wiki would seem to make most
> sense.

If this is the way you are going, may I make a suggestion?  Once upon a
time Gilbert Baumann (I think) translated the CLIM documentation into a
wiki, and it had a really neat feature:  it supported adding annotations
to individual paragraphs of the CLIM spec.  This meant that people could
drop in useful marginalia with examples, amplifications, etc.

This was a good, easy way to take advantage of the user community, while
maintaining a pretty rigorous document set.

Wikipedia has its discussion page, but that's not really the same thing
--- it's for meta-discussion about the process of generating the
document, and it's not conducive to reading at the same time as the main
document.

I don't have any real experience with media wiki, so I don't know if
this would be possible to do with it.

Best,
r