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

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

[Drew Adams]

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.

In GNU Emacs 24.3.50.1 (i686-pc-mingw32)
 of 2013-12-05 on ODIEONE
Bzr revision: 115389 monnier@iro.umontreal.ca-20131205202554-1az0dm7bdk303bgw
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/Devel/emacs/binary --enable-checking=yes,glyphs
 'CFLAGS=-O0 -g3' CPPFLAGS=-Ic:/Devel/emacs/include
 LDFLAGS=-Lc:/Devel/emacs/lib'

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

[Lars Ingebrigtsen]

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.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

[Stefan Kangas]

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

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

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Sat, 24 Aug 2019 07:40:37 +0200
> Cc: 16074@debbugs.gnu.org
> 
> >> 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?

IMO, doing this is a waste of time, energy, VC resources and whatnot.

Just one opinion.

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

[Drew Adams]

> >> 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.
> >
> > Yes, renaming here seems like a good idea.
> 
> How about the attached patch?

Maybe I missed something when perusing the patch,
but it looks like it addresses only the global
mark ring (`C-x C-SPC'), not also the (local)
mark ring (`C-u C-SPC').

The enhancement request is about both.  The doc
for both speaks of "pop" instead of cycle.

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

[Lars Ingebrigtsen]

Stefan Kangas <stefan@marxist.se> writes:

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

I think that looks like the correct solution.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

[Drew Adams]

> >> Yes, renaming here seems like a good idea.
> >
> > How about the attached patch?
> 
> I think that looks like the correct solution.

It doesn't address the problem for the `mark-ring',
does it?  My impression was that it addresses it
only for `global-mark-ring'.  The local `mark-ring'
is used much more often than the `global-mark-ring',
and its doc is probably accessed much more often.

For example -

This part of `C-h k C-SPC' is wrong:

 With prefix argument (e.g., C-u C-SPC), jump to the mark,
 and set the mark from position popped off the local mark
                                ^^^^^^^^^^
 ring (this does not affect the global mark ring).
 ...

 If 'set-mark-command-repeat-pop' is non-nil, repeating
 the C-SPC command with no prefix argument pops the next
 position off the local (or global) mark ring and jumps there.

 With C-u C-u as prefix argument, unconditionally set
 mark where point is, even if 'set-mark-command-repeat-pop'
 is non-nil.

And the doc & name of option `set-mark-command-repeat-pop'
are wrong (plus, the line lengths are screwy):

 Non-nil means repeating C-SPC after popping mark
 pops it again.
 That means that C-u C-SPC C-SPC
 will pop the mark twice, and
 C-u C-SPC C-SPC C-SPC
 will pop the mark three times.

And the doc & name of function `pop-to-mark-command'
are wrong:

 Jump to mark, and pop a new position for mark off the ring.

A position is NOT popped off the ring.  That's what's
wrong with all of these.  Likewise, the doc in the
manuals.

The enhancement request is to fix this wrong
terminology wrt BOTH `global-mark-ring' and
`mark-ring'.

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

[Juri Linkov]

>> >> Yes, renaming here seems like a good idea.
>> >
>> > How about the attached patch?
>>
>> I think that looks like the correct solution.
>
> It doesn't address the problem for the `mark-ring',
> does it?  My impression was that it addresses it
> only for `global-mark-ring'.  The local `mark-ring'
> is used much more often than the `global-mark-ring',
> and its doc is probably accessed much more often.
>
> For example -
>
> This part of `C-h k C-SPC' is wrong:
>
>  With prefix argument (e.g., C-u C-SPC), jump to the mark,
>  and set the mark from position popped off the local mark
>                                 ^^^^^^^^^^
>  ring (this does not affect the global mark ring).
>  ...
>
>  If 'set-mark-command-repeat-pop' is non-nil, repeating
>  the C-SPC command with no prefix argument pops the next
>  position off the local (or global) mark ring and jumps there.
>
>  With C-u C-u as prefix argument, unconditionally set
>  mark where point is, even if 'set-mark-command-repeat-pop'
>  is non-nil.
>
> And the doc & name of option `set-mark-command-repeat-pop'
> are wrong (plus, the line lengths are screwy):
>
>  Non-nil means repeating C-SPC after popping mark
>  pops it again.
>  That means that C-u C-SPC C-SPC
>  will pop the mark twice, and
>  C-u C-SPC C-SPC C-SPC
>  will pop the mark three times.
>
> And the doc & name of function `pop-to-mark-command'
> are wrong:
>
>  Jump to mark, and pop a new position for mark off the ring.
>
> A position is NOT popped off the ring.  That's what's
> wrong with all of these.  Likewise, the doc in the
> manuals.
>
> The enhancement request is to fix this wrong
> terminology wrt BOTH `global-mark-ring' and
> `mark-ring'.

And `yank' doesn't yank, and `kill' doesn't kill literally.
What is the most important is that docstrings should describe
the behavior in all details.  The name is more a matter of taste.

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

[Drew Adams]

> > The enhancement request is to fix this wrong
> > terminology wrt BOTH `global-mark-ring' and
> > `mark-ring'.
> 
> And `yank' doesn't yank, and `kill' doesn't kill literally.
> What is the most important is that docstrings should describe
> the behavior in all details.  The name is more a matter of taste.

Irrelevant.  Emacs _has_ "pop" in its terminology,
just like it has "yank" and "kill" (buffer, text).

This mistaken use of "pop" doesn't fit Emacs's use
of the word (or even typical outside uses of it).

And Emacs _has_ a term, "cycle", for the behavior
here.  "Cycle" is the term Emacs uses for rings.

And it's not just about the name.  It's also about
the doc, which incorrectly tells users that the
behavior is to "pop" the mark/position "off" the
ring.

That's wrong; it's not what happens.  That doesn't
"describe the behavior in all details".  Instead,
it describes a different behavior, which doesn't
happen.

Hand-waving alone can't justify this misleading.

On the other hand, as I replied to Eli, you can
decide whether fixing this is "worth the necessary
time, energy, VC resources and your whatnot."
That's up to you.

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

[Eli Zaretskii]

> From: Juri Linkov <juri@linkov.net>
> Date: Sun, 25 Aug 2019 23:09:45 +0300
> Cc: Lars Ingebrigtsen <larsi@gnus.org>, Stefan Kangas <stefan@marxist.se>,
>  16074@debbugs.gnu.org
> 
> > A position is NOT popped off the ring.  That's what's
> > wrong with all of these.  Likewise, the doc in the
> > manuals.
> >
> > The enhancement request is to fix this wrong
> > terminology wrt BOTH `global-mark-ring' and
> > `mark-ring'.
> 
> And `yank' doesn't yank, and `kill' doesn't kill literally.

And 'window' is not a window, it's a pane; and 'frame' is actually a
window, etc. etc.

> What is the most important is that docstrings should describe
> the behavior in all details.  The name is more a matter of taste.

Indeed.  Especially since what these functions really do is only
slightly different from a literal "pop".

We shouldn't waste our time on such renaming, IMO.

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

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

>> What is the most important is that docstrings should describe
>> the behavior in all details.  The name is more a matter of taste.
>
> Indeed.  Especially since what these functions really do is only
> slightly different from a literal "pop".
>
> We shouldn't waste our time on such renaming, IMO.

OK, it doesn't sound like this renaming was greatly favoured, so I'm
closing this bug report.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

[Drew Adams]

> IMO, doing this is a waste of time, energy, VC resources and whatnot.

It helps users.  Whether in this case that help
is worth the necessary time, energy, VC resources
and your whatnot is up to you.

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

[Drew Adams]

> > > A position is NOT popped off the ring.  That's what's
> > > wrong with all of these.  Likewise, the doc in the
> > > manuals.
> > >
> > > The enhancement request is to fix this wrong
> > > terminology wrt BOTH `global-mark-ring' and
> > > `mark-ring'.
> >
> > And `yank' doesn't yank, and `kill' doesn't kill literally.
> 
> And 'window' is not a window, it's a pane; and 'frame' is actually a
> window, etc. etc.

And all of those terms are standard Emacs
terminology, defined clearly and used
consistently.

That's not the case with this outlier use
of "pop", which is not a pop but is exactly
what Emacs calls "cycling" of a ring.

And again, it's about the doc also, not
just the function names.