* doc/lispref/display.texi (Invisible Text): Clarify point adjustment.

Fixes: debbugs:10072

2 files changed, 51 insertions, 41 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index a1c6472c3fa..3324b5dcfec 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,7 +1,11 @@
+2011-11-20  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+        * display.texi (Invisible Text): Clarify point adjustment (bug#10072).
+
 2011-11-20  Martin Rudalics  <rudalics@gmx.at>
 
-        * windows.texi (Resizing Windows, Splitting Windows): Remove
-        term "status" when talking about combination limits.
+        * windows.texi (Resizing Windows, Splitting Windows):
+        Remove term "status" when talking about combination limits.
 
 2011-11-20  Juanma Barranquero  <lekktu@gmail.com>
 
@@ -12,8 +16,8 @@
 
         * windows.texi (Splitting Windows): Clarify role of window
         parameters in split-window.  Shorten the example.
-        (Deleting Windows): Rewrite intro to handle internal windows.  Fix
-        delete-windows-on doc.
+        (Deleting Windows): Rewrite intro to handle internal windows.
+        Fix delete-windows-on doc.
         (Selecting Windows): Copyedits.
 
 2011-11-17  Martin Rudalics  <rudalics@gmx.at>
@@ -24,8 +28,8 @@
 
 2011-11-16  Martin Rudalics  <rudalics@gmx.at>
 
-        * windows.texi (Resizing Windows, Splitting Windows): Rename
-        occurrences of window-nest to window-combination-limit.
+        * windows.texi (Resizing Windows, Splitting Windows):
+        Rename occurrences of window-nest to window-combination-limit.
 
 2011-11-14  Juanma Barranquero  <lekktu@gmail.com>
 
@@ -33,8 +37,8 @@
 
 2011-11-12  Martin Rudalics  <rudalics@gmx.at>
 
-        * windows.texi (Splitting Windows, Deleting Windows): Remove
-        references to splits status of windows.
+        * windows.texi (Splitting Windows, Deleting Windows):
+        Remove references to splits status of windows.
 
 2011-11-10  Glenn Morris  <rgm@gnu.org>
 
@@ -86,8 +90,8 @@
         (Windows and Frames): Various clarifications, e.g. non-live
         windows also belong to frames.  Fix window-list description.
         Simplify window nesting example.
-        (Splitting Windows, Window Configurations): Use
-        split-window-below.
+        (Splitting Windows, Window Configurations):
+        Use split-window-below.
 
 2011-11-04  Eli Zaretskii  <eliz@gnu.org>
 
@@ -137,8 +141,8 @@
 
 2011-10-05  Chong Yidong  <cyd@stupidchicken.com>
 
-        * display.texi (Low-Level Font, Face Attributes, Font Lookup): Fix
-        Emacs manual xref (Bug#9675).
+        * display.texi (Low-Level Font, Face Attributes, Font Lookup):
+        Fix Emacs manual xref (Bug#9675).
 
 2011-10-01  Chong Yidong  <cyd@stupidchicken.com>
 
@@ -177,8 +181,8 @@
         * windows.texi (Window History): New node.  Move text here from
         Buffers and Windows.
         (Switching Buffers): Rename from Displaying Buffers, since we
-        don't document display-buffer here; callers changed.  Document
-        FORCE-SAME-WINDOW arg to switch-to-buffer and
+        don't document display-buffer here; callers changed.
+        Document FORCE-SAME-WINDOW arg to switch-to-buffer and
         switch-to-buffer-other-frame.  Delete duplicate
         replace-buffer-in-windows doc.
         (Choosing Window): Document display actions.
@@ -209,10 +213,10 @@
         Provide examples.  Describe window-nest and window-splits
         options.
         (Deleting Windows): Minor rewrite.
-        (Selecting Windows): Minor rewrite.  Describe
-        frame-selected-window and set-frame-selected-window here.
-        (Cyclic Window Ordering): Minor rewrite.  Describe
-        window-list-1.
+        (Selecting Windows): Minor rewrite.
+        Describe frame-selected-window and set-frame-selected-window here.
+        (Cyclic Window Ordering): Minor rewrite.
+        Describe window-list-1.
         (Buffers and Windows): Rewrite.  Explain a window's previous and
         next buffers and the corresponding functions.
         (Window Tree): Merge into Windows and Frames section.
@@ -314,8 +318,8 @@
 
         * display.texi (Bidirectional Display): Document the pitfalls of
         concatenating strings with bidirectional content, with possible
-        solutions.  Document bidi-string-mark-left-to-right.  Mention
-        paragraph direction in modes that inherit from prog-mode.
+        solutions.  Document bidi-string-mark-left-to-right.
+        Mention paragraph direction in modes that inherit from prog-mode.
         Document use of `bidi-class' and `mirroring' properties as part of
         reordering.
 
@@ -371,8 +375,8 @@
         the next character, and doesn't affect longer sequences in
         particular (bug#8935).
 
-        * debugging.texi (Using Debugger): Mention
-        @code{eval-expression-debug-on-error} (bug#8549).
+        * debugging.texi (Using Debugger):
+        Mention @code{eval-expression-debug-on-error} (bug#8549).
 
 2011-07-14  Eli Zaretskii  <eliz@gnu.org>
 
@@ -521,7 +525,7 @@
 
 2011-06-15  Lars Magne Ingebrigtsen  <larsi@gnus.org>
 
-        * processes.texi (Process Information): Renamed `process-alive-p'
+        * processes.texi (Process Information): Rename `process-alive-p'
         to `process-live-p' for consistency with other `-live-p' functions.
 
 2011-06-03  Paul Eggert  <eggert@cs.ucla.edu>
@@ -538,8 +542,8 @@
 
 2011-05-31  Lars Magne Ingebrigtsen  <larsi@gnus.org>
 
-        * processes.texi (Process Information): Document
-        `process-alive-p'.
+        * processes.texi (Process Information):
+        Document `process-alive-p'.
 
 2011-05-29  Chong Yidong  <cyd@stupidchicken.com>
 
@@ -1937,8 +1941,8 @@
 
 2009-05-09  Eli Zaretskii  <eliz@gnu.org>
 
-        * nonascii.texi (Default Coding Systems): Document
-        find-auto-coding, set-auto-coding, and auto-coding-alist.
+        * nonascii.texi (Default Coding Systems):
+        Document find-auto-coding, set-auto-coding, and auto-coding-alist.
         Add indexing.
         (Lisp and Coding Systems): Add index entries.
 
@@ -5169,8 +5173,8 @@
         (Saving Buffers): Mention code and EOL conversions by file I/O
         primitives and subroutines.
 
-        * nonascii.texi (Lisp and Coding Systems): Document
-        coding-system-eol-type.  Add index entries for eol conversion.
+        * nonascii.texi (Lisp and Coding Systems):
+        Document coding-system-eol-type.  Add index entries for eol conversion.
 
         * display.texi (Defining Faces): Mention `mac', and add an xref to
         where window-system is described.
@@ -9120,7 +9124,7 @@
 
         * functions.texi (Defining Functions): Explain about redefining
         primitives.
-        (Function Safety): Renamed.  Minor changes.
+        (Function Safety): Rename.  Minor changes.
         Comment out the detailed criteria for what is safe.
 
 2003-06-22  Andreas Schwab  <schwab@suse.de>
@@ -9621,7 +9625,7 @@
 
         * Makefile (infodir, prefix): New vars.
         (install): Use infodir.
-        (emacsinfodir): Deleted.
+        (emacsinfodir): Delete.
 
 1993-05-27  Richard Stallman  (rms@mole.gnu.ai.mit.edu)
 
@@ -9632,7 +9636,7 @@
 
 1993-05-16  Jim Blandy  (jimb@wookumz.gnu.ai.mit.edu)
 
-        * Makefile (dist): Changed to use Gzip instead of compress.
+        * Makefile (dist): Change to use Gzip instead of compress.
 
 1993-04-23  Eric S. Raymond  (eric@mole.gnu.ai.mit.edu)
 
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 39a81ecc6ad..9849420b1f5 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -870,15 +870,21 @@ ignore invisible newlines if @code{line-move-ignore-invisible} is
 non-@code{nil} (the default), but only because they are explicitly
 programmed to do so.
 
-  However, if a command ends with point inside or immediately before
-invisible text, the main editing loop moves point further forward or
-further backward (in the same direction that the command already moved
-it) until that condition is no longer true.  Thus, if the command
-moved point back into an invisible range, Emacs moves point back to
-the beginning of that range, and then back one more character.  If the
-command moved point forward into an invisible range, Emacs moves point
-forward up to the first visible character that follows the invisible
-text.
+  However, if a command ends with point inside or at the boundary of invisible
+text, the main editing loop moves point to one of the two ends of the invisible
+text.  Which end to move to is chosen based on the following factors: make sure
+that the overall movement of the command is still in the same direction, and
+prefer a position where an inserted char would not inherit the @code{invisible}
+property.  Additionally, if the text is not replaced by an ellipsis and the
+command only moved within the invisible text, then point is moved one extra
+character so as to try and reflect the command's movement by a visible movement
+of the cursor.
+
+  Thus, if the command moved point back to an invisible range (with the usual
+stickiness), Emacs moves point back to the beginning of that range.  If the
+command moved point forward into an invisible range, Emacs moves point forward
+to the first visible character that follows the invisible text and then forward
+one more character.
 
   Incremental search can make invisible overlays visible temporarily
 and/or permanently when a match includes invisible text.  To enable