When to use procedures, and when to use transclusions?

[Sii]

With the new updates to TiddlyWiki it seems that now a lot of what we previously used macros for can now be achieved with transclusions.

For example I have a simple macro for creating a reference to a source:

<<ref "Source title" "Chapter">>

Now this could be achieved with:

{{ref|Source title|Chapter}}

Or I suppose even:

<$.ref source="Source title" chapter="Chapter />

Is there any particular reason to choose one over the other? What are the advantages of each?

[TW_Tones]

I imagine there may still be some variance in the details of the procedure, or the transuded tiddler you design. Perhaps both could be written efficiently or poorly and give different results.

never the less it is a useful question.

[jeremyruston]

@Sii

Is there any particular reason to choose one over the other? What are the advantages of each?

The key characteristic we can use to distinguish the examples you’ve given is whether they transclude a variable or a tiddler. That determines the namespace we’re using: that of variables, whose names are only locally unique, and that of tiddlers, whose titles must be globally unique.

The challenge with transcluding tiddlers is that short tiddler titles (like “ref”) are visible in the sidebar lists, which one doesn’t necessarily want for templates that are not useful to end users on their own. Using system tiddlers is less concise: for example {{$:/ref|Source title|Chapter}}.

There’s no such penalty for using short names for variables, but the converse is that there is no direct way to determine which tiddler was the origin of a particular definition, nor to easily browse the available variables/procedures/functions/macros.

Another useful dimension for analysing your three examples is that they offer different tradeoffs of verbosity vs. flexibility:

1. The transclusion syntax {{ref|Source title|Chapter}} is the most concise, but the least flexible as one can only pass parameters by position, with no named parameters
2. The macro/procedure syntax <<ref "Source title" "Chapter">> is less concise, but increases flexibility by allowing named parameters to be passed in any order
3. The custom widget syntax <$.ref source="Source title" chapter="Chaper"/> is a little more verbose but increases flexibility further by allowing blocks of wikitext to be passed as parameters via the <$slot>/<$fill> mechanism
   3.We could add the transclusion widget syntax <$transclude $tiddler="ref" source="Source title" chapter="Chaper"/> that is again less concise but increases flexibility by allowing the name of the transclusion target to be computed

The core has some inchoate policies to help navigate the choices:

• Transclude named tiddlers for system templates that are used to construct the system user interface and do not generally need to be invoked within ordinary textual content (eg $:/core/ui/PageTemplate)
• Transclude global variables for system templates that are used to construct user interface components that are frequently invoked in ordinary textual content (eg <<tag example>>)

I suspect that more nuanced guidelines might emerge with usage, and the community making discoveries about the new syntax.

[Hans_Wobbe]

Thank you, Jeremy. That’s a nice summary.

Regards,
Hans

[TW_Tones]

Yes, Thanks @jeremyruston this kind of “summary” from you is very informative and helps with the “Big Picture”.

Having had to make these choices in the past, as a result I have had to address some of the issues you raised for templates and macros, in both cases its about the ease of hiding or finding content in tiddlywiki;

@jeremyruston

The challenge with transcluding tiddlers is that short tiddler titles (like “ref”) are visible in the sidebar lists, which one doesn’t necessarily want for templates that are not useful to end users on their own. Using system tiddlers is less concise: for example {{$:/ref|Source title|Chapter}}.

• Another approach is to use templates named using an alternative unicode character set. They will at least not be found in the search unless the alternative name (or part thereof is used).
  • Eg From Math double-struck 𝕝𝕚𝕟𝕜𝕖𝕣 as a template name.
  • See this useful tool
• Using this mechanisium a simple descriptive name can be used eg Math double-struck > 𝕝𝕚𝕟𝕜𝕖𝕣 without risk of clash with user titles.
• We can easly include additional searches in the sidebar and standard search Customising search results However there is no current way without editing core tiddlers to introduce an exception filter, to the standard search,
  • for example “except the field/value [standard-search[hide]]”
  • such a method could be added to all standard lists as well.

@jeremyruston

There’s no such penalty for using short names for variables, but the converse is that there is no direct way to determine which tiddler was the origin of a particular definition, nor to easily browse the available variables/procedures/functions/macros.

• I have addressed this two ways in the past,
  • first a custom search of all tiddlers with the $:/tags/Macro tag searching for \define macroname
  • And a view template version that lists the definitions in the current tiddler, image below.
• Of course we now need to update this to include other tags, functions and proceedures etc… perhaps even designed for all pragmas.

Macro tools view template example;

In closing, a small subset of such tools could be available in a core plugin, or even added to the current “Internals” plugin.

• These could alter some of the choices as presented in your reply.

[Sii]

Thanks for the summary, that’s very helpful.