Merge pull request #2879 from obsidian-tasks-group/finalise-auto-sugg…

…est-docs docs: Finalise the documentation for Auto-Suggest supporting dependencies
obsidian-tasks-group · Jun 3, 2024 · 60ce234 · 60ce234
2 parents b1c1dab + 2383c92
commit 60ce234
Show file tree

Hide file tree

Showing 10 changed files with 97 additions and 72 deletions.
diff --git a/docs/Editing/Auto-Suggest.md b/docs/Editing/Auto-Suggest.md
@@ -19,7 +19,9 @@ lot of the typing of emojis and dates for you.
 It is particularly powerful when creating and editing tasks on mobile phones.
 
 > [!released]
-`➕ created today` was introduced in Tasks 3.2.0.
+>
+> - `➕ created today` was introduced in Tasks 3.2.0.
+> - `🆔 id`  and `⛔ depends on id` were introduced in Tasks X.Y.Z.
 
 ### Video Demo
 
@@ -88,6 +90,17 @@ The menu is smart: it will only offer valid options:
 - When the `⏎` item is shown at the top of the menu, it is given as a default option to enter a new line instead of choosing a suggestion. It is only shown when there is no concrete match.
 - There are many more recognized options than are showing in the menus, including many more dates, such as `2 months`, `15 days`.
 
+Since Tasks X.Y.Z, the menu supports easy creation of [[Task Dependencies]].
+
+- Type `id` to filter show the options for dependencies.
+- `⛔ depends on id` searches the descriptions of all not-done tasks.
+  - Select a task from the menu to add a dependency, and automatically add an `id` value the selected task, if need be.
+  - Having added a dependency, such as `⛔ dcf64c`, you can type a comma (`,`) to add another dependency - as many times as you wish.
+- `🆔 id` allows you to add an `id` to a task.
+  - You can accept its offer to `generate unique id`.
+  - Or you can type your own more meaningful `id` if you wish, such as `🆔 suggester-update-docs`.
+  - Be sure to stick to the allowed [[Task Dependencies#`id`|allowed `id` characters]], and do not create duplicate `id` values.
+
 The auto-suggest menu supports powerful keyboard control:
 
 - Example: type some fraction of the word `start` and you will get a suggestion to turn it into the start emoji. Pressing `<enter>` then immediately adds the start emoji: 🛫.
@@ -188,8 +201,19 @@ Similarly, you can type some fraction of the word `start` (of whatever length is
 <!-- include: Suggestor.test.auto-complete_with__emoji__symbols_show_all_suggested_text.approved.md -->
 | Searchable Text | Text that is added |
 | ----- | ----- |
-| 🆔 Task ID | 🆔 |
-| ⛔ Task depends on ID | ⛔ |
+| ⏎ | &lt;new line> |
+| 📅 due date | 📅  |
+| 🛫 start date | 🛫  |
+| ⏳ scheduled date | ⏳  |
+| 🆔 id | 🆔 |
+| ⛔ depends on id | ⛔ |
+| ⏫ high priority | ⏫  |
+| 🔼 medium priority | 🔼  |
+| 🔽 low priority | 🔽  |
+| 🔺 highest priority | 🔺  |
+| ⏬ lowest priority | ⏬  |
+| 🔁 recurring (repeat) | 🔁  |
+| ➕ created today (2022-07-11) | ➕ 2022-07-11  |
 | every | 🔁 every  |
 | every day | 🔁 every day  |
 | every week | 🔁 every week  |
@@ -203,15 +227,6 @@ Similarly, you can type some fraction of the word `start` (of whatever length is
 | every week on Thursday | 🔁 every week on Thursday  |
 | every week on Friday | 🔁 every week on Friday  |
 | every week on Saturday | 🔁 every week on Saturday  |
-| 📅 due date | 📅  |
-| 🛫 start date | 🛫  |
-| ⏳ scheduled date | ⏳  |
-| ⏫ high priority | ⏫  |
-| 🔼 medium priority | 🔼  |
-| 🔽 low priority | 🔽  |
-| 🔺 highest priority | 🔺  |
-| ⏬ lowest priority | ⏬  |
-| ➕ created today (2022-07-11) | ➕ 2022-07-11  |
 | today (2022-07-11) | 📅 2022-07-11  |
 | tomorrow (2022-07-12) | 📅 2022-07-12  |
 | Sunday (2022-07-17) | 📅 2022-07-17  |
@@ -224,7 +239,6 @@ Similarly, you can type some fraction of the word `start` (of whatever length is
 | next week (2022-07-18) | 📅 2022-07-18  |
 | next month (2022-08-11) | 📅 2022-08-11  |
 | next year (2023-07-11) | 📅 2023-07-11  |
-| 🔁 recurring (repeat) | 🔁  |
 | today (2022-07-11) | ⏳ 2022-07-11  |
 | tomorrow (2022-07-12) | ⏳ 2022-07-12  |
 | Sunday (2022-07-17) | ⏳ 2022-07-17  |
@@ -249,8 +263,7 @@ Similarly, you can type some fraction of the word `start` (of whatever length is
 | next week (2022-07-18) | 🛫 2022-07-18  |
 | next month (2022-08-11) | 🛫 2022-08-11  |
 | next year (2023-07-11) | 🛫 2023-07-11  |
-| Auto Generate Unique ID | 🆔 ****** |
-| ⏎ | &lt;new line> |
+| generate unique id | 🆔 ****** |
 <!-- endInclude -->
 
 ### How can I use auto-suggest features from other plugins together with the Tasks auto-suggest?
@@ -291,7 +304,3 @@ at least the specified number of characters to find a match.
 How many suggestions should be shown when an auto-suggest menu pops up (including the "⏎" option).
 
 The default is 6, and you can select any value from 3 to 12.
-
-## Current Limitations
-
-- The Auto-Suggest mechanism does not yet support [[task dependencies]]. We are tracking this in [issue #2681](https://github.com/obsidian-tasks-group/obsidian-tasks/issues/2681).
diff --git a/docs/Getting Started/Task Dependencies.md b/docs/Getting Started/Task Dependencies.md
@@ -107,7 +107,7 @@ The following are valid `dependsOn` values:
 
 Below is a worked example, walking through adding one dependency.
 
-For a more detailed explanation of how to add and edit dependencies between tasks, see [[Create or edit Task#Dependencies]].
+For more detailed explanations of how to add and edit dependencies between tasks, see [[Create or edit Task#Dependencies]] and [[Auto-Suggest#Details]].
 
 ### Worked example
 
@@ -120,6 +120,10 @@ To illustrate the concept of task dependencies, let's consider a scenario where
 
 In this scenario, testing with users can only occur after the initial draft is completed. To establish this relationship, you can create a dependency between the two tasks using either of the following methods.
 
+#### Option 1: Use the Edit Task Modal
+
+Using the [[Create or edit Task]] modal, you can:
+
 1. **Either:**
     - open the **'Build a first draft'** task in the Edit Task Modal
     - and specify **'Test with users'** in **After this**.
@@ -130,24 +134,38 @@ In this scenario, testing with users can only occur after the initial draft is c
 ![Making the 'Test with users' task depend on the 'Build a first draft'](../images/task-dependencies-blocked-by-example.png)
 <span class="caption">Making the **'Test with users'** task depend on the **'Build a first draft'** task.</span>
 
-<!--
-**Via the Auto Suggest Feature:**
+#### Option 2: Use the Auto-Suggest feature
+
+Using the [[Auto-Suggest]] feature, when in **Source mode** or **Live Preview** you can add the dependency without leaving the editor:
+
+> [!Tip]
+> This is an optional first step, if you want to control the `id` used:
+>
+> 1. Click at the end of the `Build a first draft`.
+> 1. Start typing `id` and select `🆔 id`.
+> 1. There are then two options:
+>     - You can select `generate unique id` to generate an ID automatically.
+>     - Or you can specify your own.
 
-1. (Optional) On the 'Build a frist draft' You can select the ID symbol via the Automatic suggestion dialog box. An ID can be generated automatically via Auto Suggestions. Or you can Specify your own.
-2. select the "Task depends on ID" icon in the "Test with users" task via the Automatic suggestion dialog box.
-3. start entering the task on which it should depend ("Create a first draft")
-4. Press the enter key. If no ID has been entered, an ID is generated for the task.
+To create the dependency:
+
+1. Click at the end of the `Test with users` line.
+1. Start typing `id` or `dep`, and select `⛔ depends on id`.
+1. Start typing the task on which it should depend (`Build a first draft`)
+1. Click on the `Build a first draft` task, to add the dependency.
+1. Press the enter key. If no ID has been entered, an ID is generated for the task.
 
 > [!info]
-> When selecting Task depends on ID:
+> When selecting `⛔ depends on id`:
 >
-> - To depend on multiple tasks, type a comma after the last id in an existing 'depends on' value, and select another task.
-> - it only searche/shows descriptions of not-done tasks.
+> - To depend on multiple tasks, type a comma after the last id in an existing `depends on` value, and select another task.
+> - It only searches/shows descriptions of not-done tasks.
 > - It initially filters to show tasks in the same file ('closer' to the Task), but if you type more text, it will search all non-done tasks in the vault.
-> - Circular Dependecy, should not be created
--->
+> - Do not create Circular Dependencies between tasks.
+
+#### The Result
 
-By implementing either of these methods, the task list is updated to reflect the dependency relationship:
+By implementing any of these methods, the task list is updated to reflect the dependency relationship:
 
 ```text
 - [ ] Build a first draft 🆔 4ijuhy

diff --git a/docs/Introduction.md b/docs/Introduction.md
@@ -13,6 +13,8 @@ _In recent [releases](https://github.com/obsidian-tasks-group/obsidian-tasks/rel
     Move the older ones down to the top of the comment block below...
 -->
 
+- X.Y.Z:
+  - [[Auto-Suggest#Details|Auto-suggest]] now supports [[Task Dependencies#Option 2 Use the Auto-Suggest feature|task dependencies]].
 - 7.3.0:
   - Add 'Remove date' option to the [[Postponing|postpone]] right-click menu in search results.
 - 7.2.0:

diff --git a/docs/Support and Help/Known Limitations.md b/docs/Support and Help/Known Limitations.md
@@ -55,10 +55,6 @@ This page gathers together all the documentation on known limitations of the plu
 
 ![[Create or edit Task#Known limitations]]
 
-## Editing Tasks: Auto-Suggest
-
-![[Auto-Suggest#Current Limitations]]
-
 ## Editing Tasks: Postponing
 
 ![[Postponing#Current Limitations]]

diff --git a/src/Suggestor/Suggestor.ts b/src/Suggestor/Suggestor.ts
@@ -152,13 +152,13 @@ function addTaskPropertySuggestions(
     if (globalThis.SHOW_DEPENDENCY_SUGGESTIONS) {
         if (!line.includes(symbols.idSymbol))
             genericSuggestions.push({
-                displayText: `${symbols.idSymbol} Task ID`,
+                displayText: `${symbols.idSymbol} id`,
                 appendText: `${symbols.idSymbol}`,
             });
 
         if (!line.includes(symbols.dependsOnSymbol))
             genericSuggestions.push({
-                displayText: `${symbols.dependsOnSymbol} Task depends on ID`,
+                displayText: `${symbols.dependsOnSymbol} depends on id`,
                 appendText: `${symbols.dependsOnSymbol}`,
             });
     }
@@ -443,7 +443,7 @@ function addIDSuggestion(line: string, cursorPos: number, idSymbol: string, allT
         const ID = generateUniqueId(allTasks.map((task) => task.id));
         results.push({
             suggestionType: 'match',
-            displayText: 'Auto Generate Unique ID',
+            displayText: 'generate unique id',
             appendText: `${idSymbol} ${ID}`,
             insertAt: idMatch.index,
             insertSkip: idSymbol.length,

diff --git a/...e_with__dataview__symbols_offers_basic_completion_options_for_an_empty_task.approved.json b/...e_with__dataview__symbols_offers_basic_completion_options_for_an_empty_task.approved.json
@@ -12,11 +12,11 @@
     "appendText": "scheduled:: "
   },
   {
-    "displayText": "id:: Task ID",
+    "displayText": "id:: id",
     "appendText": "id::"
   },
   {
-    "displayText": "dependsOn:: Task depends on ID",
+    "displayText": "dependsOn:: depends on id",
     "appendText": "dependsOn::"
   },
   {

diff --git a/....test.auto-complete_with__dataview__symbols_show_all_suggested_text.approved.md b/....test.auto-complete_with__dataview__symbols_show_all_suggested_text.approved.md
@@ -1,7 +1,17 @@
 | Searchable Text | Text that is added |
 | ----- | ----- |
-| id:: Task ID | id:: |
-| dependsOn:: Task depends on ID | dependsOn:: |
+| due:: due date | due::  |
+| start:: start date | start::  |
+| scheduled:: scheduled date | scheduled::  |
+| id:: id | id:: |
+| dependsOn:: depends on id | dependsOn:: |
+| priority:: high priority | priority:: high]  |
+| priority:: medium priority | priority:: medium]  |
+| priority:: low priority | priority:: low]  |
+| priority:: highest priority | priority:: highest]  |
+| priority:: lowest priority | priority:: lowest]  |
+| repeat:: recurring (repeat) | repeat::  |
+| created:: created today (2022-07-11) | created:: 2022-07-11]  |
 | every | repeat:: every  |
 | every day | repeat:: every day  |
 | every week | repeat:: every week  |
@@ -15,15 +25,6 @@
 | every week on Thursday | repeat:: every week on Thursday  |
 | every week on Friday | repeat:: every week on Friday  |
 | every week on Saturday | repeat:: every week on Saturday  |
-| due:: due date | due::  |
-| start:: start date | start::  |
-| scheduled:: scheduled date | scheduled::  |
-| priority:: high priority | priority:: high]  |
-| priority:: medium priority | priority:: medium]  |
-| priority:: low priority | priority:: low]  |
-| priority:: highest priority | priority:: highest]  |
-| priority:: lowest priority | priority:: lowest]  |
-| created:: created today (2022-07-11) | created:: 2022-07-11]  |
 | today (2022-07-11) | due:: 2022-07-11]  |
 | tomorrow (2022-07-12) | due:: 2022-07-12]  |
 | Sunday (2022-07-17) | due:: 2022-07-17]  |
@@ -36,7 +37,6 @@
 | next week (2022-07-18) | due:: 2022-07-18]  |
 | next month (2022-08-11) | due:: 2022-08-11]  |
 | next year (2023-07-11) | due:: 2023-07-11]  |
-| repeat:: recurring (repeat) | repeat::  |
 | today (2022-07-11) | scheduled:: 2022-07-11]  |
 | tomorrow (2022-07-12) | scheduled:: 2022-07-12]  |
 | Sunday (2022-07-17) | scheduled:: 2022-07-17]  |
@@ -61,4 +61,4 @@
 | next week (2022-07-18) | start:: 2022-07-18]  |
 | next month (2022-08-11) | start:: 2022-08-11]  |
 | next year (2023-07-11) | start:: 2023-07-11]  |
-| Auto Generate Unique ID | id:: ****** |
+| generate unique id | id:: ****** |
diff --git a/...lete_with__emoji__symbols_offers_basic_completion_options_for_an_empty_task.approved.json b/...lete_with__emoji__symbols_offers_basic_completion_options_for_an_empty_task.approved.json
@@ -17,11 +17,11 @@
     "appendText": "⏳ "
   },
   {
-    "displayText": "🆔 Task ID",
+    "displayText": "🆔 id",
     "appendText": "🆔"
   },
   {
-    "displayText": "⛔ Task depends on ID",
+    "displayText": "⛔ depends on id",
     "appendText": "⛔"
   }
 ]
diff --git a/...tor.test.auto-complete_with__emoji__symbols_show_all_suggested_text.approved.md b/...tor.test.auto-complete_with__emoji__symbols_show_all_suggested_text.approved.md
@@ -1,7 +1,18 @@
 | Searchable Text | Text that is added |
 | ----- | ----- |
-| 🆔 Task ID | 🆔 |
-| ⛔ Task depends on ID | ⛔ |
+| ⏎ | &lt;new line> |
+| 📅 due date | 📅  |
+| 🛫 start date | 🛫  |
+| ⏳ scheduled date | ⏳  |
+| 🆔 id | 🆔 |
+| ⛔ depends on id | ⛔ |
+| ⏫ high priority | ⏫  |
+| 🔼 medium priority | 🔼  |
+| 🔽 low priority | 🔽  |
+| 🔺 highest priority | 🔺  |
+| ⏬ lowest priority | ⏬  |
+| 🔁 recurring (repeat) | 🔁  |
+| ➕ created today (2022-07-11) | ➕ 2022-07-11  |
 | every | 🔁 every  |
 | every day | 🔁 every day  |
 | every week | 🔁 every week  |
@@ -15,15 +26,6 @@
 | every week on Thursday | 🔁 every week on Thursday  |
 | every week on Friday | 🔁 every week on Friday  |
 | every week on Saturday | 🔁 every week on Saturday  |
-| 📅 due date | 📅  |
-| 🛫 start date | 🛫  |
-| ⏳ scheduled date | ⏳  |
-| ⏫ high priority | ⏫  |
-| 🔼 medium priority | 🔼  |
-| 🔽 low priority | 🔽  |
-| 🔺 highest priority | 🔺  |
-| ⏬ lowest priority | ⏬  |
-| ➕ created today (2022-07-11) | ➕ 2022-07-11  |
 | today (2022-07-11) | 📅 2022-07-11  |
 | tomorrow (2022-07-12) | 📅 2022-07-12  |
 | Sunday (2022-07-17) | 📅 2022-07-17  |
@@ -36,7 +38,6 @@
 | next week (2022-07-18) | 📅 2022-07-18  |
 | next month (2022-08-11) | 📅 2022-08-11  |
 | next year (2023-07-11) | 📅 2023-07-11  |
-| 🔁 recurring (repeat) | 🔁  |
 | today (2022-07-11) | ⏳ 2022-07-11  |
 | tomorrow (2022-07-12) | ⏳ 2022-07-12  |
 | Sunday (2022-07-17) | ⏳ 2022-07-17  |
@@ -61,5 +62,4 @@
 | next week (2022-07-18) | 🛫 2022-07-18  |
 | next month (2022-08-11) | 🛫 2022-08-11  |
 | next year (2023-07-11) | 🛫 2023-07-11  |
-| Auto Generate Unique ID | 🆔 ****** |
-| ⏎ | &lt;new line> |
+| generate unique id | 🆔 ****** |
diff --git a/tests/Suggestor/Suggestor.test.ts b/tests/Suggestor/Suggestor.test.ts
@@ -266,12 +266,12 @@ describe.each([
     describe('suggestions for dependency field ID', () => {
         it('should offer "id" then "depends on" if user typed "id"', () => {
             const line = '- [ ] some task id';
-            shouldStartWithSuggestionsEqualling(line, [`${idSymbol} Task ID`, `${dependsOnSymbol} Task depends on ID`]);
+            shouldStartWithSuggestionsEqualling(line, [`${idSymbol} id`, `${dependsOnSymbol} depends on id`]);
         });
 
         it('should offer to generate unique id if the id symbol is already present', () => {
             const line = `- [ ] some task ${idSymbol}`;
-            shouldStartWithSuggestionsEqualling(line, ['Auto Generate Unique ID']);
+            shouldStartWithSuggestionsEqualling(line, ['generate unique id']);
         });
 
         it('should offer to generate unique id if the id symbol is already present', () => {
-Original file line number
+Diff line change
@@ Expand Up @@
         Move the older ones down to the top of the comment block below...
     -->
+    - X.Y.Z:
+      - [[Auto-Suggest#Details|Auto-suggest]] now supports [[Task Dependencies#Option 2 Use the Auto-Suggest feature|task dependencies]].
     - 7.3.0:
       - Add 'Remove date' option to the [[Postponing|postpone]] right-click menu in search results.
     - 7.2.0:
@@ Expand Down @@