Add section about dynamic links to 'Linking in WikiText' (#6361)

* Add discussion of dynamic links to 'Linking in WikiText'

* Added macro and styles for displaying a 'bad' example

* Use .bad-example macro in 'Linking in WikiText'

* Convert existing warnings to use .bad-example macro

editions/tw5.com/tiddlers/howtos/Concatenating text and variables using macro substitution.tid

@@ -1,5 +1,5 @@
 created: 20160424150551727
-modified: 20190115162340362
+modified: 20211230153027382
 tags: Learning
 title: Concatenating text and variables using macro substitution
 type: text/vnd.tiddlywiki
@@ -9,9 +9,7 @@ It's a frequent use case in ~TiddlyWiki that you will want to put the results of
 
 You might, for instance want to set up a template for your customer database, where links will automatically refer to additional contact information about your customer. Inside your tiddler, you might try something like this:
 
-
-|warning|k
-|@@font-size:1.5em;&#9888;@@ Warning:<br/> Don't do it this way!| `[[Additional Info|<<currentTiddler>>-Contact]]` |
+<<.bad-example "`[[Additional Info|<<currentTiddler>>-Contact]]`">>
 
 But that won't work. If you try this, the link will be interpreted very literally, and will attempt to take you to:
 
@@ -29,9 +27,7 @@ Create a macro at the top of the tiddler like this:
 
 You might be tempted to invoke the new macro like this:
 
-|warning|k
-|@@font-size:1.5em;&#9888;@@ Warning:<br/> Don't do it this way!| `<<linkup <<currentTiddler>> >>` |
-
+<<.bad-example "`<<linkup <<currentTiddler>> >>`">>
 
 But if you do, you will find that `<<currentTiddler>>` doesn't get rendered, but instead gets passed literally.
 
@@ -53,10 +49,4 @@ Notice that in this case we don't pass an argument. Instead, we reference the va
 
 ```
 <<linkup>>
-```
-
-<style>
-.warning code  {background-color:#ffff80}
-table.warning {background-color:#ffff80;}
-
-</style>
+```

editions/tw5.com/tiddlers/system/doc-macros.tid

@@ -1,5 +1,5 @@
 created: 20150117152607000
-modified: 201804111739
+modified: 20211230150413997
 tags: $:/tags/Macro
 title: $:/editions/tw5.com/doc-macros
 type: text/vnd.tiddlywiki
@@ -113,6 +113,20 @@ This is an example tiddler. See [[Table-of-Contents Macros (Examples)]].
 </$list>
 \end
 
+\define .bad-example(eg)
+<table class="doc-bad-example">
+<tbody>
+<tr class="evenRow">
+<td><span class="tc-inline-style" style="font-size:1.5em;">&#9888;</span> Warning:<br> Don't do it this way!</td>
+<td>
+
+$eg$
+</td>
+</tr>
+</tbody>
+</table>
+\end
+
 \define .link-badge(text,link,colour)
 <a href=<<__link__>> class="doc-link-badge" style="background-color:$colour$;" target="_blank" rel="noopener noreferrer"><$text text=<<__text__>>/></a>
 \end

editions/tw5.com/tiddlers/system/doc-styles.tid

@@ -1,5 +1,5 @@
 created: 20150117152612000
-modified: 20211124164948726
+modified: 20211230150725145
 tags: $:/tags/Stylesheet
 title: $:/editions/tw5.com/doc-styles
 type: text/vnd.tiddlywiki
@@ -133,6 +133,10 @@ td svg {
 	padding-left: 20px;
 }
 
+.doc-bad-example code, .doc-bad-example pre, table.doc-bad-example {
+  background-color:#ffff80;
+}
+
 .doc-table th, .doc-table tr {
 	vertical-align: top;
 }

editions/tw5.com/tiddlers/wikitext/Linking in WikiText.tid

@@ -1,6 +1,6 @@
 caption: Linking
 created: 20131205155230596
-modified: 20160607095245257
+modified: 20211230145939554
 tags: WikiText
 title: Linking in WikiText
 type: text/vnd.tiddlywiki
@@ -80,3 +80,40 @@ You can also use the extended syntax to force an external link:
 
 See the LinkWidget for details of the underlying widget used to implement tiddler links, including macros that can be used to customise its behaviour.
 
+! Generating dynamic links
+
+[[Linking in WikiText]] does not lend itself well to creating dynamic links. The reason is because this WikiText link:
+
+```
+[[link to myself|Linking in WikiText]]
+```
+is shorthand for using the LinkWidget and TextWidget like this:
+
+```
+<$link to="Linking in WikiText">
+  <$text text="link to myself"/>
+</$link>
+```
+Since both the link title ("link to myself") and the link target ("Linking in ~WikiText") are used as widget attributes, no WikiText expansion takes place.
+
+For example, an attempt to use a [[reference|TextReference]] and a [[variable|Variables]] to dynamically generate a link like this:
+
+<<.bad-example "`[[{{!!caption}}|<<currentTiddler>>]]`">>
+
+is the same as trying to use the LinkWidget and TextWidget like this:
+
+<<.bad-example """```
+<$link to="<<currentTiddler>>">
+  <$text text="{{!!caption}}"/>
+</$link>
+```""">>
+
+This will not work as desired. Content inside of quoted widget attributes is [[treated as a literal value|HTML in WikiText]] and protected from WikiText expansion, so it will render like this:
+
+<<.bad-example "[[{{!!caption}}|<<currentTiddler>>]]">>
+
+In order to get the desired result, the LinkWidget can be used directly like this:
+
+<<wikitext-example-without-html src:"<$link to=<<currentTiddler>>>{{!!caption}}</$link>">>
+
+See also another example of [[constructing dynamic links|Concatenating text and variables using macro substitution]].