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/>
