The pymdl book

This is a self-contained book about pymdl: how to run it, program in MDL, and use its development tools. It brings together the language and programming-environment material of the earlier MDL books, with explanations of pymdl's compilers, PDP-10 emulator, and archived programs. The earlier books are sources, not prerequisites; their authors and provenance are credited in appendix G.

Where to begin

• To try pymdl, read Running pymdl and Setting up.
• To learn MDL, continue with Part II. Its progression from expressions to functions and structured data introduces the language step by step.
• To work on a larger program, read Part III for packages, libraries, editing, and debugging.
• To compile programs or study old binaries, read Part IV. Chapter 34 distinguishes the native Python compiler from MIT's PDP-10 compiler.

Reading conventions

All instructions and explanations belong in this book. Cross-references should lead to the relevant chapter or appendix here. Some section numbers still reflect the source books: chapter 14, for example, contains section 11.7.2 on FLOAD. These are section identifiers within this book; you do not need another volume to follow them.

Historical descriptions of ITS, Tenex, and TOPS-20 provide context for the language and its files. Notes labelled pymdl's own explain implementation choices and differences. Measured notes identify observations, including the release or tool used; Found along the way notes record discoveries. Struck-through passages preserve the wording of a technical claim corrected in this edition. Ordinary prose edits do not change the underlying claim. Appendix E collects differences and discoveries; Appendix G records the sources and provenance.

Notation

MDL names and expressions appear in monospace. A name such as channel or radix:fix in a calling pattern is a placeholder: replace it with a value of the indicated kind. The colon separates the argument's name from its type. boolean means that only the argument's truth or falsity matters; it is not a separate MDL type. Each function's description states which arguments are required and which may be omitted.

An ellipsis (...) stands for omitted material or additional arguments. In terminal transcripts, $ represents the ESC key, and ^G means Ctrl+G. In executable examples, ⇒ separates an expression from its expected result. Type the expression, not the arrow or result.

For definitions and lookup, use the glossary, type table, error explanations, and topic and name indexes.

Examples and review status

The book has 38 drafted chapters and 10 appendices. Each fenced mdl block runs in one fresh interpreter under tests/test_book_examples.py. Forms within a block share state; results following ⇒ are checked against the returned values. The arrow is notation for the reader, not MDL syntax. Blocks marked mdl-x, including historical and interactive transcripts, are displayed but not executed by that test. Passing examples do not by themselves verify every statement in the surrounding prose.

PLAN.md records the drafting history; EDITING.md records the editorial review and remaining work.

Part I -- pymdl

#	chapter	file	status
1	What pymdl is	01-what-pymdl-is.md	drafted
2	Running pymdl	02-running-pymdl.md	drafted
3	Setting up	03-setting-up.md	drafted

Part II -- the language, as pymdl has it

#	chapter	file	status
4	Basic introduction	04-basic-introduction.md	drafted
5	Read, evaluate, print	05-read-evaluate-print.md	drafted
6	Built-in functions	06-built-in-functions.md	drafted
7	Values of atoms	07-values-of-atoms.md	drafted
8	Simple functions	08-simple-functions.md	drafted
9	Data types	09-data-types.md	drafted
10	Structured objects	10-structured-objects.md	drafted
11	Truth	11-truth.md	drafted
12	Functions	12-functions.md	drafted
13	Looping	13-looping.md	drafted
14	Input/output	14-input-output.md	drafted
15	Locatives	15-locatives.md	drafted
16	Association (properties)	16-association-properties.md	drafted
17	Data-type declarations	17-data-type-declarations.md	drafted
18	Lexical blocking	18-lexical-blocking.md	drafted
19	Errors, frames, etc.	19-errors-frames-etc.md	drafted
20	Macro-operations	20-macro-operations.md	drafted
21	Machine words and bits	21-machine-words-and-bits.md	drafted
22	Coroutines	22-coroutines.md	drafted
23	Interrupts	23-interrupts.md	drafted
24	Storage management	24-storage-management.md	drafted
25	MDL as a system process	25-mdl-as-a-system-process.md	drafted
26	Efficiency and tastefulness	26-efficiency-and-tastefulness.md	drafted

Part III -- the programming environment

#	chapter	file	status
27	Overview	27-overview.md	drafted
28	The package system	28-package-system.md	drafted
29	Program writing and debugging	29-program-writing-debugging.md	drafted
30	The library system	30-library-system.md	drafted
31	Making it run faster	31-making-it-run-faster.md	drafted
32	Informational aids	32-informational-aids.md	drafted

Part IV -- compiled code, the machine, and the era

#	chapter	file	status
33	Compiled programs and their files	33-compiled-programs.md	drafted
34	The compilers	34-the-compilers.md	drafted
35	The assembler	35-the-assembler.md	drafted
36	The PDP-10 inside	36-the-pdp10-inside.md	drafted
37	Asking the era	37-asking-the-era.md	drafted
38	Era artifacts	38-era-artifacts.md	drafted

Appendices

#	appendix	file	status
A	The SUBRs and FSUBRs	appendix-a-subrs.md	generated
B	The TYPEs	appendix-b-types.md	generated
C	The error names	appendix-c-errors.md	generated
D	Knobs and initial settings	appendix-d-knobs.md	drafted
E	Measured differences and discoveries	appendix-e-measured.md	drafted
F	Glossary	appendix-f-glossary.md	drafted
G	References and provenance	appendix-g-references.md	drafted
H	Object representation and storage	appendix-h-object-representation.md	reviewed for coverage
I	Topic and name indexes	appendix-i-indexes.md	links checked
J	Historical prefaces and publication record	appendix-j-historical-prefaces.md	incorporated

Working files: PLAN.md, EDITING.md, harvest.md.