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) {