@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-2014 Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-2015 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Display
@chapter Emacs Display
* Faces:: A face defines a graphics style for text characters:
font, colors, etc.
* Fringes:: Controlling window fringes.
-* Scroll Bars:: Controlling vertical scroll bars.
+* Scroll Bars:: Controlling scroll bars.
* Window Dividers:: Separating windows visually.
* Display Property:: Enabling special display features.
* Images:: Displaying images in Emacs buffers.
@node Refresh Screen
@section Refreshing the Screen
+@cindex refresh the screen
+@cindex screen refresh
The function @code{redraw-frame} clears and redisplays the entire
contents of a given frame (@pxref{Frames}). This is useful if the
@node Echo Area Customization
@subsection Echo Area Customization
+@cindex echo area customization
These variables control details of how the echo area works.
@node Warning Variables
@subsection Warning Variables
+@cindex warning variables
Programs can customize how their warnings appear by binding
the variables described in this section.
@node Warning Options
@subsection Warning Options
+@cindex warning options
These variables are used by users to control what happens
when a Lisp program reports a warning.
@node Delayed Warnings
@subsection Delayed Warnings
+@cindex delayed warnings
Sometimes, you may wish to avoid showing a warning while a command is
running, and only show it only after the end of the command. You can
@node Temporary Displays
@section Temporary Displays
+@cindex temporary display
+@cindex temporary buffer display
Temporary displays are used by Lisp programs to put output into a
buffer and then present it to the user for perusal rather than for
buffer in some window. Unlike @code{with-output-to-temp-buffer},
however, it does not automatically switch that buffer to Help mode.
-Like @code{with-output-to-temp-buffer} it neither makes the buffer
-specified by @var{buffer-or-name} current when executing @var{body}.
-@findex with-current-buffer-window
-The otherwise identical macro @code{with-current-buffer-window} can be
-used to execute @var{body} with that buffer current.
-
The argument @var{buffer-or-name} specifies the temporary buffer. It
can be either a buffer, which must already exist, or a string, in which
case a buffer of that name is created, if necessary. The buffer is
exits.
This macro does not call @code{temp-buffer-show-function}. Rather, it
-passes the @var{action} argument to @code{display-buffer} in order to
-display the buffer.
+passes the @var{action} argument to @code{display-buffer}
+(@pxref{Choosing Window}) in order to display the buffer.
The value of the last form in @var{body} is returned, unless the
argument @var{quit-function} is specified. In that case, it is called
with two arguments: the window showing the buffer and the result of
-@var{body}. The final return value is then whatever
-@var{quit-function} returns.
+@var{body}. The final return value is then whatever @var{quit-function}
+returns.
@vindex temp-buffer-window-setup-hook
@vindex temp-buffer-window-show-hook
run by @code{with-output-to-temp-buffer}.
@end defmac
+The two constructs described next are mostly identical to
+@code{with-temp-buffer-window} but differ from it as specified:
+
+@defmac with-current-buffer-window buffer-or-name action quit-function &rest body
+This macro is like @code{with-temp-buffer-window} but unlike that makes
+the buffer specified by @var{buffer-or-name} current for running
+@var{body}.
+@end defmac
+
+@defmac with-displayed-buffer-window buffer-or-name action quit-function &rest body
+This macro is like @code{with-current-buffer-window} but unlike that
+displays the buffer specified by @var{buffer-or-name} @emph{before}
+running @var{body}.
+@end defmac
+
+A window showing a temporary buffer can be fit to the size of that
+buffer using the following mode:
+
+@defopt temp-buffer-resize-mode
+When this minor mode is enabled, windows showing a temporary buffer are
+automatically resized to fit their buffer's contents.
+
+A window is resized if and only if it has been specially created for the
+buffer. In particular, windows that have shown another buffer before
+are not resized. By default, this mode uses @code{fit-window-to-buffer}
+(@pxref{Resizing Windows}) for resizing. You can specify a different
+function by customizing the options @code{temp-buffer-max-height} and
+@code{temp-buffer-max-width} below.
+@end defopt
+
+@defopt temp-buffer-max-height
+This option specifies the maximum height (in lines) of a window
+displaying a temporary buffer when @code{temp-buffer-resize-mode} is
+enabled. It can also be a function to be called to choose the height
+for such a buffer. It gets one argument, the buffer, and should return
+a positive integer. At the time the function is called, the window to
+be resized is selected.
+@end defopt
+
+@defopt temp-buffer-max-width
+This option specifies the maximum width of a window (in columns)
+displaying a temporary buffer when @code{temp-buffer-resize-mode} is
+enabled. It can also be a function to be called to choose the width for
+such a buffer. It gets one argument, the buffer, and should return a
+positive integer. At the time the function is called, the window to be
+resized is selected.
+@end defopt
+
+The following function uses the current buffer for temporal display:
+
@defun momentary-string-display string position &optional char message
This function momentarily displays @var{string} in the current buffer at
@var{position}. It has no effect on the undo list or on the buffer's
@node Managing Overlays
@subsection Managing Overlays
+@cindex managing overlays
+@cindex overlays, managing
This section describes the functions to create, delete and move
overlays, and to examine their contents. Overlay changes are not
@node Overlay Properties
@subsection Overlay Properties
+@cindex overlay properties
Overlay properties are like text properties in that the properties that
alter how a character is displayed can come from either source. But in
@node Finding Overlays
@subsection Searching for Overlays
+@cindex searching for overlays
+@cindex overlays, searching for
@defun overlays-at pos &optional sorted
This function returns a list of all the overlays that cover the character at
@node Size of Displayed Text
@section Size of Displayed Text
+@cindex size of text on display
+@cindex character width on display
Since not all characters have the same width, these functions let you
check the width of a character. @xref{Primitive Indent}, and
@node Defining Faces
@subsection Defining Faces
+@cindex defining faces
@cindex face spec
The usual way to define a face is through the @code{defface} macro.
@node Attribute Functions
@subsection Face Attribute Functions
+@cindex face attributes, access and modification
This section describes functions for directly accessing and
modifying the attributes of a named face.
@node Displaying Faces
@subsection Displaying Faces
+@cindex displaying faces
+@cindex face merging
When Emacs displays a given piece of text, the visual appearance of
the text may be determined by faces drawn from different sources. If
@node Face Remapping
@subsection Face Remapping
+@cindex face remapping
The variable @code{face-remapping-alist} is used for buffer-local or
global changes in the appearance of a face. For instance, it is used
@node Basic Faces
@subsection Basic Faces
+@cindex basic faces
If your Emacs Lisp program needs to assign some faces to text, it is
often a good idea to use certain existing faces or inherit from them,
@node Font Lookup
@subsection Looking Up Fonts
+@cindex font lookup
+@cindex looking up fonts
@defun x-list-fonts name &optional reference-face frame maximum width
This function returns a list of available font names that match
@node Fontsets
@subsection Fontsets
+@cindex fontset
A @dfn{fontset} is a list of fonts, each assigned to a range of
character codes. An individual font cannot display the whole range of
@item :otf
@cindex OpenType font
The font must be an OpenType font that supports these OpenType
-features, provided Emacs is compiled with support for @samp{libotf} (a
-library for performing complex text layout in certain scripts). The
-value must be a list of the form
+features, provided Emacs is compiled with a library, such as
+@samp{libotf} on GNU/Linux, that supports complex text layout for
+scripts which need that. The value must be a list of the form
@smallexample
@code{(@var{script-tag} @var{langsys-tag} @var{gsub} @var{gpos})}
consecutive wildcards in the XLFD are folded into one.
@end defun
+The following two functions return important information about a font.
+
+@defun font-info name &optional frame
+This function returns information about a font specified by its
+@var{name}, a string, as it is used on @var{frame}. If @var{frame} is
+omitted or @code{nil}, it defaults to the selected frame.
+
+The value returned by the function is a vector of the form
+@code{[@var{opened-name} @var{full-name} @var{size} @var{height}
+@var{baseline-offset} @var{relative-compose} @var{default-ascent}
+@var{max-width} @var{ascent} @var{descent} @var{space-width}
+@var{average-width} @var{filename} @var{capability}]}. Here's the
+description of each components of this vector:
+
+@table @var
+@item opened-name
+The name used to open the font, a string.
+
+@item full-name
+The full name of the font, a string.
+
+@item size
+The pixel size of the font.
+
+@item height
+The height of the font in pixels.
+
+@item baseline-offset
+The offset in pixels from the @acronym{ASCII} baseline, positive
+upward.
+
+@item relative-compose
+@itemx default-ascent
+Numbers controlling how to compose characters.
+
+@item ascent
+@itemx descent
+The ascent and descent of this font. The sum of these two numbers
+should be equal to the value of @var{height} above.
+
+@item space-width
+The width, in pixels, of the font's space character.
+
+@item average-width
+The average width of the font characters. If this is zero, Emacs uses
+the value of @var{space-width} instead, when it calculates text layout
+on display.
+
+@item filename
+The file name of the font as a string. This can be @code{nil} if the
+font back-end does not provide a way to find out the font's file name.
+
+@item capability
+A list whose first element is a symbol representing the font type, one
+of @code{x}, @code{opentype}, @code{truetype}, @code{type1},
+@code{pcf}, or @code{bdf}. For OpenType fonts, the list includes 2
+additional elements describing the @sc{gsub} and @sc{gpos} features
+supported by the font. Each of these elements is a list of the form
+@code{((@var{script} (@var{langsys} @var{feature} @dots{}) @dots{})
+@dots{})}, where @var{script} is a symbol representing an OpenType
+script tag, @var{langsys} is a symbol representing an OpenType langsys
+tag (or @code{nil}, which stands for the default langsys), and each
+@var{feature} is a symbol representing an OpenType feature tag.
+@end table
+@end defun
+
+@defun query-font font-object
+This function returns information about a @var{font-object}. (This is
+in contrast to @code{font-info}, which takes the font name, a string,
+as its argument.)
+
+The value returned by the function is a vector of the form
+@code{[@var{name} @var{filename} @var{pixel-size} @var{max-width}
+@var{ascent} @var{descent} @var{space-width} @var{average-width}
+@var{capability}]}. Here's the description of each components of this
+vector:
+
+@table @var
+@item name
+The font name, a string.
+
+@item filename
+The file name of the font as a string. This can be @code{nil} if the
+font back-end does not provide a way to find out the font's file name.
+
+@item pixel-size
+The pixel size of the font used to open the font.
+
+@item max-width
+The maximum advance width of the font.
+
+@item ascent
+@itemx descent
+The ascent and descent of this font. The sum of these two numbers
+gives the font height.
+
+@item space-width
+The width, in pixels, of the font's space character.
+
+@item average-width
+The average width of the font characters. If this is zero, Emacs uses
+the value of @var{space-width} instead, when it calculates text layout
+on display.
+
+@item capability
+A list whose first element is a symbol representing the font type, one
+of @code{x}, @code{opentype}, @code{truetype}, @code{type1},
+@code{pcf}, or @code{bdf}. For OpenType fonts, the list includes 2
+additional elements describing the @sc{gsub} and @sc{gpos} features
+supported by the font. Each of these elements is a list of the form
+@code{((@var{script} (@var{langsys} @var{feature} @dots{}) @dots{})
+@dots{})}, where @var{script} is a symbol representing an OpenType
+script tag, @var{langsys} is a symbol representing an OpenType langsys
+tag (or @code{nil}, which stands for the default langsys), and each
+@var{feature} is a symbol representing an OpenType feature tag.
+@end table
+@end defun
+
@node Fringes
@section Fringes
@cindex fringes
@code{overlay-arrow-string} or @code{overlay-arrow} fringe indicator
is used.
+
@node Scroll Bars
@section Scroll Bars
@cindex scroll bars
Normally the frame parameter @code{vertical-scroll-bars} controls
-whether the windows in the frame have vertical scroll bars, and
-whether they are on the left or right. The frame parameter
-@code{scroll-bar-width} specifies how wide they are (@code{nil}
-meaning the default). @xref{Layout Parameters}.
+whether the windows in the frame have vertical scroll bars, and whether
+they are on the left or right. The frame parameter
+@code{scroll-bar-width} specifies how wide they are (@code{nil} meaning
+the default).
+
+ The frame parameter @code{horizontal-scroll-bars} controls whether
+the windows in the frame have horizontal scroll bars. The frame
+parameter @code{scroll-bar-height} specifies how high they are
+(@code{nil} meaning the default). @xref{Layout Parameters}.
+
+@vindex horizontal-scroll-bars-available-p
+ Horizontal scroll bars are not available on all platforms. The
+function @code{horizontal-scroll-bars-available-p} which takes no
+argument returns non-@code{nil} if they are available on your system.
+
+ The following three functions take as argument a live frame which
+defaults to the selected one.
@defun frame-current-scroll-bars &optional frame
-This function reports the scroll bar type settings for frame
-@var{frame}. The value is a cons cell
-@code{(@var{vertical-type} .@: @var{horizontal-type})}, where
-@var{vertical-type} is either @code{left}, @code{right}, or @code{nil}
-(which means no scroll bar.) @var{horizontal-type} is meant to
-specify the horizontal scroll bar type, but since they are not
-implemented, it is always @code{nil}.
-@end defun
-
-@vindex vertical-scroll-bar
- You can enable or disable scroll bars for a particular buffer,
-by setting the variable @code{vertical-scroll-bar}. This variable
-automatically becomes buffer-local when set. The possible values are
-@code{left}, @code{right}, @code{t}, which means to use the
-frame's default, and @code{nil} for no scroll bar.
+This function reports the scroll bar types for frame @var{frame}. The
+value is a cons cell @code{(@var{vertical-type} .@:
+@var{horizontal-type})}, where @var{vertical-type} is either
+@code{left}, @code{right}, or @code{nil} (which means no vertical scroll
+bar.) @var{horizontal-type} is either @code{bottom} or @code{nil}
+(which means no horizontal scroll bar).
+@end defun
- You can also control this for individual windows. Call the function
-@code{set-window-scroll-bars} to specify what to do for a specific window:
+@defun frame-scroll-bar-width &optional Lisp_Object &optional frame
+This function returns the width of vertical scroll bars of @var{frame}
+in pixels.
+@end defun
-@defun set-window-scroll-bars window width &optional vertical-type horizontal-type
-This function sets the width and type of scroll bars for window
-@var{window}.
+@defun frame-scroll-bar-height &optional Lisp_Object &optional frame
+This function returns the height of horizontal scroll bars of
+@var{frame} in pixels.
+@end defun
-@var{width} specifies the scroll bar width in pixels (@code{nil} means
-use the width specified for the frame). @var{vertical-type} specifies
-whether to have a vertical scroll bar and, if so, where. The possible
-values are @code{left}, @code{right} and @code{nil}, just like the
-values of the @code{vertical-scroll-bars} frame parameter.
+You can override the frame specific settings for individual windows by
+using the following function:
-The argument @var{horizontal-type} is meant to specify whether and
-where to have horizontal scroll bars, but since they are not
-implemented, it has no effect. If @var{window} is @code{nil}, the
-selected window is used.
+@defun set-window-scroll-bars window &optional width vertical-type height horizontal-type
+This function sets the width and/or height and the types of scroll bars
+for window @var{window}.
+
+@var{width} specifies the width of the vertical scroll bar in pixels
+(@code{nil} means use the width specified for the frame).
+@var{vertical-type} specifies whether to have a vertical scroll bar and,
+if so, where. The possible values are @code{left}, @code{right},
+@code{t}, which means to use the frame's default, and @code{nil} for no
+vertical scroll bar.
+
+@var{height} specifies the height of the horizontal scroll bar in pixels
+(@code{nil} means use the height specified for the frame).
+@var{horizontal-type} specifies whether to have a horizontal scroll bar.
+The possible values are @code{bottom}, @code{t}, which means to use the
+frame's default, and @code{nil} for no horizontal scroll bar.
+
+If @var{window} is @code{nil}, the selected window is used.
@end defun
+The following four functions take as argument a live window which
+defaults to the selected one.
+
@defun window-scroll-bars &optional window
-Report the width and type of scroll bars specified for @var{window}.
-If @var{window} is omitted or @code{nil}, the selected window is used.
-The value is a list of the form @code{(@var{width}
-@var{cols} @var{vertical-type} @var{horizontal-type})}. The value
-@var{width} is the value that was specified for the width (which may
-be @code{nil}); @var{cols} is the number of columns that the scroll
-bar actually occupies.
+This function returns a list of the form @code{(@var{width}
+@var{columns} @var{vertical-type} @var{height} @var{lines}
+@var{horizontal-type})}.
+
+The value @var{width} is the value that was specified for the width of
+the vertical scroll bar (which may be @code{nil}); @var{columns} is the
+(possibly rounded) number of columns that the vertical scroll bar
+actually occupies.
-@var{horizontal-type} is not actually meaningful.
+The value @var{height} is the value that was specified for the height of
+the horizontal scroll bar (which may be @code{nil}); @var{lines} is the
+(possibly rounded) number of lines that the horizontally scroll bar
+actually occupies.
+@end defun
+
+@defun window-current-scroll-bars &optional window
+This function reports the scroll bar type for window @var{window}. The
+value is a cons cell @code{(@var{vertical-type} .@:
+@var{horizontal-type})}. Unlike @code{window-scroll-bars}, this reports
+the scroll bar type actually used, once frame defaults and
+@code{scroll-bar-mode} are taken into account.
@end defun
@defun window-scroll-bar-width &optional window
-This function returns the width of @var{window}'s vertical scrollbar,
-in pixels. @var{window} must be a live window. If @var{window} is
-@code{nil} or omitted, it will be the selected window.
+This function returns the width in pixels of @var{window}'s vertical
+scrollbar.
+@end defun
+
+@defun window-scroll-bar-height &optional window
+This function returns the height in pixels of @var{window}'s horizontal
+scrollbar.
@end defun
If you don't specify these values for a window with
@code{set-window-scroll-bars}, the buffer-local variables
-@code{scroll-bar-mode} and @code{scroll-bar-width} in the buffer being
-displayed control the window's vertical scroll bars. The function
+@code{vertical-scroll-bar}, @code{horizontal-scroll-bar},
+@code{scroll-bar-width} and @code{scroll-bar-height} in the buffer being
+displayed control the window's scroll bars. The function
@code{set-window-buffer} examines these variables. If you change them
-in a buffer that is already visible in a window, you can make the
-window take note of the new values by calling @code{set-window-buffer}
+in a buffer that is already visible in a window, you can make the window
+take note of the new values by calling @code{set-window-buffer}
specifying the same buffer that is already displayed.
-@defopt scroll-bar-mode
-This variable, always local in all buffers, controls whether and where
-to put scroll bars in windows displaying the buffer. The possible values
-are @code{nil} for no scroll bar, @code{left} to put a scroll bar on
-the left, and @code{right} to put a scroll bar on the right.
-@end defopt
+You can control the appearance of scroll bars for a particular buffer by
+setting the following variables which automatically become buffer-local
+when set.
-@defun window-current-scroll-bars &optional window
-This function reports the scroll bar type for window @var{window}.
-If @var{window} is omitted or @code{nil}, the selected window is used.
-The value is a cons cell
-@code{(@var{vertical-type} .@: @var{horizontal-type})}. Unlike
-@code{window-scroll-bars}, this reports the scroll bar type actually
-used, once frame defaults and @code{scroll-bar-mode} are taken into
-account.
-@end defun
+@defvar vertical-scroll-bar
+This variable specifies the location of the vertical scroll bar. The
+possible values are @code{left}, @code{right}, @code{t}, which means to
+use the frame's default, and @code{nil} for no scroll bar.
+@end defvar
+
+@defvar horizontal-scroll-bar
+This variable specifies the location of the horizontal scroll bar. The
+possible values are @code{bottom}, @code{t}, which means to use the
+frame's default, and @code{nil} for no scroll bar.
+@end defvar
@defvar scroll-bar-width
-This variable, always local in all buffers, specifies the width of the
-buffer's scroll bars, measured in pixels. A value of @code{nil} means
-to use the value specified by the frame.
+This variable specifies the width of the buffer's vertical scroll bars,
+measured in pixels. A value of @code{nil} means to use the value
+specified by the frame.
@end defvar
+@defvar scroll-bar-height
+This variable specifies the height of the buffer's horizontal scroll
+bar, measured in pixels. A value of @code{nil} means to use the value
+specified by the frame.
+@end defvar
+
+Finally you can toggle the display of scroll bars on all frames by
+customizing the variables @code{scroll-bar-mode} and
+@code{horizontal-scroll-bar-mode}.
+
+@defopt scroll-bar-mode
+This variable controls whether and where to put vertical scroll bars in
+all frames. The possible values are @code{nil} for no scroll bars,
+@code{left} to put scroll bars on the left and @code{right} to put
+scroll bars on the right.
+@end defopt
+
+@defopt horizontal-scroll-bar-mode
+This variable controls whether to display horizontal scroll bars on all
+frames.
+@end defopt
+
+
@node Window Dividers
@section Window Dividers
@cindex window dividers
@node Replacing Specs
@subsection Display Specs That Replace The Text
+@cindex replacing display specs
Some kinds of display specifications specify something to display
instead of the text that has the property. These are called
Each image descriptor has the form @code{(image . @var{props})},
where @var{props} is a property list of alternating keyword symbols
-and values, including at least the pair @code{:type @var{TYPE}} which
+and values, including at least the pair @code{:type @var{type}} that
specifies the image type.
The following is a list of properties that are meaningful for all
@node Defining Images
@subsection Defining Images
+@cindex define image
The functions @code{create-image}, @code{defimage} and
@code{find-image} provide convenient ways to create image descriptors.
Each specification in @var{specs} is a property list with contents
depending on image type. All specifications must at least contain the
properties @code{:type @var{type}} and either @w{@code{:file @var{file}}}
-or @w{@code{:data @var{DATA}}}, where @var{type} is a symbol specifying
+or @w{@code{:data @var{data}}}, where @var{type} is a symbol specifying
the image type, e.g., @code{xbm}, @var{file} is the file to load the
image from, and @var{data} is a string containing the actual image data.
The first specification in the list whose @var{type} is supported, and
@node Showing Images
@subsection Showing Images
+@cindex show image
You can use an image descriptor by setting up the @code{display}
property yourself, but it is easier to use the functions in this
position. In performing this @dfn{bidirectional reordering}, Emacs
follows the Unicode Bidirectional Algorithm (a.k.a.@: @acronym{UBA}),
which is described in Annex #9 of the Unicode standard
-(@url{http://www.unicode.org/reports/tr9/}). Emacs currently provides
-a ``Non-isolate Bidirectionality'' class implementation of the
-@acronym{UBA}: it does not yet support the isolate directional
-formatting characters introduced with Unicode Standard v6.3.0.
+(@url{http://www.unicode.org/reports/tr9/}). Emacs provides a ``Full
+Bidirectionality'' class implementation of the @acronym{UBA},
+consistent with the requirements of the Unicode Standard v7.0.
@defvar bidi-display-reordering
If the value of this buffer-local variable is non-@code{nil} (the
appropriate mirrored character in the reordered text. Lisp programs
can affect the mirrored display by changing this property. Again, any
such changes affect all of Emacs display.
+
+@cindex overriding bidirectional properties
+@cindex directional overrides
+@cindex LRO
+@cindex RLO
+ The bidirectional properties of characters can be overridden by
+inserting into the text special directional control characters,
+LEFT-TO-RIGHT OVERRIDE (@acronym{LRO}) and RIGHT-TO-LEFT OVERRIDE
+(@acronym{RLO}). Any characters between a @acronym{RLO} and the
+following newline or POP DIRECTIONAL FORMATTING (@acronym{PDF})
+control character, whichever comes first, will be displayed as if they
+were strong right-to-left characters, i.e.@: they will be reversed on
+display. Similarly, any characters between @acronym{LRO} and
+@acronym{PDF} or newline will display as if they were strong
+left-to-right, and will @emph{not} be reversed even if they are strong
+right-to-left characters.
+
+@cindex phishing using directional overrides
+@cindex malicious use of directional overrides
+ These overrides are useful when you want to make some text
+unaffected by the reordering algorithm, and instead directly control
+the display order. But they can also be used for malicious purposes,
+known as @dfn{phishing}. Specifically, a URL on a Web page or a link
+in an email message can be manipulated to make its visual appearance
+unrecognizable, or similar to some popular benign location, while the
+real location, interpreted by a browser in the logical order, is very
+different.
+
+ Emacs provides a primitive that applications can use to detect
+instances of text whose bidirectional properties were overridden so as
+to make a left-to-right character display as if it were a
+right-to-left character, or vise versa.
+
+@defun bidi-find-overridden-directionality from to &optional object
+This function looks at the text of the specified @var{object} between
+positions @var{from} (inclusive) and @var{to} (exclusive), and returns
+the first position where it finds a strong left-to-right character
+whose directional properties were forced to display the character as
+right-to-left, or for a strong right-to-left character that was forced
+to display as left-to-right. If it finds no such characters in the
+specified region of text, it returns @code{nil}.
+
+The optional argument @var{object} specifies which text to search, and
+defaults to the current buffer. If @var{object} is non-@code{nil}, it
+can be some other buffer, or it can be a string or a window. If it is
+a string, the function searches that string. If it is a window, the
+function searches the buffer displayed in that window. If a buffer
+whose text you want to examine is displayed in some window, we
+recommend to specify it by that window, rather than pass the buffer to
+the function. This is because telling the function about the window
+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