Overhaul the filter operator documentation: part 2

editions/tw5.com/tiddlers/concepts/AbsoluteOperators.tid

@@ -1,11 +1,13 @@
 created: 20150117204109000
-modified: 20150119190116000
+modified: 20150124185709000
 tags: Concepts
 title: Absolute Operators
 type: text/vnd.tiddlywiki
 
-The output of a filter step depends on its [[operator|Filter Operators]]:
+The output of a [[filter|Filters]] step depends on its [[operator|Filter Operators]]:
 
 * Most operators perform <<.def relative>> to their input. They examine each input title in turn and filter out any that don't match. Such steps narrow down the output of a run.
 
-* <<.def Absolute>> operators ignore their input and generate an independent output instead. <<.olink title>> is an example: the result of `[title[A]title[B]]` is `B`. But the <<.olink field>> operator is relative, so the result of `[title[A]field:title[B]` is empty.
+* <<.def Absolute>> operators ignore their input and generate an independent output instead.
+
+A good example of an absolute operator is <<.olink title>>. The output of `[title[A]title[B]]` is just <<.tid B>>. But the <<.olink field>> operator is relative, so `[title[A]field:title[B]` outputs nothing at all.

editions/tw5.com/tiddlers/concepts/DominantAppend.tid

@@ -1,11 +1,11 @@
-created: 20151714300000000
-modified: 20150119191515000
+created: 20150123220223000
+modified: 20150124185028000
 tags: Concepts
 title: Dominant Append
 type: text/vnd.tiddlywiki
 
-A <<.def "dominant append">> is a frequent occurrence in [[filter|Filters]] processing.
+[[Filters]] manipulate [[sets of titles|Title Selection]] in which no title may appear more than once. Furthermore, they often need to append one such set to another.
 
-Filters manipulate [[selections|Title Selections]] in which no title can appear more than once, and they often append one selection to another.
+This is done in such a way that, if a title would be duplicated, the earlier copy of that title is discarded. The titles being appended are dominant.
 
-This is done in such a way that if the result would contain two copies of the same title, the <<.em earlier>> one is removed. The appended titles thus dominate over any earlier duplicates.
+For example, if a selection contains `Andrew Becky Clara Daniel` and `Andrew Barney Clara Daisy` is then appended to it, the result is `Becky Daniel Andrew Barney Clara Daisy`.

editions/tw5.com/tiddlers/concepts/FilterParameters.tid

@@ -1,20 +0,0 @@
-created: 20151714300000000
-modified: 20150119185917000
-tags: Concepts
-title: Filter Parameters
-type: text/vnd.tiddlywiki
-
-The parameter to a [[filter operator|Filter Operators]] can be:
-
-;<<.def direct>>
-: `[like this]`
-: Literal, treated at face value
-;<<.def indirect>>
-:<<.def transcluded>>
-:: `{like this}`
-:: The value of a field of a specified tiddler, or the value of a property of a specified [[data tiddler|DataTiddlers]]
-:<<.def variable>>
-::`<like this>`
-:: The value of the specified [[variable|Variables]]
-
-See [[Filter Syntax]].

editions/tw5.com/tiddlers/concepts/Filters.tid

@@ -1,5 +1,5 @@
 created: 20130827080000000
-modified: 20150119191522000
+modified: 20150124183938000
 tags: Reference Concepts
 title: Filters
 type: text/vnd.tiddlywiki
@@ -7,7 +7,7 @@ list: [[Introduction to filter notation]] [[Filter Syntax]]
 
 You can think of TiddlyWiki as a database in which the records are tiddlers. A database typically provides a way of discovering which records match a given pattern, and in ~TiddlyWiki this is done with filters.
 
-A <<.def filter>> is a concise notation for selecting a particular [[set of tiddlers|Title Selections]], known as its <<.def "output">>. Whenever ~TiddlyWiki encounters a filter, it calculates the output. Further work can then be done with just those tiddlers, such as [[counting|CountWidget]] or [[listing|ListWidget]] them.
+A <<.def filter>> is a concise notation for selecting a particular [[set of tiddlers|Title Selection]], known as its <<.def "output">>. Whenever ~TiddlyWiki encounters a filter, it calculates the output. Further work can then be done with just those tiddlers, such as [[counting|CountWidget]] or [[listing|ListWidget]] them.
 
 The following example passes a filter to the [[list-links macro|ListMacro]] to display a list of all tiddlers whose titles start with the letter H:
 
@@ -21,5 +21,5 @@ A filter's output can change as tiddlers are added and deleted in the wiki. ~Tid
 
 ;Find out more:
 * [[Introduction to filter notation]] -- a step-by-step walkthrough
-* [[Filter Syntax]] -- the exact rules of the notation
+* [[Filter Syntax]] -- the detailed technical rules
 * [[Filter Operators]] -- the available methods of filtering

editions/tw5.com/tiddlers/concepts/HardAndSoftLinks.tid

@@ -0,0 +1,15 @@
+created: 20150123220237000
+modified: 20150124120447000
+tags: Concepts
+title: Hard and Soft Links
+type: text/vnd.tiddlywiki
+
+A <<.def "hard link">> is one that can be detected by a superficial examination of WikiText.
+
+A link is <<.def "soft">> if it is:
+
+* contained in text [[trancluded|Transclusion]] from elsewhere
+* supplied via a [[macro|Macros]] or [[variable|Variables]]
+* generated by a link widget whose <<.attr to>> attribute is a transclusion, macro or variable
+
+Soft links are not detected by link-related filter operators such as <<.olink backlinks>>, <<.olink links>>, <<.olink all>> and <<.olink is>>.

editions/tw5.com/tiddlers/concepts/ObservableLinks.tid

@@ -1,20 +0,0 @@
-created: 20130825202900000
-modified: 20150117152438000
-tags: Concepts
-title: Observable Links
-type: text/vnd.tiddlywiki
-
-An <<.def "observable link">> is a [[link|TiddlerLinks]] whose presence can be detected by a superficial examination of WikiText.
-
-A link is <<.em not>> observable if it is:
-
-* contained in text [[transcluded|Transclusion]] from elsewhere
-* supplied via [[Macros]] or [[Variables]]
-* generated by a <<.wlink LinkWidget>> widget whose `to` attribute is a transclusion, macro or variable
-
-Unobservable links are <<.em ignored>> by the link-related [[Filter Operators]]:
-
-* <<.olink backlinks>>
-* <<.olink links>>
-* <<.olink2 "all[missing]" all>>
-* <<.olink2 "all[orphans]" all>>

editions/tw5.com/tiddlers/concepts/OrderOfTaggedTiddlers.tid

@@ -0,0 +1,15 @@
+created: 20150124125646000
+modified: 20150124202917000
+tags: Concepts
+title: Order of Tagged Tiddlers
+
+When ~TiddlyWiki generates a list of the tiddlers that have a particular tag (e.g. the dropdown list of a tag pill), it orders the tiddlers using the following rules:
+
+# Start with any that are [[declared|Title List]] in the <<.field list>> field of the tag tiddler, in the order given there.
+
+# In each remaining tiddler <<.place T>>, look for a <<.field list-before>> field. If this has a tiddler title as its value, place <<.place T>> just <<.em before>> that one.
+#* As a special case, if the field exists but its value is empty, place <<.place T>> at the very start of the list.
+
+# In each remaining tiddler <<.place T>>, look for a <<.field list-after>> field. If this has a tiddler title as its value, place tiddler <<.place T>> just <<.em after>> that one.
+
+# If any tiddlers still remain, place them at the end of the list. <!-- in alphabetical order if #1378 is accepted; then also update Tagging -->

editions/tw5.com/tiddlers/concepts/RailroadDiagrams.tid

@@ -1,8 +1,8 @@
 created: 20150105133800000
-modified: 20150105134300000
-title: RailroadDiagrams
+modified: 20150124181306000
+title: Railroad Diagrams
 
-Railroad diagrams, sometimes called syntax diagrams, are a visual way of explaining the syntax rules of a computer language. Reading one is like reading a public transport map.
+<<.def "Railroad diagrams">>, sometimes called <<.def "syntax diagrams">>, are a visual way of explaining the syntax rules of a computer language. Reading one is like reading a public transport map.
 
 Each diagram starts on the left and ends on the right. Simply follow any line from the startpoint to the endpoint. All the alternative lines are equally valid. A line will sometimes jump over an item that is optional, or loop back to indicate that an item can be repeated.
 
@@ -14,4 +14,4 @@ In the example above, a comma appears between each occurrence of the `repeated`
 
 Characters in round boxes are literal, i.e. they denote themselves. A name in a rectangular box denotes a further railroad diagram.
 
-The railroad diagrams on this site are generated with the [[Railroad Plugin]].
+The railroad diagrams in ~TiddlyWiki's documentation are generated with the [[Railroad Plugin]].

editions/tw5.com/tiddlers/concepts/TextReference.tid

@@ -1,5 +1,5 @@
 created: 201308270759
-modified: 201311011115
+modified: 20150124211238000
 tags: Concepts
 title: TextReference
 
@@ -14,7 +14,7 @@ Text references are made up of several parts, most of which can be optional:
 
 Text references can be used in several places:
 
-* As IndirectOperands within [[Filters]] (eg, `<$list filter="[tag{MyTag!!name}]"/>`)
+* As [[indirect parameters|Filter Parameter]] within [[Filters]] (eg, `<$list filter="[tag{MyTag!!name}]"/>`)
 * As IndirectAttributes of an element or widget (eg, `<$widget attrib={{Title!!description}}/>`)
 * As the operand of a shortcut transclusion (eg, `{{MyTiddler!!title}}`)
 * As the `state` attribute of the RevealWidget and the LinkCatcherWidget

editions/tw5.com/tiddlers/concepts/TitleList.tid

@@ -1,9 +1,9 @@
 created: 20150117152418000
-modified: 20150119191533000
+modified: 20150124205659000
 tags: Concepts
-title: Title Lists
+title: Title List
 
-A <<.def "title list">> is a line of text that contians one or more tiddler titles, strung together with a space between each one and the next.
+A <<.def "title list">> is a line of text that presents one or more tiddler titles, strung together with a space between each one and the next.
 
 If a title <<.em contains>> a space, it needs double square brackets around it:
 
@@ -11,4 +11,4 @@ If a title <<.em contains>> a space, it needs double square brackets around it:
 
 Title lists are used in various places, including PermaLinks and the ListField.
 
-They are in fact the simplest case of a [[filter|Filters]], and are thus a way of expressing a [[title selection|Title Selections]].
+They are in fact the simplest case of a [[filter|Filters]], and are thus a way of expressing a [[selection of titles|Title Selection]].

editions/tw5.com/tiddlers/concepts/TitleSelection.tid

@@ -1,10 +1,10 @@
 created: 20150117152418000
-modified: 20150119191302000
+modified: 20150124202920000
 tags: Concepts
-title: Title Selections
+title: Title Selection
 
 A <<.def "title selection">> is an ordered set of tiddler titles (or similar strings), in which no title appears more than once.
 
 Title selections are important in [[filter|Filters]] processing.
 
-The simplest way to write one down is as a [[title list|Title Lists]].
+The simplest way to write one down is as a [[title list|Title List]].

editions/tw5.com/tiddlers/demonstrations/Tasks/Kill the Dragon.tid

@@ -1,6 +1,7 @@
 created: 201308251431
-modified: 201308251431
+modified: 20150124131347000
 tags: task
 title: Kill the Dragon
+list-before: Get the Ring
 
 //This is a sample task for the TaskManagementExample//

editions/tw5.com/tiddlers/demonstrations/Tasks/task.tid

@@ -1,6 +1,7 @@
 color: #8d9ac3
 created: 201308252132
-modified: 201308252132
+modified: 20150124123528000
 title: task
+list: [[Make the beds]]
 
-Sample tasks for the TaskManagementExample.
+Sample tasks for the TaskManagementExample.

editions/tw5.com/tiddlers/demonstrations/Weekdays/Days of the Week.tid

@@ -1,8 +1,10 @@
 created: 20150117192110000
-modified: 20150118132010000
+modified: 20150123214636000
 title: Days of the Week
 type: text/vnd.tiddlywiki
 list: Monday Tuesday Wednesday Thursday Friday Saturday Sunday
+short: Mon Tue Wed Thu Fri Sat Sun
+my-special-list: [[listed Operator (Examples)]]
 
 <<.this-is-operator-example>>
 

editions/tw5.com/tiddlers/demonstrations/Weekdays/Thursday.tid

@@ -1,5 +1,5 @@
 created: 20150117192116000
-modified: 20150118131552000
+modified: 20150124204253000
 title: Thursday
 type: text/vnd.tiddlywiki
 
@@ -9,5 +9,5 @@ type: text/vnd.tiddlywiki
 
 <<.using-days-of-week>>
 
-<<.operator-example "[list[Days of the Week]before{!!title}]">>
-<<.operator-example "[list[Days of the Week]after{!!title}]">>
+<<.operator-example 1 "[list[Days of the Week]before{!!title}]">>
+<<.operator-example 2 "[list[Days of the Week]after{!!title}]">>

editions/tw5.com/tiddlers/fields/ListField.tid

@@ -1,11 +1,11 @@
 created: 20130830092500000
-modified: 20150119191334000
+modified: 20150124202924000
 tags: Fields
 title: ListField
 caption: list
 type: text/vnd.tiddlywiki
 
-The `list` [[field of a tiddler|TiddlerFields]] is an optional feature that can be used to help structure your content. Its value is a [[title list|Title Lists]], and it can be used in several ways:
+The `list` [[field of a tiddler|TiddlerFields]] is an optional feature that can be used to help structure your content. Its value is a [[title list|Title List]], and it can be used in several ways:
 
 * The `list` field of a tiddler that is being used as a tag determines the ordering of the tiddlers that carry that tag - see [[Tagging]] for details
 * The `list` [[filter|Filters]] selects the entries from a list

editions/tw5.com/tiddlers/filters/FilterOperators.tid

@@ -1,24 +1,42 @@
 created: 20140410103123179
-modified: 20150119190404000
+modified: 20150124200331000
 tags: Concepts Filters
 title: Filter Operators
 type: text/vnd.tiddlywiki
 
-A <<.def "filter operator">> is a predefined name attached to an individual step in a [[filter|Filters]]. It defines the particular action of that step.
+\define .operator-rows(filter)
+<$list filter="$filter$"><tr>
+<td><$link to={{!!title}}>{{!!caption}}</$link></td>
+<td>{{!!purpose}} <$list filter="[all[current]tag[Common Operators]]">{{$:/core/images/done-button}}</$list></td>
+<td align="center"><$list filter="[all[current]tag[Negatable Operators]]">`!`</$list></td>
+</tr></$list>
+\end
 
-<table class>
+\define .group-heading(_)
+<tr class="doc-table-subheading"><th colspan="3" align="center">$_$</th></tr>
+\end
+
+A <<.def "filter operator">> is a predefined keyword attached to an individual [[step|Filter Step]] of a [[filter|Filters]]. It defines the particular action of that step.
+
+The following table lists all the core operators. The commonest ones are checkmarked. The third column indicates which operators allow <$link to="Filter Step">the <code>!</code> prefix</$link> to reverse their meaning.
+
+<table>
 <tr>
 <th align="left">Operator</th>
 <th align="left">Purpose</th>
-<th align="left">Common</th>
+<th align="left">Neg</th>
 </tr>
-<$list filter="[tag[Filter Operators]sort[]]"><tr>
-<td><$link to={{!!title}}>{{!!caption}}</$link></td>
-<td>{{!!purpose}}</td>
-<td><$list filter="[all[current]tag[Common Operators]]">{{$:/core/images/done-button}}</$list></td>
-</tr></$list>
+<<.operator-rows "[tag[Filter Operators]!tag[Order Operators]!tag[String Operators]!tag[Tag Operators]!tag[Special Operators]sort[]]">>
+<<.group-heading "Order Operators">>
+<<.operator-rows "[tag[Filter Operators]tag[Order Operators]!tag[String Operators]!tag[Tag Operators]!tag[Special Operators]sort[]]">>
+<<.group-heading "String Operators">>
+<<.operator-rows "[tag[Filter Operators]!tag[Order Operators]tag[String Operators]!tag[Tag Operators]!tag[Special Operators]sort[]]">>
+<<.group-heading "Tag Operators">>
+<<.operator-rows "[tag[Filter Operators]!tag[Order Operators]!tag[String Operators]tag[Tag Operators]!tag[Special Operators]sort[]]">>
+<<.group-heading "Special Operators">>
+<<.operator-rows "[tag[Filter Operators]!tag[Order Operators]!tag[String Operators]!tag[Tag Operators]tag[Special Operators]sort[]]">>
 </table>
 
-A typical step is written as `[operator[parameter]]`, although not all of the operators need a [[parameter|Filter Parameters]].
+A typical step is written as `[operator[parameter]]`, although not all of the operators need a [[parameter|Filter Parameter]].
 
-Most steps accept a [[selection|Selection]] of tiddler titles as their input. For the exact rules, see [[Filter Syntax]].
+Most steps process the [[selection of titles|Title Selection]] that are supplied as their input, but a few are [[absolute|Absolute Operators]]. For the exact rules, see [[Filter Syntax]].

editions/tw5.com/tiddlers/filters/FilterSyntax.tid

@@ -1,87 +0,0 @@
-created: 20140210141217955
-modified: 20150119191956000
-tags: Filters
-title: Filter Syntax
-type: text/vnd.tiddlywiki
-
-<<.preamble """[[Filters]] follow a grammar that is presented here, using [[RailroadDiagrams]], for those who find formal syntax descriptions helpful. However, you can [[learn to write filters|Introduction to filter notation]] without needing to understand this tiddler.""">>
-
-A <<.def filter>> is a pipeline for transforming an <<.def input>> into an <<.def output>>. Both the input and the output are [[ordered sets|Title Selections]] of tiddler titles or similar strings.
-
-Filters are built from smaller pieces, called ''runs'' and ''steps'', each of which also transforms an input to an output.
-
----
-
-;filter
-: <$railroad text="""
-[{: [:whitespace] ("+"|:-|"-") run }]
-"""/>
-
-A filter starts with an empty output. Its runs are processed from left to right, progressively modifying the output.
-
-A run's input is normally a list of all the non-shadow tiddler titles in the wiki (in no particular order). But the `+` prefix can change this.
-
-* If a run has no `+` or `-` prefix, its output titles are [[dominantly appended|Dominant Append]] to the filter's output.
-* If a run has a `-` prefix, its output titles are <<.em removed>> from the filter's output (if they were present).
-* If a run has a `+` prefix, it receives the filter's output so far as its input. The filter's output is then completely <<.em replaced>> by the run's output. Any subsequent run reverts to receiving all tiddler titles as its input, unless it too has a `+` prefix.
-
-In concise technical terms:
-
-|!Run |!Interpretation |!Output |
-|`run` |union of sets |... OR run |
-|`+run` |intersection of sets |... AND run |
-|`-run` |difference of sets |... AND NOT run |
-
----
-
-;run
-: <$railroad text="""
-( "[" {step} "]"
-  |
-  [:{/"anything but [ ] or whitespace"/}]
-  |
-  '"' [:{/'anything but "'/}] '"'
-  |
-  "'" [:{/"anything but '"/}] '"'
-)
-"""/>
-
-The steps of a run are processed from left to right. The input to the first step is same as the input to the run. For each subsequent step, the input is the output of the previous step.
-
-{{Absolute Operators}}
-
-The lower three options in the diagram match `HelloThere`, `"HelloThere"` and `'HelloThere'`, and are short for `[title[HelloThere]]`. The two quoted options exist to support titles that contain square brackets: `"An [[[[Unusual]]]] Tiddler"`.
-
----
-
-;step
-: <$railroad text="""
-[:"!"] [:operator [:":" suffix] ] parameter
-"""/>
-
-The <<.def operator>> is drawn from a list of [[predefined names|Filter Operators]], which can be extended by plugins. Any unrecognised operator is treated as if it was the suffix to the <<.olink field>> operator. If a step's operator is omitted altogether, it defaults to `title`.
-
-The <<.def suffix>> is additional text, usually the name of a [[field|TiddlerFields]], that extends the meaning of certain operators.
-
----
-
-;parameter
-: <$railroad text="""
-( "[" [:{/"anything but ]"/}] "]"
-  |
-  "{" [:{/"anything but }"/}] "}"
-  |
-  "<" [:{/"anything but >"/}] ">"
-)
-"""/>
-
-* `[`...`]` encloses a direct parameter
-* `{`...`}` encloses a transcluded parameter
-* `<`...`>` encloses a [[variable|Variables]] parameter
-
----
-
-;whitespace
-: <$railroad text="""
-{( "space" | "tab" | "linefeed" | "return" | "vertical tab" | "formfeed" )}
-"""/>

editions/tw5.com/tiddlers/filters/Introduction to Filters.tid

@@ -1,10 +1,12 @@
 created: 20140410101941871
-modified: 20150117180519000
+modified: 20150124183957000
 tags: Learning Filters
 title: Introduction to filter notation
 type: text/vnd.tiddlywiki
 
-<<.preamble """This explains the basics of writing a [[filter|Filters]] to select a set of tiddlers. For a more technical summary, see [[Filter Syntax]].)""">>
+<<.preamble """This explains the basics of writing a [[filter|Filters]] to select a set of tiddlers. For a more technical presentation, see [[Filter Syntax]].""">>
+
+<$macrocall $name=".note" _="""Filters do nothing if you just type them into a tiddler on their own. They need a context. An easy way to experiment with filters is to type them into the <<.advancedsearch-tab Filter>> tab of [[Advanced Search|$:/AdvancedSearch]]."""/>
 
 The simplest case is where you already know exactly which tiddlers you want. Type each title in double square brackets, with a space between each one and the next:
 

editions/tw5.com/tiddlers/filters/addprefix.tid

@@ -1,5 +1,5 @@
 created: 20140410103123179
-modified: 20150119192731000
+modified: 20150124172110000
 tags: [[Filter Operators]] [[String Operators]]
 title: addprefix Operator
 type: text/vnd.tiddlywiki
@@ -7,10 +7,10 @@ caption: addprefix
 purpose: extend each input title with a prefix
 
 <$macrocall $name=".operator-def"
-input="a [[title selection|Title Selections]]"
-parameter="a prefix to be added"
-paramName="p"
-output="a copy of the input, but with <<.place p>> added to the start of each title"
+input="a [[selection of titles|Title Selection]]"
+parameter="a string of characters"
+paramName="s"
+output="the input, but with <<.place s>> added to the start of each title"
 />
 
 <<.operator-examples "addprefix">>

editions/tw5.com/tiddlers/filters/addsuffix.tid

@@ -1,5 +1,5 @@
 created: 20140828133830424
-modified: 20150119192734000
+modified: 20150124172115000
 tags: [[Filter Operators]] [[String Operators]]
 title: addsuffix Operator
 type: text/vnd.tiddlywiki
@@ -7,10 +7,10 @@ caption: addsuffix
 purpose: extend each input title with a suffix
 
 <$macrocall $name=".operator-def"
-input="a [[title selection|Title Selections]]"
-parameter="a suffix to be added"
-paramName="p"
-output="a copy of the input, but with <<.place p>> added to the end of each title"
+input="a [[selection of titles|Title Selection]]"
+parameter="a string of characters"
+paramName="s"
+output="the input, but with <<.place s>> added to the end of each title"
 />
 
 <<.operator-examples "addsuffix">>

editions/tw5.com/tiddlers/filters/after.tid

@@ -1,18 +1,18 @@
 created: 20140512103123179
-modified: 20150119192331000
-tags: [[Filter Operators]] [[List Operators]]
+modified: 20150124204353000
+tags: [[Filter Operators]] [[Order Operators]]
 title: after Operator
 type: text/vnd.tiddlywiki
 caption: after
-purpose: get the title that follows a particular one in the input
+purpose: find which input title follows a specified one
 
 <$macrocall $name=".operator-def"
-input="a [[title selection|Title Selections]]"
+input="a [[selection of titles|Title Selection]]"
 parameter="one of those titles"
-paramName="p"
-output="the title that immediately follows <<.place p>> in the input"
+paramName="t"
+output="the title that immediately follows <<.place t>> in the input"
 />
 
-If <<.place p>> is not present in the input, or is the last item there, then the output is empty.
+If <<.place t>> is not present in the input, or is the last title there, then the output is empty.
 
 <<.operator-examples "after">>

editions/tw5.com/tiddlers/filters/all.tid

@@ -1,19 +1,18 @@
 created: 20140410103123179
-modified: 20150119191633000
-tags: [[Filter Operators]] [[Common Operators]] [[Absolute Operators]] [[Category Operators]]
+modified: 20150124200847000
+tags: [[Filter Operators]] [[Common Operators]] [[Absolute Operators]]
 title: all Operator
 type: text/vnd.tiddlywiki
 caption: all
-purpose: get all tiddlers of a basic category
+purpose: find all titles of a fundamental category
 
 <$macrocall $name=".operator-def"
-input="ignored, unless <<.place p>> is empty"
-parameter="see below"
-paramName="p"
-output="the complete [[selection|Title Selections]] of tiddler titles that belong to one or more basic categories"
+input="ignored, unless the parameter is empty"
+parameter="zero or more categories -- see below"
+output="the titles that belong to all the specified categories"
 />
 
-The parameter specifies tiddler categories using the following syntax:
+The parameter specifies zero or more fundamental categories using the following syntax:
 
 <$railroad text="""
 [{: ("current" | "missing" |: "orphans" | "shadows" | "tiddlers" ) +"+" }]
@@ -21,15 +20,15 @@ The parameter specifies tiddler categories using the following syntax:
 
 |!Category |!Members |!Sorted |
 |^`current` |just the [[current tiddler|CurrentTiddler]] |^-- |
-|^`missing` |all non-existent tiddlers to which there is at least one [[observable link|Observable Links]] |^no |
-|^`orphans` |all tiddlers to which there are <<.em no>> observable links |^by title |
+|^`missing` |all non-existent tiddlers to which there is at least one [[hard link|Hard and Soft Links]] |^no |
+|^`orphans` |all tiddlers to which there are <<.em no>> hard links |^by title |
 |^`shadows` |all the [[shadow tiddlers|ShadowTiddlers]] that exist, including any that have been overridden with non-shadow tiddlers |^no |
 |^`tiddlers` |all the non-shadow tiddlers that exist |no |
 
 If the parameter specifies more than one category, they are processed from left to right. The overall output is initially empty, and each category's output is [[dominantly appended|Dominant Append]] to it in turn. Unrecognised categories contribute nothing to the output.
 
-As a special case, if there is no parameter, the output is simply a copy of the input. This can be useful when the parameter is [[supplied indirectly|Filter Parameters]].
+As a special case, if the parameter is empty, the output is simply a copy of the input. This can be useful when the parameter is [[soft|Filter Parameter]].
 
-The <<.op is>> operator is similar, but its scope is restricted to its input tiddlers.
+The <<.olink is>> operator is similar, but its scope is restricted to its input.
 
 <<.operator-examples "all">>

editions/tw5.com/tiddlers/filters/backlinks.tid

@@ -1,17 +1,17 @@
 created: 20140410103123179
-modified: 20150119192416000
-tags: [[Filter Operators]] [[Link Operators]]
+modified: 20150124200946000
+tags: [[Filter Operators]]
 title: backlinks Operator
 type: text/vnd.tiddlywiki
 caption: backlinks
-purpose: get the tiddlers that link to each input tiddler
+purpose: find the titles that link to each input title
 
 <$macrocall $name=".operator-def"
-input="a [[title selection|Title Selections]]"
+input="a [[selection of titles|Title Selection]]"
 parameter="none"
-output="the titles of any non-system tiddlers that contain [[Observable Links]] to the input tiddlers"
+output="any non-[[system|SystemTiddlers]] titles that contain [[hard links|Hard and Soft Links]] to the input titles"
 />
 
-Each input tiddler is processed in turn. Its corresponding list of backlinks is generated, sorted by title, and then [[dominantly appended|Dominant Append]] to the operator's overall output.
+Each input title is processed in turn. The corresponding tiddler's list of backlinks is generated, sorted alphabetically by title, and then [[dominantly appended|Dominant Append]] to the operator's overall output.
 
 <<.operator-examples "backlinks">>

editions/tw5.com/tiddlers/filters/before.tid

@@ -1,18 +1,18 @@
 created: 20140512103123179
-modified: 20150119192411000
-tags: [[Filter Operators]] [[List Operators]]
+modified: 20150124164952000
+tags: [[Filter Operators]] [[Order Operators]]
 caption: before
 title: before Operator
 type: text/vnd.tiddlywiki
-purpose: get the title that precedes a particular one in the input
+purpose: find which input title precedes a specified one
 
 <$macrocall $name=".operator-def"
-input="a [[title selection|Title Selections]]"
+input="a [[selection of titles|Title Selection]]"
 parameter="one of those titles"
-paramName="p"
-output="the title that immediately precedes <<.place p>> in the input"
+paramName="t"
+output="the title that immediately precedes <<.place t>> in the input"
 />
 
-If <<.place p>> is not present in the input, or is the first title there, then the output is empty.
+If <<.place t>> is not present in the input, or is the first title there, then the output is empty.
 
 <<.operator-examples "before">>

editions/tw5.com/tiddlers/filters/bf.tid

@@ -1,6 +1,6 @@
 created: 20140410103123179
-modified: 20150118182927000
-tags: [[Filter Operators]] [[List Operators]]
+modified: 20150124200504000
+tags: [[Filter Operators]] [[Order Operators]]
 title: bf Operator
 type: text/vnd.tiddlywiki
 caption: bf

editions/tw5.com/tiddlers/filters/butfirst.tid

@@ -1,6 +1,6 @@
 created: 20140410103123179
-modified: 20150118183016000
-tags: [[Filter Operators]] [[Sequence Operators]]
+modified: 20150124200507000
+tags: [[Filter Operators]] [[Order Operators]]
 title: butfirst Operator
 type: text/vnd.tiddlywiki
 caption: butfirst

editions/tw5.com/tiddlers/filters/butlast.tid

@@ -1,16 +1,16 @@
 created: 20140410103123179
-modified: 20150119192424000
-tags: [[Filter Operators]] [[Sequence Operators]]
+modified: 20150124172210000
+tags: [[Filter Operators]] [[Order Operators]]
 title: butlast Operator
 type: text/vnd.tiddlywiki
 caption: butlast
-purpose: get all the but last <<.place n>> input titles
+purpose: discard the last <<.place n>> input titles
 
 <$macrocall $name=".operator-def"
-input="a [[title selection|Title Selections]]"
+input="a [[selection of titles|Title Selection]]"
 parameter="an integer, defaulting to 1"
 paramName="n"
-output="all but the last <<.place n>> titles from the input"
+output="all but the last <<.place n>> input titles"
 />
 
 <<.operator-examples "butlast">>

editions/tw5.com/tiddlers/filters/commands.tid

@@ -1,16 +1,15 @@
 created: 20140410103123179
-modified: 20150119191708000
-tags: [[Filter Operators]] [[Non-Tiddler Operators]] [[Absolute Operators]]
+modified: 20150124155303000
+tags: [[Filter Operators]] [[Special Operators]] [[Absolute Operators]]
 title: commands Operator
 type: text/vnd.tiddlywiki
 caption: commands
-purpose: get all the Node.js commands
+purpose: select the titles of all the Node.js commands
 
 <$macrocall $name=".operator-def"
 input="ignored"
 parameter="none"
-output="the [[selection|Title Selections]] of [[commands|Commands]] that can be given to [[TiddlyWiki on Node.js]]"
+output="the [[command words|Commands]] that can be given to [[TiddlyWiki on Node.js]]"
 />
 
 <<.operator-examples "commands">>
-

editions/tw5.com/tiddlers/filters/each.tid

@@ -1,18 +1,20 @@
 created: 20140410103123179
-modified: 20150119192427000
+modified: 20150124164957000
 tags: [[Filter Operators]] [[Group Operators]]
 title: each Operator
 type: text/vnd.tiddlywiki
 caption: each
-purpose: get one of each group of input tiddlers by field value
+purpose: select one of each group of input titles by field
 
 <$macrocall $name=".operator-def"
-input="a [[title selection|Title Selections]]"
+input="a [[selection of titles|Title Selection]]"
 parameter="the name of a [[field|TiddlerFields]]"
 paramName="f"
-output="a [[selection|Title Selections]] containing the first tiddler found with each distinct value for field <<.place f>>"
+output="a selection containing the first input title encountered for each distinct value of field <<.place f>>"
 />
 
-Each input tiddler is processed in turn. The value of field <<.place f>> in that tiddler is examined, and as long as the value has not been encountered before, the tiddler's title is appended to the output set.
+Each input title is processed in turn. The value of field <<.place f>> in the corresponding tiddler is examined, and as long as the value has not been encountered before, the title is appended to the output set.
+
+If a tiddler doesn't contain field <<.place f>>, or contains it but with an empty value, then it contributes nothing to the output.
 
 <<.operator-examples "each">>

editions/tw5.com/tiddlers/filters/eachday.tid

@@ -1,18 +1,20 @@
 created: 20140410103123179
-modified: 20150119192430000
-tags: [[Filter Operators]] [[Group Operators]]
+modified: 20150124164959000
+tags: [[Filter Operators]] [[Group Operators]] [[Date Operators]]
 title: eachday Operator
 type: text/vnd.tiddlywiki
 caption: eachday
-purpose: get one of each group of input tiddlers by date
+purpose: select one of each group of input titles by date
 
 <$macrocall $name=".operator-def"
-input="a [[selection|Title Selections]] of tiddler titles"
-parameter="the name of a [[date field|DateFields]]"
+input="a [[selection of titles|Title Selection]]"
+parameter="the name of a date [[field|TiddlerFields]]"
 paramName="f"
-output="a [[selection|Title Selections]] containing the first tiddler found with each distinct value (ignoring times of day) for field <<.place f>>"
+output="a selection containing the first input title encountered for each distinct value (ignoring times of day) of field <<.place f>>"
 />
 
-Each input tiddler is processed in turn. The value of field <<.place f>> in that tiddler is examined, and as long as this indicates a date that has not been encountered before, the tiddler's title is appended to the output set.
+Each input title is processed in turn. The value of field <<.place f>> in the corresponding tiddler is examined, and as long as this indicates a date that has not been encountered before, the title is appended to the output set.
+
+If a tiddler doesn't contain field <<.place f>>, it contributes nothing to the output.
 
 <<.operator-examples "eachday">>

editions/tw5.com/tiddlers/filters/editiondescription.tid

@@ -1,13 +1,13 @@
 created: 20150111145738451
-modified: 20150119192433000
-tags: [[Filter Operators]] [[Non-Tiddler Operators]] [[Node.js Operators]]
+modified: 20150124165002000
+tags: [[Filter Operators]] [[Special Operators]]
 title: editiondescription Operator
 type: text/vnd.tiddlywiki
 caption: editiondescription
-purpose: get the descriptions of the input ~TiddlyWiki editions
+purpose: select the descriptions of the input editions
 
 <$macrocall $name=".operator-def"
-input="a [[selection|Title Selections]] of edition names"
+input="a [[selection|Title Selection]] of edition names"
 parameter="none"
 output="the description string of each edition in the input"
 />

editions/tw5.com/tiddlers/filters/editions.tid

@@ -1,13 +1,13 @@
 created: 20150111145738451
-modified: 20150118183042000
-tags: [[Filter Operators]] [[Non-Tiddler Operators]] [[Node.js Operators]] [[Absolute Operators]]
+modified: 20150124150912000
+tags: [[Filter Operators]] [[Special Operators]] [[Absolute Operators]]
 title: editions Operator
 type: text/vnd.tiddlywiki
 caption: editions
-purpose: get the names of all ~TiddlyWiki editions
+purpose: select the names of all the ~TiddlyWiki editions
 
 <$macrocall $name=".operator-def"
-input="none"
+input="ignored"
 parameter="none"
 output="the name of each ~TiddlyWiki edition, in alphabetical order"
 />

editions/tw5.com/tiddlers/filters/examples/get.tid

@@ -1,8 +1,9 @@
 created: 20150118134611000
-modified: 20150118183215000
+modified: 20150124201839000
 tags: [[get Operator]] [[Operator Examples]]
 title: get Operator (Examples)
 type: text/vnd.tiddlywiki
 
 <<.operator-example 1 "[all[current]get[draft.of]]" "the title of the tiddler of which the current tiddler is a draft">>
 <<.operator-example 2 "[get[tags]]">>
+<<.operator-example 3 "[each[tags]get[tags]]">>

editions/tw5.com/tiddlers/filters/examples/limit.tid

@@ -0,0 +1,8 @@
+created: 20150118134611000
+modified: 20150123214304000
+tags: [[limit Operator]] [[Operator Examples]]
+title: limit Operator (Examples)
+type: text/vnd.tiddlywiki
+
+<<.operator-example 1 "[sort[modified]!limit[20]]" "the 20 most recently modified tiddlers">>
+<<.operator-example 2 "[has[created]sort[created]limit[10]]" "the oldest 10 tiddlers in the wiki">>

editions/tw5.com/tiddlers/filters/examples/links.tid

@@ -0,0 +1,14 @@
+created: 20150118134611000
+modified: 20150124202748000
+tags: [[links Operator]] [[Operator Examples]]
+title: links Operator (Examples)
+type: text/vnd.tiddlywiki
+
+<<.operator-example 1 "[[HelloThere]links[]]">>
+<<.operator-example 2 "[all[current]links[]]" "tiddlers [[hard-linked|Hard and Soft Links]] from the current one">>
+
+Here are some hard links:
+
+* HelloThere
+* [[Filter Operators]]
+* [[links Operator]]

editions/tw5.com/tiddlers/filters/examples/list.tid

@@ -0,0 +1,10 @@
+created: 20150118134611000
+modified: 20150123214445000
+tags: [[list Operator]] [[Operator Examples]]
+title: list Operator (Examples)
+type: text/vnd.tiddlywiki
+
+<<.using-days-of-week>>
+
+<<.operator-example 1 "[list[HelloThere]]">>
+<<.operator-example 2 "[list[Days of the Week!!short]]">>

editions/tw5.com/tiddlers/filters/examples/listed.tid

@@ -0,0 +1,8 @@
+created: 20150118134611000
+modified: 20150123214616000
+tags: [[listed Operator]] [[Operator Examples]]
+title: listed Operator (Examples)
+type: text/vnd.tiddlywiki
+
+<<.operator-example 1 "[[HelloThere]listed[]]">>
+<<.operator-example 2 "[all[current]listed[my-special-list]]">>

editions/tw5.com/tiddlers/filters/examples/modules.tid

@@ -0,0 +1,7 @@
+created: 20150123221510000
+modified: 20150123221534000
+tags: [[modules Operator]] [[Operator Examples]]
+title: modules Operator (Examples)
+type: text/vnd.tiddlywiki
+
+<<.operator-example 1 "[[filteroperator]modules[]]">>

editions/tw5.com/tiddlers/filters/examples/moduletypes.tid

@@ -0,0 +1,7 @@
+created: 20150123221601000
+modified: 20150123221623000
+tags: [[moduletypes Operator]] [[Operator Examples]]
+title: moduletypes Operator (Examples)
+type: text/vnd.tiddlywiki
+
+<<.operator-example 1 "[moduletypes[]]">>

editions/tw5.com/tiddlers/filters/examples/next.tid

@@ -0,0 +1,11 @@
+created: 20150123221711000
+modified: 20150123221834000
+tags: [[next Operator]] [[Operator Examples]]
+title: next Operator (Examples)
+type: text/vnd.tiddlywiki
+
+<<.using-days-of-week>>
+
+<<.operator-example 1 "[[Monday]next[Days of the Week]]">>
+<<.operator-example 2 "[[Sunday]next[Days of the Week]]">>
+<<.operator-example 3 "Tuesday Wednesday Thursday +[next[Days of the Week]]">>

editions/tw5.com/tiddlers/filters/examples/nsort.tid

@@ -0,0 +1,8 @@
+created: 20150123221921000
+modified: 20150123222142000
+tags: [[nsort Operator]] [[Operator Examples]]
+title: nsort Operator (Examples)
+type: text/vnd.tiddlywiki
+
+<<.operator-example 1 "10 010 1000 100 +[nsort[]]">>
+<<.operator-example 2 "10 010 ALPHA beta alpha 1000 100 +[nsort[]]">>

editions/tw5.com/tiddlers/filters/examples/nsortcs.tid

@@ -0,0 +1,8 @@
+created: 20150123222108000
+modified: 20150123222139000
+tags: [[nsortcs Operator]] [[Operator Examples]]
+title: nsortcs Operator (Examples)
+type: text/vnd.tiddlywiki
+
+<<.operator-example 1 "10 010 1000 100 +[nsortcs[]]">>
+<<.operator-example 2 "10 010 ALPHA beta alpha 1000 100 +[nsortcs[]]">>

editions/tw5.com/tiddlers/filters/examples/nth.tid

@@ -0,0 +1,10 @@
+created: 20150118134611000
+modified: 20150123222912000
+tags: [[nth Operator]] [[Operator Examples]]
+title: nth Operator (Examples)
+type: text/vnd.tiddlywiki
+
+<<.using-days-of-week>>
+
+<<.operator-example 1 "[list[Days of the Week]nth[]]">>
+<<.operator-example 2 "[list[Days of the Week]nth[5]]">>

editions/tw5.com/tiddlers/filters/examples/plugintiddlers.tid

@@ -0,0 +1,8 @@
+created: 20150123223006000
+modified: 20150123223023000
+tags: [[plugintiddlers Operator]] [[Operator Examples]]
+title: plugintiddlers Operator (Examples)
+type: text/vnd.tiddlywiki
+
+<<.operator-example 1 "[[$:/core]plugintiddlers[]]">>
+

editions/tw5.com/tiddlers/filters/examples/prefix.tid

@@ -0,0 +1,9 @@
+created: 20150123223129000
+modified: 20150123223321000
+tags: [[prefix Operator]] [[Operator Examples]]
+title: prefix Operator (Examples)
+type: text/vnd.tiddlywiki
+
+<<.operator-example 1 "[tag[task]!prefix[Go]]">>
+<<.operator-example 2 "[prefix[$:/languages/]]">>
+<<.operator-example 3 "[prefix[$:/]]" "same as `[is[system]]`">>

editions/tw5.com/tiddlers/filters/examples/previous.tid

@@ -0,0 +1,11 @@
+created: 20150123221711000
+modified: 20150123223422000
+tags: [[previous Operator]] [[Operator Examples]]
+title: previous Operator (Examples)
+type: text/vnd.tiddlywiki
+
+<<.using-days-of-week>>
+
+<<.operator-example 1 "[[Wednesday]previous[Days of the Week]]">>
+<<.operator-example 2 "[[Monday]previous[Days of the Week]]">>
+<<.operator-example 3 "Tuesday Wednesday Thursday +[previous[Days of the Week]]">>

editions/tw5.com/tiddlers/filters/examples/regexp.tid

@@ -0,0 +1,21 @@
+created: 20150123221711000
+modified: 20150123225347000
+tags: [[regexp Operator]] [[Operator Examples]]
+title: regexp Operator (Examples)
+type: text/vnd.tiddlywiki
+
+<<.using-days-of-week>>
+
+<<.operator-example 1 "[!is[system]regexp[Wiki]]" "non-system tiddlers with `Wiki` in their title">>
+<<.operator-example 2 "[!is[system]regexp[(?i)Wiki]]" "non-system tiddlers with `Wiki` in their title, ignoring case">>
+<<.operator-example 3 "[!is[system]regexp[Wiki(?i)]]" "same again">>
+<<.operator-example 4 "[regexp[(?i)\.jpe?g$]]" "tiddlers with titles ending in `.jpg` or `.jpeg`, ignoring case">>
+<<.operator-example 5 "[regexp:created[^201408]]" "tiddlers created in August 2014">>
+
+The regular expression `[0-9]{2}` matches two consecutive digits. Because it contains square brackets, the way to use it with the <<.op regexp>> operator is via a [[variable|Variables]], as follows:
+
+<$macrocall
+$name="wikitext-example-without-html"
+src="""<$set name="digit-pattern" value="[0-9]{2}">
+<<list-links "[regexp:title<digit-pattern>]">>
+</$set>"""/>

editions/tw5.com/tiddlers/filters/examples/removeprefix.tid

@@ -0,0 +1,7 @@
+created: 20150118132851000
+modified: 20150123210429000
+tags: [[removeprefix Operator]] [[Operator Examples]]
+title: removeprefix Operator (Examples)
+type: text/vnd.tiddlywiki
+
+<<.operator-example 1 "[[My Cat]] [[Your Garden]] [[My Favourite Armchair]] +[removeprefix[My ]]">>

editions/tw5.com/tiddlers/filters/examples/removesuffix.tid

@@ -0,0 +1,9 @@
+created: 20150118132851000
+modified: 20150123211000000
+tags: [[removesuffix Operator]] [[Operator Examples]]
+title: removesuffix Operator (Examples)
+type: text/vnd.tiddlywiki
+
+<<.operator-example 1 "SIMPLEX Googolplex Complex +[removesuffix[plex]]">>
+
+

editions/tw5.com/tiddlers/filters/examples/rest.tid

@@ -0,0 +1,11 @@
+created: 20150118134611000
+modified: 20150123211722000
+tags: [[rest Operator]] [[Operator Examples]]
+title: rest Operator (Examples)
+type: text/vnd.tiddlywiki
+
+<<.using-days-of-week>>
+
+<<.operator-example 1 "[list[Days of the Week]rest[]]">>
+<<.operator-example 2 "[list[Days of the Week]rest[3]]">>
+<<.operator-example 3 "Z Y X W V U T S R Q P O +[rest[5]]">>

editions/tw5.com/tiddlers/filters/examples/reverse.tid

@@ -0,0 +1,9 @@
+created: 20150118134611000
+modified: 20150123212752000
+tags: [[reverse Operator]] [[Operator Examples]]
+title: reverse Operator (Examples)
+type: text/vnd.tiddlywiki
+
+<<.using-days-of-week>>
+
+<<.operator-example 1 "[list[Days of the Week]reverse[]]">>

editions/tw5.com/tiddlers/filters/examples/sameday.tid

@@ -0,0 +1,8 @@
+created: 20150124101702000
+modified: 20150124101739000
+tags: [[sameday Operator]] [[Operator Examples]]
+title: sameday Operator (Examples)
+type: text/vnd.tiddlywiki
+
+<<.operator-example 1 "[sameday[20140410]]" "tiddlers modified on 10 April 2014">>
+<<.operator-example 2 "[sameday:created[20140410]]" "tiddlers created on 10 April 2014">>

editions/tw5.com/tiddlers/filters/examples/search.tid

@@ -0,0 +1,10 @@
+created: 20150124104508000
+modified: 20150124110256000
+tags: [[search Operator]] [[Operator Examples]]
+title: search Operator (Examples)
+type: text/vnd.tiddlywiki
+
+<$macrocall $name=".operator-example" n="1" eg="[!is[system]search[table]]" ie="non-system tiddlers containing the word <<.word table>>"/>
+<$macrocall $name=".operator-example" n="2" eg="[all[shadows]search[table]]" ie="shadow tiddlers containing the word <<.word table>>"/>
+<$macrocall $name=".operator-example" n="3" eg="[search:caption[arch]]" ie="tiddlers containing `arch` in their <<.field caption>> field"/>
+

editions/tw5.com/tiddlers/filters/examples/shadowsource.tid

@@ -0,0 +1,8 @@
+created: 20150124111726000
+modified: 20150124210736000
+tags: [[shadowsource Operator]] [[Operator Examples]]
+title: shadowsource Operator (Examples)
+type: text/vnd.tiddlywiki
+
+<<.operator-example 1 "[[$:/core/copyright.txt]shadowsource[]]">>
+<<.operator-example 2 "$:/core/copyright.txt $:/plugins/tiddlywiki/railroad/parser.js +[shadowsource[]]">>

editions/tw5.com/tiddlers/filters/examples/sort.tid

@@ -0,0 +1,13 @@
+created: 20150124112340000
+modified: 20150124113250000
+tags: [[sort Operator]] [[Operator Examples]]
+title: sort Operator (Examples)
+type: text/vnd.tiddlywiki
+
+<<.using-days-of-week>>
+
+<<.operator-example 1 "[list[Days of the Week]sort[]]">>
+<<.operator-example 2 "[list[Days of the Week]!sort[]]">>
+<<.operator-example 3 "one two Three four +[sort[]]">>
+<<.operator-example 4 "[prefix[Tiddl]sort[text]]">>
+<<.operator-example 5 "[has[created]sort[created]limit[10]]" "the oldest 10 tiddlers in the wiki">>

editions/tw5.com/tiddlers/filters/examples/sortcs.tid

@@ -0,0 +1,10 @@
+created: 20150124113044000
+modified: 20150124113344000
+tags: [[sortcs Operator]] [[Operator Examples]]
+title: sortcs Operator (Examples)
+type: text/vnd.tiddlywiki
+
+<<.using-days-of-week>>
+
+<<.operator-example 1 "one two Three four +[sortcs[]]">>
+<<.operator-example 2 "one two Three four +[!sortcs[]]">>

editions/tw5.com/tiddlers/filters/examples/suffix.tid

@@ -0,0 +1,8 @@
+created: 20150124113652000
+modified: 20150124113925000
+tags: [[suffix Operator]] [[Operator Examples]]
+title: suffix Operator (Examples)
+type: text/vnd.tiddlywiki
+
+<<.operator-example 1 "[suffix[.jpg]]">>
+<<.operator-example 2 "[tag[task]!suffix[ing]]">>

editions/tw5.com/tiddlers/filters/examples/tag - Copy.tid

@@ -0,0 +1,9 @@
+created: 20150124142346000
+modified: 20150124142713000
+tags: [[untagged Operator]] [[Operator Examples]]
+title: untagged Operator (Examples)
+type: text/vnd.tiddlywiki
+
+<<.operator-example 1 "[untagged[]]">>
+<<.operator-example 2 "[all[shadows]untagged[]]">>
+<<.operator-example 3 "[list[HelloThere]!untagged[]]">>

editions/tw5.com/tiddlers/filters/examples/tag.tid

@@ -0,0 +1,10 @@
+created: 20150124122400000
+modified: 20150124122939000
+tags: [[tag Operator]] [[Operator Examples]]
+title: tag Operator (Examples)
+type: text/vnd.tiddlywiki
+
+<<.operator-example 1 "[tag[task]]">>
+<<.operator-example 2 "[tag[task]!tag[done]]">>
+<<.operator-example 3 "[!tag[task]]">>
+<<.operator-example 4 "[all[shadows]tag[$:/tags/Stylesheet]]">>

editions/tw5.com/tiddlers/filters/examples/tagging.tid

@@ -0,0 +1,9 @@
+created: 20150124133043000
+modified: 20150124133617000
+tags: [[tagging Operator]] [[Operator Examples]]
+title: tagging Operator (Examples)
+type: text/vnd.tiddlywiki
+
+<<.operator-example 1 "[[task]tagging[]]" "same as `[tag[task]]`">>
+<<.operator-example 2 "Concepts task +[tagging[]]">>
+<<.operator-example 3 "[all[current]tagging[]]" "tiddlers tagged with the current one">>

editions/tw5.com/tiddlers/filters/examples/tags.tid

@@ -0,0 +1,9 @@
+created: 20150124134009000
+modified: 20150124134203000
+tags: [[tags Operator]] [[Operator Examples]]
+title: tags Operator (Examples)
+type: text/vnd.tiddlywiki
+
+<<.operator-example 1 "[[Filter Operators]tags[]]">>
+<<.operator-example 2 "[all[shadows]tags[]]">>
+<<.operator-example 3 "[all[shadows+tiddlers]tags[]sort[]]">>

editions/tw5.com/tiddlers/filters/examples/title.tid

@@ -0,0 +1,15 @@
+created: 20150124140124000
+modified: 20150124140355000
+tags: [[title Operator]] [[Operator Examples]]
+title: title Operator (Examples)
+type: text/vnd.tiddlywiki
+
+<<.operator-example 1 "[title[HelloThere]]">>
+<<.operator-example 2 "[[HelloThere]]">>
+<<.operator-example 3 "HelloThere">>
+<<.operator-example 4 "[title[HelloThere]] [title[Filter Operators]]">>
+<<.operator-example 5 "[[HelloThere]] [[Filter Operators]]">>
+<<.operator-example 6 "HelloThere [[Filter Operators]]">>
+<<.operator-example 7 "[tag[Filters]] +[!title[Filter Operators]]">>
+<<.operator-example 8 "[tag[Filters]] +[![Filter Operators]]">>
+<<.operator-example 9 "[tag[Filters]] -[[Filter Operators]]">>

editions/tw5.com/tiddlers/filters/field.tid

@@ -1,28 +1,26 @@
 created: 20140410103123179
-modified: 20150119192437000
-tags: [[Filter Operators]] [[Common Operators]] [[Field Operators]]
+modified: 20150124201655000
+tags: [[Filter Operators]] [[Common Operators]] [[Field Operators]] [[Negatable Operators]]
 title: field Operator
 type: text/vnd.tiddlywiki
 caption: field
-purpose: filter the input tiddlers by field value
+purpose: filter the input by field
 
-<$macrocall $name=".operator-def-suffix"
-input="a [[title selection|Title Selections]]"
-suffix="the name of a field"
+<$macrocall $name=".operator-def"
+input="a [[selection of titles|Title Selection]]"
+suffix="the name of a [[field|TiddlerFields]]"
 suffixName="f"
-parameter="a potential value for field <<.place f>>"
-paramName="p"
-output="the [[subselection|Title Selections]] of the input tiddlers in which field <<.place f>> has the value <<.place p>>"
+parameter="a possible value of field <<.place f>>"
+paramName="s"
+output="those input tiddlers in which field <<.place f>> has the value <<.place s>>"
+negationOutput="those input tiddlers in which field <<.place f>> does <<.em not>> have the value <<.place s>>"
 />
 
-If <<.place p>> is empty, <<.op field>> will match both of the following:
+If <<.place s>> is empty, <<.op field>> will match both of the following:
 
 * tiddlers that don't contain field <<.place f>>
 * tiddlers in which field <<.place f>> exists but has an empty value
 
-;Negation
-: `!field` outputs the subselection of the input tiddlers in which field <<.place f>> does <<.em not>> have the value <<.place p>>.
-
-The [[Filter Syntax]] treats any unrecognised [[filter operator|Filter Operators]] as if it was the suffix to the <<.olink field>> operator. See the second example below.
+The syntax of a [[filter step|Filter Step]] treats any unrecognised [[filter operator|Filter Operators]] as if it was the suffix to the <<.op field>> operator. See the <<.operator-examples "field" "examples">>.
 
 <<.operator-examples "field">>

editions/tw5.com/tiddlers/filters/fields.tid

@@ -1,15 +1,15 @@
 created: 20140924115616653
-modified: 20150119192440000
+modified: 20150124184835000
 tags: [[Filter Operators]] [[Field Operators]]
 title: fields Operator
 type: text/vnd.tiddlywiki
 caption: fields
-purpose: get all fields of the input tiddlers
+purpose: select all field names of the input titles
 
 <$macrocall $name=".operator-def"
-input="a [[selection|Title Selections]] of tiddler titles"
+input="a [[selection of titles|Title Selection]]"
 parameter="none"
-output="the [[selection|Title Selections]] of all field names contained in the input tiddlers"
+output="all the field names contained in the input tiddlers"
 />
 
 Each input title is processed in turn. Its list of field names is retrieved (in no particular order) and then [[dominantly appended|Dominant Append]] to the operator's output.

editions/tw5.com/tiddlers/filters/first.tid

@@ -1,16 +1,16 @@
 created: 20140410103123179
-modified: 20150119192443000
-tags: [[Filter Operators]] [[List Operators]]
+modified: 20150124161800000
+tags: [[Filter Operators]] [[Order Operators]]
 title: first Operator
 type: text/vnd.tiddlywiki
 caption: first
-purpose: get the first <<.place n>> input titles
+purpose: select the first <<.place n>> input titles
 
 <$macrocall $name=".operator-def"
-input="a [[selection|Title Selections]] of titles"
+input="a [[selection of titles|Title Selection]]"
 parameter="an integer, defaulting to 1"
 paramName="n"
-output="the first <<.place n>> titles from the input"
+output="the first <<.place n>> input titles"
 />
 
 <<.operator-examples "first">>

editions/tw5.com/tiddlers/filters/get.tid

@@ -1,20 +1,20 @@
 created: 20140426183123179
-modified: 20150119192446000
+modified: 20150124165013000
 tags: [[Filter Operators]] [[Field Operators]]
 title: get Operator
 type: text/vnd.tiddlywiki
 caption: get
-purpose: get the values of a field from all input tiddlers
+purpose: select all values of a field in the input titles
 
 <$macrocall $name=".operator-def"
-input="a [[selection|Title Selections]] of tiddler titles"
+input="a [[selection of titles|Title Selection]]"
 parameter="the name of a [[field|TiddlerFields]]"
 paramName="f"
-output="the values of field <<.place f>> in each of the input tiddlers"
+output="the values of field <<.place f>> in each of the input titles"
 />
 
-Each input tiddler is processed in turn. If the tiddler contains field <<.place f>>, and the value of this field is not empty, then its value is appended to the output.
+Each input title is processed in turn. If the corresponding tiddler contains field <<.place f>>, and the value of this field is not empty, then its value is appended to the output.
 
-Unlike most other [[Filter Operators]], the output of <<.op get>> can contain duplicates.
+Unlike most other [[Filter Operators]], the [[selection|Title Selection]] output by <<.op get>> can contain duplicates. To avoid duplicates, use `each[f]get[f]`.
 
 <<.operator-examples "get">>

editions/tw5.com/tiddlers/filters/has.tid

@@ -1,25 +1,18 @@
 created: 20140410103123179
-modified: 20150119192449000
-tags: [[Filter Operators]] [[Common Operators]] [[Field Operators]]
+modified: 20150124191952000
+tags: [[Filter Operators]] [[Common Operators]] [[Field Operators]] [[Negatable Operators]]
 title: has Operator
 type: text/vnd.tiddlywiki
 caption: has
-purpose: filter the input tiddlers by field existence
+purpose: filter the input by field existence
 
 <$macrocall $name=".operator-def"
 syntax="has[f]"
-input="a [[selection|Title Selections]] of tiddler titles"
-parameter="the name of a field"
+input="a [[selection of titles|Title Selection]]"
+parameter="the name of a [[field|TiddlerFields]]"
 paramName="f"
-output="the [[subselection|Title Selections]] of the input tiddlers that have a value in field <<.place f>>"
+output="those input tiddlers in which field <<.place f>> has a non-empty value"
+negationOutput="those input tiddlers in which field <<.place f>> does <<.em not>> exist or has an empty value"
 />
 
-<<.op has>> filters out both of the following:
-
-* tiddlers that don't contain field <<.place f>>
-* tiddlers in which field <<.place f>> exists but has an empty value
-
-;Negation
-: `!has` outputs the subset of the input tiddlers in which field <<.place f>> does <<.em not>> exist or does not have the value <<.place p>>.
-
 <<.operator-examples "has">>

editions/tw5.com/tiddlers/filters/indexes.tid

@@ -1,19 +1,19 @@
 created: 20140410103123179
-modified: 20150119192453000
+modified: 20150124184840000
 tags: [[Filter Operators]]
 title: indexes Operator
 type: text/vnd.tiddlywiki
 caption: indexes
-purpose: get all properties of the input data tiddlers
+purpose: select all data properties of the input titles
 
 <$macrocall $name=".operator-def"
-input="a [[selection|Title Selections]] of tiddler titles"
+input="a [[selection of titles|Title Selection]]"
 parameter="none"
-output="the [[selection|Title Selections]] of all property names contained in the input data tiddlers"
+output="all the property names or indices contained in the input data tiddlers"
 />
 
 Each input title is processed in turn, and is ignored if it does not denote a [[data tiddler|DataTiddlers]]. The list of property names is retrieved from the data tiddler (in no particular order) and then [[dominantly appended|Dominant Append]] to the operator's output.
 
-Where a tiddler's [[content is JSON|JSONTiddlers]] with an array as its root, the <<.op indexes>> operator retrieves a selection of integer indexes instead.
+Where a tiddler's [[content is JSON|JSONTiddlers]] with an array as its root, the <<.op indexes>> operator retrieves a selection of integer indices instead.
 
 <<.operator-examples "indexes">>

editions/tw5.com/tiddlers/filters/is.tid

@@ -1,37 +1,37 @@
 created: 20140410103123179
-modified: 20150119192457000
-tags: [[Filter Operators]] [[Common Operators]] [[Category Operators]]
+modified: 20150124202225000
+tags: [[Filter Operators]] [[Common Operators]] [[Negatable Operators]]
 title: is Operator
 type: text/vnd.tiddlywiki
 caption: is
-purpose: filter the input tiddlers by basic category
+purpose: filter the input by fundamental category
 
 <$macrocall $name=".operator-def"
-input="a [[selection|Title Selections]] of titles"
-parameter="see below"
-paramName="p"
-output="the [[subselection|Title Selections]] of the input tiddlers that belong to the specified basic category"
+input="a [[selection of titles|Title Selection]]"
+parameter="a category -- see below"
+paramName="c"
+output="those input tiddlers that belong to category <<.place c>>"
+negationOutput="those input tiddlers that do <<.em not>> belong to category <<.place c>>"
 />
 
-The parameter is one of the following categories:
+The parameter <<.place c>> is one of the following fundamental categories:
 
 |!Category |!Matches any tiddler that... |
-|^`current`|is the [[current tiddler|CurrentTiddler]] |
-|^`image`|has an image ContentType |
+|^`current` |is the [[current tiddler|CurrentTiddler]] |
+|^`image` |has an image ContentType |
 |^`missing` |does not exist (other than possibly as a non-shadow tiddler), regardless of whether there are any links it |
-|^`orphan` |has no [[Observable Links]] to it |
+|^`orphan` |has no [[hard links|Hard and Soft Links]] to it |
 |^`shadow` |is a [[shadow tiddler|ShadowTiddlers]], regardless of whether it has been overridden with a non-shadow tiddler |
 |^`system` |is a [[system tiddler|SystemTiddlers]], i.e. its title starts with `$:/` |
 |^`tag` |is in use as a tag |
 |^`tiddler` |exists as a non-shadow tiddler |
 
-;Negation
-: `!is` outputs the subselection of the input tiddlers that are <<.em not>> in the specified category. `!is[tiddler]` is a synonym for `is[missing]`, and vice versa.
+If <<.place c>> is anything else, the output is an error message.
 
-An unrecognised category outputs an error string.
+`!is[tiddler]` is a synonym for `is[missing]`, and vice versa.
 
-When <<.op is[missing]>> is the first operator in a [[run|Filter Syntax]], its output is always empty. And when <<.op is[shadow]>> comes first, it outputs only those shadow tiddlers that have been overridden. This is because the [[initial input to a run|Filter Syntax]] contains only <<.em non>>-shadow tiddlers.
+When <<.op is[missing]>> is the first operator in a [[run|Filter Run]], its output is always empty. And when <<.op is[shadow]>> comes first, it outputs only those shadow tiddlers that have been overridden. This is because the [[initial input to a run|Filter Expression]] contains only <<.em non>>-shadow tiddlers.
 
-The <<.op all>> operator is similar, but its scope is the whole wiki.
+The <<.olink all>> operator is similar, but its scope is the whole wiki.
 
 <<.operator-examples "is">>

editions/tw5.com/tiddlers/filters/last.tid

@@ -1,16 +1,16 @@
 created: 20140410103123179
-modified: 20150119192502000
-tags: [[Filter Operators]] [[List Operators]]
+modified: 20150124204508000
+tags: [[Filter Operators]] [[Order Operators]]
 title: last Operator
 type: text/vnd.tiddlywiki
 caption: last
-purpose: get the last <<.place n>> input titles
+purpose: select the last <<.place n>> input titles
 
 <$macrocall $name=".operator-def"
-input="a [[selection|Title Selections]] of titles"
+input="a [[selection of titles|Title Selection]]"
 parameter="an integer, defaulting to 1"
 paramName="n"
-output="the last <<.place n>> titles from the input"
+output="the last <<.place n>> input titles"
 />
 
 <<.operator-examples "last">>

editions/tw5.com/tiddlers/filters/limit.tid

@@ -1,15 +1,19 @@
 created: 20140410103123179
-modified: 20140410103123179
-tags: Filters CommonFilters
-caption: limit
-title: FilterOperator: limit
+modified: 20150124204544000
+tags: [[Filter Operators]] [[Common Operators]] [[Order Operators]] [[Negatable Operators]]
+title: limit Operator
 type: text/vnd.tiddlywiki
+caption: limit
+purpose: select the first or last <<.place n>> input titles
 
-The ''limit'' filter operator trims the current list to the length specified in the operator. Usually the first tiddlers in the list are returned; preceding the operator with ''!'' causes it to instead return the last tiddlers in the list.
+<$macrocall $name=".operator-def"
+input="a [[selection of titles|Title Selection]]"
+parameter="an integer, defaulting to 0"
+paramName="n"
+output="the first <<.place n>> input titles"
+negationOutput="the last <<.place n>> input titles"
+/>
 
-For example:
-
-|!Filter String |!Description |
-|`[sort[modified]!limit[20]]` |Returns the titles of the last 20 tiddlers to have been modified |
-|`[has[created]sort[created]limit[10]]` |Returns the titles of the oldest 10 tiddlers to have been created |
+`limit[n]` and `!limit[n]` are synonyms for `first[n]` and `last[n]` respectively.
 
+<<.operator-examples "limit">>

editions/tw5.com/tiddlers/filters/links.tid

@@ -1,14 +1,17 @@
 created: 20140410103123179
-modified: 20140410103123179
-tags: Filters CommonFilters
-caption: links
-title: FilterOperator: links
+modified: 20150124184844000
+tags: [[Filter Operators]] [[Common Operators]]
+title: links Operator
 type: text/vnd.tiddlywiki
+caption: links
+purpose: find the titles linked to by each input title
 
-The ''links'' filter operator replaces the current list with a list of the targets of outgoing links from those tiddlers.
+<$macrocall $name=".operator-def"
+input="a [[selection of titles|Title Selection]]"
+parameter="none"
+output="the titles to which the input tiddlers contain [[hard links|Hard and Soft Links]]"
+/>
 
-For example:
+Each input title is processed in turn. The corresponding tiddler's list of links is generated, in the order in which they appear in the tiddler's text, and [[dominantly appended|Dominant Append]] to the operator's overall output.
 
-|!Filter String |!Description |
-|`[[HelloThere]links[]]` |Returns the titles of tiddlers linked from `HelloThere` |
-|`[all[current]links[]]` |Returns the titles of tiddlers linked from the current tiddler |
+<<.operator-examples "links">>

editions/tw5.com/tiddlers/filters/list.tid

@@ -1,16 +1,23 @@
 created: 20140410103123179
-modified: 20140410103123179
-tags: Filters
-caption: list
-title: FilterOperator: list
+modified: 20150124203324000
+tags: [[Filter Operators]] [[Field Operators]] [[Absolute Operators]] [[Negatable Operators]]
+title: list Operator
 type: text/vnd.tiddlywiki
+caption: list
+purpose: select titles via a list field
 
-The ''list'' filter operator replaces the current list with the list contained in the TextReference specified in the operand. The default field for the text reference is `list`.
+<$macrocall $name=".operator-def"
+input="ignored"
+negationInput="a [[selection of titles|Title Selection]]"
+parameter="a [[reference|TextReference]] to a [[field|TiddlerFields]] or [[property|DataTiddlers]] of a particular tiddler"
+paramName="r"
+output="the titles stored as a [[title list|Title List]] at <<.place r>>"
+negationOutput="those input titles that are <<.em not>> mentioned at <<.place r>>"
+/>
 
-Preceding the operator name with `!` inverts the logic so that the filter only returns the tiddlers in the current list that are not listed in the specified list.
+<<.place r>> can reference either a field or a property. See [[TextReference]] for the syntax.
 
-For example:
+* If neither is specified, the <<.field list>> field is used by default. So `[list[T]]` outputs the titles listed in the <<.field list>> of tiddler T.
+* If <<.place r>> consists of <<.em only>> a field or a property, the tiddler part of the reference defaults to the CurrentTiddler. So `[list[!!tags]]` outputs the titles listed in the <<.field tags>> field of the current tiddler.
 
-|!Filter String |!Description |
-|`[list[HelloThere]]` |Returns the list of tiddlers in the `list` field of the tiddler `HelloThere` |
-|`[list[HelloThere!!mylist]]` |Returns the list of tiddlers in the `mylist` field of the tiddler `HelloThere` |
+<<.operator-examples "list">>

editions/tw5.com/tiddlers/filters/listed.tid

@@ -1,14 +1,20 @@
 created: 20140410103123179
-modified: 20140613103123179
-tags: Filters
-caption: listed
-title: FilterOperator: listed
+modified: 20150124203638000
+tags: [[Filter Operators]] [[Field Operators]]
+title: listed Operator
 type: text/vnd.tiddlywiki
+caption: listed
+purpose: find the titles that list the input titles
 
-The ''listed'' filter operator returns the titles of the tiddlers that have `list` fields that contain any members of the current list. The optional operand can be used to specify a different field.
+<$macrocall $name=".operator-def"
+input="a [[selection of titles|Title Selection]]"
+parameter="the name of a [[field|TiddlerFields]], defaulting to <<.field list>>"
+paramName="f"
+output="the titles in which field <<.place f>> mentions any of the input titles"
+/>
 
-For example:
+<<.field f>> is assumed to be a [[title list|Title List]].
 
-|!Filter String |!Description |
-|`[[HelloThere]listed[]]` |Returns the titles of any tiddlers containing `HelloThere` in their `list` fields |
-|`[all[current]listed[my-special-list]]` |Returns the titles of any tiddlers containing the current tiddler in their `my-special-list` fields |
+Each input title is processed in turn. A list of tiddlers whose <<.place f>> field mentions it is generated (in no particular order) and [[dominantly appended|Dominant Append]] to the operator's overall output.
+
+<<.operator-examples "listed">>

editions/tw5.com/tiddlers/filters/modules.tid

@@ -1,15 +1,15 @@
 created: 20140410103123179
-modified: 20150118182943000
-tags: Filters
-caption: modules
-title: FilterOperator: modules
+modified: 20150124170624000
+tags: [[Filter Operators]] [[Special Operators]]
+title: modules Operator
 type: text/vnd.tiddlywiki
+caption: modules
+purpose: select the names of all modules of the input module types
 
-The ''modules'' filter operator treats the current list as a list of [[module types|ModuleType]], and returns the titles of all of the modules of those types.
+<$macrocall $name=".operator-def"
+input="a [[selection|Title Selection]] of module types"
+parameter="none"
+output="the title of each module with any of the input types"
+/>
 
-For example:
-
-|!Filter String |!Description |
-|`[[filteroperator]modules[]]` |Returns a list of the modules of type `filteroperator` |
-
-See also [[FilterOperator: moduletypes]].
+<<.operator-examples "modules">>

editions/tw5.com/tiddlers/filters/moduletypes.tid

@@ -1,15 +1,15 @@
 created: 20140410103123179
-modified: 20140410103123179
-tags: Filters
-caption: moduletypes
-title: FilterOperator: moduletypes
+modified: 20150124170640000
+tags: [[Filter Operators]] [[Special Operators]] [[Absolute Operators]]
+title: moduletypes Operator
 type: text/vnd.tiddlywiki
+caption: moduletypes
+purpose: select the names of all ~TiddlyWiki module types
 
-The ''moduletypes'' filter operator replaces the current list with a list of the types of the currently loaded modules.
+<$macrocall $name=".operator-def"
+input="ignored"
+parameter="none"
+output="the name of each known ~TiddlyWiki [[module type|ModuleType]], in alphabetical order"
+/>
 
-For example:
-
-|!Filter String |!Description |
-|`[moduletypes[]]` |Returns a list of the types of the currently loaded modules |
-
-See also [[FilterOperator: modules]].
+<<.operator-examples "moduletypes">>

editions/tw5.com/tiddlers/filters/next.tid

@@ -1,21 +1,18 @@
 created: 20140410103123179
-modified: 20140410103123179
-tags: Filters
-caption: next
-title: FilterOperator: next
+modified: 20150124171754000
+tags: [[Filter Operators]] [[Field Operators]] [[Order Operators]]
+title: next Operator
 type: text/vnd.tiddlywiki
+caption: next
+purpose: find which titles in a <<.field list>> field follow the input ones
 
-The ''next'' filter operator takes each tiddler in the current list and looks it up in the `list` field of the tiddler specified in the operand, and then returns the immediately following tiddler title.
+<$macrocall $name=".operator-def"
+input="a [[selection of titles|Title Selection]]"
+parameter="a tiddler title"
+paramName="t"
+output="a selection containing each title that immediately follows each of the input titles in the <<.field list>> field of <<.place t>>"
+/>
 
-The following examples assume a tiddler called `MyList` with a `list` field containing:
+Each input title is processed in turn, and its successor is located in the <<.field list>> field and appended to the output. If a title is not listed in the field, or is the last title there, then it contributes nothing to the output.
 
-```
-one two three four five
-```
-
-|!Filter String |!Description |
-|`[[three]next[MyList]]` |Returns `four` |
-|`[[five]next[MyList]]` |Returns an empty list |
-|`one three +[next[MyList]]` |Returns `two`, `four` |
-
-See also [[FilterOperator: previous]].
+<<.operator-examples "next">>

editions/tw5.com/tiddlers/filters/nsort.tid

@@ -1,16 +1,19 @@
 created: 20140410103123179
-modified: 20140410103123179
-tags: Filters
-caption: nsort
-title: FilterOperator: nsort
+modified: 20150124205344000
+tags: [[Filter Operators]] [[Field Operators]] [[Order Operators]] [[Negatable Operators]]
+title: nsort Operator
 type: text/vnd.tiddlywiki
+caption: nsort
+purpose: sort the input by number field
 
-The ''nsort'' filter operator sorts the current list as numeric values, along the field specified in the operand (which defaults to `title`). String values are sorted case insensitively (upper and lower case letters are considered equivalent). Preceding the operator with `!` reverses the sort order.
+<$macrocall $name=".operator-def"
+input="a [[selection of titles|Title Selection]]"
+parameter="the name of a [[field|TiddlerFields]], defaulting to <<.field title>>"
+paramName="f"
+output="the input, sorted into ascending order by field <<.field f>>, treating field values as numbers"
+negationOutput="the input, likewise sorted into descending order"
+/>
 
-For example:
+Non-numeric values are treated as having a higher value than any number, and the difference between capital and lowercase letters is ignored. Compare <<.olink nsortcs>>.
 
-|!Filter String |!Description |
-|`10 010 1000 100 +[nsort[]]` |Returns `10`, `010`, `100`, `1000` |
-|`10 010 alpha 1000 100 +[nsort[]]` |Returns `10`, `010`, `100`, `1000`, `alpha` |
-
-See also [[FilterOperator: sort]], [[FilterOperator: sortcs]] and [[FilterOperator: nsortcs]].
+<<.operator-examples "nsort">>

editions/tw5.com/tiddlers/filters/nsortcs.tid

@@ -1,16 +1,19 @@
 created: 20140410103123179
-modified: 20140410103123179
-tags: Filters
-caption: nsortcs
-title: FilterOperator: nsortcs
+modified: 20150124205339000
+tags: [[Filter Operators]] [[Field Operators]] [[Order Operators]] [[Negatable Operators]]
+title: nsortcs Operator
 type: text/vnd.tiddlywiki
+caption: nsortcs
+purpose: sort the input titles by number field, ignoring case
 
-The ''nsortcs'' filter operator sorts the current list as numeric values, along the field specified in the operand (which defaults to `title`). String values are sorted case sensitively (upper and lower case letters are considered different). Preceding the operator with `!` reverses the sort order.
+<$macrocall $name=".operator-def"
+input="a [[selection of titles|Title Selection]]"
+parameter="the name of a [[field|TiddlerFields]], defaulting to <<.field title>>"
+paramName="f"
+output="the input, sorted into ascending order by field <<.field f>>, treating field values as numbers"
+negationOutput="the input, likewise sorted into descending order"
+/>
 
-For example:
+Non-numeric values are treated as having a higher value than any number, and capital and lowercase letters are treated as different. Compare <<.olink nsort>>.
 
-|!Filter String |!Description |
-|`10 010 1000 100 +[nsortcs[]]` |Returns `10`, `010`, `100`, `1000` |
-|`10 010 alpha 1000 100 +[nsortcs[]]` |Returns `10`, `010`, `100`, `1000`, `alpha` |
-
-See also [[FilterOperator: sort]], [[FilterOperator: sortcs]] and [[FilterOperator: nsort]].
+<<.operator-examples "nsortcs">>

editions/tw5.com/tiddlers/filters/nth.tid

@@ -1,14 +1,18 @@
-created: 20140410103123179
-modified: 20140410103123179
-tags: Filters
-caption: nth
-title: FilterOperator: nth
+created: 20150122204111000
+modified: 20150124204959000
+tags: [[Filter Operators]] [[Order Operators]]
+title: nth Operator
 type: text/vnd.tiddlywiki
+caption: nth
+purpose: select the <<.place n>>th input title
 
-Without an operand, the ''nth'' filter operator returns the first entry in the current list. The optional operand specifies the position of the entry in the list.
+<$macrocall $name=".operator-def"
+input="a [[selection of titles|Title Selection]]"
+parameter="an integer, defaulting to 1"
+paramName="n"
+output="the <<.place n>>th input title"
+/>
 
-For example:
+<<.place n>> is one-based. In other words, `nth[1]` has the same effect as the <<.olink first>> operator.
 
-|!Filter String |!Description |
-|`one two three four five +[nth[]]` |Returns `one` |
-|`one two three four five +[nth[3]]` |Returns `three` |
+<<.operator-examples "nth">>

editions/tw5.com/tiddlers/filters/plugintiddlers.tid

@@ -1,15 +1,15 @@
 created: 20140410103123179
-modified: 20140410103123179
-tags: Filters
-caption: plugintiddlers
-title: FilterOperator: plugintiddlers
+modified: 20150124200549000
+tags: [[Filter Operators]] [[Special Operators]]
+title: plugintiddlers Operator
 type: text/vnd.tiddlywiki
+caption: plugintiddlers
+purpose: select all shadow titles in the input plugins
 
-The ''plugintiddlers'' filter operator returns the titles of the shadow tiddlers within any plugin tiddlers in the current list.
+<$macrocall $name=".operator-def"
+input="a [[selection|Title Selection]] of plugin tiddler titles"
+parameter="none"
+output="all shadow titles contained in the input plugins"
+/>
 
-For example:
-
-|!Filter String |!Description |
-|`[[$:/core]plugintiddlers[]]` |Returns a list of the shadow tiddlers within the [[$:/core]] module |
-
-See also [[FilterOperator: shadowsource]].
+<<.operator-examples "plugintiddlers">>

editions/tw5.com/tiddlers/filters/prefix.tid

@@ -1,16 +1,19 @@
 created: 20140410103123179
-modified: 20140410103123179
-tags: Filters
-caption: prefix
-title: FilterOperator: prefix
+modified: 20150124192023000
+tags: [[Filter Operators]] [[String Operators]] [[Negatable Operators]]
+title: prefix Operator
 type: text/vnd.tiddlywiki
+caption: prefix
+purpose: filter the input titles by how they start
 
-The ''prefix'' filter operator returns the titles in the current list that start with a specified prefix. If the ''prefix'' operator is preceded by `!` then it returns the titles that do not start with the specified prefix.
+<$macrocall $name=".operator-def"
+input="a [[selection of titles|Title Selection]]"
+parameter="a string of characters"
+paramName="s"
+output="those input titles that start with <<.place s>>"
+negationOutput="those input tiddlers that do <<.em not>> start with <<.place s>>"
+/>
 
-For example:
+<<.s-matching-is-case-sensitive>>
 
-|!Filter String |!Description |
-|`[tag[task]!prefix[hidden]]` |Returns tiddlers tagged `task` whose titles do not start with `hidden` |
-|`[prefix[$:/]]` |Equivalent to `[is[system]]` |
-
-See also [[FilterOperator: removeprefix]], [[FilterOperator: removesuffix]], [[FilterOperator: removesuffix]], [[FilterOperator: addprefix]], and [[FilterOperator: addsuffix]].
+<<.operator-examples "prefix">>

editions/tw5.com/tiddlers/filters/previous.tid

@@ -1,21 +1,18 @@
 created: 20140410103123179
-modified: 20140410103123179
-tags: Filters
-caption: previous
-title: FilterOperator: previous
+modified: 20150124171748000
+tags: [[Filter Operators]] [[Field Operators]] [[Order Operators]]
+title: previous Operator
 type: text/vnd.tiddlywiki
+caption: previous
+purpose: find which titles in a <<.field list>> field precede the input ones
 
-The ''previous'' filter operator takes each tiddler in the current list and looks it up in the `list` field of the tiddler specified in the operand, and then returns the immediately preceding tiddler title.
+<$macrocall $name=".operator-def"
+input="a [[selection of titles|Title Selection]]"
+parameter="a tiddler title"
+paramName="t"
+output="a selection containing each title that immediately precedes each of the input titles in the <<.field list>> field of <<.place t>>"
+/>
 
-The following examples assume a tiddler called `MyList` with a `list` field containing:
+Each input title is processed in turn, and its predecessor is located in the <<.field list>> field and appended to the output. If a title is not listed in the field, or is the first item there, then it contributes nothing to the output.
 
-```
-one two three four five
-```
-
-|!Filter String |!Description |
-|`[[three]previous[MyList]]` |Returns `two` |
-|`[[one]previous[MyList]]` |Returns an empty list |
-|`two four +[previous[MyList]]` |Returns `one`, `three` |
-
-See also [[FilterOperator: next]].
+<<.operator-examples "previous">>

editions/tw5.com/tiddlers/filters/regexp.tid

@@ -1,37 +1,31 @@
 created: 20140909134102102
-modified: 20140909134102102
-tags: Filters
-caption: regexp
-title: FilterOperator: regexp
+modified: 20150124203736000
+tags: [[Filter Operators]] [[Field Operators]] [[Negatable Operators]]
+title: regexp Operator
 type: text/vnd.tiddlywiki
+caption: regexp
+purpose: filter the input by pattern-matched field
 
-The ''regexp'' filter operator filters tiddlers that match a regular expression.
+<$macrocall $name=".operator-def"
+input="a [[selection of titles|Title Selection]]"
+suffix="the name of a [[field|TiddlerFields]]"
+suffixName="f"
+parameter="a regular expression"
+paramName="x"
+output="those input tiddlers in which field <<.place f>> matches <<.place x>>"
+negationOutput="those input tiddlers in which field <<.place f>> does <<.em not>> match <<.place x>>"
+/>
 
-Regular expressions are a way of encoding complex string matching criteria. The format is defined fully in [[this Mozilla reference|https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions]].
+<<.def "Regular expressions">> are concise strings of characters that denote patterns of text to search for. The format used in ~TiddlyWiki is fully defined in [[this Mozilla reference|https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions]].
 
-The regexp filter operator takes a fieldname as the optional suffix (defaulting to `title`).
+The [[filter syntax|Filter Run]] makes it impossible to directly specify a regular expression that contains square brackets. The solution is to store the expression in a [[variable|Variables]]. See the <<.operator-examples "regexp" "examples">>.
 
-The regular expression itself can start or end with an optional string to specify flags in the format `(?flags)` where flags can be "g", "m" or "i". Only the "i" flag is generally useful: it forces the match to be case-insensitive (ie upper and lower case letters are considered the same).
+The parameter <<.place x>> can optionally start or end with a string of flags:
 
-For example:
+<$railroad text=""" "(?" { ("i"|"m"|:"g") } ")" """/>
 
-|!Filter String |!Description |
-|`[all[tiddlers]regexp[EggCup]]` |Selects all tiddlers that have the CamelCase string "EggCup" in their title |
-|`[all[tiddlers]regexp[eggcup(?i)]]` |Selects all tiddlers that have the string "eggcup" in their title (ignoring case) |
-|`[all[tiddlers]regexp[(?i)\.jpe?g$]]` |Selects all tiddlers with titles ending in ".jpg" or ".jpeg" (ignoring case) |
-|`[all[tiddlers]regexp:modified[^2014]]` |Selects all tiddlers whose modified field starts with the string "2014" |
+Only the `i` flag is generally useful: it forces the different between capital and lowercase letters to be ignored.
 
-! Regular Expressions with Square Brackets
-
-Note that the filter syntax doesn't allow you to directly enter regular expressions that include square brackets. Instead, you should use a variable to store the filter string. For example, the following regular expression matches all titles that contain any combination the letters "a", "b" and "c" (with no other characters present).
-
-```
-<$set name="myfilter" value="^[abc]*$">
-<$list filter="[regexp:title<myfilter>]">
-<div>
-<$view field="title"/>
-</div>
-</$list>
-</$set>
-```
+If <<.place x>> is empty, <<.op regexp>> will match all of the input tiddlers.
 
+<<.operator-examples "regexp">>

editions/tw5.com/tiddlers/filters/removeprefix.tid

@@ -1,15 +1,18 @@
 created: 20140410103123179
-modified: 20140410103123179
-tags: Filters
-caption: removeprefix
-title: FilterOperator: removeprefix
+modified: 20150124173431000
+tags: [[Filter Operators]] [[String Operators]]
+title: removeprefix Operator
 type: text/vnd.tiddlywiki
+caption: removeprefix
+purpose: filter the input titles by how they start, deleting that prefix
 
-The ''removeprefix'' filter operator returns the titles in the current list that start with a specified prefix with the prefix removed.
+<$macrocall $name=".operator-def"
+input="a [[selection of titles|Title Selection]]"
+parameter="a string of characters"
+paramName="s"
+output="those input titles that start with <<.place s>>, but with those characters discarded"
+/>
 
-For example:
+<<.s-matching-is-case-sensitive>>
 
-|!Filter String |!Description |
-|`tid-one tid-two three +[removeprefix[tid-]]` |Returns `one`, `two` |
-
-See also [[FilterOperator: prefix]], [[FilterOperator: suffix]], [[FilterOperator: removesuffix]], [[FilterOperator: addprefix]], and [[FilterOperator: addsuffix]].
+<<.operator-examples "removeprefix">>

editions/tw5.com/tiddlers/filters/removesuffix.tid

@@ -1,15 +1,18 @@
 created: 20140828133830424
-modified: 20140902145613329
-tags: Filters
-caption: removesuffix
-title: FilterOperator: removesuffix
+modified: 20150124173434000
+tags: [[Filter Operators]] [[String Operators]]
+title: removesuffix Operator
 type: text/vnd.tiddlywiki
+caption: removesuffix
+purpose: filter the input titles by how they end, deleting that suffix
 
-The ''removesuffix'' filter operator returns the titles in the current list that end with a specified suffix with the suffix removed.
+<$macrocall $name=".operator-def"
+input="a [[selection of titles|Title Selection]]"
+parameter="a string of characters"
+paramName="s"
+output="those input titles that end with <<.place s>>, but with those characters discarded"
+/>
 
-For example:
+<<.s-matching-is-case-sensitive>>
 
-|!Filter String |!Description |
-|`one-tid two-tid three +[removesuffix[-tid]]` |Returns `one`, `two` |
-
-See also [[FilterOperator: suffix]], [[FilterOperator: prefix]], [[FilterOperator: removeprefix]], [[FilterOperator: addprefix]], and [[FilterOperator: addsuffix]].
+<<.operator-examples "removesuffix">>

editions/tw5.com/tiddlers/filters/rest.tid

@@ -1,14 +1,18 @@
 created: 20140410103123179
-modified: 20140410103123179
-tags: Filters
-caption: rest
-title: FilterOperator: rest
+modified: 20150124191714000
+tags: [[Filter Operators]] [[Order Operators]]
+title: rest Operator
 type: text/vnd.tiddlywiki
+caption: rest
+purpose: discard the first <<.place n>> input titles
 
-Without an operand, the ''rest'' filter operator returns all but the first entry in the current list. The optional operand specifies the number of entries to omit.
+<$macrocall $name=".operator-def"
+input="a [[selection of titles|Title Selection]]"
+parameter="an integer, defaulting to 1"
+paramName="n"
+output="all but the first <<.place n>> input titles"
+/>
 
-For example:
+<<.olink butfirst>> and <<.olink bf>> are synonyms for <<.op rest>>.
 
-|!Filter String |!Description |
-|`one two three four five +[rest[]]` |Returns `two`, `three`, `four`, `five` |
-|`one two three four five +[rest[2]]` |Returns `three`, `four`, `five` |
+<<.operator-examples "rest">>

editions/tw5.com/tiddlers/filters/reverse.tid

@@ -1,13 +1,15 @@
 created: 20140410103123179
-modified: 20140410103123179
-tags: Filters
-caption: reverse
-title: FilterOperator: reverse
+modified: 20150124205130000
+tags: [[Filter Operators]] [[Order Operators]]
+title: reverse Operator
 type: text/vnd.tiddlywiki
+caption: reverse
+purpose: reverse the order of the input titles
 
-The ''reverse'' filter operator reverses the order of the titles in the current list.
+<$macrocall $name=".operator-def"
+input="a [[selection of titles|Title Selection]]"
+parameter="none"
+output="the input, in reverse order"
+/>
 
-For example:
-
-|!Filter String |!Description |
-|`one two three +[reverse[]]` |Returns the list `three`, `two`, `one` |
+<<.operator-examples "reverse">>

editions/tw5.com/tiddlers/filters/sameday.tid

@@ -1,16 +1,22 @@
 created: 20140410103123179
-modified: 20140410103123179
-tags: Filters
-caption: sameday
-title: FilterOperator: sameday
+modified: 20150124191743000
+tags: [[Filter Operators]] [[Date Operators]]
+title: sameday Operator
 type: text/vnd.tiddlywiki
+caption: sameday
+purpose: filter the input by date
 
-The ''sameday'' filter operator filters the current list to leave only those tiddlers whose `modified` field is on the same day as the date provided as the operand. The optional suffix allows a different field to be specified.
+<$macrocall $name=".operator-def"
+input="a [[selection of titles|Title Selection]]"
+suffix="the name of a date [[field|TiddlerFields]], defaulting to <<.field modified>>"
+suffixName="f"
+parameter="a date, in the [[format|DateFormat]] `YYYYMMDD`"
+paramName="d"
+output="those input tiddlers in which field <<.place f>> has the value <<.place d>>, ignoring time"
+/>
 
-For example:
+If <<.place d>> is not a valid date, the output is empty.
 
-|!Filter String |!Description |
-|`[sameday[20140410]]` |Returns a list of the tiddlers modified on the 10th April 2014 |
-|`[sameday:created[20140410]]` |Returns a list of the tiddlers created on the 10th April 2014 |
+<<.place d>> may include a time of day, but this is ignored.
 
-See [[FilterOperator: eachday]] for an example.
+<<.operator-examples "sameday">>

editions/tw5.com/tiddlers/filters/search.tid

@@ -1,17 +1,24 @@
 created: 20140410103123179
-modified: 20140410103123179
-tags: Filters CommonFilters
-caption: search
-title: FilterOperator: search
+modified: 20150124204023000
+tags: [[Filter Operators]] [[Common Operators]] [[Field Operators]] [[Negatable Operators]]
+title: search Operator
 type: text/vnd.tiddlywiki
+caption: search
+purpose: filter the input by searching tiddler content
 
-The ''search'' filter operator filters the current list to leave only those tiddlers that include the operand text in their title, body or tags. Preceding the operator with `!` returns all tiddlers that do not include the specified text. The search is case-insenstive.
+<$macrocall $name=".operator-def"
+input="a [[selection of titles|Title Selection]]"
+suffix="optionally, the name of a [[field|TiddlerFields]]"
+suffixName="f"
+parameter="one or more search terms, separated by spaces"
+output="those input tiddlers in which <<.em all>> of the search terms can be found in the value of field <<.place f>>"
+negationOutput="those input tiddlers in which <<.em not>> all of the search terms can be so found"
+/>
 
-Optionally, a field can be specified to restrict the search.
+When used with a suffix, the <<.op search>> operator is similar to <<.olink regexp>> but less powerful.
 
-For example:
+If the suffix is omitted, a tiddler is deemed to match if all the search terms appear in the combination of its <<.field tags>>, <<.field text>> and <<.field title>> fields.
 
-|!Filter String |!Description |
-|`[search[alsatian]]` |Returns a list of the tiddlers containing the text "alsatian" |
-|`[all[shadows]search[alsatian]]` |Returns a list of the shadow tiddlers containing the text "alsatian" |
-|`[search:caption[spaniel]]` |Returns a list of the tiddlers containing the text "spaniel" in their caption field |
+The search ignores the difference between capital and lowercase letters.
+
+<<.operator-examples "search">>

editions/tw5.com/tiddlers/filters/shadowsource.tid

@@ -1,15 +1,17 @@
 created: 20140410103123179
-modified: 20140410103123179
-tags: Filters
-title: FilterOperator: shadowsource
-caption: shadowsource
+modified: 20150124210534000
+tags: [[Filter Operators]] [[Special Operators]]
+title: shadowsource Operator
 type: text/vnd.tiddlywiki
+caption: shadowsource
+purpose: select the plugin titles that contain the input shadows
 
-The ''shadowsource'' filter operator returns the titles of the plugin tiddlers containing any ShadowTiddlers in the current list.
+<$macrocall $name=".operator-def"
+input="a [[selection|Title Selection]] of [[shadow titles|ShadowTiddlers]]"
+parameter="none"
+output="the [[plugins|Plugins]] that contain the input tiddlers"
+/>
 
-For example:
+Each input title is processed in turn. If it denotes a shadow tiddler, the title of its plugin tiddler is [[dominantly appended|Dominant Append]] to the output. Non-shadow tiddlers contribute nothing to the output.
 
-|!Filter String |!Description |
-|`[[$:/core/copyright.txt]shadowsource[]]` |Returns `$:/core`, which is the plugin that contains the shadow tiddler [[$:/core/copyright.txt]] |
-
-See also [[FilterOperator: plugintiddlers]].
+<<.operator-examples "shadowsource">>

editions/tw5.com/tiddlers/filters/sort.tid

@@ -1,18 +1,19 @@
 created: 20140410103123179
-modified: 20140410103123179
-tags: Filters CommonFilters
-title: FilterOperator: sort
-caption: sort
+modified: 20150124205350000
+tags: [[Filter Operators]] [[Common Operators]] [[Field Operators]] [[Order Operators]] [[Negatable Operators]]
+title: sort Operator
 type: text/vnd.tiddlywiki
+caption: sort
+purpose: sort the input by text field
 
-The ''sort'' filter operator sorts the current list case insensitively (upper and lower case letters are considered equivalent), along the field specified in the operand (which defaults to `title`). Preceding the operator with `!` reverses the sort order.
+<$macrocall $name=".operator-def"
+input="a [[selection of titles|Title Selection]]"
+parameter="the name of a [[field|TiddlerFields]], defaulting to <<.field title>>"
+paramName="f"
+output="the input, sorted into ascending order by field <<.field f>>, treating field values as text"
+negationOutput="the input, likewise sorted into descending order"
+/>
 
-For example:
+The difference between capital and lowercase letters is ignored. Compare <<.olink sortcs>>.
 
-|!Filter String |!Description |
-|`one two three four +[sort[]]` |Returns `four`, `one`, `three`, `two` |
-|`one two Three four +[sort[]]` |Returns `four`, `one`, `Three`, `two` |
-
-For an example of use with explicit operands, see [[FilterOperator: limit]].
-
-See also [[FilterOperator: nsort]], [[FilterOperator: sortcs]] and [[FilterOperator: nsortcs]].
+<<.operator-examples "sort">>

editions/tw5.com/tiddlers/filters/sortcs.tid

@@ -1,15 +1,19 @@
 created: 20140410103123179
-modified: 20140410103123179
-tags: Filters
-title: FilterOperator: sortcs
-caption: sortcs
+modified: 20150124205353000
+tags: [[Filter Operators]] [[Field Operators]] [[Order Operators]] [[Negatable Operators]]
+title: sortcs Operator
 type: text/vnd.tiddlywiki
+caption: sortcs
+purpose: sort the input by text field, ignoring case
 
-The ''sortcs'' filter operator sorts the current list case sensitively (upper and lower case letters are considered different), along the field specified in the operand (which defaults to `title`). Preceding the operator with `!` reverses the sort order.
+<$macrocall $name=".operator-def"
+input="a [[selection of titles|Title Selection]]"
+parameter="the name of a [[field|TiddlerFields]], defaulting to <<.field title>>"
+paramName="f"
+output="the input, sorted into ascending order by field <<.field f>>, treating field values as text"
+negationOutput="the input, likewise sorted into descending order"
+/>
 
-For example:
+Capital and lowercase letters are treated as different. Compare <<.olink sort>>.
 
-|!Filter String |!Description |
-|`one two Three four +[sortcs[]]` |Returns `Three`, `four`, `one`, `two` |
-
-See also [[FilterOperator: sort]], [[FilterOperator: nsort]] and [[FilterOperator: nsortcs]].
+<<.operator-examples "sortcs">>