Give the Programming Manual a title, and send the boot image format away

Last of the four. What was left after the reorder was a document whose first
heading was "General Description" doing a part title's job without being
one, and a section called "Input and Output In the Emulator" that held two
console ports, a worked program, and a file format.

  A title and an opening that says what this document is FOR, and what the
  other two are for, so a reader who wants the operating system or the
  language knows immediately they are in the wrong file.

  "General Description" is "The Machine", which matches the three part
  headings the reorder gave the rest.

  "Input and Output In the Emulator" is "Making It Print Something", which
  is what the section is: port 0, and the shortest program that uses it.

THE BOOT IMAGE FORMAT MOVES TO THE ASSEMBLER MANUAL, beside the loadable
program format, for the reason SBEX went there: it is a thing the assembler
WRITES. It is fair that the emulator reads them too - both tools speak it,
the way SplitDisk and sbfs.asm both speak the filesystem - but only one of
them makes one.

And it is called a boot image now, in the text as well as the heading. That
is what this project has been calling these files for a while; the manual
was still saying "binary", which now means either kind of output file and so
means neither.

A CHECK THAT GOT BETTER BY BEING SPLIT. The hello world program and the hex
dump of it were both in the Programming Manual, and docs.sh compared them
with each other and with the assembler. The program stays with the machine,
where the reorder put it just after the instruction list; the dump goes with
the format it demonstrates. So the check now settles THREE things against
each other: what one manual prints, what the other prints, and what the
assembler actually makes. Verified both ways - a wrong byte in the dump, and
the anchor renamed.

The manual is 692 lines and four parts. It was 1,116 lines and nineteen flat
sections when this started.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E2JrLzFvuFX9fgi1LDRjrW

SplitBit Assembler Manual.md

@@ -207,6 +207,52 @@ A program that genuinely wants a segment at the bottom of memory says so:
 
 `#Base` is the one directive that takes zero. `#Align` and `#Reserve` are counts, and a count of nothing is a typo, so they still require at least one.
 
+## The Boot Image Format:
+
+A boot image is what the machine starts from: the Program and Data segments in one file,
+with nothing to say where they go, because they go at the bottom of each memory. It is what
+the assembler writes when a program does not say where it lives, and what the emulator is
+given on the command line.
+
+Every value in it is stored most significant byte first, which is the same order the CPU reads addresses out of Program Memory.
+
+A file begins with a nine byte header:
+
+| Offset | Size | Field |
+| -- | -- | -- |
+| 0 | 4 | The characters `SPBT`, so that a file which is not a boot image is recognised as such straight away. |
+| 4 | 1 | The format version. This document describes version 1. |
+| 5 | 4 | Required feature flags. |
+
+The feature flags are how a boot image states that it needs something the base machine does not provide. An emulator that cannot provide everything an image asks for refuses to run it, rather than running it and going quietly wrong. No feature bits are defined yet, so the field is currently zero in every image.
+
+After the header come the segments. The Program Segment comes first and then the Data Segment, each beginning with a three character marker, `PRG` or `DAT`, followed by a two byte length. The system loads each memory with the bytes that follow, in sequence, starting from address 0x0000.
+
+A third segment may follow them, marked `VEC`, holding the vectors a program named in its Vector Segment. It is four bytes an entry: two saying where in Program Memory the vector sits, and two saying where its handler is. A program that named no vectors has no such segment, and a file that simply ends after its Data Segment is one written before vectors existed. Either way the reader treats the end of the file as an empty table, which is why adding this cost no format version and left every image already written still loadable.
+
+Here is the hello world program from the Programming Manual, assembled and dumped as hex:
+
+```
+53 50 42 54 01 00 00 00 00 50 52 47 00 11 42 00 12 00 0c d1 00 40 00 10 00 00 26 0a d1 00 ff 44
+41 54 00 0e 48 65 6c 6c 6f 2c 20 57 6f 72 6c 64 21 00
+```
+
+Taken apart:
+
+| Bytes | Meaning |
+| -- | -- |
+| `53 50 42 54` | `SPBT` |
+| `01` | Format version 1 |
+| `00 00 00 00` | No features required |
+| `50 52 47` | `PRG` |
+| `00 11` | The Program Segment is 17 bytes long |
+| `42 00 12 00 0c d1 00 40 00 10 00 00 26 0a d1 00 ff` | The Program Segment |
+| `44 41 54` | `DAT` |
+| `00 0e` | The Data Segment is 14 bytes long |
+| `48 65 6c 6c 6f 2c 20 57 6f 72 6c 64 21 00` | The Data Segment |
+
+The `42 00` at the start of the Program Segment is worth a look: `42` is LDA, and the `00` after it is the Data Pointer selector the assembler filled in, because the program did not name one.
+
 ## Loading A Program From A Disk:
 
 A program that was not the one the machine booted from carries sixteen bytes in front of it saying where it belongs.