From d6881c39c91beabdc0bfb29d6dc8a81202a84e40 Mon Sep 17 00:00:00 2001 Message-Id: From: Ihor Radchenko Date: Thu, 23 Mar 2023 12:20:19 +0100 Subject: [PATCH] org-agenda: Rename sorting "priority" to "urgency" * lisp/org-habit.el (org-habit-get-priority): Rename to `org-habit-get-urgency'. * lisp/org-compat.el (org-habit-get-priority): Obsolete the old name. * lisp/org-agenda.el (org-agenda-sorting-strategy): * lisp/org-agenda.el (org-search-view): (org-agenda-get-todos): (org-agenda-get-timestamps): (org-agenda-get-progress): (org-agenda-get-deadlines): (org-agenda-get-scheduled): (org-agenda-get-blocks): (org-entries-lessp): Alter priority-up and priority-down sorting strategies to only sort by actual priority. Rename the previous composite sorting rank to urgency, corresponding to the new urgency-up and urgency-down sorting strategies. Store the new rank in 'urgency text property. Update the docstrings accordingly. Use `urgency-down' in place of `priority-down' in the default sorting strategy. (org-set-sorting-strategy): Use `urgency-down' in place of `priority-down'. * etc/ORG-NEWS ("Priority" used to sort items in agenda is renamed to "urgency"): Document the change. * doc/org-manual.org (Sorting of agenda items): Update manual using "urgency" term in place of confusing "priority". Thanks to Samuel Wales for the idea how to fix the inconsistency. Reported-by: Jonas Olofsson Link: https://orgmode.org/list/26396316-1201-4D88-9D81-C87DDDA8885A@apple.com --- doc/org-manual.org | 16 +++++------ etc/ORG-NEWS | 15 ++++++++++ lisp/org-agenda.el | 72 +++++++++++++++++++++++++++++----------------- lisp/org-compat.el | 2 ++ lisp/org-habit.el | 4 +-- 5 files changed, 73 insertions(+), 36 deletions(-) diff --git a/doc/org-manual.org b/doc/org-manual.org index 37fd3df14..ff06694a8 100644 --- a/doc/org-manual.org +++ b/doc/org-manual.org @@ -9419,16 +9419,16 @@ *** Sorting of agenda items time-of-day specification. These entries are shown at the beginning of the list, as a /schedule/ for the day. After that, items remain grouped in categories, in the sequence given by ~org-agenda-files~. - Within each category, items are sorted by priority (see - [[*Priorities]]), which is composed of the base priority (2000 for - priority =A=, 1000 for =B=, and 0 for =C=), plus additional - increments for overdue scheduled or deadline items. + Within each category, items are sorted by urgency, which is composed + of the base priority (see [[*Priorities]]; 2000 for priority =A=, 1000 + for =B=, and 0 for =C=), plus additional increments for overdue + scheduled or deadline items. - For the TODO list, items remain in the order of categories, but - within each category, sorting takes place according to priority (see - [[*Priorities]]). The priority used for sorting derives from the - priority cookie, with additions depending on how close an item is to - its due or scheduled date. + within each category, sorting takes place according to urgency. The + urgency used for sorting derives from the priority cookie, with + additions depending on how close an item is to its due or scheduled + date. - For tags matches, items are not sorted at all, but just appear in the sequence in which they are found in the agenda files. diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS index 4ca13af17..2b055a76a 100644 --- a/etc/ORG-NEWS +++ b/etc/ORG-NEWS @@ -13,6 +13,21 @@ Please send Org bug reports to mailto:emacs-orgmode@gnu.org. * Version 9.7 (not released yet) ** Important announcements and breaking changes +*** "Priority" used to sort items in agenda is renamed to "urgency" + +Previously, ~priority-up~ and ~priority-down~ in +~org-agenda-sorting-strategy~ used a composite rank depending on +item's priority (=[#A]=, =[#B]=, =[#C]=, etc) and overdue time to +order agenda items (see "11.4.3 Sorting of agenda items" section of +Org manual). + +Now, this composite rank is renamed to =urgency= and the relevant +sorting strategies are renamed to ~urgency-up~ and ~urgency-down~. +~priority-up~ and ~priority-down~ sort by item's priority only. + +Users relying on the previous composite ranking should adjust their +agenda sorting settings. + *** =python-mode.el (MELPA)= support in =ob-python.el= is removed =python-mode.el= support has been removed from =ob-python.el=. The diff --git a/lisp/org-agenda.el b/lisp/org-agenda.el index 892d88a77..263f242d4 100644 --- a/lisp/org-agenda.el +++ b/lisp/org-agenda.el @@ -85,7 +85,7 @@ (declare-function org-habit-insert-consistency-graphs "org-habit" (&optional line)) (declare-function org-is-habit-p "org-habit" (&optional pom)) (declare-function org-habit-parse-todo "org-habit" (&optional pom)) -(declare-function org-habit-get-priority "org-habit" (habit &optional moment)) +(declare-function org-habit-get-urgency "org-habit" (habit &optional moment)) (declare-function org-agenda-columns "org-colview" ()) (declare-function org-add-archive-files "org-archive" (files)) (declare-function org-capture "org-capture" (&optional goto keys)) @@ -267,6 +267,7 @@ (defconst org-sorting-choice (const category-keep) (const category-up) (const category-down) (const tag-down) (const tag-up) (const priority-up) (const priority-down) + (const urgency-up) (const urgency-down) (const todo-state-up) (const todo-state-down) (const effort-up) (const effort-down) (const habit-up) (const habit-down) @@ -1617,9 +1618,9 @@ (defgroup org-agenda-sorting nil :group 'org-agenda) (defcustom org-agenda-sorting-strategy - '((agenda habit-down time-up priority-down category-keep) - (todo priority-down category-keep) - (tags priority-down category-keep) + '((agenda habit-down time-up urgency-down category-keep) + (todo urgency-down category-keep) + (tags urgency-down category-keep) (search category-keep)) "Sorting structure for the agenda items of a single day. This is a list of symbols which will be used in sequence to determine @@ -1646,6 +1647,12 @@ (defcustom org-agenda-sorting-strategy tag-down Sort alphabetically by last tag, Z-A. priority-up Sort numerically by priority, high priority last. priority-down Sort numerically by priority, high priority first. +urgency-up Sort numerically by urgency, high urgency last. + Urgency is calculated based on item's priority, + and proximity to scheduled time and deadline. See + info node `(org)Sorting of agenda items' for + details. +urgency-down Sort numerically by urgency, high urgency first. todo-state-up Sort by todo state, tasks that are done last. todo-state-down Sort by todo state, tasks that are done first. effort-up Sort numerically by estimated effort, high effort last. @@ -4884,6 +4891,7 @@ (defun org-search-view (&optional todo-only string edit-at) 'org-todo-regexp org-todo-regexp 'level level 'org-complex-heading-regexp org-complex-heading-regexp + 'urgency 1000 'priority 1000 'type "search") (push txt ee) @@ -5640,7 +5648,7 @@ (defun org-agenda-get-todos () "\\|") "\\)")) (t org-not-done-regexp)))) - marker priority category level tags todo-state + marker priority urgency category level tags todo-state ts-date ts-date-type ts-date-pair ee txt beg end inherited-tags todo-state-end-pos effort effort-minutes) @@ -5678,15 +5686,18 @@ (defun org-agenda-get-todos () (memq 'todo org-agenda-use-tag-inheritance)))) tags (org-get-tags nil (not inherited-tags)) level (make-string (org-reduced-level (org-outline-level)) ? ) - txt (org-agenda-format-item "" - (org-add-props txt nil - 'effort effort - 'effort-minutes effort-minutes) - level category tags t) - priority (1+ (org-get-priority txt))) + txt (org-agenda-format-item + "" + (org-add-props txt nil + 'effort effort + 'effort-minutes effort-minutes) + level category tags t) + urgency (1+ (org-get-priority txt)) + priority (org-get-priority txt)) (org-add-props txt props 'org-marker marker 'org-hd-marker marker 'priority priority + 'urgency urgency 'effort effort 'effort-minutes effort-minutes 'level level 'ts-date ts-date @@ -5916,9 +5927,10 @@ (defun org-agenda-get-timestamps (&optional deadlines) 'effort-minutes effort-minutes) level category tags time-stamp org-ts-regexp habit?))) (org-add-props item props - 'priority (if habit? - (org-habit-get-priority (org-habit-parse-todo)) - (org-get-priority item)) + 'urgency (if habit? + (org-habit-get-urgency (org-habit-parse-todo)) + (org-get-priority item)) + 'priority (org-get-priority item) 'org-marker (org-agenda-new-marker pos) 'org-hd-marker (org-agenda-new-marker) 'date date @@ -6172,7 +6184,7 @@ (defun org-agenda-get-progress () (setq priority 100000) (org-add-props txt props 'org-marker marker 'org-hd-marker hdmarker 'face 'org-agenda-done - 'priority priority 'level level + 'urgency priority 'priority priority 'level level 'effort effort 'effort-minutes effort-minutes 'type type 'date date 'undone-face 'org-warning 'done-face 'org-agenda-done) @@ -6473,13 +6485,14 @@ (defun org-agenda-get-deadlines (&optional with-hour) 'level level 'effort effort 'effort-minutes effort-minutes 'ts-date deadline - 'priority - ;; Adjust priority to today reminders about deadlines. - ;; Overdue deadlines get the highest priority + 'urgency + ;; Adjust urgency to today reminders about deadlines. + ;; Overdue deadlines get the highest urgency ;; increase, then imminent deadlines and eventually ;; more distant deadlines. (let ((adjust (if today? (- diff) 0))) (+ adjust (org-get-priority item))) + 'priority (org-get-priority item) 'todo-state todo-state 'type (if upcoming? "upcoming-deadline" "deadline") 'date (if upcoming? date deadline) @@ -6615,13 +6628,14 @@ (defun org-agenda-get-deadlines (&optional with-hour) 'level level 'effort effort 'effort-minutes effort-minutes 'ts-date deadline - 'priority - ;; Adjust priority to today reminders about deadlines. - ;; Overdue deadlines get the highest priority + 'urgency + ;; Adjust urgency to today reminders about deadlines. + ;; Overdue deadlines get the highest urgency ;; increase, then imminent deadlines and eventually ;; more distant deadlines. (let ((adjust (if today? (- diff) 0))) (+ adjust (org-get-priority item))) + 'priority (org-get-priority item) 'todo-state todo-state 'type (if upcoming? "upcoming-deadline" "deadline") 'date (if upcoming? date deadline) @@ -6871,8 +6885,9 @@ (defun org-agenda-get-scheduled (&optional deadlines with-hour) 'warntime warntime 'level level 'effort effort 'effort-minutes effort-minutes - 'priority (if habitp (org-habit-get-priority habitp) - (+ 99 diff (org-get-priority item))) + 'urgency (if habitp (org-habit-get-urgency habitp) + (+ 99 diff (org-get-priority item))) + 'priority (org-get-priority item) 'org-habit-p habitp 'todo-state todo-state) (push item scheduled-items))))))) @@ -7056,8 +7071,9 @@ (defun org-agenda-get-scheduled (&optional deadlines with-hour) 'warntime warntime 'level level 'effort effort 'effort-minutes effort-minutes - 'priority (if habitp (org-habit-get-priority habitp) - (+ 99 diff (org-get-priority item))) + 'urgency (if habitp (org-habit-get-urgency habitp) + (+ 99 diff (org-get-priority item))) + 'priority (org-get-priority item) 'org-habit-p habitp 'todo-state todo-state) (push item scheduled-items))))))) @@ -7169,6 +7185,7 @@ (defun org-agenda-get-blocks () 'level level 'effort effort 'effort-minutes effort-minutes 'todo-state todo-state + 'urgency (org-get-priority txt) 'priority (org-get-priority txt)) (push txt ee)))) (goto-char pos))) @@ -7530,7 +7547,7 @@ (defun org-set-sorting-strategy (key) org-agenda-sorting-strategy (or (cdr (assq key org-agenda-sorting-strategy)) (cdr (assq 'agenda org-agenda-sorting-strategy)) - '(time-up category-keep priority-down))))) + '(time-up category-keep urgency-down))))) (defun org-get-time-of-day (s &optional string) "Check string S for a time of day. @@ -7877,6 +7894,9 @@ (defun org-entries-lessp (a b) (priority-up (and (org-em 'priority-up 'priority-down ss) (org-cmp-values a b 'priority))) (priority-down (if priority-up (- priority-up) nil)) + (urgency-up (and (org-em 'urgency-up 'urgency-down ss) + (org-cmp-values a b 'urgency))) + (urgency-down (if urgency-up (- urgency-up) nil)) (effort-up (and (org-em 'effort-up 'effort-down ss) (org-cmp-effort a b))) (effort-down (if effort-up (- effort-up) nil)) diff --git a/lisp/org-compat.el b/lisp/org-compat.el index c47a4e8c2..5620f038b 100644 --- a/lisp/org-compat.el +++ b/lisp/org-compat.el @@ -387,6 +387,8 @@ (define-obsolete-function-alias 'org-pop-to-buffer-same-window 'pop-to-buffer-sa (define-obsolete-function-alias 'org-string-match-p 'string-match-p "9.0") ;;;; Functions and variables from previous releases now obsolete. +(define-obsolete-function-alias 'org-habit-get-priority + 'org-habit-get-urgency "Org 9.7") (define-obsolete-function-alias 'org-timestamp-format 'org-format-timestamp "Org 9.6") (define-obsolete-variable-alias 'org-export-before-processing-hook diff --git a/lisp/org-habit.el b/lisp/org-habit.el index fb6a48b5f..ea935fe7c 100644 --- a/lisp/org-habit.el +++ b/lisp/org-habit.el @@ -263,8 +263,8 @@ (defsubst org-habit-done-dates (habit) (defsubst org-habit-repeat-type (habit) (nth 5 habit)) -(defsubst org-habit-get-priority (habit &optional moment) - "Determine the relative priority of a habit. +(defsubst org-habit-get-urgency (habit &optional moment) + "Determine the relative urgency of a habit. This must take into account not just urgency, but consistency as well." (let ((pri 1000) (now (if moment (time-to-days moment) (org-today))) -- 2.39.1