# Turbo Modula-2 — Compiler outline

Target: give meaning back to `procN` / `globalN` in the
`Reversing-Turbo-Modula2-main/decompiled/COMPILER/` sources,
which compile but are unreadable.

Status: outline only, no semantic change to upstream sources.
Upstream folders are git-ignored (see `../.gitignore`);
only `docs/compiler/` is versioned.

## Layout

```text
docs/compiler/
  00-overview.md        this file, map + reading order
  10-folders.md         what each upstream folder contains
  20-compiler-module.md Compiler.MOD/DEF: Record descriptor + Init procs
  30-scanner-module.md  Scanner: buffer, GetSym, Accept/Expect/Test
  40-symtab-errors.md   SymTab scopes + Errors reporting/recovery
  50-codegen.md         CodeGen MCode emitter + 2KB window + fixups
  60-frontend.md        COMPILE link: Pass1 + Statement + Express (no .MOD yet)
  70-rename-plan.md     ordered rename work plan procN/globalN -> real names
  TAGGED-SUMMARY.md     one-page tagged snapshot for `git tag`
```

## Compiler shape (recall)

Resident, overlaid in M2.COM:

* `Compiler` + `Scanner` + `SymTab` + `Errors` + `CodeGen`

Dynamically loaded via `Loader.Call`:

* `COMPILE` = link of `Pass1` + `Statemen` + `Express`
* `GENZ80` = native-code backend (if requested)

Drivers:

* `C.MOD` (`MODULE M2C`): `ReadString -> inName -> Scanner.Compile`
* `Scanner.Compile` (`proc30`): `MARK, Compiler.proc2, Call("COMPILE")`,
  then `Call("GENZ80")` if `Compiler.global25`
* `ComLine`: `commandLine, inName, outName, codepos, execute`

## Reading order (suggested)

1. `20-compiler-module.md` — the `Record` descriptor unlocks everything.
2. `30-scanner-module.md` — token codes, `GetSym/Accept/Expect`.
3. `50-codegen.md` — opcode table + `Emit/Peek/Poke/Fixup`.
4. `40-symtab-errors.md` — scopes, `.SYM` import/export, error recovery.
5. `60-frontend.md` — parsers that consume 1-4.
6. `70-rename-plan.md` — execute renames in that dependency order.

Note on sources: `decompiled/COMPILER/*.{DEF,MOD}` are CP/M text
(`CRLF + 0x1A`). Plain readers fail; use:

```sh
tr -d '\032\r' < Reversing-Turbo-Modula2-main/decompiled/COMPILER/SCANNER.MOD | less
```

`Turbo-Modula-2-Reloaded-main/disk_content/COMPILER.DIR/SCANNER.MOD`
is a stub (30x `PROCnn; BEGIN END`); the real logic is in the
`Reversing-.../MCode_disassembly/*.txt` disassemblies.