clone/TiddlyWiki5
1
0
Fork 0
mirror of https://github.com/TiddlyWiki/TiddlyWiki5.git synced 2026-02-01 22:07:41 +00:00
Code Issues Packages Projects Releases Wiki Activity

Docs updates

Browse Source
This commit is contained in:
Jeremy Ruston
2026-01-31 13:10:02 +00:00
parent 2e89771129
commit e1625afab5
19 changed files with 178 additions and 208 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
editions/fr-FR/tiddlers/$__editions_tw5.com_railroad_macro-parameter-value.tid
View File

@@ -1,11 +1,13 @@
created: 20150220191009000
modified: 20150602092431500
title: $:/editions/tw5.com/railroad/macro-parameter-value
title: $:/editions/tw5.com/railroad/call-parameter-value
type: text/vnd.tiddlywiki.railroad
( '"""' [:{/'tout sauf """'/}] '"""'
| '"' [:{/'tout sauf "'/}] '"'
| "'" [:{/"tout sauf '"/}] "'"
| "[[" [:{/"tout sauf ]"/}] "]]"
| "`" [:{/"tout sauf `"/}] "`"
| "```" [:{/"tout sauf ```"/}] "```"
| {/"""tout sauf ' " ou espacevierge"""/}
)

2
editions/fr-FR/tiddlers/Macro_Call_Syntax.tid
View File

@@ -25,4 +25,4 @@ The <<.place param-nom>> is a sequence of letters (`A`--`Z`, `a`--`z`), digits (
The <<.place valeur>> is specified as follows<<dp>>
<$railroad text={{$:/editions/tw5.com/railroad/macro-parameter-value}}/>
<$railroad text={{$:/editions/tw5.com/railroad/call-parameter-value}}/>

2
editions/fr-FR/tiddlers/Macro_Definition_Syntax.tid
View File

@@ -33,7 +33,7 @@ parametre.nom [: [:espace] ":" [:espace] defaut ]
La valeur par <<.place défaut>> d'un paramètre est spécifiée comme suit<<:>>
<$railroad text={{$:/editions/tw5.com/railroad/macro-parameter-value}}/>
<$railroad text={{$:/editions/tw5.com/railroad/call-parameter-value}}/>
La définition de la <<.place suite>> se fait comme suit<<:>>

4
editions/tw5.com/tiddlers/filters/function.tid
View File

@@ -1,6 +1,6 @@
caption: function
created: 20220909111836951
modified: 20230419103154328
modified: 20260130210336084
op-input: a [[selection of titles|Title Selection]] passed as input to the function <<.place F>>
op-output: the [[selection of titles|Title Selection]] returned from the function <<.place F>>
op-parameter: first parameter is the [[function name|Functions]], subsequent parameters are passed to the function by position
@@ -10,7 +10,7 @@ tags: [[Filter Operators]]
title: function Operator
type: text/vnd.tiddlywiki
<<.from-version "5.3.0">> The <<.op function>> operator applies a named [[function|Functions]] to the input titles, and returns the results from the function. The function is invoked once with all of the input titles (in contrast, the [[filter Operator]] invokes its function separately for each input title).
<<.from-version "5.3.0">> The <<.op function>> operator applies a named [[function|Functions]] to the input titles, and returns the results from the function. The function is called once with all of the input titles (in contrast, the [[filter Operator]] calls its function separately for each input title).
The first parameter of the <<.op function>> operator specifies the name of the function to be called. Subsequent parameters are passed to the function.

8
editions/tw5.com/tiddlers/functions/Functions.tid
View File

@@ -16,13 +16,13 @@ Functions are usually defined with the [[Pragma: \function]]:
\end
```
Functions can be invoked in several ways:
Functions can be called in several ways:
* Using the same syntax as [[Procedure Calls]]:
* Using the [[Calls]] syntax:
** Directly transclude functions with the syntax `<<myfun param:"value">>`
** Assign functions to widget attributes with the syntax `<div class=<<myfun param:"value">>>`
* Invoke functions via the [[function Operator]] with the syntax `[function[myfun],[value],...]`
* Directly invoke functions whose names contain a period as custom filter operators with the syntax `[my.fun[value]]` or `[.myfun[value]]`
* Call functions via the [[function Operator]] with the syntax `[function[myfun],[value],...]`
* Directly call functions whose names contain a period as custom filter operators with the syntax `[my.fun[value]]` or `[.myfun[value]]`
!! How Functions Work

43
editions/tw5.com/tiddlers/macros/syntax/Call Syntax.tid Normal file
View File

@@ -0,0 +1,43 @@
created: 20240310165023000
modified: 20260125212303316
tags: [[Call Syntax]]
title: Call Syntax
type: text/vnd.tiddlywiki
<<.preamble """What follows is a formal presentation of the syntax of the WikiText syntax for procedure/function/macro calls, using [[railroad diagrams|Railroad Diagrams]].""">>
!! callee-name
<$railroad text="""
"<<" [[ callee-name |Calls]] [: [[whitespace|"Filter Whitespace"]] [:{param-value}] ]">>"
"""/>
* The <<.place callee-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
(
value
|
param-name [:space] (
":" [:space] value [: space]
|
"=" [:space] new-value [: space]
)
)
"""/>
* 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/call-parameter-value}}/>
* <<.from-version 5.4.0>> The <<.place new-value>> can either be a plain <<.place value>> or a full <<.place callee-name>> call, allowing for dynamic parameter values.

2
editions/tw5.com/tiddlers/macros/syntax/MacroParameterValue.tid → editions/tw5.com/tiddlers/macros/syntax/CallParameterValue.tid
View File

@@ -1,6 +1,6 @@
created: 20150220191009000
modified: 20260125212303316
title: $:/editions/tw5.com/railroad/macro-parameter-value
title: $:/editions/tw5.com/railroad/call-parameter-value
type: text/vnd.tiddlywiki.railroad
( '"""' [:{/'anything but """'/}] '"""'

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

@@ -1,7 +1,7 @@
created: 20150221105732000
modified: 20260125212303316
tags: [[Macro Syntax]] $:/deprecated
tags: $:/deprecated
title: Macro Call Syntax
type: text/vnd.tiddlywiki
<<.deprecated-since "5.3.0" "Procedure Call Syntax">>
<<.deprecated-since "5.3.0" "Call Syntax">>

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

@@ -37,7 +37,7 @@ param-name [: [:space] ":" [:space] default ]
The optional <<.place default>> value of a parameter is specified as follows:
<$railroad text={{$:/editions/tw5.com/railroad/macro-parameter-value}}/>
<$railroad text={{$:/editions/tw5.com/railroad/call-parameter-value}}/>
The <<.place rest>> of the definition has the following syntax:

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

@@ -1,43 +1,6 @@
created: 20240310165023000
modified: 20260125212303316
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
(
value
|
param-name [:space] (
":" [:space] value [: space]
|
"=" [:space] new-value [: space]
)
)
"""/>
* 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}}/>
* <<.from-version 5.4.0>> The <<.place new-value>> can either be a plain <<.place value>> or a full <<.place procedure-name>> call, allowing for dynamic parameter values.
<<.deprecated-since "5.4.0" "Call Syntax">>

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

@@ -1,6 +1,6 @@
created: 20240310165023000
modified: 20240310175033730
tags: [[Procedure Syntax]]
tags: [[Call Syntax]]
title: Procedure Definition Syntax
type: text/vnd.tiddlywiki
@@ -73,7 +73,7 @@ Each ''individual'' <<.place parameter>> has the following syntax:
* <<.place default>> is an optional value of a parameter is specified as follows:
<$railroad text={{$:/editions/tw5.com/railroad/macro-parameter-value}}/>
<$railroad text={{$:/editions/tw5.com/railroad/call-parameter-value}}/>
!! body

2
editions/tw5.com/tiddlers/macros/syntax/Procedure Syntax.tid
View File

@@ -6,6 +6,6 @@ type: text/vnd.tiddlywiki
Plain text description can be found at [[Procedures]]
<<list-links filter:"[tag[Procedure Syntax]]">>
<<list-links filter:"[tag[Call Syntax]]">>
<<.tip "The railroad boxes in the linked tiddlers can be used to navigate.">>

51
editions/tw5.com/tiddlers/procedures/Procedure Calls.tid
View File

@@ -1,56 +1,7 @@
caption: Procedure Calls
created: 20221007130006705
modified: 20260125212303316
tags: WikiText Procedures
title: Procedure Calls
type: text/vnd.tiddlywiki
!! Introduction
This tiddler describes the different ways in which [[procedure|Procedures]] can be called. See [[Procedure Call Syntax]] for a formal description of the syntax.
!! 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>
```
<<.deprecated-since "5.4.0" "Calls">>

4
editions/tw5.com/tiddlers/procedures/Procedures.tid
View File

@@ -33,6 +33,6 @@ Procedures are implemented as a special kind of [[variable|Variables]]. The only
!! Using Procedures
* [[Procedure Definitions]] describes how to create procedures
* [[Procedure Calls]] describes how to use procedures
* [[Calls]] describes how to use procedures
* [[Procedure Parameter Handling]] describes how procedure parameters work
* [[Procedure Syntax]] is a formal syntax description using railroad diagrams
* [[Call Syntax]] is a formal syntax description using railroad diagrams

56
editions/tw5.com/tiddlers/procedures/calls/Calls.tid Normal file
View File

@@ -0,0 +1,56 @@
caption: Calls
created: 20221007130006705
modified: 20260125212303316
tags: WikiText Procedures Functions Macros
title: Calls
type: text/vnd.tiddlywiki
!! Introduction
This tiddler describes the different ways in which [[procedures|Procedures]], [[functions|Functions]] and [[macros|Macros]] can be called. See [[Call Syntax]] for a formal description of the syntax.
!! Call Transclusion Shortcut
To perform a call, place `<<`double angle brackets`>>` around the callee name and any parameter values.
```
<<my-procedure param="This is the parameter value">>
```
By default, parameters are interpreted as being in the same order as in the definition. A parameter value can be labelled with its name and an equals sign 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]], [[function definition|Function Definitions]] or [[macro definition|Macro 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. [[Substituted Attribute Values]] enclosed in single or triple back quotes are also supported.
See the discussion about [[parser modes|WikiText parser mode: macro examples]]
!! 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 override it with a custom widget.
!! Assigning Results of Calls to Attribute Values
The text returned from a call can be directly assigned to an attribute of a widget or HTML element. The result of the call is not wikified, which means that [[parameter handling|Procedure Parameter Handling]] does not take place.
```
<div class=<<myclasses>>>
...
</div>
```
!! Using Calls in Filters
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>
```

52
editions/tw5.com/tiddlers/variables/Behaviour of called variables depends on how the variable was declared.tid Normal file
View File

@@ -0,0 +1,52 @@
created: 20230726145210484
modified: 20260130210336084
tags: [[Variable Usage]]
title: Behaviour of called variables depends on how the variable was declared
type: text/vnd.tiddlywiki
\define m1(a1) $a1$ - <<__a1__>> - <<a1>>
\procedure p1(a1) $a1$ - <<__a1__>> - <<a1>>
\function f1(a1) "$a1$" "-" [<__a1__>] ="-" [<a1>] :and[join[ ]]
Called in normal wikitext context: `<$transclude $variable=myvar/>` or `<<myvar>>`
{{Behaviour of variables called via normal wikitext}}
Called via widget attribute: `<div class=<<myvar>>/>`
{{Behaviour of variables called via widget attributes}}
Called via filter operator parameter: `[<myvar>]`
{{Behaviour of variables called via filter operator parameter}}
Called via function call in a filter expression: `[function[.myfun]]`
{{Behaviour of variables called via filter expression function call}}
!! Examples
Below is an example macro, procedure and function definition. All three forms of parameter substitution `$a1$`, `<<__a1__>>`, and `<<a1>>` are included in each definition. The output helps illustrate when each form of substitution will or will not have affect.
```
\define m1(a1) $a1$ - <<__a1__>> - <<a1>>
\procedure p1(a1) $a1$ - <<__a1__>> - <<a1>>
\function f1(a1) $a1$ "-" [<__a1__>] ="-" [<a1>] :and[join[ ]]
```
| !Variable transclusion|!output |
| `<<m1 foo>>`|<<m1 foo>>|
| `<<p1 foo>>`|<<p1 foo>>|
| `<<f1 foo>>`|<<f1 foo>>|
| !Widget attribute|!output |
| `<$text text=<<m1 foo>>/>`|<$text text=<<m1 foo>>/>|
| `<$text text=<<p1 foo>>/>`|<$text text=<<p1 foo>>/>|
| `<$text text=<<f1 foo>>/>`|<$text text=<<f1 foo>>/>|
| !Filter operator parameter|!output |
| `[<m1 foo>]`|<$text text={{{[<m1 foo>]}}}/>|
| `[<p1 foo>]`|<$text text={{{[<p1 foo>]}}}/>|
| `[<f1 foo>]`|<$text text={{{[<f1 foo>]}}}/>|
| !Function call in filter expression|!output |
| `[function[m1],[foo]]`|<$text text={{{[function[m1],[foo]]}}}/>|
| `[function[p1],[foo]]`|<$text text={{{[function[p1],[foo]]}}}/>|
| `[function[f1],[foo]]`|<$text text={{{[function[f1],[foo]]}}}/>|

52
editions/tw5.com/tiddlers/variables/Behaviour of invoked variables depends on how the variable was declared.tid
View File

@@ -1,52 +1,6 @@
created: 20230726145210484
modified: 20240619211734149
tags: [[Variable Usage]]
title: Behaviour of invoked variables depends on how the variable was declared
modified: 20260130210336084
title: Behaviour of called variables depends on how the variable was declared
type: text/vnd.tiddlywiki
\define m1(a1) $a1$ - <<__a1__>> - <<a1>>
\procedure p1(a1) $a1$ - <<__a1__>> - <<a1>>
\function f1(a1) "$a1$" "-" [<__a1__>] ="-" [<a1>] :and[join[ ]]
Invoked in normal wikitext context: `<$transclude $variable=myvar/>` or `<<myvar>>`
{{Behaviour of variables invoked via normal wikitext}}
Invoked via widget attribute: `<div class=<<myvar>>/>`
{{Behaviour of variables invoked via widget attributes}}
Invoked via filter operator parameter: `[<myvar>]`
{{Behaviour of variables invoked via filter operator parameter}}
Invoked via function call in a filter expression: `[function[.myfun]]`
{{Behaviour of variables invoked via filter expression function call}}
!! Examples
Below is an example macro, procedure and function definition. All three forms of parameter substitution `$a1$`, `<<__a1__>>`, and `<<a1>>` are included in each definition. The output helps illustrate when each form of substitution will or will not have affect.
```
\define m1(a1) $a1$ - <<__a1__>> - <<a1>>
\procedure p1(a1) $a1$ - <<__a1__>> - <<a1>>
\function f1(a1) $a1$ "-" [<__a1__>] ="-" [<a1>] :and[join[ ]]
```
| !Variable transclusion|!output |
| `<<m1 foo>>`|<<m1 foo>>|
| `<<p1 foo>>`|<<p1 foo>>|
| `<<f1 foo>>`|<<f1 foo>>|
| !Widget attribute|!output |
| `<$text text=<<m1 foo>>/>`|<$text text=<<m1 foo>>/>|
| `<$text text=<<p1 foo>>/>`|<$text text=<<p1 foo>>/>|
| `<$text text=<<f1 foo>>/>`|<$text text=<<f1 foo>>/>|
| !Filter operator parameter|!output |
| `[<m1 foo>]`|<$text text={{{[<m1 foo>]}}}/>|
| `[<p1 foo>]`|<$text text={{{[<p1 foo>]}}}/>|
| `[<f1 foo>]`|<$text text={{{[<f1 foo>]}}}/>|
| !Function call in filter expression|!output |
| `[function[m1],[foo]]`|<$text text={{{[function[m1],[foo]]}}}/>|
| `[function[p1],[foo]]`|<$text text={{{[function[p1],[foo]]}}}/>|
| `[function[f1],[foo]]`|<$text text={{{[function[f1],[foo]]}}}/>|
See [[Behaviour of called variables depends on how the variable was declared]].

2
editions/tw5.com/tiddlers/variables/Behaviour of variables invoked via filter expression function call.tid
View File

@@ -6,5 +6,5 @@ type: text/vnd.tiddlywiki
|tc-first-col-min-width|k
|!how declared|!behaviour|
|\define, <<.wlink SetWidget>>, <<.wlink LetWidget>>, <<.wlink VarsWidget>>, \procedure, \widget|Every function is a variable, but only variables defined using \function are invokable using the <<.olink function>> filter operator. Attempts to use a non-function variable is the same as if the function doesn't exist. The behavior in this case is like the identity function. All filter input is passed unchanged to the output.|
|\define, <<.wlink SetWidget>>, <<.wlink LetWidget>>, <<.wlink VarsWidget>>, \procedure, \widget|Every function is a variable, but only variables defined using \function are callable using the <<.olink function>> filter operator. Attempts to use a non-function variable is the same as if the function doesn't exist. The behavior in this case is like the identity function. All filter input is passed unchanged to the output.|
|\function|The body text of the function is treated as a filter expression and evaluated. This filter expression can itself contain a function call. Filter expressions can be factored out into functions arbitrarily deep.|

53
editions/tw5.com/tiddlers/wikitext/Macro Calls.tid
View File

@@ -1,58 +1,7 @@
caption: Macro Calls
created: 20150220182252000
modified: 20230419103154328
tags: WikiText Macros
title: Macro Calls
type: text/vnd.tiddlywiki
!! Introduction
This tiddler describes the different ways in which [[macros|Macros]] can be called.
!! Macro Call Transclusion Shortcut
To call a [[macro|Macros]], place `<<`double angle brackets`>>` around the name and any parameter values.
```
<<mymacro param:"This is the parameter value">>
```
By default, parameters are listed in the same order as in the macro's 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 [[macro definition|Macro 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.
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]].
!! Macro Calls with <<.wlink TranscludeWidget>> Widget
The shortcut syntax expands to the <<.wlink TranscludeWidget>> widget with the `$variable` attribute specifying the name of the macro to transclude.
```
<$transclude $variable="mymacro" param="This is the parameter value"/>
```
The widget itself offers greater flexibility than the shortcut syntax, including the ability to specify parameter values.
!! Assigning Macro Calls to Attribute Values
The result of a macro can be directly assigned to an attribute of a widget or HTML element. The result of the macro is not wikified, but the [[parameter substitution|Macro Parameter Handling]] is performed.
```
<div class=<<myclasses "Horizontal">>>
...
</div>
```
!! Using Macro Calls in Filters
Macro calls can be used in filters:
```
<$list filter="[<mymacro param:'value'>]">
...
</$list>
```
<<.deprecated-since "5.4.0" "Calls">>