jumplist: browser-style (or 'tagstack') navigation #11530

Traditionally, when navigating to a specific location from the middle of
the jumplist results in shifting the current location to the bottom of
the list and adding the new location after it.  This behavior is not
desireable to all users--see, for example
https://vi.stackexchange.com/questions/18344/how-to-change-jumplist-behavior.

Here, another jumplist behavior is introduced.  When jumpoptions (a new
option set added here) includes stack, the jumplist behaves like the
tagstack or like history in a web browser.  That is, when navigating to
a location from the middle of the jumplist

    2 first
    1 second
    0 third <-- current location
    1 fourth
    2 fifth

to a new location the locations after the current location in the jump
list are discarded

    2 first
    1 second
    0 third
            <-- current location

The result is that when moving forward from that location, the new
location will be appended to the jumplist:

    3 first
    2 second
    1 third
    0 new

If the new location is the same

  new == second

as some previous (but not immediately prior) entry in the jumplist,

    2 first
    1 second
    0 third <-- current location
    1 fourth
    2 fifth

both occurrences preserved

    3 first
    2 second
    1 third
    0 second (new)

when moving forward from that location.

It would be desireable to go farther and, when the new location is the
same as the location that is currently next in the jumplist,

    new == fourth

make the result of navigating to the new location by jumping (e.g. 50gg)
be the same as moving forward in the jumplist

    2 first
    1 second
    0 third
    1 new <-- current location
    2 fifth

and simply increment the jumplist index.  That change is NOT part of
this patch because it would require passing the new cursor location to
the function (setpcmark) from all of its callees.  That in turn would
require those callees to know *before* calling what the new cursor
location is, which do they do not currently.

4 files changed, 71 insertions, 0 deletions

diff --git a/runtime/doc/motion.txt b/runtime/doc/motion.txt
index 07ff4cf030..3947e583b7 100644
--- a/runtime/doc/motion.txt
+++ b/runtime/doc/motion.txt
@@ -1083,6 +1083,60 @@ When you split a window, the jumplist will be copied to the new window.
 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 neovim 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
+
+jumping to location Y results in the locations after the current 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
+> 
+
+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
+> 
 
 CHANGE LIST JUMPS			*changelist* *change-list-jumps* *E664*
 
diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index 95265fa153..4b8740c5d2 100644
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -3457,6 +3457,17 @@ A jump table for the options with a short description can be found at |Q_op|.
 	Unprintable and zero-width Unicode characters are displayed as <xxxx>.
 	There is no option to specify these characters.
 
+						*'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 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|
+
 			*'joinspaces'* *'js'* *'nojoinspaces'* *'nojs'*
 'joinspaces' 'js'	boolean	(default on)
 			global
diff --git a/runtime/doc/quickref.txt b/runtime/doc/quickref.txt
index dfa7218bdf..224f14a18b 100644
--- a/runtime/doc/quickref.txt
+++ b/runtime/doc/quickref.txt
@@ -743,6 +743,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
 'keymap'	  'kmp'     name of a keyboard mapping
 'keymodel'	  'km'	    enable starting/stopping selection with keys
 'keywordprg'	  'kp'	    program to use for the "K" command
diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt
index 9c106077ab..64b5830575 100644
--- a/runtime/doc/vim_diff.txt
+++ b/runtime/doc/vim_diff.txt
@@ -336,6 +336,11 @@ Macro/|recording| behavior
 Motion:
   The |jumplist| avoids useless/phantom jumps.
 
+  When the new option |jumpoptions| includes 'stack', the jumplist behaves
+  like the tagstack or history in a web browser--jumping from the middle of
+  the jumplist discards the locations after the jumped-from position
+  (|jumplist-stack|).
+
 Normal commands:
   |Q| is the same as |gQ|