From: Eli Zaretskii Date: Thu, 21 Dec 2023 11:45:58 +0000 (+0200) Subject: Improve and update documentation of registers X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=7058988fd65d719b69b658a74b268d4a2f1909c5;p=emacs.git Improve and update documentation of registers * lisp/register.el (register-use-preview) (register--read-with-preview-function) (register-preview-function, register-preview-default-1) (register-preview-default, register--preview-function) (register-preview-info, register-command-info) (register-preview-forward-line, register-preview-next) (register-preview-previous, set-register, register-type) (register--type, register-preview, register-preview-1) (register-preview-get-defaults, register-read-with-preview) (register-read-with-preview-traditional) (register-read-with-preview-fancy, register-preview-delay): Doc fixes. * doc/emacs/regs.texi (Registers): Describe the new preview modes. * etc/NEWS: Move the registers entry to its correct place, and document the modified behavior. (Bug#66394) --- diff --git a/doc/emacs/regs.texi b/doc/emacs/regs.texi index 5e5b7ae2b16..d7542e996dc 100644 --- a/doc/emacs/regs.texi +++ b/doc/emacs/regs.texi @@ -32,14 +32,46 @@ view-register}: Display a description of what register @var{r} contains. @end table -@vindex register-preview-delay + @cindex preview of registers - All of the commands that prompt for a register will display a -preview window that lists the existing registers (if there are -any) after a short delay. To change the length of the delay, -customize @code{register-preview-delay}. To prevent this display, set -that option to @code{nil}. You can explicitly request a preview -window by pressing @kbd{C-h} or @key{F1}. +@vindex register-use-preview + All of the commands that prompt for a register will by default +display a preview window that lists the existing registers (if there +are any) and their current values, after a short delay. This and +other aspects of prompting for a register can be customized by setting +the value of @code{register-use-preview}, which can have the following +values: + +@table @code +@vindex register-preview-delay +@item traditional +With this value, which is the default, Emacs behaves like it did in +all the versions before Emacs 29: it shows a preview of existing registers +after a delay, and lets you overwrite the values of existing registers +by typing a single character, the name of the register. The preview +appears after the delay determined by the customizable variable +@code{register-preview-delay}, which specifies the delay in seconds; +setting it to @code{nil} disables the preview (but you can still +explicitly request a preview window by pressing @kbd{C-h} or +@key{F1} when Emacs prompts for a register). + +@item t +This value requests a more flexible preview of existing registers. +The preview appears immediately when Emacs prompts for a register +(thus @code{register-preview-delay} has no effect), and the preview +window provides navigation: by using @kbd{C-n} and @kbd{C-p} (or the +@kbd{@key{UP}} and @kbd{@key{DOWN}} arrow keys), you can move between +the registers in the preview window. To overwrite the value of an +existing registers in this mode, you need to type @key{RET} after +selecting the register by navigation or typing its name. + +@item nil +This value requests behavior similar to @code{traditional}, but the +preview is shown without delay. + +@item never +This value is like @code{nil}, but it disables the preview. +@end table @dfn{Bookmarks} record files and positions in them, so you can return to those positions when you look at the file again. Bookmarks diff --git a/etc/NEWS b/etc/NEWS index f96f06af0e2..689aed30009 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -554,6 +554,21 @@ files. *** 'dired-listing-switches' handles connection-local values if exist. This allows to customize different switches for different remote machines. +** Registers + ++++ +*** New mode of prompting for register names and showing preview. +The new user option 'register-use-preview' can be customized to the +value t to request a different user interface of prompting for +register names and previewing the registers: Emacs will require +confirmation for overwriting the value of a register, and will show +the preview of registers without delay. You can also customize this +new option to disable the preview completely. + +The default value of 'register-use-preview' preserves the behavior of +Emacs 29 and before. See the Info node "(emacs) Registers" for more +details about the new UI and its variants. + ** Ediff --- @@ -1216,12 +1231,6 @@ showcases all their customization options. * Incompatible Lisp Changes in Emacs 30.1 ---- -** 'register-preview-delay' is no longer used. -Register preview is no longer delayed. If you want to disable the -preview, customize the new option 'register-use-preview' to the value -'never'. - +++ ** 'M-TAB' now invokes 'completion-at-point' also in Text mode. Text mode no longer binds 'M-TAB' to 'ispell-complete-word', and diff --git a/lisp/register.el b/lisp/register.el index ac4f48d23ce..bd8e8c2edcd 100644 --- a/lisp/register.el +++ b/lisp/register.el @@ -96,7 +96,10 @@ of the marked text." (defcustom register-preview-delay 1 "If non-nil, time to wait in seconds before popping up register preview window. If nil, do not show register previews, unless `help-char' (or a member of -`help-event-list') is pressed." +`help-event-list') is pressed. + +This variable has no effect when `register-use-preview' is set to any +value except \\='traditional." :version "24.4" :type '(choice number (const :tag "No preview unless requested" nil)) :group 'register) @@ -107,35 +110,38 @@ If nil, do not show register previews, unless `help-char' (or a member of :version "30.1") (defvar register--read-with-preview-function nil - "The register read preview function to use. -Two functions are provided, one that provide navigation and -highlighting of the register selected, filtering of register -according to command in use, defaults register to use when -setting a new register, confirmation and notification when you -are about to overwrite a register and generic functions to -configure how each existing commands behave. The other function -provided is the same as what was used in Emacs-29, no filtering, -no navigation, no defaults.") + "Function to use for reading a register name with preview. +Two functions are provided, one that provide navigation and highlighting +of the selected register, filtering of register according to command in +use, defaults register to use when setting a new register, confirmation +and notification when you are about to overwrite a register, and generic +functions to configure how each existing command behaves. Use the +function `register-read-with-preview-fancy' for this. The other +provided function, `register-read-with-preview-traditional', behaves +the same as in Emacs 29 and before: no filtering, no navigation, +and no defaults.") (defvar register-preview-function nil "Function to format a register for previewing. -Called with one argument, a cons (NAME . CONTENTS) as found in `register-alist'. -The function should return a string, the description of the argument. -It is set according to the value of `register--read-with-preview-function'.") +Called with one argument, a cons (NAME . CONTENTS), as found +in `register-alist'. The function should return a string, the +description of the argument. The function to use is set according +to the value of `register--read-with-preview-function'.") (defcustom register-use-preview 'traditional - "Maybe show register preview. - -This has no effect when `register--read-with-preview-function' value -is `register-read-with-preview-traditional'. - -When set to `t' show a preview buffer with navigation and highlighting. -When nil show a preview buffer with no such features and exit minibuffer -immediately after insertion in minibuffer. -When set to \\='never behave as above but with no preview buffer at -all but the preview buffer is still accessible with `help-char' (C-h). -When set to \\='traditional provide a much more basic preview according to -`register-preview-delay', it has the exact same behavior as in Emacs-29." + "Whether to show register preview when modifying registers. + +When set to `t', show a preview buffer with navigation and highlighting. +When nil, show a preview buffer without navigation and highlighting, and +exit the minibuffer immediately after inserting response in minibuffer. +When set to \\='never, behave as with nil, but with no preview buffer at +all; the preview buffer is still accessible with `help-char' (C-h). +When set to \\='traditional (the default), provide a more basic preview +according to `register-preview-delay'; this preserves the traditional +behavior of Emacs 29 and before. + +This has no effect when the value of `register--read-with-preview-function' +is `register-read-with-preview-traditional'." :type '(choice (const :tag "Use preview" t) (const :tag "Use quick preview" nil) @@ -155,7 +161,7 @@ When set to \\='traditional provide a much more basic preview according to (alist-get register register-alist)) (defun set-register (register value) - "Set contents of Emacs register named REGISTER to VALUE. Return VALUE. + "Set contents of Emacs register named REGISTER to VALUE, return VALUE. See the documentation of the variable `register-alist' for possible VALUEs." (setf (alist-get register register-alist) value)) @@ -169,21 +175,25 @@ See the documentation of the variable `register-alist' for possible VALUEs." d))) (defun register-preview-default-1 (r) - "Function that is the default value of the variable `register-preview-function'." + "Function used to format a register for fancy previewing. +This is used as the value of the variable `register-preview-function' +when `register-use-preview' is set to t or nil." (format "%s: %s\n" (propertize (string (car r)) 'display (single-key-description (car r))) (register-describe-oneline (car r)))) (defun register-preview-default (r) - "Function that is the default value of the variable `register-preview-function'." + "Function used to format a register for traditional preview. +This is the default value of the variable `register-preview-function', +and is used when `register-use-preview' is set to \\='traditional." (format "%s: %s\n" (single-key-description (car r)) (register-describe-oneline (car r)))) (cl-defgeneric register--preview-function (read-preview-function) - "Returns a function to format a register for previewing. -This according to the value of READ-PREVIEW-FUNCTION.") + "Return a function to format a register for previewing. +This is according to the value of `read-preview-function'.") (cl-defmethod register--preview-function ((_read-preview-function (eql register-read-with-preview-traditional))) #'register-preview-default) @@ -193,14 +203,15 @@ This according to the value of READ-PREVIEW-FUNCTION.") (cl-defstruct register-preview-info "Store data for a specific register command. -TYPES are the types of register supported. -MSG is the minibuffer message to send when a register is selected. +TYPES are the supported types of registers. +MSG is the minibuffer message to show when a register is selected. ACT is the type of action the command is doing on register. -SMATCH accept a boolean value to say if command accept non matching register." +SMATCH accept a boolean value to say if the command accepts non-matching +registers." types msg act smatch noconfirm) (cl-defgeneric register-command-info (command) - "Returns a `register-preview-info' object storing data for COMMAND." + "Return a `register-preview-info' object storing data for COMMAND." (ignore command)) (cl-defmethod register-command-info ((_command (eql insert-register))) (make-register-preview-info @@ -286,7 +297,7 @@ SMATCH accept a boolean value to say if command accept non matching register." (defun register-preview-forward-line (arg) "Move to next or previous line in register preview buffer. -If ARG is positive goto next line, if negative to previous. +If ARG is positive, go to next line; if negative, go to previous line. Do nothing when defining or executing kmacros." ;; Ensure user enter manually key in minibuffer when recording a macro. (unless (or defining-kbd-macro executing-kbd-macro @@ -315,31 +326,31 @@ Do nothing when defining or executing kmacros." (insert str))))))) (defun register-preview-next () - "Goto next line in register preview buffer." + "Go to next line in the register preview buffer." (interactive) (register-preview-forward-line 1)) (defun register-preview-previous () - "Goto previous line in register preview buffer." + "Go to previous line in the register preview buffer." (interactive) (register-preview-forward-line -1)) (defun register-type (register) "Return REGISTER type. -Current register types actually returned are one of: -- string -- number -- marker -- buffer -- file -- file-query -- window -- frame -- kmacro +Register type that can be returned is one of the following: + - string + - number + - marker + - buffer + - file + - file-query + - window + - frame + - kmacro One can add new types to a specific command by defining a new `cl-defmethod' -matching this command. Predicate for type in new `cl-defmethod' should -satisfy `cl-typep' otherwise the new type should be defined with +matching that command. Predicates for type in new `cl-defmethod' should +satisfy `cl-typep', otherwise the new type should be defined with `cl-deftype'." ;; Call register--type against the register value. (register--type (if (consp (cdr register)) @@ -347,7 +358,7 @@ satisfy `cl-typep' otherwise the new type should be defined with (cdr register)))) (cl-defgeneric register--type (regval) - "Returns type of register value REGVAL." + "Return the type of register value REGVAL." (ignore regval)) (cl-defmethod register--type ((_regval string)) 'string) @@ -371,8 +382,8 @@ satisfy `cl-typep' otherwise the new type should be defined with collect register))) (defun register-preview (buffer &optional show-empty) - "Pop up a window showing the registers preview in BUFFER. -If SHOW-EMPTY is non-nil, show the window even if no registers. + "Pop up a window showing the preview of registers in BUFFER. +If SHOW-EMPTY is non-nil, show the preview window even if no registers. Format of each entry is controlled by the variable `register-preview-function'." (unless register-preview-function (setq register-preview-function (register--preview-function @@ -392,13 +403,13 @@ Format of each entry is controlled by the variable `register-preview-function'." register-alist))))) (defun register-preview-1 (buffer &optional show-empty types) - "Pop up a window showing the registers preview in BUFFER. + "Pop up a window showing the preview of registers in BUFFER. -This is the preview function use with -`register-read-with-preview-fancy' function. -If SHOW-EMPTY is non-nil, show the window even if no registers. -Argument TYPES (a list) specify the types of register to show, when nil show all -registers, see `register-type' for suitable types. +This is the preview function used with the `register-read-with-preview-fancy' +function. +If SHOW-EMPTY is non-nil, show the preview window even if no registers. +Optional argument TYPES (a list) specifies the types of register to show; +if it is nil, show all the registers. See `register-type' for suitable types. Format of each entry is controlled by the variable `register-preview-function'." (unless register-preview-function (setq register-preview-function (register--preview-function @@ -419,7 +430,7 @@ Format of each entry is controlled by the variable `register-preview-function'." registers)))))) (cl-defgeneric register-preview-get-defaults (action) - "Returns default registers according to ACTION." + "Return default registers according to ACTION." (ignore action)) (cl-defmethod register-preview-get-defaults ((_action (eql set))) (cl-loop for s in register-preview-default-keys @@ -427,19 +438,25 @@ Format of each entry is controlled by the variable `register-preview-function'." collect s)) (defun register-read-with-preview (prompt) - "Read and return a register name, possibly showing existing registers. -Prompt with the string PROMPT. + "Read register name, prompting with PROMPT; possibly show existing registers. +This reads and returns the name of a register. PROMPT should be a string +to prompt the user for the name. If `help-char' (or a member of `help-event-list') is pressed, -display such a window regardless." +display preview window unconditionally. +This calls the function specified by `register--read-with-preview-function'." (funcall register--read-with-preview-function prompt)) (defun register-read-with-preview-traditional (prompt) - "Read and return a register name, possibly showing existing registers. -Prompt with the string PROMPT. If `register-alist' and -`register-preview-delay' are both non-nil, display a window -listing existing registers after `register-preview-delay' seconds. + "Read register name, prompting with PROMPT; possibly show existing registers. +This reads and returns the name of a register. PROMPT should be a string +to prompt the user for the name. +If `register-alist' and `register-preview-delay' are both non-nil, display +a window listing existing registers after `register-preview-delay' seconds. If `help-char' (or a member of `help-event-list') is pressed, -display such a window regardless." +display preview window unconditionally. + +This function is used as the value of `register--read-with-preview-function' +when `register-use-preview' is set to \\='traditional." (let* ((buffer "*Register Preview*") (timer (when (numberp register-preview-delay) (run-with-timer register-preview-delay nil @@ -467,10 +484,15 @@ display such a window regardless." (and (get-buffer buffer) (kill-buffer buffer))))) (defun register-read-with-preview-fancy (prompt) - "Read and return a register name, possibly showing existing registers. -Prompt with the string PROMPT. + "Read register name, prompting with PROMPT; possibly show existing registers. +This reads and returns the name of a register. PROMPT should be a string +to prompt the user for the name. If `help-char' (or a member of `help-event-list') is pressed, -display such a window regardless." +display preview window regardless. + +This function is used as the value of `register--read-with-preview-function' +when `register-use-preview' is set to any value other than \\='traditional +or \\='never." (let* ((buffer "*Register Preview*") (buffer1 "*Register quick preview*") (buf (if register-use-preview buffer buffer1))