Merge pull request #1334 from tobibeer/variable-documentation

updates to variable documentation

editions/tw5.com/tiddlers/concepts/Macros.tid

@@ -1,18 +1,17 @@
 created: 20140211171341271
-modified: 20140910215504098
+modified: 20150107121000000
 tags: Concepts Reference
 title: Macros
 type: text/vnd.tiddlywiki
 
-Macros are snippets of text that can be inserted with a concise shortcut:
+Macros are snippets of text, inserted with the following shortcut syntax:
 
 ```
 <<myMacro>>
 ```
 
-You can write your own [[Macros in WikiText]] or for more flexibility you can write [[JavaScript Macros|http://tiddlywiki.com/dev/index.html#JavaScript%20Macros]].
+You can define and use [[Macros in WikiText]] or write [[JavaScript Macros|http://tiddlywiki.com/dev/index.html#JavaScript%20Macros]] for more flexibility.
 
-The following macros are built-in to the TiddlyWiki core:
+The following macros are provided by the TiddlyWiki core:
 
 <<list-links "[tag[Macros]]">>
-

editions/tw5.com/tiddlers/macros/DumpVariablesMacro.tid

@@ -1,28 +1,20 @@
 created: 20140908104107181
-modified: 20140908104107181
+modified: 20150107121000000
 tags: Macros
 title: DumpVariablesMacro
 type: text/vnd.tiddlywiki
 caption: dumpvariables
 
-The dumpvariables macro displays a table containing the values of all the variables defined at that location in the widget tree. It can be useful for exploring the mechanisms of TiddlyWiki and for debugging.
+The ''dumpvariables'' [[macro|Macros]] displays a table with values of all [[variables|Variables]] that are defined in the current scope. It is useful for debugging and exploring TiddlyWiki internals.
 
-! Parameters
+''Note:'' Parameters and variable subsitutions for macros are displayed as empty strings. A macro defined as `\define myMacro(text) ''$text$''` thus displays as `''''`.
-
-The dumpvariables macro does not require any parameters
-
-! Examples
 
+!! Example
 
 ```
 <<dumpvariables>>
 ```
 
-Returns:
+Renders as:
 
 <<dumpvariables>>
-
-The results returned by the dumpvariables macro will depend upon where it is used.
-
-Note that the values displayed for macros are displayed with all the parameters and variable subsitutions set to an empty string. So, a macro defined as `\define myMacro(text) ''$text$''` will display as `''''`.
-

editions/tw5.com/tiddlers/variables/Variables.tid

@@ -1,15 +1,13 @@
 created: 20141002133113496
-modified: 20141002230631361
+modified: 20150107121000000
 tags: Reference
 title: Variables
 type: text/vnd.tiddlywiki
 
-Variables together with [[Widgets]] and [[Macros]] are essential for dynamic WikiText.
+[[Variables]] are an essential component of dynamic WikiText, as are [[Widgets]] and [[Macros]]. In fact, a variable is a shorthand of a macro.
 
-You can define your own [[Variables in WikiText]] or use built-in variables.
+You can define custom [[Variables in WikiText]] or use one of the standard variables...
-
-More detailed information of built-in variables could be found in below:
 
 <<list-links "[tag[Variables]]">>
 
-See also DumpVariablesMacro
+The [[<<dumpvariables>>|DumpVariablesMacro]] macro lists all variables defined in the current scope, allowing you to see and edit their values.

editions/tw5.com/tiddlers/variables/WidgetVariable_ currentTiddler.tid

@@ -1,22 +1,41 @@
 caption: currentTiddler
 created: 20141001232824187
-modified: 20141002161518301
+modified: 20150107121000000
 tags: Variables
 title: WidgetVariable: currentTiddler
 type: text/vnd.tiddlywiki
 
-! Mechanism
+The ''currentTiddler'' [[variable|Variables]] contains the title of the current tiddler. 
 
-The ''currentTiddler'' variable contains the title of the current tiddler. 
+!! Usage
 
-The ListWidget assigns the list result to the ''currentTiddler'' variable, unless the `variable` attribute is specified.
+Various [[Widgets]] and [[Macros]] are by default applied with respect to the tiddler referenced via ''currentTiddler''. Within the [[ListWidget]] or TemplateTiddlers you are thus often not required to specify the tiddler title.
 
-A couple of [[Widgets]] and [[Macros]] by default apply to the tiddler according to the ''currentTiddler'' variable. 
+The following two examples are thus equivalent...
 
-The TranscludeWidget (or WikiText `{{||TemplateTitle}}`) transcludes a tiddler without changing the ''currentTiddler'' variable.
+* `<$view field=title/>`
+* `<$view field=title tiddler=<<currentTiddler>>/>`
 
-! Using currentTiddler Variable
+;TranscludeWidget
+: when [[transcluding|Transclusion]] a tiddler, ''currentTiddler'' is set to the tiddler being transcluded,
+: e.g. when using the [[WikiText shorthand|Transclusion in WikiText]]: `{{||TemplateTiddlerTitle}}`
+; ListWidget
+: overrides the ''currentTiddler'' variable with the currently iterated list-item,
+: unless a custom `variable` attribute is specified
+; TiddlerWidget
+: sets the ''currentTiddler'' variable for its inner scope
 
-These mechanisms together allow you to write references like `<$view field="title" format="link"/>` in TemplateTiddlers or inside the ListWidget hierarchy without explicitly specifying the tiddler that it applies to.
+!! Example
 
-See also [[WidgetVariable: storyTiddler]] and [[WidgetVariable: currentTiddler]]
+```
+<$view tiddler=<<currentTiddler>> field=title/>
+```
+
+<<<
+<$view tiddler=<<currentTiddler>> field=title/>
+<<<
+
+!! Other Standard Variables
+
+* [[WidgetVariable: storyTiddler]]
+* [[WidgetVariable: transclusion]]

editions/tw5.com/tiddlers/variables/WidgetVariable_ storyTiddler.tid

@@ -1,10 +1,23 @@
 caption: storyTiddler
 created: 20141001232753952
-modified: 20141002133957245
+modified: 20150107121000000
 tags: Variables
 title: WidgetVariable: storyTiddler
 type: text/vnd.tiddlywiki
 
-The ''storyTiddler'' variable is set by the  [[default viewtemplate|$:/core/ui/ViewTemplate]] to the name of the current tiddler within tiddlers in the story river, and is not defined within the sidebar.
+The ''storyTiddler'' [[variable|Variables]] is set by the [[default view-template|$:/core/ui/ViewTemplate]] to the title of the tiddler in the story river. It is therefore undefined in elements like the ''sidebar''.
 
-See also [[WidgetVariable: currentTiddler]]
+!! Example
+
+```
+<$view tiddler=<<storyTiddler>> field=title/>
+```
+
+<<<
+<$view tiddler=<<storyTiddler>> field=title/>
+<<<
+
+!! Other Standard Variables
+
+* [[WidgetVariable: currentTiddler]]
+* [[WidgetVariable: transclusion]]

editions/tw5.com/tiddlers/variables/WidgetVariable_ transclusion.tid

@@ -1,36 +1,46 @@
 caption: transclusion
 created: 20141002004621385
-modified: 20141002162057822
+modified: 20150107121000000
 tags: Variables
 title: WidgetVariable: transclusion
 type: text/vnd.tiddlywiki
 
-! Mechanism 
+The ''transclusion'' [[variable|Variables]] is automatically set by the TranscludeWidget to contain a string identifying the position of the current node within the widget tree.
-The ''transclusion'' variable is set automatically by the transclude widget to contain a string that identifies the position of the current node within the widget tree. In the sidebar it is set to `{|$:/core/ui/PageTemplate/sidebar|||}` and within the tiddler "HelloThere" in the story river it is set to `{HelloThere|HelloThere|||}`. Each nested level of transclusion appends another curly bracketed list of symbols.
 
-The QualifyMacro uses the ''transclusion'' variable to identify the stack of transcluded tiddlers.
+With the ''transclusion'' variable, the QualifyMacro identifies the stack of transcluded tiddlers.
 
-! Example
+In the sidebar, the ''transclusion'' variable is set to:<br>
+`{|$:/core/ui/PageTemplate/sidebar|||}`
+
+When the tiddler "HelloThere" is displayed in the story river ''transclusion'' is set to:<br> `{HelloThere|HelloThere|||}`
+
+Each nested level of transclusion appends another curly bracketed list of symbols.
+
+!! Example
+
+''identifying if we're in the sidebar or not''
 
 ```
 \define mymacro()
-Hello from mymacro
+We are
-<$list filter="[<transclusion>prefix[{|$:/core/ui/PageTemplate/sidebar|||}]]" emptyMessage="in a tiddler">
+<$list
-	in the sidebar
+filter="[<transclusion>prefix[{|$:/core/ui/PageTemplate/sidebar|||}]]"
+emptyMessage="in the story river.">
+in the sidebar.
 </$list>
 \end
 
 <<mymacro>>
 ```
 
-Result in story tiddler
+Result in a story tiddler:
 
-```
+<<<
-Hello from mymacro in a tiddler
+We are in the story river.
-```
+<<<
 
-Result in the sidebar
+Result in the sidebar:
 
-```
+<<<
-Hello from mymacro in the sidebar
+We are in the sidebar.
-```
+<<<

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

@@ -1,28 +1,79 @@
 caption: Variables
 created: 20141002141231992
-modified: 20141018104313995
+modified: 20150107121000000
 tags: WikiText
 title: Variables in WikiText
 type: text/vnd.tiddlywiki
 
-! Defining Variables
+\define tags() {{!!tags}}
-Variables contains values defined by [[Widgets]].
-Variables are available within the widget that defines them, and the child widgets in the widget tree.
 
-Variables are defined by:
+[[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.
 
-* TiddlyWiki core and viewtemplate
+!!Defining Variables
-* SetWidget
-* ListWidget
-* [[Macro definition|Macros in WikiText]]
 
-! Using Variables
+Variables are defined by...
 
-Variables are used in:
+; [[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
 
-* Variable substitution `$(name)$`
+!!Using Variables
-* Concise shortcut  `<<name>>`
-* [[Filter expression|Introduction to Filters]] `[operator<variable-operand>]`
-* Some default behaviors of [[Widgets]]
 
-See also [[currentTiddler|WidgetVariable: currentTiddler]] variable, built-in [[variables|Variables]] and [[Confusion between Transclusion and Substitution]].
+Variables are used via...
+
+; shorthand
+:`<<variableName>>`
+; variable substitution within [[macros|Macros]]
+:`$(variableName)$`
+; as variable operands in [[filter expressions|Introduction to Filters]]
+: `[operator<variableName>]`
+; in [[widgets|Widgets]]
+: internally, or as widget attributes
+: `<$edit tiddler=<<currentTiddler>>/>`
+
+!! Examples
+
+''defining a variable via SetWidget''
+
+```
+<$set name=foo value=bar>
+<<foo>>
+</$set>
+```
+
+<<<
+<$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 [[backlinks|FilterOperator: backlinks]] [[filter operator|FilterOperators]] to get all tiddlers linking to this one...
+
+```
+<<list-links filter:"[<currentTiddler>backlinks[]]">>
+```
+
+<<<
+<<list-links filter:"[<currentTiddler>backlinks[]]">>
+<<<