Another approach to Literate Programming

I tried for Literate Programming (LP) two solutions: Nuweb and Python tool Pyweb and found Pyweb tool is better. But with LP there are some problems:

1. it's not very easy to work with "hidden" source: after tangling http://www.blogger.com/img/blank.gifand weaving you get pure source code and should debug source code (this is usually a "solid" process), after this - should modify .w file


2. usage of "placeholders" lines split code (difficult for debugging)

Another approach is to use reStructuredText document generator system (see docutils). How to? It's easy: instead of embedding into source code the hyper-text formatting, images, links, you can write your program like story (in usual LP style), use RST syntax (like WiKi) for images embedding and various styles - your code is Literate Programming story as before. But now you can embed code fragments where you need with "include" directive of docutils. This directive requires "startd-after" and "end-before" options for this case. These options defines line (string fragment) the code starts after, and line - the code ends before. I use for this lines Vim foldering lines. See:

// Source code:
int x;
// Opening port {{{
int open_port(int port) {
...
}
// }}}

This is very usuable for folding big source code!
And in your .rst file (which plays a role of the .w file but for weaving only):

and we define the function for a port opening:

.. include:: port.c
    :start-after: // Opening port {{{
    :end-before: // }}}

Thos technique is not pure LP but is like LP without LP cons. And it's simple documentation approach :)