From 32bf9fd7a1470adb0b85df590ab3079e9ad232db Mon Sep 17 00:00:00 2001 From: Mario Pietsch Date: Wed, 13 Mar 2024 23:02:56 +0100 Subject: [PATCH 1/6] Docs - wikitext-macros new v5.3.x syntaxWikitext macros (#8059) * docs - wikitext-macros new v5.3.x syntax * fix flexcard macro wrong link --- .../tiddlers/system/wikitext-macros.tid | 116 ++++++++---------- 1 file changed, 54 insertions(+), 62 deletions(-) diff --git a/editions/tw5.com/tiddlers/system/wikitext-macros.tid b/editions/tw5.com/tiddlers/system/wikitext-macros.tid index 7db97bf50b2..c9f3177617c 100644 --- a/editions/tw5.com/tiddlers/system/wikitext-macros.tid +++ b/editions/tw5.com/tiddlers/system/wikitext-macros.tid @@ -1,104 +1,96 @@ code-body: yes created: 20150117184156000 -modified: 20220617122915793 +modified: 20240229155641000 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=<> windowTitle="Side by Side View" - width="800" height="600" /> +\procedure activateTiddlerWindow() +<$action-sendmessage $message="tm-open-window" $param=<> windowTitle="Side by Side View" width="800" height="600" /> \end -\define controlPanel-plugin-link() +\procedure controlPanel-plugin-link() <$button actions=<> class="tc-btn-invisible tc-tiddlylink"> -{{$:/core/images/options-button}} ~ControlPanel + {{$:/core/images/options-button}} ~ControlPanel \end -\define open-tiddler-in-window() +\procedure open-tiddler-in-window() +\whitespace notrim <$button actions=<> class="tc-btn-invisible tc-tiddlylink"> -open ''this'' tiddler in a new window + open ''this'' tiddler in a new window \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=<> windowName="_edition" windowFeatures="width=800 height=600" /> \end -\define open-external-window(url) -<$button actions=<> class="tc-btn-invisible tc-tiddlylink"> -open the ''example edition'' in a new window +\procedure open-external-window(url) +\whitespace notrim +<$button actions=<> class="tc-btn-invisible tc-tiddlylink"> + open the ''example edition'' in a new window \end -\define wikitext-example(src) +\procedure wikitext-example(src)
- -<$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=<>/> - + <$macrocall $name="copy-to-clipboard-above-right" src=<>/> + <$codeblock code=<>/> +

+ That renders as: +

+ <$transclude $variable="src" $mode="block"/> +

+ ... and the underlying HTML is: +

+ <$wikify name="html" text=<> output="html"> + <$codeblock code=<>/> +
\end -\define wikitext-example-without-html(src) +\procedure wikitext-example-without-html(src)
- -<$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=<>/> + <$codeblock code=<>/> +

+ That renders as: +

+ <$macrocall $name="src"/>
\end -\define wikitext-example-table-header() wiki textrenders as - -\define wikitext-example-table-row(id, code) - -<<__id__>><$codeblock code=<<__code__>>/> +\procedure wikitext-example-table-header() wiki textrenders as -<<__code__>> - +\procedure wikitext-example-table-row(id, code) + + <> + <$codeblock code=<>/> + <> \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$]]: - <> \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={{{ [get<__linkField__>else] }}}> -
!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={{{ [addprefix[tc-card ]] }}} to={{{ [getelse] }}}> +
!is[blank]addprefix[5px solid ]] }}} style.background={{!!background}} style.backgroundColor=<> style.color=<> style.fill=<>> <$list filter="[has[ribbon-text]]" variable="ignore">
get[ribbon-color]else[red]] }}}> @@ -108,21 +100,21 @@ That renders as:
- <$list filter="[has<__imageField__>]" variable="ignore"> + <$list filter="[has]" variable="ignore">
- <$image source={{{ [get<__imageField__>] }}}/> + <$image source={{{ [get] }}}/>
-
<$transclude field=<<__captionField__>>><$view field="title"/>
- <$list filter="[<__subtitle__>!is[blank]]" variable="ignore"> +
<$transclude field=<>><$view field="title"/>
+ <$list filter="[!is[blank]]" variable="ignore">
- <$text text=<<__subtitle__>>/> + <$text text=<>/>
<$transclude tiddler={{!!icon}}/>
- <$transclude field=<<__descriptionField__>> mode="block"/> + <$transclude field=<> mode="block"/>
From 8f741e8e67b49ff2d0a1128fbe10b20933de8dfc Mon Sep 17 00:00:00 2001 From: Mario Pietsch Date: Wed, 13 Mar 2024 23:06:23 +0100 Subject: [PATCH 2/6] Docs: deprecate Macro call railroad syntax (#8062) --- .../tw5.com/tiddlers/macros/syntax/Macro Call Syntax.tid | 6 +++++- .../tiddlers/macros/syntax/Macro Definition Syntax.tid | 6 +++++- 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/editions/tw5.com/tiddlers/macros/syntax/Macro Call Syntax.tid b/editions/tw5.com/tiddlers/macros/syntax/Macro Call Syntax.tid index 846200cc9ef..f070bbeac79 100644 --- a/editions/tw5.com/tiddlers/macros/syntax/Macro Call Syntax.tid +++ b/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=""" diff --git a/editions/tw5.com/tiddlers/macros/syntax/Macro Definition Syntax.tid b/editions/tw5.com/tiddlers/macros/syntax/Macro Definition Syntax.tid index 81877b3a54c..ecc389d54fc 100644 --- a/editions/tw5.com/tiddlers/macros/syntax/Macro Definition Syntax.tid +++ b/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=""" From ec0b264426d2aa915de05b543dc69f272e4f3095 Mon Sep 17 00:00:00 2001 From: Mario Pietsch Date: Wed, 13 Mar 2024 23:07:39 +0100 Subject: [PATCH 3/6] Docs: add Procedures railroad syntax description (#8061) --- .../macros/syntax/Procedure Call Syntax.tid | 33 +++++++ .../syntax/Procedure Definition Syntax.tid | 93 +++++++++++++++++++ .../macros/syntax/Procedure Syntax.tid | 11 +++ .../tiddlers/procedures/Procedures.tid | 8 +- 4 files changed, 142 insertions(+), 3 deletions(-) create mode 100644 editions/tw5.com/tiddlers/macros/syntax/Procedure Call Syntax.tid create mode 100644 editions/tw5.com/tiddlers/macros/syntax/Procedure Definition Syntax.tid create mode 100644 editions/tw5.com/tiddlers/macros/syntax/Procedure Syntax.tid diff --git a/editions/tw5.com/tiddlers/macros/syntax/Procedure Call Syntax.tid b/editions/tw5.com/tiddlers/macros/syntax/Procedure Call Syntax.tid new file mode 100644 index 00000000000..c7ab07644a2 --- /dev/null +++ b/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}}/> diff --git a/editions/tw5.com/tiddlers/macros/syntax/Procedure Definition Syntax.tid b/editions/tw5.com/tiddlers/macros/syntax/Procedure Definition Syntax.tid new file mode 100644 index 00000000000..7a621ee5971 --- /dev/null +++ b/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>>.
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. + diff --git a/editions/tw5.com/tiddlers/macros/syntax/Procedure Syntax.tid b/editions/tw5.com/tiddlers/macros/syntax/Procedure Syntax.tid new file mode 100644 index 00000000000..2ef519fcce3 --- /dev/null +++ b/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]] + +<> + +<<.tip "The railroad boxes in the linked tiddlers can be used to navigate.">> diff --git a/editions/tw5.com/tiddlers/procedures/Procedures.tid b/editions/tw5.com/tiddlers/procedures/Procedures.tid index 15b422647df..8c80e61f520 100644 --- a/editions/tw5.com/tiddlers/procedures/Procedures.tid +++ b/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 ``` <> -<> +<> ``` 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 From 3342cfc886181396ca24035a62cb8cba9394b59e Mon Sep 17 00:00:00 2001 From: Mario Pietsch Date: Wed, 13 Mar 2024 23:08:11 +0100 Subject: [PATCH 4/6] Docs: fix doubled list in: Deprecated - What does it mean (#8060) --- editions/tw5.com/tiddlers/system/Deprecated.tid | 2 +- .../tw5.com/tiddlers/system/Deprecated_-_What_does_it_mean.tid | 3 --- 2 files changed, 1 insertion(+), 4 deletions(-) diff --git a/editions/tw5.com/tiddlers/system/Deprecated.tid b/editions/tw5.com/tiddlers/system/Deprecated.tid index d363f07ed49..5a7b501e7a7 100644 --- a/editions/tw5.com/tiddlers/system/Deprecated.tid +++ b/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: <> \ No newline at end of file diff --git a/editions/tw5.com/tiddlers/system/Deprecated_-_What_does_it_mean.tid b/editions/tw5.com/tiddlers/system/Deprecated_-_What_does_it_mean.tid index 98fbf6bb0ff..891e00bca75 100644 --- a/editions/tw5.com/tiddlers/system/Deprecated_-_What_does_it_mean.tid +++ b/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`'' - -><> \ No newline at end of file From 511d480a6041199403755ea76182c32de04e76d5 Mon Sep 17 00:00:00 2001 From: Mario Pietsch Date: Fri, 15 Mar 2024 19:08:37 +0100 Subject: [PATCH 5/6] Fix wikitext-macros example block mode (#8071) --- editions/tw5.com/tiddlers/system/wikitext-macros.tid | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/editions/tw5.com/tiddlers/system/wikitext-macros.tid b/editions/tw5.com/tiddlers/system/wikitext-macros.tid index c9f3177617c..c09b0d8fe97 100644 --- a/editions/tw5.com/tiddlers/system/wikitext-macros.tid +++ b/editions/tw5.com/tiddlers/system/wikitext-macros.tid @@ -1,6 +1,6 @@ code-body: yes created: 20150117184156000 -modified: 20240229155641000 +modified: 20240315144208842 tags: $:/tags/Macro title: $:/editions/tw5.com/wikitext-macros type: text/vnd.tiddlywiki @@ -65,7 +65,7 @@ type: text/vnd.tiddlywiki

That renders as:

- <$macrocall $name="src"/> + <$transclude $variable="src" $mode="block"/>
\end From 09f04cb5a6000e86c62c5aecca303a5cd896f597 Mon Sep 17 00:00:00 2001 From: poc2go Date: Sat, 16 Mar 2024 13:33:13 -0400 Subject: [PATCH 6/6] Signing the CLA (#8077) --- licenses/cla-individual.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/licenses/cla-individual.md b/licenses/cla-individual.md index 5f7a833c338..3dafcf352cc 100644 --- a/licenses/cla-individual.md +++ b/licenses/cla-individual.md @@ -561,3 +561,5 @@ Wang Ke, @Gk0Wk, 2023/10/17 John Long, @drevarr, 2023/12/12 Ed Holsinger, @eschlon, 2024/02/08 + +Kim I. McKinley, @PotOfCoffee2Go, 2024/03/16