Although “\define” (macro) syntax has been deprecated in favor of “\procedure” and “\function” syntax, TiddlyWiki has a very strong goal of backwards compatibility. Thus, while it is recommended to use procedures and functions, old-style macros will always be supported, and users will never have to “rewrite their list manually”.
Within the TWCore, “official macros” are being gradually replaced by equivalent procedures and/or functions.
However, this process is not always as smooth as you might expect.
For example, in the most recent TWCore update (v5.3.4, released on June 27th), the <<colour>> macro was re-written as a procedure. However, after release it was then discovered that this resulted in a significant error if this new procedure was used as an unquotedtext=<<colour ...>> parameter in a $wikify widget (a common coding technique for resolving color values retrieved from TiddlyWiki palette definitions).
As a consequence, a new TWCore update (v.5.3.5) is about to be released (scheduled for July 8th) that will revert the change in <<colour>> back to its previous macro syntax. Of course, in some future TWCore update, this macro may once again be replaced by a procedure, but only if/when backward-compatible usage can be preserved.
They will still work as expected. It only means, that for the core we will try to rewrite them and hopefully make them easier to maintain and a bit more performant.
Instead of \define use \procedure
\funcitons, most of the time can be used instead of filtered transclusions {{{ }}}
\widget is completely new and for advanced users only
We will probably rewrite them. But we are also still new to the new functionalities. So there will be some hickups on the way. – From my own experience using the new possibilities improves wikitext coding. There are functionalities that are easier to create. Especially \functions are great tool.
Other, perhaps better facilities are available, but that does not make macros deprecated. If they were, special mention would be made of it, which it hasn’t.
In computer software standards and documentation, the term deprecation is used to indicate discouragement of usage of a particular software feature, usually because it has been superseded by a newer/better version .
That quote above has always been my understanding of “deprecation” and “superseded” in that context. If that is not the intent of the word “superseded” in the TiddlyWiki docs, then the docs should probably refactor the wording to eliminate any confusion.
All of that said. When the specific term “deprecated” is used, it often means that the feature will eventually be removed. When that specific word is not there, and only superseded appears, then superseded, as I know it, means “deprecated in a partial scope”, as in “not going away, but usage is discouraged.”
Of course it’s fair to say it, but it’s not true say it. TiddlyWiki has a means to publish a given facility is deprecated and this is NOT the case here. Example:
It would be confusing to say that macros are (per se) deprecated when there are still so many macros in the core. Hence the “superceded” language seems more accurate.
Lots of the documentation necessarily still refers to macros, since many core macros have yet to be rewritten. And indeed, some have been recently rewritten, but (as it turns out) not-quite-successfully.
Maybe that’s why the deprecation note doesn’t seem to apply to macros per se, but instead the deprecation alert is attached to using macrocall (rather than transclude). Perhaps it also should be attached to using \define to create new custom macros…
Indeed. Not helped by the sprawling nature of the documentation. There is a clear (and, to me) obvious spot to show the deprecation badge, but it’s not there.
It can’t be deprecated to use macros (that is, to use the capabilities that leverage them), because macros are still part of the architecture of the core.
But it can be deprecated to generate macros (with the \define pragma), and it can be deprecated to call them as macros (with macrocall widget) — because (if I understand correctly) once the core macros are re-written, your macro-call will eventually fail, or at least become brittle. But you can get the same behavior through transclude widget, and that will be more future-compatible.
I think that’s why we see the deprecation badge in the locations where it’s appearing now.
Still, a more consistent flagging, and clearer messaging about what end-users should and shouldn’t worry about, would be helpful. I hate to imagine a newcomer getting excited about some of TiddlyWiki’s capabilities, learning that these are macro-based, and being spooked after learning that macros are deprecated.
I would like to point out the $macrocall widget is still useful and can even make use of parameters defined in a procedure. In fact it is more readable than using the new $transclude $variables format, however it can’t use all new features.
I will propose a new simpler form be created.
My advice is to learn the new alternatives to the depricated features and use them where possible otherwise use the original methods.
As a designer it’s wise to think one day you may need to rewrite old to new, this is unlikely, and you want to minimise the effort by transitioning to the new methods in new code going forward.
Hey! I totally agree that the $macrocall is still useful, especially for simpler projects. It has its advantages but the new $transclude $variables offer more flexibility. I think its worth knowing both approaches as sometimes the old way can be quicker. code clarity is the key!
