Implement copying of a buffer portion while preserving visual order.

 See http://lists.gnu.org/archive/html/emacs-devel/2014-11/msg02203.html
 and http://lists.gnu.org/archive/html/emacs-devel/2014-12/msg00063.html
 for the rationale.

 lisp/simple.el (bidi-directional-controls-chars)
 (bidi-directional-non-controls-chars): New variables.
 (squeeze-bidi-context-1, squeeze-bidi-context)
 (line-substring-with-bidi-context)
 (buffer-substring-with-bidi-context): New functions.

 doc/lispref/display.texi (Bidirectional Display): Document
 'buffer-substring-with-bidi-context'.
 doc/lispref/text.texi (Buffer Contents): Mention
 'buffer-substring-with-bidi-context' with a cross-reference.

 etc/NEWS: Mention 'buffer-substring-with-bidi-context'.

3 files changed, 38 insertions, 0 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index f98e457566e..d8215be6b15 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,11 @@
+2014-12-04  Eli Zaretskii  <eliz@gnu.org>
+
+        * display.texi (Bidirectional Display): Document
+        'buffer-substring-with-bidi-context'.
+
+        * text.texi (Buffer Contents): Mention
+        'buffer-substring-with-bidi-context' with a cross-reference.
+
 2014-12-02  Eli Zaretskii  <eliz@gnu.org>
 
         * display.texi (Bidirectional Display): Document
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 59f73223a1f..90aa9797a59 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -6854,3 +6854,27 @@ allows it to correctly account for window-specific overlays, which
 might change the result of the function if some text in the buffer is
 covered by overlays.
 @end defun
+
+@cindex copying bidirectional text, preserve visual order
+@cindex visual order, preserve when copying bidirectional text
+  When text that includes mixed right-to-left and left-to-right
+characters and bidirectional controls is copied into a different
+location, it can change its visual appearance, and also can affect the
+visual appearance of the surrounding text at destination.  This is
+because reordering of bidirectional text specified by the
+@acronym{UBA} has non-trivial context-dependent effects both on the
+copied text and on the text at copy destination that will surround it.
+
+  Sometimes, a Lisp program may need to preserve the exact visual
+appearance of the copied text at destination, and of the text that
+surrounds the copy.  Lisp programs can use the following function to
+achieve that effect.
+
+@defun buffer-substring-with-bidi-context start end &optional no-properties
+This function works similar to @code{buffer-substring} (@pxref{Buffer
+Contents}), but it prepends and appends to the copied text bidi
+directional control characters necessary to preserve the visual
+appearance of the text when it is inserted at another place.  Optional
+argument @var{no-properties}, if non-@code{nil}, means remove the text
+properties from the copy of the text.
+@end defun
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 9c878a00c94..720343cb17d 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -219,6 +219,12 @@ This function returns the contents of the entire accessible portion of
 the current buffer, as a string.
 @end defun
 
+  If you need to make sure the resulting string, when copied to a
+different location, will not change its visual appearance due to
+reordering of bidirectional text, use the
+@code{buffer-substring-with-bidi-context} function
+(@pxref{Bidirectional Display, buffer-substring-with-bidi-context}).
+
 @defun filter-buffer-substring start end &optional delete
 This function filters the buffer text between @var{start} and @var{end}
 using a function specified by the variable