diff --git a/doc/Language/regexes.pod6 b/doc/Language/regexes.pod6
index 9841f3c6d..5eaf83d6e 100644
--- a/doc/Language/regexes.pod6
+++ b/doc/Language/regexes.pod6
@@ -775,7 +775,19 @@ Note that neither the colon C<:> nor balancing delimiters such as C<{}> or
 C<()> can be substitution delimiters. Colons clash with adverbs such as C<s:i/Foo/bar/>
 and the other delimiters are used for other purposes.
 
-Like the C<m//> operator, whitespace is ignored in general. Comments, as in
+If you use balancing brackets, the substitution works like this instead:
+
+    s[replace] = 'with';
+
+The right-hand side is now a (not quoted) Perl 6 expression, in which C<$/>
+is available as the current match:
+
+    $_ = 'some 11 words 21';
+    s:g[ \d+ ] =  2 * $/;
+    .say;                    # OUTPUT: «some 22 words 42␤»
+
+Like the C<m//> operator, whitespace is ignored in the regex part of a
+substitution. Comments, as in
 Perl 6 in general, start with the hash character C<#> and go to the end of
 the current line.