Docs updates

editions/tw5.com/tiddlers/Custom Widgets.tid

@@ -0,0 +1,52 @@
+created: 20221007144237585
+modified: 20221007145934733
+tags: Concepts Reference
+title: Custom Widgets
+type: text/vnd.tiddlywiki
+
+!! Introduction
+
+A <<.def "custom widget">> is a special kind of [[procedure|Procedures]] that can be called using the same syntax as widgets.
+
+Custom widgets can also be used to override built-in JavaScript widgets to customise their behaviour. 
+
+!! Defining Custom Widgets
+
+Custom widgets are usually defined with the [[Pragma: \widget]]:
+
+```
+\widget $$my-widget(attribute:"Default value")
+This is the widget, and the attribute is <<attribute>>.
+\end
+```
+
+The name of the widget must start with one or two dollar signs:
+
+* A ''single dollar sign'' is used to override existing core widgets
+** for example, `$text` or `$codeblock`
+* ''Double dollar signs'' are used to define a custom widget
+** for example, `$$mywidget` or `$$acme-logger`
+
+
+ The <<.wlink "GenesisWidget">> widget  For example:
+
+
+
+
+!! Using Custom Widgets
+
+The name wrapped in double angled [[brackets|Brackets]] is used a shorthand way of [[transcluding|Transclusion]] the snippet. Each of these <<.def "procedure calls">> can supply a different set of parameters:
+
+```
+<<my-procedure>>
+<<my-procedure "The parameter">>
+```
+
+The parameters that are specified in the procedure call are made available as variables.
+
+!! How Custom Widgets Work
+
+Custom widgets are implemented as a special kind of [[variable|Variables]]. The only thing that distinguishes them from ordinary variables is the way that they can be called as a custom widget with attributes mapped to parameters.
+
+!! Using Custom Widgets
+

editions/tw5.com/tiddlers/Pragma_ _procedure.tid

@@ -0,0 +1,35 @@
+created: 20221007132845007
+modified: 20221007133003128
+tags: Pragmas
+title: Pragma: \procedure
+type: text/vnd.tiddlywiki
+
+The ''\procedure'' [[pragma|Pragmas]] is used to [[define procedures|Procedure Definitions]]. It is a shortcut syntax for the SetVariableWidget.
+
+The usual form allows procedures to span multiple lines:
+
+```
+\procedure <procedure-name>(<param-name>[:<param-default-value>],<param-name>[:<param-default-value>]...)
+<multiple-line-definition-text>
+\end
+```
+
+There is also a single line form for shorter procedures:
+
+```
+\define <procedure-name>(<param-name>[:<param-default-value>],<param-name>[:<param-default-value>]...) <single-line-definition-text>
+```
+
+The first line of the definition specifies the procedure name and any parameters. Each parameter has a name and, optionally, a default value that is used if no value is supplied on a particular call to the macro. The lines that follow contain the text of the procedure text (i.e. the snippet represented by the procedure name), until `\end` appears on a line by itself:
+
+For example:
+
+```
+
+```
+
+Alternatively, the entire definition can be presented on a single line without an `\end` marker:
+
+```
+\define sayhi(name:"Bugs Bunny") Hi, I'm $name$.
+```

editions/tw5.com/tiddlers/Procedure Calls.tid

@@ -0,0 +1,56 @@
+caption: Macro Calls
+created: 20221007130006705
+modified: 20221007130607159
+tags: WikiText Procedures
+title: Procedure Calls
+type: text/vnd.tiddlywiki
+
+!! Introduction
+
+This tiddler describes the different ways in which [[macros|Procedures]] can be called.
+
+!! Procedure Call Transclusion Shortcut
+
+To call a [[procedure|Procedures]], place `<<`double angle brackets`>>` around the name and any parameter values.
+
+```
+<<my-procedure param:"This is the parameter value">>
+```
+
+By default, parameters are listed in the same order as in the procedure definition. A parameter can be labelled with its name and a colon to allow them to be listed in a different order.
+
+If no value is specified for a parameter, the default value given for that parameter in the [[procedure definition|Procedure Definitions]] is used instead. (If no default value was defined, the parameter is blank).
+
+Each parameter value can be enclosed in `'`single quotes`'`, `"`double quotes`"`, `"""`triple double quotes`"""` or `[[`double square brackets`]]`. Triple double quotes allow a value to contain almost anything. If a value contains no spaces or single or double quotes, it requires no delimiters.
+
+See the discussion about [[parser modes|WikiText parser mode: macro examples]]
+
+!! Procedure Calls with <<.wlink TranscludeWidget>> Widget
+
+The shortcut syntax expands to the <<.wlink TranscludeWidget>> widget with the `$variable` attribute specifying the name of the procedure to transclude.
+
+```
+<$transclude $variable="my-procedure" param="This is the parameter value"/>
+```
+
+The widget itself offers greater flexibility than the shortcut syntax, including the ability to specify dynamic parameter values.
+
+!! Assigning Procedure Calls to Attribute Values
+
+The text of a procedure can be directly assigned to an attribute of a widget or HTML element. The result of the procedure is not wikified, which means that [[parameter handling|Procedure Parameter Handling]] does not take place.
+
+```
+<div class=<<myclasses>>>
+...
+</div>
+```
+
+!! Using Procedure Calls in Filters
+
+Procedure calls can be used in filters. The text is not wikified which again means that the parameters will be ignored.
+
+```
+<$list filter="[<my-procedure>]">
+...
+</$list>
+```

editions/tw5.com/tiddlers/Procedure Definitions.tid

@@ -0,0 +1,44 @@
+caption: Macro Definitions
+created: 20221007125701001
+modified: 20221007130618079
+tags: WikiText Procedures
+title: Procedure Definitions
+type: text/vnd.tiddlywiki
+
+!! Introduction
+
+This tiddler describes the different ways in which [[macros|Procedures]] can be defined.
+
+!! Procedure Definition Pragma
+
+Macros are created using the [[Pragma: \procedure]] at the start of a tiddler. The definitions are available in the rest of the tiddler that defines them, plus any tiddlers that it transcludes.
+
+```
+\define my-procedure(param)
+This is the macro text (param=<<param>>)
+\end
+```
+
+!! Procedure Definition with Set Widget
+
+Procedures are implemented as a special kind of [[variable|Variables]] and so internally are actually defined with a <<.wlink SetWidget>> widget.
+
+```
+<$set name="my-procedure" value="This is the procedure text">
+...
+</$set>
+```
+
+<<.note """that it is not currently possible to specify parameters when defining a procedure with the  <<.wlink SetWidget>> widget.""">>
+
+!! Importing Procedure Definitions
+
+The [[Pragma: \import]] or <<.wlink ImportVariablesWidget>> widget can be used to copy procedure definitions from another tiddler.
+
+!! `$:/tags/Macro` Tag
+
+Global procedures can be defined using the [[SystemTag: $:/tags/Macro]].
+
+The tag [[SystemTag: $:/tags/Macro/View]] is used to define procedures that should only be available within the main view template and the preview panel.
+
+The tag [[SystemTag: $:/tags/Macro/View/Body]] is used to define procedures that should only be available within the main view template body and the preview panel.

editions/tw5.com/tiddlers/Procedure Parameter Handling.tid

@@ -0,0 +1,25 @@
+caption: Macro Definitions
+created: 20221007130538285
+modified: 20221007130953725
+tags: WikiText Procedures
+title: Procedure Parameter Handling
+type: text/vnd.tiddlywiki
+
+!! Introduction
+
+[[Procedure|Procedures]] parameters are made available as variables when the procedure contents are wikified.
+
+!! Accessing Parameters as Variables
+
+When procedures are wikified, the parameters can be accessed as variables.
+
+For example:
+
+<$macrocall $name="wikitext-example-without-html" src="""\procedure say-hi(name,address)
+Hi, I'm <<name>> and I live in <<address>>.
+\end
+
+<<say-hi name:"Bugs" address:"Rabbit Hole Hill">>
+"""/>
+
+Accessing parameters as variables only works in procedures that are wikified and not, for example, when a procedure is used as an attribute value.

editions/tw5.com/tiddlers/Procedures.tid

@@ -0,0 +1,35 @@
+created: 20221007124007426
+modified: 20221007144806995
+tags: Concepts Reference
+title: Procedures
+type: text/vnd.tiddlywiki
+
+!! Introduction
+
+A <<.def procedure>> is a named snippet of text. They are typically defined with the [[Pragma: \procedure]]:
+
+```
+\procedure my-procedure(parameter:"Default value")
+This is the procedure, and the parameter is <<parameter>>.
+\end
+```
+
+The name wrapped in double angled [[brackets|Brackets]] is used a shorthand way of [[transcluding|Transclusion]] the snippet. Each of these <<.def "procedure calls">> can supply a different set of parameters:
+
+```
+<<my-procedure>>
+<<my-procedure "The parameter">>
+```
+
+The parameters that are specified in the procedure call are made available as variables.
+
+!! How Procedures Work
+
+Procedures are implemented as a special kind of [[variable|Variables]]. The only thing that distinguishes them from ordinary variables is the way that the parameters are handled.
+
+!! Using Procedures
+
+* [[Procedure Definitions]] describes how to create procedures
+* [[Procedure Calls]] describes how to use procedures
+* [[Procedure Parameter Handling]] describes how procedure parameters work
+

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

@@ -1,12 +1,12 @@
 created: 20140211171341271
-modified: 20220917154956636
+modified: 20221007144757675
 tags: Concepts Reference
 title: Macros
 type: text/vnd.tiddlywiki
 
 !! Introduction
 
-A <<.def macro>> is a named snippet of text. It is typically defined with the [[Pragma: \define]]:
+A <<.def macro>> is a named snippet of text. They are typically defined with the [[Pragma: \define]]:
 
 ```
 \define my-macro(parameter:"Default value")
@@ -26,11 +26,11 @@ The parameters that are specified in the macro call are substituted for special
 *  `$parameter-name$` is replaced with the value of the named parameter
 * `$(variable-name)$` is replaced with the value of the named [[variable|Variables]]).
 
-<<.from-version "5.3.0">> Macros have been superseded by [[Procedures]], [[Custom Widgets]] and [[Functions]] which together provide more robust and flexible ways to encapsulate and re-use code. It is now recommended to only use macros when textual substitution is specifically required.
+<<.from-version "5.3.0">> Macros have been [[superseded|Macro Pitfalls]] by [[Procedures]], [[Custom Widgets]] and [[Functions]] which together provide more robust and flexible ways to encapsulate and re-use code. It is now recommended to only use macros when textual substitution is specifically required.
 
 !! How Macros Work
 
-Macros are implemented as a special type of [[variable|Variables]]. The only thing that distinguishes them from ordinary variables is the way that the parameters are handled.
+Macros are implemented as a special kind of [[variable|Variables]]. The only thing that distinguishes them from ordinary variables is the way that the parameters are handled.
 
 !! Using Macros
 

editions/tw5.com/tiddlers/widgets/MacroCallWidget.tid

@@ -1,11 +1,13 @@
 caption: macrocall
 created: 20131024141900000
-modified: 20220909111836951
+modified: 20221007121724264
-tags: Widgets
+tags: Widgets $:/deprecated
 title: MacroCallWidget
 type: text/vnd.tiddlywiki
 
-<<.from-version "5.3.0">> The <<.wlink MacroCallWidget>> widget is now deprecated. While it will continue to work, users are advised to use the <<.wlink TranscludeWidget>> widget, converting the `$name` attribute to `$variable`.
+<<.deprecated-since "5.3.0" "TranscludeWidget">>
+
+The <<.wlink MacroCallWidget>> widget is deprecated. While it will continue to work, users are now advised to use the <<.wlink TranscludeWidget>> widget, converting the `$name` attribute to `$variable`.
 
 For example,
 

editions/tw5.com/tiddlers/widgets/TranscludeWidget.tid

@@ -1,6 +1,6 @@
 caption: transclude
 created: 20130824142500000
-modified: 20220917113915710
+modified: 20221007123821494
 tags: Widgets
 title: TranscludeWidget
 type: text/vnd.tiddlywiki
@@ -87,7 +87,7 @@ There are several different ways to declare parameters within a transclusion:
 * the <<.wlink ParametersWidget>> widget
 * the [[Pragma: \parameters]]
 * the [[Pragma: \procedure]] for declaring procedure
-* the [[Pragma: \widgets]] for declaring custom widgets
+* the [[Pragma: \widget]] for declaring custom widgets
 * the [[Pragma: \define]] for declaring macros
 
 An example of declaring parameters with the <<.wlink ParametersWidget>> widget:

editions/tw5.com/tiddlers/wikitext/Macro Calls.tid

@@ -1,6 +1,6 @@
 caption: Macro Calls
 created: 20150220182252000
-modified: 20220918115347941
+modified: 20221007132734417
 tags: WikiText Macros
 title: Macro Calls
 type: text/vnd.tiddlywiki
@@ -25,7 +25,7 @@ Each parameter value can be enclosed in `'`single quotes`'`, `"`double quotes`"`
 
 A more formal [[presentation|Macro Call Syntax]] of this syntax is also available.
 
-See some [[examples|Macro Calls in WikiText (Examples)]] and discussion about [[parser modes|WikiText parser mode: macro examples]]
+See some [[examples|Macro Calls in WikiText (Examples)]] and discussion about [[parser modes|WikiText parser mode: macro examples]].
 
 !! Macro Calls with <<.wlink TranscludeWidget>> Widget