Re: [Chicken-hackers] single egg documentation format

[Alaric Snell-Pym]

On 31 Jul 2009, at 9:34 am, Peter Bex wrote:

> On Fri, Jul 31, 2009 at 05:23:34PM +0900, Ivan Raikov wrote:
> >  Ok, I can do some research and see if there is some existing wiki
> > parser that can be adapted to read the svnwiki dialect and produce
> > s-expressions. If there are some reasonable solutions out there,
> > then I
> > will propose an s-expression-based substitute for stream-wiki, and
> > some way to automatically merge eggdoc in such a wiki.
>
> You've got my help.  Starting monday, I will be able to work on such
> a wiki.

Cool!

But would it be crazy for me to suggest not putting documentation in
dedicated text files at all, but instead putting it in declarations in
a file that can be read as Scheme source (which may or may not be the
file that defines the symbols being documented), using appropriate
macros, that registers function documentation in a registry?

This makes it easy to keep the two in synch, and also means you can
attach the documentation to symbols in csi's environment, thereby
supporting (help 'fold) type magic.

Factor have done this, and the resulting effect is rather good:

http://gitweb.factorcode.org/gitweb.cgi?p=factor/.git;a=blob;f=core/splitting/splitting-docs.factor;h=354df832cab99bd2d1c3bb722c22a88c21c14c04;hb=HEAD

+

http://gitweb.factorcode.org/gitweb.cgi?p=factor/.git;a=blob;f=core/splitting/splitting.factor;h=5ec396e5ba6301376bc6f134f5c9581ad0ca8f3d;hb=HEAD

->

http://docs.factorcode.org/content/word-__que__head%2csplitting.html

Ok, I hate their syntax, but still, the idea's quite sound. Design a
documentation system that's meant to be 'online' in your prompt, then
you get the benefits of that, and being able to roll off static
documentation from it is then a nice and easy side effect.

ABS

--
Alaric Snell-Pym
Work: http://www.snell-systems.co.uk/
Play: http://www.snell-pym.org.uk/alaric/
Blog: http://www.snell-pym.org.uk/?author=4