From 88c8f496c4294f22b47399d958215b1f2b44f30d Mon Sep 17 00:00:00 2001 From: Perry Kivolowitz Date: Sun, 19 Apr 2026 02:20:10 -0500 Subject: [PATCH] Document hex dump display convention in alignment chapter 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. --- section_1/structs/alignment.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/section_1/structs/alignment.md b/section_1/structs/alignment.md index 19f4a31..e9a8c52 100644 --- a/section_1/structs/alignment.md +++ b/section_1/structs/alignment.md @@ -58,6 +58,18 @@ stinkin' rules. If they don't mind writing code that's buggy, that is. +## A Note on Hex Dumps + +The hex dumps shown in the examples that follow use the +default `hexdump(1)` output format: bytes are grouped into +16-bit *little endian* words, and each word is printed with +its most significant byte first. A byte-oriented tool such +as `xxd` or `hexdump -C` displays the raw bytes in memory +order instead — the same contents, shown differently. +If you reproduce these examples with `xxd`, expect the bytes +within each pair to appear swapped relative to what is shown +here. + ## Example 1 ```c