From c3589357bf6145ba25e6c19d252cdf37a4d8679f Mon Sep 17 00:00:00 2001 From: "jeremy@jermolene.com" Date: Wed, 21 Sep 2022 10:41:03 +0100 Subject: [PATCH] Huge Documentation Update Not quite finished, but definitely on the home stretch --- .../tiddlers/{ => concepts}/Brackets.tid | 4 +- editions/tw5.com/tiddlers/concepts/Macros.tid | 39 +++++---- editions/tw5.com/tiddlers/concepts/Pragma.tid | 19 +---- .../tiddlers/features/StartupActions.tid | 4 +- .../tiddlers/howtos/Visible Transclusions.tid | 2 + .../tiddlers/pragmas/Pragma_ _define.tid | 19 +++++ .../tiddlers/pragmas/Pragma_ _import.tid | 8 ++ .../tiddlers/pragmas/Pragma_ _parameters.tid | 7 ++ .../tiddlers/pragmas/Pragma_ _rules.tid | 7 ++ .../tiddlers/pragmas/Pragma_ _whitespace.tid | 10 +++ editions/tw5.com/tiddlers/pragmas/Pragmas.tid | 13 +++ .../widgets/ImportVariablesWidget.tid | 4 +- .../tiddlers/widgets/ParametersWidget.tid | 8 +- .../tiddlers/widgets/TranscludeWidget.tid | 12 +-- .../tiddlers/wikitext/HTML in WikiText.tid | 6 +- .../wikitext/Macro Calls in WikiText.tid | 26 +----- .../tw5.com/tiddlers/wikitext/Macro Calls.tid | 58 ++++++++++++++ .../Macro Definitions in WikiText.tid | 79 +------------------ .../tiddlers/wikitext/Macro Definitions.tid | 52 ++++++++++++ .../wikitext/Macro Parameter Handling.tid | 77 ++++++++++++++++++ .../tiddlers/wikitext/Macro Pitfalls.tid | 39 +++++++++ .../tiddlers/wikitext/Macros in WikiText.tid | 11 +-- .../Transclusion and Substitution.tid | 4 +- .../wikitext/Transclusion in WikiText.tid | 6 +- .../wikitext/Variables in WikiText.tid | 6 +- .../wikitext/parser/Inline Mode WikiText.tid | 6 +- ...aces where the parser ignores WikiText.tid | 8 +- .../wikitext/parser/WikiText Parser Modes.tid | 4 +- .../WikiText parser mode transitions.tid | 6 +- .../WikiText parser mode_ macro examples.tid | 4 +- 30 files changed, 374 insertions(+), 174 deletions(-) rename editions/tw5.com/tiddlers/{ => concepts}/Brackets.tid (87%) create mode 100644 editions/tw5.com/tiddlers/pragmas/Pragma_ _define.tid create mode 100644 editions/tw5.com/tiddlers/pragmas/Pragma_ _import.tid create mode 100644 editions/tw5.com/tiddlers/pragmas/Pragma_ _parameters.tid create mode 100644 editions/tw5.com/tiddlers/pragmas/Pragma_ _rules.tid create mode 100644 editions/tw5.com/tiddlers/pragmas/Pragma_ _whitespace.tid create mode 100644 editions/tw5.com/tiddlers/pragmas/Pragmas.tid create mode 100644 editions/tw5.com/tiddlers/wikitext/Macro Calls.tid create mode 100644 editions/tw5.com/tiddlers/wikitext/Macro Definitions.tid create mode 100644 editions/tw5.com/tiddlers/wikitext/Macro Parameter Handling.tid create mode 100644 editions/tw5.com/tiddlers/wikitext/Macro Pitfalls.tid diff --git a/editions/tw5.com/tiddlers/Brackets.tid b/editions/tw5.com/tiddlers/concepts/Brackets.tid similarity index 87% rename from editions/tw5.com/tiddlers/Brackets.tid rename to editions/tw5.com/tiddlers/concepts/Brackets.tid index 529adb17e..d1299f937 100644 --- a/editions/tw5.com/tiddlers/Brackets.tid +++ b/editions/tw5.com/tiddlers/concepts/Brackets.tid @@ -1,5 +1,5 @@ created: 20220728145925343 -modified: 20220728150440771 +modified: 20220917073942912 tags: Definitions title: Brackets type: text/vnd.tiddlywiki @@ -10,5 +10,5 @@ WikiText syntax uses a number of different types of brackets. Their names are sh |`()` |Round brackets |Parenthesis |Not used in WikiText | |`[]` |Square brackets |Brackets |[[Links|Linking in WikiText]], [[Filters|Filters]] | |`{}` |Curly brackets |Braces |[[Text references|TextReference]], [[Filtered attributes|HTML in WikiText]] | -|`<>` |Angle brackets |Chevrons |[[HTML elements and widgets|HTML in WikiText]], [[Macros|Macros in WikiText]] | +|`<>` |Angle brackets |Chevrons |[[HTML elements and widgets|HTML in WikiText]], [[Macros]] | diff --git a/editions/tw5.com/tiddlers/concepts/Macros.tid b/editions/tw5.com/tiddlers/concepts/Macros.tid index 1d06f9755..ead9fdfc0 100644 --- a/editions/tw5.com/tiddlers/concepts/Macros.tid +++ b/editions/tw5.com/tiddlers/concepts/Macros.tid @@ -1,31 +1,42 @@ created: 20140211171341271 -modified: 20220505082754270 +modified: 20220917154956636 tags: Concepts Reference title: Macros type: text/vnd.tiddlywiki -A <<.def macro>> is a named snippet of text. WikiText can use the name as a shorthand way of [[transcluding|Transclusion]] the snippet. Such transclusions are known as <<.def "macro calls">>, and each call can supply a different set of parameters that get substituted for special placeholders within the snippet. +!! Introduction -For the syntax, see [[Macros in WikiText]]. +A <<.def macro>> is a named snippet of text. It is typically defined with the [[Pragma: \define]]: -Most macros are in fact just parameterised [[variables|Variables]]. +``` +\define my-macro(parameter:"Default value") +This is the macro, and the parameter is $parameter$. +\end +``` -They are created using the `\define` [[pragma|Pragma]]. (Behind the scenes, this is transformed into a <<.wlink SetWidget>>, i.e. macros and variables are two sides of the same coin.) +The name wrapped in double angled [[brackets|Brackets]] is used a shorthand way of [[transcluding|Transclusion]] the snippet. Such transclusions are known as <<.def "macro calls">>, and each call can supply a different set of parameters: -The snippet and its incoming parameter values are treated as simple strings of characters with no WikiText meaning, at least until the placeholders have been filled in and the macro call has returned. This means that a macro can assemble and return the complete syntax of a ~WikiText component, such as a [[link|Linking in WikiText]]. (See [[Transclusion and Substitution]] for further discussion of this.) +``` +<> +<> +``` -Within a snippet itself, the only markup detected is `$name$` (a placeholder for a macro parameter) and `$(name)$` (a placeholder for a [[variable|Variables]]). +The parameters that are specified in the macro call are substituted for special placeholders within the snippet: -The <<.mlink dumpvariables>> macro lists all variables (including macros) that are available at that position in the widget tree. +* `$parameter-name$` is replaced with the value of the named parameter +* `$(variable-name)$` is replaced with the value of the named [[variable|Variables]]). -An <<.wlink ImportVariablesWidget>> widget can be used to copy macro definitions to another branch of the [[widget tree|Widgets]]. ~TiddlyWiki uses this technique internally to implement global macros -- namely any macros defined in tiddlers with the <<.tag $:/tags/Macro>> tag. +<<.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. -The tag <<.tag $:/tags/Macro/View>> is used to define macros that should only be available within the main view template and the preview panel. +!! How Macros Work -The tag <<.tag $:/tags/Macro/View/Body>> is used to define macros that should only be available within the main view template body and the preview panel. +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. -For maximum flexibility, macros can also be <<.js-macro-link "written as JavaScript modules">>. +!! Using Macros -A similar effect to a parameterised macro call can be produced by setting [[variables|Variables]] around a [[transclusion|Transclusion]]. +* [[Macro Definitions]] describes how to create macros +* [[Macro Calls]] describes how to use macros +* [[Macro Parameter Handling]] describes how macro parameters work +* [[Macro Pitfalls]] describes some of the pitfalls of using macros +* [[Core Macros]] lists the built-in core macros -~TiddlyWiki's core has [[several macros|Core Macros]] built in. diff --git a/editions/tw5.com/tiddlers/concepts/Pragma.tid b/editions/tw5.com/tiddlers/concepts/Pragma.tid index 05a29a2cc..cb9d4421b 100644 --- a/editions/tw5.com/tiddlers/concepts/Pragma.tid +++ b/editions/tw5.com/tiddlers/concepts/Pragma.tid @@ -1,20 +1,7 @@ created: 20150219175930000 -modified: 20220122182842041 -tags: Concepts [[WikiText Parser Modes]] +modified: 20220917112448488 +tags: title: Pragma type: text/vnd.tiddlywiki -A <<.def pragma>> is a special component of WikiText that provides control over the way the remaining text is parsed. - -Pragmas occupy lines that start with `\`. They can only appear at the start of the text, but blank lines are allowed between them. If a pragma line appears in the main body of the text, it is treated as if it was ordinary text. - -The following pragmas are available: - -;`\define` -: for defining a [[macro|Macros]] -;`\rules` -: for adjusting the set of rules used to parse the text -;`\whitespace trim` or `\whitespace notrim` -: <<.from-version "5.1.15">> Control whether whitespace is trimmed from the start and end of text runs (the default is ''notrim''). This setting can be useful when the whitespace generated by linebreaks disturbs formatting -;`\import ` -: <<.from-version "5.1.18">> for importing macro definitions from tiddlers identified by a filter expression +See [[Pragmas]]. diff --git a/editions/tw5.com/tiddlers/features/StartupActions.tid b/editions/tw5.com/tiddlers/features/StartupActions.tid index 79a23b3d9..97be188ac 100644 --- a/editions/tw5.com/tiddlers/features/StartupActions.tid +++ b/editions/tw5.com/tiddlers/features/StartupActions.tid @@ -1,5 +1,5 @@ created: 20180323092308399 -modified: 20201025161723719 +modified: 20220917113816093 tags: Features title: StartupActions type: text/vnd.tiddlywiki @@ -33,7 +33,7 @@ The initial startup actions are useful for customising TiddlyWiki according to e <$action-setfield $tiddler="$:/language" text={{{ [[$:/languages/en-GB]] [plugin-type[language]sort[description]removeprefix[$:/languages/]] +[prefix{$:/info/browser/language}] ~[[en-GB]] +[addprefix[$:/languages/]] }}}/> ``` -Note that global macros are not available within initial startup action tiddlers by default. If you need to access them then you'll need to explicitly include them with an ''import'' [[pragma|Pragma]] at the top of the tiddler: +Note that global macros are not available within initial startup action tiddlers by default. If you need to access them then you'll need to explicitly include them with an [[Pragma: \import]] at the top of the tiddler: ``` \import [[$:/core/ui/PageMacros]] [all[shadows+tiddlers]tag[$:/tags/Macro]!has[draft.of]] diff --git a/editions/tw5.com/tiddlers/howtos/Visible Transclusions.tid b/editions/tw5.com/tiddlers/howtos/Visible Transclusions.tid index 6b7d26024..848220f37 100644 --- a/editions/tw5.com/tiddlers/howtos/Visible Transclusions.tid +++ b/editions/tw5.com/tiddlers/howtos/Visible Transclusions.tid @@ -1,5 +1,7 @@ title: Visible Transclusions tags: Learning +created: 20220909111836951 +modified: 20220909111836951 !! Visible Transclusions diff --git a/editions/tw5.com/tiddlers/pragmas/Pragma_ _define.tid b/editions/tw5.com/tiddlers/pragmas/Pragma_ _define.tid new file mode 100644 index 000000000..4f8208720 --- /dev/null +++ b/editions/tw5.com/tiddlers/pragmas/Pragma_ _define.tid @@ -0,0 +1,19 @@ +created: 20220917112233317 +modified: 20220917155832411 +tags: Pragmas +title: Pragma: \define +type: text/vnd.tiddlywiki + +The ''\define'' [[pragma|Pragmas]] + +The first line of the definition specifies the macro 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 macro text (i.e. the snippet represented by the macro name), until `\end` appears on a line by itself: + +<$codeblock code={{$:/editions/tw5.com/macro-examples/say-hi}}/> + +Alternatively, the entire definition can be presented on a single line without an `\end` marker: + +``` +\define sayhi(name:"Bugs Bunny") Hi, I'm $name$. +``` + +A more formal [[presentation|Macro Definition Syntax]] of this syntax is also available. diff --git a/editions/tw5.com/tiddlers/pragmas/Pragma_ _import.tid b/editions/tw5.com/tiddlers/pragmas/Pragma_ _import.tid new file mode 100644 index 000000000..e82b769b0 --- /dev/null +++ b/editions/tw5.com/tiddlers/pragmas/Pragma_ _import.tid @@ -0,0 +1,8 @@ +created: 20220917113054582 +modified: 20220917113329624 +tags: Pragmas +title: Pragma: \import +type: text/vnd.tiddlywiki + +The ''\import'' [[pragma|Pragmas]] + diff --git a/editions/tw5.com/tiddlers/pragmas/Pragma_ _parameters.tid b/editions/tw5.com/tiddlers/pragmas/Pragma_ _parameters.tid new file mode 100644 index 000000000..8a1ed5f12 --- /dev/null +++ b/editions/tw5.com/tiddlers/pragmas/Pragma_ _parameters.tid @@ -0,0 +1,7 @@ +created: 20220917113154900 +modified: 20220917113205051 +tags: Pragmas +title: Pragma: \parameters +type: text/vnd.tiddlywiki + +The ''\parameters'' [[pragma|Pragmas]] \ No newline at end of file diff --git a/editions/tw5.com/tiddlers/pragmas/Pragma_ _rules.tid b/editions/tw5.com/tiddlers/pragmas/Pragma_ _rules.tid new file mode 100644 index 000000000..b6c8f0671 --- /dev/null +++ b/editions/tw5.com/tiddlers/pragmas/Pragma_ _rules.tid @@ -0,0 +1,7 @@ +created: 20220917112931273 +modified: 20220917113254747 +tags: Pragmas +title: Pragma: \rules +type: text/vnd.tiddlywiki + +The ''\rules'' [[pragma|Pragmas]] adjusts the set of rules used to parse the remaining text. \ No newline at end of file diff --git a/editions/tw5.com/tiddlers/pragmas/Pragma_ _whitespace.tid b/editions/tw5.com/tiddlers/pragmas/Pragma_ _whitespace.tid new file mode 100644 index 000000000..7c5d4d471 --- /dev/null +++ b/editions/tw5.com/tiddlers/pragmas/Pragma_ _whitespace.tid @@ -0,0 +1,10 @@ +created: 20220917113002350 +modified: 20220917113304284 +tags: Pragmas +title: Pragma: \whitespace +type: text/vnd.tiddlywiki + +The ''\whitespace'' [[pragma|Pragmas]] + +;`\whitespace trim` or `\whitespace notrim` +: <<.from-version "5.1.15">> Control whether whitespace is trimmed from the start and end of text runs (the default is ''notrim''). This setting can be useful when the whitespace generated by linebreaks disturbs formatting diff --git a/editions/tw5.com/tiddlers/pragmas/Pragmas.tid b/editions/tw5.com/tiddlers/pragmas/Pragmas.tid new file mode 100644 index 000000000..b510c616a --- /dev/null +++ b/editions/tw5.com/tiddlers/pragmas/Pragmas.tid @@ -0,0 +1,13 @@ +created: 20220917112416666 +modified: 20220917154414837 +tags: Concepts [[WikiText Parser Modes]] +title: Pragmas +type: text/vnd.tiddlywiki + +A <<.def pragma>> is a special component of WikiText that provides control over the way the remaining text is parsed. + +Pragmas occupy lines that start with `\`. They can only appear at the start of the text of a tiddler, but blank lines and comments are allowed between them. If a pragma appears in the main body of the text, it is treated as if it was ordinary text. + +The following pragmas are available: + +<> diff --git a/editions/tw5.com/tiddlers/widgets/ImportVariablesWidget.tid b/editions/tw5.com/tiddlers/widgets/ImportVariablesWidget.tid index a9451bc63..02fbb75c6 100644 --- a/editions/tw5.com/tiddlers/widgets/ImportVariablesWidget.tid +++ b/editions/tw5.com/tiddlers/widgets/ImportVariablesWidget.tid @@ -1,6 +1,6 @@ caption: importvariables created: 20140612142500000 -modified: 20180928150043777 +modified: 20220917113605771 tags: Widgets title: ImportVariablesWidget type: text/vnd.tiddlywiki @@ -34,7 +34,7 @@ So-called global macros are implemented within the main page template ([[$:/core ! `\import` Pragma -<<.from-version "5.1.18">> The `\import` [[pragma|Pragma]] is an alternative syntax for using the ImportVariablesWidget. For example, the previous example could be expressed as: +<<.from-version "5.1.18">> The [[Pragma: \import]] is an alternative syntax for using the ImportVariablesWidget. For example, the previous example could be expressed as: ``` \import [[$:/core/ui/PageMacros]] [all[shadows+tiddlers]tag[$:/tags/Macro]!has[draft.of]] diff --git a/editions/tw5.com/tiddlers/widgets/ParametersWidget.tid b/editions/tw5.com/tiddlers/widgets/ParametersWidget.tid index c71aaf103..a178f04bb 100644 --- a/editions/tw5.com/tiddlers/widgets/ParametersWidget.tid +++ b/editions/tw5.com/tiddlers/widgets/ParametersWidget.tid @@ -1,6 +1,6 @@ caption: parameters created: 20220909111836951 -modified: 20220909111836951 +modified: 20220917113745884 tags: Widgets title: ParametersWidget type: text/vnd.tiddlywiki @@ -9,9 +9,9 @@ type: text/vnd.tiddlywiki There are shortcuts for common scenarios that can often make it unnecessary to use the <<.wlink ParametersWidget>> widget directly: -* the `\parameters` [[pragma|Pragma]] -* the `\procedure` [[pragma|Pragma]] for declaring procedure -* the `\widgets` [[pragma|Pragma]] for declaring custom widgets +* the [[Pragma: \parameters]] +* the [[Pragma: \procedure]] for declaring procedure +* the [[Pragma: \widget]] for declaring custom widgets * the `_parameters` field of tiddlers containing [[Global Definitions]] The <<.wlink ParametersWidget>> widget must be used directly in the following situations: diff --git a/editions/tw5.com/tiddlers/widgets/TranscludeWidget.tid b/editions/tw5.com/tiddlers/widgets/TranscludeWidget.tid index c50bb4880..c25b37045 100644 --- a/editions/tw5.com/tiddlers/widgets/TranscludeWidget.tid +++ b/editions/tw5.com/tiddlers/widgets/TranscludeWidget.tid @@ -1,6 +1,6 @@ caption: transclude created: 20130824142500000 -modified: 20220909111836951 +modified: 20220917113915710 tags: Widgets title: TranscludeWidget type: text/vnd.tiddlywiki @@ -85,10 +85,10 @@ To pass parameters whose names start with a dollar sign `$`, prefix them with an There are several different ways to declare parameters within a transclusion: * the <<.wlink ParametersWidget>> widget -* the `\parameters` [[pragma|Pragma]] -* the `\procedure` [[pragma|Pragma]] for declaring procedure -* the `\widgets` [[pragma|Pragma]] for declaring custom widgets -* the `\define` [[pragma|Pragma]] for declaring macros +* the [[Pragma: \parameters]] +* the [[Pragma: \procedure]] for declaring procedure +* the [[Pragma: \widgets]] for declaring custom widgets +* the [[Pragma: \define]] for declaring macros An example of declaring parameters with the <<.wlink ParametersWidget>> widget: @@ -98,7 +98,7 @@ An example of declaring parameters with the <<.wlink ParametersWidget>> widget: ``` -The `\parameters` [[pragma|Pragma]] can be used as a shortcut syntax for declaring parameters. For example: +The `\parameters` [[Pragma: \parameters]] can be used as a shortcut syntax for declaring parameters. For example: ``` \parameters (firstParameter:"default",secondParameter:"another default") diff --git a/editions/tw5.com/tiddlers/wikitext/HTML in WikiText.tid b/editions/tw5.com/tiddlers/wikitext/HTML in WikiText.tid index 544c3c5fc..519e0e273 100644 --- a/editions/tw5.com/tiddlers/wikitext/HTML in WikiText.tid +++ b/editions/tw5.com/tiddlers/wikitext/HTML in WikiText.tid @@ -1,6 +1,6 @@ caption: HTML created: 20131205160816081 -modified: 20220123174919252 +modified: 20220917074907646 tags: WikiText title: HTML in WikiText type: text/vnd.tiddlywiki @@ -55,7 +55,7 @@ In an extension of conventional HTML syntax, attributes of elements/widgets can * a literal string * a transclusion of a TextReference -* a transclusion of a [[macro/variable|Macros in WikiText]] +* a transclusion of a [[macro/variable|Macros]] * as the result of a [[Filter Expression]] !! Style Attributes @@ -118,7 +118,7 @@ attr={{tiddler!!field}} !! Variable Attribute Values -Variable attribute values are indicated with double angle brackets around a [[macro invocation|Macro Calls in WikiText]]. For example: +Variable attribute values are indicated with double angle brackets around a [[macro invocation|Macro Calls]]. For example: ```
>> diff --git a/editions/tw5.com/tiddlers/wikitext/Macro Calls in WikiText.tid b/editions/tw5.com/tiddlers/wikitext/Macro Calls in WikiText.tid index b79d98134..0d45612f0 100644 --- a/editions/tw5.com/tiddlers/wikitext/Macro Calls in WikiText.tid +++ b/editions/tw5.com/tiddlers/wikitext/Macro Calls in WikiText.tid @@ -1,26 +1,8 @@ caption: Macro Calls -created: 20150220182252000 -modified: 20220122193853161 -tags: WikiText +created: 20220917074831994 +modified: 20220917074844235 +tags: title: Macro Calls in WikiText type: text/vnd.tiddlywiki -To call a [[macro|Macros]], place `<<`double angle brackets`>>` around the name and any parameter values. - -By default, parameters are listed in the same order as in the macro's definition. A parameter can be labelled with its name, either for clarity or to modify the order. - -If no value is specified for a parameter, the default value given for that parameter in the macro's definition is used instead. (If no default value was defined, the parameter is simply 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. - -The syntax is actually a shorthand for a <<.wlink MacroCallWidget>> widget. The widget itself offers greater flexibility, including the ability to [[transclude|Transclusion]] parameter values or generate them via additional macros. - -As macros are simply parameterised [[variables|Variables]], a variable's value can be inserted using the same techniques. - -[[Examples|Macro Calls in WikiText (Examples)]] and [[more examples|WikiText parser mode: macro examples]] - -!! Named vs.unnamed parameters - -In the wikitext notation, using named parameters is always the safer choice compared to defining values only. Not naming parameters may have confusing side effects. For example, imagine the first parameter of some macro specifies a [[state tiddler|StateMechanism]] while the second one is intended for a [[template|Transclusion with Templates]] tiddler. Should you accidentally forget to define the first parameter or are confused about the order, the next time your macro is run, which might even be triggered using the preview, your template tiddler may inadvertently be overriden with what was intended to be the state. +See [[Macro Calls]]. \ No newline at end of file diff --git a/editions/tw5.com/tiddlers/wikitext/Macro Calls.tid b/editions/tw5.com/tiddlers/wikitext/Macro Calls.tid new file mode 100644 index 000000000..ab939f1c4 --- /dev/null +++ b/editions/tw5.com/tiddlers/wikitext/Macro Calls.tid @@ -0,0 +1,58 @@ +caption: Macro Calls +created: 20150220182252000 +modified: 20220918115347941 +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. + +``` +<> +``` + +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. + +``` +
>> +... +
+``` + +!! Using Macro Calls in Filters + +Macro calls can be used in filters: + +``` +<$list filter="[]"> +... + +``` \ No newline at end of file diff --git a/editions/tw5.com/tiddlers/wikitext/Macro Definitions in WikiText.tid b/editions/tw5.com/tiddlers/wikitext/Macro Definitions in WikiText.tid index 693e7833c..2cee3da71 100644 --- a/editions/tw5.com/tiddlers/wikitext/Macro Definitions in WikiText.tid +++ b/editions/tw5.com/tiddlers/wikitext/Macro Definitions in WikiText.tid @@ -1,79 +1,8 @@ caption: Macro Definitions -created: 20150220181617000 -modified: 20180820165115455 -tags: WikiText +created: 20220917074327678 +modified: 20220917074339095 +tags: title: Macro Definitions in WikiText type: text/vnd.tiddlywiki -A [[macro|Macros]] is defined using a `\define` [[pragma|Pragma]]. Like any pragma, this can only appear at the start of a tiddler. - -The first line of the definition specifies the macro 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 macro text (i.e. the snippet represented by the macro name), until `\end` appears on a line by itself: - -<$codeblock code={{$:/editions/tw5.com/macro-examples/say-hi}}/> - -Alternatively, the entire definition can be presented on a single line without an `\end` marker: - -``` -\define sayhi(name:"Bugs Bunny") Hi, I'm $name$. -``` - -A more formal [[presentation|Macro Definition Syntax]] of this syntax is also available. - -!! Accessing variables and parameters - -Inside the macro there are several methods for accessing variables defined outside of the macro or parameters from the macro parameter list. - -|syntax|description|h -|`$...$`|Text substitution of a parameter defined in the macro parameters list | -|`<<__...__>>`|Parameter-as-variable access to a parameter defined in the macro parameters list | -|`$(...)$`|Text substitution of a variable defined outside of the macro | -|`<<...>>`|Access to a variable (or other macro) defined outside of the macro | -
- -!!! Placeholders `$(...)$` - -The macro can contain placeholders for parameters. These consist of a parameter name between dollar signs, like `$this$`. - -The macro can also contain placeholders for [[variables|Variables]]. These consist of a variable name (or macro name) between dollar signs and round brackets, like `$(this)$`. - -The actual value of the parameter or variable is substituted for the placeholder whenever the macro is called: - -<$importvariables filter="$:/editions/tw5.com/macro-examples/say-hi-using-variables"> -<$codeblock code={{$:/editions/tw5.com/macro-examples/say-hi-using-variables}}/> -<$macrocall $name=".example" n="1" -eg="""<$set name="address" value="Rabbit Hole Hill"> -<> -"""/> - - -!!! Parameters as Variables `<<__...__>>` - -Parameters in a wikitext macro can be accessed as variables by using the syntax `<<__...__>>`, i.e the parameter name surrounded by double underscores. For example, the example above could also be expressed as: - -``` -\define sayhi(name:"Bugs Bunny") Hi, I'm <$text text=<<__name__>>/>. -``` - -Accessing parameters as variables only works in macros that are wikified and not, for example, when a macro is used as an attribute value. The advantage of the technique is that it avoids the parameter value being substituted into the macro as a literal string, which in turn can help avoid issues with parameters that contain quotes. - -For example, consider this macro. It invokes another macro using the single parameter as an argument for it: - -``` -\define film-quote(line) <$macrocall $name="anothermacro" actor="Bugs Bunny" line="""$line$"""/> -``` - -The code above will fail if the macro is invoked with the argument containing triple double quotes (for example `<>`). Using parameter variables offers a workaround: - -``` -\define film-quote(line) <$macrocall $name="anothermacro" actor="Bugs Bunny" line=<<__line__>>/> -``` - -!! Scope - -Macros are available to the tiddler that defines them, plus any tiddlers that it transcludes. - -To make a macro available to all tiddlers, define it in a tiddler that has the tag <<.tag $:/tags/Macro>>. - -It is also possible to write a macro as a [[JavaScript module|https://tiddlywiki.com/dev/index.html#JavaScript%20Macros]]. ~JavaScript macros are available to all tiddlers, and offer the maximum flexibility. - -A tiddler can manually import macro definitions from a [[selection|Title Selection]] of other tiddlers by using the <<.wlink ImportVariablesWidget>> widget. +See [[Macro Definitions]]. \ No newline at end of file diff --git a/editions/tw5.com/tiddlers/wikitext/Macro Definitions.tid b/editions/tw5.com/tiddlers/wikitext/Macro Definitions.tid new file mode 100644 index 000000000..31bc006a8 --- /dev/null +++ b/editions/tw5.com/tiddlers/wikitext/Macro Definitions.tid @@ -0,0 +1,52 @@ +caption: Macro Definitions +created: 20150220181617000 +modified: 20220918115917656 +tags: WikiText Macros +title: Macro Definitions +type: text/vnd.tiddlywiki + +!! Introduction + +This tiddler describes the different ways in which [[macros|Macros]] can be defined. + +!! Macro Definition Pragma + +Macros are created using the [[Pragma: \define]] 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 mymacro(param) +This is the macro text (param=$param$) +\end +``` + +!! Macro Definition with Set Widget + +Macros are implemented as a special type of [[variable|Variables]] and so internally are actually defined with a <<.wlink SetWidget>> widget. + +``` +<$set name="mymacro" value="This is the macro text"> +... + +``` + +<<.note """that it is not currently possible to specify parameters when defining a macro with the <<.wlink SetWidget>> widget.""">> + +!! Importing Macro Definitions + +The [[Pragma: \import]] or <<.wlink ImportVariablesWidget>> widget can be used to copy macro definitions from another tiddler. + +!! Global Macro Definitions + +Macros can be made available globally by placing them in a tiddler titled with the name of the global prefixed with `$:/global/`. See [[Global Definitions]] for details. + +!! `$:/tags/Macro` Tag + +For backwards compatibility, global macros can also be defined using the [[SystemTag: $:/tags/Macro]]. The new [[Global Definitions]] mechanism is [[preferred|Macro Pitfalls]] for new applications. + +The tag [[SystemTag: $:/tags/Macro/View]] is used to define macros 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 macros that should only be available within the main view template body and the preview panel. + +!! JavaScript Macros + +Macros can also be <<.js-macro-link "written as JavaScript modules">>. diff --git a/editions/tw5.com/tiddlers/wikitext/Macro Parameter Handling.tid b/editions/tw5.com/tiddlers/wikitext/Macro Parameter Handling.tid new file mode 100644 index 000000000..800b947b1 --- /dev/null +++ b/editions/tw5.com/tiddlers/wikitext/Macro Parameter Handling.tid @@ -0,0 +1,77 @@ +caption: Macro Definitions +created: 20220917154902906 +modified: 20220921093842230 +tags: WikiText Macros +title: Macro Parameter Handling +type: text/vnd.tiddlywiki + +!! Introduction + +[[Macros]] parameters are handled in two different ways: + +# Textual substitution is always performed for each parameter before the macro contents is used +# When the macro contents are wikified the parameters are made available as variables. The variable names are formed by wrapping the parameter name with double underscores + +Somewhat confusingly, in some situations both of these mechanisms will occur; this is related to the [[pitfalls of using macros|Macro Pitfalls]]. + +!! Textual Substitution of Parameters and variables + +The following substitutions take place before the text of a macro is used: + +* The pattern `$param$` is replaced with the value of the named parameter +* The pattern `$(variable)$` is replaced with the value of the named variable + +The actual value of the parameter or variable is substituted for the placeholder whenever the macro is called: + +<$macrocall $name="wikitext-example-without-html" src="""\define say-hi-using-parameters(name,address) +Hi, I'm $name$ and I live in $address$. +\end + +<> +"""/> + +Here's an example using variable substitution: + +<$macrocall $name="wikitext-example-without-html" src="""\define say-hi-using-variables() +Hi, I'm $(name)$ and I live in $(address)$. +\end + +\define name() Bugs + +<$let address="Rabbit Hole Hill"> +<> + +"""/> + +!! Accessing Parameters as Variables + +When macros are wikified, the parameters can be accessed as variables with the name of the parameter wrapped with double underscores. For example, the parameter `address` would be accessed as the variable `__address__`. + +Thus, the example above could also be expressed as: + +<$macrocall $name="wikitext-example-without-html" src="""\define say-hi-using-parameters(name,address) +Hi, I'm <<__name__>> and I live in <<__address__>>. +\end + +<> +"""/> + +Accessing parameters as variables only works in macros that are wikified and not, for example, when a macro is used as an attribute value. + +!!! Advantages of Accessing Parameters as Variables + +The primary advantage of the technique is that it avoids the parameter value being substituted into the macro as a literal string, which in turn can help avoid issues with parameters that contain quotes. + +For example, consider this macro. It invokes another macro using the single parameter as an argument for it: + +``` +\define film-quote(line) <$macrocall $name="anothermacro" actor="Bugs Bunny" line="""$line$"""/> +``` + +The code above will fail if the macro is invoked with the argument containing triple double quotes (for example `<>`). Using parameter variables offers a workaround: + +``` +\define film-quote(line) <$macrocall $name="anothermacro" actor="Bugs Bunny" line=<<__line__>>/> +``` + +See [[Macro Pitfalls]] for more discussion. diff --git a/editions/tw5.com/tiddlers/wikitext/Macro Pitfalls.tid b/editions/tw5.com/tiddlers/wikitext/Macro Pitfalls.tid new file mode 100644 index 000000000..3959191a7 --- /dev/null +++ b/editions/tw5.com/tiddlers/wikitext/Macro Pitfalls.tid @@ -0,0 +1,39 @@ +created: 20220917091428117 +modified: 20220917101652047 +title: Macro Pitfalls +type: text/vnd.tiddlywiki + +! Introduction + +In the early days of TiddlyWiki, [[macros|Macros]] were the best way of encapsulating snippets for reuse, and so they were used extensively. However, they have always suffered from some significant disadvantages that can give rise to errors and poor performance. + +<<.from-version "5.3.0">> Macros have been joined 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. + +! Shortcomings of Textual Substitution + +TiddlyWiki's handling of [[macro|Macros]] parameters is based on "textual substitution" which means that the string values of the parameters provided when calling a macro are plugged into the macro definition before it is wikified. + +Here's a typical example of the approach in early versions of TiddlyWiki 5. The intention is to provide a macro that takes a single parameter of the title of the tiddler to view: + +``` +\define mymacro(title) +<$codeblock code={{$title$}}/> +\end +``` + +That works for simple cases like `<>` but is subtly brittle. For example, the macro above would fail with tiddler titles containing double closing curly braces. Trying to use it with the title `foo}}bar` would lead to the macro being expanded to the following invalid syntax: + +``` +<$codeblock code={{foo}}bar}}/> +``` + +As a result of this issue, for many years the TiddlyWiki 5 user interface failed if a variety of combinations of special characters were encountered in tiddler titles. + +This issue has been mitigated over the years, particularly by providing access to the macro parameters as variables. However, for backwards compatibility, this was done without affecting the existing syntax, which required us to adopt the clumsy protocol of wrapping the parameter name in double underscores to get the name of the corresponding variable. + +! Performance of Global Macros + +Global [[Macro Definitions]] defined with the [[SystemTag: $:/tags/Macro]] suffer from poor performance because every macro has to be parsed regardless of whether it is actually used. + +Furthermore, the way that definitions are imported means that updating a tiddler tagged [[SystemTag: $:/tags/Macro]] will cause the entire page to be refreshed. + diff --git a/editions/tw5.com/tiddlers/wikitext/Macros in WikiText.tid b/editions/tw5.com/tiddlers/wikitext/Macros in WikiText.tid index a738d5389..44dd3ecdc 100644 --- a/editions/tw5.com/tiddlers/wikitext/Macros in WikiText.tid +++ b/editions/tw5.com/tiddlers/wikitext/Macros in WikiText.tid @@ -1,11 +1,8 @@ +caption: Macros created: 20131205160746466 -modified: 20150221094003000 -tags: WikiText +modified: 20220917073713670 +tags: title: Macros in WikiText type: text/vnd.tiddlywiki -caption: Macros -The use of [[macros|Macros]] in WikiText has two distinct aspects: - -* [[Defining macros|Macro Definitions in WikiText]] -* [[Calling macros|Macro Calls in WikiText]] +See [[Macros]]. \ No newline at end of file diff --git a/editions/tw5.com/tiddlers/wikitext/Transclusion and Substitution.tid b/editions/tw5.com/tiddlers/wikitext/Transclusion and Substitution.tid index c74c68855..92333e5b3 100644 --- a/editions/tw5.com/tiddlers/wikitext/Transclusion and Substitution.tid +++ b/editions/tw5.com/tiddlers/wikitext/Transclusion and Substitution.tid @@ -1,5 +1,5 @@ created: 20141018090608643 -modified: 20211117212543789 +modified: 20220917073920737 tags: WikiText title: Transclusion and Substitution type: text/vnd.tiddlywiki @@ -55,6 +55,6 @@ As described in [[Introduction to filter notation]], you can also transclude a v ! Textual Substitution -Textual substitution occurs when the value of a macro/variable is used. It is described in [[Macros in WikiText]]. +Textual substitution occurs when the value of a macro/variable is used. It is described in [[Macros]]. The key difference between substitution and transclusion is that substitution occurs before WikiText parsing. This means that you can use substitution to build WikiText constructions. Transclusions are processed independently, and cannot be combined with adjacent text to define WikiText constructions. diff --git a/editions/tw5.com/tiddlers/wikitext/Transclusion in WikiText.tid b/editions/tw5.com/tiddlers/wikitext/Transclusion in WikiText.tid index f7de5d83d..b7a6134d1 100644 --- a/editions/tw5.com/tiddlers/wikitext/Transclusion in WikiText.tid +++ b/editions/tw5.com/tiddlers/wikitext/Transclusion in WikiText.tid @@ -1,6 +1,6 @@ caption: Transclusion created: 20131205160146648 -modified: 20220122193352028 +modified: 20220909111836951 tags: WikiText title: Transclusion in WikiText type: text/vnd.tiddlywiki @@ -12,6 +12,8 @@ You can incorporate the content of one tiddler within another using the [[Transc * `{{MyTiddler}}` transcludes a single tiddler * `{{MyTiddler||TemplateTitle}}` displays the tiddler through a specified [[TemplateTiddler|TemplateTiddlers]] * `{{||TemplateTitle}}` displays the specified template tiddler without altering the [[current tiddler|Current Tiddler]] +* `{{MyTiddler|Parameter}}` transcludes a single tiddler with a single parameter +* `{{MyTiddler||TemplateTitle|Parameter|SecondParameter}}` transcludes a single tiddler through a specified [[TemplateTiddler|TemplateTiddlers]] with two parameters !! Transcluding Text References @@ -37,7 +39,7 @@ The WikiText transclusion syntax generates a TiddlerWidget wrapped around a Tran ``` <$tiddler tiddler="MyTiddler"> -<$transclude tiddler="MyTemplate" field="myField"/> +<$transclude $tiddler="MyTemplate" $field="myField"/> ``` diff --git a/editions/tw5.com/tiddlers/wikitext/Variables in WikiText.tid b/editions/tw5.com/tiddlers/wikitext/Variables in WikiText.tid index a23938037..4c465528b 100644 --- a/editions/tw5.com/tiddlers/wikitext/Variables in WikiText.tid +++ b/editions/tw5.com/tiddlers/wikitext/Variables in WikiText.tid @@ -1,13 +1,13 @@ caption: Variables created: 20141002141231992 -modified: 20220909111836951 +modified: 20220917075007507 tags: WikiText title: Variables in WikiText type: text/vnd.tiddlywiki See also the [[introduction to the concept of variables|Variables]]. -To transclude the value of a variable, use the [[macro call syntax|Macro Calls in WikiText]] or the <<.wlink TranscludeWidget>> widget with the `$variable` attribute. +To transclude the value of a variable, use the [[macro call syntax|Macro Calls]] or the <<.wlink TranscludeWidget>> widget with the `$variable` attribute. A [[macro|Macros]] snippet can contain `$(name)$` as a [[placeholder|Macro Definitions in WikiText]] for which the value of the variable of that name will be substituted. @@ -22,7 +22,7 @@ eg="""<$set name=animal value=zebra> !! Example: defining a macro -The `\define` pragma below [[defines a macro|Macros in WikiText]] called <<.var tags-of-current-tiddler>>. The macro returns the value of the tiddler's <<.field tags>> field, and can be accessed from anywhere else in the same tiddler (or in any tiddler that [[imports|ImportVariablesWidget]] it). +The `\define` pragma below [[defines a macro|Macro Definitions]] called <<.var tags-of-current-tiddler>>. The macro returns the value of the tiddler's <<.field tags>> field, and can be accessed from anywhere else in the same tiddler (or in any tiddler that [[imports|ImportVariablesWidget]] it). <$importvariables filter="$:/editions/tw5.com/macro-examples/tags-of-current-tiddler"> <$codeblock code={{$:/editions/tw5.com/macro-examples/tags-of-current-tiddler}}/> diff --git a/editions/tw5.com/tiddlers/wikitext/parser/Inline Mode WikiText.tid b/editions/tw5.com/tiddlers/wikitext/parser/Inline Mode WikiText.tid index 88afd8372..3e04a01ac 100644 --- a/editions/tw5.com/tiddlers/wikitext/parser/Inline Mode WikiText.tid +++ b/editions/tw5.com/tiddlers/wikitext/parser/Inline Mode WikiText.tid @@ -1,6 +1,6 @@ caption: inline parser mode created: 20220111000108618 -modified: 20220122182842036 +modified: 20220917074925230 tags: [[WikiText Parser Modes]] title: Inline Mode WikiText type: text/vnd.tiddlywiki @@ -14,13 +14,13 @@ These WikiText types can be expressed without an entire line of text. They aren' * [[HTML in WikiText]] * [[Images in WikiText]] * [[Linking in WikiText]] -* [[Macro Calls in WikiText]] +* [[Macro Calls]] * [[Styles and Classes in WikiText]] (single line version only) * [[Transclusion in WikiText]] * [[Variables in WikiText]] * [[Widgets in WikiText]] -<<.tip """[[Macro Calls in WikiText]] and [[Transclusion in WikiText]] will be recognised in block mode if the macro call or transclusion spans an entire line.""">> +<<.tip """[[Macro Calls]] and [[Transclusion in WikiText]] will be recognised in block mode if the macro call or transclusion spans an entire line.""">> <<.tip """The other ''inline mode'' WikiText types are technically <<.em only>> detected while the parser is in ''inline mode''. However, the opening punctuation will also trigger the start of [[Paragraphs in WikiText]] which will automatically cause the parser to go into ''inline mode''. Therefore, practically speaking, it is just as useful to consider these WikiText types as recognised while the parser is in either ''inline mode'' or ''block mode''""">> While processing the //enclosed// text of some of these WikiText types, the parser [[will not look for new WikiText|Places where the parser ignores WikiText]]. But for rest of these WikiText types, the parser will continue in ''inline mode'' for the //enclosed// text. While parsing that text, it might encounter something which [[moves it to block mode|WikiText parser mode transitions]]. \ No newline at end of file diff --git a/editions/tw5.com/tiddlers/wikitext/parser/Places where the parser ignores WikiText.tid b/editions/tw5.com/tiddlers/wikitext/parser/Places where the parser ignores WikiText.tid index afb9db192..e8791f2ea 100644 --- a/editions/tw5.com/tiddlers/wikitext/parser/Places where the parser ignores WikiText.tid +++ b/editions/tw5.com/tiddlers/wikitext/parser/Places where the parser ignores WikiText.tid @@ -1,6 +1,6 @@ caption: ignore parser mode created: 20220111000929700 -modified: 20220122182842038 +modified: 20220917074956808 tags: [[WikiText Parser Modes]] title: Places where the parser ignores WikiText type: text/vnd.tiddlywiki @@ -8,7 +8,7 @@ type: text/vnd.tiddlywiki Text enclosed by these constructs is skipped by the parser and WikiText punctuation will be ignored: |[[Code Blocks in WikiText]]|One of the main purposes of code blocks is to suppress wikitext expansion. Once the code block starts, the parser will ignore all WikiText punctuation until the code block ends.| -|[[Images in WikiText]]|`[[img|literal image link text]]` - the text enclosed by square braces will be ignored. This means, for example, [[transclusions|Transclusion in WikiText]] and [[macro calls|Macro Calls in WikiText]] cannot be used to dynamically construct the link text| -|[[Linking in WikiText]]|`[[literal link target|literal link text]]` - the text enclosed by square braces will be ignored. This means, for example, [[transclusions|Transclusion in WikiText]] and [[macro calls|Macro Calls in WikiText]] cannot be used to dynamically construct the link target or the link text| -|[[Macro Calls in WikiText]]|`<>" {{transclusion_ignored}}>>` - while processing the text enclosed by a macro call, the parser will follow special rules for detecting macro parameters. These rules do not include detection of WikiText. However, after the parameters are substituted into the macro definition, the result will be parsed using [[normal rules|Wiki Text Parser Modes]]. This will likely result in the detection of any WikiText.| +|[[Images in WikiText]]|`[[img|literal image link text]]` - the text enclosed by square braces will be ignored. This means, for example, [[transclusions|Transclusion in WikiText]] and [[macro calls|Macro Calls]] cannot be used to dynamically construct the link text| +|[[Linking in WikiText]]|`[[literal link target|literal link text]]` - the text enclosed by square braces will be ignored. This means, for example, [[transclusions|Transclusion in WikiText]] and [[macro calls|Macro Calls]] cannot be used to dynamically construct the link target or the link text| +|[[Macro Calls]]|`<>" {{transclusion_ignored}}>>` - while processing the text enclosed by a macro call, the parser will follow special rules for detecting macro parameters. These rules do not include detection of WikiText. However, after the parameters are substituted into the macro definition, the result will be parsed using [[normal rules|Wiki Text Parser Modes]]. This will likely result in the detection of any WikiText.| diff --git a/editions/tw5.com/tiddlers/wikitext/parser/WikiText Parser Modes.tid b/editions/tw5.com/tiddlers/wikitext/parser/WikiText Parser Modes.tid index 4a9c431b2..67a31c75b 100644 --- a/editions/tw5.com/tiddlers/wikitext/parser/WikiText Parser Modes.tid +++ b/editions/tw5.com/tiddlers/wikitext/parser/WikiText Parser Modes.tid @@ -1,12 +1,12 @@ created: 20220110233944530 -modified: 20220513112653029 +modified: 20220917112724551 tags: WikiText title: WikiText Parser Modes type: text/vnd.tiddlywiki In order to display Tiddlers (usually the text field), the WikiText parser reads and interprets the content and applies WikiText rules. The parser has three modes: -* ''pragma mode'' - the parser will recognise only [[pragma mode WikiText|Pragma]] punctuation +* ''pragma mode'' - the parser will recognise only [[pragma mode WikiText|Pragmas]] punctuation * ''block mode'' - the parser will recognise only [[block mode WikiText|Block Mode WikiText]] punctuation * ''inline mode'' - the parser will recognise only [[inline mode WikiText|Inline Mode WikiText]] diff --git a/editions/tw5.com/tiddlers/wikitext/parser/WikiText parser mode transitions.tid b/editions/tw5.com/tiddlers/wikitext/parser/WikiText parser mode transitions.tid index 009c3d3f3..2bde74418 100644 --- a/editions/tw5.com/tiddlers/wikitext/parser/WikiText parser mode transitions.tid +++ b/editions/tw5.com/tiddlers/wikitext/parser/WikiText parser mode transitions.tid @@ -1,5 +1,5 @@ created: 20220110235808139 -modified: 20220122184232928 +modified: 20220917113931866 tags: [[WikiText Parser Modes]] title: WikiText parser mode transitions type: text/vnd.tiddlywiki @@ -27,11 +27,11 @@ This is a <<.em rough>> diagram whose lines mostly correspond to the parser mode By default the parser starts in [[block mode|Block Mode WikiText]]. However, a tiddler can instead be transcluded with [[inline mode|Inline Mode WikiText]] in which case [[block mode WikiText|Block Mode WikiText]] will not be recognised. -At the start of text only, the parser will also recognise any [[pragma mode WikiText|Pragma]]. +At the start of text only, the parser will also recognise any [[pragma mode WikiText|Pragmas]]. !! Transitions from pragma mode -At the start of text, the parser will recognise any [[pragma|Pragma]]. If none are found then it will move to [[inline|Inline Mode WikiText]] or [[block|Block Mode WikiText]] mode depending on the transclusion mode. If any [[pragma|Pragma]] are found then it will continue looking for [[pragma|Pragma]] until it finds one or more blank lines not followed by the start of a new pragma. +At the start of text, the parser will recognise any [[pragma|Pragmas]]. If none are found then it will move to [[inline|Inline Mode WikiText]] or [[block|Block Mode WikiText]] mode depending on the transclusion mode. If any [[pragma|Pragmas]] are found then it will continue looking for [[pragma|Pragmas]] until it finds one or more blank lines not followed by the start of a new pragma. !! Transitions from block mode diff --git a/editions/tw5.com/tiddlers/wikitext/parser/WikiText parser mode_ macro examples.tid b/editions/tw5.com/tiddlers/wikitext/parser/WikiText parser mode_ macro examples.tid index 07a08db46..e2a2e9616 100644 --- a/editions/tw5.com/tiddlers/wikitext/parser/WikiText parser mode_ macro examples.tid +++ b/editions/tw5.com/tiddlers/wikitext/parser/WikiText parser mode_ macro examples.tid @@ -1,5 +1,5 @@ created: 20220122144742419 -modified: 20220122180929683 +modified: 20220917075019770 tags: [[WikiText parser mode transitions]] title: WikiText parser mode: macro examples type: text/vnd.tiddlywiki @@ -25,7 +25,7 @@ then """>> -The list syntax is recognised in [[block mode|Block Mode WikiText]] and the enclosed contents are parsed using [[inline mode|Inline Mode WikiText]]. When the parser encounters a [[wikitext macro call|Macro Calls in WikiText]] it will use the current parse mode to parse the contents of the macro. The contents of the macro contains table syntax which is only recognised in [[block mode|Block Mode WikiText]]. +The list syntax is recognised in [[block mode|Block Mode WikiText]] and the enclosed contents are parsed using [[inline mode|Inline Mode WikiText]]. When the parser encounters a [[wikitext macro call|Macro Calls]] it will use the current parse mode to parse the contents of the macro. The contents of the macro contains table syntax which is only recognised in [[block mode|Block Mode WikiText]]. Therefore, in #1 above the table syntax is not recognised. In #2 above, the blank line after the open `div` tag moves the parser back into [[block mode|Block Mode WikiText]], the macro call inherits it and the table is recognised.