A few design/terminology questions to inform Grok TiddlyWiki updates

[sobjornstad]

Hey all,

The Grok TiddlyWiki updates are coming along. I’m a little behind on my original schedule but am hoping to catch up in the next week or two and get something out for review to the folks who said they were interested.

I have a couple of questions to help me explain everything effectively, especially for @jeremyruston and other folks who were involved in developing the new features, but anyone should feel free to weigh in:

1. What’s the reason for needing a . in function names to call them directly from filters? At first I was like “well if not, you could confuse them with fields or built-in operators,” but of course fields can also contain periods so this doesn’t help anything, and there’s already the potential for a conflict between fields and built-in operators and the built-in just wins there.
2. Why does calling a function with <<angle brackets>> yield only the first output tiddler? I know that filtered transclusions do the same thing when you use them as attribute values, but angle brackets do this even when placed directly in rendered wikitext. I assume there is either some logical reason or a matter of technical convenience, and would like to be able to explain it.
3. The new <% %> syntax is called “conditional shortcut syntax” in the docs. What, though, do you call an instance of using this syntax? I’ve been saying “a conditional expression,” or “conditional inclusion,” but I’d love to avoid making up terms that other people in the TiddlyWiki community don’t agree with. (draft tiddler)
4. Similarly, when you put a . in a function or widget name, is there an established name for this? I’ve been calling it “namespacing,” because I am in the habit of prefixing things with an abbreviation for the name of my wiki or plugin, especially as a way to avoid name collisions. But technically everything remains in the same namespace, so I’m not sure if there’s a better way to describe it.

Thanks!

[saqimtiaz]

@sobjornstad

What’s the reason for needing a . in function names to call them directly from filters?

To ensure that user defined functions do not clash with those written in JavaScript, otherwise introducing any core operators in the future would risk breaking user code as the core operator would win.

With the exception of the draft.of and draft.title fields, the core does not use the dot character in field names. So consistency in one’s own wikitext code and using the dot character only for functions does help make code easier to understand.

@sobjornstad

Why does calling a function with <<angle brackets>> yield only the first output tiddler?

There is currently no standardized robust format in which we can serialize a list of tiddlers as plain text. The title list format for example, is brittle if the tiddler title itself contains leading and trailing square brackets. Comma separated titles run into the same problem when dealing with titles including a comma.

@sobjornstad

The new <% %> syntax is called “conditional shortcut syntax” in the docs. What, though, do you call an instance of using this syntax?

Conditional expression is how I think of it myself but consensus on this would indeed be very welcome.

[jeremyruston]

@saqimtiaz

Conditional expression is how I think of it myself but consensus on this would indeed be very welcome.

A couple of thoughts:

• We might introduce shortcut syntax for <%switch%>/<%case%>. Perhaps it would be called the “switch shortcut syntax”
• I think of the term “shortcut syntax” as applying to any wikitext construction that implicitly generates widgets. That would mean that things like the list syntax would be under the same heading, albeit we omit the word “shortcut” when it is not needed
• On that basis, we might want to consider just calling it the “conditional syntax” in the docs, and not raise the question of what “shortcut” means
• We might need a term for the syntax <%...%></%...%>, perhaps they are “shortcut tags”?

[pmario]

@sobjornstad

Similarly, when you put a . in a function or widget name, is there an established name for this? I’ve been calling it “namespacing,” because I am in the habit of prefixing things with an abbreviation for the name of my wiki or plugin, especially as a way to avoid name collisions. But technically everything remains in the same namespace, so I’m not sure if there’s a better way to describe it.

We already use the word “namespace” for eg: x/name/space/tiddlers or $:/name/space/tiddler – Basically everything what the tree-macro can handle and display as a tree can be called a “namespace”.

For functions and widgets that contain a dot we could use “custom function” or “custom widget” – just a thought.

[sobjornstad]

@saqimtiaz

To ensure that user defined functions do not clash with those written in JavaScript, otherwise introducing any core operators in the future would risk breaking user code as the core operator would win.

I agree that this is a good idea; but isn’t the same thing true of fields? Were we just not thinking that far ahead back then? Or thought it would be too much of an imposition on field-naming flexibility?

[sobjornstad]

@pmario

For functions and widgets that contain a dot we could use “custom function” or “custom widget” – just a thought.

I’m specifically in need of a participle for the action, and/or a word for the prefix that you add to disambiguate specifically. Like I have a procedure I want to call float-image, and I use m2.float-image to mark it as part of M2 and separate it from anyone else’s float-image. What’s that called?

[pmario]

m2.float-image … would call that a vendor-prefix. They would be similar to what we discuss for global TW functions. For the core we prefix them with tf. eg: tf.function-name

[Mohammad]

A side note:
I would recommend to emphasis on using functions for making user filter operator and defining filters (and complex filter expressions with several runs).