Docs updates

editions/tw5.com/tiddlers/howtos/How to apply custom styles by tag.tid

@@ -4,9 +4,9 @@ tags: Learning
 title: How to apply custom styles by tag
 type: text/vnd.tiddlywiki
 
-You can apply custom styles to tiddlers that have a particular tag by defining a CSS class with the name `tc-tagged-<Tag Name>`
+You can apply custom styles to tiddlers that have a particular tag by defining a CSS class with the name `tc-tagged-<Tag Name>`.
 
-For example, to make tiddlers tagged "NightReader" appear in a special colour scheme suitable for night-time reading, [[create a stylesheet|Using Stylesheets]] defining the class .`tc-tagged-NightReader` like this:
+For example, to make tiddlers tagged "NightReader" appear in a special colour scheme suitable for night-time reading, [[create a stylesheet|Using Stylesheets]] defining the class `tc-tagged-NightReader` like this:
 
 ```
 .tc-tagged-NightReader {
@@ -20,4 +20,11 @@ For example, to make tiddlers tagged "NightReader" appear in a special colour sc
 }
 ```
 
-Note that the `NightReader` class is applied to the entire tiddler and not just the tiddler text. If you want to target a smaller portion of the tiddler you can qualify the CSS selector, as is done here with `.tc-tagged-NightReader .tc-tiddler-body`.
+The `tc-tagged-NightReader` class is applied to the entire tiddler and not just the tiddler text. If you want to target a smaller portion of the tiddler you can qualify the CSS selector, as is done here with `.tc-tagged-NightReader .tc-tiddler-body`.
+
+Note that tags containing spaces or non-alphanumeric characters will be converted using URI encoding, making the generated CSS classname hard to predict. For example:
+
+|!Tag |!Generated Class Name |
+|`$:/mytag |`tc-tagged-%24%3A%2Fmytag` |
+|`one two` |`tc-tagged-one%20two` |
+|`£35.23` |`tc-tagged-%C2%A335.23` |

editions/tw5.com/tiddlers/wikitext/Confusion between Transclusion and Substitution.tid

@@ -0,0 +1,60 @@
+caption: Confusion between Transclusion and Substitution
+created: 20141018090608643
+modified: 20141018181414011
+tags: WikiText
+type: text/vnd.tiddlywiki
+
+The power of WikiText comes from the ability to use the content of one tiddler inside another one. This ability takes several different forms that can easily be confused.
+
+The main distinction is between a transclusion and a textual substitution:
+
+* A transclusion is replaced dynamically with the value of either:
+** a tiddler field
+** a variable
+* Textual substitutions are performed on the text of macro definitions before they are used
+
+! Tiddler Field Transclusion
+
+[[Transclusion in WikiText]] describes the basics of transclusion. For example:
+
+```
+{{MyTiddler}}
+```
+
+As described in [[HTML in WikiText]], you can also transclude tiddler field values as attributes of HTML elements and widgets. For example:
+
+```
+<$text text={{MyTiddler}}/>
+```
+
+As described in [[Introduction to Filters]], you can also transclude tiddler field values as filter operands. For example:
+
+```
+{{{ [tag{TiddlerContainingMyTag}] }}}
+```
+
+! Variable/Macro Transclusion
+
+Variables that were defined with parameter or variable substitution are referred to as "macros". The value of a variable/macro can be transcluded with the syntax:
+
+```
+<<myMacro param:"Value of parameter">>
+```
+
+As described in [[HTML in WikiText]], you can also transclude a variable as the value of an attribute of HTML elements and widgets. For example:
+
+```
+<$text text=<<myMacro>>/>
+```
+
+As described in [[Introduction to Filters]], you can also transclude a variable as the value of a filter operand. For example:
+
+```
+{{{ [tag<myMacro>] }}}
+```
+
+! Textual Substitution
+
+Textual substitution occurs when the value of a macro/variable is used. It is described in [[Macros in WikiText]].
+
+The key difference between substitution and transclusion is that substitution occurs before WikiText parsing. This means that you can use substitution to build WikiText constructions. Transclusions are processed independently, and cannot be combined with adjacent text to define WikiText constructions.

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

@@ -24,3 +24,7 @@ A similar syntax can be used to transclude a list of tiddlers matching a specifi
 {{{ [tag[mechanism]] }}}
 {{{ [tag[mechanism]] ||TemplateTitle}}}
 ```
+
+See also:
+
+* [[Confusion between Transclusion and Substitution]]

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

@@ -25,4 +25,4 @@ Variables are used in:
 * [[Filter expression|Introduction to Filters]] `[operator<variable-operand>]`
 * Some default behaviors of [[Widgets]]
 
-See also [[currentTiddler|WidgetVariable: currentTiddler]] variable, built-in [[variables|Variables]] and [[substitutions in WikiText|Variables, Macros and Substitutions in WikiText]]
+See also [[currentTiddler|WidgetVariable: currentTiddler]] variable, built-in [[variables|Variables]] and [[Confusion between Transclusion and Substitution]].

editions/tw5.com/tiddlers/wikitext/Variables, Macros and Substitutions in WikiText.tid

@@ -1,53 +0,0 @@
-caption: Variables, Parameters, Substitutions
-created: 20141018090608643
-modified: 20141018181414011
-tags: WikiText
-title: Variables, Macros and Substitutions in WikiText
-type: text/vnd.tiddlywiki
-
-! Syntax for Attributes
-
-The syntax for the attributes of [[HTML elements|HTML in WikiText]] and [[widgets|Widgets in WikiText]]:
-
-* `"text"`, `'text'`, `"""text"""` - passed as a literal value
-* `{{text reference}}` - [[transcludes|Transclusion in WikiText]] a text reference
-* `<<macro>>` - transcludes a variable or macro invocation
-
-! Syntax for Filters
-
-Using single brace `{...}` and `<...>` when referenced as operands in [[Filter expression|Introduction to Filters]].
-
-* Text reference as `[search{$:/temp/search}]` or `[prefix{tiddlerA!!fieldname}]`
-* Variable reference as  `[search<currentTiddler>]`
-
-! Variables and Macros
-
-[[Variables|Variables in WikiText]] and [[macros|Macros in WikiText]] are indeed the same thing. Macros are just variables that have their parameters substituted before use.
-
-! Textual Substitution
-
-* `$parametername$` - for [[macro parameters|Macros in WikiText]] 
-```
-\define mysamplemacro(name:"Bugs Bunny",address:"Rabbit Hole Hill")
-Hi, I'm $name$ and I live in $address$
-\end
-```
-
-* `$(variablename)$` - for variable substitutions ''within macros''
-```
-\define mysamplemacro2()
-Hi, I'm $(name)$ and I live in $(address)$
-\end
-
-<$set name="name" value="Bugs Bunny">
-<$set name="address" value="Rabbit Hole Hill">
-<<mysamplemacro2>>
-</$set></$set>
-```
-The difference between textual substitution and other syntax:
-
-* Textual substitution is performed before the macro is parsed, the values are inserted into the target.
-* While the `<<...>>` syntax is a transclusion, where the "WikiText" is inserted and rendered separately.
-* Textual substitution behaves as text. So that they can be combined with other text, and the usage should include all braces like :
-** `filter="[prefix[$:/$(a)$/$(b)$]]"` or 
-** `<$reveal ... text="$(c)$"> `