literate programming in D

[Philippe Sigaud via Digitalmars-d-learn]

> Ah that sounds interesting too! Immediately I start thinking in terms like
> tidlywiki http://tiddlywiki.com/ or something similar, I guess the emacs way
> described earlier also would support this. I personally always enjoy reading
> the readthedocs stuff http://docs.readthedocs.org/en/latest/ is that the
> sort of stuff you mean?

Tiddlywiki is interesting, but I'm really talking about the way LP was
used by Knuth WEB/CWEB in his explanation of TeX and METAFONT.
The Wikipedia article explains it pretty well
(http://en.wikipedia.org/wiki/Literate_programming)

You write a document combining documentation and code. Then two
different programs (weave and ? for WEB) create the resulting
documentation for one (HTML, pdf, whatever) and the code (a .d file)
for another.


I discovered LP through the incredible book "Physically-based
Ray-Tracing". The book is one program, explained and documented using
literate progamming. It's an incredible achievement (1000+ pages of
explanations!).
See:

www.pbrt.org

and more precisely:

http://www.pbrt.org/chapters/pbrt_chapter7.pdf

The code begins at page 18 of the pdf.

For example, at page 22:

<Sample Method Definitions> ≡
    Sample::Sample(SurfaceIntegrator *surf, VolumeIntegrator *vol,
const Scene *scene) {
        surf->RequestSamples(this, scene);
        vol->RequestSamples(this, scene);
        <Allocate storage for sample pointers 301>
        <Compute total number of sample values needed 302>
        <Allocate storage for sample values 302>
}

The snippet <Sample Method Definitions> introduces three new snippets,
that will be explained elsewhere. Other snippets might also use the
same references, if needed.

It's not complicated to write a D tool for that, I did that some time
ago. Once you define your begin/end token for snippet definitions, you
can parse them to extract the way they are linked.