fix(appendix-k): correct §K.3.2 abbreviation limit description#85
Merged
fix(appendix-k): correct §K.3.2 abbreviation limit description#85
Conversation
The source (expressp.c) folds 'X || <anything>' to 1 whenever X is any non-zero compile-time constant (check: o1.value != 0), not only when X is specifically the literal 1. Update the description to match. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: 36bit <24438359+36bit@users.noreply.github.com>
…ints - Table row 682: Glulx 'Maximum common properties' corrected from 'INDIV_PROP_START - 1 (default 255)' to show both the property slot range (INDIV_PROP_START - 1 = 255) and the user-declarable count (INDIV_PROP_START - 3 = 253, as confirmed by the compiler error message in objects.c:352-353). - Table row 686: 'Maximum classes' corrected to show the hard limits enforced by VENEER_CONSTRAINT_ON_CLASSES_Z = 256 (Z-machine) and VENEER_CONSTRAINT_ON_CLASSES_G = 32768 (Glulx) in header.h:617-622 and objects.c:1877. The previous text incorrectly said classes were 'limited only by the maximum number of objects / memory'. - Section 7.4.1 Glulx property text: clarified that 253 properties are user-declarable (not all 255 slots), matching the compiler's check. No changes to ch08-arrays.md: all claims verified correct against arrays.c (five array types, 32767 Z-machine entry limit, 255 string array entry limit, buffer/table/string layout, WORDSIZE handling). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: 36bit <24438359+36bit@users.noreply.github.com>
The guide claimed a 'hard limit of 96 abbreviations', which is technically the absolute ceiling but misleading: the default effective limit is 64 (from $MAX_ABBREVS defaulting to 64), and exceeding it gives an error suggesting 'Increase MAX_ABBREVS'. Only by raising $MAX_ABBREVS can the user reach 96. Also, $MAX_ABBREVS and $MAX_DYNAMIC_STRINGS must sum to exactly 96 in Z-code (enforced by tables.c:315-316), so raising one requires lowering the other. This constraint was entirely absent from the guide. Verified against Inform6-6.44 source: - directs.c:96-103: two-tier check (96 hard, MAX_ABBREVS soft) - errors.c:419-426: two distinct error messages - tables.c:315-316: fatalerror if MAX_ABBREVS+MAX_DYNAMIC_STRINGS != 96 - options.c:108-115: MAX_ABBREVS defaults to 64, ceiling 96 - options.c:176-184: MAX_DYNAMIC_STRINGS defaults to 32, ceiling 96 Update appendix-d MAX_ABBREVS and MAX_DYNAMIC_STRINGS entries to note the sum-to-96 constraint. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: 36bit <24438359+36bit@users.noreply.github.com>
- ch12 §12.4.3: $MAX_ABBREVS Glulx default was 64 (misleading, setting is Z-code only per OPTUSE_ZCODE in options.c); changed to N/A to match ch15 §15.4.1 and the source - ch12 §12.4.3 / ch15 §15.2.2: Both settings said 'hard upper limit of 96' independently, but inform.c lines 223-234 enforce MAX_ABBREVS + MAX_DYNAMIC_STRINGS = 96 exactly in Z-code (shared pool). Updated both chapters to describe the constraint accurately. - ch15 §15.8.1 comparison table: Glulx local variables showed 119 but the usable count is 118 (inform.c line 138 allocates slot 0 as the internal 'sp' register). The Z-machine column correctly showed 15 (not 16); Glulx column corrected to 118 for consistency. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: 36bit <24438359+36bit@users.noreply.github.com>
The table incorrectly stated that returning 2 from Initialise() suppresses both the banner and the initial Look. Verified against parser.h: if (j ~= 2) Banner(); #Ifndef NOINITIAL_LOOK; <Look>; #Endif; Returning 2 only skips the Banner() call. The <Look> action is always performed unconditionally (unless NOINITIAL_LOOK is defined at compile time). - Corrected the table row for return value 2 - Updated the note to accurately describe the use case and mention NOINITIAL_LOOK for games that also want to suppress the initial Look Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: 36bit <24438359+36bit@users.noreply.github.com>
The compiler's opcodes_table_g[] (asm.c lines 786–814) contains 29 single-precision floating-point opcodes with the GOP_Float flag: 3 conversion (numtof, ftonumz, ftonumn), 2 rounding (ceil, floor), 5 arithmetic (fadd, fsub, fmul, fdiv, fmod), 4 transcendental (sqrt, exp, log, pow), 7 trig (sin, cos, tan, asin, acos, atan, atan2), 6 float comparisons (jfeq, jfne, jflt, jfle, jfgt, jfge), and 2 special value tests (jisnan, jisinf). The chapter body text (§30.9.3) already listed all 29 correctly but the introductory sentence and the §30.7.2 summary table both said 26. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: 36bit <24438359+36bit@users.noreply.github.com>
Corrected the Glk function selector table against infglk.h (inform6lib-6.12.8): - glk_window_iterate: $0040 → $0020 (decimal 32) - glk_window_open: $0047 → $0023 (decimal 35) - glk_window_get_size:$002F → $0025 (decimal 37) - glk_put_buffer: $0086 → $0084 (decimal 132) - glk_select: $00E0 → $00C0 (decimal 192) - glk_fileref_create_by_prompt: $0160 → $0062 (decimal 98) Each wrong value was actually the selector for a different Glk function; e.g. $0040=glk_stream_iterate, $00E0=glk_image_get_info, $0160=glk_current_time. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: 36bit <24438359+36bit@users.noreply.github.com>
The Limitations section incorrectly stated "Positions 0–2 are reserved for shift characters". The compiler's map_new_zchar() function (chars.c) uses the loop "for (i=2; i<26; i++)", which starts at position 2. Only positions 0 and 1 are skipped entirely; position 2 is scannable and can be replaced by the single-character Zcharacter form. The 21-position count is correct (26 total − 2 reserved − 3 protected = 21), but the description of which positions are reserved was wrong. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: 36bit <24438359+36bit@users.noreply.github.com>
…ay and lowest_global_number Both constants produce "System constant not implemented in Glulx" at runtime: neither class_objects_array_SC nor lowest_global_number_SC is handled in value_of_system_constant_g() in expressp.c. The appendix incorrectly labelled them Z/G. - §G.3: class_objects_array Z/G → Z - §G.10.2: lowest_global_number Z/G → Z - §G.11: move both constants from "Both VMs" list to "Z-machine only" list Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: 36bit <24438359+36bit@users.noreply.github.com>
Agent-Logs-Url: https://github.com/36bit/inform-guide/sessions/075b6576-6f18-43a2-a247-1e42c9f0296b Co-authored-by: 36bit <24438359+36bit@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
This PR updates the guide’s documentation around Z-machine abbreviation limits, correcting the previously stated v3-specific limit and aligning multiple chapters/appendices with the compiler’s actual behavior (including the shared 96-slot pool with dynamic strings). It also includes several unrelated factual corrections across Glulx, library entry points, and language/operator documentation.
Changes:
- Corrects and expands the documentation for
Abbreviate,$MAX_ABBREVS, and$MAX_DYNAMIC_STRINGS, including the Z-code shared 96-slot pool behavior. - Fixes several Glulx-related reference values (Glk selector numbers; Glulx float opcode counts).
- Clarifies/adjusts assorted VM/library/language limits and behaviors (Initialise return value
2, local variable count, common property counts, constant folding wording).
Reviewed changes
Copilot reviewed 12 out of 12 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| guide/part5-advanced/ch33-internationalization-localization.md | Adjusts A2 reserved-position description (but terminology needs correction; see comment). |
| guide/part4-vm/ch31-glulx-instruction-set.md | Corrects sample Glk selector numbers to match infglk.h. |
| guide/part4-vm/ch30-glulx-architecture.md | Updates single-precision float opcode counts (26 → 29). |
| guide/part3-library/ch26-library-entry-points.md | Corrects meaning of Initialise() return value 2 (banner suppression vs initial Look). |
| guide/part2-compiler/ch15-compiler-limits.md | Documents the shared 96-slot pool for abbreviations/dynamic strings; adjusts Glulx locals count. |
| guide/part2-compiler/ch12-compiler-switches.md | Clarifies $MAX_ABBREVS as Z-code-only and documents the shared-pool constraint. |
| guide/part1-language/ch10-compiler-directives.md | Updates Abbreviate directive description to reflect default vs hard ceiling and shared pool constraint. |
| guide/part1-language/ch07-objects-classes-inheritance.md | Clarifies Glulx common-property numbering and class-count caps. |
| guide/part1-language/ch04-expressions-and-operators.md | Refines constant-folding description for ` |
| guide/appendices/appendix-k-inform6-bnf-grammar.md | Updates §K.3.2 abbreviation limit text (but incorrectly claims no Glulx support; see comment). |
| guide/appendices/appendix-g-system-constants-reference.md | Refines VM applicability for selected system constants and updates platform lists. |
| guide/appendices/appendix-d-compiler-memory-settings.md | Adds the “must sum to 96” constraint note in both relevant setting sections. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
741
to
743
| shift characters, and three positions (`.`, `,`, and `~` at positions 12, | ||
| 13, and 19) are protected as essential punctuation, but the remaining 21 | ||
| positions (digits 0–9 and miscellaneous punctuation) may be replaced. |
Comment on lines
+371
to
+373
| The hard ceiling is 96 abbreviations in Z-code; the default `$MAX_ABBREVS` | ||
| setting is 64, and the 96-slot pool is shared with `$MAX_DYNAMIC_STRINGS`. | ||
| Not supported in Glulx mode. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The
Abbreviatedirective description incorrectly stated a version 3–specific limit of 64 abbreviations. The Z-machine spec allows 96 for v3 (same as v4–v8), and the Inform 6 compiler enforces the same ceiling regardless of target version.$MAX_ABBREVS(64) accurately$MAX_DYNAMIC_STRINGS