bug#16074: 24.3.50; enhancement request: Remove "pop" from command names & doc for `C-(u|x) C-SPC'

[Stefan Kangas <stefan@marxist.se>]

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

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Drew Adams <drew.adams@oracle.com> writes:
>
>> See http://stackoverflow.com/a/20427244/729907.
>>
>> The names and doc of the commands bound to `C-u C-SPC' and `C-x C-SPC'
>> are misleading, in that the commands do not really "pop" the marker
>> rings. They cycle the rings.  Markers are not removed from the rings
>> by such "popping".
>>
>> Emacs uses the verb "cycle" for this kind of behavior elsewhere.  The
>> same terminology should be used here also.  We should rename
>> `pop-global-mark' and rephrase the doc.
>
> Heh.  I didn't even know that they didn't pop, after all these years.
>
> Yes, renaming here seems like a good idea.

How about the attached patch?

Thanks,
Stefan Kangas

[-- Attachment #2: 0001-Rename-pop-global-mark-to-cycle-global-mark.patch --]
[-- Type: application/octet-stream, Size: 7670 bytes --]

From b0bd0c0e7d997a0e50463864c8db01db8f92c29f Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas@gmail.com>
Date: Sat, 24 Aug 2019 07:29:11 +0200
Subject: [PATCH] Rename pop-global-mark to cycle-global-mark

This better reflects how this command actually works.  It does not
delete or pop from global-mark-ring, instead it cycles the elements.

* lisp/simple.el (cycle-global-mark): Rename from 'pop-global-mark'.
(Bug#16074)  Signal user-error instead of error when mark is in
narrowed part of buffer and widen-automatically is nil.

* lisp/simple.el (set-mark-command)
* lisp/bindings.el (ctl-x-map)
* lisp/emulation/cua-base.el (cua-set-mark)
* lisp/emacs-lisp/eldoc.el
* lisp/org/org.el: Use the new name.

* doc/emacs/mark.texi (Global Mark Ring): Update documentation to
reflect the above change.
* etc/NEWS: Announce it.
---
 doc/emacs/mark.texi        |  4 ++--
 etc/NEWS                   |  5 +++++
 lisp/bindings.el           |  4 ++--
 lisp/emacs-lisp/eldoc.el   |  2 +-
 lisp/emulation/cua-base.el | 10 +++++-----
 lisp/org/org.el            |  2 +-
 lisp/simple.el             | 24 +++++++++++++++---------
 7 files changed, 31 insertions(+), 20 deletions(-)

diff --git a/doc/emacs/mark.texi b/doc/emacs/mark.texi
index bbeb4cb039..d6c5a1550c 100644
--- a/doc/emacs/mark.texi
+++ b/doc/emacs/mark.texi
@@ -368,8 +368,8 @@ Global Mark Ring
 @code{global-mark-ring-max}, and is 16 by default.
 
 @kindex C-x C-SPC
-@findex pop-global-mark
-  The command @kbd{C-x C-@key{SPC}} (@code{pop-global-mark}) jumps to
+@findex cycle-global-mark
+  The command @kbd{C-x C-@key{SPC}} (@code{cycle-global-mark}) jumps to
 the buffer and position of the latest entry in the global ring.  It also
 rotates the ring, so that successive uses of @kbd{C-x C-@key{SPC}} take
 you to earlier buffers and mark positions.
diff --git a/etc/NEWS b/etc/NEWS
index cf187598ce..7a2c0b6590 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -423,6 +423,11 @@ RGB triplets with a single hexadecimal digit per component.
 ---
 ** The toolbar now shows the equivalent key binding in its tooltips.
 
++++
+** 'pop-global-mark' is now an obsolete alias of 'cycle-global-mark'.
+The new name better reflects how this command works.  See the doc
+string of 'cycle-global-mark' for more details.
+
 \f
 * Editing Changes in Emacs 27.1
 
diff --git a/lisp/bindings.el b/lisp/bindings.el
index 0be1458798..45f18d76d0 100644
--- a/lisp/bindings.el
+++ b/lisp/bindings.el
@@ -997,9 +997,9 @@ global-map
 (put 'set-mark-command :advertised-binding [?\C- ])
 
 (define-key ctl-x-map "\C-x" 'exchange-point-and-mark)
-(define-key ctl-x-map "\C-@" 'pop-global-mark)
+(define-key ctl-x-map "\C-@" 'cycle-global-mark)
 (define-key ctl-x-map " " 'rectangle-mark-mode)
-(define-key ctl-x-map [?\C- ] 'pop-global-mark)
+(define-key ctl-x-map [?\C- ] 'cycle-global-mark)
 
 (define-key global-map "\C-n" 'next-line)
 (define-key global-map "\C-p" 'previous-line)
diff --git a/lisp/emacs-lisp/eldoc.el b/lisp/emacs-lisp/eldoc.el
index 2892faae21..ad15f41c53 100644
--- a/lisp/emacs-lisp/eldoc.el
+++ b/lisp/emacs-lisp/eldoc.el
@@ -455,7 +455,7 @@ eldoc-remove-command-completions
  "down-list" "end-of-" "exchange-point-and-mark" "forward-" "goto-"
  "handle-select-window" "indent-for-tab-command" "left-" "mark-page"
  "mark-paragraph" "mouse-set-point" "move-" "move-beginning-of-"
- "move-end-of-" "newline" "next-" "other-window" "pop-global-mark"
+ "move-end-of-" "newline" "next-" "other-window" "cycle-global-mark"
  "previous-" "recenter" "right-" "scroll-" "self-insert-command"
  "split-window-" "up-list")
 
diff --git a/lisp/emulation/cua-base.el b/lisp/emulation/cua-base.el
index 46258cbbd8..38bc995aa8 100644
--- a/lisp/emulation/cua-base.el
+++ b/lisp/emulation/cua-base.el
@@ -1004,8 +1004,8 @@ cua-set-mark
 
 With argument, jump to mark, and pop a new position for mark off
 the local mark ring (this does not affect the global mark ring).
-Use \\[pop-global-mark] to jump to a mark off the global mark ring
-\(see `pop-global-mark').
+Use \\[cycle-global-mark] to jump to a mark off the global mark ring
+\(see `cycle-global-mark').
 
 If `cua-auto-mark-last-change' is non-nil, this command behaves as if there
 was an implicit mark at the position of the last buffer change.
@@ -1021,9 +1021,9 @@ cua-set-mark
    ((eq last-command 'pop-to-mark-command)
     (setq this-command 'pop-to-mark-command)
     (pop-to-mark-command))
-   ((and (eq last-command 'pop-global-mark) (not arg))
-    (setq this-command 'pop-global-mark)
-    (pop-global-mark))
+   ((and (eq last-command 'cycle-global-mark) (not arg))
+    (setq this-command 'cycle-global-mark)
+    (cycle-global-mark))
    (arg
     (setq this-command 'pop-to-mark-command)
     (or (and cua-auto-mark-last-change
diff --git a/lisp/org/org.el b/lisp/org/org.el
index ab29353ae8..1ddd7f33ef 100644
--- a/lisp/org/org.el
+++ b/lisp/org/org.el
@@ -24885,7 +24885,7 @@ org-mark-jump-unhide
      (org-mark-jump-unhide)))
 
 (eval-after-load "simple"
-  '(defadvice pop-global-mark (after org-make-visible activate)
+  '(defadvice cycle-global-mark (after org-make-visible activate)
      "Make the point visible with `org-show-context'."
      (org-mark-jump-unhide)))
 
diff --git a/lisp/simple.el b/lisp/simple.el
index 358b6a4f20..901cde638b 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -5761,8 +5761,8 @@ set-mark-command
 With prefix argument (e.g., \\[universal-argument] \\[set-mark-command]), \
 jump to the mark, and set the mark from
 position popped off the local mark ring (this does not affect the global
-mark ring).  Use \\[pop-global-mark] to jump to a mark popped off the global
-mark ring (see `pop-global-mark').
+mark ring).  Use \\[cycle-global-mark] to jump to a mark popped off the global
+mark ring (see `cycle-global-mark').
 
 If `set-mark-command-repeat-pop' is non-nil, repeating
 the \\[set-mark-command] command with no prefix argument pops the next position
@@ -5787,10 +5787,10 @@ set-mark-command
 	(pop-to-mark-command)
       (push-mark-command t)))
    ((and set-mark-command-repeat-pop
-	 (eq last-command 'pop-global-mark)
+         (eq last-command 'cycle-global-mark)
 	 (not arg))
-    (setq this-command 'pop-global-mark)
-    (pop-global-mark))
+    (setq this-command 'cycle-global-mark)
+    (cycle-global-mark))
    ((or (and set-mark-command-repeat-pop
              (eq last-command 'pop-to-mark-command))
         arg)
@@ -5959,10 +5959,16 @@ non-essential
 background or displaying possible completions before the user even asked
 for it.")
 
-(defun pop-global-mark ()
-  "Pop off global mark ring and jump to the top location."
+(define-obsolete-function-alias 'pop-global-mark
+  'cycle-global-mark "27.1")
+(defun cycle-global-mark ()
+  "Cycle the global mark ring and jump to position and buffer of latest mark.
+This will move point to the buffer and position of the latest
+element in `global-mark-ring'.  It also rotates the ring, so that
+successive uses of \\[cycle-global-mark] will take you to earlier
+buffers and mark positions."
   (interactive)
-  ;; Pop entries which refer to non-existent buffers.
+  ;; Remove entries which refer to non-existent buffers.
   (while (and global-mark-ring (not (marker-buffer (car global-mark-ring))))
     (setq global-mark-ring (cdr global-mark-ring)))
   (or global-mark-ring
@@ -5977,7 +5983,7 @@ pop-global-mark
 	     (<= position (point-max)))
 	(if widen-automatically
 	    (widen)
-	  (error "Global mark position is outside accessible part of buffer")))
+          (user-error "Global mark position is outside accessible part of buffer")))
     (goto-char position)
     (switch-to-buffer buffer)))
 \f
-- 
2.22.0