More documentation for :intersection filter prefix (#5051)

editions/tw5.com/tiddlers/filters/syntax/Filter Expression.tid

@@ -56,3 +56,15 @@ In order to remove `$:/baz` in any case, existing or not, simply use the `+` pre
 
 * <$link to="is Operator">`foo bar $:/baz +[!is[system]]`</$link>
 * <$link to="prefix Operator">`foo bar $:/baz +[!prefix[$:/]]`</$link>
+
+There is also a difference between the `:intersection` and `+` prefixes due to varying inputs.
+
+The `+` prefix should be thought of as an "AND" in formal logic, e.g. "give me all titles that satisfy condition A ''and'' condition B". But it's not suitable for all cases; if condition B uses a filter operator that replaces its input, then it will be difficult to use the `+` prefix. For example, if you wanted to find out what tags two tiddlers have in common, you might try to write a filter expression like:
+
+* <$link to="tags Operator">`[[field Operator]tags[]] +[[compare Operator]tags[]]`</$link>
+
+But that won't work, because the second filter run will end up throwing away its input and replacing it with an input consisting of the single title `[[compare Operator]]`. So the result you'd get from that filter expression would be just the tags of the `compare Operator` tiddler.
+
+For cases like this, the `:intersection` prefix is what you need. It takes the filter output so far, //sets it aside// in temporary storage, and starts the next filter run with all tiddler titles as input. Then once the latest filter run has completed, it takes the latest output, compares it to the set-aside output, and produces a new output that contains only titles that appeared in both the set-aside output and the latest output. So to get only the tags that the `field Operator` and `compare Operator` tiddlers have in common, you would write a filter expresison like this:
+
+* <$link to="tags Operator">`[[field Operator]tags[]] :intersection[[compare Operator]tags[]]`</$link>