procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Improve documentation of registers

Browse source 
* 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)
This commit is contained in:
Eli Zaretskii 2023-06-30 10:13:53 +03:00
parent 884b668b98
commit 16e9bdff4f
4 changed files with 37 additions and 21 deletions
Download patch file Download diff file Expand all files Collapse all files

2
doc/emacs/emacs.texi
View file

@ -349,7 +349,7 @@ Registers
* Position Registers:: Saving positions in registers. * Position Registers:: Saving positions in registers.
* Text Registers:: Saving text in registers. * Text Registers:: Saving text in registers.
* Rectangle Registers:: Saving rectangles 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. * Number Registers:: Numbers in registers.
* File and Buffer Registers:: File and buffer names in registers. * File and Buffer Registers:: File and buffer names in registers.
* Keyboard Macro Registers:: Keyboard macros in registers. * Keyboard Macro Registers:: Keyboard macros in registers.

29
doc/emacs/regs.texi
View file

@ -22,10 +22,11 @@ because these keys are reserved for quitting (@pxref{Quitting}).
@findex view-register @findex view-register
A register can store a position, a piece of text, a rectangle, a 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 number, a window or frame configuration, a buffer name, or a file
any given time. Whatever you store in a register remains there until name, but only one thing at any given time. Whatever you store in a
you store something else in that register. To see what register register remains there until you store something else in that
@var{r} contains, use @kbd{M-x view-register}: register. To see what register @var{r} contains, use @kbd{M-x
view-register}:
@table @kbd @table @kbd
@item M-x view-register @key{RET} @var{r} @item M-x view-register @key{RET} @var{r}
@ -50,7 +51,7 @@ this chapter.
* Position Registers:: Saving positions in registers. * Position Registers:: Saving positions in registers.
* Text Registers:: Saving text in registers. * Text Registers:: Saving text in registers.
* Rectangle Registers:: Saving rectangles 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. * Number Registers:: Numbers in registers.
* File and Buffer Registers:: File and buffer names in registers. * File and Buffer Registers:: File and buffer names in registers.
* Keyboard Macro Registers:: Keyboard macros 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. rather than a text string, if the register contains a rectangle.
@node Configuration Registers @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 window configuration in a register
@cindex saving frame configuration in a register
@cindex frameset, saving in a register
@findex window-configuration-to-register @findex window-configuration-to-register
@findex frameset-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 @kindex C-x r f
You can save the window configuration of the selected frame in a You can save the window configuration of the selected frame in a
register, or even the configuration of all windows in all frames, and register, or even the configuration of all windows in all frames, and
restore the configuration later. @xref{Windows}, for information restore the configuration later. @xref{Windows Convenience}, for
about window configurations. information about window configurations.
@table @kbd @table @kbd
@item C-x r w @var{r} @item C-x r w @var{r}
Save the state of the selected frame's windows in register @var{r} Save the state of the selected frame's windows in register @var{r}
(@code{window-configuration-to-register}). (@code{window-configuration-to-register}).
@cindex frameset
@item C-x r f @var{r} @item C-x r f @var{r}
Save the state of all frames, including all their windows, in register Save the state of all frames, including all their windows (a.k.a.@:
@var{r} (@code{frameset-to-register}). @dfn{frameset}), in register @var{r} (@code{frameset-to-register}).
@end table @end table
Use @kbd{C-x r j @var{r}} to restore a window or frame configuration. 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 @var{r}}. (This is the same command used to jump to a position or
restore a frame configuration.) 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 can put their names in registers. For instance, if you visit the
@samp{*Messages*} buffer often, you can use the following snippet to @samp{*Messages*} buffer often, you can use the following snippet to
put that buffer into the @samp{m} register: 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*")) (set-register ?m '(buffer . "*Messages*"))
@end smallexample @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 @node Keyboard Macro Registers
@section Keyboard Macro Registers @section Keyboard Macro Registers
@cindex saving keyboard macro in a register @cindex saving keyboard macro in a register

13
doc/lispref/text.texi
View file

@ -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 This represents a window configuration to restore in one frame, and a
position to jump to in the current buffer. position to jump to in the current buffer.
@c FIXME: Mention frameset here. @cindex frameset
@item @code{(@var{frame-configuration} @var{position})} @item @code{(@var{frame-configuration} @var{position})}
This represents a frame configuration to restore, and a 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 This represents a file to visit; jumping to this value visits file
@var{filename}. @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 This represents a file to visit and a position in it; jumping to this
value visits file @var{filename} and goes to buffer position value visits file @var{filename} and goes to buffer position
@var{position}. Restoring this type of position asks the user for @var{position}. Restoring this type of position asks the user for
confirmation first. confirmation first.
@item @code{(buffer @var{buffer-name})}
This represents a buffer; jumping to this value switches to buffer
@var{buffer-name}.
@end table @end table
The functions in this section return unpredictable values unless The functions in this section return unpredictable values unless

14
lisp/register.el
View file

@ -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 A list of the form (file-query FILE-NAME POSITION) represents
position POSITION in the file named FILE-NAME, but query before position POSITION in the file named FILE-NAME, but query before
visiting it. visiting it.
A list of the form (buffer . BUFFER-NAME) represents the buffer BUFFER-NAME.
A list of the form (WINDOW-CONFIGURATION POSITION) A list of the form (WINDOW-CONFIGURATION POSITION)
represents a saved window configuration plus a saved value of point. represents a saved window configuration plus a saved value of point.
A list of the form (FRAME-CONFIGURATION POSITION) 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 (defgroup register nil
"Register commands." "Register commands."
@ -179,7 +181,7 @@ display such a window regardless."
(defun point-to-register (register &optional arg) (defun point-to-register (register &optional arg)
"Store current location of point in register REGISTER. "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. Use \\[jump-to-register] to go to that location or restore that configuration.
Argument is a character, naming the register. 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) (defun frame-configuration-to-register (register &optional _arg)
"Store the window configuration of all frames in register REGISTER. "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. Use \\[jump-to-register] to restore the configuration.
Argument is a character, naming the register. 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 If the register contains a window configuration (one frame) or a frameset
\(all frames), restore that frame or all frames accordingly. \(all frames), restore that frame or all frames accordingly.
First argument is a character, naming the register. First argument is a character, naming the register.
Optional second arg non-nil (interactively, prefix argument) says to Optional second arg DELETE non-nil (interactively, prefix argument) says
delete any existing frames that the frameset doesn't mention. to delete any existing frames that the frameset doesn't mention.
\(Otherwise, these frames are iconified.) \(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'." Interactively, reads the register using `register-read-with-preview'."
(interactive (list (register-read-with-preview "Jump to register: ") (interactive (list (register-read-with-preview "Jump to register: ")