add notes on arrays and parent / child

diff --git a/doc/antora/modules/unlang/pages/attr.adoc b/doc/antora/modules/unlang/pages/attr.adoc
index b2689c4490104bdc8149eb962e170552bc86a8f7..ab4fb97c113a6f6ef268d47337655e518dcd5ff4 100644 (file)
--- a/doc/antora/modules/unlang/pages/attr.adoc
+++ b/doc/antora/modules/unlang/pages/attr.adoc
@@ -16,9 +16,86 @@ evaluates to `false`.
 When used elsewhere, such as in xref:switch.adoc[switch], it returns
 the value of the named attribute.
 
+.Examples
+[source,unlang]
+----
+&User-Name
+&NAS-IP-Address
+----
+
+== Lists
+
+The attribute reference can also be qualified with a
+xref:list.adoc[list] reference.  When no list is given, the server
+looks in the input packet list for the named attribute.
+
+.Examples
+
+[source,unlang]
+----
+&request.User-Name
+&reply.NAS-IP-Address
+----
+
+== Array References
+
+.Syntax
+[source,unlang]
+----
+&Attribute-Name[<integer]
+----
+
+When an attribute appears multiple times in a list, this syntax allows
+you to address the attributes as if they were array entries.  The
+`<integer>` value defines which attribute to address.  The `[0]` value
+refers to the first attributes, `[1]` refers to the second attribute,
+etc.
+
+.Examples
+[source,unlang]
+----
+&EAP-Message[1]
+&reply.NAS-IP-Address[2]
+----
+
+== Parent / child references
+
+.Syntax
+[source,unlang]
+----
+&Attribute-Name.Attribute-Name
+----
+
+In some cases, attributes are nested or grouped.  The child reference
+syntax is used to address a particular child attribute.  Multiple
+levels of parent / child nesting can be performed by simply appending
+the name of another child attribute, separated by the `.` character.
+
+.Examples
+
+[source,unlang]
+----
+&TLV-One.Child-one
+&TLV-One.Child-one.Child-Three
+&reply.TLV[3].Child-Two
+----
+
+== Putting it All Together
+
+All of the above syntaxes can be used interchangeably, at any nesting level.  The examples are presented
+
+.Examples
+[source,unlang]
+----
+&TLV-One.Child-one[3].Child-Three
+&reply.TLV[3].Child-Two
+----
+
+== Compatibility with Older Versions of FreeRADIUS
+
 Older versions of the server did not use the `&` character to
 distinguish attribute names from other strings.  Version 4 requires
-the user of the `&` before attribute names.
+the use of the `&` character before attribute names.
 
 Without the `&`, the server could interpret a string as `hello-there`
 either as a literal string "hello-there", or as a reference to an
@@ -28,15 +105,5 @@ parse the configuration files correctly in all cases.
 Adding the leading `&` character means that attribute references are
 now easily distinguishable from literal strings.
 
-The attribute reference can also be qualified with a
-xref:list.adoc[list] reference.  When no list is given, the
-server looks in the input packet list for the named attribute.
-
-.Examples
-
-`&User-Name` +
-`&NAS-IP-Address` +
-`&reply.Reply-Message`
-
 // Copyright (C) 2019 Network RADIUS SAS.  Licenced under CC-by-NC 4.0.
 // Development of this documentation was sponsored by Network RADIUS SAS.