repltut | Tim Menzies

http://tiny.cc/repltut

How to convert source code into a textbook. Prompts and exemplars for generating "genetic stanza" REPL tutorials: source files that read top-to-bottom as a short paper and load top-to-bottom as code, narrated by numbered REPL traces ([1]> ... [48]>). Includes the authoring prompt, a worked example (Lisp data mining), and the K&R tone exemplar.

# install and read
git clone http://tiny.cc/repltut repltut && cd repltut
less author.md

tutgen.md = meta-prompt: code in, multi-lecture REPL course out (harness, audits, weave rules); author.md = the authoring prompt (genetic stanza spec, AUTHOR-CONFIG knobs); fri2.md = worked example, data-lite active learning in SBCL, 48 REPL steps; kr_ch1.md = K&R ch.1 tone calibration; ezr.tex = paper-dialog exemplar (coverage + topic order); repl.lua = reference replay harness for verbatim numbered traces.

NAME

repltut - authoring kit for REPL-driven literate tutorials.
Paste author.md into an LLM (system prompt, CLAUDE.md, or
lead of a turn); it writes a tutorial like fri2.md.

SYNOPSIS

1. Read author.md; fill in its AUTHOR-CONFIG stanza
   (audience, language, depth, tone, repl-density...).
2. Give the prompt + config + your source code to an LLM.
3. Out comes a stanza-form tutorial: 65-col prose blocks
   paired with 4-space code blocks, punctuated by numbered
   REPL traces.

OPTIONS

AUTHOR-CONFIG knobs (see author.md for full list + defaults):

  audience          one sentence pinning reader background
  assumed           concepts NOT explained
  language          target language + runtime
  depth             terse | standard | verbose
  tone              academic | textbook | conversational | kr
  prose-width       columns of prose            (65)
  stanza-length-cap max code lines per stanza   (10)
  repl-density      stanzas between REPL traces (3)
  repl-prompt       trace prompt string         ([1]>)

EXEMPLARS

K&R chapter 1        tone and pacing (kr_ch1.md)
Lions' Commentary    code-as-paper coverage (cited)
fri2.md              the stanza + numbered-REPL form
ezr.tex              coverage, topic order, paper dialog

OUTPUT

A single markdown/source file. Each stanza: claim -> code ->
consequence. Every few stanzas, a runnable REPL trace:

  [12]> (adds (mapcar #'second rows) (make-num))
  #S(NUM :n 398 :mu 23.5 :sd 7.8)

LICENSE

MIT. https://choosealicense.com/licenses/mit/

AUTHOR

Tim Menzies <timm@ieee.org>