Re: [Chicken-users] egg documentation

[Alejandro Forero Cuervo]

> 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/