From a4a9ffdd80a2b8ccd2e6705887d3cae0876a50ab Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Fri, 17 Mar 2023 10:14:41 +0200 Subject: [PATCH] Fix the documentation of various aspects of adding Xref history * lisp/progmodes/xref.el (xref-marker-ring-length) (xref-set-marker-ring-length): * lisp/progmodes/etags.el (tags-location-ring-length) (find-tag-marker-ring): Add doc strings saying the variables are unused. * etc/NEWS: Enhance the description of the change which made Xref marker stack unlimited in its length. * doc/emacs/maintaining.texi (Looking Up Identifiers): Add back text lost when xref forward history was added in bug#38797. Explain the difference between 'C-M-,' and 'M-.'. Improve wording (Bug#62229) --- doc/emacs/maintaining.texi | 19 ++++++++++++++----- etc/NEWS | 12 ++++++++++-- lisp/progmodes/etags.el | 10 +++++++--- lisp/progmodes/xref.el | 14 +++++++++----- 4 files changed, 40 insertions(+), 15 deletions(-) diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi index f5bbc4d65c0..7d49e28d11f 100644 --- a/doc/emacs/maintaining.texi +++ b/doc/emacs/maintaining.texi @@ -2283,16 +2283,25 @@ buffer, but doesn't select any of them. @kindex M-, @findex xref-go-back - To go back to places @emph{from where} you've displayed the definition, -use @kbd{M-,} (@code{xref-go-back}). It jumps back to the + To go back to places @emph{from where} you've displayed the +definition, 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-,}. +where you were with @kbd{M-,}. @kbd{M-,} allows you to retrace the +steps you made forward in the history of places, all the way to the +first place in history, where you first invoked @kbd{M-.}, or to any +place in-between. @kindex C-M-, @findex xref-go-forward - If you previously went back too far with @kbd{M-,}, @kbd{C-M-,} -(@code{xref-go-forward}) can be used to go forward again. + If you previously went back too far with @kbd{M-,}, or want to +re-examine a place from which you went back, you can use @kbd{C-M-,} +(@code{xref-go-forward}) to go forward again. This is similar to +using @kbd{M-.}, except that you don't need on each step to move point +to the identifier whose definition you want to look up. @kbd{C-M-,} +allows you to retrace all the steps you made back in the history of +places, all the way to the last place in history, where you invoked +@kbd{M-,}, or to any place in-between. @findex xref-etags-mode Some major modes install @code{xref} support facilities that might diff --git a/etc/NEWS b/etc/NEWS index a5f9f8c6ec1..0b651f7a519 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -2540,8 +2540,16 @@ the project by a VC project based on that VCS. +++ *** New command 'xref-go-forward'. -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. +It is bound to 'C-M-,' and jumps to the location where you previously +invoked 'xref-go-back' ('M-,', also known as 'xref-pop-marker-stack'). + ++++ +*** The depth of the Xref marker stack is now infinite. +The implementation of the Xref marker stack was changed in a way that +allows as many places to be saved on the stack as needed, limited only +by the available memory. Therefore, the variables +'find-tag-marker-ring-length' and 'xref-marker-ring-length' are now +obsolete and unused; setting them has no effect. +++ *** 'xref-query-replace-in-results' prompting change. diff --git a/lisp/progmodes/etags.el b/lisp/progmodes/etags.el index 8efdae6060f..cb95f29b5fe 100644 --- a/lisp/progmodes/etags.el +++ b/lisp/progmodes/etags.el @@ -146,7 +146,10 @@ Otherwise, `find-tag-default' is used." (define-obsolete-variable-alias 'find-tag-marker-ring-length 'tags-location-ring-length "25.1") -(defvar tags-location-ring-length 16) +(defvar tags-location-ring-length 16 + "Size of the find-tag marker ring. +This variable has no effect, and is kept only for backward compatibility. +The actual size of the find-tag marker ring is unlimited.") (defcustom tags-tag-face 'default "Face for tags in the output of `tags-apropos'." @@ -181,8 +184,9 @@ Example value: (sexp :tag "Tags to search"))) :version "21.1") -;; Obsolete variable kept for compatibility. We don't use it in any way. -(defvar find-tag-marker-ring (make-ring 16)) +(defvar find-tag-marker-ring (make-ring 16) + "Find-tag marker ring. +Obsolete variable kept for compatibility. It is not used in any way.") (make-obsolete-variable 'find-tag-marker-ring "use `xref-push-marker-stack' or `xref-go-back' instead." diff --git a/lisp/progmodes/xref.el b/lisp/progmodes/xref.el index d4e34f7e55a..ee4253960c5 100644 --- a/lisp/progmodes/xref.el +++ b/lisp/progmodes/xref.el @@ -355,8 +355,10 @@ backward." (t (goto-char start) nil)))) -;; Dummy variable retained for compatibility. -(defvar xref-marker-ring-length 16) +(defvar xref-marker-ring-length 16 + "Xref marker ring length. +This is a dummy variable retained for backward compatibility, and +otherwise unused.") (make-obsolete-variable 'xref-marker-ring-length nil "29.1") (defcustom xref-prompt-for-identifier '(not xref-find-definitions @@ -453,7 +455,9 @@ are predefined: (make-obsolete-variable 'xref--marker-ring 'xref--history "29.1") (defun xref-set-marker-ring-length (_var _val) - (declare (obsolete nil "29.1")) + (declare (obsolete + "this function has no effect: Xref marker ring is now unlimited in size" + "29.1")) nil) (defun xref--make-xref-history () @@ -499,7 +503,7 @@ Override existing value with NEW-VALUE if NEW-VALUE is set." (defun xref-push-marker-stack (&optional m) "Add point M (defaults to `point-marker') to the marker stack. -The future stack is erased." +Erase the stack slots following this one." (xref--push-backward (or m (point-marker))) (let ((history (xref--get-history))) (dolist (mk (cdr history)) @@ -527,7 +531,7 @@ To undo, use \\[xref-go-forward]." ;;;###autoload (defun xref-go-forward () - "Got to the point where a previous \\[xref-go-back] was invoked." + "Go to the point where a previous \\[xref-go-back] was invoked." (interactive) (let ((history (xref--get-history))) (if (null (cdr history)) -- 2.39.5