Literate Programming [was Re: Doc Tasks]

[roland dot kaufmann at space dot at]

>>>>> "Clark" == Clark McGrew <mcgrew@ale.physics.sunysb.edu> writes:

>>>>> "Greg" == Greg J Badros <gjb@cs.washington.edu> writes:

  [[lots of texinfo vs DocBook omitted]]

    Greg> But the point of Docbook markup is to permit getting any of
    Greg> those formats from a single source by enriching that source
    Greg> substantial.

    Clark> In that case, we should probably be using CWEB which is far
    Clark> more expressive that DocBook.  With CWEB there really isn't
    Clark> a distinction between source and documentation.  Personally
    Clark> I find it distracting but some people like it.

Most people experienced in Literate Programming (LP [1]) agree that LP
is not about mixing source and user-level documentation, but a way to
reason about source code, i.e. implementation documentation.  After
all, TeX's user/reference manual is the TeXbook, and only a small
proportion of TeX users have ever read the LP source"TeX, the
Program".

In the unlikely case LP would be adopted for Guile, it would be a way
to make eval more approachable and could provide a Guile internals
manual, but not the reference manual.

Hope this helps,
Roland

[1]  see the newsgroup comp.prog.literate
     www.literateprogramming.com