@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990-1995, 1998-2012 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
-@setfilename ../../info/display
-@node Display, System Interface, Processes, Top
+@node Display
@chapter Emacs Display
This chapter describes a number of features related to the 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
indicate truncated and continued lines (@pxref{Fringes}). On a text
terminal, a @samp{$} in the rightmost column of the window indicates
truncation; a @samp{\} on the rightmost column indicates a line that
-``wraps.'' (The display table can specify alternate characters to use
+``wraps''. (The display table can specify alternate characters to use
for this; @pxref{Display Tables}).
@defopt truncate-lines
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
message is printed immediately.
@end defun
-@defun progress-reporter-update reporter value
+@defun progress-reporter-update reporter &optional value
This function does the main work of reporting progress of your
operation. It displays the message of @var{reporter}, followed by
progress percentage determined by @var{value}. If percentage is zero,
likely negate your effort.
@end defun
-@defun progress-reporter-force-update reporter value &optional new-message
+@defun progress-reporter-force-update reporter &optional value new-message
This function is similar to @code{progress-reporter-update} except
that it prints a message in the echo area unconditionally.
echo area.
You should always call this function and not hope for
-@code{progress-reporter-update} to print ``100%.'' Firstly, it may
+@code{progress-reporter-update} to print ``100%''. Firstly, it may
never print it, there are many good reasons for this not to happen.
Secondly, ``done'' is more explicit.
@end defun
@findex collapse-delayed-warnings
@findex display-delayed-warnings
@noindent
-The function @code{collapse-delayed-warnings} iterates through
-@code{delayed-warnings-list}, removing repeated entries. The function
+The function @code{collapse-delayed-warnings} removes repeated entries
+from @code{delayed-warnings-list}. The function
@code{display-delayed-warnings} calls @code{display-warning} on each
of the entries in @code{delayed-warnings-list}, in turn, and then sets
@code{delayed-warnings-list} to @code{nil}.
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
This is the only valid way to change the endpoints of an overlay. Do
not try modifying the markers in the overlay by hand, as that fails to
update other vital data structures and can cause some overlays to be
-``lost.''
+``lost''.
@end defun
@defun remove-overlays &optional start end name value
@end example
Emacs stores the overlays of each buffer in two lists, divided
-around an arbitrary ``center position.'' One list extends backwards
+around an arbitrary ``center position''. One list extends backwards
through the buffer from that center position, and the other extends
forwards from that center position. The center position can be anywhere
in the buffer.
@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.
@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}).
A @dfn{face} is a collection of graphical @dfn{attributes} for
displaying text: font, foreground color, background color, optional
-underlining, and so on. Faces control how Emacs displays text in
-buffers, as well as other parts of the frame such as the mode line.
-@xref{Standard Faces,,, emacs, The GNU Emacs Manual}, for the list of
-faces Emacs normally comes with.
-
-@cindex face id
- For most purposes, you refer to a face in Lisp programs using its
-@dfn{face name}, which is usually a Lisp symbol. For backward
-compatibility, a face name can also be a string, which is equivalent
-to a Lisp symbol of the same name.
+underlining, etc. Faces control how Emacs displays text in buffers,
+as well as other parts of the frame such as the mode line.
+
+@cindex anonymous face
+ One way to represent a face is as a property list of attributes,
+like @code{(:foreground "red" :weight bold)}. For example, you can
+assign such an @dfn{anonymous face} as the value of the @code{face}
+text property; this causes Emacs to display the underlying text with
+the specified attributes. @xref{Special Properties}.
+
+@cindex face name
+ More commonly, a face is referred to via a @dfn{face name}: a Lisp
+symbol which is associated with a set of face attributes. Named faces
+are defined using the @code{defface} macro (@pxref{Defining Faces}).
+Emacs defines several standard named faces; @xref{Standard Faces,,,
+emacs, The GNU Emacs Manual}.
+
+ Many parts of Emacs require named faces, and do not accept anonymous
+faces. These include the functions documented in @ref{Attribute
+Functions}, and the variable @code{font-lock-keywords}
+(@pxref{Search-based Fontification}). Unless otherwise stated, we
+will use the term @dfn{face} to refer only to named faces.
+
+ For backward compatibility, you can also use a string to specify a
+face name; that is equivalent to a Lisp symbol with the same name.
@defun facep object
-This function returns a non-@code{nil} value if @var{object} is a Lisp
-symbol or string that names a face. Otherwise, it returns @code{nil}.
+This function returns a non-@code{nil} value if @var{object} is a
+named face: a Lisp symbol or string which serves as a face name.
+Otherwise, it returns @code{nil}.
@end defun
By default, each face name corresponds to the same set of attributes
attributes in one frame (@pxref{Attribute Functions}).
@menu
-* Defining Faces:: How to define a face.
* Face Attributes:: What is in a face?
+* Defining Faces:: How to define a face.
* Attribute Functions:: Functions to examine and set face attributes.
* Displaying Faces:: How Emacs combines the faces specified for a character.
* Face Remapping:: Remapping faces to alternative definitions.
* Low-Level Font:: Lisp representation for character display fonts.
@end menu
-@node Defining Faces
-@subsection Defining Faces
-
- The @code{defface} macro defines a face and specifies its default
-appearance. The user can subsequently customize the face using the
-Customize interface (@pxref{Customization}).
-
-@defmac defface face spec doc [keyword value]@dots{}
-This macro declares @var{face} as a customizable face whose default
-attributes are given by @var{spec}. You should not quote the symbol
-@var{face}, and it should not end in @samp{-face} (that would be
-redundant). The argument @var{doc} is a documentation string for the
-face. The additional @var{keyword} arguments have the same meanings
-as in @code{defgroup} and @code{defcustom} (@pxref{Common Keywords}).
-
-When @code{defface} executes, it defines the face according to
-@var{spec}, then uses any customizations that were read from the
-init file (@pxref{Init File}) to override that specification.
-
-When you evaluate a @code{defface} form with @kbd{C-M-x} in Emacs
-Lisp mode (@code{eval-defun}), a special feature of @code{eval-defun}
-overrides any customizations of the face. This way, the face reflects
-exactly what the @code{defface} says.
-
-@cindex face specification
-The @var{spec} argument is a @dfn{face specification}, which states
-how the face should appear on different kinds of terminals. It should
-be an alist whose elements each have the form @code{(@var{display}
-@var{atts})}. @var{display} specifies a class of terminals (see
-below), while @var{atts} is a property list of face attributes and
-their values, specifying the appearance of the face on matching
-terminals
-@iftex
-(see the next section for details about face attributes).
-@end iftex
-@ifnottex
-(@pxref{Face Attributes}, for details about face attributes).
-@end ifnottex
-
-The @var{display} part of an element of @var{spec} determines which
-frames the element matches. If more than one element of @var{spec}
-matches a given frame, the first element that matches is the one used
-for that frame. There are three possibilities for @var{display}:
-
-@table @asis
-@item @code{default}
-This element of @var{spec} doesn't match any frames; instead, it
-specifies defaults that apply to all frames. This kind of element, if
-used, must be the first element of @var{spec}. Each of the following
-elements can override any or all of these defaults.
-
-@item @code{t}
-This element of @var{spec} matches all frames. Therefore, any
-subsequent elements of @var{spec} are never used. Normally
-@code{t} is used in the last (or only) element of @var{spec}.
-
-@item a list
-If @var{display} is a list, each element should have the form
-@code{(@var{characteristic} @var{value}@dots{})}. Here
-@var{characteristic} specifies a way of classifying frames, and the
-@var{value}s are possible classifications which @var{display} should
-apply to. Here are the possible values of @var{characteristic}:
-
-@table @code
-@item type
-The kind of window system the frame uses---either @code{graphic} (any
-graphics-capable display), @code{x}, @code{pc} (for the MS-DOS console),
-@code{w32} (for MS Windows 9X/NT/2K/XP), or @code{tty}
-(a non-graphics-capable display).
-@xref{Window Systems, window-system}.
-
-@item class
-What kinds of colors the frame supports---either @code{color},
-@code{grayscale}, or @code{mono}.
-
-@item background
-The kind of background---either @code{light} or @code{dark}.
-
-@item min-colors
-An integer that represents the minimum number of colors the frame
-should support. This matches a frame if its
-@code{display-color-cells} value is at least the specified integer.
-
-@item supports
-Whether or not the frame can display the face attributes given in
-@var{value}@dots{} (@pxref{Face Attributes}). @xref{Display Face
-Attribute Testing}, for more information on exactly how this testing
-is done.
-@end table
-
-If an element of @var{display} specifies more than one @var{value} for a
-given @var{characteristic}, any of those values is acceptable. If
-@var{display} has more than one element, each element should specify a
-different @var{characteristic}; then @emph{each} characteristic of the
-frame must match one of the @var{value}s specified for it in
-@var{display}.
-@end table
-@end defmac
-
- Here's how the standard face @code{highlight} is defined:
-
-@example
-(defface highlight
- '((((class color) (min-colors 88) (background light))
- :background "darkseagreen2")
- (((class color) (min-colors 88) (background dark))
- :background "darkolivegreen")
- (((class color) (min-colors 16) (background light))
- :background "darkseagreen2")
- (((class color) (min-colors 16) (background dark))
- :background "darkolivegreen")
- (((class color) (min-colors 8))
- :background "green" :foreground "black")
- (t :inverse-video t))
- "Basic face for highlighting."
- :group 'basic-faces)
-@end example
-
- Internally, Emacs stores the face's default specification in its
-@code{face-defface-spec} symbol property (@pxref{Property Lists}).
-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
-session, but not saved; and the @code{theme-face} property stores an
-alist associating the active customization settings and Custom themes
-with their specifications for that face. The face's documentation
-string is stored in the @code{face-documentation} property. But
-normally you should not try to set any of these properties directly.
-@xref{Applying Customizations}, for the @code{custom-set-faces}
-function, which is used to apply customized face settings.
-
- People are sometimes tempted to create variables whose values
-specify a face to use. In the vast majority of cases, this is not
-necessary; it is preferable to simply use faces directly.
-
-@defopt frame-background-mode
-This option, if non-@code{nil}, specifies the background type to use for
-interpreting face definitions. If it is @code{dark}, then Emacs treats
-all frames as if they had a dark background, regardless of their actual
-background colors. If it is @code{light}, then Emacs treats all frames
-as if they had a light background.
-@end defopt
-
@node Face Attributes
@subsection Face Attributes
@cindex face attributes
- The effect of using a face is determined by a fixed set of @dfn{face
-attributes}. This table lists all the face attributes, their possible
-values, and their effects. You can specify more than one face for a
-given piece of text; Emacs merges the attributes of all the faces to
-determine how to display the text. @xref{Displaying Faces}.
+ @dfn{Face attributes} determine the visual appearance of a face.
+The following table lists all the face attributes, their possible
+values, and their effects.
- In addition to the values given below, each face attribute can also
-have the value @code{unspecified}. This special value means the face
-doesn't specify that attribute. In face merging, when the first face
-fails to specify a particular attribute, the next face gets a chance.
-However, the @code{default} face must specify all attributes.
+ Apart from the values given below, each face attribute can have the
+value @code{unspecified}. This special value means that the face
+doesn't specify that attribute directly. An @code{unspecified}
+attribute tells Emacs to refer instead to a parent face (see the
+description @code{:inherit} attribute below); or, failing that, to an
+underlying face (@pxref{Displaying Faces}). The @code{default} face
+must specify all attributes.
Some of these attributes are meaningful only on certain kinds of
displays. If your display cannot handle a certain attribute, the
@table @code
@item :family
Font family or fontset (a string). @xref{Fonts,,, emacs, The GNU
-Emacs Manual}. If you specify a font family name, the wild-card
-characters @samp{*} and @samp{?} are allowed. The function
-@code{font-family-list}, described below, returns a list of available
-family names. @xref{Fontsets}, for information about fontsets.
+Emacs Manual}, for more information about font families. The function
+@code{font-family-list} (see below) returns a list of available family
+names. @xref{Fontsets}, for information about fontsets.
@item :foundry
The name of the @dfn{font foundry} for the font family specified by
-the @code{:family} attribute (a string). The wild-card characters
-@samp{*} and @samp{?} are allowed. @xref{Fonts,,, emacs, The GNU
-Emacs Manual}.
+the @code{:family} attribute (a string). @xref{Fonts,,, emacs, The
+GNU Emacs Manual}.
@item :width
-Relative proportionate character width, also known as the character
-set width. This should be one of the symbols @code{ultra-condensed},
-@code{extra-condensed}, @code{condensed}, @code{semi-condensed},
-@code{normal}, @code{semi-expanded}, @code{expanded},
-@code{extra-expanded}, or @code{ultra-expanded}.
+Relative character width. This should be one of the symbols
+@code{ultra-condensed}, @code{extra-condensed}, @code{condensed},
+@code{semi-condensed}, @code{normal}, @code{semi-expanded},
+@code{expanded}, @code{extra-expanded}, or @code{ultra-expanded}.
@item :height
The height of the font. In the simplest case, this is an integer in
units of 1/10 point.
The value can also be a floating point number or a function, which
-specifies the height relative to an @dfn{underlying face} (i.e., a
-face that has a lower priority in the list described in
-@ref{Displaying Faces}). If the value is a floating point number,
+specifies the height relative to an @dfn{underlying face}
+(@pxref{Displaying Faces}). If the value is a floating point number,
that specifies the amount by which to scale the height of the
underlying face. If the value is a function, that function is called
with one argument, the height of the underlying face, and returns the
as extra bright, and any weight less than normal is displayed as
half-bright.
+@cindex italic text
@item :slant
Font slant---one of the symbols @code{italic}, @code{oblique},
@code{normal}, @code{reverse-italic}, or @code{reverse-oblique}. On
Background color, a string. The value can be a system-defined color
name, or a hexadecimal color specification. @xref{Color Names}.
+@cindex underlined text
@item :underline
-Whether or not characters should be underlined, and in what color. If
-the value is @code{t}, underlining uses the foreground color of the
-face. If the value is a string, underlining uses that color. The
-value @code{nil} means do not underline.
+Whether or not characters should be underlined, and in what
+way. The possible values of the @code{:underline} attribute are:
+
+@table @asis
+@item @code{nil}
+Don't underline.
+
+@item @code{t}
+Underline with the foreground color of the face.
+
+@item @var{color}
+Underline in color @var{color}, a string specifying a color.
+
+@item @code{(:color @var{color} :style @var{style})}
+@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}
+means to use a straight line.
+@end table
+@cindex overlined text
@item :overline
Whether or not characters should be overlined, and in what color.
-The value is used like that of @code{:underline}.
+If the value is @code{t}, overlining uses the foreground color of the
+face. If the value is a string, overlining uses that color. The
+value @code{nil} means do not overline.
+@cindex strike-through text
@item :strike-through
Whether or not characters should be strike-through, and in what
-color. The value is used like that of @code{:underline}.
+color. The value is used like that of @code{:overline}.
@item :box
Whether or not a box should be drawn around characters, its color, the
faces.
@end table
-For compatibility with Emacs 20, you can also specify values for two
-``fake'' face attributes: @code{:bold} and @code{:italic}. Their
-values must be either @code{t} or @code{nil}; a value of
-@code{unspecified} is not allowed. Setting @code{:bold} to @code{t}
-is equivalent to setting the @code{:weight} attribute to @code{bold},
-and setting it to @code{nil} is equivalent to setting @code{:weight}
-to @code{normal}. Setting @code{:italic} to @code{t} is equivalent to
-setting the @code{:slant} attribute to @code{italic}, and setting it
-to @code{nil} is equivalent to setting @code{:slant} to @code{normal}.
-
@defun font-family-list &optional frame
This function returns a list of available font family names. The
optional argument @var{frame} specifies the frame on which the text is
@code{nil} otherwise.
@end defun
+@node Defining Faces
+@subsection Defining Faces
+
+ The usual way to define a face is through the @code{defface} macro.
+This macro defines a face name, and associates that name with a set of
+face attributes. It also sets up the face so that the user can
+customize it via the Customize interface (@pxref{Customization}).
+
+@defmac defface face spec doc [keyword value]@dots{}
+This macro declares @var{face} as a customizable face whose default
+attributes are given by @var{spec}. You should not quote the symbol
+@var{face}, and it should not end in @samp{-face} (that would be
+redundant). The argument @var{doc} is a documentation string for the
+face. The additional @var{keyword} arguments have the same meanings
+as in @code{defgroup} and @code{defcustom} (@pxref{Common Keywords}).
+
+When @code{defface} executes, it defines the face according to
+@var{spec}, then uses any customizations that were read from the
+init file (@pxref{Init File}) to override that specification.
+
+When you evaluate a @code{defface} form with @kbd{C-M-x} in Emacs
+Lisp mode (@code{eval-defun}), a special feature of @code{eval-defun}
+overrides any customizations of the face. This way, the face reflects
+exactly what the @code{defface} says.
+
+@cindex face specification
+The @var{spec} argument is a @dfn{face specification}, which states
+how the face should appear on different kinds of terminals. It should
+be an alist whose elements each have the form
+
+@example
+(@var{display} . @var{plist})
+@end example
+
+@noindent
+@var{display} specifies a class of terminals (see below). @var{plist}
+is a property list of face attributes and their values, specifying how
+the face appears on such terminals. For backward compatibility, you
+can also write an element as @code{(@var{display} @var{plist})}.
+
+The @var{display} part of an element of @var{spec} determines which
+terminals the element matches. If more than one element of @var{spec}
+matches a given terminal, the first element that matches is the one
+used for that terminal. There are three possibilities for
+@var{display}:
+
+@table @asis
+@item @code{default}
+This element of @var{spec} doesn't match any terminal; instead, it
+specifies defaults that apply to all terminals. This element, if
+used, must be the first element of @var{spec}. Each of the following
+elements can override any or all of these defaults.
+
+@item @code{t}
+This element of @var{spec} matches all terminals. Therefore, any
+subsequent elements of @var{spec} are never used. Normally @code{t}
+is used in the last (or only) element of @var{spec}.
+
+@item a list
+If @var{display} is a list, each element should have the form
+@code{(@var{characteristic} @var{value}@dots{})}. Here
+@var{characteristic} specifies a way of classifying terminals, and the
+@var{value}s are possible classifications which @var{display} should
+apply to. Here are the possible values of @var{characteristic}:
+
+@table @code
+@item type
+The kind of window system the terminal uses---either @code{graphic}
+(any graphics-capable display), @code{x}, @code{pc} (for the MS-DOS
+console), @code{w32} (for MS Windows 9X/NT/2K/XP), or @code{tty} (a
+non-graphics-capable display). @xref{Window Systems, window-system}.
+
+@item class
+What kinds of colors the terminal supports---either @code{color},
+@code{grayscale}, or @code{mono}.
+
+@item background
+The kind of background---either @code{light} or @code{dark}.
+
+@item min-colors
+An integer that represents the minimum number of colors the terminal
+should support. This matches a terminal if its
+@code{display-color-cells} value is at least the specified integer.
+
+@item supports
+Whether or not the terminal can display the face attributes given in
+@var{value}@dots{} (@pxref{Face Attributes}). @xref{Display Face
+Attribute Testing}, for more information on exactly how this testing
+is done.
+@end table
+
+If an element of @var{display} specifies more than one @var{value} for
+a given @var{characteristic}, any of those values is acceptable. If
+@var{display} has more than one element, each element should specify a
+different @var{characteristic}; then @emph{each} characteristic of the
+terminal must match one of the @var{value}s specified for it in
+@var{display}.
+@end table
+@end defmac
+
+ Here's how the standard face @code{highlight} is defined:
+
+@example
+(defface highlight
+ '((((class color) (min-colors 88) (background light))
+ :background "darkseagreen2")
+ (((class color) (min-colors 88) (background dark))
+ :background "darkolivegreen")
+ (((class color) (min-colors 16) (background light))
+ :background "darkseagreen2")
+ (((class color) (min-colors 16) (background dark))
+ :background "darkolivegreen")
+ (((class color) (min-colors 8))
+ :background "green" :foreground "black")
+ (t :inverse-video t))
+ "Basic face for highlighting."
+ :group 'basic-faces)
+@end example
+
+ Internally, Emacs stores the face's default specification in its
+@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
+session, but not saved; and the @code{theme-face} property stores an
+alist associating the active customization settings and Custom themes
+with their specifications for that face. The face's documentation
+string is stored in the @code{face-documentation} property. But
+normally you should not try to set any of these properties directly.
+@xref{Applying Customizations}, for the @code{custom-set-faces}
+function, which is used to apply customized face settings.
+
+ People are sometimes tempted to create variables whose values
+specify a face to use. In the vast majority of cases, this is not
+necessary; it is preferable to simply use faces directly.
+
@node Attribute Functions
@subsection Face Attribute Functions
This section describes the functions for accessing and modifying the
-attributes of an existing face.
+attributes of an existing named face.
@defun set-face-attribute face frame &rest arguments
This function sets one or more attributes of @var{face} for
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
@subsection Displaying Faces
- Here is how Emacs determines the face to use for displaying any
-given piece of text:
+ When Emacs displays a given piece of text, the visual appearance of
+the text may be determined by faces drawn from different sources. If
+these various sources together specify more than one face for a
+particular character, Emacs merges the attributes of the various
+faces. Here is the order in which Emacs merges the faces, from
+highest to lowest priority:
@itemize @bullet
@item
@item
If the text lies within an overlay with a non-@code{nil} @code{face}
-property, Emacs applies the face or face attributes specified by that
-property. If the overlay has a @code{mouse-face} property and the
-mouse is ``near enough'' to the overlay, Emacs applies the face or
-face attributes specified by the @code{mouse-face} property instead.
-@xref{Overlay Properties}.
+property, Emacs applies the face(s) specified by that property. If
+the overlay has a @code{mouse-face} property and the mouse is ``near
+enough'' to the overlay, Emacs applies the face or face attributes
+specified by the @code{mouse-face} property instead. @xref{Overlay
+Properties}.
When multiple overlays cover one character, an overlay with higher
priority overrides those with lower priority. @xref{Overlays}.
steps, Emacs applies the attribute of the @code{default} face.
@end itemize
- If these various sources together specify more than one face for a
-particular character, Emacs merges the attributes of the various faces
-specified. For each attribute, Emacs tries using the above order
-(i.e.@: first the face of any special glyph; then the face for region
-highlighting, if appropriate; and so on).
+ At each stage, if a face has a valid @code{:inherit} attribute,
+Emacs treats any attribute with an @code{unspecified} value as having
+the corresponding value drawn from the parent face(s). @pxref{Face
+Attributes}. Note that the parent face(s) may also leave the
+attribute unspecified; in that case, the attribute remains unspecified
+at the next level of face merging.
@node Face Remapping
@subsection Face Remapping
The value of this variable is an alist whose elements have the form
@code{(@var{face} . @var{remapping})}. This causes Emacs to display
any text having the face @var{face} with @var{remapping}, rather than
-the ordinary definition of @var{face}. @var{remapping} may be any
-face specification suitable for a @code{face} text property: either a
-face name, or a property list of attribute/value pairs, or a list in
-which each element is either a face name or a property list
-(@pxref{Special Properties}).
+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
+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
+specification for the remapped face---it replaces the normal
+definition of @var{face}, instead of modifying it.
If @code{face-remapping-alist} is buffer-local, its local value takes
effect only within that buffer.
-Two points bear emphasizing:
-
-@enumerate
-@item
-@var{remapping} serves as the complete specification for the remapped
-face---it replaces the normal definition of @var{face}, instead of
-modifying it.
-
-@item
-If @var{remapping} references the same face name @var{face}, either
-directly or via the @code{:inherit} attribute of some other face in
-@var{remapping}, that reference uses the normal definition of
-@var{face}. In other words, the remapping cannot be recursive.
+Note: face remapping is non-recursive. If @var{remapping} references
+the same face name @var{face}, either directly or via the
+@code{:inherit} attribute of some other face in @var{remapping}, that
+reference uses the normal definition of @var{face}. For instance, if
+the @code{mode-line} face is remapped using this entry in
+@code{face-remapping-alist}:
-For instance, if the @code{mode-line} face is remapped using this
-entry in @code{face-remapping-alist}:
@example
(mode-line italic mode-line)
@end example
+
@noindent
then the new definition of the @code{mode-line} face inherits from the
@code{italic} face, and the @emph{normal} (non-remapped) definition of
@code{mode-line} face.
-@end enumerate
@end defvar
The following functions implement a higher-level interface to
(put 'modeline 'face-alias 'mode-line)
@end example
-@defun define-obsolete-face-alias obsolete-face current-face &optional when
-This function defines a face alias and marks it as obsolete, indicating
-that it may be removed in future. The optional string @var{when}
-indicates when the face was made obsolete (for example, a release number).
-@end defun
+@defmac define-obsolete-face-alias obsolete-face current-face when
+This macro defines @code{obsolete-face} as an alias for
+@var{current-face}, and also marks it as obsolete, indicating that it
+may be removed in future. @var{when} should be a string indicating
+when @code{obsolete-face} was made obsolete (usually a version number
+string).
+@end defmac
@node Auto Faces
@subsection Automatic Face Assignment
@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
-@defvar 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
-currently 100.
-@end defvar
-
@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}
-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
@end ifnottex
@item disabled
-Specifies transforming the image so that it looks ``disabled.''
+Specifies transforming the image so that it looks ``disabled''.
@end table
@item :mask @var{mask}
@cindex images, support for more formats
If you build Emacs with ImageMagick support, you can use the
-ImageMagick library to load many image formats. The image type symbol
+ImageMagick library to load many image formats (@pxref{File
+Conveniences,,, emacs, The GNU Emacs Manual}). The image type symbol
for images loaded via ImageMagick is @code{imagemagick}, regardless of
the actual underlying image format.
@defun imagemagick-types
This function returns a list of image file extensions supported by the
-current ImageMagick installation.
-@end defun
-
- By default, Emacs does not use ImageMagick to display images in
-Image mode, e.g.@: when visiting such files with @kbd{C-x C-f}. This
-feature is enabled by calling @code{imagemagick-register-types}.
-
-@defun imagemagick-register-types
-This function enables using Image mode to visit image files supported
-by ImageMagick. @xref{File Conveniences,,, emacs, The GNU Emacs
-Manual}. It also causes @code{create-image} and other helper
-functions to associate such file names with the @code{imagemagick}
-image type (@pxref{Defining Images}).
-
-All image file extensions supported by ImageMagick are registered,
-except those specified in @code{imagemagick-types-inhibit}. If Emacs
-was not compiled with ImageMagick support, this function does nothing.
-@end defun
+current ImageMagick installation. Each list element is a symbol
+representing an internal ImageMagick name for an image type, such as
+@code{BMP} for @file{.bmp} images.
+@end defun
+
+@defopt imagemagick-enabled-types
+The value of this variable is a list of ImageMagick image types which
+Emacs may attempt to render using ImageMagick. Each list element
+should be one of the symbols in the list returned by
+@code{imagemagick-types}, or an equivalent string. Alternatively, a
+value of @code{t} enables ImageMagick for all possible image types.
+Regardless of the value of this variable,
+@code{imagemagick-types-inhibit} (see below) takes precedence.
+@end defopt
@defopt imagemagick-types-inhibit
-This variable specifies a list of image types that should @emph{not}
-be registered by @code{imagemagick-register-types}. Each entry in
-this list should be one of the symbols returned by
-@code{imagemagick-types}. The default value lists several file types
-that are considered ``images'' by ImageMagick, but which should not be
-considered as images by Emacs, including C files and HTML files.
+The value of this variable lists the ImageMagick image types which
+should never be rendered using ImageMagick, regardless of the value of
+@code{imagemagick-enabled-types}. A value of @code{t} disables
+ImageMagick entirely.
@end defopt
-@ignore
-@c I don't know what this means. I suspect it means eg loading jpg
-@c images via libjpeg or ImageMagick. But it doesn't work.
-@c If you don't have libjpeg support compiled in, you cannot
-@c view jpeg images, even if you have imagemagick support:
-@c http://debbugs.gnu.org/9045
-@c And if you have both compiled in, then you always get
-@c the libjpeg version:
-@c http://debbugs.gnu.org/10746
-There may be overlap between image loaders in your Emacs installation,
-and you may prefer to use a different one for a given image type
-(which loader will be used in practice depends on the priority of the
-loaders).
-For example, if you never want to use the ImageMagick loader to view
-JPEG files, add @code{JPG} to this list.
-@end ignore
-
Images loaded with ImageMagick support the following additional
image descriptor properties:
@table @code
+@item :background @var{background}
+@var{background}, if non-@code{nil}, should be a string specifying a
+color, which is used as the image's background color if the image
+supports transparency. If the value is @code{nil}, it defaults to the
+frame's background color.
+
@item :width, :height
The @code{:width} and @code{:height} keywords are used for scaling the
image. If only one of them is specified, the other one will be
@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
The following functions related to animated images are available.
@defun image-animated-p image
-This function returns non-nil if @var{image} can be animated.
-The actual return value is a cons @code{(@var{nimages} . @var{delay})},
+This function returns non-@code{nil} if @var{image} can be animated.
+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.
@subsection Abstract Display Example
Here is a simple example using functions of the ewoc package to
-implement a ``color components display,'' an area in a buffer that
+implement a ``color components display'', an area in a buffer that
represents a vector of three integers (itself representing a 24-bit RGB
value) in various ways.
@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
@strong{Warning:} if you use the display table to change the display
of newline characters, the whole buffer will be displayed as one long
-``line.''
+``line''.
The display table also has six ``extra slots'' which serve special
purposes. Here is a table of their meanings; @code{nil} in any slot
@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
@defvar ring-bell-function
If this is non-@code{nil}, it specifies how Emacs should ``ring the
-bell.'' Its value should be a function of no arguments. If this is
+bell''. Its value should be a function of no arguments. If this is
non-@code{nil}, it takes precedence over the @code{visible-bell}
variable.
@end defvar
@section Window Systems
Emacs works with several window systems, most notably the X Window
-System. Both Emacs and X use the term ``window,'' but use it
+System. Both Emacs and X use the term ``window'', but use it
differently. An Emacs frame is a single window as far as X is
concerned; the individual Emacs windows are not known to X at all.
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