tests/docs_preludes/akglbody.pre

/*
 * Prelude for the akgl-backend fragment in docs/10-embedding.md. Same shape as
 * hostbody.pre, plus the renderer and the two backend states those calls take.
 * Only compiled in the AKBASIC_WITH_AKGL build, which is the only one where
 * <akbasic/akgl.h> exists to include.
 */
#include <akerror.h>
#include <akbasic/runtime.h>
#include <akbasic/akgl.h>

static akbasic_Runtime RUNTIME;
static akbasic_GraphicsBackend graphics;
static akbasic_SpriteBackend sprites;
static akbasic_AkglGraphics gstate;
static akbasic_AkglSprites sstate;
static akgl_RenderBackend *my_renderer;

akerr_ErrorContext AKERR_NOIGNORE *akbasic_docs_fragment(void);
akerr_ErrorContext AKERR_NOIGNORE *akbasic_docs_fragment(void)
{
    PREPARE_ERROR(e);
Execute every documented example as a test docs/ and README.md carry 85 fenced blocks. Every one was checked by hand exactly once, when it was written, which is not a standard that survives a changing interpreter -- and four were already wrong: two transcripts showing a leading space PRINT does not emit, akbasic_TextSink in README.md missing the two members it had grown hours earlier, and FILTER's refusal quoted with wording the code does not use. tests/docs_examples.sh reads a fence-tag vocabulary and runs what it finds. BASIC programs and transcripts run and are byte-compared against an `output` block; C snippets compile with -fsyntax-only against the real include path, which CMake writes out because it is transitive through akerror, akstdlib and akgl; shell blocks run in a sandbox. Anything that would reconfigure the build tree, hit the network or re-enter the suite is tagged norun with the reason in MAINTENANCE.md, and the two cmake blocks stay hand-maintained by decision. An untagged block is a failure rather than a default, and the pass line reports what it executed by kind. Both exist because the way a harness like this dies is by quietly matching nothing and passing -- which it duly did on the first CTest run, where a generator expression evaluating to nothing still contributed an empty argument that the script read as a filename. The count is what caught it. The excerpt check earns its own mention: a block tagged `c excerpt=include/akbasic/sink.h` must still appear in that header, comments and whitespace ignored. Compiling it would only redefine the type, so a compile check could not have found the stale struct, and did not. Registered as the CTest case docs_examples in both configurations. Fixing the four wrong examples turned up two interpreter defects, fixed in the previous commit and recorded in TODO.md section 8. MAINTENANCE.md is new: the fence-tag reference, what to do when the case fails, and the conventions that until now only existed inside source comments -- the three test lists and how two of them invert "passed", the sorted verb table, that a golden file is never edited to suit this interpreter, and that a fix gets mutation-checked with a file copy rather than git checkout. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> 2026-07-31 22:41:36 -04:00			`/*`
			`* Prelude for the akgl-backend fragment in docs/10-embedding.md. Same shape as`
			`* hostbody.pre, plus the renderer and the two backend states those calls take.`
			`* Only compiled in the AKBASIC_WITH_AKGL build, which is the only one where`
			`* <akbasic/akgl.h> exists to include.`
			`*/`
			`#include <akerror.h>`
			`#include <akbasic/runtime.h>`
			`#include <akbasic/akgl.h>`

			`static akbasic_Runtime RUNTIME;`
			`static akbasic_GraphicsBackend graphics;`
			`static akbasic_SpriteBackend sprites;`
			`static akbasic_AkglGraphics gstate;`
			`static akbasic_AkglSprites sstate;`
			`static akgl_RenderBackend *my_renderer;`

			`akerr_ErrorContext AKERR_NOIGNORE *akbasic_docs_fragment(void);`
			`akerr_ErrorContext AKERR_NOIGNORE *akbasic_docs_fragment(void)`
			`{`
			`PREPARE_ERROR(e);`