#literateprogramming — Public Fediverse posts

I am close to finishing stitching in ReTangled. Once this is done I will have a bidirectional literate programming tool.

After that is making error handling nice and user friendly.

#LiterateProgramming #ReTangled

Writing documentation is just an important as writing code.

Most of the context for a program lives in the minds of those who maintain it. If that isn't written down, the program is incomplete.

#LiterateProgramming

@Floppy Briefly describe your plan, and I'd probably want to join.

I have been writing Ruby code for some twenty years; very rarely touched any Rails. Ended up making a couple of things that do some things that Rails does, albeit differently; the one that had most staying power was a basic application server framework I dubbed Pyramid; its most distinct characteristic was focusing on #LiterateProgramming kind of application development. It used to be proprietary; things have changed since, and now I have full rights to it, although haven't done a public release yet. Insomuch as it would make sense, I'd be happy to share and/or adapt some Pyramid code.

(Tempted to suggest naming the new project Ziggurat, after the Asimov quip about cavemen's railroads and ziggurats being built without computers. It kind of ... fits?)

En 2012, j’ai testé de faire du literate programming en Ruby.

Vous savez, ce truc où le programme est essentiellement de la documentation, avec éventuellement les lignes de code intercalées par endroit.

Hébin le résultat tient bien la route, je trouve ! C’est à la fois le code source, et quasiment un article de blog.

Si vous voulez juger ma prose et mon Ruby d’il y a mille ans :

https://kemenaran.github.io/murApplis/

#ruby #literateprogramming

Tirritate #LiterateProgramming fans by arguing that the Clarion database's template system is the most commercially successful literate programming system (for fairly abecedarian values of 'literate', naturally) invented to date.

You’ve got my word, if drag races don’t bring up website design from scratch surprise contests, I was dead before I could make it happen.

#Queer #Gameing #LiterateProgramming #FreeSoftware #QueerTechnology #QueerTech

Because of historic compatibility reasons, I sort of ended up rewriting a subset of #Microblaze-compatible core for synthesising on tight corners inside Lattice's ICE40/ECP5 #FPGA:s.

It's in #Verilog with some #LiterateProgramming preprocessing. Userspace (and I/O+interrupt support) only. Explicit support for combining code and data bus, optionally for 8-bit memory access (as in HyperRAM), or for synthesising instruction memory as block RAM, optionally with a secondary debug interface. Explicit support for resetting the core without resetting the whole FPGA. AXI-like, Wishbone-compliant, and serial I/O support, and I/O-mappable interrupt support. The register file can be pared down. Arithmetics can be divided up into chunks of a parametrically specified size, all the way down to bit-serial if need be, and slow-but-smol microcoded multiplication and division are optionally available. Some optional extensions for fixed-point transcendental calculations were originally planned, but right now, only binary logarithms and CORDIC are ready.

The original commercial interest in it is likely to go away in the near future. Would there be interest in a GPL release of this sort of thing?

This is not at all the sort of context that MicroBlaze was originally designed for, even in the Xilinx world, and I'm not sure that the specific backwards compatibility reasons exist outside this particular niche (=> I would probably not be doing maintenance work on the core after release without a good $€parate r€a$on), but if you have a use case that might match something like these criteria, please let me know.

(Obligatory LBNL: only deterministic automation was used in writing this code. GenAI has not touched any part of it.)

I have uploaded a new paper to the arXiv, “Counting number-conserving cellular automata with radius 1“ (https://arxiv.org/abs/2605.31157).

The text is both a semi-brute-force calculation of the number of one-dimensional cellular automata with radius 1 and up to seven states, and an exercise in literate programming.

I call this a “semi-brute-force” calculation because, while it relies on my theory of one-dimensional number-conserving automata to speed up the calculation, there still remains an enormous number of individual cases that need to be computed and added up. It is by no means fast. The algorithm is also very specialised and works only for radius 1.

And literate programming means that the source code is a mixture of LaTeX and Haskell code, so that it (a) can be directly compiled by the Haskell compiler and (b) in the generated PDF, I can see each source code fragment together with the mathematical explanation what it does and why it does it. I did this in order to be (almost) absolutely sure that the program does what it was intended to do. The literate programming method works, but it is still quite an effort.

I do not think there is a journal that publishes such a text, but at least it is now in the arXiv.

#CellularAutomata #NumberConservation #LiterateProgramming #EnumerativeCombinatorics #Mathematics

Knitr support in Overleaf
#literateprogramming

https://docs.overleaf.com/integrations-and-add-ons/r-code-knitr

I recently got back to my work on literate #GRASP, and I think things finally started to look good. I implemented a new document representation (the previous one was built from cons-cells and multiple hacks), and I have some working tests that are capable of rendering this representation to "unicode-art" strings, and I'm currently working on a new parser that would work well with that representation.

I still have a long way to go before I get a running system, and I don't think it's a very good literature, but if you're a #Scheme maniac or a fan of #LiterateProgramming and you don't find the #Java runtime environment too repulsive, I invite you to follow the work and provide your feedback:

https://github.com/panicz/grasp/blob/main/literate/grasp.org

Currently, when exported to pdf, the document has about 100 pages, and it mainly describes language extensions that were developed for Kawa Scheme to develop GRASP. I think it might be a delight to people who enjoy studying language extensions, but unfortunately the part about the architecture and implementation of GRASP has yet to be developed.

(the document is written in #Emacs #OrgMode using its #noweb component for literate programming. I recommend reading it from Emacs rather than from its github preview)

Because I already have to parse the literate document in the tangler (which is already operational), I decided to reuse the parser. But that means refactoring the parser to make it more agnostic towards what it's parsing as well as support

I decided to write ReTangled as a literate-first project. The reason I spedrun the tangler is so that it could self-host as quickly as possible. I also use tangling far more often than stitching since I prefer to work in the literate document. But that cuts me off from tooling like rustfmt.

So now I'm having to refactor everything together. Which is a good learning experience! I haven't spent much time refactoring a literate program before. Time will tell if this approach helped or hindered the development of the tool.

#ReTangled #LiterateProgramming

Been working towards getting stitching working in #ReTangled. It's complicated because codeblocks can be embedded in other codeblocks so the stitcher has to keep track of a lot of information about the source document to make sense of where everything goes.

#LiterateProgramming

@poleguy So, the way I approach 3D design is, I define the models as OpenSCAD source (with some Ruby-powered preprocessing) in a #LiterateProgramming framework, and the rest of the workflow, including slicing, is pretty much automatic.

I'd kind of like an abstraction that would allow me to describe the shape of the whole, and then something on the order of "place a snappable gravity direction change plane here". If I get there, it'll probably be some more Ruby preprocessing code.

I mostly dabble in drones and other flying things these days, and I'm not too big on WYSIWYG-only kinds of CAD applications. But, of course, for people who do sculptures, WYSIWYG and STL-centric workflows can make more sense.

@pathunstrom As in, #LiterateProgramming ?

Hey, look what unexpected context I found #LiterateProgramming to be used in!

https://www.cs.tufts.edu/~nr/toolkit/specs/sparc.html

Nice adding to org-transclusion #emacs #literateprogramming #reproducibility with https://github.com/steve-downey/surround that add uid around block code. Poke @khinsen

1990's literate programming: this is the future! everyone will be writing software like this!

AGENTS.md

LP: oh no!

#programmingLanguages #literateProgramming #cweb #llm

@oblomov

apologies, real life kept reminding me that it exists :blobcatglare:

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. :blobcatflop:

Maybe this one could have used some more procrastination.

We should revisit literate programming in the agent era

https://silly.business/blog/we-should-revisit-literate-programming-in-the-agent-era/

#HackerNews #literateprogramming #agentera #programminginnovation #techthoughts #revisitthepast

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

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

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

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

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