* 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