Literate Programming

[Hans Georg Schaathun]

On Sat, 9 Apr 2011 03:45:55 -0700 (PDT), Jim
  <jim.hefferon at gmail.com> wrote:
:  I'm sorry; I don't understand "commenting code within a block" but I
:  wondered if it meant you were not fully familiar with the idea of the
:  web-type programs.

The idea was pretty clear from the web page you cited.  The web system
allows merging code and doc's within one file, but it does not provide
a markup language.  Hence I need to find a markup language with suitable
markup to go with it.

:  Before each chunk comes the description of what that chunk does.

Sure, and reST does this fine if every chunk is at the same level of
indentation, but if I split an indented block with a comment, reST
does not preserve the correct indentation.  Similarily, if the else
clause is in a different chunk from the corresponding if clause,
sphinx looses track and will not highlight consistently.  I posted an
example of what I wanted to do in reply to Robert Kern's post.

: > Alternatively, I could use pyweb directly with LaTeX.  However, then
: > I would need to find or create macro packages which provide the
: > features of reST directly in LaTeX.  Do you know of a good candidate?
: 
:  What features?

Standardised and well thought-out markup for functions/methods/classes etc.,
as well as highlighting.  

-- 
:-- Hans Georg