Re: Literate programming

[Nikita Karetnikov <nikita@karetnikov.org>]

[-- Attachment #1: Type: text/plain, Size: 1313 bytes --]

>> What do you think about literate programming [1,2,3]?

> I don’t think it’s appropriate here.  We have (or should have) user doc
> for command-line tools, a manual for the API, as well as an on-line
> reference in the form of docstrings; the code itself is reasonably
> commented, I think, and in a functional style that hopefully simplifies
> reasoning a bit (I know there’s more to it than just writing functional
> code, but still, it’s better than TeX macros ;-)).

> WDYT?

Here is what I found yesterday: [1,2].  Those (texinfo ...) modules
provide various functions to generate html, pdf, and info from a single
source file.  If different files are used, it's easy to end up with
undocumented code [3] or to have a documentation for nonexistent
functions [4].

There might be some problems (I've only checked a couple of functions).
Though, I hope that we'll give it a try.

The only drawback I see right now is the need to adapt the existing
modules.  But I'm willing to do it.

[1] http://wingolog.org/archives/2004/07/25/literate-programming-with-guile-lib
[2] http://wingolog.org/archives/2006/11/17/high-on-sodium-vapor
[3] https://lists.gnu.org/archive/html/guile-user/2007-06/msg00046.html
[4] https://lists.gnu.org/archive/html/bug-guile/2013-04/msg00000.html

[-- Attachment #2: Type: application/pgp-signature, Size: 835 bytes --]