Merge pull request #3425 from obsidian-tasks-group/refactor-remove-scheduled-dates

refactor: Small refinements to drop/remove scheduled dates setting

Author: claremacrae

.gitignore

@@ -49,5 +49,8 @@ yarn-error.log
 # Backup files.
 *.bak
 
+# Internationalisation
+/src/i18n/locales/*_old.json
+
 # VS code config
 .vscode/

docs/Getting Started/Dates.md

@@ -59,10 +59,10 @@ Scheduled dates use an hourglass emoji: ⏳.
 - [ ] take out the trash ⏳ 2021-04-09
 ```
 
-See [[Use Filename as Default Date]] for how to optionally make Tasks use any dates in file names as the scheduled date for all undated tasks in that file.
+See also:
 
-> [!released]
-'Use Filename as Default Date' was introduced in Tasks 1.18.0.
+- [[Use Filename as Default Date]] for how to optionally make Tasks use any dates in file names as the scheduled date for all undated tasks in that file.
+- [[Recurring Tasks#Remove scheduled date on recurrence|Remove scheduled date on recurrence]] for controlling whether new recurring tasks are automatically scheduled.
 
 Related instructions for use in Tasks query blocks:
 

docs/Getting Started/Recurring Tasks.md

@@ -46,6 +46,8 @@ Alternatively, if you have enabled addition of [[Dates#Created date|created date
 - [x] take out the trash 🔁 every Sunday 📅 2021-04-25 ✅ 2023-03-10
 ```
 
+## Recurrence Settings
+
 ### Order of the new task
 
 Use this setting to control where the recurring task is inserted. The default is to put the new task before the original one.
@@ -55,11 +57,18 @@ Use this setting to control where the recurring task is inserted. The default is
 > [!released]
 > Control of the location (or order) of the new task was introduced in Tasks 3.8.0
 
-### Drop scheduled dates
+### Remove scheduled date on recurrence
+
+Use this setting to control whether the Scheduled date should be removed from the next occurrence. The Scheduled date is only removed the task also has a Start or Due date.
+
+This is useful when you want the Start and Due dates to carry forward to the next recurrence, but you will set the Scheduled date in future, once you know when you intend to work on it.
 
-Use this setting to control whether the scheduled date should be removed from the next occurrence. The scheduled date is only removed the task also has another date.
+![Setting for Remove scheduled date on recurrence](../images/settings-recurrence-remove-scheduled-date.png)
+
+> [!released]
+> The option to remove the scheduled date on recurrence was introduced in Tasks X.Y.Z.
 
-### Recurring Tasks with Custom Statuses
+## Recurring Tasks with Custom Statuses
 
 > [!Warning]
 > If you use [[Custom Statuses]], please see [[Recurring Tasks and Custom Statuses]] for important information about how these two facilities interact.

docs/Getting Started/Settings.md

@@ -27,6 +27,6 @@ For convenience, here is a list of all those documentation pages (in the order t
 - [[Status Settings#Overview|Status Settings]]
 - [[Dates#Date-tracking settings|Dates]]
 - [[Use Filename as Default Date#Settings|Use Filename as Default Date]]
-- [[Recurring Tasks#Order of the new task|Recurring Tasks]]
+- [[Recurring Tasks#Recurrence Settings|Recurring Tasks]]
 - [[Auto-Suggest#Settings|Auto-Suggest]]
 - [[Create or edit Task#Turning off keyboard shortcuts|Create or edit Task modal]]

docs/images/settings-recurrence-remove-scheduled-date.png

@@ -19,7 +19,7 @@ module.exports = {
     useKeysAsDefaultValue: true, // Use keys for default values if no translation exists
     resetDefaultValueLocale: null, // Retain existing default values
     sort: true, // Sort keys alphabetically
-    keepRemoved: true, // Keep keys not found in source files
+    keepRemoved: false, // Keep keys not found in source files. Removed values are written to *_old.json files
     jsonIndent: 2, // Pretty-print JSON
     lexers: {
         ts: ['JavascriptLexer'], // TypeScript files

i18next-parser.config.js

@@ -76,7 +76,7 @@ export interface Settings {
     filenameAsScheduledDateFormat: string;
     filenameAsDateFolders: string[];
     recurrenceOnNextLine: boolean;
-    dropScheduledDateOnRecurrence: boolean;
+    removeScheduledDateOnRecurrence: boolean;
 
     // The custom status states.
     statusSettings: StatusSettings;
@@ -111,7 +111,7 @@ const defaultSettings: Settings = {
     filenameAsScheduledDateFormat: '',
     filenameAsDateFolders: [],
     recurrenceOnNextLine: false,
-    dropScheduledDateOnRecurrence: false,
+    removeScheduledDateOnRecurrence: false,
     statusSettings: new StatusSettings(),
     features: Feature.settingsFlags,
     generalSettings: {

src/Config/Settings.ts

@@ -377,18 +377,20 @@ export class SettingsTab extends PluginSettingTab {
             });
 
         new Setting(containerEl)
-            .setName(i18n.t('settings.recurringTasks.dropScheduledDate.name'))
+            .setName(i18n.t('settings.recurringTasks.removeScheduledDate.name'))
             .setDesc(
                 SettingsTab.createFragmentWithHTML(
-                    i18n.t('settings.recurringTasks.dropScheduledDate.description') +
+                    i18n.t('settings.recurringTasks.removeScheduledDate.description.line1') +
+                        '</br>' +
+                        i18n.t('settings.recurringTasks.removeScheduledDate.description.line2') +
                         '</br>' +
                         this.seeTheDocumentation('https://publish.obsidian.md/tasks/Getting+Started/Recurring+Tasks'),
                 ),
             )
             .addToggle((toggle) => {
-                const { dropScheduledDateOnRecurrence } = getSettings();
-                toggle.setValue(dropScheduledDateOnRecurrence).onChange(async (value) => {
-                    updateSettings({ dropScheduledDateOnRecurrence: value });
+                const { removeScheduledDateOnRecurrence } = getSettings();
+                toggle.setValue(removeScheduledDateOnRecurrence).onChange(async (value) => {
+                    updateSettings({ removeScheduledDateOnRecurrence: value });
                     await this.plugin.saveSettings();
                 });
             });

src/Config/SettingsTab.ts

@@ -87,9 +87,9 @@ export class Occurrence {
      * If the occurrence has no reference date, an empty {@link Occurrence} will be returned.
      *
      * @param nextReferenceDate
-     * @param dropScheduledDate - Optional boolean to drop the scheduled date from the next occurrence so long as a start or due date exists.
+     * @param removeScheduledDate - Optional boolean to remove the scheduled date from the next occurrence so long as a start or due date exists.
      */
-    public next(nextReferenceDate: Date, dropScheduledDate: boolean = false): Occurrence {
+    public next(nextReferenceDate: Date, removeScheduledDate: boolean = false): Occurrence {
         // Only if a reference date is given. A reference date will exist if at
         // least one of the other dates is set.
         if (this.referenceDate === null) {
@@ -102,11 +102,11 @@ export class Occurrence {
 
         const hasStartDate = this.startDate !== null;
         const hasDueDate = this.dueDate !== null;
-        const canDropScheduledDate = hasStartDate || hasDueDate;
-        const shouldDropScheduledDate = dropScheduledDate && canDropScheduledDate;
+        const canRemoveScheduledDate = hasStartDate || hasDueDate;
+        const shouldRemoveScheduledDate = removeScheduledDate && canRemoveScheduledDate;
 
         const startDate = this.nextOccurrenceDate(this.startDate, nextReferenceDate);
-        const scheduledDate = shouldDropScheduledDate
+        const scheduledDate = shouldRemoveScheduledDate
             ? null
             : this.nextOccurrenceDate(this.scheduledDate, nextReferenceDate);
         const dueDate = this.nextOccurrenceDate(this.dueDate, nextReferenceDate);

src/Task/Occurrence.ts

@@ -72,16 +72,16 @@ export class Recurrence {
      * Returns the dates of the next occurrence or null if there is no next occurrence.
      *
      * @param today - Optional date representing the completion date. Defaults to today.
-     * @param dropScheduledDate - Optional boolean to drop the scheduled date from the next occurrence so long as a start or due date exists.
+     * @param removeScheduledDate - Optional boolean to remove the scheduled date from the next occurrence so long as a start or due date exists.
      */
-    public next(today = window.moment(), dropScheduledDate: boolean = false): Occurrence | null {
+    public next(today = window.moment(), removeScheduledDate: boolean = false): Occurrence | null {
         const nextReferenceDate = this.nextReferenceDate(today);
 
         if (nextReferenceDate === null) {
             return null;
         }
 
-        return this.occurrence.next(nextReferenceDate, dropScheduledDate);
+        return this.occurrence.next(nextReferenceDate, removeScheduledDate);
     }
 
     public identicalTo(other: Recurrence) {

src/Task/Recurrence.ts

@@ -377,8 +377,8 @@ export class Task extends ListItem {
             return [toggledTask];
         }
 
-        const { dropScheduledDateOnRecurrence } = getSettings();
-        const nextOccurrence = this.recurrence.next(today, dropScheduledDateOnRecurrence);
+        const { removeScheduledDateOnRecurrence } = getSettings();
+        const nextOccurrence = this.recurrence.next(today, removeScheduledDateOnRecurrence);
         if (nextOccurrence === null) {
             return [toggledTask];
         }

src/Task/Task.ts

@@ -180,6 +180,13 @@
       "nextLine": {
         "description": "Уключэнне гэтага зробіць наступнае паўтарэнне задачы на радку ніжэй за завершаную задачу. У адваротным выпадку наступнае паўтарэнне з'явіцца перад завершанай задачай.",
         "name": "Наступнае паўтарэнне з'яўляецца на радку ніжэй"
+      },
+      "removeScheduledDate": {
+        "description": {
+          "line1": "",
+          "line2": ""
+        },
+        "name": ""
       }
     },
     "seeTheDocumentation": "Глядзіце дакументацыю",

src/i18n/locales/be.json

@@ -181,9 +181,12 @@
         "description": "Enabling this will make the next recurrence of a task appear on the line below the completed task. Otherwise the next recurrence will appear before the completed one.",
         "name": "Next recurrence appears on the line below"
       },
-      "dropScheduledDate": {
-        "description": "Enabling this will make the next recurrence of a task have no scheduled date, unless the scheduled date is the only date the task has.",
-        "name": "Drop scheduled date (only if Start or Due is present)"
+      "removeScheduledDate": {
+        "description": {
+          "line1": "Enabling this will make the next recurrence of a task have no Scheduled (⏳) date, when at least one of Start (🛫) or Due (📅) dates is present.",
+          "line2": "This is for when you want the Start and Due dates to carry forward to the next recurrence, but you will set the Scheduled date in future, once you plan to work on it."
+        },
+        "name": "Remove scheduled date on recurrence"
       }
     },
     "seeTheDocumentation": "See the documentation",

src/i18n/locales/en.json

@@ -180,6 +180,13 @@
       "nextLine": {
         "description": "Включение этой опции приведет к тому, что следующее повторение задачи появится на строке ниже завершенной задачи. В противном случае следующее повторение появится перед завершенной.",
         "name": "Следующее повторение появляется на строке ниже"
+      },
+      "removeScheduledDate": {
+        "description": {
+          "line1": "",
+          "line2": ""
+        },
+        "name": ""
       }
     },
     "seeTheDocumentation": "Смотрите документацию",

src/i18n/locales/ru.json

@@ -180,6 +180,13 @@
       "nextLine": {
         "description": "Увімкнення цього параметра змусить наступне повторення задачі з’являтися на рядку нижче завершеної задачі. Інакше наступне повторення з’явиться перед завершеною.",
         "name": "Наступне повторення з’являється на рядку нижче"
+      },
+      "removeScheduledDate": {
+        "description": {
+          "line1": "",
+          "line2": ""
+        },
+        "name": ""
       }
     },
     "seeTheDocumentation": "Переглянути документацію",

src/i18n/locales/uk.json

@@ -180,6 +180,13 @@
       "nextLine": {
         "description": "启用此功能后，任务的下一次重复将显示在已完成任务的下一行。若关闭此功能，则下一次重复将出现在已完成任务的上一行。",
         "name": "把任务的下一次重复放在下一行"
+      },
+      "removeScheduledDate": {
+        "description": {
+          "line1": "",
+          "line2": ""
+        },
+        "name": ""
       }
     },
     "seeTheDocumentation": "参阅文档",

src/i18n/locales/zh_cn.json

@@ -229,8 +229,8 @@ describe('identicalTo', () => {
     });
 });
 
-describe('Recurrence - with dropScheduledDateOnRecurrence', () => {
-    it('drops the scheduledDate when dropScheduledDate is true', () => {
+describe('Recurrence - with removeScheduledDateOnRecurrence', () => {
+    it('should remove the scheduledDate when removeScheduledDate is true', () => {
         // Arrange
         const recurrence = Recurrence.fromText({
             recurrenceRuleText: 'every month',
@@ -250,7 +250,7 @@ describe('Recurrence - with dropScheduledDateOnRecurrence', () => {
         expect(next!.dueDate).toEqualMoment(moment('2022-02-10'));
     });
 
-    it('does not drop the scheduledDate when it is the only date', () => {
+    it('should not remove the scheduledDate when it is the only date', () => {
         // Arrange
         const recurrence = Recurrence.fromText({
             recurrenceRuleText: 'every month',