From 5dfdbc8ea0f0b1382b06d6d3691e645edda9af05 Mon Sep 17 00:00:00 2001
From: Mario Pietsch <pmariojo@gmail.com>
Date: Fri, 7 Nov 2025 20:27:20 +0100
Subject: [PATCH] [DOCS] Slightly improve the substitution documentation
 (#9357)

---
 ...ating a text reference to create a URL.tid | 13 ++++
 ...oncatenating variables to create a URL.tid | 13 ++++
 .../substitute Operator (Examples).tid        | 77 ++++++++++++-------
 .../tiddlers/filters/substitute Operator.tid  |  4 +-
 ...and variables using macro substitution.tid |  2 +-
 .../wikitext/Substituted Attribute Values.tid | 20 ++---
 6 files changed, 84 insertions(+), 45 deletions(-)
 create mode 100644 editions/tw5.com/tiddlers/Concatenating a text reference to create a URL.tid
 create mode 100644 editions/tw5.com/tiddlers/Concatenating variables to create a URL.tid

diff --git a/editions/tw5.com/tiddlers/Concatenating a text reference to create a URL.tid b/editions/tw5.com/tiddlers/Concatenating a text reference to create a URL.tid
new file mode 100644
index 000000000..91e0abb3c
--- /dev/null
+++ b/editions/tw5.com/tiddlers/Concatenating a text reference to create a URL.tid	
@@ -0,0 +1,13 @@
+created: 20251021142729667
+modified: 20251021142729667
+tags: 
+title: Concatenating a text reference to create a URL
+type: text/vnd.tiddlywiki
+
+!! Concatenating variables and a text reference to create a URL
+
+<$macrocall $name=wikitext-example src="""<$let hash={{{ [<currentTiddler>encodeuricomponent[]] }}}>
+<a href=`${ [{!!base-url}] }$#$(hash)$`>this tiddler on tiddlywiki.com</a>
+</$let>"""/>
+
+See: [[Substituted Attribute Values]]
diff --git a/editions/tw5.com/tiddlers/Concatenating variables to create a URL.tid b/editions/tw5.com/tiddlers/Concatenating variables to create a URL.tid
new file mode 100644
index 000000000..0aeff2fab
--- /dev/null
+++ b/editions/tw5.com/tiddlers/Concatenating variables to create a URL.tid	
@@ -0,0 +1,13 @@
+created: 20251021142733998
+modified: 20251021142733998
+tags: 
+title: Concatenating variables to create a URL
+type: text/vnd.tiddlywiki
+
+!! Concatenating strings and variables to create a URL
+
+<$macrocall $name=wikitext-example src="""<$let hash={{{ [<currentTiddler>encodeuricomponent[]] }}}>
+<a href=`http://tiddlywiki.com/#$(hash)$`>this tiddler on tiddlywiki.com</a>
+</$let>"""/>
+
+See: [[Substituted Attribute Values]]
\ No newline at end of file
diff --git a/editions/tw5.com/tiddlers/filters/examples/substitute Operator (Examples).tid b/editions/tw5.com/tiddlers/filters/examples/substitute Operator (Examples).tid
index ece8aecf6..7d738b957 100644
--- a/editions/tw5.com/tiddlers/filters/examples/substitute Operator (Examples).tid	
+++ b/editions/tw5.com/tiddlers/filters/examples/substitute Operator (Examples).tid	
@@ -1,37 +1,60 @@
 created: 20230614225302905
-modified: 20230614233448662
+modified: 20251021140446753
 tags: [[Operator Examples]] [[substitute Operator]]
 title: substitute Operator (Examples)
 type: text/vnd.tiddlywiki
 
-\define time() morning
-\define field() modified
+!! Substitute operator parameters
+
+The following example uses a ''function definition'' and a ''function call'' with a ''filter expression''
+
+<<wikitext-example-without-html """\function f.text() [[Hi, I'm $1$ and I live in $2$]substitute[Bugs Bunny],[Rabbit Hole Hill]]
+
+<<f.text>>
+""">>
+
+---
+
+The following example uses a [[filtered transclusion|Transclusion in WikiText]] with a [[filter expression|Filter Syntax]] creating a link and a text output.
+
+<<wikitext-example-without-html """link: {{{ [[Hi, I'm $1$ and I live in $2$]substitute[Bugs Bunny],[Rabbit Hole Hill]] }}}
+
+text: <$text text={{{ [[Hi, I'm $1$ and I live in $2$]substitute[Bugs Bunny],[Rabbit Hole Hill]] }}}/>
+""">>
+
+
+!! Substitute variables and parameters
+
+The following example uses [[variable definitions|Pragma: \procedure]] "name", "address", a ''filtered transclusion'' assigned to a ''text-widget''. The variables "name" and "address" are used as ''substitute parameters''.
+
+<<wikitext-example-without-html """\procedure name() Bugs Bunny
+\procedure address() Rabbit Hole Hill
+
+<$text text={{{ [[Hi, I'm $1$ and I live in $2$]substitute<name>,<address>] }}}/>
+""">>
+
+!! Substitute $(variables)$
+
+The following examples use the variables "name" and "address" and directly substitute the with the [[attribute substitution|Substituted Attribute Values]] syntax. 
+
+<<wikitext-example-without-html """\procedure name() Bugs Bunny
+\procedure address() Rabbit Hole Hill
+
+<$text text=`Hi, I'm $(name)$ and I live in $(address)$`/>
+""">>
+
+!! Substitute a filter expression and a variable
+
+The following example uses a procedure, that defines the text with substitution placeholders. `$(field)$` is defined as a variable. `${ ... }$` is filtered <<.olink2 "substitution placeholder" to:"substitute">>.
+
+<<wikitext-example-without-html """\procedure field() modified
+
 \procedure sentence() This tiddler was last $(field)$ on ${[{!!modified}format:date[DDth MMM YYYY]]}$
-\define name() Bugs Bunny
-\define address() Rabbit Hole Hill
 
-!Substitute <<.op substitute[]>> operator parameters
-<<.operator-example 1 "[[Hi, I'm $1$ and I live in $2$]substitute[Bugs Bunny],[Rabbit Hole Hill]]">>
+<$text text={{{ [<sentence>substitute[]] }}}/>
 
-!Substitute variables
-This example uses the following variables:
+---
 
-* name: <$codeblock code=<<name>>/>
-* address: <$codeblock code=<<address>>/>
+<$text text=`This tiddler was last $(field)$ on ${[{!!modified}format:date[DDth MMM YYYY]]}$`/>
 
-<<.operator-example 2 "[[Hi, I'm $(name)$ and I live in $(address)$]substitute[]]">>
-
-!Substitute variables and operator parameters
-This example uses the following variable:
-
-* time: <$codeblock code=<<time>>/>
-
-<<.operator-example 3 "[[Something in the $(time)$ at $2$ about $1$ ]substitute[Maths],[the Library]]">>
-
-!Substitute a filter expression and a variable
-This example uses the following variables:
-
-* field: <$codeblock code=<<field>>/>
-* sentence: <$codeblock code=<<sentence>>/>
-
-<<.operator-example 4 "[<sentence>substitute[]]">>
+""">>
diff --git a/editions/tw5.com/tiddlers/filters/substitute Operator.tid b/editions/tw5.com/tiddlers/filters/substitute Operator.tid
index c7f98384e..6a67aef84 100644
--- a/editions/tw5.com/tiddlers/filters/substitute Operator.tid	
+++ b/editions/tw5.com/tiddlers/filters/substitute Operator.tid	
@@ -1,6 +1,6 @@
 caption: substitute
 created: 20230614223551834
-modified: 20230615173049692
+modified: 20251021124124967
 op-input: a [[selection of titles|Title Selection]]
 op-output: the input titles with placeholders for filter expressions, parameter and variables replaced with their corresponding values
 op-parameter: the <<.op substitute>> operator optionally accepts a variable number of parameters, see below for details
@@ -18,7 +18,7 @@ The <<.op substitute>> operator replaces any placeholders in the input titles in
 # variables
 
 |placeholder syntax|description|h
-|`$n$`|Text substitution of a parameter provided to the operator, where n is the position of the parameter starting with 1 for the first parameter. Unmatched placeholders pass through unchanged. |
+|`$n$`|Text substitution of a parameter provided to the operator, where n is the position of the parameter starting with 1 for the first parameter.<br>Unmatched placeholders pass through unchanged. |
 |`$(varname)$`|Text substitution of a variable. Undefined variables are replaced with an empty string. |
 |`${ filter expression }$`|Text substitution of the first result of evaluating a filter expression. In other words, if the filter returns multiple titles only the first one will be used. |
 
diff --git a/editions/tw5.com/tiddlers/howtos/Concatenating text and variables using macro substitution.tid b/editions/tw5.com/tiddlers/howtos/Concatenating text and variables using macro substitution.tid
index 933e1e80e..ee9a8d546 100644
--- a/editions/tw5.com/tiddlers/howtos/Concatenating text and variables using macro substitution.tid	
+++ b/editions/tw5.com/tiddlers/howtos/Concatenating text and variables using macro substitution.tid	
@@ -6,7 +6,7 @@ type: text/vnd.tiddlywiki
 
 !! Important
 
-<<.from-version "5.3.0">> It is recommended to use [[substituted attributes|Substituted Attribute Values]] or the [[substitute filter operator|substitute Operator]] to concatenate text and variables.
+Since <<.from-version "5.3.0">> it is recommended to use [[substituted attributes|Substituted Attribute Values]] or the [[substitute filter operator|substitute Operator]] to concatenate text and variables.
 
 It's a frequent use case in ~TiddlyWiki that you will want to put the results of variables together with various bits of strings of text. This process in some programming languages is often referred to as "concatenating" text.
 
diff --git a/editions/tw5.com/tiddlers/wikitext/Substituted Attribute Values.tid b/editions/tw5.com/tiddlers/wikitext/Substituted Attribute Values.tid
index 3e195d87a..07128dbce 100644
--- a/editions/tw5.com/tiddlers/wikitext/Substituted Attribute Values.tid	
+++ b/editions/tw5.com/tiddlers/wikitext/Substituted Attribute Values.tid	
@@ -1,6 +1,6 @@
 base-url: http://tiddlywiki.com/
 created: 20230615050814821
-modified: 20230615173033918
+modified: 20251021134906488
 tags: [[Widget Attributes]] WikiText
 title: Substituted Attribute Values
 type: text/vnd.tiddlywiki
@@ -24,22 +24,12 @@ The value of the attribute will be the text denoted by the backticks with any of
 
 !! Substituting a variable value into a string
 
-<$macrocall $name=wikitext-example-without-html src='<$text text=`Hello there this is the tiddler "$(currentTiddler)$"`/>'/>
+<$macrocall $name=wikitext-example-without-html src="""<$text text=`Hello there this is the tiddler "$(currentTiddler)$"`/>"""/>
 
 
 !! Substituting a variable value and the result of evaluating a filter expression into a string
-<$macrocall $name=wikitext-example-without-html src='<$text text=`This tiddler is titled "$(currentTiddler)$" and was last modified on ${[{!!modified}format:date[DDth MMM YYYY]]}$`/>'/>
+<$macrocall $name=wikitext-example-without-html src="""<$text text=`This tiddler is titled "$(currentTiddler)$" and was last modified on ${[{!!modified}format:date[DDth MMM YYYY]]}$`/>"""/>
 
-!! Concatenating strings and variables to create a URL
+{{Concatenating variables to create a URL}}
 
-<$macrocall $name=wikitext-example-without-html src='
-<$let hash={{{ [<currentTiddler>encodeuricomponent[]] }}}>
-<a href=`http://tiddlywiki.com/#$(hash)$`>this tiddler on tiddlywiki.com</a>
-</$let>'/>
-
-!! Concatenating variables and a text reference to create a URL
-
-<$macrocall $name=wikitext-example-without-html src='
-<$let hash={{{ [<currentTiddler>encodeuricomponent[]] }}}>
-<a href=`${ [{!!base-url}] }$#$(hash)$`>this tiddler on tiddlywiki.com</a>
-</$let>'/>
+{{Concatenating a text reference to create a URL}}
\ No newline at end of file