From 049eefa611912c6894c5fdeef2127ab2165e0144 Mon Sep 17 00:00:00 2001
From: "Jacob S. Gordon" <jacob.as.gordon@gmail.com>
Date: Mon, 26 Jan 2026 16:20:00 -0500
Subject: [PATCH] display-time: Add option to customize help-echo format

This option controls the format of the help-echo when hovering
over the time display in mode line.  (Bug#80143)
* lisp/time.el (display-time-help-echo-format): Add option.
(display-time-string-forms): Use it.

* etc/NEWS (Time): Announce the new option.
---
 etc/NEWS     |  5 +++++
 lisp/time.el | 16 +++++++++++++++-
 2 files changed, 20 insertions(+), 1 deletion(-)

diff --git a/etc/NEWS b/etc/NEWS
index 8cd29a5659f..8929fcc1215 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -3338,6 +3338,11 @@ each refresh.  The sort direction can be controlled by using a cons cell
 of a format string and a boolean.  Alternatively, a sorting function can
 be provided directly.
 
+---
+*** New user option 'display-time-help-echo-format'.
+This option controls the format of the help echo when hovering over the
+time.
+
 ** Fill
 
 +++
diff --git a/lisp/time.el b/lisp/time.el
index c78a51e9f97..f553ebab413 100644
--- a/lisp/time.el
+++ b/lisp/time.el
@@ -177,6 +177,18 @@ depend on `display-time-day-and-date' and `display-time-24hr-format'."
   :type '(choice (const :tag "Default" nil)
 		 string))
 
+(defcustom display-time-help-echo-format "%a %b %e, %Y"
+  "Format for the help echo when hovering over the time in the mode line.
+Use the function `customize-variable' to choose a common format, and/or
+see the function `format-time-string' for an explanation of the syntax."
+  :version "31.1"
+  :type `(choice
+          ,@(mapcar #'(lambda (fmt)
+                        (list 'const
+                              ':tag (format-time-string fmt 0 "UTC") fmt))
+                    '("%a %b %e, %Y" "%F (%a)" "%a %D"))
+          (string :tag "Format string")))
+
 (defcustom display-time-string-forms
   '((if (and (not display-time-format) display-time-day-and-date)
 	(format-time-string "%a %b %e " now)
@@ -186,7 +198,9 @@ depend on `display-time-day-and-date' and `display-time-24hr-format'."
 			     (if display-time-24hr-format "%H:%M" "%-I:%M%p"))
 			 now)
      'face 'display-time-date-and-time
-     'help-echo (format-time-string "%a %b %e, %Y" now))
+     'help-echo (format-time-string (if (stringp display-time-help-echo-format)
+                                        display-time-help-echo-format
+                                      "%a %b %e, %Y") now))
     load
     (if mail
 	;; Build the string every time to act on customization.