@code{condition-case}, the user won't see the error message; it could
show the message to the user by reporting it as a warning.)
+@c FIXME: Why use ‘(bytecomp)’ instead of ‘'bytecomp’ or simply
+@c ‘bytecomp’ here? The parens are part of ‘warning-type-format’ but
+@c not part of the warning type. --xfq
@cindex warning type
Each warning has a @dfn{warning type} to classify it. The type is a
list of symbols. The first symbol should be the custom group that you
@defun lwarn type level message &rest args
This function reports a warning using the value of @code{(format
-@var{message} @var{args}...)} as the message. In other respects it is
-equivalent to @code{display-warning}.
+@var{message} @var{args}...)} as the message in the @file{*Warnings*}
+buffer. In other respects it is equivalent to @code{display-warning}.
@end defun
@defun warn message &rest args
@dfn{Selective display} refers to a pair of related features for
hiding certain lines on the screen.
+@cindex explicit selective display
The first variant, explicit selective display, is designed for use
in a Lisp program: it controls which lines are hidden by altering the
text. This kind of hiding in some ways resembles the effect of the
@result{} #<buffer foo>
---------- Buffer: foo ----------
+
20
#<buffer foo>
@var{string} extends across the column @var{start-column}.
If @var{ellipsis} is non-@code{nil}, it should be a string which will
-replace the end of @var{str} (including any padding) if it extends
-beyond @var{end-column}, unless the display width of @var{str} is
-equal to or less than the display width of @var{ellipsis}. If
+replace the end of @var{string} (including any padding) if it extends
+beyond @var{width}, unless the display width of @var{string} is equal
+to or less than the display width of @var{ellipsis}. If
@var{ellipsis} is non-@code{nil} and not a string, it stands for
@code{"..."}.
@node Line Height
@section Line Height
@cindex line height
+@cindex height of a line
The total height of each display line consists of the height of the
contents of the line, plus optional additional vertical line spacing
to bring the total line height up to @var{total}. In this case, the
other ways to specify the line spacing are ignored.
+@cindex height spec
Any other kind of property value is a height spec, which translates
into a number---the specified line height. There are several ways to
write a height spec; here's how each of them translates into a number:
Whether or not characters should be strike-through, and in what
color. The value is used like that of @code{:overline}.
+@cindex 2D box
+@cindex 3D box
@item :box
Whether or not a box should be drawn around characters, its color, the
width of the box lines, and 3D appearance. Here are the possible
@end example
@end defun
+@c FIXME: Add an index for "relative face attribute", maybe here? --xfq
@defun face-attribute-relative-p attribute value
This function returns non-@code{nil} if @var{value}, when used as the
value of the face attribute @var{attribute}, is relative. This means
@code{mode-line} face.
@end defvar
+@cindex relative remapping, faces
+@cindex base remapping, faces
The following functions implement a higher-level interface to
@code{face-remapping-alist}. Most Lisp code should use these
functions instead of setting @code{face-remapping-alist} directly, to
@node Font Selection
@subsection Font Selection
+@cindex font selection
+@cindex selecting a font
Before Emacs can draw a character on a graphical display, it must
select a @dfn{font} for that character@footnote{In this context, the
until it finds a registry that does exist.
@end defopt
+@cindex scalable fonts
Emacs can make use of scalable fonts, but by default it does not use
them.
If optional argument @var{style-variant-p} is non-@code{nil}, that says
to create bold, italic and bold-italic variants of the fontset as well.
These variant fontsets do not have a short name, only a long one, which
-is made by altering @var{fontpattern} to indicate the bold or italic
+is made by altering @var{fontpattern} to indicate the bold and/or italic
status.
The specification string also says which fonts to use in the fontset.
@node Low-Level Font
@subsection Low-Level Font Representation
+@cindex font property
Normally, it is not necessary to manipulate fonts directly. In case
you need to do so, this section explains how.
@code{font-entity}.
@end defun
+@cindex font object
A font object is a Lisp object that represents a font that Emacs has
@dfn{opened}. Font objects cannot be modified in Lisp, but they can
be inspected.
specifies a position in that string.
@end defun
+@cindex font spec
A font spec is a Lisp object that contains a set of specifications
that can be used to find a font. More than one font may match the
specifications in a font spec.
Additional typographic style information for the font, such as
@samp{sans}. The value should be a string or a symbol.
+@cindex font registry
@item :registry
The charset registry and encoding of the font, such as
@samp{iso8859-1}. The value should be a string or a symbol.
The script that the font must support (a symbol).
@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
to @var{value}.
@end defun
+@cindex font entity
A font entity is a reference to a font that need not be open. Its
properties are intermediate between a font object and a font spec:
like a font object, and unlike a font spec, it refers to a single,
@defopt indicate-empty-lines
@cindex fringes, and empty line indication
+@cindex empty lines, indicating
When this is non-@code{nil}, Emacs displays a special glyph in the
fringe of each empty line at the end of the buffer, on graphical
displays. @xref{Fringes}. This variable is automatically
@end defopt
@defopt indicate-buffer-boundaries
+@cindex buffer boundaries, indicating
This buffer-local variable controls how the buffer boundaries and
window scrolling are indicated in the window fringes.
@xref{Fringe Bitmaps}.
@end ifnottex
+@c FIXME: I can't find the ‘fringes-indicator-alist’ variable. Maybe
+@c it should be ‘fringe-indicator-alist’ or ‘fringe-cursor-alist’? --xfq
When @code{fringe-cursor-alist} has a buffer-local value, and there is
no bitmap defined for a cursor type, the corresponding value from the
default value of @code{fringes-indicator-alist} is used.
@node Customizing Bitmaps
@subsection Customizing Fringe Bitmaps
+@cindex fringe bitmaps, customizing
@defun define-fringe-bitmap bitmap bits &optional height width align
This function defines the symbol @var{bitmap} as a new fringe bitmap,
@table @asis
@item @code{(+ @var{n})}
+@c FIXME: Add an index for "step"? --xfq
This means to use a font that is @var{n} steps larger. A ``step'' is
defined by the set of available fonts---specifically, those that match
what was otherwise specified for this text, in all attributes except
``disabled'' button.
@item (edge-detection :matrix @var{matrix} :color-adjust @var{adjust})
+@cindex edge detection, images
Specifies a general edge-detection algorithm. @var{matrix} must be
either a nine-element list or a nine-element vector of numbers. A pixel
at position @math{x/y} in the transformed image is computed from
image. @xref{Pointer Shape}, for available pointer shapes.
@item :map @var{map}
+@cindex image maps
This associates an image map of @dfn{hot spots} with this image.
An image map is an alist where each element has the format
wish. @code{:max-width} and @code{:max-height} will always preserve
the aspect ratio.
+@c FIXME: ‘:format-type’ or ‘:format’? --xfq
@item :format
ImageMagick tries to auto-detect the image type, but it isn't always
able to. By using @code{:format-type}, we can give ImageMagick a hint
The remaining arguments, @var{props}, specify additional image
properties---for example,
+@c ‘:heuristic-mask’ is not documented?
@example
(create-image "foo.xpm" 'xpm nil :heuristic-mask t)
@end example
@end defun
@defun image-size spec &optional pixels frame
+@cindex size of image
This function returns the size of an image as a pair
@w{@code{(@var{width} . @var{height})}}. @var{spec} is an image
specification. @var{pixels} non-@code{nil} means return sizes
from accidentally being loaded into Emacs. It only takes effect the
first time an image is loaded. Once an image is placed in the image
cache, it can always be displayed, even if the value of
-@var{max-image-size} is subsequently changed (@pxref{Image Cache}).
+@code{max-image-size} is subsequently changed (@pxref{Image Cache}).
@end defvar
@node Multi-Frame Images
@subsection Multi-Frame Images
+@cindex multi-frame images
@cindex animation
@cindex image animation