From 52bf6eccd90f71f317e0d235002aa5d8f1f75cb0 Mon Sep 17 00:00:00 2001 From: Perry Kivolowitz Date: Sun, 19 Apr 2026 02:26:19 -0500 Subject: [PATCH] Clarify PUSH_P / PUSH_R / POP_P / POP_R naming at first encounter 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. --- section_1/hello_world/README.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/section_1/hello_world/README.md b/section_1/hello_world/README.md index fa59106..df73035 100644 --- a/section_1/hello_world/README.md +++ b/section_1/hello_world/README.md @@ -798,10 +798,12 @@ MAIN // 7 .end // 24 ``` -The push and pop macros simply save typing but the other macros sense -if you are building on Linux or on Apple M family. In this case, the -macros are helping with underscores but the macro suite contains more -sophisticated helpers as well. +The push and pop macros simply save typing, continuing the `stp` / +`str` (store pair / store register) naming you've already seen: the +`_P` suffix takes a register pair, the `_R` suffix takes a single +register. The other macros sense if you are building on Linux or on +Apple M family. In this case, the macros are helping with underscores +but the macro suite contains more sophisticated helpers as well. ## Questions