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 <stob...@gmail.com> 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) > <https://docs-syntax.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 <sto...@gmail.com> 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 / 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, Examples maybe phase II, >>>> and then >>>> other areas besides widgets (filter operators, macros, CSS, SVG etc. >>>> could >>>> come later) >>>> >>>> @Álvaro >>>> >>>> - That point is really valid and Soren agrees. As I mentioned to >>>> him I only worry about the length, but you additionally make the point >>>> that >>>> without it, people could falsely assume that you can omit the parameter >>>> name and have it work in a position-based way, which you can't. So maybe >>>> I'll have to relent there. >>>> - I'm not clear on your second point. I will say that the mockup >>>> does in fact use a macro as a template as you describe if you scroll >>>> down a >>>> bit, so all of the parameter information is in fields and the syntax >>>> bit is >>>> generated centrally so it can be tweaked. If you mean something else, >>>> maybe >>>> elaborate a bit more? >>>> >>>> All, thank you again for the feedback, I'll take another look tonight >>>> and incorporate what I can from the above. As mentioned I'll intend to do >>>> this in phases and at least make it through Phase I. My day-job is quite >>>> strenuous right now (normally 12-hours/day X 5 days and then maybe 4 >>>> hours/day on the weekend), so this will go slowly. For those curious, I run >>>> a team of project managers, so that's where my background of project >>>> managent, scope, requirements etc. comes from. >>>> >>>> Parting questions for now: >>>> >>>> - Is there a better way to get per-tiddler commentary? I think I >>>> mentioned doing the Disqus thing, is anyone interested in participating >>>> that way? I wish there was a multi-user environment available for this >>>> kind >>>> of thing. >>>> - Who has to approve this for it to get implemnted? I know >>>> @Mohammad offered to turn the result of this into a pull-request. I >>>> still >>>> worry we might get to the end of this whole effort and the right person >>>> doesn't say yes? >>>> >>>> >>> Sure! I help with PRs! No worries on this and if you like I can prepare >>> a short slideshow to teach you how to do so! I am sure Saq and Jeremy will >>> be there to answer our questions and give advice on how to do this! >>> >>> >>> >>>> On Thursday, May 27, 2021 at 2:56:35 AM UTC-4 TiddlyTweeter wrote: >>>> >>>>> 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+...@googlegroups.com. >>>> >>> To view this discussion on the web visit >>>> https://groups.google.com/d/msgid/tiddlywiki/9936c0a8-f090-4973-bdc6-d4551b5e5879n%40googlegroups.com >>>> <https://groups.google.com/d/msgid/tiddlywiki/9936c0a8-f090-4973-bdc6-d4551b5e5879n%40googlegroups.com?utm_medium=email&utm_source=footer> >>>> . >>>> >>> -- > 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/e126ce9d-38b6-4d15-83ff-9108397b070dn%40googlegroups.com > <https://groups.google.com/d/msgid/tiddlywiki/e126ce9d-38b6-4d15-83ff-9108397b070dn%40googlegroups.com?utm_medium=email&utm_source=footer> > . > -- 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/CAAV1gMDS7ORsVF%2BcpFqL7naHeXcGD%3DgHp6GdVOEqrnJhr%3DpySg%40mail.gmail.com.
