Litrepl: Literate Paper Processor Promoting Transparency More Than Reproducibility
Sergei Mironov · 2025
Read Litrepl: Literate Paper Processor Promoting Transparency More Than Reproducibility by Sergei Mironov (2025) in the Tower of Babel, a free online library of public-domain works preserved in clean, searchable text. No sign-up. The full text is served as a plain-text file at a predictable URL, where text is present: https://antarctic-labs.com/tower-of-babel/arxiv-2501-10738.txt.
Introduction
Sergei Mironov introduces a text processing tool in a paper from two thousand twenty-five. The tool, called Litrepl, finds code sections inside Markdown or LaTeX documents and runs them. It can work on whole documents at once or inside a text editor as the author writes.
The tool takes cues from Jupyter notebooks and aims to make research documents easier to build. Mironov argues that full reproducibility is less vital than clear openness about how the computer was used. The tool therefore removes hidden state in the link between text and code, or exposes it plainly. Readers can see exactly what was run and what it returned.
Catalog record
| CREATOR | Sergei Mironov |
|---|---|
| YEAR | 2025 |
| COLLECTION | PAPERS |
| FORMAT | TXT |
| FILE SIZE | 13 KB |
| VERSION | 1.0 |
| LICENSE | http://creativecommons.org/licenses/by/4.0/ |
| RIGHTS | CC BY |
| SOURCE | arXiv |
Source: https://arxiv.org/abs/2501-10738
Browse the full library · About the Tower of Babel
Full text
The opening of the work, from the library's hosted text:
Litrepl: Literate Paper Processor Promoting Transparency More Than Reproducibility Sergei Mironov Abstract Litrepl is a lightweight text processing tool designed to recognize and evaluate code sections within Markdown or L a T e X documents. This functionality is useful for both batch document section evaluation and interactive coding within a text editor, provided a straightforward integration is established. Inspired by Project Jupyter, Litrepl aims to facilitate the creation of research documents. In the light of recent developments in software deployment, however, we have shifted our focus from informal reproducibility to enhancing transparency in communication with programming language interpreters, by either eliminating or clearly exposing mutable states within the communication process. 1 Statement of Need Figure 1: Litrepl resource allocation diagram. Hash A is computed based on the Litrepl working directory and the interpreter class. Hash B is computed based on the contents of the code section. The concept of Literate Programming was formulated by Donald Knuth, suggesting a shift in focus from writing code to explaining to human beings what we want a computer to do. This approach is embodied in the WEB system [ 6 ] and its descendant family of tools, whose name refers to a text document format containing the ”network” of code sections interleaved with text. The system could both render such text into human-readable documentation and compile machine-executable code. Over time, this concept has evolved, showing a trend towards simplification ( [ 10 ] ). Concurrently, a concept of human-computer interaction often called the Read-Evaluate-Print Loop or ”REPL” gained traction, notably within the LISP an APL communities ( [ 12 ] , [ 7 ] , [ 4 ] ). The combination of a command-line interface and a language interpreter enables incremental and interactive programming, allowing users to directly modify the interpreter state. By maintaining human involvement in the loop, this approach is believed to facilitate human thought processes ( [ 2 ] ). A significant milestone in this field was the IPython interpreter ( [ 8 ] ), which later evolved into the Jupyter Project. Its creators introduced a new document format called the Jupyter Notebook ( [ 5 ] ), characterized by a series of logical sections of various types, including text and code, which could directly interact with programming language interpreters. This interactive communication, akin to REPL style programming, allows the creation of well-structured documents suitable for presentations and sharing. The concept underpinning these developments is termed Literate Computing [ 9 ] , which includes goals of spanning a wide audience range, boosting reproducibility, and fostering collaboration. To achieve these objectives, several technical decisions were made, notably the introduction of bidirectional communication between the computational core, known as the Jupyter Kernel, and the Notebook web-based renderer, along with another layer of client-server communication between the web-server and the user’s web browser. While we recognize the importance of all goals within the Literate Computing framework, we think that the goal of reproducibility is more important than others. Addressing it alone would suffice to enhance communication among time-separated and space-separated researchers and significantly expand the audience. However, as it became clear ( [ 1 ] ), this challenge extends beyond the scope of a single human-computer interaction system, and even beyond the typical boundaries of software distribution management for a particular programming language. A comprehensive solution to the software deployment problem operates at the entire operating system level. Following [ 13 ] , we suggest changing the focus of human-computer interaction towards simplicity and transparency. We saw an opportunity to implement a tool that would offer REPL-style editing, be compatible with existing code editors and text formats, thus maintaining familiar editing practices, contain only a few hidden state variables, and have a significantly smaller codebase. We introduce Litrepl 1 1 1 https://github.com/sergei-mironov/litrepl , a text processor that employs the following approaches: first, utilizing straightforward bidirectional text streams for inter-process communication with language interpreters to evaluate code; second, advocating for the reuse of existing text document formats. In both the Markdown and L a T e X evaluators we have implemented, simplified parsers are used to distinguish code and result sections from the rest of the document. As of now, we support Python and Shell interpreter families, as well as a custom large language model communication interpreter. Finally, we strive to leverage POSIX [ 3 ] operating system facilities as much as possible. 2 How it works Litrepl is implemented as a command-line text utility. Its primary function is to take a text document as input, process it according to specified command-line arguments and environment settings, and then output the resulting document through its standard output. The operation of Litrepl is best illustrated through the example below. Consider the document named input.tex : $ cat input.tex \begin{python} import sys print(f"I use {sys.platform} btw!") \end{python} \begin{result} \end{result} This document contains a Python code section and an empty result section marked with the corresponding L a T e X environment tags. To ”execute” the document we pipe it though the Litrepl processor as follows: $ cat input.tex | litrepl \begin{python} import sys print(f"I use {sys.platform} btw!") \end{python} \begin{result} I use linux btw! \end{result} Now we can see the expected statement about the author’s operating system. The side-effect of this execution is the started session of the python interpreter which is now running in the background. We can modify its state by adding more section to the document and executing them selectively or e.g. by accessing litrepl repl python terminal. So for example, setting sys.platform to another value and re-evaluating the document would yield a different statement. 2.1 Interfacing Interpreters Litrepl communicates with interpreters using two uni-directional text streams: one for writing input and another for reading outputs. To establish effective communication, the interpreter should conform to the following general assumptions: • Synchronous single-user mode, which is implemented in most interpreters. • A capability to disable command line prompts. Litrepl relies on the echo response, as described below, rather than on prompt detection. • The presence of an echo command or equivalent. The interpreter must be able to echo an argument string provided by the user in response to the echo command. In Litrepl, these details are hardcoded for several prominent interpreter families, which we refer to as interpreter classes . At the time of writing, Litrepl supports three such classes: python , sh , and ai . Using these names in command line arguments, users can configure how to map code section labels to the correct class and specify which interpreter command to execute to start a session for each class. For example, to select a Bourne-Again Shell interpreter as sh , we add the --sh-interpreter=/usr/bin/bash argument assuming that this binary is present in the system. 2.2 Session Management \begin{result} ... some output ... [LR:/tmp/litrepl/python/partial_c335adc.txt] \end{result} Figure 2: Example partial result section that ends with a continuation tag, where LR: is a distinguishable prefix, and the rest is the filename storing a response of the interpreter to the section being evaluated. Litrepl’s ability to maintain interpreter sessions in the background is crucial for enabling a Read-Eval-Print Loop (REPL) environment. The associated resources, shown in Figure 1 , are stored as files within an auxiliary directory. If not