[petsc-dev] [DocTip!] #2: Aiming for self-updating docs

[Matthew Knepley]

On Mon, Nov 8, 2021 at 12:36 PM Scott Kruger <kruger at txcorp.com> wrote:

> On 2021-11-06 11:12, Matthew Knepley did write:
> > On Sat, Nov 6, 2021 at 10:34 AM Patrick Sanan <patrick.sanan at gmail.com>
> > 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               kruger at txcorp.com
> 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/>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mcs.anl.gov/pipermail/petsc-dev/attachments/20211108/31fac225/attachment.html>