From f5ad5010bc642f7f5a76e492c9fa89fbc607ac28 Mon Sep 17 00:00:00 2001
From: saqimtiaz <saq.imtiaz@gmail.com>
Date: Wed, 28 Oct 2020 13:00:18 +0100
Subject: [PATCH] Added documentation for ':filter' prefix for filter runs.
 (#4920)

---
 editions/tw5.com/tiddlers/filters/filter.tid     | 16 +++++++++++++++-
 .../filters/syntax/Filter Expression.tid         |  7 +++++--
 2 files changed, 20 insertions(+), 3 deletions(-)

diff --git a/editions/tw5.com/tiddlers/filters/filter.tid b/editions/tw5.com/tiddlers/filters/filter.tid
index faca51090..62619c20f 100644
--- a/editions/tw5.com/tiddlers/filters/filter.tid
+++ b/editions/tw5.com/tiddlers/filters/filter.tid
@@ -1,6 +1,6 @@
 caption: filter
 created: 20200929174420821
-modified: 20201006173606828
+modified: 20201027185144953
 op-input: a [[selection of titles|Title Selection]] passed as input to the filter
 op-neg-input: a [[selection of titles|Title Selection]] passed as input to the filter
 op-neg-output: those input titles that <<.em "do not">> pass the filter  <<.place S>>
@@ -30,4 +30,18 @@ Simple filter operations can be concatenated together directly (eg `[tag[HelloTh
 
 <<.tip "Compare with the similar [[subfilter|subfilter Operator]] operator which runs a subfilter and directly returns the results">>
 
+<<.tip "Compare with the analagous named filter run prefix `:filter`">>
+
+```
+\define larger-than-1k() [get[text]length[]compare:integer:gteq[1000]]
+
+{{{ [tag[HelloThere]filter<larger-than-1k>] }}}
+```
+
+is equivalent to:
+
+```
+{{{ [tag[HelloThere]] :filter[get[text]length[]compare:integer:gteq[1000]] }}}
+```
+
 <<.operator-examples "filter">>
diff --git a/editions/tw5.com/tiddlers/filters/syntax/Filter Expression.tid b/editions/tw5.com/tiddlers/filters/syntax/Filter Expression.tid
index c78066833..1b67a98b8 100644
--- a/editions/tw5.com/tiddlers/filters/syntax/Filter Expression.tid	
+++ b/editions/tw5.com/tiddlers/filters/syntax/Filter Expression.tid	
@@ -1,5 +1,5 @@
 created: 20150124182421000
-modified: 20201027134811701
+modified: 20201027185638636
 tags: [[Filter Syntax]]
 title: Filter Expression
 type: text/vnd.tiddlywiki
@@ -19,9 +19,12 @@ If a run has:
 * no prefix, its output titles are [[dominantly appended|Dominant Append]] to the filter's output
 * <<.from-version "5.1.20">> the prefix `=`, output titles are appended to the filter's output without de-duplication
 * the prefix `-`, output titles are <<.em removed>> from the filter's output (if such tiddlers exist)
-* the prefix `+`, it receives the filter output so far as its input; its output then <<.em "replaces">> all filter ouput so far and forms the input for the next run
+* the prefix `+`, it receives the filter output so far as its input; its output then <<.em "replaces">> all filter output so far and forms the input for the next run
 * <<.from-version "5.1.18">> the prefix `~`, if the filter output so far is an empty list then the output titles of the run are [[dominantly appended|Dominant Append]] to the filter's output. If the filter output so far is not an empty list then the run is ignored
 * <<.from-version "5.1.23">> named prefixes for filter runs are available.
+* <<.from-version "5.1.23">> named prefix `:filter`, it receives the filter output so far as its input. The next run is evaluated for each title of the input, removing every input title for which the output is an empty list.
+
+<<.tip "Compare named filter run prefix `:filter` with [[filter Operator]] which applies a subfilter to every input title, removing the titles that return an empty result from the subfilter">>
 
 In technical / logical terms: