Parameterised Transclusion Introduction

Announcements
#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?

#25

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.

#26

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

#28

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

#29

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…

#30

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.
#31

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;
    Snag_1b41d72
    Snag_1b41d721136×74 4.45 KB
    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
#32

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.

#33

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.

#34

hmmm. … @jeremyruston … Looks good to me … would be worth a try to create a new code branch for these 3 suggestions.

#35
  • I argue nothing different, but I understand the idea of deprecation but I cant see how the current macro can go away, ever, for backward compatibility reasons?

I look forward to seeing this. I did some experiments on the pre-release to see how some simple concatenations worked, no luck so far. I fear they will be more verbose.

  • But I stand to be corrected.

My point here is about what we call the the new macros\procedures. Lets call them macros. Be they the ones created using the \define pragma, or the new pragma, one of my suggestions being \macro or the current \procedures they still do macro things.

The easiest way to deprecate something is simply to use the replacement.

As far as I can see the word procedure is just a synonym for macro in the pragma ONLY. Macro is I believe available. Someone new to tiddlywiki gains nothing seeing there are macros and procedures. Lots of prior content will say use a macro to do that, when now we want them to use the new approach.

  • Lets just make use of the new macros, using the \macro pragma?
  • But as I understand the new function returns a particular type of variable, used in a particular way. As a filter, a filter-operator, a filter-expression but the word function implies a much more general use. Maybe we can use it in the future for a real function :nerd_face:
  • perhaps a synonym of filter a sieve
#36

That’s a different topic. … We will need to make a UI overhaul and update the existing code to “best practice”. … Since many users get their inspiration from the core “improved” code will be generated of time. … BUT … as long as the core needs “macros” they will have to stay anyway.

#37

:slight_smile: … yea … You touch the pain point, but I think I do have some understandable examples here. A bit of polishing needed, but I think it looks good already.

1 Like
#38

I think you have an argument here. … We would need to test it a bit more.

1 Like
#39

I don’t think that the term “macro” works for the new procedures because in programming contexts the term “macro” almost always indicates a preprocessor where expansion occurs via textual substitution (some examples are C/C++ and Rust). We take the term from programming, and so it would be unhelpful to take an existing term from the field and use it to mean something different. Meanwhile, “macro” covers very well the functionality of the existing macros.

#40

That is a good arguement but can we find another term? I am yet to understand it deeply enough, but I am working on it. Can we find a term that describes it without miss representing it?.

Sure I may need to concede procedure, but I will continue to research it. I have a hunch that I cant yet put my finger on.

#41

The changes to the transclude widget attributes don’t affect any of the attributes for the other widgets.

What exactly do you mean by “stand alone”? It only makes sense to use the parameters widget in some context in which you can pass parameters. That could be by transcluding a tiddler or invoking a macro/procedure/widget (i.e. transcluding a variable). Under the covers, all of those are handled by the transclude widget. The parameters widget is handled by the transclude widget code.

Could you share an example of what you mean? You can place the parameters widget whereever you want, but it won’t have any effect unless you have a way of passing parameters into the widget.