runtime(doc): buffers can be re-used

while at it, also move the note about :wincmd
directly to :h :wincmd, it doesn't seem to belong to the buffer section.

closes: #15636

Signed-off-by: Christian Brabandt <cb@256bit.org>

diff --git a/runtime/doc/tags b/runtime/doc/tags
index c5801af00d18c1232b7c25b5a84c4674b8146dc6..bd47526613b966da0b36c9f1b43342e2fc22ec20 100644 (file)
--- a/runtime/doc/tags
+++ b/runtime/doc/tags
@@ -6192,6 +6192,7 @@ bufexists()       builtin.txt     /*bufexists()*
 buffer-functions       usr_41.txt      /*buffer-functions*
 buffer-hidden  windows.txt     /*buffer-hidden*
 buffer-list    windows.txt     /*buffer-list*
+buffer-reuse   windows.txt     /*buffer-reuse*
 buffer-variable        eval.txt        /*buffer-variable*
 buffer-write   editing.txt     /*buffer-write*
 buffer_exists()        builtin.txt     /*buffer_exists()*

diff --git a/runtime/doc/windows.txt b/runtime/doc/windows.txt
index d3e5f6785861a7753889eaf637b1d9e8e2a60916..46b75bdff8efaaf6338b536e7b978a5b7cde4388 100644 (file)
--- a/runtime/doc/windows.txt
+++ b/runtime/doc/windows.txt
@@ -1,4 +1,4 @@
-*windows.txt*   For Vim version 9.1.  Last change: 2024 Jul 09
+*windows.txt*   For Vim version 9.1.  Last change: 2024 Sep 07
 
 
                  VIM REFERENCE MANUAL    by Bram Moolenaar
@@ -67,11 +67,17 @@ active                yes            yes              'a'
 hidden           no             yes              'h'
 inactive         no             no               ' '
 
-Note: All CTRL-W commands can also be executed with |:wincmd|, for those
-places where a Normal mode command can't be used or is inconvenient.
+                                                       *buffer-reuse*
+Each buffer has a unique number and the number will not change within a Vim
+session.  The |bufnr()| and |bufname()| functions can be used to convert
+between a buffer name and the buffer number.  There is one exception: if a new
+empty buffer is created and it is not modified, the buffer will be re-used
+when loading another file into that buffer. This also means the buffer number
+will not change.
 
 The main Vim window can hold several split windows.  There are also tab pages
 |tab-page|, each of which can hold multiple windows.
+
                                        *window-ID* *winid* *windowid*
 Each window has a unique identifier called the window ID.  This identifier
 will not change within a Vim session. The |win_getid()| and |win_id2tabwin()|
@@ -83,9 +89,6 @@ across tabs.  For most functions that take a window ID or a window number, the
 window number only applies to the current tab, while the window ID can refer
 to a window in any tab.
 
-Each buffer has a unique number and the number will not change within a Vim
-session.  The |bufnr()| and |bufname()| functions can be used to convert
-between a buffer name and the buffer number.
 
 ==============================================================================
 2. Starting Vim                                                *windows-starting*
@@ -485,6 +488,10 @@ These commands can also be executed with ":wincmd":
                        :exe nr .. "wincmd w"
 <              This goes to window "nr".
 
+Note: All CTRL-W commands can also be executed with |:wincmd|, for those
+places where a Normal mode command can't be used or is inconvenient (e.g.
+in a browser-based terminal).
+
 ==============================================================================
 5. Moving windows around                               *window-moving*