docs.sh: say which heading went missing, rather than raising IndexError

The manual checks find what they examine by splitting the file on an exact
heading. Ten of the eleven anchors already say what they could not find -
"the Programming Manual has lost its Devices table" and so on. Two did not:
the worked hello world program and the hex dump beside it were reached with
pm.split(anchor)[1] and nothing else, so renaming either produced a Python
traceback and an IndexError.

A traceback is a worse answer than a stale manual. It says a check broke
without saying which heading moved, and it stops the rest of the run, so
whatever else was wrong stays unreported.

Both anchors are now tested before they are used, and both say which one is
missing and what that means. Verified by renaming each and reading the
message.

This is the first of four commits restructuring the Programming Manual, and
it comes first on purpose: the next three move headings around, and they
should be watched by checks that would notice.

IT ALSO CORRECTS THE PLAN. I had written that renaming a heading fails
silently, and set out to fix all eleven. Probing them one at a time showed
that was wrong - ten were already fine, and the job was one check rather
than the whole file. The claim was worth testing before acting on it.

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

Tests/docs.sh

@@ -316,22 +316,34 @@ import os
 import subprocess
 import tempfile
 
-source = pm.split("### Example Program: Hello World")[1].split("```")[1]
+# BOTH ANCHORS ARE CHECKED BEFORE THEY ARE USED. Every other heading this script splits on
-claimed = pm.split("assembled and dumped as hex:")[1].split("```")[1].split()
+# says what it could not find; these two were the exception, and a rename here produced an
-with tempfile.TemporaryDirectory() as work:
+# IndexError and a traceback instead of a sentence. That is a worse answer than a stale
-    asm = os.path.join(work, "hello.asm")
+# manual, because whoever reads it learns nothing about which heading moved.
-    binary = os.path.join(work, "hello.bin")
+exampleAnchor = "### Example Program: Hello World"
-    open(asm, "w").write(source)
+dumpAnchor = "assembled and dumped as hex:"
-    built = subprocess.run(["./Assembler", asm, "-o", binary],
+if exampleAnchor not in pm:
-                           capture_output=True)
+    problems.append("the Programming Manual has lost its \"Example Program: Hello World\""
-    if built.returncode != 0:
+                    " heading, so the worked example cannot be found")
-        problems.append("the hello world program in the manual no longer assembles")
+elif dumpAnchor not in pm:
-    else:
+    problems.append("the Programming Manual no longer says \"%s\" before the hex dump, so"
-        actual = ["%02x" % b for b in open(binary, "rb").read()]
+                    " there is nothing to compare the worked example against" % dumpAnchor)
-        if [c.lower() for c in claimed] != actual:
+else:
-            problems.append("the hex dump in the manual is not what that program assembles to"
+    source = pm.split(exampleAnchor)[1].split("```")[1]
-                            " now: it prints %d bytes and the assembler makes %d"
+    claimed = pm.split(dumpAnchor)[1].split("```")[1].split()
-                            % (len(claimed), len(actual)))
+    with tempfile.TemporaryDirectory() as work:
+        asm = os.path.join(work, "hello.asm")
+        binary = os.path.join(work, "hello.bin")
+        open(asm, "w").write(source)
+        built = subprocess.run(["./Assembler", asm, "-o", binary], capture_output=True)
+        if built.returncode != 0:
+            problems.append("the hello world program in the manual no longer assembles")
+        else:
+            actual = ["%02x" % b for b in open(binary, "rb").read()]
+            if [c.lower() for c in claimed] != actual:
+                problems.append("the hex dump in the manual is not what that program"
+                                " assembles to now: it prints %d bytes and the assembler"
+                                " makes %d" % (len(claimed), len(actual)))
 
 # ---- The Assembler Manual's worked programs still assemble ----
 for heading in ["## An Example SplitBit Assembly Program:",