Re: Literate Executables
Tim Daly <[email protected]> Fri, 2 Dec 2022 11:49:08 -0500
| Newsgroups | gmane.comp.mathematics.axiom.devel |
|---|---|
| Message-ID | <CAJn5L=LeYve0PEQ23v2nAC0S0AsoCSywPa3k7-0S23=vhgty9w@mail.gmail.com> |
--00000000000084a87c05eedb1eb3 Content-Type: text/plain; charset="UTF-8" As I mentioned, I really like your idea of embedding code in various support tools such as make, grep, etc. It would prevent code-rot as it would be possible (assuming C++ would hold still for a week) to be able to recreate the support tool. Axiom uses git. That makes it possible to check out a particular instance at any given time in the past. On a practical level generating the PDFs from inside the Axiom executable is questionable. Axiom has about 1.2 million lines of code. The PDFs that contain the code, the images, etc. would be MUCH larger. It would be much easier to create an Axiom command for a given function to link a URL to the PDF and pop the PDF up in a browser. Axiom's PDFs can contain 6000 pages. On a philosophical level, the question is one of emphasis. Axiom is a large computer algebra system. Understanding it in detail requires a PhD level of mathematical education. Indeed some of the algorithms were implemented as part of a PhD thesis. It is not reasonable to expect anyone to understand some of the algorithms without access to explanation. The code is opaque. As mentioned before, my approach to literate programming leans toward 'textbooks'. The textbook has an expected structure which includes an introduction, a table of contents, chapters, sections, cross-references, an index, and a bibliography. People know what to expect and how to navigate a book. This gives structure to the explanation and makes it easier to find things. Also of philosophical note, the fundamental point of a literate program, in my approach, is explanation (not documentation). So the PDF book is the primary element (as it would be in physics textbook). The code is secondary (as equations would be in physics textbooks). The explanation communicates to the human in hopefully precise terms whereas the code communicates to the machine and could have many different implementations. To your point, the project goal of Axiom emphasizes literate programming because, unlike other kinds of software, the mathematical algorithms will not soon go out of date. However, open source software tends to die when the lead developers stop working on a project. The literate programming approach is an effort to let Axiom live beyond the current authors (some of whom are already dead). The above considerations leads me to the conclusion that the PDF is the thing that generates code rather than the code generating the PDF. Tim Daly http://axiom-developer.org/~daly On Thu, Dec 1, 2022 at 10:00 PM Terence Kelly <[email protected]> wrote: > > > 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) > --00000000000084a87c05eedb1eb3 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable <div dir=3D"ltr"><div>As I mentioned, I really like your idea of embedding = code in various</div><div>support tools such as make, grep, etc. It would p= revent code-rot as</div><div>it would be possible (assuming C++ would hold = still for a week) to</div><div>be able to recreate the support tool. Axiom = uses git. That makes it</div><div>possible to check out a particular instan= ce at any given time in the past.</div><div><br></div><div>On a practical l= evel generating the PDFs from inside the Axiom <br></div><div>executable is= questionable. Axiom has about 1.2 million lines of</div><div>code. The PDF= s that contain the code, the images, etc. would</div><div>be MUCH larger. I= t would be much easier to create an Axiom</div><div>command for a given fun= ction to link a URL to the PDF and pop</div><div>the PDF up in a browser. A= xiom's PDFs can contain 6000 pages.<br></div><div><br></div><div>On a p= hilosophical level, the question is one of emphasis.</div><div><br></div><d= iv><div>Axiom is a large computer algebra system. Understanding it in <br><= /div><div>detail requires a PhD level of mathematical education. Indeed som= e</div><div>of the algorithms were implemented as part of a PhD thesis. It = is</div><div>not reasonable to expect anyone to understand some of the <br>= </div><div>algorithms without access to explanation. The code is opaque.<br= ></div></div><div><br></div><div>As mentioned before, my approach to litera= te programming leans</div><div>toward 'textbooks'. The textbook has= an expected structure which</div><div>includes an introduction, a table of= contents, chapters, sections,</div><div>cross-references, an index, and a = bibliography. People know what</div><div>to expect and how to navigate a bo= ok. This gives structure to the</div><div>explanation and makes it easier t= o find things.<br></div><div><br></div><div>Also of philosophical note, the= fundamental point of a literate program,<br></div><div>in my approach, is = explanation (not documentation). So the PDF book</div><div>is the primary e= lement (as it would be in physics textbook). The code</div><div>is secondar= y=C2=A0 (as equations would be in physics textbooks). The <br></div><div>ex= planation communicates to the human in hopefully precise terms</div><div>wh= ereas the code communicates to the machine and could have many</div><div>di= fferent implementations.</div><div><br></div><div>To your point, the projec= t goal of Axiom emphasizes literate programming</div><div>because, unlike o= ther kinds of software, the mathematical algorithms will</div><div>not soon= go out of date. However, open source software tends to die when</div><div>= the lead developers stop working on a project. The literate programming</di= v><div>approach is an effort to let Axiom live beyond the current authors (= some</div><div>of whom are already dead).<br></div><div><br></div><div>The = above considerations leads me to the conclusion that the PDF</div><div>is t= he thing that generates code rather than the code generating the PDF.</div>= <div><br></div><div>Tim Daly</div><div><a href=3D"http://axiom-developer.or= g/~daly">http://axiom-developer.org/~daly</a></div><div><br></div></div><br= ><div class=3D"gmail_quote"><div dir=3D"ltr" class=3D"gmail_attr">On Thu, D= ec 1, 2022 at 10:00 PM Terence Kelly <<a href=3D"mailto:[email protected]= ch.edu">[email protected]</a>> wrote:<br></div><blockquote class=3D= "gmail_quote" style=3D"margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(2= 04,204,204);padding-left:1ex"><br> <br> Hi Tim,<br> <br> Thanks for your feedback, and for pointing me to Axiom.<br> <br> One "literacy" aspect of literate executables is that the latter = can "give <br> an account of themselves," in the sense of dumping their own source --= - <br> and their own documentation, which of course can be a literate program!<br> <br> Imagine if the Axiom executable(s) could dump the PDFs containing the <br> Axiom literate programs.=C2=A0 That would ensure that any user capable of <= br> executing Axiom had the documentation *and* the source at her fingertips, <= br> with no possibility of executables and documentation becoming separated or = <br> mismatched.<br> <br> I'd be happy to help if you'd like to try this.=C2=A0 As my example= code ("grep <br> literatizer") illustrates, endowing a program with literacy (in my sen= se) <br> is remarkably easy.<br> <br> Thanks again & let me know.<br> <br> -- Terence<br> <br> <br> On Wed, 30 Nov 2022, Tim Daly wrote:<br> <br> > I'm a huge believer in literate programming. In fact I'm tryin= g to embed <br> > a complete computer algebra system (Axiom) in literate form [0]. The <= br> > PDFs listed on that page contain the actual source code that creates <= br> > Axiom.<br> > <br> > I believe you've achieved 'the letter of the literate concept&= #39; but <br> > missed the 'spirit', as expounded by Knuth.<br> > <br> > Your ACM article on Literate Executables <br> > <a href=3D"https://queue.acm.org/detail.cfm?id=3D3570938" rel=3D"noref= errer" target=3D"_blank">https://queue.acm.org/detail.cfm?id=3D3570938</a> = inverts the approach I've <br> > taken. I like your proposal.<br> > <br> > In your approach the executable is the primary carrier. For small, <br= > > stand-alone executables this is an excellent idea. It has the potentia= l <br> > to eliminate code-rot in supporting tools.<br> > <br> > For a large system like Axiom, one key struggle is that Axiom has <br> > various layers and subsystems. Working on one part of the system does = <br> > not affect other parts.<br> > <br> > However, even more fundamental is that literate programming is about <= br> > Explanation, not Documentation. Think of a physics textbook. The <br> > equations (code) are quite opaque without the surrounding paragraphs o= f <br> > explanation. The same is true for complex software.<br> > <br> > In Axiom's approach the PDF is the primary carrier (the textbook).= <br> > <br> > The development cycle is to change the latex source code for the PDF. = <br> > Then type 'make' which (a) recreates the PDF and (b) recompile= s the <br> > code. Rinse and repeat. At all times the PDF and code are in sync. The= <br> > purpose of the PDF is to explain the concepts and hold the related cod= e.<br> > <br> > My point is that your use of 'literate' in 'literate execu= tables' is <br> > (slightly) missing the fundamental point of literate software. It is <= br> > true that it keeps the code in sync with the executable and keeps the = <br> > code available for any given version. However, it misses the fundament= al <br> > literate point of 'Explanation'.<br> > <br> > Tim Daly<br> > <a href=3D"http://daly.axiom-developer.org/~daly" rel=3D"noreferrer" t= arget=3D"_blank">http://daly.axiom-developer.org/~daly</a><br> > <br> > [0] Axiom<br> > <a href=3D"https://en.wikipedia.org/wiki/Axiom_(computer_algebra_syste= m)" rel=3D"noreferrer" target=3D"_blank">https://en.wikipedia.org/wiki/Axio= m_(computer_algebra_system)</a><br> </blockquote></div> --00000000000084a87c05eedb1eb3--