Feedback on documentation of filter operators

#41

I’ll try writing one :+1:

#42

Here’s a small sample testcase for list-item:

<$list filter="[tag[Book]each:list-item[author]]" variable="author">
  <$link to=<<author>>/>
  <<list-links filter:"[<author>listed[author]tag[Book]]">>
</$list>

This is useful to list books that have multiple authors:

image

But it require to write the name of the author in a title list format ([[ … ]]).

each Operator Example 4.json (2.7 KB)

It would probably be a good idea to put the list of books in a separate tiddler and use it as a payload for the various examples.

Note that the testcase widget is not the preferred style for writing filter doc, at least for now: Add example for the function operator by DesignThinkerer · Pull Request #8793 · TiddlyWiki/TiddlyWiki5 · GitHub

1 Like
#43

Most filter examples are directly demonstrating the filter expression. These each examples are also using widgets to make the usage more clear. IMO, it makes perfect sense to use the testcase widget.

In the PR you linked to I liked the testcase widget version better. In my mind the rule should be that if examples use variables and/or other tiddlers and/or any wikitext, the testcase widget is the best vehicle for demonstration.

2 Likes
#44

First of all, :100: for Good Omens. I love that book!

This is great. Any objection if i cut it down to Gaiman and Pratchett… and maybe add one more multi-author book?

Also thank you for the gentle correction. With the output tiddler visible by default, there is little reason to duplicate the code as a code-block.

I would love to! Is that possible? I haven’t seen how, and was planning on requesting that feature. Do you a pointer?

On top of Brian’s excellent response, please note that as well as documenting each, I also want to use this as an example of moving beyond our usual style of examples, which has all working examples drawn from one style of wiki: namely a documentation/demo wiki for a tool. I think it makes our documentation much less useful than it might be. A list of Books/Authors/Publishers/More? would be easily understood. (For thism reusing such a payload would be essential.)

1 Like
#45

I read about it on the tiddler documenting the test case widget:

image
image1334×596 68.2 KB

It was not very clear to me how to do it, so I wanted to see how the testcase macro that the doc is using is defined. I didn’t found documentation about it, so I had to do a bit of digging. This macro is defined in the tiddler $:/core/macros/testcase and simply transclude this tiddler:

$:/core/ui/TestCaseTemplate

\parameters (hideIfPass:"no")
\whitespace trim
<$let
	linkTarget="yes"
	displayFormat={{!!display-format}}
	testcaseTiddler=<<currentTiddler>>
>
	<$testcase
		testOutput="Output"
		testExpectedResult="ExpectedResult"
		testActions="Actions"
		testHideIfPass=<<hideIfPass>>
	>
		<$data $filter={{!!import}}/>
		<$data $compound-filter={{!!import-compound}}/>
		<$data $compound-tiddler=<<currentTiddler>>/>
		<%if [{!!description}!is[blank]] %><$data title="Description" text={{!!description}}/><%endif%>
	</$testcase>
</$let>

According to the doc for the data widget:

  • $tiddler is used to specify the title of a tiddler to be used as a payload tiddler
  • $filter is used for identifying tiddlers to be used as payload tiddlers
  • $compound-tiddler is the same as $tiddler but for the new compound tiddler data type (multiple tiddlers in one)
  • $compound-filter is the same as $filter but for a list of compound tiddler

Therefore, if we want to re-use the testcase macro, we could use the same list of books in several testcases by using the field import-compound set to the name of the tiddler containing the list of books:

image
image1311×650 37.4 KB

each Operator Example 4 - importing books as payload.json (2.8 KB)

It would be great to properly document the testcase macro, especially if we are going to use it extensively from now on.

PS: I agree with you, cutting down the list of books would probably be a good idea ^^

1 Like
#46

Thank you! I had read the testcase docs a number of times but hadn’t gone to the data ones. I really didn’t get any sense that there actually was an import process involved. This is very good news for my ideas on documentation!

#47

No real time for commentary, but I’ve created another version:

EachDocs.json (9.9 KB)

It still needs an example for each:value, but I think it’s getting there.

I was also happy to note that import-compound can hold a list of CompoundTiddler titles. That is making it easier and easier to think about my idea of having 5 - 10 mini-wikis used for various examples.

1 Like