note "please don't use %{expr:..}"

diff --git a/doc/antora/modules/reference/pages/xlat/builtin.adoc b/doc/antora/modules/reference/pages/xlat/builtin.adoc
index e10748666a3e8613107328fbe00765d1a6478cc7..a55eec14349e961b68fa1ca8aca8fb57f3c0190b 100644 (file)
--- a/doc/antora/modules/reference/pages/xlat/builtin.adoc
+++ b/doc/antora/modules/reference/pages/xlat/builtin.adoc
@@ -1019,12 +1019,16 @@ not bob!
 === +%(expr:<string>)+
 
 Evaluates the string as an xref:reference:unlang/expression.adoc[Unlang expression], and returns the result.  Please see the
-xref:reference:unlang/expression.adoc[Unlang expression] page for full
-documentation on expressions.
+xref:reference:unlang/expression.adoc[Unlang expression] page for full documentation on expressions.
+
+[NOTE]
+====
+You probably don't want to use this.  In v4, the main use of `%{expr:...}` is inside of strings which can't be split into actual expressions.
+====
 
 .Return: _data_
 
-.Example:
+.Example
 
 [source,unlang]
 ----
@@ -1041,6 +1045,15 @@ update reply
 3
 ```
 
+.A Better example of not using `%{expr:...}`
+
+[source,unlang]
+----
+&Tmp-String-0 := 1 + 2
+----
+
+
+
 === +%(nexttime:<time>)+
 
 Calculate number of seconds until next n hour(`s`), day(`s`), week(`s`), year(`s`).