From 0d74b84ce4c484f0ef4a23326c4327d05ac4358a Mon Sep 17 00:00:00 2001
From: bbbradsmith <bbbradsmith@users.noreply.github.com>
Date: Sat, 16 Dec 2023 19:18:25 -0500
Subject: [PATCH 1/6] Test of .struct and .union features. Update documentation
 with more examples, better clarity, and fixes to incorrect data.

---
 doc/ca65.sgml         |  76 ++++++++++++---
 test/asm/val/struct.s | 222 ++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 286 insertions(+), 12 deletions(-)
 create mode 100644 test/asm/val/struct.s

diff --git a/doc/ca65.sgml b/doc/ca65.sgml
index 104c59bbd..e54b308d4 100644
--- a/doc/ca65.sgml
+++ b/doc/ca65.sgml
@@ -4086,8 +4086,10 @@ See: <tt><ref id=".ASCIIZ" name=".ASCIIZ"></tt>,<tt><ref id=".BYTE" name=".BYTE"
 
 <sect1><tt>.TAG</tt><label id=".TAG"><p>
 
-  Allocate space for a struct or union.
-
+  Allocate space for a struct or union. This is equivalent to
+  <tt><ref id=".RES" name=".RES"></tt> with the
+  <tt><ref id=".SIZEOF" name=".SIZEOF"></tt> of a struct.
+  
   Example:
 
   <tscreen><verb>
@@ -4100,6 +4102,7 @@ See: <tt><ref id=".ASCIIZ" name=".ASCIIZ"></tt>,<tt><ref id=".BYTE" name=".BYTE"
                 .tag    Point           ; Allocate 4 bytes
   </verb></tscreen>
 
+  See: <ref id="structs" name="&quot;Structs and unions&quot;">
 
 <sect1><tt>.UNDEF, .UNDEFINE</tt><label id=".UNDEFINE"><p>
 
@@ -4865,10 +4868,15 @@ compiler, depending on the target system selected:
 
 Structs and unions are special forms of <ref id="scopes" name="scopes">.  They
 are, to some degree, comparable to their C counterparts. Both have a list of
-members. Each member allocates storage, and optionally may have a name whose
-value, in the case of a struct, usually is the storage offset from the
-beginning, and in the case of a union, doesn't change, and usually is zero.
+members. Each member allocates storage, and optionally may have a name.
 
+Each named member has a constant value equal to the storage offset from the
+beginning of the structure. In the case of a union, all members are placed at
+the same offset, typically 0.
+
+Each named member also has a storage size which can be accessed with the
+<ref id=".SIZEOF" name=".SIZEOF"></tt> operator. The struct or union itself also
+has a <tt/.SIZEOF/ indicating its total storage size.
 
 <sect1>Declaration<p>
 
@@ -4895,8 +4903,9 @@ A struct or union may not necessarily have a name. If it is anonymous, no
 local scope is opened; the identifiers used to name the members are placed
 into the current scope instead.
 
-A struct may contain unnamed members and definitions of local structs/unions.
-The storage allocators may contain a multiplier, as in the example below:
+Storage allocators may contain a multiplier. A struct may also contain members
+and definitions of local structs/unions. Example:
+
 <tscreen><verb>
       .struct Circle
               .struct Point
@@ -4905,7 +4914,8 @@ The storage allocators may contain a multiplier, as in the example below:
               Radius  .word
       .endstruct
 </verb></tscreen>
-The size of the Circle struct is 6 (three words).
+
+In this example the size of the Circle struct is 6 (three words).
 
 
 <sect1>The storage allocator keywords<p>
@@ -4915,7 +4925,7 @@ The size of the Circle struct is 6 (three words).
   <tag/.BYTE, .RES/
     Allocates multiples of 1 byte.  <tt/.RES/ requires an operand.
 
-  <tag/.DBYTE, .WORD, .ADDR/
+  <tag/.DBYT, .WORD, .ADDR/
     Allocates multiples of 2 bytes.
 
   <tag/.FARADDR/
@@ -4924,6 +4934,15 @@ The size of the Circle struct is 6 (three words).
   <tag/.DWORD/
     Allocates multiples of 4 bytes.
 
+  <tag/.TAG/
+    Allocates a previously defined struct.
+
+  <tag/.STRUCT, .UNION/
+    Begins a nested .struct or .union definition, and allocates it.
+    Note that its member offset values will begin at 0, unless this nested
+    structure is anonymous, in which case they will instead become members of
+    the enclosing scope.
+
   </descrip>
 
 
@@ -4968,13 +4987,46 @@ name=".TAG"> directive.
 C:      .tag    Circle
 </verb></tscreen>
 
-Currently, members are just offsets from the start of the struct or union. To
+Members are just offsets from the start of the struct or union. To
 access a field of a struct, the member offset must be added to the address of
 the struct variable itself:
 <tscreen><verb>
-        lda     C+Circle::Radius        ; Load circle radius into A
+        lda    C + Circle::Radius                    ; Load circle radius
+        lda    C + Circle::Origin + Point::ycoord    ; Load circle origin.ycoord
 </verb></tscreen>
-That may change in a future version of the assembler.
+
+Nested structures or unions are treated differently depending on whether they
+are anonymous. If named, a new structure definition is created within the
+enclosing scope, with its offsets beginning at 0. If anonymous, the members of
+the new structure are added to the enclosing scope instead. Example:
+
+<tscreen><verb>
+      .struct Object
+              member .byte            ; Object::member = 0
+              named .struct Point     ; Object::named = 1
+                      xcoord  .word   ; Object::Point::xcoord = 0
+                      ycoord  .word   ; Object::Point::ycoord = 2
+              .endstruct
+              unnamed .struct         ; Object::unnamed = 5
+                      un1  .word      ; Object::un1 = 5
+                      un2  .word      ; Object::un2 = 7
+              .endstruct
+              .struct
+                      un3  .word      ; Object::un3 = 9
+              .endstruct
+      .endstruct
+
+      lda    O + Object::named + Object::Point::ycoord
+      lda    O + Object::un2
+</verb></tscreen>
+
+In this example, the first nested structure is named "Point", and its member
+offsets begin at 0. On the other hand, the two anonymous structures simply
+continue to add members to the enclosing Object structure.
+
+Note that an anonymous structure does not need a member name, since all of its
+members become part of the enclosing structure. The "unnamed" member in the
+example is redundantly the same offset as its first member "un1.
 
 
 <sect1>Limitations<p>
diff --git a/test/asm/val/struct.s b/test/asm/val/struct.s
new file mode 100644
index 000000000..b2bf08ea0
--- /dev/null
+++ b/test/asm/val/struct.s
@@ -0,0 +1,222 @@
+; test .struct feature
+
+.code
+
+; exit with 0
+.export _main
+_main:
+    lda #0
+    tax
+    rts
+
+; test storage allocator sizes and offsets
+
+.struct Storage
+    mb1 .byte
+    mb5 .byte 5
+    mr1 .res 1
+    mr5 .res 5
+    mdb1 .dbyt
+    mdb5 .dbyt 5
+    mw1 .word
+    mw5 .word 5
+    ma1 .addr
+    ma5 .addr 5
+    mf1 .faraddr
+    mf5 .faraddr 5
+    mdw1 .dword
+    mdw5 .dword 5
+.endstruct
+
+.assert .sizeof(Storage::mb1)  =  1, error, ".struct .byte member has unexpected .sizeof"
+.assert .sizeof(Storage::mb5)  =  5, error, ".struct .byte 5 member has unexpected .sizeof"
+.assert .sizeof(Storage::mr1)  =  1, error, ".struct .res 1 member has unexpected .sizeof"
+.assert .sizeof(Storage::mr5)  =  5, error, ".struct .res 5 member has unexpected .sizeof"
+.assert .sizeof(Storage::mdb1) =  2, error, ".struct .dbyt member has unexpected .sizeof"
+.assert .sizeof(Storage::mdb5) = 10, error, ".struct .dbyt 5 member has unexpected .sizeof"
+.assert .sizeof(Storage::mw1)  =  2, error, ".struct .word member has unexpected .sizeof"
+.assert .sizeof(Storage::mw5)  = 10, error, ".struct .word 5 member has unexpected .sizeof"
+.assert .sizeof(Storage::ma1)  =  2, error, ".struct .addr member has unexpected .sizeof"
+.assert .sizeof(Storage::ma5)  = 10, error, ".struct .addr 5 member has unexpected .sizeof"
+.assert .sizeof(Storage::mf1)  =  3, error, ".struct .faraddr member has unexpected .sizeof"
+.assert .sizeof(Storage::mf5)  = 15, error, ".struct .faraddr 5 member has unexpected .sizeof"
+.assert .sizeof(Storage::mdw1) =  4, error, ".struct .dword member has unexpected .sizeof"
+.assert .sizeof(Storage::mdw5) = 20, error, ".struct .dword 5 member has unexpected .sizeof"
+
+.assert Storage::mb1  = 0, error, ".struct storage offset is incorrect"
+.assert Storage::mb5  = Storage::mb1  + .sizeof(Storage::mb1),  error, ".struct storage offset is incorrect"
+.assert Storage::mr1  = Storage::mb5  + .sizeof(Storage::mb5),  error, ".struct storage offset is incorrect"
+.assert Storage::mr5  = Storage::mr1  + .sizeof(Storage::mr1),  error, ".struct storage offset is incorrect"
+.assert Storage::mdb1 = Storage::mr5  + .sizeof(Storage::mr5),  error, ".struct storage offset is incorrect"
+.assert Storage::mdb5 = Storage::mdb1 + .sizeof(Storage::mdb1), error, ".struct storage offset is incorrect"
+.assert Storage::mw1  = Storage::mdb5 + .sizeof(Storage::mdb5), error, ".struct storage offset is incorrect"
+.assert Storage::mw5  = Storage::mw1  + .sizeof(Storage::mw1),  error, ".struct storage offset is incorrect"
+.assert Storage::ma1  = Storage::mw5  + .sizeof(Storage::mw5),  error, ".struct storage offset is incorrect"
+.assert Storage::ma5  = Storage::ma1  + .sizeof(Storage::ma1),  error, ".struct storage offset is incorrect"
+.assert Storage::mf1  = Storage::ma5  + .sizeof(Storage::ma5),  error, ".struct storage offset is incorrect"
+.assert Storage::mf5  = Storage::mf1  + .sizeof(Storage::mf1),  error, ".struct storage offset is incorrect"
+.assert Storage::mdw1 = Storage::mf5  + .sizeof(Storage::mf5),  error, ".struct storage offset is incorrect"
+.assert Storage::mdw5 = Storage::mdw1 + .sizeof(Storage::mdw1), error, ".struct storage offset is incorrect"
+.assert .sizeof(Storage) = Storage::mdw5 + .sizeof(Storage::mdw5), error, ".struct has unexpected .sizeof"
+
+; test union offset and size
+
+.union UStorage
+    mb1 .byte
+    mb5 .byte 5
+    mr1 .res 1
+    mr5 .res 5
+    mdb1 .dbyt
+    mdb5 .dbyt 5
+    mw1 .word
+    mw5 .word 5
+    ma1 .addr
+    ma5 .addr 5
+    mf1 .faraddr
+    mf5 .faraddr 5
+    mdw1 .dword
+    mdw5 .dword 5
+.endunion
+
+.assert .sizeof(UStorage::mb1)  =  1, error, ".union .byte member has unexpected .sizeof"
+.assert .sizeof(UStorage::mb5)  =  5, error, ".union .byte 5 member has unexpected .sizeof"
+.assert .sizeof(UStorage::mr1)  =  1, error, ".union .res 1 member has unexpected .sizeof"
+.assert .sizeof(UStorage::mr5)  =  5, error, ".union .res 5 member has unexpected .sizeof"
+.assert .sizeof(UStorage::mdb1) =  2, error, ".union .dbyt member has unexpected .sizeof"
+.assert .sizeof(UStorage::mdb5) = 10, error, ".union .dbyt 5 member has unexpected .sizeof"
+.assert .sizeof(UStorage::mw1)  =  2, error, ".union .word member has unexpected .sizeof"
+.assert .sizeof(UStorage::mw5)  = 10, error, ".union .word 5 member has unexpected .sizeof"
+.assert .sizeof(UStorage::ma1)  =  2, error, ".union .addr member has unexpected .sizeof"
+.assert .sizeof(UStorage::ma5)  = 10, error, ".union .addr 5 member has unexpected .sizeof"
+.assert .sizeof(UStorage::mf1)  =  3, error, ".union .faraddr member has unexpected .sizeof"
+.assert .sizeof(UStorage::mf5)  = 15, error, ".union .faraddr 5 member has unexpected .sizeof"
+.assert .sizeof(UStorage::mdw1) =  4, error, ".union .dword member has unexpected .sizeof"
+.assert .sizeof(UStorage::mdw5) = 20, error, ".union .dword 5 member has unexpected .sizeof"
+.assert .sizeof(UStorage) = 20, error, ".union has unexpected .sizeof"
+
+.assert UStorage::mb1  = 0, error, ".union storage offset is incorrect"
+.assert UStorage::mb5  = 0, error, ".union storage offset is incorrect"
+.assert UStorage::mr1  = 0, error, ".union storage offset is incorrect"
+.assert UStorage::mr5  = 0, error, ".union storage offset is incorrect"
+.assert UStorage::mdb1 = 0, error, ".union storage offset is incorrect"
+.assert UStorage::mdb5 = 0, error, ".union storage offset is incorrect"
+.assert UStorage::mw1  = 0, error, ".union storage offset is incorrect"
+.assert UStorage::mw5  = 0, error, ".union storage offset is incorrect"
+.assert UStorage::ma1  = 0, error, ".union storage offset is incorrect"
+.assert UStorage::ma5  = 0, error, ".union storage offset is incorrect"
+.assert UStorage::mf1  = 0, error, ".union storage offset is incorrect"
+.assert UStorage::mf5  = 0, error, ".union storage offset is incorrect"
+.assert UStorage::mdw1 = 0, error, ".union storage offset is incorrect"
+.assert UStorage::mdw5 = 0, error, ".union storage offset is incorrect"
+
+; test tag
+
+storage: .tag Storage
+.assert (*-storage)=.sizeof(Storage), error, ".tag reserved size incorrect"
+
+; test nested structures
+
+.struct Point
+    xc .word
+    yc .word
+.endstruct
+
+.struct Nested
+    pad .res 13
+    tag .tag Point
+    ch .struct Child
+        ca .word ; offset = 0
+        gch .struct Grandchild
+            gca .word ; offset = 0
+            gcb .byte
+        .endstruct
+        cb .byte
+    .endstruct
+    anon .struct
+        aa .dword ; offset = Nested::anon (anonymous .struct)
+        ab .dword
+    .endstruct
+    chu .union Chunion
+        ua .byte ; offset = 0
+        ub .dword
+    .endunion
+    chanon .union
+        uc .byte ; offset = Nested::chanon
+        ud .dword
+    .endunion
+    last .byte
+.endstruct
+
+.assert Nested::pad                    = 0, error, "Nested .struct has unexpected starting offset"
+.assert Nested::Child::ca              = 0, error, "Nested .struct has unexpected starting offset"
+.assert Nested::Child::Grandchild::gca = 0, error, "Nested .struct has unexpected starting offset"
+
+.assert .sizeof(Nested::tag) = .sizeof(Point), error, ".tag in .struct has unexpected .sizeof"
+.assert .sizeof(Nested::Child::Grandchild) = 2 + 1, error, "Nested .struct has unexpected .sizeof"
+.assert .sizeof(Nested::Child) = 2 + 1 + .sizeof(Nested::Child::Grandchild), error, "Nested .struct has unpexpected .sizeof"
+.assert .sizeof(Nested::ch) = .sizeof(Nested::Child), error, "Nested .struct has unexpected member .sizeof"
+.assert .sizeof(Nested::Child::gch) = .sizeof(Nested::Child::Grandchild), error, "Nested .struct has unexpected member .sizeof"
+.assert .sizeof(Nested::anon) = 8, error, "Nested anonymous member .struct has unexpected .sizeof"
+.assert .sizeof(Nested::aa) = 4, error, "Nested anonymous .struct member has unexpected .sizeof"
+.assert .sizeof(Nested::ab) = 4, error, "Nested anonymous .struct member has unexpected .sizeof"
+.assert .sizeof(Nested::Chunion) = 4, error, "Nested .union has unexpected .sizeof"
+.assert .sizeof(Nested::chu) = .sizeof(Nested::Chunion), error, "Nested member .union has unexpected .sizeof"
+.assert .sizeof(Nested::chanon) = 4, error, "Nested anonymous member .union as unexpected .sizeof"
+
+.assert Nested::tag    = Nested::pad + .sizeof(Nested::pad),     error, ".tag within .struct has unexpected offset"
+.assert Nested::ch     = Nested::tag + .sizeof(Nested::tag),     error,  "Nested .struct has unexpected offset"
+.assert Nested::anon   = Nested::ch + .sizeof(Nested::ch),       error, "Nested anonymous member .struct has unexpected offset"
+.assert Nested::aa     = Nested::anon,                           error, "Nested anonymous .struct member has unexpected offset"
+.assert Nested::ab     = Nested::aa + .sizeof(Nested::aa),       error, "Nested anonymous .struct member has unexpected offset"
+.assert Nested::chu    = Nested::ab + .sizeof(Nested::ab),       error, "Nested member .union has unexpected offset"
+.assert Nested::chanon = Nested::chu + .sizeof(Nested::Chunion), error, "Nested anonymous member .union has unexpected offset"
+.assert Nested::uc     = Nested::chanon,                         error, "Nested anonymous .union member has unexpected offset"
+.assert Nested::ud     = Nested::chanon,                         error, "Nested anonymous .union member has unexpected offset"
+.assert Nested::last   = Nested::ud + .sizeof(Nested::ud),       error, ".struct member has unexpected offset after anonymous nested .struct"
+
+; test .org
+
+start:
+
+.struct OrgStruct
+    ma .byte
+    mb .byte
+    .org $1234
+    mc .byte
+    md .byte
+    .struct Nested
+        me .byte
+        .org $5678
+        mf .byte
+        mg .byte
+    .endstruct
+    mh .byte
+.endstruct
+
+.assert start <> (OrgStruct::mh+1), error, "Fatal test error: accidental code position conflict, move OrgStruct .org to another arbitrary address."
+.assert * = start, error, ".org within .struct does not return to previous location at .endstruct"
+.assert OrgStruct::ma = 0, error, ".struct with .org has unexpected offset"
+.assert OrgStruct::mb = 1, error, ".struct with .org has unexpected offset"
+.assert OrgStruct::mc = $1234, error, ".struct with .org has unexpected offset"
+.assert OrgStruct::md = $1235, error, ".struct with .org has unexpected offset"
+.assert OrgStruct::Nested::me = 0, error, "Nested .struct with .org has unexpected offset"
+.assert OrgStruct::Nested::mf = $5678, error, "Nested .struct with .org has unexpected offset"
+.assert OrgStruct::Nested::mg = $5679, error, "Nested .struct with .org has unexpected offset"
+.assert OrgStruct::mh = $1239, error, ".struct with .org has unexpected offset"
+.assert .sizeof(OrgStruct) = 8, error, ".struct with .org has unexpected .sizeof"
+
+.union OrgUnion
+    ma .byte
+    mb .word
+    .org $1234
+    mc .byte
+    md .word
+.endunion
+
+.assert start <> OrgUnion::md, error, "Fatal test error: accidental code position conflict, move OrgUnion .org to another arbitrary address."
+.assert * = start, error, ".org within .union does not return to previous location at .endunion"
+.assert OrgUnion::ma = 0, error, ".union with .org has unexpected offset"
+.assert OrgUnion::mb = 0, error, ".union with .org has unexpected offset"
+.assert OrgUnion::mc = $1234, error, ".union with .org has unexpected offset"
+.assert OrgUnion::md = $1234, error, ".union with .org has unexpected offset"
+.assert .sizeof(OrgUnion) = 2, error, ".union with .org has unexpected .sizeof"

From 6cb8717c24d415448f451edbe3f949e9188fe1c1 Mon Sep 17 00:00:00 2001
From: bbbradsmith <bbbradsmith@users.noreply.github.com>
Date: Sat, 16 Dec 2023 19:25:21 -0500
Subject: [PATCH 2/6] fix dangling space, mention .union in test comment

---
 doc/ca65.sgml         | 2 +-
 test/asm/val/struct.s | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/ca65.sgml b/doc/ca65.sgml
index e54b308d4..dde782a57 100644
--- a/doc/ca65.sgml
+++ b/doc/ca65.sgml
@@ -4089,7 +4089,7 @@ See: <tt><ref id=".ASCIIZ" name=".ASCIIZ"></tt>,<tt><ref id=".BYTE" name=".BYTE"
   Allocate space for a struct or union. This is equivalent to
   <tt><ref id=".RES" name=".RES"></tt> with the
   <tt><ref id=".SIZEOF" name=".SIZEOF"></tt> of a struct.
-  
+
   Example:
 
   <tscreen><verb>
diff --git a/test/asm/val/struct.s b/test/asm/val/struct.s
index b2bf08ea0..b6ef6f45d 100644
--- a/test/asm/val/struct.s
+++ b/test/asm/val/struct.s
@@ -1,4 +1,4 @@
-; test .struct feature
+; test .struct and .union features
 
 .code
 

From f6838be1621f4ef57c1224209c50e41ee0bcfe4d Mon Sep 17 00:00:00 2001
From: bbbradsmith <bbbradsmith@users.noreply.github.com>
Date: Sat, 16 Dec 2023 19:32:52 -0500
Subject: [PATCH 3/6] missing <tt>

---
 doc/ca65.sgml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/ca65.sgml b/doc/ca65.sgml
index dde782a57..9be63d035 100644
--- a/doc/ca65.sgml
+++ b/doc/ca65.sgml
@@ -4875,8 +4875,8 @@ beginning of the structure. In the case of a union, all members are placed at
 the same offset, typically 0.
 
 Each named member also has a storage size which can be accessed with the
-<ref id=".SIZEOF" name=".SIZEOF"></tt> operator. The struct or union itself also
-has a <tt/.SIZEOF/ indicating its total storage size.
+<tt><ref id=".SIZEOF" name=".SIZEOF"></tt> operator. The struct or union itself
+also has a <tt/.SIZEOF/ indicating its total storage size.
 
 <sect1>Declaration<p>
 

From 0ff1b20f2a2420bbff8e162c54e52fa24561de3e Mon Sep 17 00:00:00 2001
From: bbbradsmith <bbbradsmith@users.noreply.github.com>
Date: Sat, 16 Dec 2023 19:52:57 -0500
Subject: [PATCH 4/6] nested struct example needs a .tag

---
 doc/ca65.sgml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/doc/ca65.sgml b/doc/ca65.sgml
index 9be63d035..3d4899366 100644
--- a/doc/ca65.sgml
+++ b/doc/ca65.sgml
@@ -5016,6 +5016,7 @@ the new structure are added to the enclosing scope instead. Example:
               .endstruct
       .endstruct
 
+O:    .tag   Object
       lda    O + Object::named + Object::Point::ycoord
       lda    O + Object::un2
 </verb></tscreen>

From 302c4f7409b898ea5c1d63009b883e5887c2ea78 Mon Sep 17 00:00:00 2001
From: bbbradsmith <bbbradsmith@users.noreply.github.com>
Date: Sun, 17 Dec 2023 05:01:06 -0500
Subject: [PATCH 5/6] clarify offsets of anonymous nested scope, missing quotes
 for names

---
 doc/ca65.sgml | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/doc/ca65.sgml b/doc/ca65.sgml
index 3d4899366..3120d9dd4 100644
--- a/doc/ca65.sgml
+++ b/doc/ca65.sgml
@@ -4998,7 +4998,8 @@ the struct variable itself:
 Nested structures or unions are treated differently depending on whether they
 are anonymous. If named, a new structure definition is created within the
 enclosing scope, with its offsets beginning at 0. If anonymous, the members of
-the new structure are added to the enclosing scope instead. Example:
+the new structure are added to the enclosing scope instead, with offsets
+continuing through that scope. Example:
 
 <tscreen><verb>
       .struct Object
@@ -5023,11 +5024,11 @@ O:    .tag   Object
 
 In this example, the first nested structure is named "Point", and its member
 offsets begin at 0. On the other hand, the two anonymous structures simply
-continue to add members to the enclosing Object structure.
+continue to add members to the enclosing "Object" structure.
 
 Note that an anonymous structure does not need a member name, since all of its
 members become part of the enclosing structure. The "unnamed" member in the
-example is redundantly the same offset as its first member "un1.
+example is redundantly the same offset as its first member "un1".
 
 
 <sect1>Limitations<p>

From 9892c8f6c45f3ad61c49ce78d22881161d21dbab Mon Sep 17 00:00:00 2001
From: bbbradsmith <bbbradsmith@users.noreply.github.com>
Date: Sun, 17 Dec 2023 05:40:00 -0500
Subject: [PATCH 6/6] using less generic names for the example to avoid
 confusion, adding cautionary example for what I think is the most error prone
 case

---
 doc/ca65.sgml | 26 ++++++++++++++++----------
 1 file changed, 16 insertions(+), 10 deletions(-)

diff --git a/doc/ca65.sgml b/doc/ca65.sgml
index 3120d9dd4..c5c6893da 100644
--- a/doc/ca65.sgml
+++ b/doc/ca65.sgml
@@ -5003,23 +5003,29 @@ continuing through that scope. Example:
 
 <tscreen><verb>
       .struct Object
-              member .byte            ; Object::member = 0
-              named .struct Point     ; Object::named = 1
+              id .byte                ; Object::id = 0
+              target .struct Point    ; Object::target = 1
                       xcoord  .word   ; Object::Point::xcoord = 0
                       ycoord  .word   ; Object::Point::ycoord = 2
               .endstruct
-              unnamed .struct         ; Object::unnamed = 5
-                      un1  .word      ; Object::un1 = 5
-                      un2  .word      ; Object::un2 = 7
+               cost .struct           ; Object::cost = 5
+                      price  .word    ; Object::price = 5
+                      tax  .word      ; Object::tax = 7
               .endstruct
               .struct
-                      un3  .word      ; Object::un3 = 9
+                      radius  .word   ; Object::radius = 9
               .endstruct
       .endstruct
 
 O:    .tag   Object
-      lda    O + Object::named + Object::Point::ycoord
-      lda    O + Object::un2
+      lda    O + Object::target + Object::Point::ycoord  ; Named struct
+      lda    O + Object::tax                             ; Anonymous
+      lda    O + Object::radius                          ; Anonymous
+
+      ; Be careful not to use a named nested structure without also adding the
+      ; offset to the nested structure itself.
+      lda    O + Object::Point::ycoord                   ; Incorrect!
+      lda    O + Object::target + Object::Point::ycoord  ; Correct
 </verb></tscreen>
 
 In this example, the first nested structure is named "Point", and its member
@@ -5027,8 +5033,8 @@ offsets begin at 0. On the other hand, the two anonymous structures simply
 continue to add members to the enclosing "Object" structure.
 
 Note that an anonymous structure does not need a member name, since all of its
-members become part of the enclosing structure. The "unnamed" member in the
-example is redundantly the same offset as its first member "un1".
+members become part of the enclosing structure. The "cost" member in the
+example is redundantly the same offset as its first member "price".
 
 
 <sect1>Limitations<p>