Use of macros in the latest version

#1

Hello,

First time user here. I’ve been reading about TW and from what I can tell, it would suit my needs for a personal Wiki :grinning_face_with_smiling_eyes:

While searching for info about macros, I noticed this: https://tiddlywiki.com/static/Macros.html

It states macros are, or will become deprecated…

Some questions I have:

  • what about TW with a large collection of macros, does there exist some sort of migration tool, or would users have to rewrite their list manually
  • macros would be replaced by 3 new options, how to choose the right one for the right case?
  • what about official macros, when will they be replaced?

Thx

#2

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 unquoted text=<<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.

3 Likes
#3

Ok thank you for the info and quick reply :grinning_face_with_smiling_eyes:

Sorry, just 1 question remains, what is the rule of thumb in choosing either function, procedure or widget?

Like f.e. If It would like to create a custom warning/info box, would I have to choose a procedure then?

Greetings

#4

Hi Chris, Welcome

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.

hope that helps
-mario

1 Like
#5

What is missing at the info-boxes described at: https://tiddlywiki.com/#Documentation%20Macros?
The code can be found at: https://tiddlywiki.com/#%24%3A%2Feditions%2Ftw5.com%2Fdoc-macros

#6

Ok thank you very much guys :grinning_face_with_smiling_eyes:

#7

Not so. They are absolutely not deprecated.

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.

See here.

Example.

1 Like
#8

I’m just being a little bit nit-picky about language. I think it is fair to say macros are deprecated (but in a narrow scope of the word!)

From https://tiddlywiki.com/static/Macros.html:

Macros have been superseded by Procedures, Functions and Custom Widgets

From terminology - The Difference Between Deprecated, Depreciated and Obsolete - Stack Overflow

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.”

Something like that.

#9

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:

image

There is no such badge attached to macros.

#10

There IS a “deprecated” badge for macros…

When you view MacroCallWidget, Macro Definition Syntax, or Macro Call Syntax, it says “Deprecated since 5.3.0”

see https://tiddlywiki.com/#Deprecated%20-%20What%20does%20it%20mean:[[Deprecated%20-%20What%20does%20it%20mean]]%20MacroCallWidget%20[[Macro%20Definition%20Syntax]]%20[[Macro%20Call%20Syntax]]

#11

Conflicting sources of info, that can cause some mighty headaches.

It would be good for all sources to be on the same page.

#12

Agreed. Single source of truth.

I stand corrected.

#13

Certainly, we’re still in transition!

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. :grimacing:

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…

(There’s still no deprecation note at the very place where the \define pragma is explained: https://tiddlywiki.com/#Macro%20Definitions )

#14

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.

I guess that’s down to us to fix. :muscle:

#15

I think it would be misleading to put it 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. :grimacing:

#16

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.

1 Like
#17

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:wink:!

1 Like