master bf3d296d24e: ; Fix documentation of a recent change (bug#68235)

[Eli Zaretskii]

branch: master
commit bf3d296d24ea24fb707a9410fccd745523347d2a
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    ; Fix documentation of a recent change (bug#68235)
    
    * etc/NEWS:
    * doc/lispref/windows.texi (Window Configurations): Improve
    wording of 'window-restore-killed-buffer-windows's doc.
    * src/window.c (syms_of_window)
    <window-restore-killed-buffer-windows>: Doc fix.
    
    * etc/NEWS:
    * doc/lispref/buffers.texi (Buffer Names): Document
    'buffer-last-name'.
---
 doc/lispref/buffers.texi |  6 ++++++
 doc/lispref/windows.texi | 39 ++++++++++++++++++----------------
 etc/NEWS                 |  6 +++++-
 src/window.c             | 54 +++++++++++++++++++++++++-----------------------
 4 files changed, 60 insertions(+), 45 deletions(-)

diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi
index 77f5f09c7bd..5375eb64155 100644
--- a/doc/lispref/buffers.texi
+++ b/doc/lispref/buffers.texi
@@ -371,6 +371,12 @@ See the related function @code{generate-new-buffer} in 
@ref{Creating
 Buffers}.
 @end defun
 
+@defun buffer-last-name &optional buffer
+This function returns the previous name of @var{buffer}, before it was
+killed or before the last time it was renamed.  If nil or omitted,
+@var{buffer} defaults to the current buffer.
+@end defun
+
 @node Buffer File Name
 @section Buffer File Name
 @cindex visited file
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 45d67ba4946..8fa4e57b153 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -6376,8 +6376,8 @@ fine-tune that behavior.
 @defvar window-restore-killed-buffer-windows
 This variable specifies how @code{set-window-configuration} and
 @code{window-state-put} shall handle a window whose buffer has been
-killed since the corresponding configuration or state was made.  Any
-such window may be live - in which case it shows some other buffer - or
+killed since the corresponding configuration or state was recorded.  Any
+such window may be live---in which case it shows some other buffer---or
 dead at the time one of these functions is called.  Usually,
 @code{set-window-configuration} leaves the window alone if it is live
 while @code{window-state-put} deletes it.
@@ -6399,14 +6399,15 @@ This means to try to delete the window if and only if 
it is dedicated to
 its buffer.
 
 @item @code{nil}
-This is the default and means that @code{set-window-configuration} will
-try to delete the window if and only if it is dedicated to its buffer
-and @code{window-state-put} will unconditionally try to delete it.
+This is the default, and it means that @code{set-window-configuration}
+will try to delete the window if and only if it is dedicated to its
+buffer, and @code{window-state-put} will unconditionally try to delete
+it.
 
 @item a function
-This means to restore the window, show some other buffer in it and add
-an entry for that window to a list that will be later passed as argument
-to that function.
+This means to restore the window and show some other buffer in it, like
+if the value is @code{t}, and also add an entry for that window to a
+list that will be later passed as the second argument to that function.
 @end table
 
 If a window cannot be deleted (typically, because it is the last window
@@ -6417,21 +6418,23 @@ If the value of this variable is a function, that 
function should take
 three arguments.  The first argument specifies the frame whose windows
 have been restored.  The third argument is either the constant
 @code{configuration} if the windows are restored by
-@code{set-window-configuration} or the constant @code{state} if the
+@code{set-window-configuration}, or the constant @code{state} if the
 windows are restored by @code{window-state-put}.
 
-The second argument specifies a list of entries for @emph{any} window
-whose previous buffer has been encountered dead at the time
+The second argument specifies a list of entries for @emph{all} windows
+whose previous buffers have been found dead at the time
 @code{set-window-configuration} or @code{window-state-put} tried to
 restore it in that window (minibuffer windows are excluded).  This means
-that the function specified by this variable may also delete windows
-encountered live by @code{set-window-configuration}.
-
-Each entry is a list of six values - the window whose buffer was found
-dead, the dead buffer or its name, the positions of start and point of
-the buffer in that window, the dedicated status of the window as
+that the function may also delete windows which were found live by
+@code{set-window-configuration}.
+
+Each entry in the list that is passed as the second argument to the
+function is itself a list of six values: the window whose buffer was
+found dead, the dead buffer or its name, the positions of window-start
+(@pxref{Window Start and End}) and window-point (@pxref{Window Point})
+of the buffer in that window, the dedicated state of the window as
 previously reported by @code{window-dedicated-p} and a flag that is
-@code{t} if the window has been encountered live by
+@code{t} if the window has been found to be alive by
 @code{set-window-configuration} and @code{nil} otherwise.
 @end defvar
 
diff --git a/etc/NEWS b/etc/NEWS
index dfbf6edb098..a654d2d8d79 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -287,7 +287,7 @@ selected or deselected at the end of executing the current 
command.
 *** New variable 'window-restore-killed-buffer-windows'.
 It specifies how 'set-window-configuration' and 'window-state-put'
 should proceed with windows whose buffer was killed after the
-corresponding configuration or state was made.
+corresponding configuration or state was recorded.
 
 ** Tab Bars and Tab Lines
 
@@ -1812,6 +1812,10 @@ styles to skip eager fontification of completion 
candidates, which
 improves performance.  Such a Lisp program can then use the
 'completion-lazy-hilit' function to fontify candidates just in time.
 
+** New primitive 'buffer-last-name'.
+It returns the name of a buffer before the last time it was renamed or
+killed.
+
 ** Functions and variables to transpose sexps
 
 +++
diff --git a/src/window.c b/src/window.c
index 928c4ae02a8..2c002418605 100644
--- a/src/window.c
+++ b/src/window.c
@@ -8675,30 +8675,32 @@ call is performed with the frame temporarily selected.  
*/);
               doc: /* Control restoring windows whose buffer was killed.
 This variable specifies how the functions `set-window-configuration' and
 `window-state-put' shall handle a window whose buffer has been killed
-since the corresponding configuration or state was made.  Any such
-window may be live - in which case it shows some other buffer - or dead
-at the time one of these functions is called.
+since the corresponding configuration or state was recorded.  Any such
+window may be live -- in which case it shows some other buffer -- or
+dead at the time one of these functions is called.
 
-As a rule, `set-window-configuration' leaves the window alone if it is
-live while `window-state-put' deletes it.  The following values can be
+By default, `set-window-configuration' leaves the window alone if it is
+live, while `window-state-put' deletes it.  The following values can be
 used to override the default behavior for dead windows in the case of
 `set-window-configuration' and for dead and live windows in the case of
 `window-state-put'.
 
-- t means to restore the window and show some other buffer in it.
+ - t means to restore the window and show some other buffer in it.
 
-- `delete' means to try to delete the window.
+ - `delete' means to try to delete the window.
 
-- `dedicated' means to try to delete the window if and only if it is
-  dedicated to its buffer.
+ - `dedicated' means to try to delete the window if and only if it is
+   dedicated to its buffer.
 
-- nil, the default, means that `set-window-configuration' will try to
-  delete the window if and only if it is dedicated to its buffer while
-  `window-state-put' will unconditionally try to delete it.
+ - nil, the default, which means that `set-window-configuration' will
+   try to delete the window if and only if it is dedicated to its
+   buffer while `window-state-put' will unconditionally try to delete
+   it.
 
-- a function means to restore the window, show some other buffer in it
-  and add an entry for that window to a list that will be later passed
-  as argument to that function.
+ - a function means to restore the window and show some other buffer in
+   it, like if the value were t, but also to add an entry for that
+   window to a list that will be later passed as argument to that
+   function.
 
 If a window cannot be deleted (typically, because it is the last window
 on its frame), show another buffer in it.
@@ -8709,19 +8711,19 @@ third argument is the constant `configuration' if the 
windows are
 restored by `set-window-configuration' and the constant `state' if the
 windows are restored by `window-state-put'.
 
-The second argument specifies a list of entries for @emph{any} window
-whose previous buffer has been encountered dead at the time
+The second argument specifies a list of entries for all windows
+whose previous buffers have been found dead at the time
 `set-window-configuration' or `window-state-put' tried to restore it in
 that window (minibuffer windows are excluded).  This means that the
-function specified by this variable may also delete windows encountered
-live by `set-window-configuration'.
-
-Each entry is a list of six values - the window whose buffer was found
-dead, the dead buffer or its name, the positions of start and point of
-the buffer in that window, the dedicated status of the window as
-reported by `window-dedicated-p' and a boolean - t if the window was
-live when `set-window-configuration' tried to restore it and nil
-otherwise.  */);
+function specified by this variable may also delete windows which were
+found to be alive by `set-window-configuration'.
+
+Each entry is a list of six values: the window whose buffer was found
+dead, the dead buffer or its name, the positions of window-start and
+window-point of the buffer in that window, the dedicated state of the
+window as reported by `window-dedicated-p', and a boolean -- t if the
+window was live when `set-window-configuration' tried to restore it,
+and nil otherwise.  */);
   window_restore_killed_buffer_windows = Qnil;
 
   DEFVAR_LISP ("recenter-redisplay", Vrecenter_redisplay,