Rename xref-pop-marker-stack to xref-go-back (bug#38797)

It is the natural name after the addition of `xref-go-forward`.
The old name is retained as an alias.

* lisp/progmodes/xref.el (xref-pop-marker-stack): Rename.
(xref-go-forward, xref-quit-and-pop-marker-stack)
(xref-find-definitions):
* lisp/menu-bar.el (menu-bar-goto-menu):
* lisp/progmodes/etags.el (find-tag-marker-ring, pop-tag-mark):
* lisp/progmodes/prog-mode.el (prog-context-menu):
* doc/emacs/maintaining.texi (Looking Up Identifiers):
* etc/NEWS:
Use the new name.

doc/emacs/maintaining.texi

@@ -2139,7 +2139,7 @@ Find definition of identifier, and display it in a new frame
 Find definition of identifier at mouse click.
 @item M-,
 Go back to where you previously invoked @kbd{M-.} and friends
-(@code{xref-pop-marker-stack}).
+(@code{xref-go-back}).
 @item C-M-,
 Go forward to where you previously invoked @kbd{M-,}
 (@code{xref-go-forward}).
@@ -2207,9 +2207,9 @@ selects the window showing the first candidate.  The default value is
 buffer, but doesn't select any of them.
 
 @kindex M-,
-@findex xref-pop-marker-stack
+@findex xref-go-back
   To go back to places @emph{from where} you've displayed the definition,
-use @kbd{M-,} (@code{xref-pop-marker-stack}).  It jumps back to the
+use @kbd{M-,} (@code{xref-go-back}).  It jumps back to the
 point of the last invocation of @kbd{M-.}.  Thus you can find and
 examine the definition of something with @kbd{M-.} and then return to
 where you were with @kbd{M-,}.

etc/NEWS

@@ -185,8 +185,8 @@ a prefix argument which is interpreted to mean "include all files".
 
 +++
 *** New command 'xref-go-forward'.
-It is bound to 'C-M-,' and jumps to the location where 'xref-pop-marker-stack'
-was invoked previously.
+It is bound to 'C-M-,' and jumps to the location where 'xref-go-back'
+('M-,', also known as 'xref-pop-marker-stack') was invoked previously.
 
 ** File notifications
 

lisp/menu-bar.el

@@ -420,7 +420,7 @@
                   :help "Forward to the position gone Back from"))
 
     (bindings--define-key menu [xref-pop]
-      '(menu-item "Back" xref-pop-marker-stack
+      '(menu-item "Back" xref-go-back
                   :visible (and (featurep 'xref)
                                 (not (xref-marker-stack-empty-p)))
                   :help "Back to the position of the last search"))

lisp/progmodes/etags.el

@@ -186,7 +186,7 @@ Example value:
 (defvar find-tag-marker-ring (make-ring 16))
 (make-obsolete-variable
  'find-tag-marker-ring
- "use `xref-push-marker-stack' or `xref-pop-marker-stack' instead."
+ "use `xref-push-marker-stack' or `xref-go-back' instead."
  "25.1")
 
 (defvar default-tags-table-function nil
@@ -1071,7 +1071,7 @@ See documentation of variable `tags-file-name'."
 	   regexp next-p t))
 
 ;;;###autoload
-(defalias 'pop-tag-mark 'xref-pop-marker-stack)
+(defalias 'pop-tag-mark 'xref-go-back)
 
 
 (defvar tag-lines-already-matched nil

lisp/progmodes/prog-mode.el

@@ -51,7 +51,7 @@
 
   (unless (xref-marker-stack-empty-p)
     (define-key-after menu [xref-pop]
-      '(menu-item "Back Definition" xref-pop-marker-stack
+      '(menu-item "Back Definition" xref-go-back
                   :help "Back to the position of the last search")
       'prog-separator))
 

lisp/progmodes/xref.el

@@ -432,7 +432,10 @@ The future stack is erased."
   (setcdr xref--history nil))
 
 ;;;###autoload
-(defun xref-pop-marker-stack ()
+(define-obsolete-function-alias 'xref-pop-marker-stack #'xref-go-back "29.1")
+
+;;;###autoload
+(defun xref-go-back ()
   "Go back to the previous position in xref history.
 To undo, use \\[xref-go-forward]."
   (interactive)
@@ -445,11 +448,10 @@ To undo, use \\[xref-go-forward]."
       (goto-char (marker-position marker))
       (set-marker marker nil nil)
       (run-hooks 'xref-after-return-hook))))
-;; FIXME: rename to `xref-go-back'.
 
 ;;;###autoload
 (defun xref-go-forward ()
-  "Got to the point where a previous \\[xref-pop-marker-stack] was invoked."
+  "Got to the point where a previous \\[xref-go-back] was invoked."
   (interactive)
   (if (null (cdr xref--history))
       (user-error "At end of xref history")
@@ -708,7 +710,7 @@ quit the *xref* buffer."
   "Quit *xref* buffer, then pop the xref marker stack."
   (interactive)
   (quit-window)
-  (xref-pop-marker-stack))
+  (xref-go-back))
 
 (defun xref-query-replace-in-results (from to)
   "Perform interactive replacement of FROM with TO in all displayed xrefs.
@@ -1418,7 +1420,7 @@ definition for IDENTIFIER, display it in the selected window.
 Otherwise, display the list of the possible definitions in a
 buffer where the user can select from the list.
 
-Use \\[xref-pop-marker-stack] to return back to where you invoked this command."
+Use \\[xref-go-back] to return back to where you invoked this command."
   (interactive (list (xref--read-identifier "Find definitions of: ")))
   (xref--find-definitions identifier nil))
 
@@ -1509,10 +1511,10 @@ output of this command when the backend is etags."
 ;;; Key bindings
 
 ;;;###autoload (define-key esc-map "." #'xref-find-definitions)
-;;;###autoload (define-key esc-map "," #'xref-pop-marker-stack)
+;;;###autoload (define-key esc-map "," #'xref-go-back)
+;;;###autoload (define-key esc-map [?\C-,] #'xref-go-forward)
 ;;;###autoload (define-key esc-map "?" #'xref-find-references)
 ;;;###autoload (define-key esc-map [?\C-.] #'xref-find-apropos)
-;;;###autoload (define-key esc-map [?\C-,] #'xref-go-forward)
 ;;;###autoload (define-key ctl-x-4-map "." #'xref-find-definitions-other-window)
 ;;;###autoload (define-key ctl-x-5-map "." #'xref-find-definitions-other-frame)