Literate Programming

A program is usually arranged for the tools that build it. A book is arranged for the people who want to understand it. Literate programming connects those two orders: explanation leads, named fragments carry the implementation, and ordinary source files are generated from the same authoritative work.

This book explains that method through Literate itself. The program is at once a deterministic generator, a Visual Studio Code environment, a publication system, and a substantial example of its own approach.

Preface — Why this program is a book

The .literate chapters are the source of the program. Generated TypeScript, JavaScript, and HTML remain in the repository so a checkout can build and verify itself, but design work begins in the book. Prose, diagrams, formulas, examples, and code fragments should evolve together.

The main chapters concentrate on method, architecture, algorithms, and the reasons behind important boundaries. Code may be read closely, but the central argument should remain understandable when a reader skips a code block. The appendices keep mechanical assembly and detailed references available without making them the spine of the explanation.

flowchart TD
    Source[Literate project snapshot] --> Model[Fragment graph and parsed project]
    Model --> Generation[Source and HTML generation]
    Model --> Preview[Screen presentation]
    Model --> Publication[Print publication]
    Model --> Projection[Generated-language projections]
    Generation --> CLI[Command-line adapter]
    Generation --> Editor[VS Code adapter]
    Projection --> Servers[Language servers]
    Servers --> Editor
    Publication --> Book[LaTeX and PDF]

Literate was inspired by Donald Knuth's account of literate programming and by the way Physically Based Rendering: From Theory to Implementation presents a large program as a sustained explanation. The aim here is not merely to place all source inside a book, but to make the book the clearest route to understanding it.

Reading paths

The book is meant to support more than one journey:

These paths overlap because every subsystem starts from the same captured project and fragment model.

Part I — Literate programming as a method

  1. Programs for people and machines
  2. A small literate program
  3. Choosing fragments well
  4. From explanation to source

Part II — The semantic model

  1. The project snapshot
  2. The fragment graph
  3. Parsing without side effects
  4. Planning a complete generation

Part III — Hosts, effects, and self-hosting

  1. One generator, several hosts
  2. The command-line adapter
  3. Changing files safely
  4. A generator that generates itself

Part IV — The editor as a literate-programming environment

  1. The editor-side project repository
  2. Fragments as editor symbols
  3. Previewing the explanation
  4. Exploring the fragment graph
  5. Extension activation and public surface

Part V — Language intelligence for generated code

  1. The projection problem
  2. Owning a language-server session
  3. Read-only language services
  4. Diagnostics over changing projections
  5. Mutating projected source safely
  6. Coordinating language features in the editor

Part VI — Publication from the same source

  1. Why publication is a separate pipeline
  2. Building a publication document
  3. Shared annotations and identities
  4. Publication on screen
  5. Typesetting the book
  6. Portable publication resources
  7. Compiling and publishing a PDF
  8. Isolating publication from the editor

Part VII — Correctness, limits, and maintenance

  1. Determinism as a design principle
  2. Resource bounds and fail-closed behavior
  3. Developing the book and program together
  4. What Literate does not promise

Part VIII — Reflection

  1. Lessons from implementing Literate literately

Chapter 36 closes the main narrative. The sections below are reference routes into implementation chapters and assembly maps; they are not additional chapters in the main reading sequence.

Implementation reference

Appendices