emacs-29 16e9bdff4f4: Improve documentation of registers

[Eli Zaretskii]

branch: emacs-29
commit 16e9bdff4f47534d62ac9ebec9c6c49fe5a0e180
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    Improve documentation of registers
    
    * doc/lispref/text.texi (Registers): Document buffers in
    registers.  Mention "frameset" as another name for "frame
    configuration".
    * doc/emacs/regs.texi (Registers, Configuration Registers)
    (File and Buffer Registers): Clarify and improve wording.  Add
    cross-references and indexing.
    (Configuration Registers): Rename the section to a more accurate
    name.  (Bug#64354)
    
    * lisp/register.el (jump-to-register, point-to-register)
    (register-alist, frame-configuration-to-register): Doc fixes.
    (Bug#64353)
---
 doc/emacs/emacs.texi  |  2 +-
 doc/emacs/regs.texi   | 29 ++++++++++++++++++-----------
 doc/lispref/text.texi | 13 +++++++++----
 lisp/register.el      | 14 +++++++++-----
 4 files changed, 37 insertions(+), 21 deletions(-)

diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi
index 7071ea44edd..0efd99261ac 100644
--- a/doc/emacs/emacs.texi
+++ b/doc/emacs/emacs.texi
@@ -349,7 +349,7 @@ Registers
 * Position Registers::        Saving positions in registers.
 * Text Registers::            Saving text in registers.
 * Rectangle Registers::       Saving rectangles in registers.
-* Configuration Registers::   Saving window configurations in registers.
+* Configuration Registers::   Saving window/frame configurations in registers.
 * Number Registers::          Numbers in registers.
 * File and Buffer Registers:: File and buffer names in registers.
 * Keyboard Macro Registers::  Keyboard macros in registers.
diff --git a/doc/emacs/regs.texi b/doc/emacs/regs.texi
index ec2367d71e3..2bc4640cbf4 100644
--- a/doc/emacs/regs.texi
+++ b/doc/emacs/regs.texi
@@ -22,10 +22,11 @@ because these keys are reserved for quitting 
(@pxref{Quitting}).
 
 @findex view-register
   A register can store a position, a piece of text, a rectangle, a
-number, a window configuration, or a file name, but only one thing at
-any given time.  Whatever you store in a register remains there until
-you store something else in that register.  To see what register
-@var{r} contains, use @kbd{M-x view-register}:
+number, a window or frame configuration, a buffer name, or a file
+name, but only one thing at any given time.  Whatever you store in a
+register remains there until you store something else in that
+register.  To see what register @var{r} contains, use @kbd{M-x
+view-register}:
 
 @table @kbd
 @item M-x view-register @key{RET} @var{r}
@@ -50,7 +51,7 @@ this chapter.
 * Position Registers::        Saving positions in registers.
 * Text Registers::            Saving text in registers.
 * Rectangle Registers::       Saving rectangles in registers.
-* Configuration Registers::   Saving window configurations in registers.
+* Configuration Registers::   Saving window/frame configurations in registers.
 * Number Registers::          Numbers in registers.
 * File and Buffer Registers:: File and buffer names in registers.
 * Keyboard Macro Registers::  Keyboard macros in registers.
@@ -182,8 +183,10 @@ previously documented in @ref{Text Registers}, inserts a 
rectangle
 rather than a text string, if the register contains a rectangle.
 
 @node Configuration Registers
-@section Saving Window Configurations in Registers
+@section Saving Window and Frame Configurations in Registers
 @cindex saving window configuration in a register
+@cindex saving frame configuration in a register
+@cindex frameset, saving in a register
 
 @findex window-configuration-to-register
 @findex frameset-to-register
@@ -191,16 +194,17 @@ rather than a text string, if the register contains a 
rectangle.
 @kindex C-x r f
   You can save the window configuration of the selected frame in a
 register, or even the configuration of all windows in all frames, and
-restore the configuration later.  @xref{Windows}, for information
-about window configurations.
+restore the configuration later.  @xref{Windows Convenience}, for
+information about window configurations.
 
 @table @kbd
 @item C-x r w @var{r}
 Save the state of the selected frame's windows in register @var{r}
 (@code{window-configuration-to-register}).
+@cindex frameset
 @item C-x r f @var{r}
-Save the state of all frames, including all their windows, in register
-@var{r} (@code{frameset-to-register}).
+Save the state of all frames, including all their windows (a.k.a.@:
+@dfn{frameset}), in register @var{r} (@code{frameset-to-register}).
 @end table
 
   Use @kbd{C-x r j @var{r}} to restore a window or frame configuration.
@@ -266,7 +270,7 @@ puts the file name shown in register @samp{z}.
 @var{r}}.  (This is the same command used to jump to a position or
 restore a frame configuration.)
 
-  Similarly, if there's certain buffers you visit frequently, you
+  Similarly, if there are certain buffers you visit frequently, you
 can put their names in registers.  For instance, if you visit the
 @samp{*Messages*} buffer often, you can use the following snippet to
 put that buffer into the @samp{m} register:
@@ -275,6 +279,9 @@ put that buffer into the @samp{m} register:
 (set-register ?m '(buffer . "*Messages*"))
 @end smallexample
 
+  To switch to the buffer whose name is in register @var{r}, type
+@kbd{C-x r j @var{r}}.
+
 @node Keyboard Macro Registers
 @section Keyboard Macro Registers
 @cindex saving keyboard macro in a register
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 0f43f3d464a..af6d6638b36 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -4642,20 +4642,25 @@ A rectangle is represented by a list of strings.
 This represents a window configuration to restore in one frame, and a
 position to jump to in the current buffer.
 
-@c FIXME: Mention frameset here.
+@cindex frameset
 @item @code{(@var{frame-configuration} @var{position})}
 This represents a frame configuration to restore, and a position
-to jump to in the current buffer.
+to jump to in the current buffer.  Frame configurations are also
+known as @dfn{framesets}.
 
-@item (file @var{filename})
+@item @code{(file @var{filename})}
 This represents a file to visit; jumping to this value visits file
 @var{filename}.
 
-@item (file-query @var{filename} @var{position})
+@item @code{(file-query @var{filename} @var{position})}
 This represents a file to visit and a position in it; jumping to this
 value visits file @var{filename} and goes to buffer position
 @var{position}.  Restoring this type of position asks the user for
 confirmation first.
+
+@item @code{(buffer @var{buffer-name})}
+This represents a buffer; jumping to this value switches to buffer
+@var{buffer-name}.
 @end table
 
   The functions in this section return unpredictable values unless
diff --git a/lisp/register.el b/lisp/register.el
index d30114bfbc7..667e03418bd 100644
--- a/lisp/register.el
+++ b/lisp/register.el
@@ -69,10 +69,12 @@ A list of the form (file . FILE-NAME) represents the file 
named FILE-NAME.
 A list of the form (file-query FILE-NAME POSITION) represents
  position POSITION in the file named FILE-NAME, but query before
  visiting it.
+A list of the form (buffer . BUFFER-NAME) represents the buffer BUFFER-NAME.
 A list of the form (WINDOW-CONFIGURATION POSITION)
  represents a saved window configuration plus a saved value of point.
 A list of the form (FRAME-CONFIGURATION POSITION)
- represents a saved frame configuration plus a saved value of point.")
+ represents a saved frame configuration (a.k.a. \"frameset\") plus
+ a saved value of point.")
 
 (defgroup register nil
   "Register commands."
@@ -179,7 +181,7 @@ display such a window regardless."
 
 (defun point-to-register (register &optional arg)
   "Store current location of point in register REGISTER.
-With prefix argument, store current frame configuration.
+With prefix argument, store current frame configuration (a.k.a. \"frameset\").
 Use \\[jump-to-register] to go to that location or restore that configuration.
 Argument is a character, naming the register.
 
@@ -214,6 +216,7 @@ Interactively, reads the register using 
`register-read-with-preview'."
 
 (defun frame-configuration-to-register (register &optional _arg)
   "Store the window configuration of all frames in register REGISTER.
+\(This window configuration is also known as \"frameset\").
 Use \\[jump-to-register] to restore the configuration.
 Argument is a character, naming the register.
 
@@ -240,9 +243,10 @@ If the register contains a file name, find that file.
 If the register contains a window configuration (one frame) or a frameset
 \(all frames), restore that frame or all frames accordingly.
 First argument is a character, naming the register.
-Optional second arg non-nil (interactively, prefix argument) says to
-delete any existing frames that the frameset doesn't mention.
-\(Otherwise, these frames are iconified.)
+Optional second arg DELETE non-nil (interactively, prefix argument) says
+to delete any existing frames that the frameset doesn't mention.
+\(Otherwise, these frames are iconified.)  This argument is currently
+ignored if the register contains anything but a frameset.
 
 Interactively, reads the register using `register-read-with-preview'."
   (interactive (list (register-read-with-preview "Jump to register: ")