Great work S. S.! Super-helpful to anyone just getting into TW. And many thanks to Jeremy for the technical background. I am still wrapping my head around the design of TW and texts of this kind go a long way toward making it clearer.
Cheers, Stefano On Thu, Feb 7, 2019 at 6:24 AM Jeremy Ruston <[email protected]> wrote: > Hi SS > > Great stuff, thank you! I like the way that you’ve gathered input from > others and incorporated it smoothly, managing to keep a consistent tone of > voice suitable for beginners. > > As background, it might be helpful for me to explain a little of *why* > widgets exists… > > Consider a simple wiki with two tiddlers, Foo and Bar: > > “Foo” contains “I am Foo. {{Bar}}” > “Bar” contains “I am Bar” > > The result of rendering “Foo” should be “I am Foo. I am Bar”. So, a naive > algorithm for wikification would take the content of “Foo”, look for any > double braces, and then replace them with the content of the tiddler they > refer to. The processing would go something like this: > > 1. Get “I am Foo. {{Bar}}” from “Foo” > 2. Replace “{{Bar}}” with the content of “Bar” yielding “I am Foo. I am > Bar” > > Now imagine that the text of “Bar” is changed to “I was Bar”, and we want > to update the rendering. We can rerun the algorithm above and get “I am > Foo. I was Bar”, but we have to regenerate the entire rendering, even > though only one tiddler has changed. > > Using TiddlyWiki interactively in the browser depends on making the > refresh cycle as fast as possible. For example, when a button is clicked to > trigger a dropdown it actually just sets a tiddler value in the store that > causes the dropdown to be rendered when the display is refreshed. Thus we > want to make the refresh cycle as fast as possible. > > In particular, the goal is that, given the example above, when “Bar” > changes we don’t need to re-render the entire tiddler “Foo”. > > This is accomplished by building a render tree. The render tree for the > example above would be: > > * Text: “I am Foo. “ > * Transclusion: “Bar” > ** Text: “I am Bar” > > Given that render tree, we can efficiently extract the text of the result > by scanning the nodes of the tree and accumulating any “Text” nodes that we > find. > > If the tiddler “Bar” changes, then we need to scan the tree looking for > any transclusions that reference that particular tiddler. Those nodes will > need to be reconstructed from the new value of the tiddler, but the > surrounding nodes can be left untouched. > > So, that gives you the basis for a technical, developers explanation of a > widget: they are the units by which content is refreshed. > > There are a couple of further important details that shape the current > design. > > First, what we call parsing: this is the basic scanning of a block of text > to find bits of wikitext syntax (e.g. finding the “{{Bar}}” transclusion in > “Foo” above). The result of parsing is a tree that we then use to construct > the render tree. As a basic optimisation, we cache the parse tree for a > tiddler, and only regenerate it when the tiddler changes. > > Secondly, each node in the render tree may render one or more DOM nodes > that are attached to it. > > With those details, you’ve got a lightning overview of how widgets work. > It’s not suitable for beginners but it might help give you some background. > > Best wishes > > Jeremy > > > On 7 Feb 2019, at 08:16, S. S. <[email protected]> wrote: > > > It's taken a month of on-and-off giving it some attention. > > Here's the result! > > Widgets for Beginners > <https://00ss.github.io/documentation/tiddlywiki.html#Widgets%20for%20Beginners> > > Feel free to thrash it and make it better by leaving some critical > comments. > > -- > You received this message because you are subscribed to the Google Groups > "TiddlyWiki" group. > To unsubscribe from this group and stop receiving emails from it, send an > email to [email protected]. > To post to this group, send email to [email protected]. > Visit this group at https://groups.google.com/group/tiddlywiki. > To view this discussion on the web visit > https://groups.google.com/d/msgid/tiddlywiki/b86ff0f5-f9fb-478c-bbd7-4cdda2124a07%40googlegroups.com > <https://groups.google.com/d/msgid/tiddlywiki/b86ff0f5-f9fb-478c-bbd7-4cdda2124a07%40googlegroups.com?utm_medium=email&utm_source=footer> > . > For more options, visit https://groups.google.com/d/optout. > > > -- > You received this message because you are subscribed to the Google Groups > "TiddlyWiki" group. > To unsubscribe from this group and stop receiving emails from it, send an > email to [email protected]. > To post to this group, send email to [email protected]. > Visit this group at https://groups.google.com/group/tiddlywiki. > To view this discussion on the web visit > https://groups.google.com/d/msgid/tiddlywiki/8A45BF52-DF2F-4E99-ABCB-92D453D36DB6%40gmail.com > <https://groups.google.com/d/msgid/tiddlywiki/8A45BF52-DF2F-4E99-ABCB-92D453D36DB6%40gmail.com?utm_medium=email&utm_source=footer> > . > For more options, visit https://groups.google.com/d/optout. > -- __________________________________________________ Stefano Franchi [email protected] <[email protected]> http://stefano.cleinias.org -- You received this message because you are subscribed to the Google Groups "TiddlyWiki" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To post to this group, send email to [email protected]. Visit this group at https://groups.google.com/group/tiddlywiki. To view this discussion on the web visit https://groups.google.com/d/msgid/tiddlywiki/CAJODLwYB1ip6ZvP53FLhY-fi6n-PXVVgCHXfMqKyv%3DAr1qeXDQ%40mail.gmail.com. For more options, visit https://groups.google.com/d/optout.
