Early Testing for v5.3.0-prerelease

[jeremyruston]

The upcoming v5.3.0 release of TiddlyWiki introduces some significant improvements and new features related to some of TiddlyWiki’s most fundamental components: macros, widgets, operators and transclusion. v5.3.0 also contains several other bug fixes and improvements. All the changes are intended to be backwards compatible.

This is a good time to test the new release and give feedback. The currently planned schedule is to freeze further changes on June 12th, followed by the final release on June 26th. That means that there is time to act on feedback, but it’s helpful to get it as soon as possible.

https://tiddlywiki.com/prerelease

There are several ways you can help:

• Visit the prerelease on the web, explore the release note and try out the new features. Let us know if the release note or documentation is not clear
• Use the prerelease upgrader at https://tiddlywiki.com/prerelease/upgrade.html to make a test upgrade of your own single file wiki and try out your usual workflows
• If using Node.js, download the prerelease from GitHub - Jermolene/TiddlyWiki5: A self-contained JavaScript wiki for the browser, Node.js, AWS Lambda etc. and try it with your own data and plugins

Any feedback is welcome here, or on GitHub.

Please wait until the official release before updating your day-to-day wikis, and remember the first rule of TiddlyWiki: to make sure to take (and verify) backups before doing anything risky.

Best wishes

Jeremy

[Mohammad]

One way to learn about the new features is to see how the core itself uses the new features.

For example

• See https://tiddlywiki.com/prerelease/#%24%3A%2Fcore%2Fmacros%2Flist and learn how genesis is used!

[etardiff]

Some documentation questions:

1. Macro Pitfalls includes the following on 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.

Since the tiddler is contrasting macros with procedures/functions/custom widgets, this leads me to assume that the new macro alternatives do not have the same performance implications and/or are not imported in the same way.

• Is this true? I can’t find anything explicitly discussing the performance of the new 5.3.0 features.
• However, Procedure Definitions does explicitly mention the $:/tags/Macro tag as a means of creating for creating global procedures.
• Are procedures handled differently than macros with the same tag, or are the docs only suggesting that we should be using the $:/tags/Macro/View and $:/tags/Macro/View/Body tags instead, and thus cutting down on the truly “global”?

2. Also on Procedure Definitions—this seems like it’s probably just a copy-paste error:

• I assume the tiddler should be referring to “procedures” and using \procedure instead.

3. Global functions and custom widgets?

• My understanding is that both can also be made global with the $:/tags/Macro tag, but this isn’t explicitly mentioned in the documentation. The Custom Widgets tiddler does explain that custom widgets are a special kind of procedure, so perhaps it goes without saying, but I think it ought to be mentioned on the Functions tiddler, at least.

4. Checking my understanding of functions…

• Since \function my-function is a shortcut for defining my-function with a <$set> widget (and, potentially, a narrower scope), I’d assume that a function using a TextReference (like \function my-function(parameter:"2") [<parameter>multiply[1.5]add{!!test}]) would destroy and re-render the entire contents of the tiddler in which it appeared if the value of the “test” field changes. This seems to be borne out in my testing.
• Is there any work-around for this? Or does best practice simply advise against defining functions that incorporate TextReferences (and, I imagine, against making any of them global?)

Edit for posterity: Not a \function issue; I’d misdiagnosed an unrelated issue with text-input widgets, now fixed.

[Scott_Sauyet]

I’ve just tried upgrades on three of my most complex wikis (which are probably not very complex by others’ standards!) and found no backward incompatibilities. Everything simply seems to work fine. Two of them are behind corporate walls, but one I’ve been talking about a fair bit here: my periodic table work.

I still haven’t spent enough time learning the new features to really try them out, and don’t know when I’ll get to that, but here’s one report of successful upgrades…

[jeremyruston]

Thank you @etardiff for the very helpful feedback.

@etardiff

Since the tiddler is contrasting macros with procedures/functions/custom widgets, this leads me to assume that the new macro alternatives do not have the same performance implications and/or are not imported in the same way.

Ouch! Those docs are referring to a feature that was retracted during the development process. At once point, I added an improved mechanism for defining global procedures/functions/macros/widgets that did not rely on globally importing the definitions. We removed it because it was complex and didn’t work as well as hoped.

@etardiff

Also on Procedure Definitions—this seems like it’s probably just a copy-paste error

Thanks, that is indeed a copy-paste error.

@etardiff

3. Global functions and custom widgets?

• My understanding is that both can also be made global with the $:/tags/Macro tag, but this isn’t explicitly mentioned in the documentation

Great that’s an oversight, thank you.

@etardiff

Since \function my-function is a shortcut for defining my-function with a <$set> widget (and, potentially, a narrower scope), I’d assume that a function using a TextReference (like \function my-function(parameter:"2") [<parameter>multiply[1.5]add{!!test}]) would destroy and re-render the entire contents of the tiddler in which it appeared if the value of the “test” field changes. This seems to be borne out in my testing.

That’s not quite right. The function definition would not get re-rendered when the test field changes. Think of the function definition as a variable containing plain, unparsed text. The text of a function is only processed when it is explicitly evaluated as part of a filter evaluation.

Perhaps you could post a fuller example so that we can see what is going on?

[jeremyruston]

@Scott_Sauyet

I’ve just tried upgrades on three of my most complex wikis (which are probably not very complex by others’ standards!) and found no backward incompatibilities. Everything simply seems to work fine. Two of them are behind corporate walls, but one I’ve been talking about a fair bit here: my periodic table work.

Thanks @Scott_Sauyet that’s very helpful.

[etardiff]

@jeremyruston

Perhaps you could post a fuller example so that we can see what is going on?

I’ll double-check when I’m at a computer, but I think I was probably just running into the issue with text input fields losing focus that’s already been reported and resolved. I was using an $edit-text widget to edit field values, and when it lost focus I assumed there must be a scoping issue forcing rerendering (as I’ve encountered before with $let widgets that were too broadly scoped.)

Edit: Looks good now!

Glad to hear this shouldn’t be a problem!

[jeremyruston]

Thanks @etardiff that’s good news.

[TW_Tones]

I notice in the in the tiddler Variables usage there is not reference to the $(var)$ form in define macros. It should be added because it is part of them only remaining uses of macros.

Otherwise my complements to all especialy @jeremyruston on the work put into this.

[pmario]

@TW_Tones

I notice in the in the tiddler Variables usage there is not reference to the $(var)$ form in define macros.

Do you have a link? … This form of variable substitution is deprecated and should not be used anymore. We should not promote it. I did write about it here in talk several times already.

[jeremyruston]

@pmario

Do you have a link? … This form of variable substitution is deprecated and should not be used anymore. We should not promote it. I did write about it here in talk several times already.

@pmario to be clear, we have not yet deprecated textual substitution in macros. There are still plenty of valid use cases. In any case, the syntax still needs to be documented.

[TW_Tones]

As Jeremy said. I am just seeking consistency and to clarify its not changed. If you read existing code you may see this and want to look it up even so you can refactor it into newer forms.

[TW_Tones]

The enhancement of the transclude widget is well documented but I can’t find many references to the new extended uses of it in its short form {{ }}. It is mentioned here Transclusion in WikiText such as {{MyTiddler||TemplateTitle|Parameter|SecondParameter}} perhaps we can expand this a little and link to it in various tiddlers.

• For example defining / accessing parameters ## Transclusion with Templates
  
  • and perhaps an example or two.
• This looks similar to the transclusion variable so there may be value clarifying this to avoid confusion such as;
  • From TW5.3.0 its possible to include parameters in short form transclusions, see here, please do not confuse this with the format of the transclude variable.
• It makes me wonder if the transclusion variable or a new one should be extended for completeness?

Using https://tiddlywiki.com/prerelease/upgrade.html to upgrade a tiddlywiki to the prerelease I am getting timeouts in chrome but not in firefox.

A preliminary test of a large sophisticated tiddlywiki I use has not exposed any problems post upgrade. Very impressive.