[Chicken-users] Comprehensive documentation rewrite

[Tobia Conforto]

Mario Domenech Goulart wrote:
> From a known format, we can convert the wiki documentation to  
> whatever format we need and even have an interactive documentation  
> system.  The current problem with the wiki documentation is that we  
> don't have semantic markup.

This is a good time to talk about a similar idea I've been having for  
a while.

My idea is to devise a "smart" document format, preferably s-expr  
based (maybe SSAX-based if nothing better comes to mind) and convert  
every piece of Chicken API documentation to that format: both for eggs  
and for the base system.  This includes any relevant SRFIs that are  
part of Chicken or of some eggs.

It's quite a lot of text, but it shouldn't be too hard, if you're  
armed with a good text editor and regexes.

This should make it relatively easy to generate any kind of  
documentation from a single, versioned source tree:
- static, heavy-hyperlinked html with full indexes by symbol, by  
permuted symbol, by topic (tags), by egg...
- dynamic html documentation, aka. API search engine on the site
- texi (or whatever it is... I'm a Vim user so I wouldn't know :-)

I'm ready to start working on this, if we agree it's a good thing, and  
after we've discussed the s-expr file format.  I'm still just a  
Chicken user (not a hacker) but this job is certainly within my reach!


Tobia