From 16e9bdff4f47534d62ac9ebec9c6c49fe5a0e180 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Fri, 30 Jun 2023 10:13:53 +0300 Subject: [PATCH] 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: ") -- 2.39.2