chicken-hackers
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Chicken-hackers] single egg documentation format


From: Alaric Snell-Pym
Subject: Re: [Chicken-hackers] single egg documentation format
Date: Fri, 31 Jul 2009 18:08:42 +0100


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






reply via email to

[Prev in Thread] Current Thread [Next in Thread]