Hi Stobot, You clearly explained the problem and have suggestions for improvement!
1. I asked the question to see if the problem is only me or others have the same experiences. 2. I do not expect the core developer to correct the docs as they are very busy! 3. I think a better template for filter operator is needed in such a way newcomer can understand the syntax better 4. I agree with your suggestion. WE NEED TO HELP! Best wishes Mohammad On Tue, May 25, 2021 at 4:05 PM Stobot <[email protected]> wrote: > Mohammad, you point to something I personally agree is a learning curve > (and I think unnecessarily so) for those who use similar "formula > languages" to those I'm used to. My background is more Windows/Office > stuff, so Excel, VBA, M, DAX, R, AutoIT etc. and there is typically a > nearly standard way of documenting the functions (widgets in our case). > > They (like your example) start with a syntax string. I think this really > helps illustrate better HOW to use it. > > For example the common XLOOKUP function in Excel is documented > <https://support.microsoft.com/en-us/office/xlookup-function-b7fd680e-6d10-43e6-84f9-88eae8bf5929> > like: > =XLOOKUP(lookup_value, lookup_array, return_array, [if_not_found], > [match_mode], [search_mode]) > ...and then immediately below that is a table with each of the parameters, > whether they're required, what each option is and does, and what happens if > it's omitted > ...and then examples immediately follow (not sure why the TiddlyWiki > examples are often (though not always) in separate tiddlers. > > Even just seeing in order how it's all pieced together, and then note the > square bracket parameters which seems nearly universally to mean optional > (at least in the languages described above). In some languages they even > put the default right in the syntax line. That was Excel, but a similar > pattern seems to be present in at least the other languages I use. > > So, for most widgets I'd suggest it would be easier to start with a > similar syntax pattern before going into parameters. Now picking what > brackets etc. to use in TiddlyWiki is a little more difficult since all of > them are already actually used, but taking a crack at it... for example the > <$wikify> would get a: > *<$wikify name=<variable name> text=<text to wikify> [type=<ContentType > (default text/vnd.tiddlywiki)>] [mode=<parse mode (default:block)>] > [output=<output type (default:text)>] >* > * Text where <variable name> is available* > *</$wikify>* > very nice! > ... and then the table for each of those like the documentation already > has largely. > > Now your example, a filter operator is slightly different, but a similar > methodology could apply. Maybe include the whole list piece like you do > already > *<$list filter="[<input>addsuffix<suffix>]">* > * The output of each input from the filter with the additional suffix* > *</$list>* > *<$list filter="[<input>addsuffix:<suffix><filter-op-param>]">* * The output of each input from the filter with the additional suffix* *</$list>* yes, we have little chars to use for syntax demonstration for example optional param, user given input, required param,... > ... and then a table for input, suffix, and output. Input and output > already have something, but a row for suffix could be there saying "string > of text to add" or something. > > Anyways, I'm sure that can be refined, but circling back to your specific > questions: > 1. I don't have better resources, I find that the example pages are > currently where I start (I guess because I think syntax first) and then > come back > 2. Experience seems similar to yours. I'm often very confused until I see > enough examples (especially the ones with all of the colons - though love > how powerful they are) > 3. Above is at least an idea of how to improve > very nice! > > > On Tuesday, May 25, 2021 at 1:42:38 AM UTC-4 Mohammad wrote: > >> I was reading the some filter operator they looks like this >> >> addsuffix Operator >> <https://tiddlywiki.com/prerelease/#>3rd February 2015 at 10:02pm >> Filter OperatorsString Operators >> input <https://tiddlywiki.com/prerelease/#Filter%20Syntax> a selection >> of titles <https://tiddlywiki.com/prerelease/#Title%20Selection> >> output the input, but with S added to the end of each title >> >> Examples >> <https://tiddlywiki.com/prerelease/#addsuffix%20Operator%20(Examples)> >> >> >> How can I realise I should use this filter operator like below: >> >> >> <$list filter="[[inputlist]addsuffix[mysuffix]]"> >> >> How should I understand it needs an input parameter which is different >> from input from a previous step? >> >> In my opinion filter operators are an ESSENTIAL part of Tiddlywiki which >> is also the most confusing part! >> >> My questions are: >> >> 1. DO you have better references for using and working with filters? >> Please share links, resources, ... >> 2. What is your experience using official documentation for filter >> operators? >> 3. How do you recommend to improve these documentations? >> >> >> Some references to help improve the filter operators documentation >> >> [1]. TW-Scripts >> [2]. PowerSearch >> [3]. Grok Tiddlywiki >> [4]. Tobias Beer Filter References >> [5]. S.S draft for restructuring TW documentation >> [6]. Tones GitWiki >> >> >> >> Best wishes >> Mohammad >> > -- > 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 [email protected]. > To view this discussion on the web visit > https://groups.google.com/d/msgid/tiddlywiki/8698e7d4-be6d-4701-8a62-62077c9628a0n%40googlegroups.com > <https://groups.google.com/d/msgid/tiddlywiki/8698e7d4-be6d-4701-8a62-62077c9628a0n%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 [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/tiddlywiki/CAAV1gMC7iRLwH3oRmNmJc3b-cpf2_6iJzdB4JPkEjOB%3DdnkHnQ%40mail.gmail.com.
