patch 9.1.0170: Re-allow curwin == prevwin, but document it insteadv9.1.0170

Problem:  more places exist where curwin == prevwin, and it may even be
          expected in some cases.
Solution: revert v9.1.0001, but document that it's possible instead.
          (Sean Dewar)

I've had a change of heart for the following reasons:

- A quick 'n dirty [GitHub code
  search](https://github.com/search?q=%2F%28winnr%5C%28%5C%29%5Cs*%3D%3D%5Cs*winnr%5C%28%5B%27%22%5D%23%5B%27%22%5D%5C%29%7Cwinnr%5C%28%5B%27%22%5D%23%5B%27%22%5D%5C%29%5Cs*%3D%3D%5Cs*winnr%5C%28%5C%29%29%2F&type=code)
  reveals some cases where it's expected in the wild.

  Particularly, it made me aware `winnr() == winnr('#')` is possible when curwin
  is changed temporarily during the evaluation of a &statusline expression item
  (`%{...}`), and is used to show something different on the statusline
  belonging to the previous window; that behaviour wasn't changed in v9.1.0001,
  but it means curwin == prevwin makes sense in some cases.

- The definition and call sites of back_to_prevwin imply some expectation that
  prevwin == wp (== curwin) is possible, as it's used to skip entering the
  prevwin in that case.

- Prior to v9.1.0001, `:wincmd p` would not beep in the case that was patched in
  v9.1.0001, but now does. That resulted in #14047 being opened, as it affected
  the CtrlP plugin.

  I find it odd that `:wincmd p` had cases where it wouldn't beep despite doing
  nothing, but it may be preferable to keep things that way (or instead also
  beep if curwin == prevwin, if that's preferred).

- After more digging, I found cases in win_free_mem, enter_tabpage,
  aucmd_restbuf and qf_open_new_cwindow where curwin == prevwin is possible
  (many of them from autocommands). Others probably exist too, especially in
  places where curwin is changed temporarily.

fixes: #14047
closes: #14186

Signed-off-by: Sean Dewar <6256228+seandewar@users.noreply.github.com>
Signed-off-by: Christian Brabandt <cb@256bit.org>

1 files changed, 4 insertions, 2 deletions

diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index fb957e54a9..941c6a76ef 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -1,4 +1,4 @@
-*builtin.txt*	For Vim version 9.1.  Last change: 2024 Mar 07
+*builtin.txt*	For Vim version 9.1.  Last change: 2024 Mar 12
 
 
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
@@ -10947,7 +10947,9 @@ winnr([{arg}])	The result is a Number, which is the number of the current
 			#	the number of the last accessed window (where
 				|CTRL-W_p| goes to).  If there is no previous
 				window or it is in another tab page 0 is
-				returned.
+				returned.  May refer to the current window in
+				some cases (e.g. when evaluating 'statusline'
+				expressions).
 			{N}j	the number of the Nth window below the
 				current window (where |CTRL-W_j| goes to).
 			{N}k	the number of the Nth window above the current