Re: [Chicken-users] Chicken manual in Texinfo format

[Alejandro Forero Cuervo]

I wish I had seen the thread about the Chicken manual before.  Anyway,
here are my thoughts.  I'll use a bit of wiki format for this message,
heh.  I'll try to keep it short.

== Improving the contents of the manual:

I agree with the people that think the manual should be improved to
make it more useful for people not already familiar with Scheme.  I
think Felix would agree as well (but I'm not sure).

If you have time to help us improve the manual, by all means do!
Think you can reorganize it all to have a far better structure?
Please help!  There is no need to start from scratch.

Would anyone oppose adding more information about Scheme to the
manual, even though it may be obvious for advanced users?  I think
some introductory section or two about Scheme would be great.

As a matter of fact, Nelson Castillo and I had already started one
such document (an Unofficial Manual):

    http://chicken.wiki.br/manual

Any help integrating it with the official manual would be welcome (I
think; Felix, what do you say?).

BTW, if you plan to spend some hours working on the manual, you may
want to work on it through your text editor (instead of the web
interface): http://chicken.wiki.br/svn%20checkout

== Format of the authoritative version

It's best to keep the authoritative version of the manual in wiki
format instead of Texinfo.  I think this makes it easier for most to
contribute to it.  I also think a Texinfo version should be generated
from it.

== Generating texinfo from wiki format

The stream-wiki egg was designed to make it reasonably easy to define
new output formats that are generated from the wiki file.  Basically,
you need to define a table of functions (a «driver») for the different
syntactic constructs.  These functions receive as parameters the
inputs from the wiki format and should return a stream with the actual
output.  The generic wiki-parse function receives the driver that is
used to produce the output (wiki->html, for example, is just a wrapper
that calls wiki-parse with the HTML driver).

So far the following output drivers haven been defined:

    ODF:

        Extremely incomplete.  But, at some point, I'll probably take
        the time to finish it, since ODF is just XML.

    HTML:

        This is the most stable driver.

    Text:
   
        This produces a text document from the wiki.  You can think of
        it as removing the wiki formatting, though sometimes it does
        clever things.  For example, the wiki string

            [[http://opwifi.com|OpWifi Project]]

        becomes

            OpWifi Project [http://opwifi.com]

    Links:

        This is a variation of the usual driver.  It doesn't really
        generate any output.  However, it calls a function once for
        each and every link in the wiki file.  Along with
        iterator->stream from the stream-ext egg, it gets you a stream
        with all the links in a wiki file.

    Tags:

        This is similar to links.  Gets a list of tags in the file (as
        in “[[tags: foo bar quux]]”).  This is soon to be deprecated
        (the tags should be stored separate from the contents of the
        files, not as part of them).

    LaTeX:

        Works for most constructs, but there are some that it doesn't
        get well.  I guess it is ok.

    Texi:

        Mostly the work of Graham Fawcett.  It is still incomplete.  I
        think getting this to work should be far less work than
        starting from scratch.

I list the drivers here just to reinforce the point that the code in
stream-wiki egg was written to support multiple outputs and I think
generating texi directly from wiki should *not* be regarded as “an
ugly hack”.

== Workflow for generating the manual

The manual should reside in its current Subversion repository.  This
is a separate discussion as to what format it should use, since it
could be stored there and still somewhat managed by Svnwiki if it
became a Texinfo (or whatever) document.  Keeping it there allows most
of us who have the repository checked out to make improvements easily
with our favorite text editors.  It also allows casual contributions,
which are welcome.  I think this supports a very good workflow.

The only drawback I see is that Svnwiki sometimes becomes unstable
because of bugs.  While this has not happened in the last months (or,
if it has, I haven't noticed), I'm almost certain it will occur again
in the future, as we keep adding features to svnwiki.

== Generating an index

We can define any new constructions for extending the wiki syntax in
SGML-like ways.  Currently, we have this:

    (define (chicken-egg-html env)
      (let-from-environment env (params parse path-in)
        (or
          (and-let* ((name-stream (assoc 'name params))
                     (name (stream->string (cdr name-stream)))
                     (description (assoc 'description params))
                     (license (assoc 'license params))
                     (author (assoc 'author params)))
            (parse
              (html-stream  
                (tr (td (if (file-exists? (svnwiki-make-pathname path-in name))
                          (format #f "[[~A]]" name)
                          (format #f "[[~A~A.html|~A]]" *url-eggs* name name)))
                    (td (cdr description))
                    (td (cdr license))
                    (td "[[" (cdr author) "]]")))))
          stream-null)))
    
    (define *extensions*
      `((chickenegg (code-break ,chicken-egg-html))))
 
What that does is replace the string

    <chickenegg name="chairthrow" description="The best egg ever" 
license="non-free" author="steve ballmer" />

with HTML for a table.

We could, similarly, define support for other tags.  For example,

    <procedure name="with-input-from-file" parameters="file tunk" />

could be expanded to something else.  This would allow us to embed
more semantics in the wiki format, and we could use this to generate
indexes.

If we can agree on some templates for the tags we should support and
the wiki-code the should expand to, I would gladly code them.

Thanks.

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