clarify behavior

diff --git a/doc/antora/modules/reference/pages/unlang/caller.adoc b/doc/antora/modules/reference/pages/unlang/caller.adoc
index fbb1f3f39b213cf3a6f12e3ed001039e60948fea..6973f9a239f307a137771e18980ad078addd8557 100644 (file)
--- a/doc/antora/modules/reference/pages/unlang/caller.adoc
+++ b/doc/antora/modules/reference/pages/unlang/caller.adoc
@@ -13,11 +13,26 @@ particular protocol.  If so, it executes the given _[statements]_, If
 the parent does not exist, or the parent protocol does not match, the
 statements are ignored.
 
-<protocol>::  The name of the protocol used by the virtual server which `call`ed this policy.
+<protocol>::  The name of the protocol used by the virtual server which xref:unlang/call.adoc[call]ed this policy.
 
-[ statements ]:: If the protocol matches, the _[
-statements]_ from inside of the `caller` section will be executed.
-These statements will be executed in the context of the current request.
+[ statements ]:: If the protocol matches, the _[statements]_ from
+inside of the `caller` section will be executed.  These statements
+will still be executed in the context of the current request.  The
+xref:unlang/call.adoc[call]ing request can be accessed by using
+`parent` in attribute references.
+
+That is, the `caller` keyword is a way to conditionally execute a
+subrequest.  It is largely equivalent to something like:
+
+[source,unlang]
+----
+if (parant && parent dictionary is RADIUS) {
+    ... statements ...
+}
+----
+
+However, for various internal reasons, that syntax is difficult to
+implement.  For now, the `caller` keyword is the best approach.
 
 A virtual server may the the target of multiple xref:unlang/call.adoc[call]
 keywords, each of which uses a different protocol.  For example, a
@@ -47,7 +62,7 @@ request to the current RADIUS reply packet, as the contents of the
 ----
 caller dhcpv4 {
     &reply += {
-        &Filter-Id = &parent.request:Client-Identifier
+        &Filter-Id = &parent.request.Client-Identifier
     }
 }
 ----