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) > <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/dcff4e97-53b3-44ac-9b9d-8316e4292608n%40googlegroups.com.
