* doc/lispref/text.texi (Special Properties): Warn against `intangible' properties.

Fixes: debbugs:10222

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 37de62be97650b68ff603c3877fc0ec59a203968..d620c9e3c4cc729191955c2c566056e1d9efe14a 100644 (file)
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,8 @@
+2011-12-05  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+       * text.texi (Special Properties): Warn against `intangible' properties
+       (bug#10222).
+
 2011-11-26  Eli Zaretskii  <eliz@gnu.org>
 
        * display.texi (Truncation):
@@ -23,8 +28,8 @@
 
 2011-11-21  Martin Rudalics  <rudalics@gmx.at>
 
-       * windows.texi (Windows and Frames, Splitting Windows): Fix
-       typos.
+       * windows.texi (Windows and Frames, Splitting Windows):
+       Fix typos.
 
 2011-11-21  Chong Yidong  <cyd@gnu.org>
 
@@ -36,8 +41,8 @@
        (Buffers and Windows): Copyedits.
        (Choosing Window): Document special handling of special-display-*.
        (Choosing Window Options): Fix display-buffer-reuse-frames doc.
-       Don't document even-window-heights, which is going away.  Clarify
-       which options are obeyed by which action functions.
+       Don't document even-window-heights, which is going away.
+       Clarify which options are obeyed by which action functions.
 
 2011-11-20  Stefan Monnier  <monnier@iro.umontreal.ca>
 

diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index e76b2bafd79ebe1a14eb1a7246a31900eb3646f0..41392273fbdc38a4e19019ac33ec48ba42be425b 100644 (file)
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -946,10 +946,9 @@ If the last event came from a keyboard macro, the value is @code{macro}.
 
   It is not easy to display a value of point in the middle of a
 sequence of text that has the @code{display}, @code{composition} or
-@code{intangible} property, or is invisible.  Therefore, after a
-command finishes and returns to the command loop, if point is within
-such a sequence, the command loop normally moves point to the edge of
-the sequence.
+is invisible.  Therefore, after a command finishes and returns to the
+command loop, if point is within such a sequence, the command loop
+normally moves point to the edge of the sequence.
 
   A command can inhibit this feature by setting the variable
 @code{disable-point-adjustment}:

diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index fc12939bec5edf9bb79361c850e4dc5482c5b6cb..f7f9c71616244d22da11a083230291e013e553a5 100644 (file)
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -3145,6 +3145,12 @@ group is separately treated as described above.
 When the variable @code{inhibit-point-motion-hooks} is non-@code{nil},
 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}.
+
 @item field
 @kindex field @r{(text property)}
 Consecutive characters with the same @code{field} property constitute a