Generate the documentation's figures from the listings they illustrate
Chapters 6 and 8 described what a verb draws in prose. Eight figures now show it, and each one is produced by running the BASIC listing printed immediately above it -- so a picture cannot drift away from the code beside it, which is the way a screenshot goes wrong and the way nothing notices. tools/screenshot.c is a second SDL host, much smaller than the frontend: dummy video driver, software renderer, run to completion, read the target back, write a PNG. It draws no text layer on purpose, so a READY in the corner is not noise in a figure about BOX and no font has to be resolved. tools/docs_screenshots.sh reads the new screenshot=NAME fence tag straight out of the markdown. size=WxH is the second tag, and SCALE's figure uses it: the point being made is a 320x200 listing filling a larger window, which cannot be made on a 320x200 surface. Two gates, answering different questions. docs_examples fails a tagged block with no image, in both configurations, so a figure cannot be added and forgotten. docs_screenshots -- a CTest, AKGL build only -- re-renders every figure and compares byte for byte, so a listing edited without regenerating fails. Only the second catches a stale picture. The PNGs are checked in because a reader on the forge has no build tree, and docs/images/README.md says loudly that they are generated. Regenerating is never part of a build: the target is run deliberately, so a make cannot put eight binary diffs in front of whoever ran it. Drawing the BOX figure caught a defect in TODO.md itself. Deviation 16 claimed in bold that BOX fills on a negative angle while its own paragraph said the fill was filed rather than implemented. BOX cannot fill, and filled_rect is reached by no verb as a result. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
21
docs/images/README.md
Normal file
@@ -0,0 +1,21 @@
|
||||
# Generated figures — do not edit
|
||||
|
||||
**Every PNG in this directory is output, not an asset.** Each one is produced by running
|
||||
the BASIC listing shown immediately above it in the chapter, through
|
||||
`tools/screenshot.c`, and it is checked in only because a reader on the forge has no
|
||||
build tree to generate it from.
|
||||
|
||||
To change a picture, **change the listing** and regenerate:
|
||||
|
||||
```sh
|
||||
cmake --build build-akgl --target docs_screenshots
|
||||
```
|
||||
|
||||
Editing a PNG here by hand puts the picture out of step with the code it illustrates,
|
||||
which is the exact failure this arrangement exists to prevent — and the `docs_screenshots`
|
||||
test will fail on it, because it re-renders every figure and compares byte for byte.
|
||||
|
||||
The tag that ties a figure to its listing is `screenshot=NAME` in the fence info string,
|
||||
and `MAINTENANCE.md` documents it along with `size=WxH` for a figure that needs a surface
|
||||
other than 320 by 200. A tagged block with no image here fails `docs_examples` in both
|
||||
build configurations, so a figure cannot be added to a chapter and then forgotten.
|
||||
BIN
docs/images/box.png
Normal file
|
After Width: | Height: | Size: 1.5 KiB |
BIN
docs/images/circle.png
Normal file
|
After Width: | Height: | Size: 1.8 KiB |
BIN
docs/images/draw.png
Normal file
|
After Width: | Height: | Size: 1.4 KiB |
BIN
docs/images/paint.png
Normal file
|
After Width: | Height: | Size: 1.2 KiB |
BIN
docs/images/scale.png
Normal file
|
After Width: | Height: | Size: 3.1 KiB |
BIN
docs/images/shapes.png
Normal file
|
After Width: | Height: | Size: 1.7 KiB |
BIN
docs/images/sprite-collision.png
Normal file
|
After Width: | Height: | Size: 739 B |
BIN
docs/images/sprites.png
Normal file
|
After Width: | Height: | Size: 904 B |