@defun redisplay &optional force
This function tries immediately to redisplay. The optional argument
@var{force}, if non-@code{nil}, forces the redisplay to be performed,
-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.
+instead of being preempted if input is pending.
The function returns @code{t} if it actually tried to redisplay, and
@code{nil} otherwise. A value of @code{t} does not mean that
newly arriving input.
@end defun
-@defvar redisplay-dont-pause
-If this variable is @code{nil}, arriving input events preempt
-redisplay; Emacs avoids starting a redisplay, and stops any redisplay
-that is in progress, until the input has been processed. In
-particular, @code{(redisplay)} returns @code{nil} without actually
-redisplaying, if there is pending input.
-
-The default value is @code{t}, which means that pending input does not
-preempt redisplay.
-@end defvar
-
-@defvar redisplay-preemption-period
-If @code{redisplay-dont-pause} is @code{nil}, this variable specifies
-how many seconds Emacs waits between checks for new input during
-redisplay; if input arrives during this interval, redisplay stops and
-the input is processed. The default value is 0.1; if the value is
-@code{nil}, Emacs does not check for input during redisplay.
-
-This variable has no effect when @code{redisplay-dont-pause} is
-non-@code{nil} (the default).
-@end defvar
-
@defvar pre-redisplay-function
A function run just before redisplay. It is called with one argument,
the set of windows to redisplay.
In batch mode, the message is printed to the standard error stream,
followed by a newline.
+When @code{inhibit-message} is non-@code{nil}, no message will be displayed
+in the echo area, it will only be logged to @samp{*Messages*}.
+
If @var{format-string} is @code{nil} or the empty string,
@code{message} clears the echo area; if the echo area has been
expanded automatically, this brings it back to its normal size. If
depending on its size, use @code{display-message-or-buffer} (see below).
@end defun
+@defvar inhibit-message
+When this variable is non-@code{nil}, @code{message} and related functions
+will not use the Echo Area to display messages.
+@end defvar
+
@defmac with-temp-message message &rest body
This construct displays a message in the echo area temporarily, during
the execution of @var{body}. It displays @var{message}, executes
these affect the display of the text within the overlay.
@cindex scalability of overlays
+@cindex overlays, scalability
The visual effect of an overlay is the same as of the corresponding
text property (@pxref{Text Properties}). However, due to a different
implementation, overlays generally don't scale well (many operations
markers. If @var{buffer} is omitted, the overlay is created in the
current buffer.
+@cindex empty overlay
+@cindex overlay, empty
+An overlay whose @var{start} and @var{end} specify the same buffer
+position is known as @dfn{empty}. A non-empty overlay can become
+empty if the text between its @var{start} and @var{end} is deleted.
+When that happens, the overlay is by default not deleted, but you can
+cause it to be deleted by giving it the @samp{evaporate} property
+(@pxref{Overlay Properties, evaporate property}).
+
The arguments @var{front-advance} and @var{rear-advance} specify the
marker insertion type for the start of the overlay and for the end of
the overlay, respectively. @xref{Marker Insertion Types}. If they
@kindex evaporate @r{(overlay property)}
If this property is non-@code{nil}, the overlay is deleted automatically
if it becomes empty (i.e., if its length becomes zero). If you give
-an empty overlay a non-@code{nil} @code{evaporate} property, that deletes
-it immediately.
+an empty overlay (@pxref{Managing Overlays, empty overlay}) a
+non-@code{nil} @code{evaporate} property, that deletes it immediately.
+Note that, unless an overlay has this property, it will not be deleted
+when the text between its starting and ending positions is deleted
+from the buffer.
@item keymap
@cindex keymap of character (and overlays)
This function returns a list of the overlays that overlap the region
@var{beg} through @var{end}. ``Overlap'' means that at least one
character is contained within the overlay and also contained within the
-specified region; however, empty overlays are included in the result if
-they are located at @var{beg}, strictly between @var{beg} and @var{end},
-or at @var{end} when @var{end} denotes the position at the end of the
-buffer.
+specified region; however, empty overlays (@pxref{Managing Overlays,
+empty overlay}) are included in the result if they are located at
+@var{beg}, strictly between @var{beg} and @var{end}, or at @var{end}
+when @var{end} denotes the position at the end of the buffer.
@end defun
@defun next-overlay-change pos
Alternative foreground color, a string. This is like @code{:foreground}
but the color is only used as a foreground when the background color is
near to the foreground that would have been used. This is useful for
-example when marking text (i.e. the region face). If the text has a foreground
+example when marking text (i.e., the region face). If the text has a foreground
that is visible with the region face, that foreground is used.
If the foreground is near the region face background,
@code{:distant-foreground} is used instead so the text is readable.
functions instead of setting @code{face-remapping-alist} directly, to
avoid trampling on remappings applied elsewhere. These functions are
intended for buffer-local remappings, so they all make
-@code{face-remapping-alist} buffer-local as a side-effect. They manage
+@code{face-remapping-alist} buffer-local as a side-effect. They manage
@code{face-remapping-alist} entries of the form
@example
if you need to remove the remapping later.
@example
-;; Remap the `escape-glyph' face into a combination
-;; of the `highlight' and `italic' faces:
+;; Remap the 'escape-glyph' face into a combination
+;; of the 'highlight' and 'italic' faces:
(face-remap-add-relative 'escape-glyph 'highlight 'italic)
-;; Increase the size of the `default' face by 50%:
+;; Increase the size of the 'default' face by 50%:
(face-remap-add-relative 'default :height 1.5)
@end example
@end defun
@defun set-fontset-font name character font-spec &optional frame add
This function modifies the existing fontset @var{name} to use the font
-matching with @var{font-spec} for the character @var{character}.
+matching with @var{font-spec} for the specified @var{character}.
If @var{name} is @code{nil}, this function modifies the fontset of the
selected frame or that of @var{frame} if @var{frame} is not
If @var{name} is @code{t}, this function modifies the default
fontset, whose short name is @samp{fontset-default}.
-@var{character} may be a cons; @code{(@var{from} . @var{to})}, where
-@var{from} and @var{to} are character codepoints. In that case, use
-@var{font-spec} for all characters in the range @var{from} and @var{to}
-(inclusive).
+In addition to specifying a single codepoint, @var{character} may be a
+cons @code{(@var{from} . @var{to})}, where @var{from} and @var{to} are
+character codepoints. In that case, use @var{font-spec} for all the
+characters in the range @var{from} and @var{to} (inclusive).
@var{character} may be a charset. In that case, use
@var{font-spec} for all character in the charsets.
@var{character} may be a script name. In that case, use
@var{font-spec} for all character in the charsets.
+@var{font-spec} may be a font-spec object created by the function
+@code{font-spec} (@pxref{Low-Level Font}).
+
@var{font-spec} may be a cons; @code{(@var{family} . @var{registry})},
where @var{family} is a family name of a font (possibly including a
foundry name at the head), @var{registry} is a registry name of a font
@var{font-spec} may be a font name string.
+@var{font-spec} may be @code{nil}, which explicitly specifies that
+there's no font for the specified @var{character}. This is useful,
+for example, to avoid expensive system-wide search for fonts for
+characters that have no glyphs, like those from the Unicode Private
+Use Area (PUA).
+
The optional argument @var{add}, if non-@code{nil}, specifies how to
add @var{font-spec} to the font specifications previously set. If it
is @code{prepend}, @var{font-spec} is prepended. If it is
@item :script
The script that the font must support (a symbol).
+@item :lang
+The language that the font should support. The value should be a
+symbol whose name is a two-letter ISO-639 language name. On X, the
+value is matched against the ``Additional Style'' field of the XLFD
+name of a font, if it is non-empty. On MS-Windows, fonts matching the
+spec are required to support codepages needed for the language.
+Currently, only a small set of CJK languages is supported with this
+property: @samp{ja}, @samp{ko}, and @samp{zh}.
+
@item :otf
@cindex OpenType font
The font must be an OpenType font that supports these OpenType
faces used for the text.
@end table
-@c We put all the `@code{(when ...)}' on one line to encourage
+@c We put all the '@code{(when ...)}' on one line to encourage
@c makeinfo's end-of-sentence heuristics to DTRT. Previously, the dot
@c was at eol; the info file ended up w/ two spaces rendered after it.
You can make any display specification conditional. To do that,
specific tasks.
@defun define-button-type name &rest properties
-Define a `button type' called @var{name} (a symbol).
+Define a ``button type'' called @var{name} (a symbol).
The remaining arguments
form a sequence of @var{property value} pairs, specifying default
property values for buttons with this type (a button's type may be set
@end defun
@defun button-activate button &optional use-mouse-action
-Call @var{button}'s @code{action} property (i.e., invoke it). If
-@var{use-mouse-action} is non-@code{nil}, try to invoke the button's
-@code{mouse-action} property instead of @code{action}; if the button
-has no @code{mouse-action} property, use @code{action} as normal.
+Call @var{button}'s @code{action} property (i.e., invoke the function
+that is the value of that property, passing it the single argument
+@var{button}). If @var{use-mouse-action} is non-@code{nil}, try to
+invoke the button's @code{mouse-action} property instead of
+@code{action}; if the button has no @code{mouse-action} property, use
+@code{action} as normal.
@end defun
@defun button-label button
These are commands and functions for locating and operating on
buttons in an Emacs buffer.
-@code{push-button} is the command that a user uses to actually `push'
+@code{push-button} is the command that a user uses to actually ``push''
a button, and is bound by default in the button itself to @key{RET}
and to @key{mouse-2} using a local keymap in the button's overlay or
text properties. Commands that are useful outside the buttons itself,
@defvar standard-display-table
The value of this variable is the standard display table, which is
used when Emacs is displaying a buffer in a window with neither a
-window display table nor a buffer display table defined. Its default
-is @code{nil}.
+window display table nor a buffer display table defined, or when Emacs
+is outputting text to the standard output or error streams. Its
+default is @code{nil}.
@end defvar
The @file{disp-table} library defines several functions for changing
hexadecimal notation.
@item an @acronym{ASCII} string
-Display a box containing that string.
+Display a box containing that string. The string should contain at
+most 6 @acronym{ASCII} characters.
@item a cons cell @code{(@var{graphical} . @var{text})}
Display with @var{graphical} on graphical displays, and with
@noindent
The @code{thin-space}, @code{empty-box}, @code{hex-code}, and
@acronym{ASCII} string display methods are drawn with the
-@code{glyphless-char} face.
+@code{glyphless-char} face. On text terminals, a box is emulated by
+square brackets, @samp{[]}.
The char-table has one extra slot, which determines how to display any
character that cannot be displayed with any available font, or cannot
@samp{\230}).
@item format-control
-Characters of Unicode General Category `Cf', such as @samp{U+200E}
+Characters of Unicode General Category ``Cf'', such as @samp{U+200E}
(Left-to-Right Mark), but excluding characters that have graphic
images, such as @samp{U+00AD} (Soft Hyphen).
by the terminal's coding system.
@end table
-@c FIXME: this can also be `acronym', but that's not currently
+@c FIXME: this can also be 'acronym', but that's not currently
@c completely implemented; it applies only to the format-control
-@c group, and only works if the acronym is in `char-acronym-table'.
+@c group, and only works if the acronym is in 'char-acronym-table'.
The @var{method} symbol should be one of @code{zero-width},
@code{thin-space}, @code{empty-box}, or @code{hex-code}. These have
the same meanings as in @code{glyphless-char-display}, above.
This variable holds the value of @code{window-system} used for the
first frame created by Emacs during startup. (When Emacs is invoked
with the @option{--daemon} option, it does not create any initial
-frames, so @code{initial-window-system} is @code{nil}. @xref{Initial
-Options, daemon,, emacs, The GNU Emacs Manual}.)
+frames, so @code{initial-window-system} is @code{nil}, except on
+MS-Windows, where it is still @code{w32}. @xref{Initial Options,
+daemon,, emacs, The GNU Emacs Manual}.)
@end defvar
@defun window-system &optional frame