Write the usage guide as thirteen chapters in docs/

Organised the way the C128 Programmer's Reference Guide is: the language
first, then each hardware area, then the reference sections. One markdown
file per chapter.

The verb and function references are generated from the interpreter's own
dispatch table, with an assertion that every row is described, so they cannot
drift out of step with what the program accepts. 98 verbs and 30 functions.

Every example was run before it was written down, which caught three claims
that were wrong: a whole FOR loop on one line prints nothing rather than
looping once, MID and INSTR count from zero where a C128 counts from one, and
a multi-line DEF returns a value the caller has to assign away.

Chapter 13 is the list a BASIC 7.0 programmer needs -- roughly sixty
documented differences, including the two known FOR defects and the fact that
drawing does not survive a frame.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

docs/05-strings-and-formatting.md

@@ -0,0 +1,128 @@
+# 5. Strings and formatting
+
+## The string functions
+
+| Function | What it gives you |
+|---|---|
+| `LEN(A$)` | how many characters, or how many elements in an array |
+| `LEFT(A$, N#)` | the leftmost `N#` characters |
+| `RIGHT(A$, N#)` | the rightmost `N#` characters |
+| `MID(A$, START#, LENGTH#)` | a substring, counting from **zero** |
+| `INSTR(A$, B$)` | where `B$` appears in `A$` counting from **zero**, or -1 |
+| `CHR(N#)` | the character for a Unicode code point |
+| `STR(N#)` | a number as a string |
+| `VAL(A$)` | a string as a number |
+| `HEX(N#)` | a number as hexadecimal text |
+| `SPC(N#)` | that many spaces |
+
+`LEFT` and `RIGHT` clamp rather than failing, so asking for more characters than the
+string has gives you the whole string.
+
+**`MID` and `INSTR` count from zero**, where a C128's `MID$` and `INSTR` count from one.
+`MID("HELLO WORLD", 6, 5)` is `WORLD`, and `INSTR("HELLO WORLD", "WORLD")` is `6`. A
+failed `INSTR` gives -1, not 0, so there is no ambiguity with a match at the start.
+
+```
+10 A$ = "HELLO WORLD"
+20 PRINT LEN(A$)
+30 PRINT LEFT(A$, 5)
+40 PRINT RIGHT(A$, 5)
+50 PRINT MID(A$, 6, 5)
+60 PRINT INSTR(A$, "WORLD")
+```
+
+`VAL` refuses text that is not a number rather than quietly returning zero, so a
+program can tell "the user typed 0" from "the user typed nonsense".
+
+## PRINT USING
+
+`PRINT USING` lays a value out in a fixed field, which is what makes columns line up.
+
+```
+10 PRINT USING "###.##"; 3.14159
+20 PRINT USING "TOTAL: $#,###.##"; 1234.5
+30 PRINT USING "####-"; -42
+```
+
+```
+  3.14
+TOTAL: $1,234.50
+  42-
+```
+
+The field is built from these characters, and any text around it is printed as it
+stands:
+
+| In the field | Means |
+|---|---|
+| `#` | one digit position |
+| `.` | the decimal point |
+| `,` | group the integer part in threes |
+| `$` | a currency sign |
+| `+` or `-` at the front | a sign position before the number |
+| `+` or `-` at the end | a sign position after it |
+| `=` | centre a string in the field |
+| `>` | right-justify a string |
+
+**A value too wide for its field fills the field with `*`.** That is deliberate and it
+is loud: printing more digits than the field asked for would push every later column
+out of line.
+
+```
+10 PRINT USING "###"; 99999
+```
+
+```
+***
+```
+
+A negative number in a field with no sign position overflows the same way, because
+printing `-5` as `5` would be worse.
+
+String fields centre and right-justify:
+
+```
+10 PRINT USING "=========="; "MID"
+20 PRINT USING ">>>>>>>>>>"; "RIGHT"
+```
+
+```
+   MID    
+     RIGHT
+```
+
+One field per statement. `PRINT USING "### ###"; A, B` is not supported — see
+Chapter 13.
+
+## PUDEF
+
+`PUDEF` changes the characters a numeric field pads and punctuates with. It takes up
+to four, in this order: the leading blank, the thousands separator, the decimal point,
+and the currency sign.
+
+```
+10 PUDEF "*"
+20 PRINT USING "#####"; 42
+```
+
+```
+***42
+```
+
+Positions you leave out keep what they had, so the one-character form above changes
+only the padding.
+
+## CHAR
+
+`CHAR` puts text at a character position rather than at the cursor:
+
+```
+10 CHAR 1, 10, 5, "HERE"
+```
+
+The arguments are colour, column, row and the text. It needs a text device with a
+cursor, which means the SDL build — a terminal's cursor is not this library's to move,
+and it refuses by name in the default build.
+
+The colour argument is accepted and ignored; the sink draws in one colour, chosen by
+whoever built it.