[twdev] Re: Understanding TW code

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

-m 

-- 
You received this message because you are subscribed to the Google Groups 
"TiddlyWikiDev" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to tiddlywikidev+unsubscr...@googlegroups.com.
To post to this group, send email to tiddlywikidev@googlegroups.com.
Visit this group at https://groups.google.com/group/tiddlywikidev.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/tiddlywikidev/3f2fd689-b2dd-4c89-a9c7-1cbd082f62b7%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[twdev] Re: Understanding TW code

[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=<>>
>

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

-- 
You received this message because you are subscribed to the Google Groups 
"TiddlyWikiDev" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to tiddlywikidev+unsubscr...@googlegroups.com.
To post to this group, send email to tiddlywikidev@googlegroups.com.
Visit this group at https://groups.google.com/group/tiddlywikidev.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/tiddlywikidev/0f688d32-e475-4321-9daa-900ed3234ec7%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[twdev] Re: Understanding TW code

[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

-- 
You received this message because you are subscribed to the Google Groups 
"TiddlyWikiDev" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to tiddlywikidev+unsubscr...@googlegroups.com.
To post to this group, send email to tiddlywikidev@googlegroups.com.
Visit this group at https://groups.google.com/group/tiddlywikidev.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/tiddlywikidev/5717ed15-744c-4ed5-a0a6-8b6a58152d3c%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[twdev] Re: Understanding TW code

[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
>

-- 
You received this message because you are subscribed to the Google Groups 
"TiddlyWikiDev" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to tiddlywikidev+unsubscr...@googlegroups.com.
To post to this group, send email to tiddlywikidev@googlegroups.com.
Visit this group at https://groups.google.com/group/tiddlywikidev.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/tiddlywikidev/2362eff9-ae75-4eae-9a6b-2ff76908aaa8%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[twdev] Re: Understanding TW code

[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

-- 
You received this message because you are subscribed to the Google Groups 
"TiddlyWikiDev" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to tiddlywikidev+unsubscr...@googlegroups.com.
To post to this group, send email to tiddlywikidev@googlegroups.com.
Visit this group at https://groups.google.com/group/tiddlywikidev.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/tiddlywikidev/55977986-a407-4358-9887-1197b98b6b6a%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[twdev] Re: Understanding TW code

[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 <> evaluates the macro
>>
>
> Correct. And something like <> 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}} *>*
> ...
> 
>
>
> 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>... are *widget *calls whereas <> 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

 

-- 
You received this message because you are subscribed to the Google Groups 
"TiddlyWikiDev" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to tiddlywikidev+unsubscr...@googlegroups.com.
To post to t

[twdev] Re: Understanding TW code

[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 <> evaluates the macro
>

Correct. And something like <> 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}} *>*
...



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

<$xxx>... are *widget *calls whereas <> 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!!!

<:-)

-- 
You received this message because you are subscribed to the Google Groups 
"TiddlyWikiDev" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to tiddlywikidev+unsubscr...@googlegroups.com.
To post to this group, send email to tiddlywikidev@googlegroups.com.
Visit this group at https://groups.google.com/group/tiddlywikidev.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/tiddlywikidev/72997ee8-365a-475a-811d-329e7a719878%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.