[PATCH] Add faces to improve contextuality of agenda views

[PATCH] Add faces to improve contextuality of agenda views

[Protesilaos Stavrou]

[-- 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

Re: [PATCH] Add faces to improve contextuality of agenda views

[Timothy]

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

Hi  Protesilaos,

Thanks for sending this patch in, and sorry it’s taken a while for you to hear
anything back. I see the utility of org-imminent-deadline, but am fairly
indifferent about the rest.

Hopefully bumping this might prompt some others to give their thoughts on your
patch.

All the best,
Timothy

Re: [PATCH] Add faces to improve contextuality of agenda views

[Protesilaos Stavrou]

On 2021-09-19, 21:23 +0800, Timothy <tecosaur@gmail.com> wrote:

> Hi  Protesilaos,

Hello Timothy,

> Thanks for sending this patch in, and sorry it’s taken a while for you to hear
> anything back.

No worries.  I understand this is a voluntary effort.

> I see the utility of org-imminent-deadline, but am fairly indifferent
> about the rest.

I can provide examples in case someone needs them.  The basic idea is to
ensure consistency of styling.

Right now, if you increase the height of the 'org-agenda-structure' and
do something like M-x org-agenda followed by 'm' you will get a header
that reads like:

    Headlines with TAGS match: admin

The "admin" part is smaller than the rest.  It is this sort of
inconsistency that we wish to address.  We do it in a manner that is
backward-compatible, which means that themes do not have to be updated
for users to benefit from the new design (though users/themes gain the
option to control the presentation with greater precision).

> Hopefully bumping this might prompt some others to give their thoughts on your
> patch.

I am happy to wait for as long as necessary and remain at your disposal
for any further commentary or possible edits to the patch.

Given this opportunity, thank you and the others for your contributions
to Org.

Best regards,
Protesilaos

-- 
Protesilaos Stavrou
https://protesilaos.com

Re: [PATCH] Add faces to improve contextuality of agenda views

[Bastien]

Hi Protesilaos,

> The attached patch defines and implements a few new faces for the
> agenda.  

Applied, thank you very much for the thorough explanations and the
well-written patch and commit message.

This deserves an entry in etc/ORG-NEWS for Org 9.5: would you be 
willing to submit a patch for this?

Thanks!

-- 
 Bastien

Re: [PATCH] Add faces to improve contextuality of agenda views

[Protesilaos Stavrou]

On 2021-09-26, 10:45 +0200, Bastien <bzg@gnu.org> wrote:

>> The attached patch defines and implements a few new faces for the
>> agenda.  
>
> Applied, thank you very much for the thorough explanations and the
> well-written patch and commit message.

Thank you, Bastien (for this and for maintaining Org in general)!

> This deserves an entry in etc/ORG-NEWS for Org 9.5: would you be 
> willing to submit a patch for this?

Yes, I will prepare one, though I am committed to a task right now and
will only be available again in ~3 hours.

-- 
Protesilaos Stavrou
https://protesilaos.com

Re: [PATCH] Add faces to improve contextuality of agenda views

[Protesilaos Stavrou]

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

On 2021-09-26, 10:45 +0200, Bastien <bzg@gnu.org> wrote:

>> The attached patch defines and implements a few new faces for the
>> agenda.  
>
> Applied, thank you very much for the thorough explanations and the
> well-written patch and commit message.
>
> This deserves an entry in etc/ORG-NEWS for Org 9.5: would you be 
> willing to submit a patch for this?

Hello again Bastien!

Please find attached the entry for the ORG-NEWS.

All the best,
Protesilaos


-- 
Protesilaos Stavrou
https://protesilaos.com


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Document-new-agenda-faces-in-the-ORG-NEWS.patch --]
[-- Type: text/x-patch, Size: 2680 bytes --]

From ac96612c9e1313ef40fef042c4e79771776423bd Mon Sep 17 00:00:00 2001
Message-Id: <ac96612c9e1313ef40fef042c4e79771776423bd.1632659262.git.info@protesilaos.com>
From: Protesilaos Stavrou <info@protesilaos.com>
Date: Sun, 26 Sep 2021 15:27:31 +0300
Subject: [PATCH] Document new agenda faces in the ORG-NEWS

---
 etc/ORG-NEWS | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 80a8bc388..f3cebd836 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -168,6 +168,44 @@ When specifying a custom agenda bulk option, you can now also specify
 a function which collects the arguments to be used with each call to
 the custom function.
 
+*** New faces to improve the contextuality of Org agenda views
+
+Four new faces improve certain styles and offer more flexibility for
+some Org agenda views: ~org-agenda-date-weekend-today~,
+~org-imminent-deadline~, ~org-agenda-structure-secondary~,
+~org-agenda-structure-filter~.  They inherit from existing faces in
+order to remain backward-compatible.
+
+Quoting from [[https://list.orgmode.org/87lf7q7gpq.fsf@protesilaos.com/][this thread]]:
+
+#+begin_quote
++ 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.
+#+end_quote
+
 *** New option ~org-clock-ask-before-exiting~
 
 By default, a function is now added to ~kill-emacs-query-functions~
-- 
2.33.0

Re: [PATCH] Add faces to improve contextuality of agenda views

[Bastien]

Hi Protesilaos,

Protesilaos Stavrou <info@protesilaos.com> writes:

> Please find attached the entry for the ORG-NEWS.

Applied, thank you very much!

-- 
 Bastien