Stop the listings and their chapters stating fixed defects as fact
Some checks failed
akbasic CI Build / cmake_build (push) Failing after 3m21s
akbasic CI Build / sanitizers (push) Failing after 4m30s
akbasic CI Build / coverage (push) Failing after 3m40s
akbasic CI Build / akgl_build (push) Failing after 21s
akbasic CI Build / mutation_test (push) Failing after 3m27s

You were right that this was still everywhere. The two `.bas` files carried
their workarounds as present-tense statements about the interpreter -- "a name
first created inside a GOSUB costs a value slot that is never handed back",
"writing PAST the terminator of a short row draws nothing at all", "SSHAPE and
GSHAPE ignore the subscript on a string array", "a FOR inside a BEGIN block does
not survive the RETURN" -- and every one of those is now false. A comment that
lies is worse than no comment, and these were the first thing anybody opening
the files would read.

**The characters game takes the geometry fix.** `CW# = 16` becomes `CW# =
RGR(3)`, and the grid comes from `RWINDOW`, so the game fits whatever window and
font the host gives it. That was the one thing in the listing that would break on
a different font, and `RGR(3)` and `RWINDOW` were added to the interpreter
because of it -- leaving the constant in place while Chapter 17 teaches the
function was the inconsistency worth closing. `RGR(1)` still comes first so a
build with no graphics device refuses by naming the device that is missing.

Everything else in both listings keeps its shape and says why. Declaring every
name up front, guarding loops with `GOTO`, six scalars for six brick stamps: none
is forced any more and none costs anything, so they stay, with the comments
marking which rules stand and which are history. The sprites header's five traps
are marked FIXED where they are fixed.

The chapters follow: Chapter 17 Step 2 no longer says "the listing still has
`CW# = 16`", and Chapter 18's trap section is "five things that did not do what
they looked like" with the two that still stand named up front rather than left
to be counted.

Verified: Chapter 17 Step 2's block is once again verbatim from the listing, so
every quoted fragment in both chapters matches its source with no exceptions;
both games run 40 seconds on the SDL frontend with no error line; both suites
green in both configurations; `docs_examples` and `docs_screenshots --check`
pass.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-08-02 06:32:48 -04:00
parent 89fca8007b
commit 0679c3042b
6 changed files with 120 additions and 78 deletions

View File

@@ -2,8 +2,11 @@
Breakout, written entirely in BASIC for the AKGL BASIC interpreter, using downloaded CC0
sprite artwork for the paddles, the balls and the powerup gems. The bricks, the HUD and
the lettering are drawn, captured with `SSHAPE` and installed as sprites — which is the
only way a program in this interpreter can put a picture on the screen.
the lettering are drawn, captured with `SSHAPE` and installed as sprites — because a
sprite is the one thing this interpreter puts on the screen for nothing. The text layer
owns every row of the window unless a program takes some back with `WINDOW`, and even
then a drawing has to be re-issued every frame; a sprite is drawn from state the
interpreter keeps.
```sh
../../../build-akgl/basic breakout.bas
@@ -89,6 +92,8 @@ drawing. The two that stand are the left-operand arithmetic rule, which turned o
decision rather than a defect and is now documented as one, and the 256-line batch tear,
which belongs to the host.
**The listing is unchanged**, and deliberately: it is what a program written against those
constraints looks like, and its comments explain what it was working around. Six separate
scalars for six brick stamps is no longer necessary, and it is still what the file does.
**The listing's code is unchanged**, and deliberately: it is what a program written
against those constraints looks like, and none of the workarounds costs anything now that
they are not needed. Six separate scalars for six brick stamps, and loops guarded by
`GOTO` rather than wrapped in a block, are both still what the file does. Its comments say
which of the five traps stand and which are marked FIXED.