Spec M26 — the documentation set

Goal: a developer learns mc from docs/ alone: how to use it in every supported case and what each element of the API means. Written by docs-writer agents against the real compiler (every sample is compiled by scripts/check-docs.sh).

Structure #

• docs/guide/ — task-oriented: 00-getting-started.md (download the binary, first program, --exe), 10-single-file.md, 20-project-toml.md (mc build, every TOML section by example), 30-teaching.md (Tier 1 #token/#infix/#prefix, Tier 2 #rule + prelude, Tier 3 hooks with a worked toy language), 40-backends.md (#section/#opcode/emit/reloc, pass()/backend(), the arm64-surface proof), 50-cross-compile.md (Linux/Windows targets, sysroots, linkers), 60-examples.md (walkthroughs of examples/api and examples/lang), 70-bootstrap.md (how the compiler builds itself; determinism rules for contributors).
• docs/reference/ — exhaustive: language.md (grammar, types, precedence, semantics, limits), directives.md, cli.md (every flag and dump), toml.md (every key, type, default), hooks.md (every public function of the parser/hook API: signature, when it is called, what it returns, errors, one example each), objects.md (sec_new/sym_new/reloc_add/... and the Ins accessors), machine.md (task contract, from M17/M24), diagnostics.md (every message the compiler emits, its cause and the fix — generated from scripts/i18n-map.tsv's English column plus a hand-written explanation), bundle.md (what <name> includes exist).
• docs/README.md — the map; the site (M27) renders this tree.

Checks (scripts/check-docs.sh, in make check) #

• Every p_*, syntax*, type_alias, pass, backend, machine*, sec_*, sym_*, reloc_add, gen_* and on_* accessor, CLI flag (--*), TOML key and directive found in src/ appears in docs/reference/; missing ones fail with the list. (on_* was added after the fact: the list above was written before M21.5 and on_stmt, a public hook, fitted none of the other families, so its whole reference entry could be deleted with the gate still green. Later still, four EXACT names joined the extraction — parse_unary, parse_top, do_directive, lex_include (docs/reference/hooks.md § 4) — because parse_ and lex_/do_ are deliberately not prefixes here: a parse_ prefix would also require documenting parse_call/parse_primary/ parse_stmt_core/… and a lex_include prefix would drag in lex_include_name/ lex_include_bundled, all of them internal on purpose.)
• Every fenced mc block in `docs/` compiles (with the taught compiler named in a fence attribute when needed, e.g. mc taught=examples/lang) and, when it declares // expect-stdout, runs.
• Links between docs resolve.

Acceptance #

make check green with check-docs; wc -l docs/guide docs/reference reported; a reviewer reads the guide end to end following it on a clean machine simulation (the standalone check environment).

Edit this page