Yes. This works in a tiddler with or without a transclusion that shows it. … BUT if transcluded, that “param” value can be changed
\parameters (param:"test parameter")
<<param>>
1 Like
Here they are. See the first 3 posts 
and have fun!
3 Likes
Then it is could be \runner, it sound good to me, because it executes a filter expression. I would prefer short pragmas (it is the same reason for my preference of \def over \procedure)
1 Like
I believe the names we will use should not so much root in (programming) semantics, but if at all possible in terms that an advanced TW user (below the level of developer) will already know if he/she has been studying the documentation diligently. I for one can live with historians 100 years from now saying “Duh, TW people used the term ‘macro’ wrongly.”
For what it’s worth, my vote is for \operator. Look up any “operator” in the docs and you will find a description of a name, suffix, parameters, functionality. This is very close to what we will define with the pragma. Maybe it’s not semantically correct, but one will intuitively know what’s going on when reading code.
For the same reason I must vote for \macro. This is finally the chance to call a spade a spade in the source code, don’t squander it.
I know <$placeholder> would be a lot to type, but I’ve been doing that every time a make an $edit-text widget, and it makes pretty clear what it does with terminology a TW programmer knows – at least better so than <$slot> does.
I’m not a fan of $$ and haven’t been, but there are only so many symbols that most people are familiar with, and I like that TW tries not to go overboard with it.
I promise, though, that I will not refuse the new functionality no matter what the pragmas will be called eventually. 
1 Like
From a user experience perspective I strongly disagree. It is extremely important to use distinct terms for new concepts that avoid the need for disambiguation, which is almost guaranteed when re-using existing terminology.
Overall I think there is far too much focus on the names of the new pragma in this discussion thread. I would suggest approaching this instead from the point of view of trying to write end user documentation for the new concepts - not the pragma that implements the concept - and think of the names for the new concepts in terms of how intuitive and precise that documentation will be for new TiddlyWiki users.
Let’s agree to disagree, then. Your point about appropriate distinction is surely valid, but with it comes a hefty initial “shock” because there is so little that’s familiar to existing users. One might certainly improve the initial acceptance (for those users), if not everything that is PR #6666 was completely new regarding every syntax, term and concept. Why must “macros” now be called “procedures” only because they gained flexibility? Why must filter “operators” now be called “functions”, only because I can define them myself? Why do widgets not get a new name?
I must admit that I’m a bit of an outsider looking in on PR #6666, so my perspective will surely be different from yours.
I think the OP in its closing remarks put the focus on exactly this point.
That was definitely something I always liked about TW.
Also, I’m thinking from the point-of-view of an existing user. From a new user perspective, starting from a clean slate, most of my points would be invalid, of course.
2 Likes
Very interesting, forthright, discussion you are having.
I have appreciation of both your takes on the matter.
I want to comment generally that “new terms/concepts” can work well within a system that co-mutually defines those terms.
Though issues would arise where they lack total inter-consistency. Without that, a given descriptive system, can fail.
TBH, I think that TW functionality is very innovative and actually deserves it’s own meta-concepts. When needed, for purpose.
Though location of those concepts in the extant computer-languages matrix does raise issues, especially on initial comprehension.
I should quickly add, I am not a programmer. Merely a social scientist interested in where “differentiation & expansion” of lingo is valuable—i.e. does new TW lingo better serve end-use or not? And avoid barriers to entry?
Just somewhat philosophical thoughts,
TT
See. … That’s wrong. An operator is only 1 element of a filter run. eg: [tag[HelloThere]] … tag is the operator and HelloThere is the operand. … All together is 1 filter run.
… But functions IMO is a name that should be challenged. IMO the best fit would be filter … but … that term is overused already.
Intentionally allowing ambiguity in the documentation and concepts and potential confusion for most users for all time, for the express purpose of allowing a semblance of familiarity of existing advanced users - who are a smaller though outspoken and important subset of the community - cannot be the goal that drives these decisions. If anything, I would hope that the advanced users are precisely the community members more willing to be open to change and learning new concepts and terms, and thus contribute to creating a better entry path for others behind them on the learning curve.
I would much rather that the introduction of parametrized transclusions come as a shock to some existing users if it means that in the long term we have greater clarity in the concepts and documentation. After all, all of the these new concepts and features are entirely backwards compatible and optional for existing users to learn at this time, and the existing mechanisms will still be present and usable just as they always have been.
I will assume that this is merely a rhetorical question since taken literally it would indicate a lack of familiarity with the relevant documentation and concepts. Reusing the same term for something that behaves and is used differently is bound to lead to user confusion and even lead them to the wrong documentation.
Would you like to take a crack at a quick draft of documentation for tw-com for “procedures” and “functions” under your proposed nomenclature of macros and operators, whilst disambiguating between the new forms and what those terms are currently used for in TiddlyWiki? It would be a good way to determine the merits of the proposal as seen from your perspective. I considered this path a while back but personally did not find it viable.
A fair proposal. I shall take a stab at it, but cannot promise that anything presentable will ever come of it. At the least it will shut me up for a while…
Thanks @Yaisog there are some helpful questions there.
That observation seems fundamental: there is a shock to the new stuff because it is new. Even though the changes are backwards compatible, they require users to reconsider the way that they have always done things. I can understand why that can be unnerving.
But there are good reasons for the introduction of these new features. A trend through this thread has been the desire to use existing names for the new things as a way to make them more familiar, and less shocking.
Part of the problem is that doing that would require us to retrospectively change what these existing names mean, which is super confusing. As @saqimtiaz notes, reusing the existing names means that we have to qualify those names to avoid ambiguity, making the docs more complex and hard to read.
Procedures are not just macros with the addition of new capabilities. Macros also have capabilities that procedures lack: notably, procedures don’t do textual substitution, which is the capability that gives macros their name.
Because what we are calling functions are not the same as filter operators. Filter operators take suffixes and operands, and can only be used in filters. Functions take named parameters, and can be used in many contexts.
The key observation with functions is that our usage of the term closely matches that of the wider software industry. Almost all programming languages agree on what a function is, and the TiddlyWiki interpretation is very similar.
Widgets already exist in TiddlyWiki. The parameterised transclusion work doesn’t replace them with anything else, it just adds the ability to make user defined widgets. There’s no need to change the terminology because there is no confusion.
1 Like
I can’t argue your facts, neither do I want to. I just gave an opinion from a singular perspective, and it wasn’t that of the persons writing the docs.
Like I said initially, I’ll be using the new stuff regardless. In fact, I can’t wait to use it in production to replace some currently very unpretty code.
In the end, it doesn’t really matter what they’re called (the pragmas and concepts), we will have to get used to new terminology anyway. So maybe it would be an opportune time, @jeremyruston having very succinctly outlined the reasons and origins, to put an end to the discussion and finalize the nomenclature?
I would propose, though, to create a “Transitioning for experienced users” (or similar) document / tiddler, which goes a bit more into detail than the “Introduction to v5.3.0” paragraph. Maybe some old-vs-new or what’s-now-possible examples. Something to “dampen the shock”, take the experienced TW’er by the hand and lead him into the promised land, if you know what I mean. And at the same time a concide reference. Much of the content could probably be found in this very thread.
There probably was something like this planned anyway or is already existing?
1 Like
I concur with @Yaisog and have said so multiple times. I have put arguments here and elsewhere including I believe reasonable alternatives and I forshadow the ambiguity and technical terminology, unlike earlier terms is going to reduce the uptake, or slow the learning for many users of tiddlywiki in the long run, and a p[ercentagew will abandone it because of this. I am an optimist that a little creativity can come up with terms acceptable to all and as for @Yaisog I will accept the result either way.
- I always need to check myself when communicating complex issues that I do not burden my language with difficult jargon and terms.
- A few of us have tried to call out this issue with these upcoming changes not because we don’t love the work / new-features, but because we are familiar with communicating with less experience users.
- Also please don’t dismiss this once again with we are not happy with change, I am very happy with change it’s why I chose IT at the bleeding edge as my career, but I also appreciate changes can be implemented at varying levels of quality.
- It is also very important we keep the communications channels open and demonstrate we are listening to each other’s differing perspectives.
I think I must withdraw part of my original propositions for the new names / concepts. That was informed at least in part by my bad memory and the amount of time passed since I had last read over the descriptions of the new features.
After the reprimand I got from @saqimtiaz I had another look. I realized that the differences between the old and the new are indeed substantial enough to warrant new names for the concepts, to avoid confusion. I am a bit embarrased by the lack of my own diligence.
As Saq rightfully noted, it is probably more important to agree on a name for the new concepts than one for the new pragmas. And maybe there is a way to bridge the gap beween the old and the new. How about we talk about Filter Functions and Macro Procedures?
Filter Functions would describe the intended (main) use and their content. And while not strictly macros from a CS point-of-view, procedures originate from macros and would be used mainly how a macro is used today. Even the docs and tags refer to macros sometimes in the context of procedures. So we combine terms that are familiar with ones that describe the underlying concepts better.
That way we could also stick with the current pragma names. I don’t have another, better proposal for those at this point. And there might not be a need.
3 Likes
A transition guide would be a great idea. The material in the OP of the PR is written from the perspective of existing users, and could serve as a basis for it.
I don’t think we’ve got viable alternatives yet. I went back through this thread collecting up the suggestions a couple of weeks ago. The suggestions that I can see for the pragmas all have the problem that they reuse words that already have an established meaning in TiddlyWiki (for example “operator” or “expression” instead of “function”).
I am hoping I read this all correctly, but if we are looking for a term to describe a pragma for defining a filter step, then why not just use \step? that way it is consistent with the filter docs etc.
Especially if you are looking to name other pragmas in this way (“I want to make a procedure so I will use the \procedure pragma”, etc)
The problem is that functions are not merely “filter steps”. They can be invoked in other contexts too. For example:
\function double(x)
[<x>add<x>]
\end
<$text text=<<double 23>>/>
I see. So these functions (as defined under the current “filter syntax”) are now going to be able to used outside of filters. Is there going to be a re-naming in the docs to generalize the filter syntax? If so, could it be generalized to “run”, “step” etc - as these are still good descriptors of the structure of these functions?
Just my thoughts as I try to understand these changes. Thanks for your response!
I don’t think that’s quite right. Functions do not have a definition under the current filter syntax.
I don’t think that introducing functions necessitates any changes to existing terminology.
One could say that a function definition consists of a parameterised filter expression, and that a function can be used to define a custom filter step by giving it a suitable name (ie starting with a period).
1 Like