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>* ... 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>* ... 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 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.
