WikiText for Dummies

[S. S.]

Now that, thanks to all the feedback, Widgets for Beginners is almost done;

It's time for WikiText for Beginners

It's a reasonably short tiddler (by my standards)!

I'd appreciate knowing if there are any glaring mistakes or omissions.

Thanks.

[TonyM]

S S ,

Seriously good work there. As you move on to WIki Text for beginners you may want to steal from my developing resource as needed.

See 

Variables, Parameters and transclusions

Note some items are untested.

In Widgets For Beginners

Perhaps this note is not for beginners.

I wonder if there is value pointing out HTML often integrates with Javascript to execute things. 

TiddlyWiki's way of providing access to execute things is via widgets (which  include javascript)

For example

<button>Inactive button</button>
<button type="button" onclick="alert('Hello world!')">Click Me!</button>

is HTML but we can't get it to execute the alert('Hello world!') in Tiddlywiki and if it did It would bypass some vary useful features of tiddlywiki.

Instead we use the tiddlywiki version, the <$button widget

<$button parameters>
Click Me!
</$button>

The point being you will always need widgets to execute things in TiddlyWiki, so behind the scenes TiddlyWiki can keep track of all executions and changes.

Regards

Tony

[S. S.]

The last line of the WikiText tiddler on TiddlyWiki/Dev documentation for developers shows this example:

WikiText:
<$button message="tm-close-tiddler">Close Me!</$button>

To help me better phrase what I say in WikiText for Beginners,I want to understand the connection of how :

Showing an example using a Widget

- relates to -

This being an example of WikiText

[Mohammad]

Hello S.S

Many thanks for your efforts.

These are valuable materials.

Cheers

Mohammad

[TonyM]

S s

Widgets are themselves placed in wiki text.

Because they have there own parameter and content rules we typically go on to discuss these, but skim over the fact they are placed in wikitext and often also contain wikitext between widget opening and closing tags.

Regards
Tony

[S. S.]

Thanks Tony.

I'm still confused as to why that particular example above was used. I only see a Widget and no WikiText. I feel like my understanding is not complete, and that makes it difficult for me to write confidently.

This is the text used in that documentation tiddler:

Furthermore the WikiText is used to access the widgets which are integrated in the application.These widgets are used to enhance the the WikiText with a rich functionality. Widgets are based on the HTML-Syntax but always starts with a $.

WikiText:
<$button message="tm-close-tiddler">Close Me!</$button>

If instead this example had been used, it would make more sense to me:

<$button message="tm-close-tiddler">I'm {{!!title}}<br> Click to Close Me! </$button>

I am beginning to understand how painstakingly careful one needs to be to write accurate official documentation for software, even if its only for the novice level.

I think I am finding it takes so much time because there is so much about the software's complex  internals that are difficult to easily understand. Thus, though it seems the topic is simple,  it's not so easy to present it to a beginner while ensuring no language is used that infers "this is all there is to it" - while also not burdening the reader with the more complex concepts.

Still, we are slowly getting there!

[TonyM]

I understand

It should read at least "Widgets always start with a <$" 

Another example could have

!Wikitext heading
*Bulleted item
*Bulleted item

<$button message="tm-close-tiddler">I'm {{!!title}}<br> Click to Close Me! </$button>

etc...

Good documentation is never so easy, but especially when coders and designers write it, because they are so familiar with the content, they make to many assumptions and always think it "obvious". It is people like yourself on this learning path who can provide the best documentation if people can help explain the gaps. Although sometimes the gaps are hard to bridge.

See my current work here https://tiddlywiki.psat.com.au/#Variables%2C%20Parameters%20and%20transclusions

Regards

Tony 

[@TiddlyTweeter]

S. S. wrote:

... I think I am finding it takes so much time because there is so much about the software's complex  internals that are difficult to easily understand. Thus, though it seems the topic is simple,  it's not so easy to present it to a beginner while ensuring no language is used that infers "this is all there is to it" - while also not burdening the reader with the more complex concepts.

So true. So very true.

There is a kinda balance between "over-prolix" and "over-terse" that is not so easy to get right.

IMO, the whole thing is about getting it right via "iteration". That is a LOT of work!

Of course no documentation is right for everyone [that fact should induce relaxment, not panic :-)]. I think the puzzle is getting to know when its "right-enough-already?"

I think you doing very well, BTW.

I LEARNT from things you have written.

Best wishes

Josiah

[TonyM]

Josiah,

In attempting to build a table of key items here I am finding iteration a valuable thing. Assuming my test are validated this table can collapse into a few key facts that will be easy to remember.

Regards

Tony