@oblomov

apologies, real life kept reminding me that it exists  

This is the Basic List of #LiterateProgramming Features That I Have Been Missing And Occasionally Implementing In Isolation, But Would Like To Implement Together Sometime Soon:

  • a mechanism for systematically attaching persisting numbers to a web's nodes (chapters, sections, leaves, leaf groups / rubrics if used);
  • a mechanism for generating missing numbers automatically when they, or some of them, have not yet been attached, but in a way that would allow them to persist in the future;
  • a mechanism for querying a selection of nodes from a web into a sub-web, and for patching them back into the underlying web after editing;
  • hashtagging a selection of a web's nodes so they could be extracted together, or disabled/enabled together at processing time, somewhat akin to Knuth's INIT...TINI and STAT...TATS mechanism;
  • a mechanism for mapping a web, or a collection of webs, into a number of smallish hyperlinkable wiki-style pages for easy on-the-web reading (and preferably, for also allowing the wiki-edited web/webs gathered back into a single-file web;
  • a mechanism for presenting a program as a series (or DAG) of /layers/, allowing one to start from a simple model, and then build successive complexity on it by adding to, replacing, or turning off nodes (or chunk lists / capers) of previous layers;
  • a syntax for defining 'records' or 'frames' or 'cards' comprising of sets of chunk / pace definitions that belong logically together, and a mechanism for querying these records, and for tangling them according to templates;
  • a mechanism for loading a table of such records, or a stripe of such a table, from an external source such as a CSV, possibly an SQLite table / view, and possibly a JSON/YAML list of records;
  • a mechanism for treating a tangled file as an immediate input for weaving, to simplify maintenance of the kind of documentation that involves long lists of implemented mechanics;
  • a mechanism for using a single-file web as a self-contained script with (some) embedded configuration, so that the same file could be both directly executable, and as a source for tangling (and, particularlly, for weaving into its documentation).

I have implemented everything on this list at least once, and some things several times. Most of these have a relatively straightforward One Obvious Way to implement them; the concept of records and their potential inheritance / prototype linkage mechanism is the oddball that can be done in a number of mutually incompatible ways.

In case these come up, a couple of terms that I like but that not everybody uses are:
-- an 'article' is a bunch of webbly-wobbly stuff in a single file or a single web page / wikipage;

  • an 'aside' is a formal digression in a narrative, potentially presented as a sidebar box or an unfoldable node on the web, or as a figure comprising of some discussion and some code in the printed form;
  • an 'automatic' table or form (or plot), as contrary to a 'manual' one, is one that is generated by the LP engine (possibly runnign an external tool or script) tools during processing, and may be used as an illustration in the weaved output;
  • a 'caper' is a series of a job's paces that go together;
  • a 'caper sign' is the marker for one or more upcoming paces that belong to a single caper (but may not comprise the whole of this caper);
  • an 'entity' is a set of fields or attributes that go together, but may be presented as multiple forms, and/or external table rows, and presents a single unified node in teration;
  • a 'fiat' is a kind of stand-alone directive that can be embedded into an article for fine processing control;
  • a 'form' is a set of fields or attributes (which may be paces) describing an entity presented together;
  • a 'job' is a whole set of input needed for tangling (and potentially, for weaving);
  • a 'leaf' is the non-outlined bottom level of structural narrative nodes of an article; some people call it a 'chunk' and define it as comprising of some text followed by some code; confusingly, some people call these a 'document chunk' and 'code chunk' correspondingly; Knuth called it 'section';
  • a 'manual' table or form is one that appears explicitly and literally in the input, and is maintained by a sophont, as contrary to an 'automatic' one;
  • 'narrative' is everything in an article (or a job) meant for a sophont to be read, that a machine is not likely to particularly care about;
  • a 'pace' is a single tangleable code chunk;
  • a 'recap' is a pace that can be 'untngled' back into the web by running an external script (but I did not list this feature above, for reasons that I suspect might be good ones);
  • a 'rubric' is a mechanism for tying together a bunch of topically associated leaves presented togeher; Knuth called it 'starred section';
  • a 'self-contained' article is one whose job contains only itself, without a dire need for any other articles or external data files; caper in code being generated during tangling;
  • a 'thematic break' is an anonymous, untitled, non-outlined formal break in the narrative, most commonly represented as a horizontal rule or asterism in woven output;
  • a 'title' is a TOC-outlined hierarchical node of an article, or the notation for introducing such a node; in some cases, these are called 'chapters', 'sections', and 'subsections' by outlining depth
  • 'transclusion' is the process of including a referenced caper in the output of tangling (or in some cases, outputof weaving);
  • a 'view' is a selected subset of nodes of a web or a job that can be handy to read or edit together, but that can not necessarily be tangled without having the rest of the web;

Might also possibly come up, but I consider it a bit problematic:

  • an 'enclave' is a somewhat segregated element in a narrative, which happens to be a common ancestor of both an 'aside' and a 'form' in some of my LP tools, but I'm not quite sure that these things actually go together.

Die Workshop-Vorbereitungen für die #FDMWerkstatt2026 von @fdm_nrw laufen auf Hochtouren und #Friedhelm ist mit dabei.

Mit Version 1.1.0 gibt es auch Handouts und eine verbesserte Anleitung des Workshops über #ResilientTechnologies . Alles automatisiert dank #TeXLaTeX und #LiterateProgramming

https://doi.org/10.5281/zenodo.19131602

#Emacs #FriedhelmOnTour #orgmode

@ericsfraga @mstempl I learned about all three of #Emacs, #TeXLaTeX, and #literateprogramming at the same time in the late 1980s.

The first two always went together, and the third was a dream, a thing only the gods upon Mount Knuth-lympus could do.

Then, much later! Oh happy day! #OrgMode came along, and all three were baked into a warm, delicious pound cake. The tool that decisively allowed me to become a confident Emacs user was to make my config a literate Org document. Inspired by @sacha's example! Having it be a document, structured as an outline, with paragraphs of prose, was just qualitatively different from a monolithic lisp file.

Collapsing outline elements (1) allow fractal movement between a gestalt and detailed view, and (2) impose structure. There is no way to overstate how necessary are both of these for managing even as small a project as my ... HOLY SHIT, I JUST LOOKED, and my config is more than 1,800 lines of code!

Okay, point proved

I finally got around to prototyping a promising-seeming #LiterateProgramming technique that I had been procrastinating on for months, and I proved that it has a fundamental internal inconsistency and can not be made to work. 

Maybe this one could have used some more procrastination.

We Should Revisit Literate Programming in the Agent Era

Literate programming is the idea that code should be intermingled with prose such that an uninformed reader could read a code base as a narrative, and come away with an understanding of how it works and what it does. Although I have long been intrigued by this idea, and have found uses for it in a couple1 of different cases2, I have found that in practice literate programming turns into a chore of maintaining two parallel narratives: the code itself, and the prose. This has obviously limited its adoption.

silly business

An interesting paper on a little-studied niche of #LiterateProgramming :

Design and evaluation of a literate spreadsheet

Support for capturing and sharing the problem-solving knowledge associated with end-user-developed software is often lacking. The principles behind literate programming have been proposed as an approach to addressing this. To study the potential efficacy of these principles in the general end-user programming case, they were applied to spreadsheets, the most common end-user programming environment, to produce a literate spreadsheet design. The resulting artifact was then evaluated through a user study with a focus on the literate design's effect on user comprehension and modification performance in each of the data, formula and dependency layers of the spreadsheet model. Significant performance improvements were observed in the formula and dependency layers over the traditional spreadsheet design, suggesting that the literate form can help improve end-user problem-solving knowledge reuse.

https://annas-archive.gl/md5/725830bf81cee76ae89bd9e33d3cd77d
https://ieeexplore.ieee.org/document/6344472

[IEEE 2012 IEEE Symposium on Visual Languages and Human-Centric Computing (VL/HCC) - Innsbruck, Austria (2012.09.30-2012.10.4)] 2012 IEEE Symposium on Visual Languages and Human-Centric Computing (VL/HCC) - Design and evaluation of a literate spreadsheet - Anna’s Archive

Dinmore, Matthew IEEE pages 15-18, 2012 sep

New article published! It's on alternative ways of making software more understandable to humans without LLMs, including literate, visual, and natural language programming.

"Programming sucks. Code sucks. It's hard to read, hard to test, and hard to maintain. Only a handful of people can understand any particular software project. These are major problems. I'm here to explain how we can fix them."

https://gracefulliberty.com/articles/towards-understandable-software/

"We should embrace visual, literate, and natural language programming in order to better communicate our intentions with machines and with each other. ... Every form of software at every level of the software stack should become accessible to programmers and non-programmers alike."

#programming #VisualProgramming #LiterateProgramming #NLP

Towards Understandable Software

Programming sucks. Code sucks. It's hard to read, hard to test, and hard to maintain. Only a handful of people can understand any particular software project. These are major problems. I'm here to explain how we can fix them.

On that note, I'm interested in learning more about the ways literate programming is used today. It's not as widespread as I believe it should be, but I'm sure there are developments I'm missing.

I'm currently aware of Knuth's work and, separately, Entangled as a modern iteration of literate programming tooling. https://entangled.github.io

Feel free to share any thoughts or resources!

#programming #LiterateProgramming

Entangled

Using literate programming for most of my code these days. I'm trying to develop my skills in communicating effectively with humans and computers alike.

At the same time, I get to test my ReTangled literate programming tool and fix missing features.

https://codeberg.org/liberty/retangled

It also motivates me to finally implement stitching—the last component to bidirectionality. I haven't finished that component due to its complexity and the fact that it's not as important if you focus on literate documents. But it's essential for widespread adoption and tooling integration.

#programming #LiterateProgramming #ReTangled

retangled

A (soon-to-be) bi-directional literate programming tool inspired by Entangled

Codeberg.org

On Saturday I will be publishing my article about making software development more accessible without LLMs!

Some snippets:

"Layers of abstraction are meant to be predictable and reliable. This is not the case with LLMs. Instead, LLMs stochastically interpret their prompts and predict intentions. If LLMs are a layer of abstraction, they're an incredibly lossy one at best."

"We should embrace visual, literate, and natural language programming in order to better communicate our intentions with machines and with each other. Every form of software at every level of the software stack should become accessible to programmers and non-programmers alike."

#programming #LiterateProgramming #LLM #VisualProgramming #NLP