Where is the GROK manual for pragma?

#1

If eventually you are going to deprecate the old macros, you need to pay @sobjornstad to write a user-friendly volume 2 of Grok that focuses on the pragma you are using to replace them.

I worked hard to learn the define / macro system and I depend on it because I’ve gotten a lot of mileage out of it. I remember watching Charlie’s helpful videos and getting excited.

The pragma stuff, on the other hand, looks a lot harder for a non-coder like me. And the current documentation for it is as confusing as, well, pretty much all the current TiddlyWiki documentation. We don’t need more “This is the definition of this noun” but “If you want to do xyz, here is how.”

Someone needs to guide us by the hand to get through it. If not, at some point you are going to drift off on a raft of the chosen few / inner circle / people in the know, and leave all us regular folk behind.

3 Likes
#2

Agreed, we should have such documentation, and it should be easy to understand and easy to read.

I am not an expert in this, so do take the following with a grain of salt

“Pragma” itself here is not the issue. \define ... is a pragma, \whitespace trim is a pragma. \rules ... is a pragma. Pragmas are simply instructions about how subsequent wikitext is handled. procedure..., parameters... and function... are the newer pragmas that you’re probably referring to.

Although \define is listed as deprecated, it’s not going anywhere… probably ever, but certainly not before TW6. Tiddlywiki puts a premium on backward compatibility.

However, \procedure... is a more flexible, more capable version of the same idea: a named template to create wikitext from parameters and the current context. There are some real differences between \procedure ... and \define .... But many macros can simply be updated by replacing the word "define" with the word "procedure" and many others only need an additional switch in how they refer to variables, a very mechanical change. (Note that this is many and not all!)

\parameters ... is a helper for procedures (and I believe it also works with macros too.) If things are working well for you without it, there’s little reason to even consider it. But it offers some additional flexibility, in the same way that <$let> improved on <$vars>, allowing one parameter’s default value to be defined in terms of earlier named parameters. But you can easily ignore this unless and until you find a real need for it.

function ... is different. It’s the same idea of dynamically building something based on the current context and parameters. But instead of building wikitext meant to be displayed, they’re used to build filters. This offers some nice new flexibility. But again, if you don’t currently feel the need, there’s no particular reason to investigate them. At the very least, they will not be replacing your macros; they’re designed for a different job.

The bottom line is simple: Yes, these need to be better documented. But you can ignore them as long as you like, using technique you already know well. When you’re ready to try them, upgrading should not be hard.

2 Likes
#3

Thanks Scott, yes I knew when I wrote ‘pragma’ that it might not be the best catch all word to describe what was replacing the \define macro.

Thanks for the explanation!