Add documentation on happens filter

docs/queries/filters.md

@@ -6,6 +6,7 @@ parent: Queries
 ---
 
 # Filters
+
 {: .no_toc }
 
 <details open markdown="block">
@@ -23,12 +24,13 @@ parent: Queries
 
 `<date>` filters can be given in natural language or in formal notation.
 The following are some examples of valid `<date>` filters as inspiration:
-- `2021-05-05`
-- `today`
-- `tomorrow`
-- `next monday`
-- `last friday`
-- `in two weeks`
+
+-   `2021-05-05`
+-   `today`
+-   `tomorrow`
+-   `next monday`
+-   `last friday`
+-   `in two weeks`
 
 Note that if it is Wednesday and you write `tuesday`, Tasks assumes you mean "yesterday", as that is the closest Tuesday.
 Use `next tuesday` instead if you mean "next tuesday".
@@ -38,6 +40,7 @@ When the day changes, relative dates like `due today` are re-evaluated so that t
 ---
 
 ## Matching
+
 All filters of a query have to match in order for a task to be listed.
 This means you cannot show tasks that have "GitHub in the path and have no due date or are due after 2021-04-04".
 Instead you would have two queries, one for each condition:
@@ -62,15 +65,16 @@ Instead you would have two queries, one for each condition:
 
 ### Done Date
 
-- `done`
-- `not done`
-- `done (before|after|on) <date>`
+-   `done`
+-   `not done`
+-   `done (before|after|on) <date>`
 
 ### Priority
 
-- `priority is (above|below)? (low|none|medium|high)`
+-   `priority is (above|below)? (low|none|medium|high)`
 
 #### Examples
+
 {: .no_toc }
 
     ```tasks
@@ -83,8 +87,9 @@ Instead you would have two queries, one for each condition:
     ```
 
 ### Start Date
-- `no start date`
-- `starts (before|after|on) <date>`
+
+-   `no start date`
+-   `starts (before|after|on) <date>`
 
 When filtering queries by [start date]({{ site.baseurl }}{% link getting-started/dates.md %}#-start),
 the result will include tasks without a start date.
@@ -97,39 +102,49 @@ Such filter could be:
     ```
 
 ### Scheduled Date
-- `no scheduled date`
-- `scheduled (before|after|on) <date>`
+
+-   `no scheduled date`
+-   `scheduled (before|after|on) <date>`
 
 ### Due Date
 
-- `no due date`
-- `due (before|after|on) <date>`
+-   `no due date`
+-   `due (before|after|on) <date>`
+
+### Happens
+
+-   `happens (before|after|on) <date>`
+
+`happens` returns any task for a matching start date, scheduled date, _or_ due date.
+For example, `happens before tomorrow` will return all tasks that are starting, scheduled, or due earlier than tomorrow.
+If a task starts today and is due in a week from today, `happens before tomorrow` will match,
+because the tasks starts before tomorrow. Only one of the dates needs to match.
 
 ### Recurrence
 
-- `is recurring`
-- `is not recurring`
+-   `is recurring`
+-   `is not recurring`
 
 ### File Path
 
-- `path (includes|does not include) <path>`
-    - Matches case-insensitive (disregards capitalization).
+-   `path (includes|does not include) <path>`
+    -   Matches case-insensitive (disregards capitalization).
 
 ### Description
 
-- `description (includes|does not include) <string>`
-    - Matches case-insensitive (disregards capitalization).
-    - Disregards the global filter when matching.
+-   `description (includes|does not include) <string>`
+    -   Matches case-insensitive (disregards capitalization).
+    -   Disregards the global filter when matching.
 
 ### Heading
 
-- `heading (includes|does not include) <string>`
-    - Whether or not the heading preceding the task includes the given string.
-    - Always tries to match the closest heading above the task, regardless of heading level.
-    - `does not include` will match a task that does not have a preceding heading in its file.
-    - Matches case-insensitive (disregards capitalization).
+-   `heading (includes|does not include) <string>`
+    -   Whether or not the heading preceding the task includes the given string.
+    -   Always tries to match the closest heading above the task, regardless of heading level.
+    -   `does not include` will match a task that does not have a preceding heading in its file.
+    -   Matches case-insensitive (disregards capitalization).
 
 ### Sub-Items
 
-- `exclude sub-items`
-    - When this is set, the result list will only include tasks that are not indented in their file. It will only show tasks that are top level list items in their list.
+-   `exclude sub-items`
+    -   When this is set, the result list will only include tasks that are not indented in their file. It will only show tasks that are top level list items in their list.