Literate Executables

--00000000000046c9ec05eeba8599
Content-Type: text/plain; charset="UTF-8"

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)

--00000000000046c9ec05eeba8599
Content-Type: text/html; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

<div dir=3D"ltr"><div>I&#39;m a huge believer in literate programming. In f=
act I&#39;m trying to <br></div><div>embed a complete computer algebra syst=
em (Axiom) in literate</div><div>form [0]. The PDFs listed on that page con=
tain the actual source</div><div>code that creates Axiom.</div><div><br></d=
iv><div>I believe you&#39;ve achieved &#39;the letter of the literate conce=
pt&#39;</div><div>but missed the &#39;spirit&#39;, as expounded by Knuth.<b=
r></div><div><br></div><div>Your ACM article on Literate Executables</div><=
div><a href=3D"https://queue.acm.org/detail.cfm?id=3D3570938">https://queue=
.acm.org/detail.cfm?id=3D3570938</a></div><div>inverts the approach I&#39;v=
e taken. I like your proposal.</div><div><br></div><div>In your approach th=
e executable is the primary carrier.</div><div>For small, stand-alone execu=
tables this is an excellent idea.</div><div>It has the potential to elimina=
te code-rot in supporting tools.<br></div><div><br></div><div><div>For a la=
rge system like Axiom, one key struggle is that Axiom <br></div><div>has va=
rious layers and subsystems. Working on one part of the <br></div><div>syst=
em does not affect other parts.</div><div><br></div><div>However, even more=
 fundamental is that literate programming is</div><div>about Explanation, n=
ot Documentation. Think of a physics textbook.</div><div>The equations (cod=
e) are quite opaque without the surrounding</div><div>paragraphs of explana=
tion. The same is true for complex software.<br></div></div><div><br></div>=
<div>In Axiom&#39;s approach the PDF is the primary carrier (the textbook).=
</div><div><br></div><div>The development cycle is to change the latex sour=
ce code <br></div><div>for the PDF. Then type &#39;make&#39; which (a) recr=
eates the PDF</div><div>and (b) recompiles the code. Rinse and repeat. At a=
ll times</div><div>the PDF and code are in sync. The purpose of the PDF is =
to</div><div>explain the concepts and hold the related code.</div><div><br>=
</div><div>My point is that your use of &#39;literate&#39; in &#39;literate=
 executables&#39; is</div><div>(slightly) missing the fundamental point of =
literate software.</div><div>It is true that it keeps the code in sync with=
 the executable and</div><div>keeps the code available for any given versio=
n. However, it</div><div>misses the fundamental literate point of &#39;Expl=
anation&#39;.</div><div><br></div><div>Tim Daly</div><div><a href=3D"http:/=
/daly.axiom-developer.org/~daly">http://daly.axiom-developer.org/~daly</a><=
br></div><div><br></div><div>[0] Axiom</div><div><a href=3D"https://en.wiki=
pedia.org/wiki/Axiom_(computer_algebra_system)">https://en.wikipedia.org/wi=
ki/Axiom_(computer_algebra_system)</a></div><div><br></div></div>

--00000000000046c9ec05eeba8599--