Re: Literate Executables

[Terence Kelly]

Hi Tim,

Thanks for your feedback, and for pointing me to Axiom.

One "literacy" aspect of literate executables is that the latter can "give 
an account of themselves," in the sense of dumping their own source --- 
and their own documentation, which of course can be a literate program!

Imagine if the Axiom executable(s) could dump the PDFs containing the 
Axiom literate programs.  That would ensure that any user capable of 
executing Axiom had the documentation *and* the source at her fingertips, 
with no possibility of executables and documentation becoming separated or 
mismatched.

I'd be happy to help if you'd like to try this.  As my example code ("grep 
literatizer") illustrates, endowing a program with literacy (in my sense) 
is remarkably easy.

Thanks again & let me know.

-- Terence


On Wed, 30 Nov 2022, Tim Daly wrote:

> I'm a huge believer in literate programming. In fact I'm trying to embed 
> a complete computer algebra system (Axiom) in literate form [0]. The 
> PDFs listed on that page contain the actual source code that creates 
> Axiom.
>
> I believe you've achieved 'the letter of the literate concept' but 
> missed the 'spirit', as expounded by Knuth.
>
> Your ACM article on Literate Executables 
> https://queue.acm.org/detail.cfm?id=3570938 inverts the approach I've 
> taken. I like your proposal.
>
> In your approach the executable is the primary carrier. For small, 
> stand-alone executables this is an excellent idea. It has the potential 
> to eliminate code-rot in supporting tools.
>
> For a large system like Axiom, one key struggle is that Axiom has 
> various layers and subsystems. Working on one part of the system does 
> not affect other parts.
>
> However, even more fundamental is that literate programming is about 
> Explanation, not Documentation. Think of a physics textbook. The 
> equations (code) are quite opaque without the surrounding paragraphs of 
> explanation. The same is true for complex software.
>
> In Axiom's approach the PDF is the primary carrier (the textbook).
>
> The development cycle is to change the latex source code for the PDF. 
> Then type 'make' which (a) recreates the PDF and (b) recompiles the 
> code. Rinse and repeat. At all times the PDF and code are in sync. The 
> purpose of the PDF is to explain the concepts and hold the related code.
>
> My point is that your use of 'literate' in 'literate executables' is 
> (slightly) missing the fundamental point of literate software. It is 
> true that it keeps the code in sync with the executable and keeps the 
> code available for any given version. However, it misses the fundamental 
> literate point of 'Explanation'.
>
> Tim Daly
> http://daly.axiom-developer.org/~daly
>
> [0] Axiom
> https://en.wikipedia.org/wiki/Axiom_(computer_algebra_system)