Re: Documentation (was Re: [Chicken-users] How to use prelude?)

[Alejandro Forero Cuervo]

> >Now, I have absolutely no problem with this. There is just one
> >catch: I don't want to maintain two versions of the manual, and we
> >definitely need something that can be installed locally.
> >Personally, I would suggest that we use
> >http://galinha.ucpel.tche.br/coop, since it's internal format can
> >be converted relatively easily to/from other formats. What we need
> >is a texi generator.  (any volunteers?)
> 
> I'll volunteer a few cycles, though I don't use streams and I know
> Alejandro is fond of them, hope that's not a barrier to entry. :-)
> I'll need to brush up on my texinfo, though, it's been a while.

Well, here is how I would recommend you do this.  The stream-wiki egg
separates the parsing of wiki format from the actual generation of
output.  The wiki->html function is defined as follows:

  (define (wiki->html str . rest)
    (stream-delay
      (let-optionals rest ( ..... )
        (wiki-parse (html-driver ..... ) .....))))

The html-driver call creates a "driver" for generating output.  A
"driver for generating output" is just a table with a lot of functions
that the wiki-parse function will be calling to generate HTML.

Just like html-driver there's also latex-driver that generates
parseable LaTeX code from a wiki file (it is 85% complete: on some
constructs such as images just generates some "[[Images not supported
in LaTeX mode]]" text) and odf-driver (20% complete, doesn't really
work right now) and texi-driver (which I made a long time ago but I
have never used, I would guess it is around 30% complete, but I could
be off by a big margin).  And there are some other drivers that
instead of generating output accumulate some information and return it
(links-driver, tags-driver).

Based on the latex-driver my wiki system can generate PDF files.  I
haven't enabled this for the Chicken wiki, but you can see an example
for another wiki that it handles here:

  http://bogowiki.org/transmilenio.pdf

So you can see where I'm going.  I would recommend you check the
texi-driver implementation and, comparing its functions with those in
html-driver, make sure they generate their output properly.  To do
that, you'll have to use streams, the whole output generation is based
on them. :-/  Though the examples in html-driver should be more than
enough to figure out how to do it.

Once texi-driver works, it will be fairly easy to add a caller for it
to svnwiki (and we would end up having a "Texi" link in the pages
right next to "Edit", "Tags", "History", etc.; clicking it would
download the current article in Texi format).

A quick note on my experience using streams instead of strings of
characters: it is ssslllooowww.  It uses a lot of conses and closures
which are discarded right away, which triggers a lot of garbage
collections, which makes everything slow.  And they force you to fill
your code with string->stream and stream->string everywhere (but I
might take a shot at solving that soon).  On the other hand,
programming with them is a real pleassure, as you get to write
everything in a purely functional manner, without requiring lots of
memory. :-)

Your help would be greatly appreciated, Graham!

Alejo.
http://azul.freaks-unidos.net/