On Mon, Nov 8, 2021 at 12:36 PM Scott Kruger <[email protected]> wrote:

On 2021-11-06 11:12, Matthew Knepley did write:

...

On Sat, Nov 6, 2021 at 10:34 AM Patrick Sanan <[email protected]> wrote:

...

I don't know what WEB is, but if you're saying that this is kinda clunky, yes it definitely is - my only contention is that it's better than copy-pasting code and output. I'm not sure if there's an easier and/or better way with Sphinx.

WEB was the futuristic documentation idea of Don Knuth.

It never caught on (for good reasons IMO), but it is important historically and programmers should be aware of it: https://en.wikipedia.org/wiki/Literate_programming

Threadjack: My major problem with WEB was that it in essence assumed that everything was One Big Source File. I tried documenting parts of PETSc with it in the 90s and I found that it did not perform as well as sowing because it really wanted one gigantic control flow, just like the algorithms Knuth was presenting. Maybe a combination of sowing and Web could bridge the gap. Thanks, Matt

For those who love literate programming and fortran, PPPL developed this in the 80's: https://w3.pppl.gov/~krommes/fweb.html and I believe it is still maintained.

I dealt with a code written with this tool. Interesting, but I never wanted to follow it myself.

Scott

...

Thanks,

Matt

...

...

Doing actual literate documentation of key tutorial programs would be

a

...

...

nice way of doing this, but I realise that's a lot more effort.

This is still a hope/plan to go into doc/tutorials - follow the deal.ii model for a small number of key examples. Matt has done a couple of pages there already, in this direction.

Lawrence

-- What most experimenters take for granted before they begin their experiments is infinitely more interesting than any results to which their experiments lead. -- Norbert Wiener

https://www.cse.buffalo.edu/~knepley/ < http://www.cse.buffalo.edu/~knepley/>

-- Scott Kruger Tech-X Corporation [email protected] 5621 Arapahoe Ave, Suite A Phone: (720) 466-3196 Boulder, CO 80303 Fax: (303) 448-7756

-- What most experimenters take for granted before they begin their experiments is infinitely more interesting than any results to which their experiments lead. -- Norbert Wiener https://www.cse.buffalo.edu/~knepley/ <http://www.cse.buffalo.edu/~knepley/>