docs, fix: Finalise Statuses docs & UI (#1584)

* fix: Rename the status settings arrays.

This is partly to avoid needing to implement
backwards-compatibility of reading settings for
settings written by the 2 test builds.

And partly because I want to reserve use of 'status type'
to the new status.type instructions (DONE, TODO, IN_PROGRESS, CANCELLED)

* fix: Remove 'Status Types' references in settings GUI.

* fix: Clarify a reference to 'Status type' in docs

* docs: Add introduction and promote related pages

* docs: More info on sections in settings pane

* test: Update documentation snippets for Core/Custom split

* feat: Improve wording on Edit Status modal

* docs: Interim commit of statuses.md

* docs: Update statuses screenshots

* docs: Fix incorrect image

* docs: Mark up interesting sections of images

* docs: Add introduction and promote related pages

* test: Status Character -> Status Symbol in docs tables

Also, re-ordered the columns so that the two symbols columns are adjacent.
I spotted an error in doing so.

* fix: The Next Symbol for DONE was wrong in both theme collections

* docs: Interim commit of statuses docs

* test: Add some more snippets of status scenarios

* docs: Add 'What can Statuses do?' section

* docs: Update create-or-edit-task.md

* docs: Document recurrence and done dates

* docs: More info on status type.

* docs: Add some sample images to the statuses page.

* fix: Add missing full-stop to CustomStatusModal

* docs: Group some headings together for readability

* docs: Reorder the status HowTos

* docs: Add a standard snippet with links between status docs

* docs: Move description of Statuses Settings to dedicated page

And added new content it it.

* docs: Add editing-a-status.md

* docs: Add 'Example Statuses' page.

* docs: Add 'Core Statuses' page

* docs: Add 'Custom Statuses' page

* docs: Add 'Status Types' page

* docs: Refine Statuses page

* docs: More readable table of status.type behaviour

* docs: Add 'Limitations and Issues' section to status-settings.md

* docs: Improve 'Broad steps to understand and set up Statuses' callout

* docs: Review and update style-custom-statuses.md

* docs: Review and update set-up-custom-statuses.md

* docs: Remove some clutter

* docs: Document 'Unknown Statuses'

* fix: ITS/slrvb now use IN_PROGRESS for 'Doing'

* docs: Add 'Ignoring clicks and toggles'

* docs: Set the version number for custom statuses feature

* docs: Credit the source of 'help message' recommendation.

* vault: Revert accidental setting of theme

* vault: Revert accidental commit of files in sample vault

docs-snippets/snippet-statuses-overview.md

@@ -0,0 +1,18 @@
+<!-- force a blank line -->
+
+{: .info }
+> Broad steps to understand and set up Statuses (or "Alternate Checkboxes"):
+>
+> - Understand what Statuses are:
+>   - [Statuses]({{ site.baseurl }}{% link getting-started/statuses.md %})
+>   - [Custom Statuses]({{ site.baseurl }}{% link getting-started/statuses/custom-statuses.md %})
+> - Choose your status styling scheme: this will determine the names and symbols for your custom statuses:
+>   - Some common ones are shown in [Status Collections]({{ site.baseurl }}{% link reference/status-collections/index.md %})
+> - Set up your status styling scheme
+>   - [How to style custom statuses]({{ site.baseurl }}{% link how-to/style-custom-statuses.md %}).
+> - Configure Tasks to use your custom statuses
+>   - [How to set up your custom statuses]({{ site.baseurl }}{% link how-to/set-up-custom-statuses.md %})
+> - Optionally, update your tasks searches to take advantage of the new flexibility
+>   - [Filters for Task Statuses]({{ site.baseurl }}{% link queries/filters.md %}#filters-for-task-statuses)
+
+<!-- force a blank line -->

docs/getting-started/create-or-edit-task.md

@@ -110,7 +110,25 @@ Supported abbreviations:
 | `weekend`    | `sat`         |
 | `we`         | `sat`         |
 
-### Status and Done on
+### Status
+
+{: .released }
+Introduced in Tasks 1.23.0.
+
+Use the Status dropdown to change the Status Symbol for the task.
+
+![Task edit modal shows new statuses immediately](../images/modal-showing-new-statuses.png)
+
+For more information, including adding your own customised statuses, see [Statuses]({{ site.baseurl }}{% link getting-started/statuses.md %}).
+
+{: .warning }
+> Editing the Status in the modal does not yet add, remove or update the Done date.
+>
+> Also, completing a recurring task via the Status in the modal does not yet add the new recurrence.
+>
+> For now, you should still complete tasks via command or by clicking on task checkboxes.
+
+### Completed and Done on
 
 These values cannot currently be edited in this modal.
 

docs/getting-started/statuses.md

@@ -4,6 +4,7 @@ title: Statuses
 nav_order: 2
 parent: Getting Started
 has_toc: false
+has_children: true
 ---
 
 # Statuses
@@ -20,119 +21,168 @@ has_toc: false
 
 ---
 
-## What's in a status?
+## Introduction
 
-- `status symbol`
+{: .released }
+Custom Statuses were introduced in Tasks 1.23.0.
+
+This page provides an overview of using Tasks with **Custom Statuses**, which some people refer to as Custom Checkboxes or Alternative/Alternate Checkboxes.
+
+Here's the kind of thing that you can do:
+
+![Selection of checkboxes from Minimal theme](../images/theme-minimal-reading-view-sample.png) ![Selection of checkboxes from ITS theme](../images/theme-its-reading-view-sample.png)
+
+### Related pages
+
+Once you're comfortable with the background information in this page, further information is available in the following related pages.
+
+- [How to style custom statuses]({{ site.baseurl }}{% link how-to/style-custom-statuses.md %}).
+- [How to set up your custom statuses]({{ site.baseurl }}{% link how-to/set-up-custom-statuses.md %}).
+- [Status Collections]({{ site.baseurl }}{% link reference/status-collections/index.md %}).
+
+---
+
+## Do I need to set up statuses?
+
+If you are happy with all your tasks beginning with `[ ]` and `[x]`, then **no**, you can just ignore Tasks' Statuses facility.
+
+---
+
+## About Statuses
+
+### What IS a Status?
+
+Every task in the Tasks plugin now has a Status.
+
+Status is just Tasks' name for:
+
+1. the character (`symbol`) between the `[` and `]` in a task line
+2. AND some options that you can customise, to tell tasks how to treat all your tasks with that character.
+
+Some obsidian users call them other names, like 'Alternative Checkboxes', but that is more about how they are displayed, rather than about the actual *behaviour* of tasks with particular statuses.
+
+### What's IN a Status?
+
+These are the options that you can modify, for each status:
+
+![Task Status modal](../images/settings-custom-statuses-dialog-2.png)
+
+Here is some more detail.
+
+- **Status Symbol**
   - the single character in the `[]` at the start of the task.
-- `status name`
+  - this character will control what how tasks are rendered by your Theme or CSS Snippet.
+- **Status Name**
   - a name for the status.
   - this is flexible: for custom statuses, you can use any name you wish.
   - is searchable with `status.name`, for example `status.name includes My custom in-progress status`.
-- `next status symbol`
+- **Next Status Symbol**
   - the status symbol to use when the task is toggled.
-- `status type`
+- **Status Type**
   - one of `TODO`, `IN_PROGRESS`, `DONE`, `CANCELLED`, `NON_TASK`.
-  - Tasks needs to know the type of each custom status, so that it knows how to treat them when searching, and what to do when tasks with the status are toggled.
-  - is searchable with `status.type`, for example `status.type is IN_PROGRESS`.
-  - you can have any number of custom statuses with the same status type, and then search them conveniently with `status.type`
+  - Tasks needs to know the type of each status, so that it knows how to treat them when searching, and what to do when tasks with the status are toggled.
+  - types are searchable with `status.type`, for example `status.type is IN_PROGRESS`.
+  - Also available:
+    - `sort by status.type`
+    - `group by status.type`
+  - For more information, see [Status Types]({{ site.baseurl }}{% link getting-started/statuses/status-types.md %})
 
-### Status Types
+### Unknown Statuses
 
-This table demonstrates the behaviour of each of the status types in Tasks.
-Each column shows an example task with the given status type.
+What happens if Tasks reads a line with a status symbol that it does not know about?
 
-The tasks shown are purely examples for context. The `~` column is just an arbitrary example to show `NON_TASK`'s behaviour'. You can assign each of these types to any of your custom statuses.
+All such tasks are given a status called `Unknown`, with these properties:
 
-<!-- placeholder to force blank line before included text --> <!-- include: DocsSamplesForStatuses.test.Status_Transitions status-types.approved.md -->
+| Property           | Value                                                               |
+| ------------------ | ------------------------------------------------------------------- |
+| Status Symbol      | The unrecognised character between the `[` and `]` in the task line |
+| Status Name        | **Unknown**                                                         |
+| Next Status Symbol | `x`                                                                 |
+| Status Type        | `TODO`                                                              |
 
-| Operation | TODO | IN_PROGRESS | DONE | CANCELLED | NON_TASK |
-| ----- | ----- | ----- | ----- | ----- | ----- |
-| Example Task | `- [ ] demo` | `- [/] demo` | `- [x] demo` | `- [-] demo` | `- [~] demo` |
-| Matches `done` | no | no | YES | YES | YES |
-| Matches `not done` | YES | YES | no | no | no |
-| Matches `status.name includes todo` | YES | no | no | no | no |
-| Matches `status.type is TODO` | YES | no | no | no | no |
-| Matches `status.name includes in progress` | no | YES | no | no | no |
-| Matches `status.type is IN_PROGRESS` | no | YES | no | no | no |
-| Matches `status.name includes done` | no | no | YES | no | no |
-| Matches `status.type is DONE` | no | no | YES | no | no |
-| Matches `status.name includes cancelled` | no | no | no | YES | no |
-| Matches `status.type is CANCELLED` | no | no | no | YES | no |
-| Matches `status.type is NON_TASK` | no | no | no | no | YES |
-| Name for `group by status` | Todo | Done | Done | Done | Done |
-| Name for `group by status.type` | 2 TODO | 1 IN_PROGRESS | 3 DONE | 4 CANCELLED | 5 NON_TASK |
-| Name for `group by status.name` | Todo | In Progress | Done | Cancelled | My custom status |
+### Done date, Recurrence and Statuses
 
-<!-- placeholder to force blank line after included text --> <!-- endInclude -->
+It is the Task Status Type changing **to** `DONE` that controls when:
 
-{: .warning }
-The `group by` results of the above table are subject to change.
+- tasks **gain** their Done dates (if Done dates are enabled in settings),
+- new copies of recurring tasks are created.
 
-## Standard Markdown task statuses
+It is the Task Status Type changing **from** `DONE` that controls when:
 
-Tasks have a status.
+- tasks **lose** their Done dates (if Done dates are enabled in settings).
 
-The convention in markdown is:
+---
 
-```text
-- [ ] I am a task that is not yet done
-- [x] I am a task that has been done
-```
+## What can Statuses do?
 
----
+Now we have seen what is in a Status, what can we do with them?
 
-## Tasks core task statuses
+We can use them to control what Tasks does when a task's checkbox is clicked, or toggled.
 
-{: .released }
-Introduced in Tasks X.Y.Z
+The [Example Statuses]({{ site.baseurl }}{% link getting-started/statuses/example-statuses.md %}) page has a variety of examples, for inspiration.
 
-Tasks supports custom task statuses.
+---
 
-This table shows the statuses provided by default:
+## More about Statuses
 
-<!-- placeholder to force blank line before included text --> <!-- include: DocsSamplesForStatuses.test.DefaultStatuses_core-statuses.approved.md -->
+### Core Statuses
 
-| Status Character | Status Name<br>`status.name includes...`<br>`sort by status.name`<br>`group by status.name` | Next Status Character | Status Type<br>`status.type is...`<br>`sort by status.type`<br>`group by status.type` | Needs Custom Styling |
-| ----- | ----- | ----- | ----- | ----- |
-| `space` | Todo | `x` | `TODO` | No |
-| `/` | In Progress | `x` | `IN_PROGRESS` | Yes |
-| `x` | Done | `space` | `DONE` | No |
-| `-` | Cancelled | `space` | `CANCELLED` | Yes |
+Core statuses represent conventional markdown tasks:
 
-<!-- placeholder to force blank line after included text --> <!-- endInclude -->
+```text
+- [ ] I am a task that is not yet done
+- [x] I am a task that has been done
+```
 
-### Editing core statuses
+They don't require any custom CSS styling or theming on order to display correctly in Tasks blocks or Live Preview.
 
-The Tasks settings shows the core statuses:
+Before Tasks 1.23.0, these were the only statuses that Tasks knew about.
 
-![Core Statuses](../images/settings-core-statuses.png)
+See [Core Statuses]({{ site.baseurl }}{% link getting-started/statuses/core-statuses.md %}) to find out more.
 
-Note that `Todo` is followed by `Done`, in order to preserve compatibility with earlier Tasks releases.
+### Custom Statuses
 
-{: .info }
-These core statuses are currently read-only.
-It will soon be possible to edit these custom statuses, and enable `Todo` -> `In Progress` -> `Done`.
+Custom statuses represent any non-standard markdown tasks.
 
----
+Here are some tasks with example custom statuses, that is, with non-standard characters between the `[` and `]`:
 
-## Custom task statuses
+```text
+- [X] Checked
+- [-] A dropped/cancelled task
+- [?] A question
+- [/] A Half Done/In-progress task
+```
 
-### First choose your styling scheme
+They **require custom CSS styling or theming** on order to display correctly in Tasks blocks or Live Preview.
 
-You can use any snippet or theme you wish. If you are already using a snippet or theme that supports "custom checkboxes", you should stick with that.
+### What's the Big Deal?
 
-If, however, you are using the default theme, or a theme that doesn't know style "custom checkboxes", you will need to pick one.
+People have been using themes and CSS snippets to style custom checkboxes in Obsidian all along.
 
-[Status Collections]({{ site.baseurl }}{% link reference/status-collections/index.md %}) has a list of the ones that Tasks already has one-click support for, to help you choose.
+What Tasks's custom statuses allow you to do is to **also customise the behaviour of your tasks**.
 
-### Editing custom statuses
+### Setting up Custom Statuses
 
-Your choice of styling facility will determine which letters and characters you wish to you in your custom statuses.
+<!-- force a blank line --> <!-- include: snippet-statuses-overview.md -->
 
-Then see [How to set up your custom statuses]({{ site.baseurl }}{% link how-to/set-up-custom-statuses.md %}) for how to set up your custom statuses.
+{: .info }
+> Broad steps to understand and set up Statuses (or "Alternate Checkboxes"):
+>
+> - Understand what Statuses are:
+>   - [Statuses]({{ site.baseurl }}{% link getting-started/statuses.md %})
+>   - [Custom Statuses]({{ site.baseurl }}{% link getting-started/statuses/custom-statuses.md %})
+> - Choose your status styling scheme: this will determine the names and symbols for your custom statuses:
+>   - Some common ones are shown in [Status Collections]({{ site.baseurl }}{% link reference/status-collections/index.md %})
+> - Set up your status styling scheme
+>   - [How to style custom statuses]({{ site.baseurl }}{% link how-to/style-custom-statuses.md %}).
+> - Configure Tasks to use your custom statuses
+>   - [How to set up your custom statuses]({{ site.baseurl }}{% link how-to/set-up-custom-statuses.md %})
+> - Optionally, update your tasks searches to take advantage of the new flexibility
+>   - [Filters for Task Statuses]({{ site.baseurl }}{% link queries/filters.md %}#filters-for-task-statuses)
+
+<!-- force a blank line --> <!-- endInclude -->
 
-{: .warning }
-Remember to set up your chosen CSS Snippet or Theme before setting up the custom statuses.
+---
 
 ## Using Statuses
 
@@ -164,12 +214,6 @@ For details, see [Filters for Task Statuses]({{ site.baseurl }}{% link queries/f
 {: .info }
 We envisage adding `status.symbol`.
 
-## Related pages
-
-- [How to set up your custom statuses]({{ site.baseurl }}{% link how-to/set-up-custom-statuses.md %}).
-- [How to style custom statuses]({{ site.baseurl }}{% link how-to/style-custom-statuses.md %}).
-- [Status Collections]({{ site.baseurl }}{% link reference/status-collections/index.md %}).
-
 ---
 
 ## Credit: Sytone and the 'Tasks SQL Powered' plugin

docs/getting-started/statuses/core-statuses.md

@@ -0,0 +1,62 @@
+---
+layout: default
+title: Core Statuses
+parent: Statuses
+grand_parent: Getting Started
+has_toc: false
+---
+
+# Core Statuses
+{: .no_toc }
+
+<details open markdown="block">
+  <summary>
+    Table of contents
+  </summary>
+  {: .text-delta }
+1. TOC
+{:toc}
+</details>
+
+---
+
+## Overview
+
+Core statuses represent conventional markdown tasks:
+
+```text
+- [ ] I am a task that is not yet done
+- [x] I am a task that has been done
+```
+
+They don't require any custom CSS styling or theming on order to display correctly in Tasks blocks or Live Preview.
+
+## Core Statuses in Settings
+
+This is what the Core Statuses look like initially in Tasks' settings:
+
+![Core Statuses](../../images/settings-core-statuses.png)
+
+Note that `Todo` is followed by `Done`, in order to preserve compatibility with earlier Tasks releases.
+
+{: .info }
+You can edit the 'Todo' core status to make its Next Status Symbol be `/` and enable `Todo` -> `In Progress` -> `Done`, if you prefer.
+
+## Editing core statuses
+
+The only restriction on editing core statuses is that you cannot change their Status Symbols.
+
+You are free to rename them, change their next character, and even change their Status Type, should you wish.
+
+## Details
+
+And this is how you can use them:
+
+<!-- placeholder to force blank line before included text --> <!-- include: DocsSamplesForStatuses.test.DefaultStatuses_core-statuses.approved.md -->
+
+| Status Symbol | Next Status Symbol | Status Name<br>`status.name includes...`<br>`sort by status.name`<br>`group by status.name` | Status Type<br>`status.type is...`<br>`sort by status.type`<br>`group by status.type` | Needs Custom Styling |
+| ----- | ----- | ----- | ----- | ----- |
+| `space` | `x` | Todo | `TODO` | No |
+| `x` | `space` | Done | `DONE` | No |
+
+<!-- placeholder to force blank line after included text --> <!-- endInclude -->