Comment by daly | Hacker News Reader

Comment by daly | Hacker News Reader

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.... I've even given a talk on the subject See https://www.youtube.com/watch?v=Av0PQDVTP4A).

I find literate programming to be the MOST important change in programming since I started in 1970.

+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!

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.

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

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.

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.

You also aren't directly editing the observable runtime behavior of the system, yet programmers seem to be able to handle that jump regularly.

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

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.

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.

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.)

Newsflash: a PDF viewer is not a programming IDE.

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.

I see that as a separate text editor and pdf viewer but I guess it blurs the lines a bit.

Reply on news.ycombinator.com