Implement visual-order cursor motion.

 src/xdisp.c (Fmove_point_visually): New function.

 lisp/bindings.el (visual-order-cursor-movement): New defcustom.
 (right-char, left-char): Provide visual-order cursor motion by
 calling move-point-visually.  Update the doc strings.

 doc/emacs/basic.texi (Moving Point): Document visual-order-cursor-movement
 and its effect on right-char and left-char.

 doc/lispref/display.texi (Bidirectional Display): Document move-point-visually.

 etc/NEWS: Document the new feature.

5 files changed, 44 insertions, 3 deletions

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index 45f08499215..d5f3095908b 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,3 +1,8 @@
+2013-06-29  Eli Zaretskii  <eliz@gnu.org>
+
+        * basic.texi (Moving Point): Document visual-order-cursor-movement
+        and its effect on right-char and left-char.
+
 2013-06-28  Glenn Morris  <rgm@gnu.org>
 
         * ack.texi (Acknowledgments): Small update.
diff --git a/doc/emacs/basic.texi b/doc/emacs/basic.texi
index b9bc391d1cf..a840f912656 100644
--- a/doc/emacs/basic.texi
+++ b/doc/emacs/basic.texi
@@ -153,10 +153,17 @@ Move forward one character (@code{forward-char}).
 @item @key{right}
 @kindex RIGHT
 @findex right-char
+@vindex visual-order-cursor-movement
+@cindex cursor, visual-order motion
 This command (@code{right-char}) behaves like @kbd{C-f}, with one
 exception: when editing right-to-left scripts such as Arabic, it
 instead moves @emph{backward} if the current paragraph is a
-right-to-left paragraph.  @xref{Bidirectional Editing}.
+right-to-left paragraph.  @xref{Bidirectional Editing}.  If
+@code{visual-order-cursor-movement} is non-@code{nil}, this command
+moves to the character that is to the right of the current screen
+position, moving to the next or previous screen line as appropriate.
+Note that this might potentially move point many buffer positions
+away, depending on the surrounding bidirectional context.
 
 @item C-b
 @kindex C-b
@@ -168,7 +175,10 @@ Move backward one character (@code{backward-char}).
 @findex left-char
 This command (@code{left-char}) behaves like @kbd{C-b}, except it
 moves @emph{forward} if the current paragraph is right-to-left.
-@xref{Bidirectional Editing}.
+@xref{Bidirectional Editing}.  If @code{visual-order-cursor-movement}
+is non-@code{nil}, this command moves to the character that is to the
+left of the current screen position, moving to the previous or next
+screen line as appropriate.
 
 @item C-n
 @itemx @key{down}
diff --git a/doc/emacs/mule.texi b/doc/emacs/mule.texi
index de3e05777cd..c8bd5027fa0 100644
--- a/doc/emacs/mule.texi
+++ b/doc/emacs/mule.texi
@@ -1804,4 +1804,6 @@ jump when point traverses reordered bidirectional text.  Similarly, a
 highlighted region covering a contiguous range of character positions
 may look discontinuous if the region spans reordered text.  This is
 normal and similar to the behavior of other programs that support
-bidirectional text.
+bidirectional text.  If you set @code{visual-order-cursor-movement} to
+a non-@code{nil} value, cursor motion by the arrow keys follows the
+visual order on screen (@pxref{Moving Point, visual-order movement}).
diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 199d94585e3..dc0c1564735 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,7 @@
+2013-06-29  Eli Zaretskii  <eliz@gnu.org>
+
+        * display.texi (Bidirectional Display): Document move-point-visually.
+
 2013-06-29  Xue Fuqiao  <xfq.free@gmail.com>
 
         * buffers.texi (Buffer File Name): Fix typo.
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index d82b9a4c5a2..ecefb684ee6 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -6431,6 +6431,26 @@ determined dynamically by Emacs.  For buffers whose value of
 buffers, this function always returns @code{left-to-right}.
 @end defun
 
+@cindex visual-order cursor motion
+  Sometimes there's a need to move point in strict visual order,
+either to the left or to the right of its current screen position.
+Emacs provides a primitive to do that.
+
+@defun move-point-visually direction
+This function moves point of the currently selected window to the
+buffer position that appears immediately to the right or to the left
+of point on the screen.  If @var{direction} is positive, point will
+move one screen position to the right, otherwise it will move one
+screen position to the left.  Note that, depending on the surrounding
+bidirectional context, this could potentially move point many buffer
+positions away.  If invoked at the end of a screen line, the function
+moves point to the rightmost or leftmost screen position of the next
+or previous screen line, as appropriate for the value of
+@var{direction}.
+
+The function returns the new buffer position as its value.
+@end defun
+
 @cindex layout on display, and bidirectional text
 @cindex jumbled display of bidirectional text
 @cindex concatenating bidirectional strings