5 ms·

You wrote "There's a fundamental problem with generating a beautifully typeset document for a codebase: it's dead. It can't render inside just about any actual

by daly 5y ago

You wrote "There's a fundamental problem with generating a beautifully typeset document for a codebase: it's dead. It can't render inside just about any actual programming environment (editor or IDE) on this planet, and so we can't make changes to it while we work on the codebase." Sorry, that's not correct. When writing a literate program you should also include a chunk containing a Makefile. Extract the Makefile and let it construct the program. I did this with the whole Clojure programming language. The whole source code for all of Clojure, as well as the test cases, are in the PDF. The sequence (from scratch is): Extract the Makefile from the Latex document. Run the Makefile. This: 1) extracts the code and tests 2) compiles the code 3) runs the tests 4) recreates the PDF from the Latex So you edit the Latex text and/or code with any editor and then re-run the Makefile. This will rebuild your program, runs the tests, and re-makes the PDF. If you have the PDF open next to your editor it is likely that the PDF viewer will reload the changes immediately. This ensures that (a) your program compiles, (b) your program passes tests, and (c) the PDF builds correctly. I've been working on literate programs for years. See https://en.wikipedia.org/wiki/Axiom_(computer_algebra_system) https://en.wikipedia.org/wiki/Axiom_(computer_algebra_system.... I've even given a talk on the subject See https://www.youtube.com/watch?v=Av0PQDVTP4A https://www.youtube.com/watch?v=Av0PQDVTP4A). I find literate programming to be the MOST important change in programming since I started in 1970.

nesarkvechnep 5y ago
Isn’t the tangle-untangle process fundamental in literate programming?
- kryptiskt 5y ago
  I wouldn't say it's absolutely needed in a language like Haskell, where functions and types can be defined in any order. So if you want to defer implementing something until later in the document you can just make it a function and get back to it later.
  - daly 5y ago
    Lisp has the same ability to define things in any order. Java wants specially named paths to files. The Makefile can create the directory structure and use the "tangle" program to extract the files to the correct place. That's what I did in the Clojure example.
- daly 5y ago
  There is a trivial C program that is also in the document. It does the actual "chunk" extraction from the Latex. The Makefile uses it to extract named chunks. The program scans the Latex looking for named "chunk" blocks. Each named block is put in a hash table under the name. Once the scan is complete you use a provided command line argument to extract the named chunk to a file. Of course, the chunk can include other chunks and these get extracted and expanded inline. So tanglec myliteratefile.tex achunkname > myfile.lang This creates a hash table from "myliteratefile.tex" containing named chunks, then prints the chunk "achunkname" to stdout (recursively expanding chunks embedded in other chunks). The Makefile can extract Java files and put them in the proper directories. It really is a trivial C program. Make a hash, print a hash key. This would be a simple interview test question. (Actually I use Lisp, mostly because I always code in Lisp these days, but lets not start that war.)
rustybolt 5y ago
Newsflash: a PDF viewer is not a programming IDE.
- andreareina 5y ago
  I do literate programming in emacs via org-mode. The output pdf is viewable in emacs, and it auto-reloads in change. In fact I can have it switch to the pdf buffer on weaving the pdf.
  - rustybolt 5y ago
    I see that as a separate text editor and pdf viewer but I guess it blurs the lines a bit.
cloogshicer 5y ago
While you're editing code (which is most of the time), aren't you still reading and working with the non-typeset version?
- daly 5y ago
  Well, you're editing the Latex version of the literate program. But since my development "style" is to make small changes, rebuild, test, and re-create the code and PDF, my "thinking" isn't focused on the "non-typeset" version. Pick up a physics textbook. Copy down all of the equations. Throw away the textbook and learn physics only using the equations. That's what programmers do. They write down the "equations" but fail to explain the ideas. Equations, like programs, are really just an "iconic form" of an idea. The idea, however, lives in the surrounding text.
  - cloogshicer 5y ago
    My point is: what I believe the author meant when he wrote that a typeset document 'is dead', is that you're not actually editing the typeset document. You're editing the code, which is then rendered - maybe instantly and continuously, but still. You're not __directly__ editing the "nicer" representation.
    - couchand 5y ago
      You also aren't directly editing the observable runtime behavior of the system, yet programmers seem to be able to handle that jump regularly.
argiopetech 5y ago
+1 for the talk on "Literature Programming in the Large" (linked in the post above.) Mr. Daly, your chat was formative for me as I made the switch to literate programming (primarily with org/org-babel) in most of my work and personal projects. While I'd love to see what was in your slides, I'm glad the talk turned out "off the cuff." Thank you!
- daly 5y ago
  The slides basically show examples from other literate programs. I also intended to give a live demonstration of literate code development, as outlined above. It only takes a minute or so to start from the PDF to create a running, tested version of Clojure running in Java, along with a new PDF. I intended to demonstrate changing both code and data in real time.

by daly 5y ago

nesarkvechnep 5y ago

Isn’t the tangle-untangle process fundamental in literate programming?

kryptiskt 5y ago
I wouldn't say it's absolutely needed in a language like Haskell, where functions and types can be defined in any order. So if you want to defer implementing something until later in the document you can just make it a function and get back to it later.
- daly 5y ago
  Lisp has the same ability to define things in any order. Java wants specially named paths to files. The Makefile can create the directory structure and use the "tangle" program to extract the files to the correct place. That's what I did in the Clojure example.
daly 5y ago
There is a trivial C program that is also in the document. It does the actual "chunk" extraction from the Latex. The Makefile uses it to extract named chunks. The program scans the Latex looking for named "chunk" blocks. Each named block is put in a hash table under the name. Once the scan is complete you use a provided command line argument to extract the named chunk to a file. Of course, the chunk can include other chunks and these get extracted and expanded inline. So tanglec myliteratefile.tex achunkname > myfile.lang This creates a hash table from "myliteratefile.tex" containing named chunks, then prints the chunk "achunkname" to stdout (recursively expanding chunks embedded in other chunks). The Makefile can extract Java files and put them in the proper directories. It really is a trivial C program. Make a hash, print a hash key. This would be a simple interview test question. (Actually I use Lisp, mostly because I always code in Lisp these days, but lets not start that war.)

rustybolt 5y ago

Newsflash: a PDF viewer is not a programming IDE.

andreareina 5y ago
I do literate programming in emacs via org-mode. The output pdf is viewable in emacs, and it auto-reloads in change. In fact I can have it switch to the pdf buffer on weaving the pdf.
- rustybolt 5y ago
  I see that as a separate text editor and pdf viewer but I guess it blurs the lines a bit.

cloogshicer 5y ago

While you're editing code (which is most of the time), aren't you still reading and working with the non-typeset version?

daly 5y ago
Well, you're editing the Latex version of the literate program. But since my development "style" is to make small changes, rebuild, test, and re-create the code and PDF, my "thinking" isn't focused on the "non-typeset" version. Pick up a physics textbook. Copy down all of the equations. Throw away the textbook and learn physics only using the equations. That's what programmers do. They write down the "equations" but fail to explain the ideas. Equations, like programs, are really just an "iconic form" of an idea. The idea, however, lives in the surrounding text.
- cloogshicer 5y ago
  My point is: what I believe the author meant when he wrote that a typeset document 'is dead', is that you're not actually editing the typeset document. You're editing the code, which is then rendered - maybe instantly and continuously, but still. You're not __directly__ editing the "nicer" representation.
  - couchand 5y ago
    You also aren't directly editing the observable runtime behavior of the system, yet programmers seem to be able to handle that jump regularly.

argiopetech 5y ago

+1 for the talk on "Literature Programming in the Large" (linked in the post above.) Mr. Daly, your chat was formative for me as I made the switch to literate programming (primarily with org/org-babel) in most of my work and personal projects. While I'd love to see what was in your slides, I'm glad the talk turned out "off the cuff." Thank you!

daly 5y ago
The slides basically show examples from other literate programs. I also intended to give a live demonstration of literate code development, as outlined above. It only takes a minute or so to start from the PDF to create a running, tested version of Clojure running in Java, along with a new PDF. I intended to demonstrate changing both code and data in real time.