Parameterised Transclusion Introduction

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.

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

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

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.

@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?)

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

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

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

Ah, you’re right!‍

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.

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?

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?

Please note I did say I will read through all the terms and proposed changes again. Macro, proceedure and functions are words that a close in meaning in english even if not in the implementation.

I will specifically respond to your question later.

From my perspective, as someone who has only hacked TW for my personal use, I find the names ‘procedure’ and ‘function’ to be confusing as they have semantics in programming languages that is different than TW. Why not use ‘\define2’ to define the construct called ‘procedure’? Then the term ‘procedure’ does not need to be used.
I would also use '\define-filter` and ‘\define-widget’ instead of ‘function’ and ‘custom widget’.

I empathise with your comments in the hidden reply and it should be visible.

Hey, thanks!

TiddlyTalk indicates that my post was flagged for review by administrators, and I got an automated message suggesting I review the community guidelines.

I got pretty frazzled when I could not find anything in the guidelines that would get my post withheld for review. Waste of time.

Come to find out, there was a request to have my post moved to a new discussion.

Talk.TiddlyWiki reminds me: to err is human, but to really foul things up requires a wonky programming algorithm…

One thing that must be said, is when we need to go from having macros to having macros, procedure’s and functions it would be simplified if we just have;

  • Macros (is and always will be macros)
  • Procedure’s (the new wiz bang macro)
  • \expression ie parametised filter/operators (or some other name, \filter \operator just not Functions)

The idea of going from macros to procedures is a simple “code switch” between the new and old way, of doing similar things. Thus it makes sense for these to be almost synonyms of each other.

The proposed “Functions” on the other hand is

a new way to encapsulate filter expressions with named parameters, including the ability to make custom filter operators"

Which is in many ways a very new thing, even if it makes use of the same features introduced in procedure’s.

  • The text above hints at a name ‘‘expression’’
  • the short form \expr is meaningful
  • an expression does not imply much more functionality as the word “function” would.

Further thoughts on the OT

  • The following comes from hours of working through the top level documentation at GitHub #6666 both to provide an informed response and to learn so I can help in the transition.
  • I have taken account of the Open Questions raised there.

Procedure vs define and macro

A question, if the word procedure is only used where we use \define for macros would it not work if the pragma was \macro as they are both called the same way?.

The advantage here is the old method would require knowledge of the \define but new users would gravitate to \macro, if someone says use a macro.

  • Further the way one calls a classic macro and the new procedure, do not differ as far as I can see. thus the only place is back in the pragma where the difference is clear \define vs \macro
  • If using procedure it is my view that \proc would be enough, and does not carry as much bagage.

A thought about custom widgets?

What if rather than $$widgetname custom widgets were named _$widgetname with overriding ones remaining $widget, thus the _ implies a custom one.

  • This standard keeps the the two distinct, and does not come close to confusion with $$$
  • The underscore, already used by some, could be used as a defacto custom indicator. For example;
    • if someone made a custom tag macro <<tag>> they would name it as follows <<_tag>> to imply its a custom version of the original.
    • It could also be used for custom variables <<transclusion>> vs <<_transclusion>> even classes ?
  • In all these cases in addition to the use in widgets, one could add/remove the _ to use a custom vs the default. The use of an extra $ is not as elegant.

Custom Filter Operator Functions

  • As I suggested previously I would prefer anything other than a \function pragma, perhaps \operator, \filter or \expression \exp short for \filter-operator.
  • I wonder if rather than a . in “custom Filter Operator Functions” we could use the _ (from above) which would carry this idea further, that is a custom filter operator uses an underscore
    • Total: <$text text={{{ [<total>_add-tax[1.125]] }}}/> to quote a GitHub example
  • Thus a function would be \expression expressionname() and a custom filter operator may be \expression _add-tax(p1 p2)

Transclude Widget Updates

  • What happens with legacy widgets that do already have $parameters such as the $tiddler $field $value or $name parameters?
  • I support the use of the $parameters widget, but do I understand it is also valid as a stand alone widget?
  • The current transclusion variable returns output of the form;
    which is a little confusing against the new form;
    • We must document this variation clearly, including the various forms that would now be available, along with the existing forms.
    • Perhaps we could have a new variable to return the “calling” transclusion? eg <<transcluded>> may return {FooBar||template|first|second|third}

Parameterised Transclusion

  • The \parameters pragma is consistent with the $parameters widget however can it also be used standalone, in an un-transcluded tiddler?
  • An important point here is this new approach is “only” position based, thus we need to put a little more effort into documenting it. see <<transclusion>> variable
    • As documented the ambiguity with the first parameter missing {{FooBar||second|third}} vs {{title||template|param1}} could we use an unlikely keyword to resolve this eg {{FooBar|_empty|second|third}}, it need only be valid if used in the first parameter position, if they must allow _empty to be passed they can use a subsequent parameter place.
  • At first glance, and a little longer, Its not clear to me the terms $fill and $slot, they are two sides of the same coin. $fill is what is to be placed in a $slot.
    • If $fill is only ever outside a procedure and $slot inside a procedure could they;
      • Be given the same name $content? $fill = $content, $slot=$content they are context sensitive (caution if nesting is possible)
      • Or a prefix $fill = $content, $slot=$_content or something less jargonised $slot=$include (somewhat resonates with transclude)
  • Again if rather than procedure we used the \macro pragma and $content and $include examples given would read;
\macro hello()
<div class="frame">
    <$include $name="greeting">
        Default text for the named slot "greeting"
    </$include>
</div>
\end

<$transclude $variable="hello">
    <$content $name="greeting">
        <h1>A heading</h1>
        <p>A paragraph</p>
    </$content>
</$transclude >
  • The above does not trigger in me a form of dyslexic response to the current terms. It seems much easier to read/understand and use.

Specifying Content to Display When Target is Missing

  • With this fall back to the content of the transclude if the $content is missing it is all more meaningful.
    • Either the transclude widget contains $content or it is the content.

In closing;

I am very excited about the possibilities these upcoming changes will introduce and appreciate @jeremyruston and the others reaching out. Many of my suggestions reflect other comments here and in GitHub so I don’t think I am saying anything controversial, just remember I have always focused on being a superuser and trying to understand core tiddlywiki features without core developer knowledge, and hope I can act as a “go between”, the new and naïve user and the great developers.

  • Please consider the meaning behind my suggestions, if not wholly in agreement with my suggested terms.

Long live tiddlywiki

1 Like

Macros need to go away. They should be deprecated, because they only cause problems in the way they are implemented at the moment. … They can be completely replaced in a consistent way by “procedures” and “functions”

I will write up a blog post with some example code, where I try to explain the problems we have with macros and how procedures and functions can fix that problem in a consistent way.

I personally could live with \expression instead fo \function

I think \filter is not possible since we already have a :filter run prefix … This would lead to misunderstandings since they are not interchangeable

IMO \operator is also not possible since a filter step is built is built from an “operator”, “suffix” and “parameters” …

An \expression can basically contain 1 or more filter runs

On the other hand an “expression” does not return a variable but a “function” does.