Merge branch 'tiddlywiki-com'

editions/tw5.com/tiddlers/macros/syntax/Macro Call Syntax.tid

@@ -1,9 +1,13 @@
 created: 20150221105732000
 modified: 20150221222352000
-tags: [[Macro Syntax]]
+tags: [[Macro Syntax]] $:/deprecated
 title: Macro Call Syntax
 type: text/vnd.tiddlywiki
 
+<<.deprecated-since "5.3.0" "Procedure Call Syntax">>
+
+----------
+
 <<.preamble """What follows is a formal presentation of the syntax of the WikiText syntax for macro calls, using [[railroad diagrams|Railroad Diagrams]]. A [[simpler overview|Macro Calls in WikiText]] is also available.""">>
 
 <$railroad text="""

editions/tw5.com/tiddlers/macros/syntax/Macro Definition Syntax.tid

@@ -1,9 +1,13 @@
 created: 20150220200255000
 modified: 20150221222349000
-tags: [[Macro Syntax]]
+tags: [[Macro Syntax]] $:/deprecated
 title: Macro Definition Syntax
 type: text/vnd.tiddlywiki
 
+<<.deprecated-since "5.3.0" "Procedure Definition Syntax">>
+
+----------
+
 <<.preamble """What follows is a formal presentation of the syntax of the `\define` pragma, using [[railroad diagrams|Railroad Diagrams]]. A [[simpler overview|Macro Definitions in WikiText]] is also available.""">>
 
 <$railroad text="""

editions/tw5.com/tiddlers/macros/syntax/Procedure Call Syntax.tid

@@ -0,0 +1,33 @@
+created: 20240310165023000
+modified: 20240310172648116
+tags: [[Procedure Syntax]]
+title: Procedure Call Syntax
+type: text/vnd.tiddlywiki
+
+<<.preamble """What follows is a formal presentation of the syntax of the WikiText syntax for procedure calls, using [[railroad diagrams|Railroad Diagrams]].""">>
+
+!! procedure-name
+
+<$railroad text="""
+"<<" [[ procedure-name |Procedures]] [: [[whitespace|"Filter Whitespace"]] [:{param-value}] ]">>"
+"""/>
+
+* The [[procedure's|Procedures]] <<.place procedure-name>> is a sequence of non-whitespace characters other than `(` or `>`.
+
+* <<.place whitespace>> denotes a sequence of [[whitespace characters|Filter Whitespace]].
+
+!!! param-value
+
+Each ''individual'' <<.place param-value>> has the following syntax:
+
+<$railroad text="""
+\start none
+\end none
+[: param-name [:[[whitespace|"Filter Whitespace"]]] ":" [:[[whitespace|"Filter Whitespace"]]] ] value [: [[whitespace|"Filter Whitespace"]] ]
+"""/>
+
+* The <<.place param-name>> is a sequence of letters (`A`--`Z`, `a`--`z`), digits (`0`--`9`), hyphens (`-`) and underscores (`_`).
+
+* The <<.place value>> is specified as follows:
+
+<$railroad text={{$:/editions/tw5.com/railroad/macro-parameter-value}}/>

editions/tw5.com/tiddlers/macros/syntax/Procedure Definition Syntax.tid

@@ -0,0 +1,93 @@
+created: 20240310165023000
+modified: 20240310175033730
+tags: [[Procedure Syntax]]
+title: Procedure Definition Syntax
+type: text/vnd.tiddlywiki
+
+<<.preamble """What follows is a formal presentation of the syntax of the [[Pragma: \procedure]], using [[railroad diagrams|Railroad Diagrams]]. """>>
+
+! \procedure
+
+There are 2 types of procedure definitions
+
+* Single line definitions
+* Multi line definitions
+
+!! Single Line
+
+Single line definitions should only be used for very short bodies, where the procedure name, params and the body fit into 1 line terminated with a line-feed.
+
+<$railroad text="""
+"\procedure"
+[[<"space">|"Filter Whitespace"]]
+"procedure-name"
+<"(params)">
+[:[[<"space">|"Filter Whitespace"]]]
+"body"
+"lf"
+"""/>
+
+!! Multi Line
+
+The majority of procedure definitions will have a body, that spans over several lines of wikitext. Those procedure definitions are terminated using the "\end" pragma
+
+<$railroad text="""
+"\procedure"
+[[<"space">|"Filter Whitespace"]]
+"procedure-name"
+<"(params)">
+[:[[<"space">|"Filter Whitespace"]]]
+body
+"\end"
+"""/>
+
+The [[procedure-name|Procedures]] is a sequence of non-whitespace characters other than `(` or `>`.
+
+
+* <<.place procedure-name>> is a sequence of letters (`A`--`Z`, `a`--`z`), digits (`0`--`9`), hyphens (`-`) and underscores (`_`)
+* <<.place body>> is wikitext including [[nested procedures|Pragma: \procedure]]
+* <<.place space>> denotes a sequence of [[whitespace characters|Filter Whitespace]]
+
+!! params
+
+The parameter declaration list <<.place (params)>> has the following syntax:
+
+<$railroad text="""
+\start none
+\end none
+"(" [:"sep"] [:{ parameter "sep" }] ")"
+"""/>
+
+* <<.place sep>> is any sequence of characters that does not match a <<.place param-name>>. <br>Among other things, this includes commas, spaces and linefeeds.
+
+
+Each ''individual'' <<.place parameter>> has the following syntax:
+
+<$railroad text="""
+\start none
+\end none
+"param-name" [: [:[[<"space">|"Filter Whitespace"]]] ":" [:[[<"space">|"Filter Whitespace"]]] default ]
+"""/>
+
+* <<.place param-name>> is a sequence of letters (`A`--`Z`, `a`--`z`), digits (`0`--`9`), hyphens (`-`) and underscores (`_`).
+
+* <<.place default>> is an optional value of a parameter is specified as follows:
+
+<$railroad text={{$:/editions/tw5.com/railroad/macro-parameter-value}}/>
+
+!! body
+
+The <<.place body>> of the definition has the following syntax:
+
+<$railroad text="""
+\start none
+\end none
+{[[<"wikitext">|WikiText]] "lf"}  
+"""/>
+
+* <<.place wikitext>> is any sequence of characters that doesn't terminate the macro definition.
+** If [[nested procedures|Pragma: \procedure]] are used they need to be at the start of the wikitext. There are the same rules as if the wikitext would be in a tiddler. 
+** Pragmas need to be before standard wikitext.
+
+* <<.place lf>> denotes a linefeed.
+

editions/tw5.com/tiddlers/macros/syntax/Procedure Syntax.tid

@@ -0,0 +1,11 @@
+created: 20240310165023000
+modified: 20240310173318213
+tags: Procedures
+title: Procedure Syntax
+type: text/vnd.tiddlywiki
+
+Plain text description can be found at [[Procedures]]
+
+<<list-links filter:"[tag[Procedure Syntax]]">>
+
+<<.tip "The railroad boxes in the linked tiddlers can be used to navigate.">>

editions/tw5.com/tiddlers/procedures/Procedures.tid

@@ -1,5 +1,5 @@
 created: 20221007124007426
-modified: 20230419103154329
+modified: 20240310173130052
 tags: Concepts Reference
 title: Procedures
 type: text/vnd.tiddlywiki
@@ -18,11 +18,13 @@ The name wrapped in double angled [[brackets|Brackets]] is used a shorthand way
 
 ```
 <<my-procedure>>
-<<my-procedure "The parameter">>
+<<my-procedure parameter:"The parameter">>
 ```
 
 The parameters that are specified in the procedure call are made available as variables.
 
+<<.tip """If a procedure has more than 1 parameter, it is highly encouraged to use "named parameters", as shown in the second example above. Even if it is more to type, it will pay off in the long run.""">>
+
 !! 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.
@@ -32,4 +34,4 @@ Procedures are implemented as a special kind of [[variable|Variables]]. The only
 * [[Procedure Definitions]] describes how to create procedures
 * [[Procedure Calls]] describes how to use procedures
 * [[Procedure Parameter Handling]] describes how procedure parameters work
-
+* [[Procedure Syntax]] is a formal syntax description using railroad diagrams

editions/tw5.com/tiddlers/system/Deprecated.tid

@@ -7,6 +7,6 @@ Deprecated features of TiddlyWiki are those that have been superseded by newer,
 
 Deprecated features will still work, but are not recommended for new content.
 
-Tiddlers tagged $:/deprecated:
+''Tiddlers tagged'' $:/deprecated:
 
 <<list-links filter:"[tag[$:/deprecated]]">>

editions/tw5.com/tiddlers/system/Deprecated_-_What_does_it_mean.tid

@@ -7,6 +7,3 @@ type: text/vnd.tiddlywiki
 
 Deprecated features are marked with a special warning button. See: [[How to apply custom styles by tag]] for an example.
 
-''Tiddlers tagged `$:/deprecated`''
-
-><<list-links "[tag[$:/deprecated]]">>

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

@@ -1,104 +1,96 @@
 code-body: yes
 created: 20150117184156000
-modified: 20220617122915793
+modified: 20240315144208842
 tags: $:/tags/Macro
 title: $:/editions/tw5.com/wikitext-macros
 type: text/vnd.tiddlywiki
 
-\define activatePluginTab()
+\whitespace trim
+
+\procedure activatePluginTab()
 <$action-setfield $tiddler="$:/state/tab-1749438307" text="$:/core/ui/ControlPanel/Plugins"/>
 <$action-navigate $to="$:/ControlPanel"/>
 \end
 
-\define activateTiddlerWindow()
-<$action-sendmessage $message="tm-open-window"
-  $param=<<currentTiddler>> windowTitle="Side by Side View"
-  width="800" height="600" />
+\procedure activateTiddlerWindow()
+<$action-sendmessage $message="tm-open-window" $param=<<currentTiddler>> windowTitle="Side by Side View" width="800" height="600" />
 \end
 
-\define controlPanel-plugin-link()
+\procedure controlPanel-plugin-link()
 <$button actions=<<activatePluginTab>> class="tc-btn-invisible tc-tiddlylink">
-{{$:/core/images/options-button}} ~ControlPanel
+	{{$:/core/images/options-button}} ~ControlPanel
 </$button>
 \end
 
-\define open-tiddler-in-window()
+\procedure open-tiddler-in-window()
+\whitespace notrim
 <$button actions=<<activateTiddlerWindow>> class="tc-btn-invisible tc-tiddlylink">
-open ''this'' tiddler in a new window
+	open ''this'' tiddler in a new window
 </$button>
 \end
 
-\define activateEditionWindow(url)
-<$action-sendmessage $message="tm-open-external-window"
-  $param="""$url$""" windowName="_edition"
-  windowFeatures="width=800 height=600" />
+\procedure activateEditionWindow(url)
+<$action-sendmessage $message="tm-open-external-window" $param=<<url>> windowName="_edition" windowFeatures="width=800 height=600" />
 \end
 
-\define open-external-window(url)
-<$button actions=<<activateEditionWindow """$url$""">> class="tc-btn-invisible tc-tiddlylink">
-open the ''example edition'' in a new window
+\procedure open-external-window(url)
+\whitespace notrim
+<$button actions=<<activateEditionWindow <<url>> class="tc-btn-invisible tc-tiddlylink">
+	open the ''example edition'' in a new window
 </$button>
 \end
 
 
-\define wikitext-example(src)
+\procedure wikitext-example(src)
 <div class="doc-example">
-
-<$macrocall $name="copy-to-clipboard-above-right" src=<<__src__>>/>
-
-<$codeblock code=<<__src__>>/>
-
-That renders as:
-
-<$macrocall $name="__src__"/>
-
-... and the underlying HTML is:
-
-<$wikify name="html" text=<<__src__>> output="html">
-<$codeblock code=<<html>>/>
-</$wikify>
+	<$macrocall $name="copy-to-clipboard-above-right" src=<<src>>/>
+	<$codeblock code=<<src>>/>
+	<p>
+		That renders as:
+	</p>
+	<$transclude $variable="src" $mode="block"/>
+	<p>
+		... and the underlying HTML is:
+	</p>
+	<$wikify name="html" text=<<src>> output="html">
+		<$codeblock code=<<html>>/>
+	</$wikify>
 </div>
 \end
 
-\define wikitext-example-without-html(src)
+\procedure wikitext-example-without-html(src)
 <div class="doc-example">
-
-<$macrocall $name="copy-to-clipboard-above-right" src=<<__src__>>/>
-
-<$codeblock code=<<__src__>>/>
-
-That renders as:
-
-<$macrocall $name="__src__"/>
-
+	<$macrocall $name="copy-to-clipboard-above-right" src=<<src>>/>
+	<$codeblock code=<<src>>/>
+	<p>
+		That renders as:
+	</p>
+	<$transclude $variable="src" $mode="block"/>
 </div>
 \end
 
-\define wikitext-example-table-header() <thead><tr><th/><th>wiki text</th><th>renders as</th></tr></thead>
-
-\define wikitext-example-table-row(id, code)
- <tr>
-<th><<__id__>></th><td><$codeblock code=<<__code__>>/></td><td>
+\procedure wikitext-example-table-header() <thead><tr><th/><th>wiki text</th><th>renders as</th></tr></thead>
 
-<<__code__>>
-</td>
+\procedure wikitext-example-table-row(id, code)
+<tr>
+	<th><<id>></th>
+	<td><$codeblock code=<<code>>/></td>
+	<td><<code>></td>
 </tr>
 \end
 
-\define tw-code(tiddler)
+\procedure tw-code(tiddler)
 <$codeblock language={{$tiddler$!!type}} code={{$tiddler$}}/>
 \end
 
-\define tw-code-link(tiddler)
+\procedure tw-code-link(tiddler)
 [[$tiddler$]]:
-
 <<tw-code $tiddler$>>
 \end
 
-\define flex-card(class,bordercolor:"",backgroundcolor:"",textcolor:"",imageField:"image",captionField:"caption",subtitle:"",descriptionField:"description",linkField:"link")
-\whitespace trim
-<$link class={{{ [<__class__>addprefix[tc-card ]] }}} to={{{ [<currentTiddler>get<__linkField__>else<currentTiddler>] }}}>
-	<div class="tc-card-accent" style.borderTop={{{ [<__bordercolor__>!is[blank]addprefix[5px solid ]] }}} style.background={{!!background}} style.backgroundColor=<<__backgroundcolor__>> style.color=<<__textcolor__>> style.fill=<<__textcolor__>>>
+\procedure flex-card(class,bordercolor:"",backgroundcolor:"",textcolor:"",imageField:"image",captionField:"caption",subtitle:"",descriptionField:"description",linkField:"link")
+<$link class={{{ [<class>addprefix[tc-card ]] }}} to={{{ [<currentTiddler>get<linkField>else<currentTiddler>] }}}>
+	<div class="tc-card-accent" style.borderTop={{{ [<bordercolor>!is[blank]addprefix[5px solid ]] }}} style.background={{!!background}} style.backgroundColor=<<backgroundcolor>> style.color=<<textcolor>> style.fill=<<textcolor>>>
 		<$list filter="[<currentTiddler>has[ribbon-text]]" variable="ignore">
 			<div class="tc-card-ribbon-wrapper">
 				<div class="tc-card-ribbon" style.backgroundColor={{{ [<currentTiddler>get[ribbon-color]else[red]] }}}>
@@ -108,21 +100,21 @@ That renders as:
 				</div>
 			</div>
 		</$list>
-		<$list filter="[<currentTiddler>has<__imageField__>]" variable="ignore">
+		<$list filter="[<currentTiddler>has<imageField>]" variable="ignore">
 			<div class="tc-card-image">
-				<$image source={{{ [<currentTiddler>get<__imageField__>] }}}/>
+				<$image source={{{ [<currentTiddler>get<imageField>] }}}/>
 			</div>
 		</$list>
-		<div class="tc-card-title"><$transclude field=<<__captionField__>>><$view field="title"/></$transclude></div>
-		<$list filter="[<__subtitle__>!is[blank]]" variable="ignore">
+		<div class="tc-card-title"><$transclude field=<<captionField>>><$view field="title"/></$transclude></div>
+		<$list filter="[<subtitle>!is[blank]]" variable="ignore">
 			<div class="tc-card-subtitle">
-				<$text text=<<__subtitle__>>/>
+				<$text text=<<subtitle>>/>
 			</div>
 		</$list>
 		<div class="tc-card-icon"><$transclude tiddler={{!!icon}}/></div>
 		<div class="tc-card-body-wrapper">
 			<div class="tc-card-body">
-				<$transclude field=<<__descriptionField__>> mode="block"/>
+				<$transclude field=<<descriptionField>> mode="block"/>
 			</div>
 			<div class="tc-card-body-clear">
 			</div>