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/ _______________________________________________ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users