Understanding TW code

[joearms]

Hello,

I'm trying to understand how to program the TW - right now what I'm doing

is reading the source of individual tiddlers and guessing what the

code means.

This is a rather time consuming process, and unsatisfactory, to the

extent that if something works, I'm not sure if it works because I

accidentally got it right or by design.

Even simple things like 'can I have white space' is unclear to me.

I observed by investigation that <<tag "About">> gives me

a "tag button" (is that what its called) but

<< tag "About">> does not -- but now I don't know if white space

following "<<" is a bug in the implementation, which I should chase

up or is by design.

So what I'd like is a accurate description of the tiddler language.

What would help is a line by line commentary of some typical

code.

I was trying to make a button which when clicked would open

today's journal entry.

I found this code: (it's as is and unformatted since I

don't know when I can add white space or even line feeds)

\define journalButton()

<$button tooltip={{$:/language/Buttons/NewJournal/Hint}} aria-label={{$:/language/Buttons/NewJournal/Caption}} class=<<tv-config-toolbar-class>>>

<$action-sendmessage $message="tm-new-tiddler" title=<<now "$(journalTitleTemplate)$">> tags="$(journalTags)$" text="$(journalText)$"/>

<$list filter="[<tv-config-toolbar-icons>prefix[yes]]">

{{$:/core/images/new-journal-button}}

</$list>

<$list filter="[<tv-config-toolbar-text>prefix[yes]]">

<span class="tc-btn-text"><$text text={{$:/language/Buttons/NewJournal/Caption}}/></span>

</$list>

</$button>

\end

<$set name="journalTitleTemplate" value={{$:/config/NewJournal/Title}}>

<$set name="journalTags" value={{$:/config/NewJournal/Tags}}>

<$set name="journalText" value={{$:/config/NewJournal/Text}}>

<<journalButton>>

</$set></$set></$set>

I guess that 

\define journalButton()

...

\end

defines a macro -- and that <<journalButton>> evaluates the macro

I suppose that

<$button tooltip={{$:/language/Buttons/NewJournal/Hint}}

...

transcludes the value of the the hint when the

when the macro is evaluated (or is it when the macro is defined)

I'm also not sure about what $set does - seems to manipulate some

variables.

I'm unsure as the lifetime of this journalButton object - I think

(don't know) that this tiddler is dynamically evaluated

when activated - but do the definitions outlive the activation?

I suspect I only need to understand certain core concepts

and grammar rules, but I don't like reading code and

guessing what it does.

So finally here's my question:

Are their any good write ups of the syntax and semantics of the

tiddler language? - and some annotated examples - line by line

detailed explanations. There seem to be hundreds of documents

describing simple translusion -- the {{Insert Me}} and

[[Insert Me]] kind of stuff - I get that - but the next step is confusing me.

Cheers

/Joe

[Mat]

Hi Joe.

You have much, and good, documentation at tiddlywiki.com

(I'm curious, for constructive purposes: How come you have not seen this?)

Some specific questions of yours:

I guess that 

\define journalButton()

...

\end

defines a macro -- and that <<journalButton>> evaluates the macro

Correct. And something like <<foo bar "baz frotz">> would be a macro foo with the two parameter values bar and baz frotz

You must not insert space right after the "<<".

 

I suppose that

<$button tooltip={{$:/language/Buttons/NewJournal/Hint}}

...

transcludes the value of the the hint when the

when the macro is evaluated (or is it when the macro is defined)

Well, more correctly it should be 

<$button tooltip={{$:/language/Buttons/NewJournal/Hint}} >
...
</$button>

Yes, the parameter named tooltip does in this case take a transcluded value as argument, i.e whatever is inside that hint tiddler.

<$xxx>...</$xxx> are widget calls whereas <<yyy ...>> are macro calls. Widgets are more fundamental, comparable to html markup and are defined with javascript. Macros are higher level and typically defined in wikitext using the /define pragma.

I'm also not sure about what $set does - seems to manipulate some variables.

https://tiddlywiki.com/#SetWidget

I'm unsure as the lifetime of this journalButton object - I think

(don't know) that this tiddler is dynamically evaluated

when activated - but do the definitions outlive the activation?

Yes definitions, i.e macros, 'live on' locally. But/and if you tag the tiddler with "$:/tags/Macro" you make the macros global.

Are their any good write ups of the syntax and semantics of the

tiddler language? - and some annotated examples - line by line

detailed explanations. There seem to be hundreds of documents

describing simple translusion -- the {{Insert Me}} and

[[Insert Me]] kind of stuff - I get that - but the next step is confusing me.

Again, tiddlywiki.com is the best source for docs. But when you say "hundreds of docs" maybe you've already seen this? Again, if you haven't it would be valuable to know why.

Tobias has a great site that may be of use: http://tobibeer.github.io/tb5/#Welcome

There are also other individual initiatives but none that I can refer to off the cuff.

I get the impression that you're knowledgable enough to read wikitext code though. If you have specific snippets you need explanations for, i.e where you cannot simply use tiddlywiki.com to look up e.g <$set> (i.e the SetWidget) then you're more than welcome to post it on the boards. At this basic level I'd probably recommend posting on the main board where you have more readers.

All best and warmly welcome to TW!!!

<:-)

[joearms]

On Sunday, 4 March 2018 19:11:43 UTC+1, Mat wrote:

Hi Joe.

You have much, and good, documentation at tiddlywiki.com

(I'm curious, for constructive purposes: How come you have not seen this?)

I have and I keep a local copy and search in it.

 

Some specific questions of yours:

I guess that 

\define journalButton()

...

\end

defines a macro -- and that <<journalButton>> evaluates the macro

Correct. And something like <<foo bar "baz frotz">> would be a macro foo with the two parameter values bar and baz frotz

You must not insert space right after the "<<".

You ask later why I asked this - I think the reason has to do with terminology

once I realised that this was a macro then I could search for the word macro 

but to start with I didn't realise this <<...>> things were macros

There are a lot of strange (to me) terms - what's a story and a story list

If I search for terminology I get nothing :-)

Once I know what things are called I can start searching for them

 

 

I suppose that

<$button tooltip={{$:/language/Buttons/NewJournal/Hint}}

...

transcludes the value of the the hint when the

when the macro is evaluated (or is it when the macro is defined)

Well, more correctly it should be 

<$button tooltip={{$:/language/Buttons/NewJournal/Hint}} >
...
</$button>

Yes, the parameter named tooltip does in this case take a transcluded value as argument, i.e whatever is inside that hint tiddler.

But when? when the tiddler containing the code is saved or when the tiddler calling the 

macro is evaluated? -

 

<$xxx>...</$xxx> are widget calls whereas <<yyy ...>> are macro calls. Widgets are more fundamental, comparable to html markup and are defined with javascript. Macros are higher level and typically defined in wikitext using the /define pragma.

 

I'm also not sure about what $set does - seems to manipulate some variables.

https://tiddlywiki.com/#SetWidget

So it's a let statement, something like

    

         let x = ...

         in

             ...

         end

         

 

I'm unsure as the lifetime of this journalButton object - I think

(don't know) that this tiddler is dynamically evaluated

when activated - but do the definitions outlive the activation?

Yes definitions, i.e macros, 'live on' locally. But/and if you tag the tiddler with "$:/tags/Macro" you make the macros global.

OK 

Are their any good write ups of the syntax and semantics of the

tiddler language? - and some annotated examples - line by line

detailed explanations. There seem to be hundreds of documents

describing simple translusion -- the {{Insert Me}} and

[[Insert Me]] kind of stuff - I get that - but the next step is confusing me.

Again, tiddlywiki.com is the best source for docs. But when you say "hundreds of docs" maybe you've already seen this? Again, if you haven't it would be valuable to know why.

I think it's two things - the terminology is unfamiliar (I'm catching up though)

and my expectations.

I'm kind of used to the traditional programming primers that start with hello world

and slowly walk you through the language.

I'd kind of hoped to find a traditional description of the tiddler language, starting with lexical conventions

and terminology.

 

Tobias has a great site that may be of use: http://tobibeer.github.io/tb5/#Welcome

There are also other individual initiatives but none that I can refer to off the cuff.

I get the impression that you're knowledgable enough to read wikitext code though. If you have specific snippets you need explanations for, i.e where you cannot simply use tiddlywiki.com to look up e.g <$set> (i.e the SetWidget) then you're more than welcome to post it on the boards. At this basic level I'd probably recommend posting on the main board where you have more readers.

Thanks I'll mail the main board.

 

All best and warmly welcome to TW!!!

Thanks - it's great

 

<:-)

And a followup question.- I searched for semantics evaluation etc. but no hits.

Is there a description of how a tiddler gets turned into HTML?

If I were to implement this I'd be thinking

tokenize -> parse -> transform -> render

After parsing I'd get an abstract syntax tree (AST1) representing the tiddler.

I'd evaluate this to produce a second AST representing (abstracted HTML)

then I'd render this.

Is it done like this?

It would be very helpful to see the AST1 after parsing (if this is the way it was done)

Of course it might be implemented by some other means (like directly manipulating the

DOM) during parsing.

Cheers

/Joe

 

[Simon Huber]

And a followup question.- I searched for semantics evaluation etc. but no hits.

Is there a description of how a tiddler gets turned into HTML?

If I were to implement this I'd be thinking

tokenize -> parse -> transform -> render

After parsing I'd get an abstract syntax tree (AST1) representing the tiddler.

I'd evaluate this to produce a second AST representing (abstracted HTML)

then I'd render this.

Is it done like this?

It would be very helpful to see the AST1 after parsing (if this is the way it was done)

Of course it might be implemented by some other means (like directly manipulating the

DOM) during parsing.

Hi Joe,

Have a look at the "Tools for exploring the internals of TiddlyWiki" in the ControlPanel under Plugins - get more plugins - open plugin library

that gives you new insight looks in the preview panel like "parse tree" or "widget tree" 

you can then choose them in the dropdown beneath the "eye" button in the editor toolbar

Simon

[joearms]

On Sunday, 4 March 2018 20:10:33 UTC+1, Simon Huber wrote:

And a followup question.- I searched for semantics evaluation etc. but no hits.

Is there a description of how a tiddler gets turned into HTML?

If I were to implement this I'd be thinking

tokenize -> parse -> transform -> render

After parsing I'd get an abstract syntax tree (AST1) representing the tiddler.

I'd evaluate this to produce a second AST representing (abstracted HTML)

then I'd render this.

Is it done like this?

It would be very helpful to see the AST1 after parsing (if this is the way it was done)

Of course it might be implemented by some other means (like directly manipulating the

DOM) during parsing.

Hi Joe,

Have a look at the "Tools for exploring the internals of TiddlyWiki" in the ControlPanel under Plugins - get more plugins - open plugin library

I installed this and reloaded

 

that gives you new insight looks in the preview panel like "parse tree" or "widget tree" 

YES !!!!

 

you can then choose them in the dropdown beneath the "eye" button in the editor toolbar

WOW - fun

Thanks a lot

/Joe

 

Simon

[PMario]

On Sunday, March 4, 2018 at 4:52:18 PM UTC+1, joearms wrote:

I'm trying to understand how to program the TW - right now what I'm doing

is reading the source of individual tiddlers and guessing what the

code means.

This is a rather time consuming process, and unsatisfactory, to the

extent that if something works, I'm not sure if it works because I

accidentally got it right or by design.

Hi,

You should start here: https://tiddlywiki.com/#WikiText
The basics are at the top of the list.
The further down you get, the more advanced the stuff gets.

-- A bit of History --------------------

The first alpha-11 was released Nov 2013,
V5.1.0 which is TW5 Version 1.0 was released Sept 2014,
We reached V5.1.15 now. ... So trying to understand everything in a week or two will be hard ;)

So just keep asking!

Since V5.1.0 Backwards compatibility is one major goal, which has advantages and disadvantages.

The advantages imo are obvious. ... The disadvantages are, that there are some inconsistencies, which are kept for compatibility reasons.

White space is 1 of them. ... I'll crate a new post for this one.

You can see the history here, if you want.

have fun!
-mario

[PMario]

On Sunday, March 4, 2018 at 4:52:18 PM UTC+1, joearms wrote:

...

I found this code: (it's as is and unformatted since I

don't know when I can add white space or even line feeds)

\define journalButton()

<$button tooltip={{$:/language/Buttons/NewJournal/Hint}} aria-label={{$:/language/Buttons/NewJournal/Caption}} class=<<tv-config-toolbar-class>>>

First off all: Whitespace matters - but not always!

That's one reason, that makes advanced TW UI based syntax "a nightmare". That's a very early decision, which makes sense for "plain text" writers. -> Standard users.
But for developers, it makes live much harder, since you basically need to know the parsing rules, by heart. Which is kind of impossible.

In "user-mode" separating 2 paragraphs only needs 2 "carriage returns" and a paragraph will be created, which is simple.
Have a look at the "Wikitext link from the other post"

Parsing the wiki-syntax has 2 modes:

 - Inline-mode which is used for eg: ''bold'' or //italic// and
 - Block-mode which is used for eg: paragraphs, bullet lists, numbered lists and so on.

A basic rule for UI developers is: Everything needs to be inline,

 ... because "whitespace matters" also for UI stuff :/.

And ATM backwards compatibility forces us to keep it that way for some more time. ... With V5.1.15 a \whitespace trim  option was implemented, which should improve the situation in the future. ... If someone rewrites the core UI in a readable way, with out breaking the whole thing. ... So time will tell.

using \whitespace trim with macros needs to be activated per macro and looks like this:

\define macro-name()
\whitespcae trim
... your code here ...
\end

You can make your code more readable. ... BUT some widgets will need a "mode=block" parameter, since the default for widgets is "mode=inline" !!!!!

The negated version is:

\whitespcae notrim


Also see: pragmas.

-mario

[PMario]

On Monday, March 5, 2018 at 12:21:08 PM UTC+1, PMario wrote:

Parsing the wiki-syntax has 2 modes:

 - Inline-mode which is used for eg: ''bold'' or //italic// and
 - Block-mode which is used for eg: paragraphs, bullet lists, numbered lists and so on.

uups forgot one important thing:

Block mode is triggered using 2 CRs ... like for paragraphs. AND a HTML paragraph element is created in the DOM, which is OK for users, but most of the time not wanted for UI

-m