@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
@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>
@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
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