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.
