literate programming in Leo: examples anybody?

[e.spin]

Hi all,
I tried hard and long to use Leo for Literate Programming but found
Leo difficult if not impossible to use to this aim.
My idea was to document not only the code but also the path of
thoughts that lead me to it (plus some other background material).
I found very easy to get an outline out of my existing Python code
base, but very difficult to add the (LaTeX) documentation the literate
programming way. So I continue to use noweb...but Leo continues to
intrigue me, I sort of feel its potentials...

In summary I want to extract code (Python, Makefile, ksh scripts) and
generate documentation.
I probably do not understand completely how Leo could help me, so I
plea for postings of some (non trivial) examples.

Thank you very much in advance
Bye
Enrico

[Edward K. Ream]

On Mon, Dec 14, 2009 at 3:16 AM, e.spin <enrico.s...@googlemail.com> wrote:

> In summary I want to extract code (Python, Makefile, ksh scripts) and
> generate documentation.
> I probably do not understand completely how Leo could help me, so I
> plea for postings of some (non trivial) examples.

We seem to have reached an important milestone in Leo; several people
want to use Leo to for literate programming or for generating LaTeX.
This is exciting, and I'll be glad to help this project.

Leo automatically generates output files directly from @file (old
name: @thin) nodes, so the "tangling" step in traditional literate
programming (TLP) "just happens". The question is, how do we simulate
the "weave" part of TLP?

If you want to emulate Knuth's original approach, then noweb would be
the natural way. Leo might help organize your .nw files, but that's
about it.

It would be odd, imo, to want to represent an entire Leo outline as
flat text. You would lose all of Leo's advantages, as described in
http://webpages.charter.net/edreamleo/design.html#how-leo-changes-the-notion-of-literate-programming

To extract selected parts of a Leo outline, and print those parts, you
could write your own "weave" script that does the following:

- Extract all @design-notes nodes to an @rst tree.
- Call Leo's rst3 command on the generated tree.

Within @design-notes nodes, you would represent text and code as in an
@rst tree, so you could use all of Leo's rst capabilities, as
described in Chapter 14:
http://webpages.charter.net/edreamleo/rstplugin3.html
You can then generate .tex files as usual using docutils (Leo's rst3 command).

These are just some thoughts. What you do depends strongly on what it
is you want to do. To repeat, I would not recommend trying to
represent large slabs of code as flat text, but it should be possible
to extract and print relatively small bits of code and documentation.

Edward