- add more on recursive dereferencing

1 files changed, 50 insertions, 9 deletions

diff --git a/doc/format-specifiers.txt b/doc/format-specifiers.txt
index 767de5c..b6ae9cf 100644
--- a/doc/format-specifiers.txt
+++ b/doc/format-specifiers.txt
@@ -176,11 +176,12 @@ And here's how various expressions evaluate for ''cn=group'':
 
 Looks for entries named by this entry's ''ATTRIBUTE'', and then by those
 entries' ''ATTRIBUTE'', repeating the search until there are no more
-entries to find named by ''ATTRIBUTE'' in the set of entries.
+entries to find named by ''ATTRIBUTE'' in the set of entries seen.
 
-Then searches for entries named by that set's ''OTHERATTRIBUTE'',
-similarly repeating until a new complete set of entries is determined,
-repeating the process for each listed attribute except the last.
+Taking that set as a new starting point, searches for entries named by
+that set's ''OTHERATTRIBUTE'' values, similarly repeating until a new
+complete set of entries is determined.  The process continues to be
+repeated for each listed attribute except the last.
 
 When the final set of entries is determined, their ''VALUEATTRIBUTE''
 values will be used to construct the result list.
@@ -190,6 +191,7 @@ Here are some example entries:
   dn: cn=group
   member: cn=othergroup
   member: uid=bob
+  includedgroup: clan=macleod
 
   dn: cn=othergroup
   member: uid=pete
@@ -201,16 +203,55 @@ Here are some example entries:
   dn: uid=pete
   uid: pete
 
+  dn: clan=macleod
+  includedgroup: cn=foundlings
+
+  dn: cn=foundlings
+  member: uid=cmacleod
+  member: uid=dmacleod
+
+  dn: uid=cmacleod
+  uid: cmacleod
+
+  dn: uid=dmacleod
+  uid: dmacleod
+
 And here's how various expressions evaluate for ''cn=group'':
 
   %deref_r("member","foo") -> no values
   %deref_r("member","uid") -> (bogus,bob,pete)
 
-The ''member'' attribute of ''cn=group'' produces this set of entries:
-  * cn=group (the original entry)
-  * cn=othergroup (added because it was named by ''cn=group'')
-  * uid=bob (added because it was named by ''cn=group'')
-  * uid=pete (added because it was named by ''cn=othergroup'')
+  When evaluating the first attribute, the ''member'' attribute of
+  ''cn=group'' produces this set of entries:
+
+    * cn=group (the original entry)
+    * cn=othergroup (added because it was named by ''cn=group'')
+    * uid=bob (added because it was named by ''cn=group'')
+    * uid=pete (added because it was named by ''cn=othergroup'')
+
+  The result list is pulled from this set of entries.
+
+Here's another example:
+
+  %deref_r("includedgroup","member","uid") -> (bogus,bob,cmacleod,dmacleod,pete)
+
+  When evaluating the first attribute, the ''includedgroup'' attribute
+  of ''cn=group'' leads to this set of entries:
+
+    * cn=group (the original entry)
+    * clan=macleod (named by cn=group)
+    * cn=foundlings (named by clan=macleod)
+
+  When evaluating the second attribute, the ''member'' attribute values
+  for the previous set of entries produces this set of entries:
+
+    * cn=othergroup (named by cn=group)
+    * uid=bob (named by cn=group)
+    * uid=cmacleod (named by cn=foundlings)
+    * uid=dmacleod (named by cn=foundlings)
+    * uid=pete (named by cn=othergroup)
+
+  The result list is pulled from this set of entries.
 
 === referred ===