Parameterised Transclusion Introduction

Announcements
#5

In my opinion having macro, function, and procedure at the same time is confusing and difficult to follow, especially for new commers. It seems for backward compatibility the macro will be kept and new term procedure is added. I thought can we use def like Python

\def name()   ...

So, this covers both: the old macro, and the new procedure.

This even can replace functions, as function are filter expression, so TW core can check the \def name() ... to see if it contains a filter expression or not! If from performance point of view this has any impact, then we can use a special naming conversion like below

\def _name()  [tag[HelloThere]]

The above definition states that a pragma name has single underscore, so it is a filter expression.
We can think to better prefix.
I know defining function in this way will affect the [function[myfn],[value],...] syntax, but then why not to use [_myfun[value],...]

NOTE: Like Python, I mean here we can use name mangling and this can allow use to have different functionality with simple \def name() ...

2 Likes
#6

If we can avoid $$, it is better to avoid. Like @twMat I think $ signals system and more $$, makes them scary for non-developers. So, if technically it is possible use the single $ and just use some name mangling here again.

I like the . too much. Small, and pretty. As end user or developer, we don’t use CSS class with the prefix (.) inside filters, or as widget attributes. There are exceptions (I think, one place . is used with CSS class is tm-focus-selector), but I can understand @telumire concern in this regard.

1 Like
#7

I like this!

\operator myoperator() ...

...

<$list filter="[operator[myoperator]]"/>

The operator term matches existing documentation, which could be completed with a link to “custom operators”…

Fred

1 Like
#8

I agree with @telumire and @twMat in their doubts and their proposal for new syntax look good. But how @Mohammad had pointed the new syntax could be confusing for many users and he has a gread idea, pointing to the use of the abbreviation.

For me, thinking about syntax and functionality:

  • macros are smart text/html templates
  • procedure looks like a macro, but it is better.
  • function is a smart template for filters
  • widget is also like a template, but the new commers won’t really use it, IMHO.

My conclusions/ideas:

  • Mantain define for macros and use def for procedures (“Procedures are the modern replacement for macros”).
  • We could also use the same pragma def for functions. But if we want differenciate it, we could use a symbol as the pragma widget does. Something like:
 \def $add-tax(rate:"1.10") [multiply<rate>]

I have took the $ from widget syntax, but it could be any other symbol like @. I don’t know if this symbol could be used in the filter syntax, but it adds visibility to the custom filter operator. For comparasi
[<total>.add-tax[1.125]]
[<total>_add-tax[1.125]]
[<total>$add-tax[1.125]]
[<total>@add-tax[1.125]]

  • I have a doubt about the use of fuction in [function[myfn],[value],...], it more complex that the use as custom filter operator [.myfn[value]] and the use of macro with parameters in filters. So I will prefer use filter<myfn "value"> if it isn’t a complete filter expression.
1 Like
#9

I like it!

It “calls” for the external operator - I like it!

#10

Realization:
Significantly simplify the syntax by reusing the same structure for all three “cases”.

Here are three gradually simpler syntaxes. I’m not sure what is possible to implement. They all show the following three things:

the definition

the direct call to the operator function in a filter

the call to the "operator" filter operator in a filter

Thus:


Joint parameter list everywhere, like in the pragma:


Joint parameters and soft brackets, like in the pragma:


There can be little disagreement that the latter is the simplest to learn and remember, but I can imagine this syntax is just not possible for some very good reasons.

#11

I have another doubt, it is about if for have global use of procedures, functions and widgets, we will have to use their own tag or we will use $:/tags/Macro. In this first case (several tag), IMO, this would be overcomplicating the functionality. It will be a point in fovar of the solution of same pragma (\def) and same tag ($:/tags/Macro).

#12

Good point. I have no idea what Jeremy has in mind. One idea could be a general tag for global stuff, e.g $:/tags/Global or something similar… even if I personally think the idea to use tags to control tiddler functionality is a bit quirky. It seems more like a setting for the tiddler that, rather than manually typed, should be selected more akin to how the tiddler type is selected.

TW v5.3.0-pre: It is proposed to add $:/tags/Global for global procedures, functions, widgets, macros
#13

I have only skimmed the conversation but I’d like to voice my strong opposition to having both \def and \define and having them do different things. It’s super confusing and people will keep mixing them up. if anything I think going verbose is better than adding another layer of arcane symbols that do magic things without any regard to what the symbol means in a language or culture.

I don’t have much of an opinion for using $$ for custom widget beyond not fully understanding why - I presume it’s for future-compatibility to avoid future core widgets accidentally getting overridden by custom ones? I’d wonder if a better option wouldn’t be to just use single $ and require explicit overriding, something like:

\widget $myCustomWidget()
// vs
\widget $codeblock()
// vs
\widget override codeblock()

The first one would define a custom widget, the second would do nothing and show a warning to the user of the mistake, the third would actually and intentionally override a built-in widget. Buuuuut… I am a very hands-on and technical person who likes to keep things perfectly clean and pristine. I imagine for a regular user the warning could be confusing. Than anything.

I am a little surprised with the name of the <$genesis> widget. I don’t think it matters for non-programmers what’s the name ultimately, and for programmers <$super> or <$parent> would’ve been much more obvious (and both are a simpler word than genesis which might be tougher to non native English speakers who are not fluent).

I like the idea of functions and I think it’s fine to keep them named that way to avoid the confusion with filters in general, but I don’t see any mention of how they behave with input if you invoke them inside a filter, though I am going to guess they just execute the same way - once per input.

I don’t quite understand the parameterised transclusion though, the word doesn’t appear in documentation and the only difference… I reread the docs and understand it now. The fill/slot feels kinda clunky to use but I’d put the blame on this being HTML, I don’t think there’s a better way to handle it.

#14

Please note I’ve updated my syntax proposal here above. I’d love to hear which ones are at all possible.

#15

In order to retain the ability to use variables or text references for operator names and parameters, my preferred syntax would rather be:

    \operator myoperator(param1, param2) ...

    [...@myoperator[val1],[val2 ]...]

    [...operator[myoperator],[val1],[val2]...]

Please note the slight variation in the operator filter operator invocation, where nested square brackets are avoided.

With this proposal one could use this legit call:

[...@myoperator<param1var>,{param2ref}...]

where the parameters values can be retrieved in variables or text references, or:

[...operator<namevar>,<param1var>,<param2var>...]

where even the name of the user-defined operator can be parameterized.

Fred

1 Like
#16

That is quite true! In new 5.3.0+ we should use the new syntax. The reason \define is kept is backward compatibility!
So, in new release we should not use mixed of them and doc shall be updated accordingly.

Side Note:
One issue with TiddlyWiki doc (tiddlywiki.com) is, it shows the doc from 5.0.0 up to 5.2.3 and this confusing! For example while we have $let, the $var shall be not shown in the doc and it should be left up to the version $let introduced.

#17

@jeremyruston

Is the introduction of Parametrized Tranclusions an opportunity to harmonize how parameter values are appointed in the pragma definition (as default values) and for widget attributes in invocations? I’m referring to the use of both : and = i.e:

\define foo(param:default)
<<foo param:myvalue>>
<$macrocall $name="foo" param=myval />
<$widget param=myvalue />

Note that it even isn’t enough to distinguish between definitions and calls to know what sign is to be used but it really depends on what kind of invocation you use. And with the introduction of custom widgets this discrepancy will stick out even more.

(BTW, I was surprised to realize that in javascript functions, default parameter values are actually set with = so I can’t help but wonder what made TW settle for : in the past?)

#18

There is a very early discussion somewhere at github and it seems we made the wrong decision

\define test(x:default)  ... IMO ":" is OK here, probably could be "=" too

<<test x:10>> ... : .. IMO was the wrong decision
\newenvironment for custom definitions
#19

@jeremyruston

‍1) It seems the transcludewidget will become a very versatile tool, both allowing to present content from transclusions and evaluate procedure calls by replacing the macrocall widget.

I like it! But it stretches the concept of “transclusion”. Maybe we should reconsider the widget name? “Transclusion” is not a term most people are familiar with. The way it is used with this OP I think the widget could instead be called e.g the “presentation” widget.

‍2) It would be useful with a clear overview of what the OP “renders superfluous”. I envision a table with two columns for side-by-side comparison of “the legacy way” vs “the recommended way”.

#20

I think we should point to Transclusion - Wikipedia to explain it in more detail. Especially the “parameterized” section is exactly to the point of the new functionality the transclusion widget has now.

1 Like
#21

Ah, you’re right!‍

#22

Any thoughts on the ideas brought up here?

Further; regarding the separated filter operators, (a.k.a function but proposed to be renamed into operator) I’m wondering if there can be a way to reuse the defined operators outside of the tiddler? I.e to call for it as if a macro or a transclusion? Every now and then I need to programmatically access and reuse filters defined elsewhere.

#23

Thanks for the invitation

First I will give my view of the current terms and return and edit after re-reading about each to make any suggestions. I acknowledge the issues and difficulty choosing such names and this is simply my perspective.

  • I am glass this question has being asked, because to be honest I am concerned about the long term viability of tiddlywiki if it gets too “termalogically complex”.

Is “procedure” confusing for the replacement for macros? It’s definitely quite long to type…

  • Yes it is confusing, as is the function which follows, they are really only synonyms for macro and as they do not strictly mean formal definitions of those terms they are very misleading because I believe the words make promises they do not deliver.
  • If we must use this proc is in my view a reasonable short form, and a 4 letter word.
  • Is _macro out of the Question?

Is “function” the best word for custom, parametized filter operators stored in variables?

  • I don’t think it is, just as for procedure. Since variables can contain anything including filters, it seems a little odd, I would be more inclined to tie it back to the words “filter” somehow, and the suggested operator seems reasonable to me.
  • It would be less imposing to use func as well

Is $$ the best prefix for custom widgets?

  • It looks to me like a type-oh when I read it, one I have often done/caused when pasting system tiddler titles.
  • Is the ¢ cent for custom widgets a possibility?. I am sure we can support additional character entry especially just for coding.
  • personally I would find $_ or _$ more meaningful and perhaps the _ could be used for these second order terms, ie variations, or customisable versions of existing terms simply get the _ treatment ?

Is . (period) the best prefix for custom filter operators?

  • Unfortunately no, its too small and one of the most common used .class is common in definition and application to wiki symbols eg *.d do this done item with d class applied

Are the new <$slot> and <$fill> widgets the best names?

  • I don’t like them because I do not use these words in any kind of code I use, I feel there must be something better. I will revisit after trawling the documentation again.
  • I don’t know enough to say, but could these be arbitrary tags that have a default but you could provide a different name eg have a slot parameter?, so then you could use slot=content and use <content></content> or <content> </> or other section name.

The problem with all these terms is as far as the user is concerned it is an example of the “cart before the horse”, until they have the terms to learn with, they can’t make good suggestions, but once the terms are decided they have to live with them.

  • Even although I am an Information Technology Professional myself, I am somewhat reluctant for us to adopt words sourced in our industries jargon.
  • I would much prefer these terms to be closer to plain English as long as it does not mislead.
  • Even if I say so, I think I am good in “naming competitions” and others seem to think so, including some “prizes” I have won demonstrate this, but I am really struggling with understanding the full implications of these new terms, such that I can’t yet easily help find better names.
    • Part of the problem learning these changes has being the existing working title “terms”, so I am confident the existing ones could be better.

If someone who understands each of these terms as they stand, could provide a plain language explanation of what they are for, and where they are used, I think it may be easier to find new and better terms. This is not a technical summary but what function/purpose to they have?

#24

Thanks @TW_Tones

If procedures/functions look like synonyms for macros then we have obviously failed to get across what any of this is about.

Did my OP at the top of this thread make sense? There’s a little section about parameterising SVGs, does that look like something that can be done with macros?