Hello, Alejandro, I figured you would respond to this sooner or later :) Thanks for the detailed section on generating Texinfo from wiki format. I did in fact discover Graham's code, and I wrote some code to fill in the missing functionality, however I haven't tested it yet, because I couldn't figure out how to use the code from svn-wiki-post-commit-hooks to run the wiki->texi converter on the files from the Chicken manual. How would you suggest that I go about creating a test harness for wiki->texi without having to create my own svnwiki site? I really just need to be able to test the converter code on a bunch of wiki files, without having to go through an svn repository and all that.
Also, you might want to consider implementing the eggdoc tags, which I find immensely useful when writing egg documentation -- perhaps this would facilitate the development of egg documentation on the wiki. I also like how eggdoc uses SXML -- why not follow its approach and just have a wiki->sxml converter and then converters for sxml to whatever. -Ivan On Thu, May 31, 2007 at 03:38:27AM +0000, Alejandro Forero Cuervo wrote: > 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 [email protected] http://lists.nongnu.org/mailman/listinfo/chicken-users
