Literate programming in multiple languages [closed]

Question

I've a library project which requires C's interoperability with other languages, and reasonable performance, but must be documented very clearly, à la literate programming, and whose documentation might benefit from a functional approach, like Haskell, or even Idris' proof features.

I'm therefore interested in building this library as a literate program, first writing the documentation and working Idris prototype code, and next writing C code that closely parallels the Idris code to address any performance issues and be easily linkable from other languages.

What literate programming tool do I want?

NuWeb is designed for multi-language literate programming, but their usage of the @ sign, or indeed any escape character, is problematic for functional languages like Idris, Haskell, etc.

Idris wants a literate programming tool to which I could contribute. I love their preferred approach of just using .tex files delimited by \begin{code} .. \end{code} blocks.

Idris, Haskell, etc. do not need tangle like C does, so doing that adds complexity and I'd prefer that any tool I'm using here sticks around.

An approach that minimizes tooling for library consumers might be to extract the C and Idris code using a simple Perl script like cat_latex_env:

#!/usr/bin/perl
use strict;
use warnings;

sub usage { die "Usage: cat_latex_env enviroment_name [filename]\n"; }
usage if ($#ARGV < 0);

my $env = shift;
my $begin = quotemeta "\\begin{$env}";
my $end = quotemeta "\\end{$env}";
while (<>) {
        if (/$begin/../$end/) {
                next if /$begin/ || /$end/;
                print;
        }
}

At which point the Idris should compile fine. And I could embed the tangle instructions needed by a literate programming tool for C like CWEB or NuWeb.

Thoughts?

Answer 1

If documentation is paramount, and you have some emacs affinity, then you might do worse than look at the literate programming support in org-mode. Babel is an org-mode extension allowing to integrate with many programming environments, including tangle-weaving compiled languages, executing code blocks, ...

It is thoroughly language agnostic, and since it has the DNA of an outliner, it allows to manage the documentation in a structured way. Of course it generates syntax highlighted HTML/LateX/PDF/... from your sources.

Check out http://orgmode.org/worg/org-contrib/babel/intro.html for more info.

a sample:

** Compiles libpq library for iOS

copy this script as *build-ios.sh* in the root of the postgresql
source tree.

#+BEGIN_SRC sh tangle:build-ios.sh
mkdir -p build
rm -rf build/* #*/

function build_libpq()   
{
    make distclean

    ./configure \
...snip...
lipo -create -output libpq.a build/*

#+END_SRC

Run it and it will create a universal library and  separate arm  
library in the root folder.

I hope this gives an idea what to do to create docs/code using org-mode/Bable combination. Of course a stackexchange answer cannot begin to scratch the surface of this system.