New subsection "A Note on Authorship and AI Assistance" at the end of
"About The Author" states that as of 19 April 2026 the author has
begun using an AI assistant as a writing and editing aid on this
book, and that all material preceding that date was produced unaided.
Points the reader at git history and the scripts/ and .github/
tooling landed around the same time as the durable markers for
distinguishing AI-assisted from unaided work going forward.
Placement rationale: "About The Author" is already the section
carrying author-identity and first-person voice, so the disclosure
lives where a reader with any interest in authorship provenance
naturally scrolls. The alternative (a Front Matter subsection) was
considered and rejected as tonally too heavy for a note that exists
mainly to answer a future question, not to front-load caveats ahead
of the book's self-description.
No test coverage applies; this is prose.
Part of #33.
The v6.S listing in the hello_world chapter introduces the PUSH_P,
PUSH_R, POP_P and POP_R macros without explicitly telling the reader
what the _P and _R suffixes stand for. For a reader reading the
chapter in order, the mapping is derivable: the book established
stp = "store pair" about 260 lines earlier, and the _R suffix falls
out by parallel with str. But a reader who jumped straight to v6.S
without reading the stp explanation (as Atcold did in issue #33) has
no such anchor and is left guessing.
One sentence at the "The push and pop macros simply save typing"
paragraph closes the gap: it names the _P / _R suffixes, connects
them to the already-taught stp / str convention, and costs a skimmer
nothing. The macro names themselves are unchanged; they were already
fine for an in-order reader, and renaming would have churned every
.S file in the book.
The repository ships a copy of apple-linux-convergence.S in each
chapter directory that demonstrates assembly (11 copies at last count,
plus the canonical one in macros/) so that readers browsing or
downloading a single chapter from GitHub have the macros sitting
right next to the sources that use them. That self-containment is
worth keeping. Manual synchronization of 12 copies on every macro
edit is not: all 11 are currently byte-identical to the canonical,
but the first drift is a matter of when, not if, and diagnosing
"which chapter broke when I added a new macro" after the fact is
a bad time.
This commit turns "the copies are in sync" from a hope into a
machine-enforced invariant:
- scripts/sync-macros.sh: walks macros/*.S, finds every file with
the same basename anywhere else in the repo (excluding .git/ and
macros/ itself), and overwrites any copy that differs. Idempotent;
prints only the files it actually changed plus a summary. Uses
only POSIX tools (find, cmp, cp, basename) plus bash builtins
under a #!/usr/bin/env bash shebang. Verified working under both
macOS bash 3.2.57 and zsh 5.9 on clean-tree and drift-repair
paths.
- .github/workflows/check-macros.yml: runs the sync script on every
push and pull request, then fails the job if git diff --exit-code
shows the script produced any uncommitted change. The failure
message tells the author exactly what to do (run the script
locally, commit the result).
- macros/README.md: new "Source of truth" section marking the
chapter copies as derived artifacts, pointing editors at the
sync script, and stating that CI enforces the invariant.
Rejected alternatives:
- Symlinking each chapter copy to macros/apple-linux-convergence.S.
Cheapest option (zero infrastructure) and git handles symlinks
natively, but Windows checkouts without Developer Mode replace
the symlink with a plain-text file containing the target path.
This book's audience is overwhelmingly Linux and Apple Silicon,
so the Windows hazard is mostly theoretical, but a sync-and-check
approach works in every clone environment and makes the
source-of-truth relationship explicit rather than implicit in a
filesystem feature.
- Having each chapter .include the canonical file via a relative
path. Breaks the "self-contained chapter" property the copies
exist to preserve; a reader who downloads one chapter gets a
broken build because macros/ is not beside it.
- Making the copies build-time artifacts (generated by make, not
committed). Same problem: a reader browsing one chapter on
GitHub no longer sees the macro file they need.
Tests:
- ./scripts/sync-macros.sh run on the current tree reports
"macros already in sync (11 chapter copies checked)" and exits 0.
- Injecting a trailing-line perturbation into a chapter copy and
re-running the script: detects the drift, reports "synced: <path>",
and restores the file to canonical. Verified under both bash and
zsh, both paths.
Closes#22.
The alignment chapter's hex dump examples (e.g. "0011 eeff ccdd aabb"
for a little-endian long initialized to 0xaabbccddeeff0011) are correct
under the default hexdump(1) output convention: bytes grouped into
16-bit little-endian words, each word printed most-significant byte
first. But the chapter never told the reader which convention was in
use, so a reader reproducing the example with xxd or hexdump -C (both
byte-oriented, showing raw memory order) would get a different-looking
result and conclude the book had an endianness bug. That is exactly
what issue #22 reported, and it is also part of what the #33 filer
flagged as "there are no instructions about how to do such a thing"
for hex dumps in this chapter.
Fix: one new subsection "A Note on Hex Dumps" placed before Example 1,
stating the convention explicitly and warning xxd / hexdump -C users
that the bytes within each pair will appear swapped relative to the
examples. The examples themselves are unchanged; they were already
self-consistent under the word-oriented convention.
Rejected alternative: rewriting all the examples in byte-oriented
(xxd) form. That would have matched what most modern readers reach
for, but would also have required regenerating every hex dump in the
chapter and losing continuity with any reader who already absorbed
the current notation. A single explanatory paragraph is less invasive
and teaches the distinction, which is useful in its own right.
No test coverage applies; this is prose.
