From eea4e9194c209770dceb55b4853451da25da4ea5 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Fri, 24 Nov 2017 12:49:04 +0200 Subject: [PATCH] Improve documentation of self-insert-uses-region-functions * lisp/simple.el (self-insert-uses-region-functions): Clarify the doc string. * lisp/delsel.el (delete-selection-uses-region-p): Mention 'self-insert-command' in the doc string. (Bug#29373) * doc/lispref/text.texi (Commands for Insertion): Mention 'self-insert-uses-region-functions'. * doc/lispref/modes.texi (Keymaps and Minor Modes): Add a cross-reference to "Commands for Insertion". --- doc/lispref/modes.texi | 9 +++++---- doc/lispref/text.texi | 10 +++++++++- lisp/delsel.el | 12 +++++++++--- lisp/simple.el | 15 ++++++++++++--- 4 files changed, 35 insertions(+), 11 deletions(-) diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi index f7013da9433..bd94aeadf15 100644 --- a/doc/lispref/modes.texi +++ b/doc/lispref/modes.texi @@ -1490,10 +1490,11 @@ alist @code{minor-mode-map-alist}. @xref{Definition of minor-mode-map-alist}. One use of minor mode keymaps is to modify the behavior of certain self-inserting characters so that they do something else as well as self-insert. (Another way to customize @code{self-insert-command} is -through @code{post-self-insert-hook}. Apart from this, the facilities -for customizing @code{self-insert-command} are limited to special cases, -designed for abbrevs and Auto Fill mode. Do not try substituting your -own definition of @code{self-insert-command} for the standard one. The +through @code{post-self-insert-hook}, see @ref{Commands for +Insertion}. Apart from this, the facilities for customizing +@code{self-insert-command} are limited to special cases, designed for +abbrevs and Auto Fill mode. Do not try substituting your own +definition of @code{self-insert-command} for the standard one. The editor command loop handles this function specially.) Minor modes may bind commands to key sequences consisting of @kbd{C-c} diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index 3d26d0930f7..1e19f75d682 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -525,9 +525,17 @@ responsible for calling @code{blink-paren-function} when the inserted character has close parenthesis syntax (@pxref{Blinking}). @vindex post-self-insert-hook +@vindex self-insert-uses-region-functions The final thing this command does is to run the hook @code{post-self-insert-hook}. You could use this to automatically -reindent text as it is typed, for example. +reindent text as it is typed, for example. If any function on this +hook needs to act on the region (@pxref{The Region}), it should make +sure Delete Selection mode (@pxref{Using Region, Delete Selection, , +emacs, The GNU Emacs Manual}) doesn't delete the region before +@code{post-self-insert-hook} functions are invoked. The way to do so +is to add a function that returns @code{nil} to +@code{self-insert-uses-region-functions}, a special hook that tells +Delete Selection mode it should not delete the region. Do not try substituting your own definition of @code{self-insert-command} for the standard one. The editor command diff --git a/lisp/delsel.el b/lisp/delsel.el index 17b46efc7cb..65b2cb85cea 100644 --- a/lisp/delsel.el +++ b/lisp/delsel.el @@ -256,12 +256,18 @@ See `delete-selection-helper'." (get this-command 'delete-selection))))) (defun delete-selection-uses-region-p () - "Return t when the current command will be using the region -rather than having `delete-selection' delete it, nil otherwise. + "Return t when `delete-selection-mode' should not delete the region. + +The `self-insert-command' could be the current command or may be +called by the current command. If this function returns nil, +then `delete-selection' is allowed to delete the region. This function is intended for use as the value of the `delete-selection' property of a command, and shouldn't be used -for anything else." +for anything else. In particular, `self-insert-command' has this +function as its `delete-selection' property, so that \"electric\" +self-insert commands that act on the region could adapt themselves +to `delete-selection-mode'." (not (run-hook-with-args-until-success 'self-insert-uses-region-functions))) diff --git a/lisp/simple.el b/lisp/simple.el index 7d47d0f8645..d629fb66599 100644 --- a/lisp/simple.el +++ b/lisp/simple.el @@ -401,9 +401,18 @@ Other major modes are defined by comparison with this one." (defvar self-insert-uses-region-functions nil "Special hook to tell if `self-insert-command' will use the region. It must be called via `run-hook-with-args-until-success' with no arguments. -Any `post-self-insert-command' which consumes the region should -register a function on this hook so that things like `delete-selection-mode' -can refrain from consuming the region.") + +If any function on this hook returns a non-nil value, `delete-selection-mode' +will act on that value (see `delete-selection-helper'), and will +usually delete the region. If all the functions on this hook return +nil, it is an indiction that `self-insert-command' needs the region +untouched by `delete-selection-mode', and will itself do whatever is +appropriate with the region. +Any function on `post-self-insert-hook' which act on the region should +add a function to this hook so that `delete-selection-mode' could +refrain from deleting the region before `post-self-insert-hook' +functions are called. +This hook is run by `delete-selection-uses-region-p', which see.") (defvar hard-newline (propertize "\n" 'hard t 'rear-nonsticky '(hard)) "Propertized string representing a hard newline character.") -- 2.11.4.GIT