From b2945e41c48a56dbfae199d6470d3082123c8199 Mon Sep 17 00:00:00 2001 From: Anachronaut Date: Fri, 21 Aug 2026 14:11:37 -0400 Subject: [PATCH] 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 Claude-Session: https://claude.ai/code/session_01E2JrLzFvuFX9fgi1LDRjrW --- Tests/docs.sh | 44 ++++++++++++++++++++++++++++---------------- 1 file changed, 28 insertions(+), 16 deletions(-) diff --git a/Tests/docs.sh b/Tests/docs.sh index 0c58922..3105555 100755 --- a/Tests/docs.sh +++ b/Tests/docs.sh @@ -316,22 +316,34 @@ import os import subprocess import tempfile -source = pm.split("### Example Program: Hello World")[1].split("```")[1] -claimed = pm.split("assembled and dumped as hex:")[1].split("```")[1].split() -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))) +# BOTH ANCHORS ARE CHECKED BEFORE THEY ARE USED. Every other heading this script splits on +# says what it could not find; these two were the exception, and a rename here produced an +# IndexError and a traceback instead of a sentence. That is a worse answer than a stale +# manual, because whoever reads it learns nothing about which heading moved. +exampleAnchor = "### Example Program: Hello World" +dumpAnchor = "assembled and dumped as hex:" +if exampleAnchor not in pm: + problems.append("the Programming Manual has lost its \"Example Program: Hello World\"" + " heading, so the worked example cannot be found") +elif dumpAnchor not in pm: + problems.append("the Programming Manual no longer says \"%s\" before the hex dump, so" + " there is nothing to compare the worked example against" % dumpAnchor) +else: + source = pm.split(exampleAnchor)[1].split("```")[1] + claimed = pm.split(dumpAnchor)[1].split("```")[1].split() + 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:",