Re: Literate Programming

[Arun Isaac]

Hi Phil,

> This would be a neat idea.  For my actual use-case after some testing,
> I've decided I that the following feature - actually suits my case better: 
>
> (source :language [:tab 8] [:definition] [:stop] [:start] [:file])
>
> I'm documenting a Guix Channel inside the channel itself, which has some
> moderately fancy enhancements in it that are worthy of more than a few
> code comments

Very interesting! I'm curious to see how you've done this. If it's a
public channel, could you share a link? I might use this idea in my own
Guix channels.

> - I figured there were 2 ways of doing this:
>
> Or write the actual Channel itself in an skb file and then tangle the
> package definitions into scm files - which is the enhancement you're
> proposing, I think?

Yes, I was proposing this.

> Because I want the channel to "just work" with Guix, after some testing
> I've found the former is easier to accomplish as it keeps the repo
> looking exactly like Guix expects, just with an addition Skibilo file
> that Guix will just ignore.

I agree this is the simpler approach.

> One thing I did notice was when using the (source ....) function was
> that :definition would not pick-up definitions of the form (define-public
> ....) only (define ....).  I'm yet to look at the source code in
> details, but I'm hoping this work be a fairly trivial and useful
> addition to :definition's current functionality?

Yes, definitely, that would be very useful. We should also support
define-record-type, define-syntax, etc. Maybe, we should make it more
versatile by supporting any define-* symbol.

Patches welcome, if you are interested! If not, could you please create
a bug report by writing to our debbugs bug tracker at
skribilo-bugs@nongnu.org ? Someone else might take it up in the future.

Thanks! :-)
Arun