patch 9.0.1921: not possible to use the jumplist like a stackv9.0.1921

Problem:  not possible to use the jumplist like a stack
Solution: Add the 'jumpoptions' setting to make the jumplist
          a stack.

Add an option for using jumplist like tag stack

related: #7738
closes: #13134

ported from NeoVim:

- https://neovim.io/doc/user/motion.html#jumplist-stack
- neovim/neovim@39094b3
- neovim/neovim#11530
- https://vi.stackexchange.com/questions/18344/how-to-change-jumplist-behavior

Based on the feedback in the previous PR, it looks like many people like
this option.

Signed-off-by: Christian Brabandt <cb@256bit.org>
Co-authored-by: Yegappan Lakshmanan <yegappan@yahoo.com>
Co-authored-by: butwerenotthereyet <58348703+butwerenotthereyet@users.noreply.github.com>

4 files changed, 53 insertions, 0 deletions

diff --git a/runtime/doc/motion.txt b/runtime/doc/motion.txt
index c89eead634..9bdbfb4936 100644
--- a/runtime/doc/motion.txt
+++ b/runtime/doc/motion.txt
@@ -1135,7 +1135,46 @@ When you split a window, the jumplist will be copied to the new window.
 If you have included the ' item in the 'viminfo' option the jumplist will be
 stored in the viminfo file and restored when starting Vim.
 
+							*jumplist-stack*
+When 'jumpoptions' option includes "stack", the jumplist behaves like the tag
+stack.  When jumping to a new location from the middle of the jumplist, the
+locations after the current position will be discarded. With this option set
+you can move through a tree of jump locations. When going back up a branch and
+then down another branch, CTRL-O still takes you further up the tree.
+
+Given a jumplist like the following in which CTRL-O has been used to move back
+three times to location X: >
+
+     jump line  col file/text
+       2  1260    8 mark.c		<-- location X-2
+       1   685    0 eval.c		<-- location X-1
+    >  0   462   36 eval.c		<-- location X
+       1   479   39 eval.c
+       2   213    2 mark.c
+       3   181    0 mark.c
+<
+jumping to (new) location Y results in the locations after the current
+locations being removed: >
+
+     jump line  col file/text
+       3  1260    8 mark.c		<-- location X-2
+       2   685    0 eval.c		<-- location X-1
+       1   462   36 eval.c		<-- location X
+    >
+<
 
+Then, when yet another location Z is jumped to, the new location Y appears
+directly after location X in the jumplist and location X remains in the same
+position relative to the locations (X-1, X-2, etc., ...) that had been before
+it prior to the original jump from X to Y: >
+
+     jump line  col file/text
+       4  1260    8 mark.c		<-- location X-2
+       3   685    0 eval.c		<-- location X-1
+       2   462   36 eval.c		<-- location X
+       1   100    0 buffer.c	<-- location Y
+    >
+<
 CHANGE LIST JUMPS			*changelist* *change-list-jumps* *E664*
 
 When making a change the cursor position is remembered.  One position is
diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index 6c82fa4959..c5123289ad 100644
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -4899,6 +4899,16 @@ A jump table for the options with a short description can be found at |Q_op|.
 	Otherwise only one space is inserted.
 	NOTE: This option is set when 'compatible' is set.
 
+						*'jumpoptions'* *'jop'*
+'jumpoptions' 'jop'	string	(default "")
+			global
+	List of words that change the behavior of the |jumplist|.
+	  stack         Make the jumplist behave like the tagstack.
+			Relative location of entries in the jumplist is
+			preserved at the cost of discarding subsequent entries
+			when navigating backwards in the jumplist and then
+			jumping to a location.  |jumplist-stack|
+
 							*'key'*
 'key'			string	(default "")
 			local to buffer
diff --git a/runtime/doc/quickref.txt b/runtime/doc/quickref.txt
index ffdfd108ac..65a560a30f 100644
--- a/runtime/doc/quickref.txt
+++ b/runtime/doc/quickref.txt
@@ -772,6 +772,7 @@ Short explanation of each option:		*option-list*
 'iskeyword'	  'isk'     characters included in keywords
 'isprint'	  'isp'     printable characters
 'joinspaces'	  'js'	    two spaces after a period with a join command
+'jumpoptions'	  'jop'     specifies how jumping is done
 'key'			    encryption key
 'keymap'	  'kmp'     name of a keyboard mapping
 'keymodel'	  'km'	    enable starting/stopping selection with keys
diff --git a/runtime/doc/tags b/runtime/doc/tags
index 8cfd1881cd..38d6b09fd4 100644
--- a/runtime/doc/tags
+++ b/runtime/doc/tags
@@ -433,7 +433,9 @@ $quote	eval.txt	/*$quote*
 'isp'	options.txt	/*'isp'*
 'isprint'	options.txt	/*'isprint'*
 'joinspaces'	options.txt	/*'joinspaces'*
+'jop'	options.txt	/*'jop'*
 'js'	options.txt	/*'js'*
+'jumpoptions'	options.txt	/*'jumpoptions'*
 'key'	options.txt	/*'key'*
 'keymap'	options.txt	/*'keymap'*
 'keymodel'	options.txt	/*'keymodel'*
@@ -8300,6 +8302,7 @@ json_encode()	builtin.txt	/*json_encode()*
 jtags	tagsrch.txt	/*jtags*
 jump-motions	motion.txt	/*jump-motions*
 jumplist	motion.txt	/*jumplist*
+jumplist-stack	motion.txt	/*jumplist-stack*
 jumpto-diffs	diff.txt	/*jumpto-diffs*
 k	motion.txt	/*k*
 kcc	uganda.txt	/*kcc*