From: Alan T. DeKok <aland@freeradius.org>
Date: Wed, 6 Dec 2023 19:42:37 +0000 (-0500)
Subject: clarify behavior
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=ff94653c5352d8d22e003d306593b1924d0c7e71;p=thirdparty%2Ffreeradius-server.git

clarify behavior
---

diff --git a/doc/antora/modules/reference/pages/unlang/caller.adoc b/doc/antora/modules/reference/pages/unlang/caller.adoc
index fbb1f3f39b2..6973f9a239f 100644
--- 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
     }
 }
 ----