diff --git a/guide/appendices/appendix-d-compiler-memory-settings.md b/guide/appendices/appendix-d-compiler-memory-settings.md index 62d7346..2839ebf 100644 --- a/guide/appendices/appendix-d-compiler-memory-settings.md +++ b/guide/appendices/appendix-d-compiler-memory-settings.md @@ -116,7 +116,7 @@ describes value constraints enforced by the compiler. |---------|-----------|---------------|----------|-------|-------------| | `MAX_ABBREVS` | 64 | — | [Z-machine] | 0–96 | Maximum number of declared abbreviations | | `NUM_ATTR_BYTES` | 6 | 7 | [Glulx] | Multiple of 4, plus 3 | Space (in bytes) used to store attribute flags; each byte stores 8 attributes | -| `DICT_WORD_SIZE` | 6 | 9 | [Glulx] | Any ≥ 0 | Number of characters in a dictionary word | +| `DICT_WORD_SIZE` | 6 (ignored) | 9 | [Glulx] | Any ≥ 0 | Number of characters in a dictionary word (ignored in Z-code; see §D.3.1) | | `DICT_CHAR_SIZE` | 1 | 1 | [Glulx] | 1 or 4 | Byte size of one character in the dictionary (4 enables full Unicode input) | | `GRAMMAR_VERSION` | 1 | 2 | [All] | Validated later | Grammar table format: 1 = Infocom format, 2 = Inform standard, 3 = compact (Z-code only, added in 6.43) | | `GRAMMAR_META_FLAG` | 0 | 0 | [All] | 0–1 | If 1, meta actions are indicated by value (≤ `#largest_meta_action`) rather than dict word flags | @@ -170,25 +170,30 @@ Abbreviate "you "; #### `DICT_WORD_SIZE` -**Platform:** Glulx only (fixed at 6 in Z-code) +**Platform:** Glulx only (ignored in Z-code) **Default:** 9 The number of source characters stored per dictionary word. -In Z-code, `DICT_WORD_SIZE` is fixed at 6 by the compiler — attempting to -set it to any other value produces a fatal error. The Z-machine specification -itself uses two different on-disk dictionary entry sizes depending on the VM -version: v3 entries are 4 bytes encoding **6 z-characters** (which decode to -up to 6 resolved characters), and v4 and later use 6 bytes encoding **9 -z-characters** (up to 9 resolved characters). Inform 6 internally limits the -word size to 4 bytes in v3 and 6 bytes in v4+, and the extra space allows -words up to 9 source characters to be parsed correctly. +In Z-code, `$DICT_WORD_SIZE` is **ignored** by the compiler. The Z-machine +dictionary sizes are handled automatically: v3 uses 4 bytes per entry +(encoding 6 Z-characters, supporting up to 6 resolved characters), and v4 +and later use 6 bytes per entry (encoding 9 Z-characters, supporting up to 9 +resolved characters). These sizes are determined by the target Z-machine +version, not by this setting. + +> **Compiler quirk:** Due to a bug in the compiler, explicitly setting +> `$DICT_WORD_SIZE` to any value other than 6 on the command line when +> targeting Z-code results in a fatal error, even though the setting is +> otherwise ignored. Setting it to 6 (the default) is accepted without error. +> A fix has been submitted to the maintainers; the expected resolution is a +> warning rather than a fatal error. In Glulx, this can be set to any value. Increasing it allows the parser to distinguish longer words, at the cost of a larger dictionary table. ```inform6 -!% $DICT_WORD_SIZE=12 +!% $DICT_WORD_SIZE=12 ! Glulx only ``` #### `DICT_CHAR_SIZE` @@ -278,14 +283,16 @@ allows individual actions to be precisely marked as meta. #### `NUM_ATTR_BYTES` -**Platform:** Glulx only (fixed at 6 in Z-code, 4 in v3) +**Platform:** Glulx only (fixed at 6 in Z-code regardless of version) **Default:** 7 The number of bytes used to store attribute flags in each object record. Each byte provides 8 attribute slots, so the default of 7 provides 56 attributes (numbered 0–55). In Glulx the value must be a multiple of 4, plus 3, so the allowed values are 3, 7, 11, 15, and so on. In Z-code this is fixed at 6 -(48 attribute slots, numbered 0–47; only attributes 0–31 are usable in v3). +regardless of Z-machine version (48 attribute slots, numbered 0–47); the +Z-machine v3 format writes only 4 of those 6 bytes to the object header, so +in practice only attributes 0–31 are usable in v3 builds. ```inform6 !% $NUM_ATTR_BYTES=11 diff --git a/guide/appendices/appendix-e-compiler-switches-reference.md b/guide/appendices/appendix-e-compiler-switches-reference.md index e87fefe..8289483 100644 --- a/guide/appendices/appendix-e-compiler-switches-reference.md +++ b/guide/appendices/appendix-e-compiler-switches-reference.md @@ -254,7 +254,7 @@ or both [All]. |---------|--------|-----------|-----------|-------------------| | `MAX_ABBREVS` | [Z] | 64 | — | Maximum declared abbreviations (max 96) | | `NUM_ATTR_BYTES` | [G] | — | 7 | Bytes for attribute flags (fixed at 6 in Z-code) | -| `DICT_WORD_SIZE` | [G] | — | 9 | Characters per dictionary word (fixed at 9 in Z-machine v4+, 6 in v3) | +| `DICT_WORD_SIZE` | [G] | — | 9 | Characters per dictionary word (ignored in Z-code; the compiler auto-selects 4 bytes/v3 or 6 bytes/v4+) | | `DICT_CHAR_SIZE` | [G] | — | 1 | Byte size of one dictionary character: 1 or 4 (Z-code uses compressed encoding) | | `GRAMMAR_VERSION` | [All] | 1 | 2 | Grammar table format version | | `GRAMMAR_META_FLAG` | [All] | 0 | 0 | Use action-value ordering for meta actions | @@ -522,7 +522,7 @@ command on the same line, preceded by `!`. ```inform6 !% -DG !% +include_path=../inform6lib -!% $DICT_WORD_SIZE=12 +!% $DICT_WORD_SIZE=12 ! Glulx only (-G flag is required for this to take effect) ! This is a regular comment — not a header comment. ! The compiler has already stopped reading !% lines. diff --git a/guide/appendices/appendix-f-veneer-routines.md b/guide/appendices/appendix-f-veneer-routines.md index 303a072..c396f2b 100644 --- a/guide/appendices/appendix-f-veneer-routines.md +++ b/guide/appendices/appendix-f-veneer-routines.md @@ -725,7 +725,9 @@ These routines provide fundamental services used by many other veneer routines. ### §F.6.1 `Copy__Primitive` (Index 21) — Deep Object Copy **Purpose:** Performs a deep copy of one object's data onto another. Used by the -class system for `create`, `recreate`, `destroy`, and `copy` operations. +class system for `recreate`, `destroy`, and `copy` operations. (The `create` +operation does not call `Copy__Primitive`; it simply removes and returns a +pre-allocated duplicate child object.) **Invoked by:** `Cl__Ms` (class message dispatch). diff --git a/guide/part1-language/ch06-routines.md b/guide/part1-language/ch06-routines.md index f6856bf..fa51fa5 100644 --- a/guide/part1-language/ch06-routines.md +++ b/guide/part1-language/ch06-routines.md @@ -310,11 +310,10 @@ Array handlers --> ProcessA ProcessB ProcessC; ### 6.8.2 Argument Limits for `indirect()` On the Z-machine (versions 4 and later), `indirect()` supports the -routine address plus up to **6 call arguments** (7 operands in total). -This is one fewer than a direct call, where the routine address plus 7 -call arguments are allowed. On version 3 the limit drops to 3 call -arguments, the same cap that applies to direct calls. The compiler -generates different call opcodes depending on the number of arguments. +routine address plus up to **7 call arguments**, the same limit as a +direct call. On version 3 the limit drops to 3 call arguments, the +same cap that applies to direct calls. The compiler generates different +call opcodes depending on the number of arguments. ## 6.9 Variable-Argument Routines (Glulx) diff --git a/guide/part1-language/ch07-objects-classes-inheritance.md b/guide/part1-language/ch07-objects-classes-inheritance.md index 577423a..3934fcb 100644 --- a/guide/part1-language/ch07-objects-classes-inheritance.md +++ b/guide/part1-language/ch07-objects-classes-inheritance.md @@ -362,7 +362,7 @@ Class Weapon(10) The `(10)` causes the compiler to manufacture a pool of 10 anonymous duplicate instances of `Weapon` at compile time (internally one additional duplicate is also created and kept as an untouched -prototype used by `recreate`, `destroy`, and `copy`). Each duplicate +prototype used by `recreate` and `destroy`). Each duplicate is initially placed as a child of the `Weapon` class object; the 10 pooled duplicates are ready-to-use instances that `Weapon.create()` can hand out and `Weapon.destroy(obj)` can return to the pool. The diff --git a/guide/part1-language/ch09-dictionary.md b/guide/part1-language/ch09-dictionary.md index c43117d..62441bb 100644 --- a/guide/part1-language/ch09-dictionary.md +++ b/guide/part1-language/ch09-dictionary.md @@ -146,6 +146,13 @@ Object -> pineapple "pineapple" The Z-machine word size is fixed by the virtual machine specification and cannot be changed by the programmer. +> **Warning:** The `$DICT_WORD_SIZE` compiler setting is silently ignored +> for Z-code targets. Due to a compiler quirk, setting `$DICT_WORD_SIZE` to +> any value other than its default of **6** on the command line (or via a +> `!%` header directive) when compiling for Z-code causes a fatal compile +> error: "You cannot change DICT_WORD_SIZE in Z-code". Use `$DICT_WORD_SIZE` +> only when targeting Glulx. + ### 9.3.2 Glulx Limits > **[Glulx]** On Glulx, the number of significant characters is controlled diff --git a/guide/part2-compiler/ch11-invoking-the-compiler.md b/guide/part2-compiler/ch11-invoking-the-compiler.md index 71ac17f..a8195e9 100644 --- a/guide/part2-compiler/ch11-invoking-the-compiler.md +++ b/guide/part2-compiler/ch11-invoking-the-compiler.md @@ -600,12 +600,12 @@ inform adventure.inf Because `$` compiler settings on the command line have higher precedence than those in `!%` header comments (§11.7.2), a command-line `$` setting -overrides the same setting embedded in the source. For example, if the -source contains `!% $DICT_WORD_SIZE=9`, you can still build with a +overrides the same setting embedded in the source. For example, if a +Glulx source contains `!% $DICT_WORD_SIZE=9`, you can still build with a 12-character dictionary by writing: ``` -inform $DICT_WORD_SIZE=12 adventure.inf +inform -G $DICT_WORD_SIZE=12 adventure.inf ``` Note that this reversal applies *only* to `$` settings. For ordinary @@ -616,5 +616,5 @@ overridden from the command line. **Use long options (6.35+):** ``` -inform --path include_path=i6lib --opt DICT_WORD_SIZE=12 --trace STATS adventure.inf +inform -G --path include_path=i6lib --opt DICT_WORD_SIZE=12 --trace STATS adventure.inf ``` diff --git a/guide/part2-compiler/ch12-compiler-switches.md b/guide/part2-compiler/ch12-compiler-switches.md index f765257..741fc3c 100644 --- a/guide/part2-compiler/ch12-compiler-switches.md +++ b/guide/part2-compiler/ch12-compiler-switches.md @@ -477,7 +477,7 @@ text data: | Setting | Z-code default | Glulx default | Description | | ------- | -------------- | ------------- | ----------- | -| `$DICT_WORD_SIZE` | 6 | 9 | Number of characters stored per dictionary word. Z-code words beyond this length are silently truncated. Increasing this value in Glulx allows the parser to distinguish longer words. | +| `$DICT_WORD_SIZE` | 6 | 9 | Number of characters stored per dictionary word. For Z-code, this setting is ignored — the compiler handles dictionary word sizes automatically (6 Z-characters in V3, 9 Z-characters in V4+). Due to a compiler quirk, setting this to any value other than 6 when compiling for Z-code produces a fatal error. For Glulx, words beyond this length are silently truncated; increasing it allows the parser to distinguish longer words. | | `$DICT_CHAR_SIZE` | 1 | 1 | Bytes per character in dictionary words. Set to 4 in Glulx to support full Unicode dictionary entries. In Z-code, this is always 1. | | `$MAX_ABBREVS` | 64 | N/A | Maximum number of `Abbreviate` directives. Z-code only; not meaningful in Glulx. In Z-code, `$MAX_ABBREVS` and `$MAX_DYNAMIC_STRINGS` share a pool of exactly 96 slots and must sum to 96. | | `$MAX_DYNAMIC_STRINGS` | 32 | 100 | Maximum number of string substitution variables (`@00`, `@(0)`, etc.). In Z-code, `$MAX_ABBREVS` and `$MAX_DYNAMIC_STRINGS` share a pool of exactly 96 slots and must sum to 96. | diff --git a/guide/part2-compiler/ch15-compiler-limits.md b/guide/part2-compiler/ch15-compiler-limits.md index 0ce329b..ac5ef49 100644 --- a/guide/part2-compiler/ch15-compiler-limits.md +++ b/guide/part2-compiler/ch15-compiler-limits.md @@ -204,7 +204,7 @@ current values, run `inform $LIST`. | Setting | Z-code default | Glulx default | Description | | ------- | -------------- | ------------- | ----------- | -| `$DICT_WORD_SIZE` | 6 (fixed) | 9 | Characters stored per dictionary word. Longer words are truncated during parsing. | +| `$DICT_WORD_SIZE` | 6 (ignored) | 9 | Characters stored per dictionary word. For Z-code, this setting is ignored; the compiler uses the correct size automatically (6 Z-characters in V3, 9 Z-characters in V4+). Due to a compiler quirk, setting this to any value other than 6 causes a fatal error in Z-code. For Glulx, words longer than this limit are truncated. | | `$DICT_CHAR_SIZE` | 1 (fixed) | 1 | Bytes per character in dictionary words. Set to 4 in Glulx for Unicode dictionary entries. | | `$MAX_ABBREVS` | 64 | N/A | Maximum number of `Abbreviate` directives. Z-code hard limit is 96. Not meaningful in Glulx (no abbreviation limit). | | `$MAX_DYNAMIC_STRINGS` | 32 | 100 | Maximum number of string substitution variables (`@00`, `@(0)`, etc.). Z-code hard limit is 96. | @@ -417,9 +417,13 @@ input in non-Latin scripts), also set `$DICT_CHAR_SIZE=4`: inform -G $DICT_WORD_SIZE=12 $DICT_CHAR_SIZE=4 adventure.inf ``` -**[Z-machine]** Dictionary word size cannot be changed in Z-code; it -is fixed at 6 characters (V3) or 9 characters (V4+) by the VM -specification. +**[Z-machine]** The `$DICT_WORD_SIZE` setting is ignored for Z-code; the +compiler automatically determines the correct dictionary word storage based +on the Z-machine version (6 Z-characters packed into 4 bytes for V3; 9 +Z-characters packed into 6 bytes for V4+). The setting is always treated +as 6 regardless of the configured value — due to a compiler quirk, +setting `$DICT_WORD_SIZE` to any value other than 6 when compiling for +Z-code produces a fatal error. ### 15.7.2 Enabling Dead-Code Stripping diff --git a/guide/part5-advanced/ch35-optimization-performance.md b/guide/part5-advanced/ch35-optimization-performance.md index 69f7927..93617f3 100644 --- a/guide/part5-advanced/ch35-optimization-performance.md +++ b/guide/part5-advanced/ch35-optimization-performance.md @@ -251,8 +251,7 @@ strings are compressed using Huffman encoding, which assigns shorter bit sequences to more frequently occurring characters and substrings. The `-H` switch controls Huffman compression for Glulx targets. It is -enabled by default; passing `-H` disables it (the switch toggles the -setting). With Huffman compression enabled, the compiler: +enabled by default; use `-~H` to disable it. With Huffman compression enabled, the compiler: 1. Analyses the frequency of all characters and common substrings across all game text. @@ -460,7 +459,7 @@ The following table lists the most commonly tuned memory settings: | `MAX_DYNAMIC_STRINGS` | 32 | 100 | Maximum number of `@NN` dynamic strings | | `MAX_STACK_SIZE` | N/A | 4096 | Glulx interpreter stack size (in bytes) | | `MEMORY_MAP_EXTENSION` | N/A | 0 | Extra zero-bytes appended to Glulx story file | -| `DICT_WORD_SIZE` | 6 | 9 | Dictionary word resolution length (in characters) | +| `DICT_WORD_SIZE` | ignored | 9 | Dictionary word resolution length in characters (Glulx only; ignored in Z-code) | ### 35.4.3 Local Variable Limits