[PATCH] Add faces to improve contextuality of agenda views

[Protesilaos Stavrou <info@protesilaos.com>]

[-- Attachment #1: Type: text/plain, Size: 3148 bytes --]

Hello everyone!

The attached patch defines and implements a few new faces for the
agenda.  Quoting from the commit message:

    These new faces are designed to improve the ability of themes/users to
    control the presentation of agenda views.  They inherit from existing
    faces in order to remain backward-compatible.

    + The 'org-imminent-deadline' is useful to disambiguate generic
      warnings from deadlines.  For example, a warning could be rendered
      in a yellow colored text and have a bold weight, whereas a deadline
      might be red and styled with italics.

    + The 'org-agenda-structure-filter' applies to all tag/term filters
      in agenda views that search for keywords or patterns.  It is
      designed to inherit from 'org-agenda-structure' in addition to the
      'org-warning' face that was present before (and removes the
      generic 'warning' face from one place).  This offers the benefit
      of consistency, as, say, an increase in font height or a change in
      font family in 'org-agenda-structure' will propagate to the filter
      as well.  The whole header line thus looks part of a singular
      design.

    + The 'org-agenda-structure-secondary' complements the above for those
      same views where a description follows the header.  For instance, the
      tags view provides information to "Press N r" to filter by a
      numbered tag.  Themes/users may prefer to disambiguate this line
      from the header above it, such as by using a less intense color or by
      reducing its height relative to the 'org-agenda-structure'.

    + The 'org-agenda-date-weekend-today' provides the option to
      differentiate the current date on a weekend from the current date on
      weekdays.

Some more words about the motivation behind this patch, which are not
included in the commit message:

+ The 'org-warning' is a generic face that should always convey a clear
  warning sign.  It does that well.  Deadlines also got styled with this
  by default, which meant that they could not be toned down a bit, or
  otherwise tweaked to meet the requirements of the agenda, without
  compromising the intended purpose of a prominent warning.  Ultimately
  this is about choice: users/themes may not want to use intense styles
  for deadlines by default.

  - For some prior work on applying a bespoke face instead of
    'org-warning', refer to commit 7ebb2d562 in org.git.

+ The 'org-agenda-date-weekend-today' complements the existing faces for
  differentiating weekdays from weekends.  So the "current day" can now
  be adapted to this distinction, depending on the user's particular
  needs.

What do you think?  Is there something you would like to see done
differently?

I include Gustavo Barros in Cc, with whom we identified the potential
for these changes and who helped me think about their design and test
their implementation.  This is done for communication purposes: any
errors are exclusively my own.

I have already assigned copyright to the FSF and have made such
contributions before.

All the best,
Protesilaos or "Prot"

-- 
Protesilaos Stavrou
https://protesilaos.com

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Add-faces-to-improve-contextuality-of-agenda-views.patch --]
[-- Type: text/x-patch, Size: 8125 bytes --]

From b47af2b79c5ecfe0954dfd0bbe1bedd531b81417 Mon Sep 17 00:00:00 2001
Message-Id: <b47af2b79c5ecfe0954dfd0bbe1bedd531b81417.1622753459.git.info@protesilaos.com>
From: Protesilaos Stavrou <info@protesilaos.com>
Date: Wed, 2 Jun 2021 12:51:07 +0300
Subject: [PATCH] Add faces to improve contextuality of agenda views

* lisp/org-agenda.el (org-search-view)
(org-agenda-propertize-selected-todo-keywords, org-todo-list)
(org-tags-view): Implement new org-agenda-structure-filter and
org-agenda-structure-secondary faces.
(org-agenda-get-day-face): Add condition for rendering the current
date heading in org-agenda-date-weekend-today.

* lisp/org-faces.el (org-agenda-structure-secondary)
(org-agenda-date-weekend-today, org-agenda-structure-filter)
(org-imminent-deadline): Add new faces.
(org-agenda-deadline-faces): Use the 'org-imminent-deadline' for
current deadlines instead of the generic 'org-warning'.

-----

These new faces are designed to improve the ability of themes/users to
control the presentation of agenda views.  They inherit from existing
faces in order to remain backward-compatible.

+ The 'org-imminent-deadline' is useful to disambiguate generic
  warnings from deadlines.  For example, a warning could be rendered
  in a yellow colored text and have a bold weight, whereas a deadline
  might be red and styled with italics.

+ The 'org-agenda-structure-filter' applies to all tag/term filters in
  agenda views that search for keywords or patterns.  It is designed to
  inherit from 'org-agenda-structure' in addition to the 'org-warning'
  face that was present before (and removes the generic 'warning' face
  from one place).  This offers the benefit of consistency, as, say, an
  increase in font height or a change in font family in
  'org-agenda-structure' will propagate to the filter as well.  The
  whole header line thus looks part of a singular design.

+ The 'org-agenda-structure-secondary' complements the above for those
  same views where a description follows the header.  For instance, the
  tags view provides information to "Press N r" to filter by a
  numbered tag.  Themes/users may prefer to disambiguate this line
  from the header above it, such as by using a less intense color or by
  reducing its height relative to the 'org-agenda-structure'.

+ The 'org-agenda-date-weekend-today' provides the option to
  differentiate the current date on a weekend from the current date on
  weekdays.
---
 lisp/org-agenda.el | 17 ++++++++++-------
 lisp/org-faces.el  | 21 ++++++++++++++++++++-
 2 files changed, 30 insertions(+), 8 deletions(-)

diff --git a/lisp/org-agenda.el b/lisp/org-agenda.el
index f49a24f88..97f0bab85 100644
--- a/lisp/org-agenda.el
+++ b/lisp/org-agenda.el
@@ -4264,6 +4264,9 @@ (defun org-agenda-get-day-face (date)
   "Return the face DATE should be displayed with."
   (cond ((and (functionp org-agenda-day-face-function)
 	      (funcall org-agenda-day-face-function date)))
+	((and (org-agenda-today-p date)
+              (memq (calendar-day-of-week date) org-agenda-weekend-days))
+         'org-agenda-date-weekend-today)
 	((org-agenda-today-p date) 'org-agenda-date-today)
 	((memq (calendar-day-of-week date) org-agenda-weekend-days)
 	 'org-agenda-date-weekend)
@@ -4802,7 +4805,7 @@ (defun org-search-view (&optional todo-only string edit-at)
 			       (list 'face 'org-agenda-structure))
 	  (setq pos (point))
 	  (insert string "\n")
-	  (add-text-properties pos (1- (point)) (list 'face 'org-warning))
+	  (add-text-properties pos (1- (point)) (list 'face 'org-agenda-structure-filter))
 	  (setq pos (point))
 	  (unless org-agenda-multi
 	    (insert (substitute-command-keys "\\<org-agenda-mode-map>\
@@ -4812,7 +4815,7 @@ (defun org-search-view (&optional todo-only string edit-at)
 `\\[org-agenda-manipulate-query-subtract-re]' to add/sub regexp, \
 `\\[universal-argument] \\[org-agenda-redo]' for a fresh search\n"))
 	    (add-text-properties pos (1- (point))
-				 (list 'face 'org-agenda-structure)))
+				 (list 'face 'org-agenda-structure-secondary)))
 	  (buffer-string)))
       (org-agenda-mark-header-line (point-min))
       (when rtnall
@@ -4833,10 +4836,10 @@ (defun org-agenda-propertize-selected-todo-keywords (keywords)
   "Use `org-todo-keyword-faces' for the selected todo KEYWORDS."
   (concat
    (if (or (equal keywords "ALL") (not keywords))
-       (propertize "ALL" 'face 'warning)
+       (propertize "ALL" 'face 'org-agenda-structure-filter)
      (mapconcat
       (lambda (kw)
-        (propertize kw 'face (org-get-todo-face kw)))
+        (propertize kw 'face (list (org-get-todo-face kw) 'org-agenda-structure)))
       (org-split-string keywords "|")
       "|"))
    "\n"))
@@ -4921,7 +4924,7 @@ (defun org-todo-list (&optional arg)
                     (insert "\n                     "))
                   (insert " " s))))
 	    (insert "\n"))
-	  (add-text-properties pos (1- (point)) (list 'face 'org-agenda-structure))
+	  (add-text-properties pos (1- (point)) (list 'face 'org-agenda-structure-secondary))
 	  (buffer-string)))
       (org-agenda-mark-header-line (point-min))
       (when rtnall
@@ -5012,7 +5015,7 @@ (defun org-tags-view (&optional todo-only match)
 				     (concat "Match: " match)))
 	  (setq pos (point))
 	  (insert match "\n")
-	  (add-text-properties pos (1- (point)) (list 'face 'org-warning))
+	  (add-text-properties pos (1- (point)) (list 'face 'org-agenda-structure-filter))
 	  (setq pos (point))
 	  (unless org-agenda-multi
 	    (insert (substitute-command-keys
@@ -5020,7 +5023,7 @@ (defun org-tags-view (&optional todo-only match)
 \\<org-agenda-mode-map>`\\[universal-argument] \\[org-agenda-redo]' \
 to search again\n")))
 	  (add-text-properties pos (1- (point))
-			       (list 'face 'org-agenda-structure))
+			       (list 'face 'org-agenda-structure-secondary))
 	  (buffer-string)))
       (org-agenda-mark-header-line (point-min))
       (when rtnall
diff --git a/lisp/org-faces.el b/lisp/org-faces.el
index 937c2d6f2..ecb957290 100644
--- a/lisp/org-faces.el
+++ b/lisp/org-faces.el
@@ -499,6 +499,16 @@ (defface org-agenda-structure ;Copied from `font-lock-function-name-face'
   "Face used in agenda for captions and dates."
   :group 'org-faces)
 
+(defface org-agenda-structure-secondary '((t (:inherit org-agenda-structure)))
+  "Face used for secondary information in agenda block headers."
+  :group 'org-faces)
+
+(defface org-agenda-structure-filter '((t (:inherit (org-warning org-agenda-structure))))
+  "Face used for the current type of task filter in the agenda.
+It inherits from `org-agenda-structure' so it can adapt to
+it (e.g. if that is assigned a diffent font height or family)."
+  :group 'org-faces)
+
 (defface org-agenda-date '((t (:inherit org-agenda-structure)))
   "Face used in agenda for normal days."
   :group 'org-faces)
@@ -508,6 +518,10 @@ (defface org-agenda-date-today
   "Face used in agenda for today."
   :group 'org-faces)
 
+(defface org-agenda-date-weekend-today '((t (:inherit org-agenda-date-today)))
+  "Face used in agenda for today during weekends."
+  :group 'org-faces)
+
 (defface org-agenda-clocking '((t (:inherit secondary-selection)))
   "Face marking the current clock item in the agenda."
   :group 'org-faces)
@@ -550,6 +564,11 @@ (defface org-scheduled-previously
   "Face for items scheduled previously, and not yet done."
   :group 'org-faces)
 
+(defface org-imminent-deadline '((t :inherit org-warning))
+  "Face for current deadlines in the agenda.
+See also `org-agenda-deadline-faces'."
+  :group 'org-faces)
+
 (defface org-upcoming-deadline
   '((((class color) (min-colors 88) (background light)) (:foreground "Firebrick"))
     (((class color) (min-colors 88) (background dark)) (:foreground "chocolate1"))
@@ -565,7 +584,7 @@ (defface org-upcoming-distant-deadline '((t :inherit org-default))
 See also `org-agenda-deadline-faces'.")
 
 (defcustom org-agenda-deadline-faces
-  '((1.0 . org-warning)
+  '((1.0 . org-imminent-deadline)
     (0.5 . org-upcoming-deadline)
     (0.0 . org-upcoming-distant-deadline))
   "Faces for showing deadlines in the agenda.
-- 
2.31.1