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>

3 files changed, 44 insertions, 61 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