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

Fixes: debbugs:10222

3 files changed, 18 insertions, 8 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 37de62be976..d620c9e3c4c 100644
--- 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 e76b2bafd79..41392273fbd 100644
--- 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 fc12939bec5..f7f9c716162 100644
--- 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