Suggestion to improve official filter documentation

,
#1

Obviously, experienced and smart users of TiddlyWiki, like @EricShulman and @Mohammad , have a good grasp of the filters.
In my case, @saqimtiaz response here is the first stance when filters made sense to me. Otherwise, I have been coasting on other people’s filters and changing operators randomly until it worked. Keep in mind that I have been using TiddlyWiki for years.
I am pretty sure there are more users like me who have trouble figuring out filters.

Taking a cue from @saqimtiaz’s excellent explanation, my suggestion to improve the filter documentation is to add pseudocode with every operator to explain its working. Or we can also use flowcharts, to explain the magic of filters.

For example, the tag filter can be explained with this pseudocode.

[tag[Example Tag]]

var output list
forEach i in all tiddlers
do
  if i.field(tag) == "Example Tag"
    push tiddler to the output list
  endif
done

print output list

Similarly, the tagging operator.

[tag[Example Tag]tagging[]]

var intermediate list
forEach i in all tiddlers
do
  if i.field(tag) == "Example Tag"
    push i to the intermediate list
  endif
done

var output list
forEach i in all tiddlers
do
  forEach j in the intermediate list
  do
    if i.field(tag) == j
      push i to the output list
    endif
  done
done

print output list
#2

@saqimtiaz quote from some other thread.

I feel coming from a programming background makes it difficult to learn TiddlyWiki customization. Its programming constructs are entirely different. The only thing I was familiar with was the markup. The rest of the concepts, like widgets and filters, were hard to wrap my head around.

If we can map the concepts of filters to know programming paradigms, it will make onboarding easier.

#3

To explain

[tag[Example]tags[]]

var output list
forEach i in all tiddlers
do
  if i.field(tag) == 'Example'
  then
    push tags in i to output list
  endif
done

print output list
#4

While this is true, the majority of TiddlyWiki users do not have a programming background and would find such additions to the reference documentation confusing and intimidating.

Do you think the proposed approach for explaining filters in this issue would have been helpful for you? (Scroll down to see the crude mockups of what the output might resemble)

#5

Oh yes! It would have been very much helpful.

Your observation of comparing filters with regex is much more apt. The mockups in the thread look great.

#6

I am familiar with pseudo code and other ways of representing filters, to be honest I see value in having other representations because your example pseudocode is quite verbose. I would think that more people would benefit from plan language;

filter [[tag[Example]tags[]] has an implied all tiddlers before it

  • The outer [ and ] wraps the filer into a single run.
  • tag[example] says to “filter out” all tiddlers without the tag example
    • in other words "keep only those with the tag example", that is it returns a list of titles.
  • tags[] takes each tiddler title it is given and retrieves all tags on each title.
    • the result will be “a list of tags found on all tiddlers with the tag Examples”. if the tag is used more than once it will be “de-duplicated” keeping only the unique list tag names. Tag names is also a list of titles.

I suppose the point is we could publish a few different ways to represent filters depending on people with different backgrounds.

#7

@talha131 and all,

More intuitive documentation of filters would be fabulous.

I often visit tiddlywiki.com and tobibeer’s reference site (Filters — filter and list examples)… and still often pour considerable (hit-or-miss) time into finding what I need.

I’m not wild about pseudo-code. It will feel intuitive only to those coming from a certain coding-oriented background, and is likely to feel alienating to others (especially if it’s verbose and/or uses terms and notation from beyond tiddlywiki).

What I’d love is careful curation of examples that are intuitive. None of the foo bar baz stuff.

So for [tag[Example]tags[]] I’d explain something like:

[tag[genus]tagging[]] returns tag-wise “grand-children” of genus tag, i.e., a list of species-level tiddlers (across multiple genus categories) available in the wiki (assuming that wolf tiddler has canis tag, while canis has genus tag, etc.).

Of course, an example is “intuitive” only relative to a background in language and cultural references. Still, if real-world reference points can be used, it’s much easier to get a feel for what the filter can do.

Also, color or font can do wonders in documentation. Any words that are merely illustrative should appear in a distinct color or font style, so it’s easier for learners to pick out where their own titles, fieldnames, tagnames, etc., can be swapped in.

-Springer

4 Likes
#8

Can’t agree more. Foo, Bar, Baz are meaningless words so the author can avoid thinking more deeply.

  • I think this can be a helpful way, ie provide a real world data set as part of the explanation however it is easy for the reader to not know enough to make use of it.
  • I have been keen for the community to build some real world data sets that would help testing, sharing and demoing more complex relationships, add some documentation and people would see Genus/Species etc… relationships. Thus we can discuss a shared data set rather than private ones.

Read forwards
[tag[Example]tags[]] Get all tiddlers with the tag example and retrieve all their tags. The result is a de-duplicated list of titles.

Read the filter backwards
[tag[Example]tags[]] Provide a de-duplicated list of ALL tags found on tiddlers with the tag example

I also think a helpful piece of documentation would involve explaining “filter delimiters” because more than one can be used in a filter [title] <var> {ref}

1 Like
#9

Another possible solution is to add “do it yourself” step-by-step exercises Wiki for filters.

The user is presented with a populated TiddlyWiki.

  1. Exercise 1: list all the tiddlers tagged with cats.
  2. Exercise 2: list all the tiddlers that link to example tiddler
  3. And so on.

Each exercise tiddler comes with hints and explanations.