Bring the tutorials back in line with the fixed interpreter

Eleven of the thirteen defects these two games found are fixed, and the
chapters that taught around them said things that are no longer true.

Chapter 17: the drawing verbs are no longer invisible, they are covered by a
text layer that `WINDOW` can now shrink; the cell size is `RGR(3)` and the grid
is `RWINDOW`, not a hand-measured constant; a character written past a short
row's end lands. Chapter 18: traps 3 and 4 -- the skipped block that broke its
caller's `RETURN`, and `SSHAPE` ignoring a subscript -- become history rather
than warnings, and Step 3 no longer claims a sprite is the *only* way to put a
picture up, only the one that costs nothing.

**Neither `.bas` listing changes, and both READMEs now say why.** The character
game still writes `CW# = 16` and the artwork game still keeps six brick stamps
in six scalars. What those listings are worth is being what a program written
against those constraints looks like, with comments explaining what each one was
avoiding -- rewriting them to pretend the problems never existed would throw
that away. So Chapter 17 Step 2 shows the `RGR(3)`/`RWINDOW` form and says
plainly that the listing beside it does not use it. That is the one place in
either chapter where a quoted fragment is not verbatim from the game.

Also: the closing pointers now say which entries are struck and which stand, and
the budgets table in Chapter 18 notes that several of those budgets were tighter
when the game was written.

TODO.md section 9 item 3 is updated rather than struck: the `WINDOW` half is
fixed, the default text area owning the whole window is not, and whether that
default is right is a question rather than a defect.

Verified against the fixed interpreter: both games run 45 seconds on the SDL
frontend with no error line and the score climbing; both suites are green in
both configurations; `docs_examples` passes and `docs_screenshots --check`
re-renders all thirteen figures byte-identically; coverage is 95.0% of lines
against the 90 gate, with src/variable.c at 100%; and every other quoted
fragment still appears verbatim in the listing it came from.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-08-02 00:31:06 -04:00
parent c3d9e91bbd
commit 91fadf032b
5 changed files with 75 additions and 30 deletions

View File

@@ -38,10 +38,11 @@ without your program doing anything:
- the **sprites**, walked slot by slot after it.
The drawing verbs are not one of them. `DRAW`, `BOX`, `CIRCLE` and `PAINT` go straight
into the renderer's back buffer, and the text layer paints over the whole window on its
way past — so in the standalone SDL build **nothing you draw with them is ever visible**.
That is recorded as a defect (`TODO.md` §9 item 3) rather than a design, but it is the
interpreter you have.
into the renderer's back buffer, and **the text layer owns every row of the window by
default** — so it paints over anything they drew on its way past. `WINDOW` shrinks the
text area and gives the rest of the window to the drawing verbs, but a drawing still has
to be re-issued every frame and has to fit in one batch to survive the capture; see
[Chapter 13](13-differences.md#graphics).
So this game uses no drawing verb at all. Anything that has to move smoothly is a sprite;
anything that can live on a 16-pixel grid is text. Ball and paddle move; bricks, score
@@ -751,5 +752,6 @@ game against:
differently from BASIC 7.0.
- **[Chapter 14](14-architecture.md)** is the interpreter itself — the step loop, the
pools and how to debug a program that stops for no visible reason.
- `TODO.md` §6 and §9 carry the defects this game found, each with a reduction that fits
on a screen and what a fix would touch.
- `TODO.md` §6 and §9 carry the thirteen defects these two games found, with the
reduction for each. Eleven have since been fixed and are struck; the entries are kept
because the reduction and the cause are worth more than the tidiness of deleting them.