I think chances are high, that we can create a whole wiki for every filter operator and we still won’t cover all the possible usecases.
Grok-TiddlyWiki has a good introduction, with some questions and answers linked to it. Grok TiddlyWiki — Build a deep, lasting understanding of TiddlyWiki … But it also only shows the filter string and no bigger context.
There may be better links in Grok-TW, but I don’t know it well enough to point them out.
Thanks all for the discussion - this is truely a great forum!
The docs regularly take a kicking but they’ve done the job for so many users so far - maybe I should have floated this as a constructive ‘enhancement’ rather than a negative ‘alteration’? Positive thinking can move mountains (of documentation)!
Instead of changing the existing macro what about keeping it as is, (but maybe labelling the existing ‘bare bones’ examples ‘Pure Filter’) and just add a second macro (maybe labelled as ‘List widget example’ with a copy to clipboard button)? Anything that produces ‘working’ cut and pasteable code would add clarity imo.
Is it bad to have too many examples?
The addition could possibly include the Learn more about how to use Filters link that already appears on Filter Operator doc tiddlers. Maybe even add another link, ‘Beyond list widgets’? Turn it into more of a pointer for learners.
The beauty of this approach is that making a few changes to the macros on one page adds a lot of value across all the documentation for minimal effort. (imo!)
That $:/editions/tw5.com/operator-macros page seems to hold an awful lot of documentation power! Thanks to @Charlie_Veniot for pinpointing it in another thread.
Of course none of this works if the changes would break existing examples.
In that case would a coding challenge to add a filter to the suggested macro which id’s and conditionally hides the proposed ‘enhancements’ where it doesn’t work make for a fun Easter hunt?
Best wishes Tiddlywikians, Happy Easter.
Well, I am extremely opinionated about documentation (organization and process). Documentation is one bit of my career bread and butter, and I am easily unsatisfied.
Probably best to not throw any appreciation my way, because as of that referenced thread, I decided to remove myself from any conversation involving TiddlyWiki documentation (this reply the exception?). Best for everybody.
Instead of yanging (edit: by that I do mean me, because I’m so opinionated, and not implying other folk who want legit help from the documentation) about TiddlyWiki documentation, I focus on continuously honing my approach to documentation with my BASIC Anywhere Machine project, in particular the Machine (IDE etc.) TiddlyWiki and the Programming Reference TiddlyWiki.
Of note, take a peek at how the Programming Reference “sucks in” programs from the machine, so that when looking up a BASIC statement/function in one TiddlyWiki, the documentation includes sample programs from the machine (that use the statement/function) in the other TiddlyWiki and provides a RUN button so that you can see the program running while viewing the documentation for the statement/function of interest and the program source code.
So every single thing exists once in some TiddlyWiki, and every single thing is view-available from any TiddlyWiki.
I love that kind of stuff:
Rock’n roll.
You have definitely read and understood the manual @Charlie_Veniot ! The Basic Anywhere Machine pushes envelopes further than my postman at Christmas, please don’t blow an opinionated gasket and disappear from the lovefest that is tiddlywiki.
For the record here is some crude code that can be pasted into $:/editions/tw5.com/operator-macros on tiddlywiki.com, immediately before the
</$reveal>
</$list>
\end
of the macro defined as .operator-example(n,eg,ie).
It adds the ‘enhancement’ unobtrusively to the ‘try it’ button, allowing clipboard copying of a list widget example on filter operator example tiddlers.
<details><summary>more...</summary>
<$macrocall $name="copy-to-clipboard-above-right" src="""<$list filter="$eg$"/>"""/>
`<$list filter="$eg$"/>`
<p>
Learn more about how to use [[Filters]]
</p>
</details>
Best wishes
That’s the kind of warm fuzzy to make my week.
For anybody who can handle the process and give the documentation some love (even just suggestions posted here in TiddlyTalk), that is a substantial gift.
This forum also offers up a feature for “wiki articles,” which folk seem to like. (Not my cup of tea. Forum and wiki and blog, I like neatly separated. Like a kid who doesn’t like peas touching the potatoes, nor the potatoes touching the chicken fingers. Yeah, cognitive disability over here, and no OCD diagnosis? Go figure …)
Yes I believe it is better to highlight areas of confusion. Even as someone like myself who has been using TiddlyWiki for quite awhile I find the way the documentation approaches certain topics, in particular filter operators rather confusing. It is absolutely possible to use TiddlyWiki for awhile and still not understand the many sophisticated methods of transclusion, filtering, and listing that are possible (new features are constantly being added too and best practices might change)
It is important to think in terms of a certain “tiddly” philosophy, namely to compose your content in such a way that enables re-use, “dividing information into the smallest semantically meaningful units of text”. The Filter Operator tiddler uses many of the advanced techniques TiddlyWiki offers in the way it generates the table listing the filter operators, even though it is hard to copy and paste this into your own wiki.
Just when I think I’m doing well at keeping my nose out of “TiddlyWiki Documentation” topics, I get a random thought out of nowhere.
I think the biggest problem with TiddlyWiki documentation is the use of TiddlyWiki for documentation.
A case in which “eat your own dog food” is maybe not such a great idea.
Two points, both in regards to multi-user/community collaboration:
Both of these are complicated, convoluted, when using TiddlyWiki for collaborative documentation (or content/KB/whatever).
If it can all be done easily, I have no knowledge of that. Because I cannot find documentation about making it easy, and with my own experience thus far: not easy.
But if you are like me and like hacking away at things for the joy of it, it can be done.
I know how to go about it with TiddlyWiki. But do I want to? Not so much. It was fun figuring it out as a brain-age game, but would I do it again? Otherwise: nah. Did it once, don’t particularly fancy doing it again. Well, maybe for the right $$$'s ?
Although there probably aren’t many folk who find joy working on documentation, I think decent documentation depends more on easy technical setup/architecture and easy process much more so than the number of collaborators.
I think quality documentation might be better served by documentation managed with a tool that makes process much easier, leaving TiddlyWiki.com purely for the examples of how to do this/that (which is documented somewhere else, which points to those examples at TiddlyWiki.com .
Something like that. Too many intertwingled thoughts in this sponge…
These are just some of the scattered thoughts I have on the whole thing.
Nailed. 
Positive thinking is the way to go guys! Huberman labs on mindsets!
Documentation does exist, it’s pretty good, just not perfect for everybody ….yet. And if we don’t like it we can always ask for our money back, right?
As the prolific @TW_Tones said “the best way to improve documentation, is to do some documentation.” @pmario and @saqimtiaz have kindly made it possible for anyone to contribute to the docs with these 7 Steps to Improve the TiddlyWiki Documentation, so that’s what I’ll try to do over Easter and make a pr request with this small suggestion. After that I’m going to try to read and understand the bleedin manual!
Best wishes
Sometimes, one may be just lucky enough to lead a critter to water, but if it ain’t gonna drink, then kind of a fool’s errand.
Maybe stubborn mule am I to keep thinking the process and the chosen tool is the problem. (To think otherwise, then subpar documentation symptoms are a people problem, and I’d rather not think that.)
Proof in the pudding either way.
Paraphrasing the gist of the OP:
I agree, the doc examples would bring more value if they were about filtering rather than about filters.
If the users are guided with actual use cases, using the ListWidget, they will probably more easily get a general understanding of filters - i.e that translates to other contexts where a filter attribute is used.
In fact, the distinction between a “list” and a “filter” is not clear: What even is a list that is not a filter? It is an oxymoron. “To filter” intrinsically means “to list”, and vice versa, so specifically using the ListWidget makes sense because . All(?) other widgets with a list attribute do further manipulations with the output but the ListWidget only presents the output and is therefore the “minimal” use case of a filter.
…
Overall, I think a nice balance in the docs would be if the docs are framed as “reference” but all examples in the docs should be about doing rather than just informing. Presumably, someone looking at the example does so because the bare bones reference fact was not enough.
I agree in the sense that IF you copy an example it should produce effects in a destination wiki. Otherwise it is a copied example of nothing,
That said, I don’t think the documentation for TW should support every example fully … MERELY, that when you offer code to copy it should function without extras to DO something.
Just a comment
TT
I agree with @saqimtiaz . I have doubts about it.
Change examples or add a tip notes about how/where we can use a filter? How could we show this notes? How could we change the examples without losing attention in the use of filters?
I don’t know if it is good idea use listwidget in examples. I think the filtered transcusion could be less complex to understand for newcomers.
I’m sure the guys actually doing the documentation go nuts when they see questions like these. Sorry documenteers! I’ll try and do a PR with this suggestion, unless anyone comes up with some specific code that would improve on my cack-handed efforts. If you actually try pasting this into $:/editions/tw5.com/operator-macros on tiddlywiki.com, immediately before the
</$reveal>
</$list>
\end
of the macro defined as .operator-example(n,eg,ie).
It adds the ‘enhancement’ unobtrusively to the ‘try it’ button on filter operator example tiddlers, allowing clipboard copying of a list widget example from filter operator example tiddlers, but only when you click the ‘try it’ button. It doesn’t change the display of the existing ‘bare bones’ filters at all. Win-Win!
<details><summary>more...</summary>
<$macrocall $name="copy-to-clipboard-above-right" src="""<$list filter="$eg$"/>"""/>
`<$list filter="$eg$"/>`
<p>
Learn more about how to use [[Filters]]
</p>
</details>
If you look at the suggestion as more of a layout issue there’s nothing to stop a whole range of examples and explanation being included in that space. There is a lot of ‘real estate’ there, but it is way beyond my abilities to know how best to populate it. If only a ‘comments’ widget could be dropped in there, then users could add targeted ‘tips’ organically, and the docs would just grow. But I suppose that’s not far off being a forum!
Best wishes
Cutting a long story short.
I do think if you provide an ability to copy code for an example it should, in a destination wiki, once copied, DO something.
I do understand that is not always possible as a local example may have dependencies on local stuff to work. But in those cases I don’t think giving a “copy-to-clipboard” button is good. It is confusing until you better know what is going on.
Side comment, TT
Good point TT. Maybe a proviso of some kind - ‘try here on tiddlywiki.com to see results, or adapt the example to use with your own wiki and data’. Sounds a bit wordy - economic layout would need to be considered.
I’ll try the PR route and see what comes back. As @Mark_S. said, if some examples break then it may be a non-starter. That ‘try it’ button is intriguing though!
Best wishes
I just want to put a different position. I am all for working examples and believe tiddlywiki is the best place given the content to work with. Alternatively an optional plugin of examples and test data would be good as this need not overload the main site, and be installable on empty.
However my key interest is template code that has place holders like tiddlername, fieldname, tagname and varname with each common form of the use of a macro or widget for quick copy and paste into my own code. To me this is much more valuable than working examples because its a faster path to experimenting on my own wikis.
The key advantage of optional plugins is the reduced complexity of updates and contributions with less impact than in public websites, increased transferability, reduced size impact unless wanted, removability and the upgradeability through updates.
Came here to say this but of course it’s already being discussed. As a self learner I rely heavily on examples to help me understand the instructions and when you can’t copy paste an example and have it workable and playable with it’s not very useful. The filter documentation gives examples of how to use the operators but does nothing (as far as I can see and I miss stuff all the time) to say where or in what context those operators are used.
An example should show context. Personally I learn mostly by backtracking through something I don’t understand but without any sort of contextual example there is nowhere to go. The context also provides a reminder for infrequent ‘coders’ like myself who might use tiddlywiki for a specific purpose for a long time and just need some prompting when trying something new.
I think instead of a ‘try it’ button it would be more helpful to describe a working example and say ‘create a new tiddler and copy and paste this code into it to see it work’.
I find running filter syntax through the Filter tab in AdvancedSearch to be a helpful way to test out the filter syntax.
I also suggest if you make a filter, to store the filter syntax in a field of a tiddler. That way you can separate the filter syntax from the other parts of formatting. See this attached example of AllTiddlers, which is a very simple example, but you could modify the filter field to use as an experiment.AllTiddlers.tid (164 Bytes)
Good Share, but I noticed the macro call was not closed
Was <$macrocall $name=list-links filter={{!!filter}}>
<$macrocall $name=list-links filter={{!!filter}}/>
unlikely to have any effect until more in tiddler