vim-patch:9.0.1921: not possible to use the jumplist like a stack (#25278)

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: vim/vim#7738
closes: vim/vim#13134

ported from NeoVim:

- https://neovim.io/doc/user/motion.html#jumplist-stack
- neovim/neovim@39094b3
- 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.

https://github.com/vim/vim/commit/87018255e3ad0f4dfa03e20318836d24af721caf

Co-authored-by: Yegappan Lakshmanan <yegappan@yahoo.com>
Co-authored-by: butwerenotthereyet <58348703+butwerenotthereyet@users.noreply.github.com>

6 files changed, 116 insertions, 68 deletions

diff --git a/runtime/doc/motion.txt b/runtime/doc/motion.txt
index dc92601bfc..c4e144ab29 100644
--- a/runtime/doc/motion.txt
+++ b/runtime/doc/motion.txt
@@ -1115,60 +1115,45 @@ If you have included the ' item in the 'shada' option the jumplist will be
 stored in the ShaDa file and restored when starting Vim.
 
 							*jumplist-stack*
-When jumpoptions includes "stack", the jumplist behaves like the history in a
-web browser and 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.
-
-This behavior corresponds to the following situation in a web browser.
-Navigate to first.com, second.com, third.com, fourth.com and then fifth.com.
-Then navigate backwards twice so that third.com is displayed.  At that point,
-the history is:
-- first.com
-- second.com
-- third.com <--
-- fourth.com
-- fifth.com
-
-Finally, navigate to a different webpage, new.com.  The history is
-- first.com
-- second.com
-- third.com
-- new.com <--
-
-When the jumpoptions includes "stack", this is the behavior of Nvim as well.
-That is, 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 src/nvim/mark.c         <-- location X-2
-   1   685    0 src/nvim/option_defs.h  <-- location X-1
->  0   462   36 src/nvim/option_defs.h  <-- location X
-   1   479   39 src/nvim/option_defs.h
-   2   213    2 src/nvim/mark.c
-   3   181    0 src/nvim/mark.c
-
+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:
+locations being removed: >
 
- jump line  col file/text
-   3  1260    8 src/nvim/mark.c
-   2   685    0 src/nvim/option_defs.h
-   1   462   36 src/nvim/option_defs.h  <-- location X
->
+     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 src/nvim/mark.c         <-- location X-2
-   3   685    0 src/nvim/option_defs.h  <-- location X-1
-   2   462   36 src/nvim/option_defs.h  <-- location X
-   1   100    0 src/nvim/option_defs.h  <-- location Y
->
-
+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 96bf2eef63..deb64bf18d 100644
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -3569,12 +3569,11 @@ A jump table for the options with a short description can be found at |Q_op|.
 'jumpoptions' 'jop'	string	(default "")
 			global
 	List of words that change the behavior of the |jumplist|.
-	  stack         Make the jumplist behave like the tagstack or like a
-	                web browser.  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|
+	  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|
 
 	  view          When moving through the jumplist, |changelist|,
 			|alternate-file| or using |mark-motions| try to
diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua
index 734096a755..b8bdfbc3f7 100644
--- a/runtime/lua/vim/_meta/options.lua
+++ b/runtime/lua/vim/_meta/options.lua
@@ -3485,12 +3485,11 @@ vim.go.joinspaces = vim.o.joinspaces
 vim.go.js = vim.go.joinspaces
 
 --- List of words that change the behavior of the `jumplist`.
----   stack         Make the jumplist behave like the tagstack or like a
----                 web browser.  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`
+---   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`
 ---
 ---   view          When moving through the jumplist, `changelist|,
 --- 		|alternate-file` or using `mark-motions` try to
diff --git a/src/nvim/options.lua b/src/nvim/options.lua
index 2a1c76fd9a..e5821b62bd 100644
--- a/src/nvim/options.lua
+++ b/src/nvim/options.lua
@@ -4443,12 +4443,11 @@ return {
       deny_duplicates = true,
       desc = [=[
         List of words that change the behavior of the |jumplist|.
-          stack         Make the jumplist behave like the tagstack or like a
-                        web browser.  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|
+          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|
 
           view          When moving through the jumplist, |changelist|,
         		|alternate-file| or using |mark-motions| try to
diff --git a/src/nvim/optionstr.c b/src/nvim/optionstr.c
index 17afd10ee3..cf8e6cf641 100644
--- a/src/nvim/optionstr.c
+++ b/src/nvim/optionstr.c
@@ -151,13 +151,13 @@ void didset_string_options(void)
   (void)opt_strings_flags(p_vop, p_ssop_values, &vop_flags, true);
   (void)opt_strings_flags(p_fdo, p_fdo_values, &fdo_flags, true);
   (void)opt_strings_flags(p_dy, p_dy_values, &dy_flags, true);
+  (void)opt_strings_flags(p_jop, p_jop_values, &jop_flags, true);
   (void)opt_strings_flags(p_rdb, p_rdb_values, &rdb_flags, true);
   (void)opt_strings_flags(p_tc, p_tc_values, &tc_flags, false);
   (void)opt_strings_flags(p_tpf, p_tpf_values, &tpf_flags, true);
   (void)opt_strings_flags(p_ve, p_ve_values, &ve_flags, true);
   (void)opt_strings_flags(p_swb, p_swb_values, &swb_flags, true);
   (void)opt_strings_flags(p_wop, p_wop_values, &wop_flags, true);
-  (void)opt_strings_flags(p_jop, p_jop_values, &jop_flags, true);
   (void)opt_strings_flags(p_cb, p_cb_values, &cb_flags, true);
 }
 
diff --git a/test/old/testdir/test_jumplist.vim b/test/old/testdir/test_jumplist.vim
index 91ad940e18..b4dcdad9d6 100644
--- a/test/old/testdir/test_jumplist.vim
+++ b/test/old/testdir/test_jumplist.vim
@@ -104,4 +104,70 @@ d
   bwipe!
 endfunc
 
+" Test for 'jumpoptions'
+func Test_jumpoptions()
+  new
+  call setline(1, range(1, 200))
+  clearjumps
+  set jumpoptions=stack
+
+  " Jump around to add some locations to the jump list.
+  normal 10G
+  normal 20G
+  normal 30G
+  normal 40G
+  normal 50G
+  let bnr = bufnr()
+
+  " discards the tail when navigating from the middle
+  exe "normal \<C-O>\<C-O>"
+  call assert_equal([
+        \ [{'lnum': 1, 'bufnr': bnr, 'col': 0, 'coladd': 0},
+        \  {'lnum': 10, 'bufnr': bnr, 'col': 0, 'coladd': 0},
+        \  {'lnum': 20, 'bufnr': bnr, 'col': 0, 'coladd': 0},
+        \  {'lnum': 30, 'bufnr': bnr, 'col': 0, 'coladd': 0},
+        \  {'lnum': 40, 'bufnr': bnr, 'col': 0, 'coladd': 0},
+        \  {'lnum': 50, 'bufnr': bnr, 'col': 0, 'coladd': 0}
+        \ ], 3], getjumplist())
+
+  " new jump location is added immediately after the last one
+  normal 90G
+  call assert_equal([
+        \ [{'lnum': 1, 'bufnr': bnr, 'col': 0, 'coladd': 0},
+        \  {'lnum': 10, 'bufnr': bnr, 'col': 0, 'coladd': 0},
+        \  {'lnum': 20, 'bufnr': bnr, 'col': 0, 'coladd': 0},
+        \  {'lnum': 30, 'bufnr': bnr, 'col': 0, 'coladd': 0},
+        \ ], 4], getjumplist())
+
+  " does not add the same location twice adjacently
+  normal 60G
+  normal 60G
+  call assert_equal([
+        \ [{'lnum': 1, 'bufnr': bnr, 'col': 0, 'coladd': 0},
+        \  {'lnum': 10, 'bufnr': bnr, 'col': 0, 'coladd': 0},
+        \  {'lnum': 20, 'bufnr': bnr, 'col': 0, 'coladd': 0},
+        \  {'lnum': 30, 'bufnr': bnr, 'col': 0, 'coladd': 0},
+        \  {'lnum': 90, 'bufnr': bnr, 'col': 0, 'coladd': 0},
+        "\ Nvim: avoids useless/phantom jumps
+        "\  {'lnum': 60, 'bufnr': bnr, 'col': 0, 'coladd': 0},
+        "\ ], 6], getjumplist())
+        \ ], 5], getjumplist())
+
+  " does add the same location twice non adjacently
+  normal 10G
+  normal 20G
+  call assert_equal([
+        \ [{'lnum': 1, 'bufnr': bnr, 'col': 0, 'coladd': 0},
+        \  {'lnum': 10, 'bufnr': bnr, 'col': 0, 'coladd': 0},
+        \  {'lnum': 20, 'bufnr': bnr, 'col': 0, 'coladd': 0},
+        \  {'lnum': 30, 'bufnr': bnr, 'col': 0, 'coladd': 0},
+        \  {'lnum': 90, 'bufnr': bnr, 'col': 0, 'coladd': 0},
+        \  {'lnum': 60, 'bufnr': bnr, 'col': 0, 'coladd': 0},
+        \  {'lnum': 10, 'bufnr': bnr, 'col': 0, 'coladd': 0},
+        \ ], 7], getjumplist())
+
+  set jumpoptions&
+  %bw!
+endfunc
+
 " vim: shiftwidth=2 sts=2 expandtab