> In the example below, > some will remark that you've no longer wrapped the procedure > description in a tag. However, any reasonable parser should be able > to reconstruct this information heuristically--after all, we don't > require the user to wrap entire wiki sections in tags; we simply > reconstruct where they end.
I think you've touched on a crucial aspect of this, specially by your use of the word “heuristically”. Clearly, we are not looking for an XML-based (or, equivalently, an s-expr based) format, but some compromise between the goals of (1) being very easy to edit and (2) containing semantics that can be extracted by other tools. In practice, I expect to use drivers (in the stream-wiki definition of “drivers”) to programatically extract meaning (such as a wiki->procedures function, receiving a wiki page and returning a list (stream) of all the procedures defined on it). I like your example. I will add a bit to it: > <proc>(+ a b ...)</proc> > > Adds two or more values. > > Examples: > > <example> > <label>Add 3 numbers together</label> > <expr>(+ 1 2 3)</expor> > <result>6</result> > </example> > > <example> > <label>Simple example of adding two numbers</label> > <expr>(+ 4 5)</expr> > <result>9</result> > </example> > > <proc>(string-append a b ...)</proc> > > ... > > Examples: > > <example> > <label>Simple example of appending two strings.</label> > <expr>(string-append "foo" "bar")</expr> > <result>"foobar"</result> > </example> > > ... > > <example> > <label>Simple example of the use of {{~A}} escape sequences.</label> > <init>(use format-modular)</init> > <expr> > (format #t "There are ~A objects." 10) > </expr> > <outputport>There are 10 objects.</outputport> > </example> Note that with just a bit of glue (a driver similar to the wiki->procedures I described above) we would very easily be able to extract the information from the examples and turn it into unit tests, so users adding examples to the documentation would actually be defining user tests and we could programatically get notified when we break one of the examples in our documentation. We could also create wiki pages to contain nothing but tests like these and encourage users to submit new tests to them (of course, the person running the tests would need to validate the logs/diffs or use sandboxes). This is something I find very exciting. Care to add more to my example above? I'll probably implement something like this during the next weekend or so. Alejo. http://azul.freaks-unidos.net/ _______________________________________________ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users