Re: [tw5] TiddlyWiki Documentation - Syntax

[Simon Baird]

I'm not following all the tech discussion here, but I like the idea of
accessible, standard documentation that's trivially easy to author.

One good example that comes to mind is the documentation for ansible
modules. There are lots of them, and they all have consistent, (mostly)
understandable docs. Perhaps there are some ideas there you could borrow or
steal.

A particularly useful section is the examples. For widgets a set of good
examples would be handy, and perhaps easier to use casually than the formal
syntax definition.

Example:
https://docs.ansible.com/ansible/2.9/modules/copy_module.html#copy-module
(Find many others here:)
https://docs.ansible.com/ansible/2.9/modules/modules_by_category.html


On Mon, Jun 7, 2021 at 7:22 PM TW Tones  wrote:

> Sorry,
>
> I meant to add I think version three could be at the bottom of every
> definition with all parameters, copy or drag.
>
> Tones
>
> On Tuesday, 8 June 2021 at 09:21:02 UTC+10 TW Tones wrote:
>
>> *Stobot et al*
>> *I'm not that familiar with screen readers etc. but if you want to take a
>> crack at an example to help me understand, I'd be happy to look at it*
>> Nor am I but alt apparently making use of alt text is important for
>> images at least. No what I am saying is making use of the other features
>> like mouse over, tooltips etc... Of late I have being getting into
>> draggable payloads, especially of content as I describe in *On syntax
>> formats* below. Just drag a syntax form into your tiddler and edit.
>>
>> *On Syntax formats*
>> To me version one is almost useless, it resembles the list of parameters
>> already documented. But you still need to refer to the rest of the
>> document. Using version one as a code snipit still requires a lot of work.
>> I would favor version 2 but one for each of the different configurations,
>> ie a subset of parameters for each common form of the widget.
>>
>> *The details widget.*
>>
>> I use the html one a lot more know since something changed to make it
>> more reliable. It does store the initial state (open or closed) just not
>> the ongoing state, and in a larger number of circumstances this is all you
>> need. Also keep in mind that even the existence of the details widget can
>> be inside a list/reveal itself which is conditional. It is ideal for more
>> or less content. Using the summary tag you can actually place macros in the
>> details "heading" to show the number of something there inside the details
>> tag (I do not think $details does this).
>>
>> Not with standing this, there is the details widget in a plugin
>> https://tid.li/tw5/plugins.html#DetailsWidget and 14kb in size, but I
>> have not used it much lately.
>>
>> I wish we could get the equivalent of the old TWC nested sliders plugin
>> but perhaps this can be emulated in Mario's "Custom Markup" as he has also
>> demonstrated the the details widget can.
>>
>> *That reminds me;*
>> We could document a lot more features and methods in tiddlywiki or a
>> separate wiki that are not just about widgets, macros tweaks and filters,
>> but also making use of html and css. For example using css to toggle
>> content display: none; and possibly classes such as nest nest1 nest2 would
>> stand in for the nested sliders plugin.
>>
>>
>>
>> Although the reality is the Custom Markup plugin may be the most valuable
>> plugin since "relink" and possibly of even more consequence.
>>
>> Regards
>> Tones
>>
>>
>> On Monday, 7 June 2021 at 22:44:42 UTC+10 TiddlyTweeter wrote:
>>
>>>
>>>- To TiddlyTweeter's point, if <$details> stored state, wouldn't it
>>>just be a less-flexible <$reveal>?
>>>
>>> RIGHT. Point is it is just a dumb state that requires NO state tiddlers
>>> at all. You can simply, directly, change the toggle state.
>>>
>>> It is mostly ONLY useful for ON/OFF situations.
>>> For that it is elegantly simple in code!
>>>
>>> TT
>>>
>>>
>>> On Monday, 7 June 2021 at 13:15:15 UTC+2 Stobot wrote:
>>>
 Great continued feedback. I'll keep going, but just to mass-reply:

 PMario

- I agree that the "closed version" should be in a small general
syntax notes area - maybe right below the syntax block. Things like:
   - Each attribute can be given as "Text Value", {{Trancluded
   Value}}, or <>
- Still thinking through how to handle the "or" situations (need
tiddler value or tiddler and field, or just field, or tiddler and 
 index...)
   - Soren had the one example which might be great. I currently
   don't understand it clearly though, so will think on how to simplify 
 it

 Tones

- I'm not that familiar with screen readers etc. but if you want to
take a crack at an example to help me understand, I'd be happy to look 
 at it

 Ste

- I'll check out the stretch text thing. Others have suggested
details which seems to have similar aims (though is non-core)

 Mohammad / Odin / TiddlyTweeter

Re: [tw5] TiddlyWiki Documentation - Syntax

[TW Tones]

Sorry, 

I meant to add I think version three could be at the bottom of every 
definition with all parameters, copy or drag.

Tones

On Tuesday, 8 June 2021 at 09:21:02 UTC+10 TW Tones wrote:

> *Stobot et al*
> *I'm not that familiar with screen readers etc. but if you want to take a 
> crack at an example to help me understand, I'd be happy to look at it*
> Nor am I but alt apparently making use of alt text is important for images 
> at least. No what I am saying is making use of the other features like 
> mouse over, tooltips etc... Of late I have being getting into draggable 
> payloads, especially of content as I describe in *On syntax formats* 
> below. Just drag a syntax form into your tiddler and edit.
>
> *On Syntax formats*
> To me version one is almost useless, it resembles the list of parameters 
> already documented. But you still need to refer to the rest of the 
> document. Using version one as a code snipit still requires a lot of work. 
> I would favor version 2 but one for each of the different configurations, 
> ie a subset of parameters for each common form of the widget. 
>
> *The details widget.*
>
> I use the html one a lot more know since something changed to make it more 
> reliable. It does store the initial state (open or closed) just not the 
> ongoing state, and in a larger number of circumstances this is all you 
> need. Also keep in mind that even the existence of the details widget can 
> be inside a list/reveal itself which is conditional. It is ideal for more 
> or less content. Using the summary tag you can actually place macros in the 
> details "heading" to show the number of something there inside the details 
> tag (I do not think $details does this). 
>
> Not with standing this, there is the details widget in a plugin 
> https://tid.li/tw5/plugins.html#DetailsWidget and 14kb in size, but I 
> have not used it much lately.
>
> I wish we could get the equivalent of the old TWC nested sliders plugin 
> but perhaps this can be emulated in Mario's "Custom Markup" as he has also 
> demonstrated the the details widget can.
>
> *That reminds me;*
> We could document a lot more features and methods in tiddlywiki or a 
> separate wiki that are not just about widgets, macros tweaks and filters, 
> but also making use of html and css. For example using css to toggle 
> content display: none; and possibly classes such as nest nest1 nest2 would 
> stand in for the nested sliders plugin. 
>
>
>
> Although the reality is the Custom Markup plugin may be the most valuable 
> plugin since "relink" and possibly of even more consequence.
>
> Regards
> Tones
>
>
> On Monday, 7 June 2021 at 22:44:42 UTC+10 TiddlyTweeter wrote:
>
>>
>>- To TiddlyTweeter's point, if <$details> stored state, wouldn't it 
>>just be a less-flexible <$reveal>?
>>
>> RIGHT. Point is it is just a dumb state that requires NO state tiddlers 
>> at all. You can simply, directly, change the toggle state.
>>
>> It is mostly ONLY useful for ON/OFF situations. 
>> For that it is elegantly simple in code!
>>
>> TT
>>
>>
>> On Monday, 7 June 2021 at 13:15:15 UTC+2 Stobot wrote:
>>
>>> Great continued feedback. I'll keep going, but just to mass-reply:
>>>
>>> PMario
>>>
>>>- I agree that the "closed version" should be in a small general 
>>>syntax notes area - maybe right below the syntax block. Things like:
>>>   - Each attribute can be given as "Text Value", {{Trancluded 
>>>   Value}}, or <>
>>>- Still thinking through how to handle the "or" situations (need 
>>>tiddler value or tiddler and field, or just field, or tiddler and 
>>> index...)
>>>   - Soren had the one example which might be great. I currently 
>>>   don't understand it clearly though, so will think on how to simplify 
>>> it
>>>
>>> Tones
>>>
>>>- I'm not that familiar with screen readers etc. but if you want to 
>>>take a crack at an example to help me understand, I'd be happy to look 
>>> at it
>>>
>>> Ste
>>>
>>>- I'll check out the stretch text thing. Others have suggested 
>>>details which seems to have similar aims (though is non-core)
>>>
>>> Mohammad / Odin / TiddlyTweeter
>>>
>>>- I think version 1 is good myself, and version 3 for completeness. 
>>>Might think about the best method to include both - via some mechanism 
>>> like 
>>>stretch-text / details / reveal / tabs (most core-ish I think)
>>>
>>>  (PMario / TiddlyTweeter)
>>>
>>>- Funnily enough the *only* thing that I can see useful about the 
>>><$details> widget is that it *doesn't* store the state (which keeps size 
>>> & 
>>># of changes down).
>>>- To TiddlyTweeter's point, if <$details> stored state, wouldn't it 
>>>just be a less-flexible <$reveal>?
>>>
>>> Thanks all, I'll keep plugging along and circle back to get more 
>>> feedback in a while. 
>>>
>>> On Monday, June 7, 2021 at 5:47:53 AM UTC-4 TiddlyTweeter wrote:
>>>

 TiddlyTweeter wrote:
>
>> ... using either 

Re: [tw5] TiddlyWiki Documentation - Syntax

[TW Tones]

*Stobot et al*
*I'm not that familiar with screen readers etc. but if you want to take a 
crack at an example to help me understand, I'd be happy to look at it*
Nor am I but alt apparently making use of alt text is important for images 
at least. No what I am saying is making use of the other features like 
mouse over, tooltips etc... Of late I have being getting into draggable 
payloads, especially of content as I describe in *On syntax formats* below. 
Just drag a syntax form into your tiddler and edit.

*On Syntax formats*
To me version one is almost useless, it resembles the list of parameters 
already documented. But you still need to refer to the rest of the 
document. Using version one as a code snipit still requires a lot of work. 
I would favor version 2 but one for each of the different configurations, 
ie a subset of parameters for each common form of the widget. 

*The details widget.*

I use the html one a lot more know since something changed to make it more 
reliable. It does store the initial state (open or closed) just not the 
ongoing state, and in a larger number of circumstances this is all you 
need. Also keep in mind that even the existence of the details widget can 
be inside a list/reveal itself which is conditional. It is ideal for more 
or less content. Using the summary tag you can actually place macros in the 
details "heading" to show the number of something there inside the details 
tag (I do not think $details does this). 

Not with standing this, there is the details widget in a 
plugin https://tid.li/tw5/plugins.html#DetailsWidget and 14kb in size, but 
I have not used it much lately.

I wish we could get the equivalent of the old TWC nested sliders plugin but 
perhaps this can be emulated in Mario's "Custom Markup" as he has also 
demonstrated the the details widget can.

*That reminds me;*
We could document a lot more features and methods in tiddlywiki or a 
separate wiki that are not just about widgets, macros tweaks and filters, 
but also making use of html and css. For example using css to toggle 
content display: none; and possibly classes such as nest nest1 nest2 would 
stand in for the nested sliders plugin. 



Although the reality is the Custom Markup plugin may be the most valuable 
plugin since "relink" and possibly of even more consequence.

Regards
Tones


On Monday, 7 June 2021 at 22:44:42 UTC+10 TiddlyTweeter wrote:

>
>- To TiddlyTweeter's point, if <$details> stored state, wouldn't it 
>just be a less-flexible <$reveal>?
>
> RIGHT. Point is it is just a dumb state that requires NO state tiddlers at 
> all. You can simply, directly, change the toggle state.
>
> It is mostly ONLY useful for ON/OFF situations. 
> For that it is elegantly simple in code!
>
> TT
>
>
> On Monday, 7 June 2021 at 13:15:15 UTC+2 Stobot wrote:
>
>> Great continued feedback. I'll keep going, but just to mass-reply:
>>
>> PMario
>>
>>- I agree that the "closed version" should be in a small general 
>>syntax notes area - maybe right below the syntax block. Things like:
>>   - Each attribute can be given as "Text Value", {{Trancluded 
>>   Value}}, or <>
>>- Still thinking through how to handle the "or" situations (need 
>>tiddler value or tiddler and field, or just field, or tiddler and 
>> index...)
>>   - Soren had the one example which might be great. I currently 
>>   don't understand it clearly though, so will think on how to simplify it
>>
>> Tones
>>
>>- I'm not that familiar with screen readers etc. but if you want to 
>>take a crack at an example to help me understand, I'd be happy to look at 
>> it
>>
>> Ste
>>
>>- I'll check out the stretch text thing. Others have suggested 
>>details which seems to have similar aims (though is non-core)
>>
>> Mohammad / Odin / TiddlyTweeter
>>
>>- I think version 1 is good myself, and version 3 for completeness. 
>>Might think about the best method to include both - via some mechanism 
>> like 
>>stretch-text / details / reveal / tabs (most core-ish I think)
>>
>>  (PMario / TiddlyTweeter)
>>
>>- Funnily enough the *only* thing that I can see useful about the 
>><$details> widget is that it *doesn't* store the state (which keeps size 
>> & 
>># of changes down).
>>- To TiddlyTweeter's point, if <$details> stored state, wouldn't it 
>>just be a less-flexible <$reveal>?
>>
>> Thanks all, I'll keep plugging along and circle back to get more feedback 
>> in a while. 
>>
>> On Monday, June 7, 2021 at 5:47:53 AM UTC-4 TiddlyTweeter wrote:
>>
>>>
>>> TiddlyTweeter wrote:

> ... using either *<$reveal>... *or ... to hide sections so 
> its not too overwhelming and the end-user can expand only the sections 
> they 
> need to see.


>>> PMario replied: 
>>>
 At the moment Jeremy doesn't accept PRs that contain the  
 element, because it doesn't store open/close state. 
 I think, we need a <$details> widget, that can 

Re: [tw5] TiddlyWiki Documentation - Syntax

[TiddlyTweeter]

   
   - To TiddlyTweeter's point, if <$details> stored state, wouldn't it just 
   be a less-flexible <$reveal>?

RIGHT. Point is it is just a dumb state that requires NO state tiddlers at 
all. You can simply, directly, change the toggle state.

It is mostly ONLY useful for ON/OFF situations. 
For that it is elegantly simple in code!

TT


On Monday, 7 June 2021 at 13:15:15 UTC+2 Stobot wrote:

> Great continued feedback. I'll keep going, but just to mass-reply:
>
> PMario
>
>- I agree that the "closed version" should be in a small general 
>syntax notes area - maybe right below the syntax block. Things like:
>   - Each attribute can be given as "Text Value", {{Trancluded 
>   Value}}, or <>
>- Still thinking through how to handle the "or" situations (need 
>tiddler value or tiddler and field, or just field, or tiddler and index...)
>   - Soren had the one example which might be great. I currently don't 
>   understand it clearly though, so will think on how to simplify it
>
> Tones
>
>- I'm not that familiar with screen readers etc. but if you want to 
>take a crack at an example to help me understand, I'd be happy to look at 
> it
>
> Ste
>
>- I'll check out the stretch text thing. Others have suggested details 
>which seems to have similar aims (though is non-core)
>
> Mohammad / Odin / TiddlyTweeter
>
>- I think version 1 is good myself, and version 3 for completeness. 
>Might think about the best method to include both - via some mechanism 
> like 
>stretch-text / details / reveal / tabs (most core-ish I think)
>
>  (PMario / TiddlyTweeter)
>
>- Funnily enough the *only* thing that I can see useful about the 
><$details> widget is that it *doesn't* store the state (which keeps size & 
># of changes down).
>- To TiddlyTweeter's point, if <$details> stored state, wouldn't it 
>just be a less-flexible <$reveal>?
>
> Thanks all, I'll keep plugging along and circle back to get more feedback 
> in a while. 
>
> On Monday, June 7, 2021 at 5:47:53 AM UTC-4 TiddlyTweeter wrote:
>
>>
>> TiddlyTweeter wrote:
>>>
 ... using either *<$reveal>... *or ... to hide sections so 
 its not too overwhelming and the end-user can expand only the sections 
 they 
 need to see.
>>>
>>>
>> PMario replied: 
>>
>>> At the moment Jeremy doesn't accept PRs that contain the  
>>> element, because it doesn't store open/close state. 
>>> I think, we need a <$details> widget, that can handle persistent state, 
>>> in the core first.
>>>
>>
>> HA!*  *is super simple. ADD "open" or remove it. 
>> *   Should be a doddle. *
>> It is NOT intelligent like *<$reveal> *which handles well complex 
>> situations, but in MANY use cases  binary sate is all you need.
>>
>> Side comment
>> TT
>>
>

-- 
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 tiddlywiki+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/tiddlywiki/6086c09e-ba93-41dd-ad6f-243b0b2953b6n%40googlegroups.com.

Re: [tw5] TiddlyWiki Documentation - Syntax

[Stobot]

Great continued feedback. I'll keep going, but just to mass-reply:

PMario

   - I agree that the "closed version" should be in a small general syntax 
   notes area - maybe right below the syntax block. Things like:
  - Each attribute can be given as "Text Value", {{Trancluded Value}}, 
  or <>
   - Still thinking through how to handle the "or" situations (need tiddler 
   value or tiddler and field, or just field, or tiddler and index...)
  - Soren had the one example which might be great. I currently don't 
  understand it clearly though, so will think on how to simplify it
   
Tones

   - I'm not that familiar with screen readers etc. but if you want to take 
   a crack at an example to help me understand, I'd be happy to look at it

Ste

   - I'll check out the stretch text thing. Others have suggested details 
   which seems to have similar aims (though is non-core)

Mohammad / Odin / TiddlyTweeter

   - I think version 1 is good myself, and version 3 for completeness. 
   Might think about the best method to include both - via some mechanism like 
   stretch-text / details / reveal / tabs (most core-ish I think)

 (PMario / TiddlyTweeter)

   - Funnily enough the *only* thing that I can see useful about the 
   <$details> widget is that it *doesn't* store the state (which keeps size & 
   # of changes down).
   - To TiddlyTweeter's point, if <$details> stored state, wouldn't it just 
   be a less-flexible <$reveal>?

Thanks all, I'll keep plugging along and circle back to get more feedback 
in a while. 

On Monday, June 7, 2021 at 5:47:53 AM UTC-4 TiddlyTweeter wrote:

>
> TiddlyTweeter wrote:
>>
>>> ... using either *<$reveal>... *or ... to hide sections so its 
>>> not too overwhelming and the end-user can expand only the sections they 
>>> need to see.
>>
>>
> PMario replied: 
>
>> At the moment Jeremy doesn't accept PRs that contain the  
>> element, because it doesn't store open/close state. 
>> I think, we need a <$details> widget, that can handle persistent state, 
>> in the core first.
>>
>
> HA!*  *is super simple. ADD "open" or remove it. 
> *   Should be a doddle. *
> It is NOT intelligent like *<$reveal> *which handles well complex 
> situations, but in MANY use cases  binary sate is all you need.
>
> Side comment
> TT
>

-- 
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 tiddlywiki+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/tiddlywiki/5df81d7c-8db9-4359-9951-f7580009761an%40googlegroups.com.

Re: [tw5] TiddlyWiki Documentation - Syntax

[TiddlyTweeter]

> TiddlyTweeter wrote:
>
>> ... using either *<$reveal>... *or ... to hide sections so its 
>> not too overwhelming and the end-user can expand only the sections they 
>> need to see.
>
>
PMario replied: 

> At the moment Jeremy doesn't accept PRs that contain the  
> element, because it doesn't store open/close state. 
> I think, we need a <$details> widget, that can handle persistent state, 
> in the core first.
>

HA!*  *is super simple. ADD "open" or remove it. 
*   Should be a doddle. *
It is NOT intelligent like *<$reveal> *which handles well complex 
situations, but in MANY use cases  binary sate is all you need.

Side comment
TT

-- 
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 tiddlywiki+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/tiddlywiki/5732410c-2ce9-452e-a986-3057a5e8171dn%40googlegroups.com.

Re: [tw5] TiddlyWiki Documentation - Syntax

[PMario]

On Monday, May 31, 2021 at 10:06:33 AM UTC+2 TiddlyTweeter wrote:

... using either *<$reveal>... *or ... to hide sections so its not 
> too overwhelming and the end-user can expand only the sections they need to 
> see.


At the moment Jeremy doesn't accept PRs that contain the  element, 
because it doesn't store open/close state. 
I think, we need a <$details> widget, that can handle persistent state, in 
the core first. 

-mario

-- 
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 tiddlywiki+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/tiddlywiki/66c42839-81a5-40cd-8a91-692a8c311d9dn%40googlegroups.com.

Re: [tw5] TiddlyWiki Documentation - Syntax

[PMario]

On Saturday, May 29, 2021 at 6:10:32 PM UTC+2 Stobot wrote:

Examples - more complex = Edit-text
> [image: edit-text-widget.PNG]
>

I personally would favour Version 1 for the Intro overview. 

The valure-options as shown in Versioin 2 should be part of the detailed 
description in the "Attributes table"

Just my thoughts.
-mario

-- 
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 tiddlywiki+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/tiddlywiki/fab36a70-5fbb-44c2-9060-f6eb3d889794n%40googlegroups.com.

Re: [tw5] TiddlyWiki Documentation - Syntax

[TiddlyTweeter]

Stobot wrote:

> Review here:
> Documentation — Syntax for Widgets (tiddlyhost.com) 
> 
>
> So on the site now I show a V1 (original), V2 (adding the metasyntactic 
> variables), and V3 with them, but splitting each attribute into a new line. 
> It's not clear to me which is best because I change my mind depending on 
> how many attributes there are. While V3 I think makes it easier to read for 
> widgets with MANY attributes, I wonder then if it's worth just combining 
> the syntax and attribute table altogether since it'd probably fit all side 
> by side (think syntax as col1 of a table with the description, defaults as 
> other columns... 
>

The Right column, *"New", *I think is excellent, because it is 
comprehensive ...

I would consider ...

   1. ... moving the * "Attributes" *table to the top ...
   2. ... using either *<$reveal>... *or ... to hide sections so 
   its not too overwhelming and the end-user can expand only the sections they 
   need to see.

Just thoughts
TT

-- 
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 tiddlywiki+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/tiddlywiki/3a2c1fbf-799d-4761-97e7-fe21f8672588n%40googlegroups.com.

Re: [tw5] TiddlyWiki Documentation - Syntax

[Odin]

I like V1 the best in combination with the table. This way the part in the 
codeblock in a quick overview that can be copied. And if an user needs more 
information, they can look it up in the table.
Op zaterdag 29 mei 2021 om 19:01:03 UTC+2 schreef Mohammad:

> I love this bold/italic format! Now at a short glance one understand how 
> to call the widget!
>
>
> If readability does matter, then V3 is the most readable but may take more 
> space and look lengthy!
> My experience says having a standard form for all widgets makes learning 
> them easier!
>
> I also recommend to keep the table! as it has a column of explanation to 
> all attributes! in other words the table is a descriptive tool 
> clarify everything while the syntax is only an abstract form!
>
> Lets see what other says!
>
>
> Best wishes
> Mohammad
>
>
> On Sat, May 29, 2021 at 8:40 PM Stobot  wrote:
>
>> Progress and feedback gathering:
>>
>>- The main suggestion I wanted to take a look at first was adding 
>>"metasyntactic variables", which was suggested by many of you. I had 
>>expressed my concern with length, so want to show that below and at the 
>>link to get feedback. 
>>- Added these attribute strings in a dictionary so they can be shared 
>>/consistent between widgets
>>- Added parenthesis around defaults that are not variable names
>>
>>
>> Review here:
>> Documentation — Syntax for Widgets (tiddlyhost.com) 
>> 
>>
>> So on the site now I show a V1 (original), V2 (adding the metasyntactic 
>> variables), and V3 with them, but splitting each attribute into a new line. 
>> It's not clear to me which is best because I change my mind depending on 
>> how many attributes there are. While V3 I think makes it easier to read for 
>> widgets with MANY attributes, I wonder then if it's worth just combining 
>> the syntax and attribute table altogether since it'd probably fit all side 
>> by side (think syntax as col1 of a table with the description, defaults as 
>> other columns... 
>>
>> Examples - fairly simple = Image
>> [image: image-widget.PNG]
>>
>> Examples - more complex = Edit-text
>> [image: edit-text-widget.PNG]
>>
>>
>> On Thursday, May 27, 2021 at 6:19:11 PM UTC-4 TW Tones wrote:
>>
>>> Folks,
>>>
>>> When documenting code perhaps mouse over and alt text could be used 
>>> along with highlighting so an optional items being bold nd green could 
>>> support screen readers and the color blind with mouse over text? We do 
>>> have  rich environment available after all. I am sure there are standards 
>>> we can follow.
>>>
>>> Tones 
>>>
>>> On Friday, 28 May 2021 at 03:47:37 UTC+10 Mohammad wrote:
>>>



 Best wishes
 Mohammad


 On Thu, May 27, 2021 at 4:28 PM Stobot  wrote:

> Thanks everyone for the feedback!
>
> @Soren
>
>- Good point about the formatting on the values in the Default 
>section, I'll try parentheses. 
>- I ''strongly'' agree that every attribute should have an 
>example. I might have to put that as a secondary effort though to make 
> sure 
>I finish this. 
>- Good reminder again on color-blindness. I did end up going with 
>the bold / italic setup so I think I'll stick with that unless I hear 
> of 
>something better
>- I like the note about doing source="MyImageTiddler" rather than 
>just source as I have it. I actually did that originally, but after 
>realizing how many attributes some of these things have, I 
> counter-balanced 
>against the length of the syntax mockup. I think you're probably right 
>anyways, and I think your point about a maintained table of example 
> values 
>per type makes sense - good idea. But take a look at something like 
><$edit-text/> which has 20 attributes. At a certain length, I worry we 
>would lose people, or you then get into a kind of stepped layout where 
> each 
>attribute gets a newline?
>- I agree on the order, I did put all the required ones first, and 
>then took some liberty on ones I thought were most common, but 
> alphabetical 
>probably makes more sense. Counter to that might be to bundle (sort 
>together) the ones that go together. 
>- Your last point on multiple required attributes is similar to 
>where I was thinking about too. For reference, using your example - 
><$action-setfield> 
>   - Your suggestion: <$action-setfield $tiddler="tid" 
>   ($field="field" | $index = "index" | *text* field) 
>   $value="value" />  - what does the *text* field part mean?
>   - I was thinking about the combinations that were valid could 
>   all be spelled out. For example either tiddler or field are fine, 
> and if 
>   you use index you need tiddler too.
>   - So maybe: 

Re: [tw5] TiddlyWiki Documentation - Syntax

[Mohammad Rahmani]

I love this bold/italic format! Now at a short glance one understand how to
call the widget!


If readability does matter, then V3 is the most readable but may take more
space and look lengthy!
My experience says having a standard form for all widgets makes learning
them easier!

I also recommend to keep the table! as it has a column of explanation to
all attributes! in other words the table is a descriptive tool
clarify everything while the syntax is only an abstract form!

Lets see what other says!


Best wishes
Mohammad


On Sat, May 29, 2021 at 8:40 PM Stobot  wrote:

> Progress and feedback gathering:
>
>- The main suggestion I wanted to take a look at first was adding
>"metasyntactic variables", which was suggested by many of you. I had
>expressed my concern with length, so want to show that below and at the
>link to get feedback.
>- Added these attribute strings in a dictionary so they can be shared
>/consistent between widgets
>- Added parenthesis around defaults that are not variable names
>
>
> Review here:
> Documentation — Syntax for Widgets (tiddlyhost.com)
> 
>
> So on the site now I show a V1 (original), V2 (adding the metasyntactic
> variables), and V3 with them, but splitting each attribute into a new line.
> It's not clear to me which is best because I change my mind depending on
> how many attributes there are. While V3 I think makes it easier to read for
> widgets with MANY attributes, I wonder then if it's worth just combining
> the syntax and attribute table altogether since it'd probably fit all side
> by side (think syntax as col1 of a table with the description, defaults as
> other columns...
>
> Examples - fairly simple = Image
> [image: image-widget.PNG]
>
> Examples - more complex = Edit-text
> [image: edit-text-widget.PNG]
>
>
> On Thursday, May 27, 2021 at 6:19:11 PM UTC-4 TW Tones wrote:
>
>> Folks,
>>
>> When documenting code perhaps mouse over and alt text could be used along
>> with highlighting so an optional items being bold nd green could support
>> screen readers and the color blind with mouse over text? We do have  rich
>> environment available after all. I am sure there are standards we can
>> follow.
>>
>> Tones
>>
>> On Friday, 28 May 2021 at 03:47:37 UTC+10 Mohammad wrote:
>>
>>>
>>>
>>>
>>> Best wishes
>>> Mohammad
>>>
>>>
>>> On Thu, May 27, 2021 at 4:28 PM Stobot  wrote:
>>>
 Thanks everyone for the feedback!

 @Soren

- Good point about the formatting on the values in the Default
section, I'll try parentheses.
- I ''strongly'' agree that every attribute should have an example.
I might have to put that as a secondary effort though to make sure I 
 finish
this.
- Good reminder again on color-blindness. I did end up going with
the bold / italic setup so I think I'll stick with that unless I hear of
something better
- I like the note about doing source="MyImageTiddler" rather than
just source as I have it. I actually did that originally, but after
realizing how many attributes some of these things have, I 
 counter-balanced
against the length of the syntax mockup. I think you're probably right
anyways, and I think your point about a maintained table of example 
 values
per type makes sense - good idea. But take a look at something like
<$edit-text/> which has 20 attributes. At a certain length, I worry we
would lose people, or you then get into a kind of stepped layout where 
 each
attribute gets a newline?
- I agree on the order, I did put all the required ones first, and
then took some liberty on ones I thought were most common, but 
 alphabetical
probably makes more sense. Counter to that might be to bundle (sort
together) the ones that go together.
- Your last point on multiple required attributes is similar to
where I was thinking about too. For reference, using your example -
<$action-setfield>
   - Your suggestion: <$action-setfield $tiddler="tid"
   ($field="field" | $index = "index" | *text* field)
   $value="value" />  - what does the *text* field part mean?
   - I was thinking about the combinations that were valid could
   all be spelled out. For example either tiddler or field are fine, 
 and if
   you use index you need tiddler too.
   - So maybe: <$action-setfield ( $tiddler | $field | $tiddler +
   $field | $tiddler + $index ) $value /> - though again that gets long 
 if
   there are lots of options like this.

 @Tones

- I commented on your other thread on CSS - I agree that's an
opportunity for a little more to be added to the documentation also
- I also like the "copy to clipboard" piece. I saw that in many of
the examples and will try 

Re: [tw5] TiddlyWiki Documentation - Syntax

[Ste]

I have no idea if this would be more hassle than it's worth or would be a 
workable work flow but could text stretch or stretch text be used to 
present a condensed version which could be expanded? 
https://links.tiddlywiki.com/urls/7f9e7e60ed40b5098996
https://links.tiddlywiki.com/urls/618ef8913574d547c412

On Saturday, 29 May 2021 at 17:10:32 UTC+1 Stobot wrote:

> Progress and feedback gathering:
>
>- The main suggestion I wanted to take a look at first was adding 
>"metasyntactic variables", which was suggested by many of you. I had 
>expressed my concern with length, so want to show that below and at the 
>link to get feedback. 
>- Added these attribute strings in a dictionary so they can be shared 
>/consistent between widgets
>- Added parenthesis around defaults that are not variable names
>
>
> Review here:
> Documentation — Syntax for Widgets (tiddlyhost.com) 
> 
>
> So on the site now I show a V1 (original), V2 (adding the metasyntactic 
> variables), and V3 with them, but splitting each attribute into a new line. 
> It's not clear to me which is best because I change my mind depending on 
> how many attributes there are. While V3 I think makes it easier to read for 
> widgets with MANY attributes, I wonder then if it's worth just combining 
> the syntax and attribute table altogether since it'd probably fit all side 
> by side (think syntax as col1 of a table with the description, defaults as 
> other columns... 
>
> Examples - fairly simple = Image
> [image: image-widget.PNG]
>
> Examples - more complex = Edit-text
> [image: edit-text-widget.PNG]
>
>
> On Thursday, May 27, 2021 at 6:19:11 PM UTC-4 TW Tones wrote:
>
>> Folks,
>>
>> When documenting code perhaps mouse over and alt text could be used along 
>> with highlighting so an optional items being bold nd green could support 
>> screen readers and the color blind with mouse over text? We do have  rich 
>> environment available after all. I am sure there are standards we can 
>> follow.
>>
>> Tones 
>>
>> On Friday, 28 May 2021 at 03:47:37 UTC+10 Mohammad wrote:
>>
>>>
>>>
>>>
>>> Best wishes
>>> Mohammad
>>>
>>>
>>> On Thu, May 27, 2021 at 4:28 PM Stobot  wrote:
>>>
 Thanks everyone for the feedback!

 @Soren

- Good point about the formatting on the values in the Default 
section, I'll try parentheses. 
- I ''strongly'' agree that every attribute should have an example. 
I might have to put that as a secondary effort though to make sure I 
 finish 
this. 
- Good reminder again on color-blindness. I did end up going with 
the bold / italic setup so I think I'll stick with that unless I hear 
 of 
something better
- I like the note about doing source="MyImageTiddler" rather than 
just source as I have it. I actually did that originally, but after 
realizing how many attributes some of these things have, I 
 counter-balanced 
against the length of the syntax mockup. I think you're probably right 
anyways, and I think your point about a maintained table of example 
 values 
per type makes sense - good idea. But take a look at something like 
<$edit-text/> which has 20 attributes. At a certain length, I worry we 
would lose people, or you then get into a kind of stepped layout where 
 each 
attribute gets a newline?
- I agree on the order, I did put all the required ones first, and 
then took some liberty on ones I thought were most common, but 
 alphabetical 
probably makes more sense. Counter to that might be to bundle (sort 
together) the ones that go together. 
- Your last point on multiple required attributes is similar to 
where I was thinking about too. For reference, using your example - 
<$action-setfield> 
   - Your suggestion: <$action-setfield $tiddler="tid" 
   ($field="field" | $index = "index" | *text* field) 
   $value="value" />  - what does the *text* field part mean?
   - I was thinking about the combinations that were valid could 
   all be spelled out. For example either tiddler or field are fine, 
 and if 
   you use index you need tiddler too.
   - So maybe: <$action-setfield ( $tiddler | $field | $tiddler + 
   $field | $tiddler + $index ) $value /> - though again that gets long 
 if 
   there are lots of options like this.

 @Tones

- I commented on your other thread on CSS - I agree that's an 
opportunity for a little more to be added to the documentation also
- I also like the "copy to clipboard" piece. I saw that in many of 
the examples and will try to implement it by reverse-engineering the 
 core 
macro that does it. 
- You bring up a lot of other things that while valid, 

Re: [tw5] TiddlyWiki Documentation - Syntax

[Stobot]

Progress and feedback gathering:

   - The main suggestion I wanted to take a look at first was adding 
   "metasyntactic variables", which was suggested by many of you. I had 
   expressed my concern with length, so want to show that below and at the 
   link to get feedback. 
   - Added these attribute strings in a dictionary so they can be shared 
   /consistent between widgets
   - Added parenthesis around defaults that are not variable names


Review here:
Documentation — Syntax for Widgets (tiddlyhost.com) 


So on the site now I show a V1 (original), V2 (adding the metasyntactic 
variables), and V3 with them, but splitting each attribute into a new line. 
It's not clear to me which is best because I change my mind depending on 
how many attributes there are. While V3 I think makes it easier to read for 
widgets with MANY attributes, I wonder then if it's worth just combining 
the syntax and attribute table altogether since it'd probably fit all side 
by side (think syntax as col1 of a table with the description, defaults as 
other columns... 

Examples - fairly simple = Image
[image: image-widget.PNG]

Examples - more complex = Edit-text
[image: edit-text-widget.PNG]


On Thursday, May 27, 2021 at 6:19:11 PM UTC-4 TW Tones wrote:

> Folks,
>
> When documenting code perhaps mouse over and alt text could be used along 
> with highlighting so an optional items being bold nd green could support 
> screen readers and the color blind with mouse over text? We do have  rich 
> environment available after all. I am sure there are standards we can 
> follow.
>
> Tones 
>
> On Friday, 28 May 2021 at 03:47:37 UTC+10 Mohammad wrote:
>
>>
>>
>>
>> Best wishes
>> Mohammad
>>
>>
>> On Thu, May 27, 2021 at 4:28 PM Stobot  wrote:
>>
>>> Thanks everyone for the feedback!
>>>
>>> @Soren
>>>
>>>- Good point about the formatting on the values in the Default 
>>>section, I'll try parentheses. 
>>>- I ''strongly'' agree that every attribute should have an example. 
>>>I might have to put that as a secondary effort though to make sure I 
>>> finish 
>>>this. 
>>>- Good reminder again on color-blindness. I did end up going with 
>>>the bold / italic setup so I think I'll stick with that unless I hear of 
>>>something better
>>>- I like the note about doing source="MyImageTiddler" rather than 
>>>just source as I have it. I actually did that originally, but after 
>>>realizing how many attributes some of these things have, I 
>>> counter-balanced 
>>>against the length of the syntax mockup. I think you're probably right 
>>>anyways, and I think your point about a maintained table of example 
>>> values 
>>>per type makes sense - good idea. But take a look at something like 
>>><$edit-text/> which has 20 attributes. At a certain length, I worry we 
>>>would lose people, or you then get into a kind of stepped layout where 
>>> each 
>>>attribute gets a newline?
>>>- I agree on the order, I did put all the required ones first, and 
>>>then took some liberty on ones I thought were most common, but 
>>> alphabetical 
>>>probably makes more sense. Counter to that might be to bundle (sort 
>>>together) the ones that go together. 
>>>- Your last point on multiple required attributes is similar to 
>>>where I was thinking about too. For reference, using your example - 
>>><$action-setfield> 
>>>   - Your suggestion: <$action-setfield $tiddler="tid" 
>>>   ($field="field" | $index = "index" | *text* field) $value="value" 
>>>   />  - what does the *text* field part mean?
>>>   - I was thinking about the combinations that were valid could all 
>>>   be spelled out. For example either tiddler or field are fine, and if 
>>> you 
>>>   use index you need tiddler too.
>>>   - So maybe: <$action-setfield ( $tiddler | $field | $tiddler + 
>>>   $field | $tiddler + $index ) $value /> - though again that gets long 
>>> if 
>>>   there are lots of options like this.
>>>
>>> @Tones
>>>
>>>- I commented on your other thread on CSS - I agree that's an 
>>>opportunity for a little more to be added to the documentation also
>>>- I also like the "copy to clipboard" piece. I saw that in many of 
>>>the examples and will try to implement it by reverse-engineering the 
>>> core 
>>>macro that does it. 
>>>- You bring up a lot of other things that while valid, would be 
>>>massive scope creep on an already large effort, but I'm happy to pencil 
>>> in 
>>>for future "phases"
>>>   - Multiple versions of common widgets, like the filtered 
>>>   transclusion example, good point. 
>>>   - Documentation of macros & <$macrocall/> syntax
>>>   - Examples should all work on TiddlyWiki.com - totally agree. I 
>>>   think the whole "recipe book" idea as base data (as is used for some 
>>> of the 
>>>   filter stuff is a good starting 

Re: [tw5] TiddlyWiki Documentation - Syntax

[TW Tones]

Folks,

When documenting code perhaps mouse over and alt text could be used along 
with highlighting so an optional items being bold nd green could support 
screen readers and the color blind with mouse over text? We do have  rich 
environment available after all. I am sure there are standards we can 
follow.

Tones 

On Friday, 28 May 2021 at 03:47:37 UTC+10 Mohammad wrote:

>
>
>
> Best wishes
> Mohammad
>
>
> On Thu, May 27, 2021 at 4:28 PM Stobot  wrote:
>
>> Thanks everyone for the feedback!
>>
>> @Soren
>>
>>- Good point about the formatting on the values in the Default 
>>section, I'll try parentheses. 
>>- I ''strongly'' agree that every attribute should have an example. I 
>>might have to put that as a secondary effort though to make sure I finish 
>>this. 
>>- Good reminder again on color-blindness. I did end up going with the 
>>bold / italic setup so I think I'll stick with that unless I hear of 
>>something better
>>- I like the note about doing source="MyImageTiddler" rather than 
>>just source as I have it. I actually did that originally, but after 
>>realizing how many attributes some of these things have, I 
>> counter-balanced 
>>against the length of the syntax mockup. I think you're probably right 
>>anyways, and I think your point about a maintained table of example 
>> values 
>>per type makes sense - good idea. But take a look at something like 
>><$edit-text/> which has 20 attributes. At a certain length, I worry we 
>>would lose people, or you then get into a kind of stepped layout where 
>> each 
>>attribute gets a newline?
>>- I agree on the order, I did put all the required ones first, and 
>>then took some liberty on ones I thought were most common, but 
>> alphabetical 
>>probably makes more sense. Counter to that might be to bundle (sort 
>>together) the ones that go together. 
>>- Your last point on multiple required attributes is similar to where 
>>I was thinking about too. For reference, using your example - 
>><$action-setfield> 
>>   - Your suggestion: <$action-setfield $tiddler="tid" 
>>   ($field="field" | $index = "index" | *text* field) $value="value" 
>>   />  - what does the *text* field part mean?
>>   - I was thinking about the combinations that were valid could all 
>>   be spelled out. For example either tiddler or field are fine, and if 
>> you 
>>   use index you need tiddler too.
>>   - So maybe: <$action-setfield ( $tiddler | $field | $tiddler + 
>>   $field | $tiddler + $index ) $value /> - though again that gets long 
>> if 
>>   there are lots of options like this.
>>
>> @Tones
>>
>>- I commented on your other thread on CSS - I agree that's an 
>>opportunity for a little more to be added to the documentation also
>>- I also like the "copy to clipboard" piece. I saw that in many of 
>>the examples and will try to implement it by reverse-engineering the core 
>>macro that does it. 
>>- You bring up a lot of other things that while valid, would be 
>>massive scope creep on an already large effort, but I'm happy to pencil 
>> in 
>>for future "phases"
>>   - Multiple versions of common widgets, like the filtered 
>>   transclusion example, good point. 
>>   - Documentation of macros & <$macrocall/> syntax
>>   - Examples should all work on TiddlyWiki.com - totally agree. I 
>>   think the whole "recipe book" idea as base data (as is used for some 
>> of the 
>>   filter stuff is a good starting point myself)
>>   - Test-data / plugins: Good ideas too, as above, I think a small 
>>   internal dataset like recipes / ingredients etc. are perfect for 
>> starting 
>>   though
>>   - Send-message vs. action widgets (paraphrasing) also valid thing 
>>   to further describe
>>   - Whole learning environment: My personal opinion based on other 
>>   languages is that I like the core to support main syntax and examples, 
>> and 
>>   leave external sources for more guided training (such as Soren's Grok 
>> book 
>>   and videos)
>>
>> @Mohammad
>>
>>- I'll take a look at Shiraz and the Alert Macro as you suggest.
>>- The general flow you illustrate sounds good to me, and I think is 
>>similar to what TiddlyWiki has, but with just a few missing pieces.
>>- Agree with you and Soren on bold / italic vs. colors, good point
>>- I agree (mostly) on the consistent outline (constant number of 
>>sections), though to keep the scope small, thought would be to split the 
>>effort into phases to increase the liklihood of it getting finished. 
>>   - Syntax and Attributes table would be phase I
>>   - Examples and other cleanup could be phase II etc.
>>- I agree on referring to the other languages for inspiration. A 
>>saying I'll sometimes use is that "sometimes consistency is more 
>> important 
>>

Re: [tw5] TiddlyWiki Documentation - Syntax

[Mohammad Rahmani]

Best wishes
Mohammad


On Thu, May 27, 2021 at 4:28 PM Stobot  wrote:

> Thanks everyone for the feedback!
>
> @Soren
>
>- Good point about the formatting on the values in the Default
>section, I'll try parentheses.
>- I ''strongly'' agree that every attribute should have an example. I
>might have to put that as a secondary effort though to make sure I finish
>this.
>- Good reminder again on color-blindness. I did end up going with the
>bold / italic setup so I think I'll stick with that unless I hear of
>something better
>- I like the note about doing source="MyImageTiddler" rather than just
>source as I have it. I actually did that originally, but after realizing
>how many attributes some of these things have, I counter-balanced against
>the length of the syntax mockup. I think you're probably right anyways, and
>I think your point about a maintained table of example values per type
>makes sense - good idea. But take a look at something like <$edit-text/>
>which has 20 attributes. At a certain length, I worry we would lose people,
>or you then get into a kind of stepped layout where each attribute gets a
>newline?
>- I agree on the order, I did put all the required ones first, and
>then took some liberty on ones I thought were most common, but alphabetical
>probably makes more sense. Counter to that might be to bundle (sort
>together) the ones that go together.
>- Your last point on multiple required attributes is similar to where
>I was thinking about too. For reference, using your example -
><$action-setfield>
>   - Your suggestion: <$action-setfield $tiddler="tid" ($field="field"
>   | $index = "index" | *text* field) $value="value" />  - what does
>   the *text* field part mean?
>   - I was thinking about the combinations that were valid could all
>   be spelled out. For example either tiddler or field are fine, and if you
>   use index you need tiddler too.
>   - So maybe: <$action-setfield ( $tiddler | $field | $tiddler +
>   $field | $tiddler + $index ) $value /> - though again that gets long if
>   there are lots of options like this.
>
> @Tones
>
>- I commented on your other thread on CSS - I agree that's an
>opportunity for a little more to be added to the documentation also
>- I also like the "copy to clipboard" piece. I saw that in many of the
>examples and will try to implement it by reverse-engineering the core macro
>that does it.
>- You bring up a lot of other things that while valid, would be
>massive scope creep on an already large effort, but I'm happy to pencil in
>for future "phases"
>   - Multiple versions of common widgets, like the filtered
>   transclusion example, good point.
>   - Documentation of macros & <$macrocall/> syntax
>   - Examples should all work on TiddlyWiki.com - totally agree. I
>   think the whole "recipe book" idea as base data (as is used for some of 
> the
>   filter stuff is a good starting point myself)
>   - Test-data / plugins: Good ideas too, as above, I think a small
>   internal dataset like recipes / ingredients etc. are perfect for 
> starting
>   though
>   - Send-message vs. action widgets (paraphrasing) also valid thing
>   to further describe
>   - Whole learning environment: My personal opinion based on other
>   languages is that I like the core to support main syntax and examples, 
> and
>   leave external sources for more guided training (such as Soren's Grok 
> book
>   and videos)
>
> @Mohammad
>
>- I'll take a look at Shiraz and the Alert Macro as you suggest.
>- The general flow you illustrate sounds good to me, and I think is
>similar to what TiddlyWiki has, but with just a few missing pieces.
>- Agree with you and Soren on bold / italic vs. colors, good point
>- I agree (mostly) on the consistent outline (constant number of
>sections), though to keep the scope small, thought would be to split the
>effort into phases to increase the liklihood of it getting finished.
>   - Syntax and Attributes table would be phase I
>   - Examples and other cleanup could be phase II etc.
>- I agree on referring to the other languages for inspiration. A
>saying I'll sometimes use is that "sometimes consistency is more important
>than accuracy" which sounds counter-intuitive, but if the end result is
>learning, absorbing material is job 1
>
> @TiddlyTweeter
>
>- I understood where you were going with your comments in the other
>thread. I think there is definitely a "too far" area, and having much
>deeper learning can be better handled in other places, with other mediums
>even
>- I agree on the scope, and will definitely not make everyone happy
>with what I plan on doing, but I think it most prudent to break the effort
>into phases as mentioned above. If I / 

Re: [tw5] TiddlyWiki Documentation - Syntax

[Stobot]

Thanks everyone for the feedback!

@Soren

   - Good point about the formatting on the values in the Default section, 
   I'll try parentheses. 
   - I ''strongly'' agree that every attribute should have an example. I 
   might have to put that as a secondary effort though to make sure I finish 
   this. 
   - Good reminder again on color-blindness. I did end up going with the 
   bold / italic setup so I think I'll stick with that unless I hear of 
   something better
   - I like the note about doing source="MyImageTiddler" rather than just 
   source as I have it. I actually did that originally, but after realizing 
   how many attributes some of these things have, I counter-balanced against 
   the length of the syntax mockup. I think you're probably right anyways, and 
   I think your point about a maintained table of example values per type 
   makes sense - good idea. But take a look at something like <$edit-text/> 
   which has 20 attributes. At a certain length, I worry we would lose people, 
   or you then get into a kind of stepped layout where each attribute gets a 
   newline?
   - I agree on the order, I did put all the required ones first, and then 
   took some liberty on ones I thought were most common, but alphabetical 
   probably makes more sense. Counter to that might be to bundle (sort 
   together) the ones that go together. 
   - Your last point on multiple required attributes is similar to where I 
   was thinking about too. For reference, using your example - 
   <$action-setfield> 
  - Your suggestion: <$action-setfield $tiddler="tid" ($field="field" | 
  $index = "index" | *text* field) $value="value" />  - what does the 
  *text* field part mean?
  - I was thinking about the combinations that were valid could all be 
  spelled out. For example either tiddler or field are fine, and if you use 
  index you need tiddler too.
  - So maybe: <$action-setfield ( $tiddler | $field | $tiddler + $field 
  | $tiddler + $index ) $value /> - though again that gets long if there 
are 
  lots of options like this.
   
@Tones

   - I commented on your other thread on CSS - I agree that's an 
   opportunity for a little more to be added to the documentation also
   - I also like the "copy to clipboard" piece. I saw that in many of the 
   examples and will try to implement it by reverse-engineering the core macro 
   that does it. 
   - You bring up a lot of other things that while valid, would be massive 
   scope creep on an already large effort, but I'm happy to pencil in for 
   future "phases"
  - Multiple versions of common widgets, like the filtered transclusion 
  example, good point. 
  - Documentation of macros & <$macrocall/> syntax
  - Examples should all work on TiddlyWiki.com - totally agree. I think 
  the whole "recipe book" idea as base data (as is used for some of the 
  filter stuff is a good starting point myself)
  - Test-data / plugins: Good ideas too, as above, I think a small 
  internal dataset like recipes / ingredients etc. are perfect for starting 
  though
  - Send-message vs. action widgets (paraphrasing) also valid thing to 
  further describe
  - Whole learning environment: My personal opinion based on other 
  languages is that I like the core to support main syntax and examples, 
and 
  leave external sources for more guided training (such as Soren's Grok 
book 
  and videos)
   
@Mohammad

   - I'll take a look at Shiraz and the Alert Macro as you suggest.
   - The general flow you illustrate sounds good to me, and I think is 
   similar to what TiddlyWiki has, but with just a few missing pieces.
   - Agree with you and Soren on bold / italic vs. colors, good point
   - I agree (mostly) on the consistent outline (constant number of 
   sections), though to keep the scope small, thought would be to split the 
   effort into phases to increase the liklihood of it getting finished. 
  - Syntax and Attributes table would be phase I
  - Examples and other cleanup could be phase II etc.
   - I agree on referring to the other languages for inspiration. A saying 
   I'll sometimes use is that "sometimes consistency is more important than 
   accuracy" which sounds counter-intuitive, but if the end result is 
   learning, absorbing material is job 1

@TiddlyTweeter

   - I understood where you were going with your comments in the other 
   thread. I think there is definitely a "too far" area, and having much 
   deeper learning can be better handled in other places, with other mediums 
   even
   - I agree on the scope, and will definitely not make everyone happy with 
   what I plan on doing, but I think it most prudent to break the effort into 
   phases as mentioned above. If I / we don't do this, the chance of giving up 
   before completion is high
  - Just adding the Syntax section and tweaking the Attribution section 
  is what I'm considering phase I, 

Re: [tw5] TiddlyWiki Documentation - Syntax

[Álvaro]

Thanks for the iniciative and the work.

- I think that put only name attribute could be confused for newcomers. 
They can think that widgets work like a macro, when (I think that) the 
widget works like a html tag.
- I am rethinking the idea of create a syntax example for each widget or 
macro. Maybe it is better try to do it in the widget documentation, in the 
tiddler *Widgets in WikiText*, and then create a line in each widget 
linking this tiddler. And the point "Widget attributes can be specified as:" 
will be more helpful. 

My idea would look something like this (Using some doc macro), but I was 
thinking in macros. 
\define tag-init() <
\define tag-end() >

<><<.wid Mywidget>> ''attribute1''="value1" 
//attribute1//="value1"<>
CONTENT
<>/<<.wid Mywidget>><>

But it doesn't look good (in color-contrast) in the name of widget/macro. 
And i don't know if it is cofused or not, maybe I need apply the style to 
all string of attribute ( attributeX="valueX"). Or Maybe we don't need if 
we use a table with column "type" as use Mohammad in their macros.
El jueves, 27 de mayo de 2021 a las 8:56:35 UTC+2, TiddlyTweeter escribió:

> Mohammad wrote:
>
>> I have attached a sample doc from Excel
>>
>> The same sequence: purpose, syntax, arguments (in/out parameters), 
>> remarks, examples
>>
>
> [image: Screenshot 2021-05-27 085252.jpg] 
>
> Ha. Very good example!
>
> And, YES. We are all Sinners, and especially Microsoft :-)
>
> TT
>

-- 
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 tiddlywiki+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/tiddlywiki/c0430e88-6358-4cdb-83fd-f401f73c83b3n%40googlegroups.com.

Re: [tw5] TiddlyWiki Documentation - Syntax

[TiddlyTweeter]

Mohammad wrote:

> I have attached a sample doc from Excel
>
> The same sequence: purpose, syntax, arguments (in/out parameters), 
> remarks, examples
>

[image: Screenshot 2021-05-27 085252.jpg] 

Ha. Very good example!

And, YES. We are all Sinners, and especially Microsoft :-)

TT

-- 
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 tiddlywiki+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/tiddlywiki/ff62909c-150a-46dc-af34-fba213a816dan%40googlegroups.com.