Overhaul the macro and variable documentation #1519

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

@@ -1,79 +1,36 @@
 caption: Variables
 created: 20141002141231992
-modified: 20150117152625000
+modified: 20150221221850000
 tags: WikiText
 title: Variables in WikiText
 type: text/vnd.tiddlywiki
 
-\define tags() {{!!tags}}
+See also the [[introduction to the concept of variables|Variables]].
 
-[[Variables]] contain values. They are available within the scope of the [[widget|Widgets]] in which they are defined, as well as all child widgets in the widget tree.
+To transclude the value of a variable, use the [[macro call syntax|Macro Calls in WikiText]] with no parameters. You can also use a <<.wlink MacroCallWidget>> widget.
 
-!!Defining Variables
+A [[macro|Macros]] snippet can contain `$(name$)` as a [[placeholder|Macro Definitions in WikiText]] for which the value of the variable of that name will be substituted.
 
-Variables are defined by...
+A variable's value can be used as a [[filter parameter|Filter Parameter]], or as a [[widget attribute|Widgets in WikiText]]. The latter supports macro parameters.
 
-; [[Macros|Macros in WikiText]]
-: in fact, variables are macro shorthands (see example below)
-; SetWidget
-: sets a variable to a value
-; ListWidget
-: sets list-item and iterator variabes
-; TiddlyWiki
-: in the core and core templates
+!! Example: defining a variable
 
-!!Using Variables
+<$macrocall $name=".example" n="1"
+eg="""<$set name=animal value=zebra>
+<<animal>>
+</$set>"""/>
 
-Variables are used...
+!! Example: defining a macro
 
-; via shorthand
-:`<<variableName>>`
-; via variable substitution within [[macros|Macros]]
-:`$(variableName)$`
-; as parameters to [[filter steps|Filters]]
-: `[operator<variableName>]`
-; in [[widgets|Widgets]]
-: internally, or as widget attributes
-: `<$edit tiddler=<<currentTiddler>>/>`
+The `\define` pragma below [[defines a macro|Macros in WikiText]] called <<.var tags>>. The macro returns the value of the tiddler's <<.field tags>> field, and can be accessed from anywhere else in the same tiddler (or in any tiddler that [[imports|ImportVariablesWidget]] it).
 
-!! Examples
+<$importvariables filter="$:/editions/tw5.com/macro-examples/tags-of-current-tiddler">
+<$codeblock code={{$:/editions/tw5.com/macro-examples/tags-of-current-tiddler}}/>
+<$macrocall $name=".example" n="2" eg="""The tags are: <<tags-of-current-tiddler>>"""/>
+</$importvariables>
 
-''defining a variable via SetWidget''
+!! Example: using a variable as a filter parameter
 
-```
-<$set name=foo value=bar>
-<<foo>>
-</$set>
-```
+This example uses the <<.olink backlinks>> [[operator|Filter Operators]] to list all tiddlers that link to this one.
 
-<<<
-<$set name=foo value=bar>
-<<foo>>
-</$set>
-<<<
-
-''a variable is a macro''
-
-Below, the `\define` pragma at the beginning of a tiddler [[defines the macro|Macros in WikiText]] `<<tags>>`, valid in the scope of the CurrentTiddler, returning the value of the standard `tags` field.
-
-```
-\define tags() {{!!tags}}
-
-<<tags>>
-```
-
-<<<
-<<tags>>
-<<<
-
-''using a filter variable to get all incoming links''
-
-Using the <<olink backlinks>> [[filter operator|Filter Operators]] to get all tiddlers linking to this one...
-
-```
-<<list-links filter:"[<currentTiddler>backlinks[]]">>
-```
-
-<<<
-<<list-links filter:"[<currentTiddler>backlinks[]]">>
-<<<
+<$macrocall $name=".example" n="3" eg="""<<list-links filter:"[<currentTiddler>backlinks[]]">>"""/>