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 <sto...@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+...@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/5229c588-3e58-4626-a59c-c83f50532d87n%40googlegroups.com.
