[Emacs-diffs] emacs-25 30c24e4: Document obsoletion of 'intangible' and 'point-entered/left'

[Eli Zaretskii]

branch: emacs-25
commit 30c24e49cb82a817a123405df92210cbab12c459
Author: Eli Zaretskii <address@hidden>
Commit: Eli Zaretskii <address@hidden>

    Document obsoletion of 'intangible' and 'point-entered/left'
    
    * doc/lispref/text.texi (Special Properties): Document the new
    properties 'cursor-intangible' and 'cursor-sensor-functions'.
    Document the obsolete status of 'intangible', 'pointer-left',
    and 'point-entered' properties, and of 'inhibit-point-motion-hooks'.
    * doc/lispref/display.texi (Overlay Properties): Document that
    'intangible' overlay property is obsolete.
    
    * lisp/emacs-lisp/cursor-sensor.el (cursor-sensor-mode): Doc fix.
---
 doc/lispref/display.texi         |    3 +-
 doc/lispref/text.texi            |   40 ++++++++++++++++++++++++++++++-------
 etc/NEWS                         |    8 +++++-
 lisp/emacs-lisp/cursor-sensor.el |    4 +-
 4 files changed, 42 insertions(+), 13 deletions(-)

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 1ac0f05..d770599 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -1721,7 +1721,8 @@ invisible, which means that it does not appear on the 
screen.
 @item intangible
 @kindex intangible @r{(overlay property)}
 The @code{intangible} property on an overlay works just like the
address@hidden text property.  @xref{Special Properties}, for details.
address@hidden text property.  It is obsolete.  @xref{Special
+Properties}, for details.
 
 @item isearch-open-invisible
 This property tells incremental search how to make an invisible overlay
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 5d9f192..41991c9 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -3380,14 +3380,22 @@ If consecutive characters have unequal address@hidden
 @code{intangible} properties, they belong to separate groups; each
 group is separately treated as described above.
 
-When the variable @code{inhibit-point-motion-hooks} is address@hidden,
-the @code{intangible} property is ignored.
+When the variable @code{inhibit-point-motion-hooks} is address@hidden
+(as it is by default), the @code{intangible} property is ignored.
 
 Beware: this property operates at a very low level, and affects a lot of code
 in unexpected ways.  So use it with extreme caution.  A common misuse is to put
 an intangible property on invisible text, which is actually unnecessary since
 the command loop will move point outside of the invisible text at the end of
-each command anyway.  @xref{Adjusting Point}.
+each command anyway.  @xref{Adjusting Point}.  For these reasons, this
+property is obsolete; use the @code{cursor-intangible} property instead.
+
address@hidden cursor-intangible
address@hidden cursor-intangible @r{(text property)}
address@hidden cursor-intangible-mode
+When the minor mode @code{cursor-intangible-mode} is turned on, point
+is moved away of any position that has a address@hidden
address@hidden property, just before redisplay happens.
 
 @item field
 @kindex field @r{(text property)}
@@ -3550,9 +3558,23 @@ It is possible to use @code{char-after} to examine 
characters at various
 buffer positions without moving point to those positions.  Only an
 actual change in the value of point runs these hook functions.
 
-The variable @code{inhibit-point-motion-hooks} can inhibit running the
address@hidden and @code{point-entered} hooks, see @ref{Inhibit
-point motion hooks}.
+The variable @code{inhibit-point-motion-hooks} by default inhibits
+running the @code{point-left} and @code{point-entered} hooks, see
address@hidden point motion hooks}.
+
+These properties are obsolete; please use
address@hidden instead.
+
address@hidden cursor-sensor-functions
address@hidden cursor-sensor-functions @r{(text property)}
address@hidden cursor-sensor-mode
+This special property records a list of functions that react to cursor
+motion.  Each function in the list is called, just before redisplay,
+with 3 arguments: the affected window, the previous known position of
+the cursor, and one of the symbols @code{entered} or @code{left},
+depending on whether the cursor is entering the text that has this
+property or leaving it.  The functions are called only when the minor
+mode @code{cursor-sensor-mode} is turned on.
 
 @item composition
 @kindex composition @r{(text property)}
@@ -3564,10 +3586,12 @@ directly by, for instance, @code{put-text-property}.
 @end table
 
 @defvar inhibit-point-motion-hooks
address@hidden point motion hooks} When this variable is
address@hidden point motion hooks} When this obsolete variable is
 address@hidden, @code{point-left} and @code{point-entered} hooks are
 not run, and the @code{intangible} property has no effect.  Do not set
-this variable globally; bind it with @code{let}.
+this variable globally; bind it with @code{let}.  Since the affected
+properties are obsolete, this variable's default value is @code{t}, to
+effectively disable them.
 @end defvar
 
 @defvar show-help-function
diff --git a/etc/NEWS b/etc/NEWS
index 7cea0c8..525fa5e 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1357,12 +1357,16 @@ It is a bit easier to use than `pre-redisplay-function'.
 ** The second arg of `looking-back' should always be provided explicitly.
 Previously, it was an optional argument, now it's mandatory.
 
-** Obsolete text properties `intangible', `point-entered', and `point-left'.
++++
+** Text properties `intangible', `point-entered', and `point-left' are 
obsolete.
 Replaced by properties `cursor-intangible' and `cursor-sensor-functions',
 implemented by the new `cursor-intangible-mode' and
 `cursor-sensor-mode' minor modes.
 
-** `inhibit-point-motion-hooks' now defaults to t and is obsolete.
++++
+** `inhibit-point-motion-hooks' now defaults to `t' and is obsolete.
+Use the new minor modes `cursor-intangible-mode' and
+`cursor-sensor-mode' instead.
 
 +++
 ** New process type `pipe', which can be used in combination with the
diff --git a/lisp/emacs-lisp/cursor-sensor.el b/lisp/emacs-lisp/cursor-sensor.el
index 70c4458..ac063d48 100644
--- a/lisp/emacs-lisp/cursor-sensor.el
+++ b/lisp/emacs-lisp/cursor-sensor.el
@@ -167,8 +167,8 @@
 This property should hold a list of functions which react to the motion
 of the cursor.  They're called with three arguments (WINDOW OLDPOS DIR)
 where WINDOW is the affected window, OLDPOS is the last known position of
-the cursor and DIR can be `left' or `entered' depending on whether the cursor 
is
-entering the area covered by the text-property property or leaving it."
+the cursor and DIR can be `entered' or `left' depending on whether the cursor
+is entering the area covered by the text-property property or leaving it."
   nil nil nil
   (if cursor-sensor-mode
       (add-hook 'pre-redisplay-functions #'cursor-sensor--detect