Bring the documents forward thirty years

[gitosaurus]

The four documents that shipped with Archetype 1.01 never made the crossing to
the C++ implementation. This is all of them, in Markdown, checked line by line
against the interpreter that exists rather than the one they were written for.

docs/
  README.md          index, and a note on why there are two voices
  about.md           ABOUT.TXT
  playing.md         GAMES.TXT
  writing.md         HOW-TO.RTF
  manual.md          MANUAL.RTF
  known-issues.md    BUGS.TXT, current list + the 1995 list scored
  original/          all five originals, verbatim

What changed is the facts, not the voices

How to Quickly Write an Adventure Game still addresses a reader who has never
met a programming language, because that reader was the design target. The
manual still hands that same person a BNF grammar, because it was also a
journeyman piece. The two documents disagree about their audience on purpose,
and the revision keeps them that way.

Gone: CREATE.EXE and PERFORM.EXE, C:\> prompts, .ACH, advice about
saving from WordPerfect with Text Out, the 256-character string, the 24-line
screen, and the rule that a state file could only be read by the exact .acx
that wrote it. Where a limit was lifted the text says so, rather than
pretending it was never there.

Errors found by running every example instead of reading it

• Three examples assign with = where := was meant, in HOW-TO's vase and
  wallet and the manual's for loop. That compiles to a comparison, evaluated
  and discarded, so the vase never shatters and the license never falls out of
  the wallet.
• The wallet example also tests inequality with <>, which was never
  Archetype syntax, and is missing a closing brace.
• The necklace is placed in start_room, a room the tutorial never
  defines; it is first_room.
• The manual teaches the IsA<type-name> convention with
  any_object.IsAshouter — and shouter is the one type in its own example
  that never declares such an attribute.
• Prepositions arrive in main.prep, not verb.prep.
• Integers were never in the range −2^32 to 2^32−1; they are −2^31 to
  2^31−1 and wrap.
• The while example compares with ==, which does not exist.

What was added

New material files where it belongs rather than in an appendix of novelties:
lists and @, head, tail with the string operators; <- with the other
send operators; write_centered, display, keyword, and class with the
statements; >> moved from the operator chapter to the statements chapter,
where it now is one, with a note that consecutive lines gather into a
paragraph; 'BANNER' with the other system messages. Only messages with
arguments gets a chapter of its own, under Advanced Topics, since it changes
how objects are designed rather than adding a spelling.

The tutorial gains main.voice, which is the most visible knob in the modern
library and was entirely undocumented: one assignment turns the whole library
from "I'm in the bleak, bare cell" to "You're in the bleak, bare cell".

Four passages from Derek's book chapter on Archetype's origins are quoted where
they answer a question the documents cannot answer themselves — most usefully
in known-issues.md, where "semantically forgiving and computationally cheap"
reframes the thirty-year-old verb-in-noun-phrase bug as a constraint that was
priced before the parser was written.

BUGS.TXT

All eighteen entries are kept and scored: nine resolved, two largely resolved,
one moot, and seven that remain, each stated as what it is. The list is also a
measure of how the ground moved — it worries at length about memory and disk on
a 10 MHz machine, and never once about running anywhere but DOS.

Bugs found while checking the documents

Three, all filed rather than fixed here:

• display of a destroyed object dereferences null and crashes the interpreter #62 — display of a destroyed object dereferences null and crashes
• An unknown operator aborts the process instead of reporting a compile error #63 — an unknown operator aborts the process instead of reporting an error
• An escaped backslash in a string literal emits a spurious "Unknown escape character" #64 — an escaped backslash emits a spurious "Unknown escape character"

Testing

Every code example in every document was compiled and run against this
interpreter, including the full tutorial game end to end, the message --> object superglue pattern, the inheritance chain, the list-walking idiom, and
the second_person voice switch. Interpreter behaviour is unchanged by this
branch: 18/18 suites and both golden checks pass, and no file outside docs/
is touched.

🤖 Generated with Claude Code

https://claude.ai/code/session_01P458PFzYW18hjwnzjmTAJj