@end defopt
@defopt truncate-partial-width-windows
+@cindex partial-width windows
This variable controls line truncation in @dfn{partial-width} windows.
A partial-width window is one that does not occupy the entire frame
width (@pxref{Splitting Windows}). If the value is @code{nil}, line
continuation to display them, computing the continuation lines can
make redisplay slow. The column computation and indentation functions
also become slow. Then you might find it advisable to set
-@code{cache-long-line-scans} to @code{t}.
+@code{cache-long-scans} to @code{t}.
-@defvar cache-long-line-scans
+@defvar cache-long-scans
If this variable is non-@code{nil}, various indentation and motion
functions, and Emacs redisplay, cache the results of scanning the
buffer, and consult the cache to avoid rescanning regions of the buffer
@cindex error display
@cindex echo area
+@c FIXME: Why not use @xref{Minibuffers} directly? --xfq
The @dfn{echo area} is used for displaying error messages
(@pxref{Errors}), for messages made with the @code{message} primitive,
and for echoing keystrokes. It is not the same as the minibuffer,
@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>
@node Overlays
@section Overlays
@cindex overlays
+@c FIXME: mention intervals in this section?
You can use @dfn{overlays} to alter the appearance of a buffer's text on
the screen, for the sake of presentation features. An overlay is an
@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
variables:
@defvar left-margin-width
-This variable specifies the width of the left margin.
-It is buffer-local in all buffers.
+This variable specifies the width of the left margin, in character
+cell (a.k.a.@: ``column'') units. It is buffer-local in all buffers.
+A value of @code{nil} means no left marginal area.
@end defvar
@defvar right-margin-width
-This variable specifies the width of the right margin.
-It is buffer-local in all buffers.
+This variable specifies the width of the right margin, in character
+cell units. It is buffer-local in all buffers. A value of @code{nil}
+means no right marginal area.
@end defvar
Setting these variables does not immediately affect the window. These
You can also set the margin widths immediately.
@defun set-window-margins window left &optional right
-This function specifies the margin widths for window @var{window}.
-The argument @var{left} controls the left margin and
-@var{right} controls the right margin (default @code{0}).
+This function specifies the margin widths for window @var{window}, in
+character cell units. The argument @var{left} controls the left
+margin, and @var{right} controls the right margin (default @code{0}).
@end defun
@defun window-margins &optional window
-This function returns the left and right margins of @var{window}
-as a cons cell of the form @code{(@var{left} . @var{right})}.
-If @var{window} is @code{nil}, the selected window is used.
+This function returns the width of the left and right margins of
+@var{window} as a cons cell of the form @w{@code{(@var{left}
+. @var{right})}}. If one of the two marginal areas does not exist,
+its width is returned as @code{nil}; if neither of the two margins exist,
+the function returns @code{(nil)}. If @var{window} is @code{nil}, the
+selected window is used.
@end defun
@node Images
``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
+to try to help it. It's used in conjunction with the
+@code{image-format-suffixes} variable, which provides a mapping from
+content types to file name suffixes. This is then given to
+ImageMagick as a file name hint.
+
@item :rotation
Specifies a rotation angle in degrees.
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