[Chicken-hackers] Chicken manual

[Vincent Manis]

Some time ago, I enquired about producing a one-page version of the  
manual, and got the standard free software answer, `fine, go ahead, do  
it yourself'. Since that time, I've hacked wiki2html so that it not  
only produces a one-page HTML version, but also produces what appears  
to be viable LaTeX.

That work is at a proof-of-concept stage now, and what remains is  
tedious but straightforward, in particular, I still need to do some  
serious tweaking of the LaTeX driver. I am happy to go ahead with  
that, but it's not particularly exciting or challenging work, so I'd  
really only like to do it if there's a real chance of this work going  
into the standard release process, so that the manual is automatically  
produced in three, if not four, formats (maybe TeXinfo as well, if we  
want the man egg to work again) each time a release is prepared.

Before embarking on this project, I would really like to find out what  
the thinking of Felix and the Chicken team is on this subject. I  
assume that we want the same production process for both the manual  
and for eggs (you might remember my ridiculous suggestion, which I  
still defend, of a year or so ago that Chicken ought to be considered  
egg number zero). In particular, I don't quite understand the  
decisions on documentation that have taken us to where we are now  
(other than the decision to use the wiki for the original source text,  
which I feel very strongly is the absolutely right choice).

So here are my questions. Is there approval in principle (you  
obviously would need to look at the delivered product before making a  
final decision) that we'd like a fully-automated process that takes  
the Chicken manual in its original Wiki format, and produces final  
products in HTML (individual files and one file), PDF, and (maybe)  
TeXinfo/Info? If so, is a deliverable that uses LaTeX for the PDF  
version (without requiring any knowledge of LaTeX) acceptable? Is the  
man egg to be resurrected? How would all of this interact (if at all)  
with the process used for documenting eggs?

I recognize that LaTeX is not universally loved. However, you can  
produce nicer-looking output with it than with any other system  
(including TeXinfo) and that's why I did it. Any TeX-based solution  
has one astonishing advantage over any other solution such as Docbook,  
namely that the required software can be easily installed on pretty  
much any platform, whereas setting up Docbook or FOP is not for the  
timid. I am not trying to start a flame war here, I targeted LaTeX  
because I know it intimately; if the community wants something else  
instead, I am happy to go with it.

Waiting with bated breath -- vincent