@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-2012 Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-2013 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Display
@chapter Emacs Display
instead of being preempted, even if input is pending and the variable
@code{redisplay-dont-pause} is @code{nil} (see below). If
@code{redisplay-dont-pause} is non-@code{nil} (the default), this
-function redisplays in any case, i.e.@: @var{force} does nothing.
+function redisplays in any case, i.e., @var{force} does nothing.
The function returns @code{t} if it actually tried to redisplay, and
@code{nil} otherwise. A value of @code{t} does not mean that
beyond the right edge of the window are truncated; otherwise, they are
continued. As a special exception, the variable
@code{truncate-partial-width-windows} takes precedence in
-@dfn{partial-width} windows (i.e.@: windows that do not occupy the
+@dfn{partial-width} windows (i.e., windows that do not occupy the
entire frame width).
@end defopt
This function executes @var{forms} while arranging to insert any output
they print into the buffer named @var{buffer-name}, which is first
created if necessary, and put into Help mode. Finally, the buffer is
-displayed in some window, but not selected.
+displayed in some window, but not selected. (See the similar
+form @code{with-temp-buffer-window} below.)
If the @var{forms} do not change the major mode in the output buffer,
so that it is still Help mode at the end of their execution, then
is current, and the window it was displayed in is selected.
@end defvar
+@defmac with-temp-buffer-window buffer-or-name action quit-function forms@dots{}
+This macro is similar to @code{with-output-to-temp-buffer}.
+Like that construct, it executes @var{forms} while arranging to insert
+any output they print into the buffer named @var{buffer-or-name}.
+Finally, the buffer is displayed in some window, but not selected.
+Unlike @code{with-output-to-temp-buffer}, this does not switch to Help
+mode.
+
+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 marked as unmodified and read-only when
+@code{with-temp-buffer-window} 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.
+
+The value of the last form in @var{forms} 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{forms}. The final return value is then
+whatever @var{quit-function} returns.
+
+@vindex temp-buffer-window-setup-hook
+@vindex temp-buffer-window-show-hook
+This macro uses the normal hooks @code{temp-buffer-window-setup-hook}
+and @code{temp-buffer-window-show-hook} in place of the analogous hooks
+run by @code{with-output-to-temp-buffer}.
+@end defmac
+
@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
@kindex mouse-face @r{(overlay property)}
This property is used instead of @code{face} when the mouse is within
the range of the overlay. However, Emacs ignores all face attributes
-from this property that alter the text size (e.g. @code{:height},
+from this property that alter the text size (e.g., @code{:height},
@code{:weight}, and @code{:slant}). Those attributes are always the
same as in the unhighlighted text.
echo area, or in the tooltip window. For details see @ref{Text
help-echo}.
+@item field
+@kindex field @r{(overlay property)}
+@c Copied from Special Properties.
+Consecutive characters with the same @code{field} property constitute a
+@emph{field}. Some motion functions including @code{forward-word} and
+@code{beginning-of-line} stop moving at a field boundary.
+@xref{Fields}.
+
@item modification-hooks
@kindex modification-hooks @r{(overlay property)}
This property's value is a list of functions to be called if any
@defun char-width char
This function returns the width in columns of the character
-@var{char}, if it were displayed in the current buffer (i.e.@: taking
+@var{char}, if it were displayed in the current buffer (i.e., taking
into account the buffer's display table, if any; @pxref{Display
Tables}). The width of a tab character is usually @code{tab-width}
(@pxref{Usual Display}).
Underline with the foreground color of the face.
@item @var{color}
-Underline in color @var{color}; which should be either a string
-specifying a color, or the symbol @code{foreground-color}, meaning the
-foreground color of the face.
+Underline in color @var{color}, a string specifying a color.
@item @code{(:color @var{color} :style @var{style})}
-@var{color} is as described above. Omitting the attribute
+@var{color} is either a string, or the symbol @code{foreground-color},
+meaning the foreground color of the face. Omitting the attribute
@code{:color} means to use the foreground color of the face.
@var{style} should be a symbol @code{line} or @code{wave}, meaning to
use a straight or wavy line. Omitting the attribute @code{:style}
@end example
Internally, Emacs stores the face's default specification in its
-@code{face-defface-spec} symbol property (@pxref{Property Lists}).
+@code{face-defface-spec} symbol property (@pxref{Symbol Properties}).
The @code{saved-face} property stores the face specification saved by
the user, using the customization buffer; the @code{customized-face}
property stores the face specification customized for the current
This sets the @code{:font} attribute of @var{face} to @var{font}.
@end deffn
-@defun set-face-bold-p face bold-p &optional frame
+@defun set-face-bold face bold-p &optional frame
This sets the @code{:weight} attribute of @var{face} to @var{normal}
if @var{bold-p} is @code{nil}, and to @var{bold} otherwise.
@end defun
-@defun set-face-italic-p face italic-p &optional frame
+@defun set-face-italic face italic-p &optional frame
This sets the @code{:slant} attribute of @var{face} to @var{normal} if
@var{italic-p} is @code{nil}, and to @var{italic} otherwise.
@end defun
-@defun set-face-underline-p face underline &optional frame
+@defun set-face-underline face underline &optional frame
This sets the @code{:underline} attribute of @var{face} to
@var{underline}.
@end defun
-@defun set-face-inverse-video-p face inverse-video-p &optional frame
+@defun set-face-inverse-video face inverse-video-p &optional frame
This sets the @code{:inverse-video} attribute of @var{face} to
@var{inverse-video-p}.
@end defun
don't specify @var{frame}, they refer to the selected frame; @code{t}
refers to the default data for new frames. They return the symbol
@code{unspecified} if the face doesn't define any value for that
-attribute.
+attribute. If @var{inherit} is @code{nil}, only an attribute directly
+defined by the face is returned. If @var{inherit} is non-@code{nil},
+any faces specified by its @code{:inherit} attribute are considered as
+well, and if @var{inherit} is a face or a list of faces, then they are
+also considered, until a specified attribute is found. To ensure that
+the return value is always specified, use a value of @code{default} for
+@var{inherit}.
+
+@defun face-font face &optional frame
+This function returns the name of the font of face @var{face}.
+@end defun
@defun face-foreground face &optional frame inherit
@defunx face-background face &optional frame inherit
These functions return the foreground color (or background color,
respectively) of face @var{face}, as a string.
-
-If @var{inherit} is @code{nil}, only a color directly defined by the face is
-returned. If @var{inherit} is non-@code{nil}, any faces specified by its
-@code{:inherit} attribute are considered as well, and if @var{inherit}
-is a face or a list of faces, then they are also considered, until a
-specified color is found. To ensure that the return value is always
-specified, use a value of @code{default} for @var{inherit}.
@end defun
@defun face-stipple face &optional frame inherit
This function returns the name of the background stipple pattern of face
@var{face}, or @code{nil} if it doesn't have one.
-
-If @var{inherit} is @code{nil}, only a stipple directly defined by the
-face is returned. If @var{inherit} is non-@code{nil}, any faces
-specified by its @code{:inherit} attribute are considered as well, and
-if @var{inherit} is a face or a list of faces, then they are also
-considered, until a specified stipple is found. To ensure that the
-return value is always specified, use a value of @code{default} for
-@var{inherit}.
-@end defun
-
-@defun face-font face &optional frame
-This function returns the name of the font of face @var{face}.
@end defun
-@defun face-bold-p face &optional frame
+@defun face-bold-p face &optional frame inherit
This function returns a non-@code{nil} value if the @code{:weight}
attribute of @var{face} is bolder than normal (i.e., one of
@code{semi-bold}, @code{bold}, @code{extra-bold}, or
@code{ultra-bold}). Otherwise, it returns @code{nil}.
@end defun
-@defun face-italic-p face &optional frame
+@defun face-italic-p face &optional frame inherit
This function returns a non-@code{nil} value if the @code{:slant}
attribute of @var{face} is @code{italic} or @code{oblique}, and
@code{nil} otherwise.
@end defun
-@defun face-underline-p face &optional frame
-This function returns the @code{:underline} attribute of face @var{face}.
+@defun face-underline-p face &optional frame inherit
+This function returns non-@code{nil} if face @var{face} specifies
+a non-@code{nil} @code{:underline} attribute.
@end defun
-@defun face-inverse-video-p face &optional frame
-This function returns the @code{:inverse-video} attribute of face @var{face}.
+@defun face-inverse-video-p face &optional frame inherit
+This function returns non-@code{nil} if face @var{face} specifies
+a non-@code{nil} @code{:inverse-video} attribute.
@end defun
@node Displaying Faces
the ordinary definition of @var{face}.
@var{remapping} may be any face specification suitable for a
-@code{face} text property: either a face (i.e.@: a face name or a
+@code{face} text property: either a face (i.e., a face name or a
property list of attribute/value pairs), or a list of faces. For
details, see the description of the @code{face} text property in
@ref{Special Properties}. @var{remapping} serves as the complete
@itemx underline
@itemx fixed-pitch
@itemx variable-pitch
-These have the attributes indicated by their names (e.g. @code{bold}
+These have the attributes indicated by their names (e.g., @code{bold}
has a bold @code{:weight} attribute), with all other attributes
unspecified (and so given by @code{default}).
encoding of the font.
@end defun
-@defopt font-list-limit
-This variable specifies maximum number of fonts to consider in font
-matching. The function @code{x-family-fonts} will not return more
-than that many fonts, and font selection will consider only that many
-fonts when searching a matching font for face attributes. The default
-is 100.
-@end defopt
-
@node Fontsets
@subsection Fontsets
@xref{Fringe Bitmaps}, for a list of standard bitmap symbols and how
to define your own. In addition, @code{nil} represents the empty
-bitmap (i.e.@: an indicator that is not shown).
+bitmap (i.e., an indicator that is not shown).
When @code{fringe-indicator-alist} has a buffer-local value, and
there is no bitmap defined for a logical indicator, or the bitmap is
@itemx @code{vertical-bar}, @code{horizontal-bar}
Used for different types of fringe cursors.
-@item @code{empty-line}, @code{question-mark}, @code{exclamation-mark}
-Unused.
+@item @code{empty-line}, @code{exclamation-mark}, @code{question-mark}, @code{exclamation-mark}
+Not used by core Emacs features.
@end table
@noindent
property'' means all the consecutive characters that have the same
Lisp object as their @code{display} property; these characters are
replaced as a single unit. If two characters have different Lisp
-objects as their @code{display} properties (i.e.@: objects which are
+objects as their @code{display} properties (i.e., objects which are
not @code{eq}), they are handled separately.
Here is an example which illustrates this point. A string serves as
@item :index
@c Doesn't work: http://debbugs.gnu.org/7978
This has the same meaning as it does for GIF images (@pxref{GIF Images}),
-i.e. it specifies which image to view inside an image bundle file format
-such as DJVM. You can use the @code{image-metadata} function to
+i.e., it specifies which image to view inside an image bundle file format
+such as DJVM@. You can use the @code{image-metadata} function to
retrieve the total number of images in an image bundle.
@end table
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
-the image type, e.g.@: @code{xbm}, @var{file} is the file to load the
+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
@var{file} exists, is used to construct the image specification to be
@defun image-animated-p image
This function returns non-@code{nil} if @var{image} can be animated.
-The actual return value is a cons @code{(@var{nimages} . @var{delay})},
+The actual return value is a cons @code{(@var{nimages} . @var{delay})},
where @var{nimages} is the number of frames and @var{delay} is the
delay in seconds between them.
@end defun
(@pxref{Text Properties}) to hold the button properties. Such buttons
do not add markers to the buffer, so editing in the buffer does not
slow down if there is an extremely large numbers of buttons. However,
-if there is an existing face text property on the text (e.g.@: a face
+if there is an existing face text property on the text (e.g., a face
assigned by Font Lock mode), the button face may not be visible. Both
of these functions return the starting position of the new button.
@code{ctl-arrow}. If this variable is non-@code{nil} (the default),
these characters are displayed as sequences of two glyphs, where the
first glyph is @samp{^} (a display table can specify a glyph to use
-instead of @samp{^}); e.g.@: the @key{DEL} character is displayed as
+instead of @samp{^}); e.g., the @key{DEL} character is displayed as
@samp{^?}.
If @code{ctl-arrow} is @code{nil}, these characters are displayed as
@cindex glyphless characters
@dfn{Glyphless characters} are characters which are displayed in a
-special way, e.g.@: as a box containing a hexadecimal code, instead of
+special way, e.g., as a box containing a hexadecimal code, instead of
being displayed literally. These include characters which are
explicitly defined to be glyphless, as well as characters for which
there is no available font (on a graphical display), and characters
from right to left. Furthermore, segments of Latin script and digits
embedded in right-to-left text are displayed left-to-right, while
segments of right-to-left script embedded in left-to-right text
-(e.g.@: Arabic or Hebrew text in comments or strings in a program
+(e.g., Arabic or Hebrew text in comments or strings in a program
source file) are appropriately displayed right-to-left. We call such
mixtures of left-to-right and right-to-left text @dfn{bidirectional
text}. This section describes the facilities and options for editing
@cindex unicode bidirectional algorithm
@cindex bidirectional reordering
Text is stored in Emacs buffers and strings in @dfn{logical} (or
-@dfn{reading}) order, i.e.@: the order in which a human would read
+@dfn{reading}) order, i.e., the order in which a human would read
each character. In right-to-left and bidirectional text, the order in
which characters are displayed on the screen (called @dfn{visual
order}) is not the same as logical order; the characters' screen