Merge pull request #2604 from obsidian-tasks-group/docs-custom-sort

docs: Document custom sorting and `sort by function`

Author: claremacrae

docs/Queries/About Queries.md

@@ -87,7 +87,7 @@ The only exceptions to this flexibility are:
 
 - When [[Combining Filters]], the boolean operators such as `AND`, `OR` and `NOT` must still be capitalised.
 - In [[Regular Expressions]], the search pattern and flags are still case-sensitive.
-- The code in expressions in [[Custom Filters]] and [[Custom Grouping]] remain case-sensitive.
+- The code in expressions in [[Custom Filters]], [[Custom Sorting]] and [[Custom Grouping]] remain case-sensitive.
 
 ### Why is my query not working?
 

docs/Queries/Line Continuations.md

@@ -42,7 +42,7 @@ Explanation of this Tasks code block query:
 ```
 <!-- endSnippet -->
 
-This facility will be helpful for long [[Combining Filters]], [[Custom Filters]], and [[Custom Grouping]] lines, and other queries that may be difficult to read on one line.
+This facility will be helpful for long [[Combining Filters]], [[Custom Sorting]], and [[Custom Grouping]] lines, and other queries that may be difficult to read on one line.
 
 There are some more realistic examples towards the end of the [[Grouping#Due Date|Due date custom grouping examples]].
 

docs/Queries/Sorting.md

@@ -13,6 +13,7 @@ publish: true
 This page is long. Here are some links to the main sections:
 
 - [[#Default sort order]]
+- [[#Custom Sorting]]
 - [[#Sort by Task Statuses]]
 - [[#Sort by Dates in Tasks]]
 - [[#Sort by Other Task Properties]]
@@ -51,7 +52,16 @@ However, any `sort by` instructions in queries take precedence over these defaul
 
 ## Custom Sorting
 
-==TODO Populate this section==
+> [!released]
+> `sort by function` was introduced in Tasks X.Y.Z.
+
+Tasks provides many built-in sorting options, but sometimes they don't quite do what is wanted by all users.
+
+Now Tasks has a powerful mechanism for you to create your own **custom sort orders**, offering incredible flexibility.
+
+There are many examples of the custom filtering instruction `sort by function` in the documentation below, with explanations, for when the instructions built in to Tasks do not satisfy your preferences.
+
+You can find out more about this very powerful facility in [[Custom Sorting]].
 
 ## Sort by Task Statuses
 
@@ -61,6 +71,9 @@ For more information, including adding your own customised statuses, see [[Statu
 
 - `sort by status` (done or todo)
 
+> [!Tip]
+> `sort by status.type` gives a much more useful sort order than `sort by status`. See [[#Status Type#]] below.
+
 Since Tasks X.Y.Z, **[[Custom Sorting|custom sorting]] by status** is now possible.
 
 <!-- placeholder to force blank line before included text --><!-- include: CustomSortingExamples.test.other_properties_task.isDone_docs.approved.md -->

docs/Scripting/Custom Grouping.md

@@ -40,12 +40,12 @@ The available task properties are also shown in the [[Quick Reference]] table.
 
 ### Available Query Properties
 
-The Reference section [[Query Properties]] shows all the query properties available for use via [[Placeholders]] in custom grouping.
-
-Any placeholders in custom groups must be surrounded by quotes.
+The Reference section [[Query Properties]] shows all the query properties available for in custom grouping.
 
 > [!released]
-> Query properties and placeholders were introduced in Tasks 4.7.0.
+>
+> - Query properties and placeholders were introduced in Tasks 4.7.0.
+> - Direct access to Query properties was introduced in Tasks 5.1.0.
 
 ### Expressions
 

docs/Scripting/Custom Sorting.md

@@ -13,12 +13,13 @@ publish: true
 
 - Define your own custom task sort order, using JavaScript expressions such as:
   - `sort by function task.description.length`
+  - We call the result of this expression a **sort key**.
+  - Tasks with **lower values** from the sort key expression are sorted **before** tasks with **higher expression** values.
 - There are examples in [[Sorting]].
   - Search for `sort by function` in that file.
 - Find all the **supported tasks properties** in [[Task Properties]] and [[Quick Reference]].
   - A number of properties are only available for custom sorting, and not for built-in sorting instructions.
 - Find all the **supported query properties** in [[Query Properties]].
-  - ==TODO Query properties are not yet supported in custom sorters.==
 - Learn a bit about how expressions work in [[Expressions]].
 
 ## Custom sorting introduction
@@ -40,12 +41,7 @@ The Reference section [[Task Properties]] shows all the task properties availabl
 The available task properties are also shown in the [[Quick Reference]] table.
 ### Available Query Properties
 
-The Reference section [[Query Properties]] shows all the query properties available for use via [[Placeholders]] in custom sorting.
-
-Any placeholders in custom sorts must be surrounded by quotes.
-
-> [!released]
-> Query properties and placeholders were introduced in Tasks 4.7.0.
+The Reference section [[Query Properties]] shows all the query properties available for use in custom sorting.
 
 ### Expressions
 
@@ -54,15 +50,17 @@ The instructions look like this:
 - `sort by function <expression>`
 - `sort by function reverse <expression>`
 
-The expression is evaluated (calculated) on each task that matches your query, and the expression result is used as the sort key for the task.
+The expression is evaluated (calculated) on each task that matches your query, and the expression result is used as the **sort key** for the task.
 
-==TODO Update this==
+This table shows how the supported sort key value types behave.
 
-| Desired heading                                                             | Values that you can return                                                                             |
-| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
-| A single sort name for the task                                            | A single value, such as `'sort name'`.<br>An array, with a single value in, such as `['sort name']`. |
-| Display the task potentially more than once (as is done by `sort by tags`) | An array of values, such as:<br>`['heading 1', 'heading 2']`                                             |
-| No heading                                                                  | `null`<br>Empty string `''`<br>Empty array `[]`                                                        |
+| Sort key expression types          | Values that you can return                                                                                                                                                                  |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Strings                            | Example: `sort by function task.originalMarkdown`<br>Tasks are sorted alphabetically by the string key values. The sort is case-sensitive. It is aware of numbers and sorts them logically. |
+| Numbers                            | Example: `sort by function task.description.length`<br>Numbers are sorted in ascending order. The lower the number, the earlier the task is sorted.                                         |
+| Boolean values: `true` and `false` | Example: `sort by function task.status.name.includes('!!')` <br>Tasks with sort key `true` sort before ones with `false`.                                                                   |
+| `TasksDate` and `Moment` objects   | Example: `sort by function task.created`<br>See [[Sorting#How dates are sorted\|How dates are sorted]].                                                                                     |
+| `null`                             | `null` sorts after valid `TasksDate` and `Moment` objects, and before all other sort key values.                                                                                                                                                                                            |
 
 The `expression` can:
 
@@ -71,19 +69,15 @@ The `expression` can:
 
 The `expression` must:
 
-==TODO Update this==
-
-- use properties on a given task, such as `task.description`, `task.status.name`
-  - See the reference page [[Task Properties]] for all the available properties
-- return one of:
-  - either a single value of any type that can be converted to string
-  - or an array of values (in which case, the task will be displayed multiple times, once under each heading generated from the array)
+- use properties on a given task, such as `task.description`, `task.status.name`.
+  - See the reference page [[Task Properties]] for all the available properties.
+- return one of types of values listed in the table above.
 
 ## Example custom sorts
 
 Below are some examples to give a flavour of what can be done with custom sorts.
 
-You can find many more examples by searching for `sort by function` in the [[Sorting]] page.
+You can find some more examples by searching for `sort by function` in the [[Sorting]] page.
 
 ### Text property examples
 
@@ -115,6 +109,11 @@ sort by function \
 
 ### Date property examples
 
+Useful sections:
+
+- [[Task Properties#Values in TasksDate Properties|Values in TasksDate Properties]]
+- [[Sorting#How dates are sorted|How dates are sorted]]
+
 <!-- placeholder to force blank line before included text --><!-- include: CustomSortingExamples.test.dates_task.due_docs.approved.md -->
 
 ```javascript
@@ -140,6 +139,10 @@ sort by function reverse task.urgency
 
 ### File property examples
 
+Useful sections:
+
+- [[Task Properties#Values for File Properties|Values for File Properties]]
+
 <!-- placeholder to force blank line before included text --><!-- include: CustomSortingExamples.test.file_properties_task.file.folder_docs.approved.md -->
 
 ```javascript
@@ -159,28 +162,11 @@ sort by function task.file.path === query.file.path
 
 ## Troubleshooting
 
-> [!Warning]
-> Currently most types of error in function expressions are only detected when the search runs.
+> [!Tip]
+> To test the values obtained from your sort key, replace `sort by` with `group by`. The generated group headings provide a sort of "debugger" to show expression values.
 >
-> This means that error messages are displayed in the sort headings, when results are viewed.
->
-> In a future release, we plan to show errors in formulae when the query block is being read.
-
-### Syntax error
+> However, be aware that whilst  `group by` expressions can return arrays of values, `sort by` does not yet support arrays.
 
-The following example gives an error:
-
-````text
-```tasks
-sort by function hello
-```
-````
-
-gives this heading name:
-
-```text
-##### Error: Failed calculating expression "hello". The error message was: hello is not defined
-```
+## Limitations of Custom Sorting
 
-> [!todo]
-> Do syntax-error checking when parsing the instruction
+- Arrays cannot yet be used as sort keys, as we have not figured out the appropriate way to sort arrays of different lengths.

docs/Scripting/Expressions.md

@@ -22,9 +22,10 @@ publish: true
 - The expression is a string instruction.
 - As of Tasks 4.4.0, variables, functions, `if` blocks and similar can be used. See [[#More complex expressions]].
 - As of Tasks 5.0.0, long expressions can be written over multiple lines thanks to [[Line Continuations]].
-- Depending on the context, one or two tasks are passed in to the expression, and a calculation is performed.
-  - As of Tasks 4.0.0, in fact only a single task is passed in, to implement [[Custom Grouping]].
+- One task is passed in to the expression, and a calculation is performed.
+  - As of Tasks 4.0.0, a single task is passed in, to implement [[Custom Grouping]].
   - As of Tasks 4.2.0, a single task is passed in, to implement [[Custom Filters]].
+  - As of Tasks X.Y.Z, a single task is passed in, to implement [[Custom Sorting]].
 - Tasks then calculates a value from the inputs.
 
 ## Example expressions

docs/Scripting/Query Properties.md

@@ -17,6 +17,7 @@ In a growing number of locations, Tasks allows programmatic/scripting access to
 
 - [[Placeholders]]
 - [[Custom Filters]]
+- [[Custom Sorting]]
 - [[Custom Grouping]]
 
 This page documents all the available pieces of information in Queries that you can access.

docs/Scripting/Task Properties.md

@@ -14,6 +14,7 @@ publish: true
 In a growing number of locations, Tasks allows programmatic/scripting access to values in your Tasks:
 
 - [[Grouping#Custom Groups]]
+- [[Sorting#Custom Sorting]]
 - [[Filters#Custom Filters]]
 
 This page documents all the available pieces of information in Tasks that you can access.

docs/Support and Help/Known Limitations.md

@@ -71,6 +71,10 @@ This page gathers together all the documentation on known limitations of the plu
 
 ![[Regular Expressions#Known limitations]]
 
+## Queries: Custom Sorting
+
+![[Custom Sorting#Limitations of Custom Sorting]]
+
 ## Settings: Status Settings
 
 ![[Status Settings#Limitations and Issues]]