From cd4c79a5758f0b6b8f5cc8acde62f806a1452b64 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas@gmail.com>
Date: Sat, 2 May 2020 16:08:33 +0200
Subject: [PATCH 2/4] Make 'display-time-world' into an alias for 'world-clock'
 (Bug#40863)

* lisp/time.el (world-clock): Rename from 'display-time-world'.
(display-time-world): Redefine as alias for 'world-clock'.
* etc/NEWS: Announce the above change.

(top-level, zoneinfo-style-world-list, legacy-style-world-list)
(display-time-world-list, display-time-world-time-format)
(display-time-world-buffer-name)
(display-time-world-timer-enable)
(display-time-world-timer-second, display-time-world-label)
(display-time-world-timer): Update documentation to match the above
rename.
---
 etc/NEWS     |  7 +++++++
 lisp/time.el | 26 ++++++++++++++------------
 2 files changed, 21 insertions(+), 12 deletions(-)

diff --git a/etc/NEWS b/etc/NEWS
index 025d5c14a7..d2b745c579 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -288,6 +288,13 @@ prefix on the Subject line in various languages.
 These new navigation commands are bound to 'n' and 'p' in
 'apropos-mode'.
 
+** Time
+
+---
+*** 'display-time-world' is now an alias for 'world-clock'.
+'world-clock' creates a buffer with an updating time display using
+several time zones.  The new name is hoped to be more discoverable.
+
 
 * New Modes and Packages in Emacs 28.1
 
diff --git a/lisp/time.el b/lisp/time.el
index 7e26c131c9..fe290ff71f 100644
--- a/lisp/time.el
+++ b/lisp/time.el
@@ -25,8 +25,7 @@
 ;; Facilities to display current time/date and a new-mail indicator
 ;; in the Emacs mode line.  The entry point is `display-time'.
 
-;; Display time world in a buffer, the entry point is
-;; `display-time-world'.
+;; Use `world-clock' to display world clock in a buffer.
 
 ;;; Code:
 
@@ -130,7 +129,7 @@ zoneinfo-style-world-list
     ("Europe/Paris" "Paris")
     ("Asia/Calcutta" "Bangalore")
     ("Asia/Tokyo" "Tokyo"))
-  "Alist of zoneinfo-style time zones and places for `display-time-world'.
+  "Alist of zoneinfo-style time zones and places for `world-clock'.
 Each element has the form (TIMEZONE LABEL).
 TIMEZONE should be a string of the form AREA/LOCATION, where AREA is
 the name of a region -- a continent or ocean, and LOCATION is the name
@@ -147,7 +146,7 @@ legacy-style-world-list
     ("CET-1CDT" "Paris")
     ("IST-5:30" "Bangalore")
     ("JST-9" "Tokyo"))
-  "Alist of traditional-style time zones and places for `display-time-world'.
+  "Alist of traditional-style time zones and places for `world-clock'.
 Each element has the form (TIMEZONE LABEL).
 TIMEZONE should be a string of the form:
 
@@ -161,7 +160,7 @@ legacy-style-world-list
   :version "23.1")
 
 (defcustom display-time-world-list t
-  "Alist of time zones and places for `display-time-world' to display.
+  "Alist of time zones and places for `world-clock' to display.
 Each element has the form (TIMEZONE LABEL).
 TIMEZONE should be in a format supported by your system.  See the
 documentation of `zoneinfo-style-world-list' and
@@ -190,25 +189,25 @@ time--display-world-list
 	zoneinfo-style-world-list))))
 
 (defcustom display-time-world-time-format "%A %d %B %R %Z"
-  "Format of the time displayed, see `format-time-string'."
+  "Time format for `world-clock', see `format-time-string'."
   :group 'display-time
   :type 'string
   :version "23.1")
 
 (defcustom display-time-world-buffer-name "*wclock*"
-  "Name of the world clock buffer."
+  "Name of the `world-clock' buffer."
   :group 'display-time
   :type 'string
   :version "23.1")
 
 (defcustom display-time-world-timer-enable t
-  "If non-nil, a timer will update the world clock."
+  "If non-nil, a timer will update the `world-clock' buffer."
   :group 'display-time
   :type 'boolean
   :version "23.1")
 
 (defcustom display-time-world-timer-second 60
-  "Interval in seconds for updating the world clock."
+  "Interval in seconds for updating the `world-clock' buffer."
   :group 'display-time
   :type 'integer
   :version "23.1")
@@ -511,7 +510,7 @@ display-time-mode
 
 (defface display-time-world-label
   '((t :inherit font-lock-variable-name-face))
-  "Face for time zone label.")
+  "Face for time zone label in `world-clock' buffer.")
 
 (defvar display-time-world-mode-map
   (let ((map (make-sparse-keymap)))
@@ -551,8 +550,8 @@ display-time-world-display
   (goto-char (point-min)))
 
 ;;;###autoload
-(defun display-time-world ()
-  "Enable updating display of times in various time zones.
+(defun world-clock ()
+  "Show world clock buffer with times in various time zones.
 `display-time-world-list' specifies the zones.
 To turn off the world time display, go to that window and type `\\[quit-window]'."
   (interactive)
@@ -564,6 +563,7 @@ display-time-world
   (display-time-world-mode))
 
 (defun display-time-world-timer ()
+  "Update the `world-clock' buffer."
   (interactive)
   (if (get-buffer display-time-world-buffer-name)
       (with-current-buffer (get-buffer display-time-world-buffer-name)
@@ -576,6 +576,8 @@ display-time-world-timer
 		       "display-time-world-timer")
             (cancel-timer elt)))))))
 
+(defalias 'display-time-world #'world-clock)
+
 ;;;###autoload
 (defun emacs-uptime (&optional format)
   "Return a string giving the uptime of this instance of Emacs.
-- 
2.26.2