+@node Fontsets
+@subsection Fontsets
+
+ A @dfn{fontset} is a list of fonts, each assigned to a range of
+character codes. An individual font cannot display the whole range of
+characters that Emacs supports, but a fontset can. Fontsets have names,
+just as fonts do, and you can use a fontset name in place of a font name
+when you specify the ``font'' for a frame or a face. Here is
+information about defining a fontset under Lisp program control.
+
+@defun create-fontset-from-fontset-spec fontset-spec &optional style-variant-p noerror
+This function defines a new fontset according to the specification
+string @var{fontset-spec}. The string should have this format:
+
+@smallexample
+@var{fontpattern}, @r{[}@var{charsetname}:@var{fontname}@r{]@dots{}}
+@end smallexample
+
+@noindent
+Whitespace characters before and after the commas are ignored.
+
+The first part of the string, @var{fontpattern}, should have the form of
+a standard X font name, except that the last two fields should be
+@samp{fontset-@var{alias}}.
+
+The new fontset has two names, one long and one short. The long name is
+@var{fontpattern} in its entirety. The short name is
+@samp{fontset-@var{alias}}. You can refer to the fontset by either
+name. If a fontset with the same name already exists, an error is
+signaled, unless @var{noerror} is non-@code{nil}, in which case this
+function does nothing.
+
+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
+status.
+
+The specification string also says which fonts to use in the fontset.
+See below for the details.
+@end defun
+
+ The construct @samp{@var{charset}:@var{font}} specifies which font to
+use (in this fontset) for one particular character set. Here,
+@var{charset} is the name of a character set, and @var{font} is the font
+to use for that character set. You can use this construct any number of
+times in the specification string.
+
+ For the remaining character sets, those that you don't specify
+explicitly, Emacs chooses a font based on @var{fontpattern}: it replaces
+@samp{fontset-@var{alias}} with a value that names one character set.
+For the @sc{ascii} character set, @samp{fontset-@var{alias}} is replaced
+with @samp{ISO8859-1}.
+
+ In addition, when several consecutive fields are wildcards, Emacs
+collapses them into a single wildcard. This is to prevent use of
+auto-scaled fonts. Fonts made by scaling larger fonts are not usable
+for editing, and scaling a smaller font is not useful because it is
+better to use the smaller font in its own size, which Emacs does.
+
+ Thus if @var{fontpattern} is this,
+
+@example
+-*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24
+@end example
+
+@noindent
+the font specification for @sc{ascii} characters would be this:
+
+@example
+-*-fixed-medium-r-normal-*-24-*-ISO8859-1
+@end example
+
+@noindent
+and the font specification for Chinese GB2312 characters would be this:
+
+@example
+-*-fixed-medium-r-normal-*-24-*-gb2312*-*
+@end example
+
+ You may not have any Chinese font matching the above font
+specification. Most X distributions include only Chinese fonts that
+have @samp{song ti} or @samp{fangsong ti} in the @var{family} field. In
+such a case, @samp{Fontset-@var{n}} can be specified as below:
+
+@smallexample
+Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\
+ chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-*
+@end smallexample
+
+@noindent
+Then, the font specifications for all but Chinese GB2312 characters have
+@samp{fixed} in the @var{family} field, and the font specification for
+Chinese GB2312 characters has a wild card @samp{*} in the @var{family}
+field.
+
+@node Display Property
+@section The @code{display} Property
+@cindex display specification
+@kindex display @r{(text property)}
+
+ The @code{display} text property (or overlay property) is used to
+insert images into text, and also control other aspects of how text
+displays. These features are available starting in Emacs 21. The value
+of the @code{display} property should be a display specification, or a
+list or vector containing several display specifications. The rest of
+this section describes several kinds of display specifications and what
+they mean.
+
+@menu
+* Specified Space:: Displaying one space with a specified width.
+* Other Display Specs:: Displaying an image; magnifying text; moving it
+ up or down on the page; adjusting the width
+ of spaces within text.
+* Display Margins:: Displaying text or images to the side of the main text.
+* Conditional Display:: Making any of the above features conditional
+ depending on some Lisp expression.
+@end menu
+
+@node Specified Space
+@subsection Specified Spaces
+@cindex spaces, specified height or width
+@cindex specified spaces
+@cindex variable-width spaces
+
+ To display a space of specified width and/or height, use a display
+specification of the form @code{(space . @var{props})}, where
+@var{props} is a property list (a list of alternating properties and
+values). You can put this property on one or more consecutive
+characters; a space of the specified height and width is displayed in
+place of @emph{all} of those characters. These are the properties you
+can use to specify the weight of the space:
+
+@table @code
+@item :width @var{width}
+Specifies that the space width should be @var{width} times the normal
+character width. @var{width} can be an integer or floating point
+number.
+
+@item :relative-width @var{factor}
+Specifies that the width of the stretch should be computed from the
+first character in the group of consecutive characters that have the
+same @code{display} property. The space width is the width of that
+character, multiplied by @var{factor}.
+
+@item :align-to @var{hpos}
+Specifies that the space should be wide enough to reach @var{hpos}. The
+value @var{hpos} is measured in units of the normal character width. It
+may be an interer or a floating point number.
+@end table
+
+ Exactly one of the above properties should be used. You can also
+specify the height of the space, with other properties:
+
+@table @code
+@item :height @var{height}
+Specifies the height of the space, as @var{height},
+measured in terms of the normal line height.
+
+@item :relative-height @var{factor}
+Specifies the height of the space, multiplying the ordinary height
+of the text having this display specification by @var{factor}.
+
+@item :ascent @var{ascent}
+Specifies that @var{ascent} percent of the height of the space should be
+considered as the ascent of the space---that is, the part above the
+baseline. The value of @var{ascent} must be a non-negative number no
+greater than 100.
+@end table
+
+ You should not use both @code{:height} and @code{:relative-height}
+together.
+
+@node Other Display Specs
+@subsection Other Display Specifications
+
+@table @code
+@item (image . @var{image-props})
+This is in fact an image descriptor (@pxref{Images}). When used as a
+display specification, it means to display the image instead of the text
+that has the display specification.
+
+@item (space-width @var{factor})
+This display specification affects all the space characters within the
+text that has the specification. It displays all of these spaces
+@var{factor} times as wide as normal. The element @var{factor} should
+be an integer or float. Characters other than spaces are not affected
+at all; in particular, this has no effect on tab characters.
+
+@item (height @var{height})
+This display specification makes the text taller or shorter.
+Here are the possibilities for @var{height}:
+
+@table @asis
+@item @code{(+ @var{n})}
+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
+height. Each size for which a suitable font is available counts as
+another step. @var{n} should be an integer.
+
+@item @code{(- @var{n})}
+This means to use a font that is @var{n} steps smaller.
+
+@item a number, @var{factor}
+A number, @var{factor}, means to use a font that is @var{factor} times
+as tall as the default font.
+
+@item a symbol, @var{function}
+A symbol is a function to compute the height. It is called with the
+current height as argument, and should return the new height to use.
+
+@item anything else, @var{form}
+If the @var{height} value doesn't fit the previous possibilities, it is
+a form. Emacs evaluates it to get the new height, with the symbol
+@code{height} bound to the current specified font height.
+@end table
+
+@item (raise @var{factor})
+This kind of display specification raises or lowers the text
+it applies to, relative to the baseline of the line.
+
+@var{factor} must be a number, which is interpreted as a multiple of the
+height of the affected text. If it is positive, that means to display
+the characters raised. If it is negative, that means to display them
+lower down.
+
+If the text also has a @code{height} display specification, that does
+not affect the amount of raising or lowering, which is based on the
+faces used for the text.
+@end table
+
+@node Display Margins
+@subsection Displaying in the Margins
+@cindex display margins
+@cindex margins, display
+
+ A buffer can have blank areas called @dfn{display margins} on the left
+and on the right. Ordinary text never appears in these areas, but you
+can put things into the display margins using the @code{display}
+property.
+
+ To put text in the left or right display margin of the window, use a
+display specification of the form @code{(margin right-margin)} or
+@code{(margin left-margin)} on it. To put an image in a display margin,
+use that display specification along with the display specification for
+the image.
+
+ Before the display margins can display anything, you must give
+them a nonzero width. The usual way to do that is to set these
+variables:
+
+@defvar left-margin-width
+@tindex left-margin-width
+This variable specifies the width of the left margin.
+It is buffer-local in all buffers.
+@end defvar
+
+@defvar right-margin-width
+@tindex right-margin-width
+This variable specifies the width of the right margin.
+It is buffer-local in all buffers.
+@end defvar
+
+ Setting these variables does not immediately affect the window. These
+variables are checked when a new buffer is displayed in the window.
+Thus, you can make changes take effect by calling
+@code{set-window-buffer}.
+
+ You can also set the margin widths immediately.
+
+@defun set-window-margins window left right
+@tindex set-window-margins
+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.
+@end defun
+
+@defun window-margins &optional window
+@tindex window-margins
+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.
+@end defun
+
+@node Conditional Display
+@subsection Conditional Display Specifications
+@cindex conditional display specifications
+
+ You can make any display specification conditional. To do that,
+package it in another list of the form @code{(when @var{condition} .
+@var{spec})}. Then the specification @var{spec} applies only when
+@var{condition} evaluates to a non-@code{nil} value. During the
+evaluation, point is temporarily set at the end position of the text
+having this conditional display specification.
+
+@node Images
+@section Images
+@cindex images in buffers
+
+ To display an image in an Emacs buffer, you must first create an image
+descriptor, then use it as a display specifier in the @code{display}
+property of text that is displayed (@pxref{Display Property}). Like the
+@code{display} property, this feature is available starting in Emacs 21.
+
+ Emacs can display a number of different image formats; some of them
+are supported only if particular support libraries are installed on your
+machine. The supported image formats include XBM, XPM (needing the
+libraries @code{libXpm} version 3.4k and @code{libz}), GIF (needing
+@code{libungif} 4.1.0), Postscript, PBM, JPEG (needing the
+@code{libjpeg} library version v6a), TIFF (needing @code{libtiff} v3.4),
+and PNG (needing @code{libpng} 1.0.2).
+
+ You specify one of these formats with an image type symbol. The image
+type symbols are @code{xbm}, @code{xpm}, @code{gif}, @code{postscript},
+@code{pbm}, @code{jpeg}, @code{tiff}, and @code{png}.
+
+@defvar image-types
+This variable contains a list of those image type symbols that are
+supported in the current configuration.
+@end defvar
+
+@menu
+* Image Descriptors:: How to specify an image for use in @code{:display}.
+* XBM Images:: Special features for XBM format.
+* XPM Images:: Special features for XPM format.
+* GIF Images:: Special features for GIF format.
+* Postscript Images:: Special features for Postscript format.
+* Other Image Types:: Various other formats are supported.
+* Defining Images:: Convenient ways to define an image for later use.
+* Showing Images:: Convenient ways to display an image once it is defined.
+* Image Cache:: Internal mechanisms of image display.
+@end menu
+
+@node Image Descriptors
+@subsection Image Descriptors
+@cindex image descriptor
+
+ An image description is a list of the form @code{(image
+. @var{props})}, where @var{props} is a property list containing
+alternating keyword symbols (symbols whose names start with a colon) and
+their values. You can use any Lisp object as a property, but the only
+properties that have any special meaning are certain symbols, all of
+them keywords.
+
+ Every image descriptor must contain the property @code{:type
+@var{type}} to specify the format of the image. The value of @var{type}
+should be an image type symbol; for example, @code{xpm} for an image in
+XPM format.
+
+ Here is a list of other properties that are meaningful for all image
+types:
+
+@table @code
+@item :ascent @var{ascent}
+The @code{:ascent} property specifies the amount of the image's
+height to use for its ascent---that is, the part above the baseline.
+The value, @var{ascent}, must be a number in the range 0 to 100, or
+the symbol @code{center}.
+
+If @var{ascent} is a number, that percentage of the image's height is
+used for its ascent.
+
+If @var{ascent} is @code{center}, the image is vertically centered
+around a centerline which would be the vertical centerline of text drawn
+at the position of the image, in the manner specified by the text
+properties and overlays that apply to the image.
+
+If this property is omitted, it defaults to 50.
+
+@item :margin @var{margin}
+The @code{:margin} property specifies how many pixels to add as an extra
+margin around the image. The value, @var{margin}, must be a
+non-negative number; if it is not specified, the default is zero.
+
+@item :relief @var{relief}
+The @code{:relief} property, if non-@code{nil}, adds a shadow rectangle
+around the image. The value, @var{relief}, specifies the width of the
+shadow lines, in pixels. If @var{relief} is negative, shadows are drawn
+so that the image appears as a pressed button; otherwise, it appears as
+an unpressed button.
+
+@item :algorithm @var{algorithm}
+The @code{:algorithm} property, if non-@code{nil}, specifies a
+conversion algorithm that should be applied to the image before it is
+displayed; the value, @var{algorithm}, specifies which algorithm.
+
+Currently, the only meaningful value for @var{algorithm} (aside from
+@code{nil}) is @code{laplace}; this applies the Laplace edge detection
+algorithm, which blurs out small differences in color while highlighting
+larger differences. People sometimes consider this useful for
+displaying the image for a ``disabled'' button.
+
+@item :heuristic-mask @var{transparent-color}
+The @code{:heuristic-mask} property, if non-@code{nil}, specifies that a
+certain color in the image should be transparent. Each pixel where this
+color appears will actually allow the frame's background to show
+through.
+
+If @var{transparent-color} is @code{t}, then determine the transparent
+color by looking at the four corners of the image. This uses the color
+that occurs most frequently near the corners as the transparent color.
+
+Otherwise, @var{heuristic-mask} should specify the transparent color
+directly, as a list of three integers in the form @code{(@var{red}
+@var{green} @var{blue})}.
+
+@item :file @var{file}
+The @code{:file} property specifies to load the image from file
+@var{file}. If @var{file} is not an absolute file name, it is expanded
+in @code{data-directory}.
+
+@item :data @var{data}
+The @code{:data} property specifies the actual contents of the image.
+Each image must use either @code{:data} or @code{:file}, but not both.
+For most image types, the value of the @code{:data} property should be a
+string containing the image data; we recommend using a unibyte string.
+
+Before using @code{:data}, look for further information in the section
+below describing the specific image format. For some image types,
+@code{:data} may not be supported; for some, it allows other data types;
+for some, @code{:data} alone is not enough, so you need to use other
+image properties along with @code{:data}.
+@end table
+
+@node XBM Images
+@subsection XBM Images
+@cindex XBM
+
+ To use XBM format, specify @code{xbm} as the image type. This image
+format doesn't require an external library, so images of this type are
+always supported.
+
+ Additional image properties supported for the @code{xbm} image type are:
+
+@table @code
+@item :foreground @var{foreground}
+The value, @var{foreground}, should be a string specifying the image
+foreground color. This color is used for each pixel in the XBM that is
+1. The default is the frame's foreground color.
+
+@item :background @var{background}
+The value, @var{background}, should be a string specifying the image
+background color. This color is used for each pixel in the XBM that is
+0. The default is the frame's background color.
+@end table
+
+ If you specify an XBM image using data within Emacs instead of an
+external file, use the following three properties:
+
+@table @code
+@item :data @var{data}
+The value, @var{data}, specifies the contents of the image.
+There are three formats you can use for @var{data}:
+
+@itemize @bullet
+@item
+A vector of strings or bool-vectors, each specifying one line of the
+image. Do specify @code{:height} and @code{:width}.
+
+@item
+A string containing the same byte sequence as an XBM file would contain.
+You must not specify @code{:height} and @code{:width} in this case,
+because omitting them is what indicates the data has the format of an
+XBM file. The file contents specify the height and width of the image.
+
+@item
+A string or a bool-vector containing the bits of the image (plus perhaps
+some extra bits at the end that will not be used). It should contain at
+least @var{width} * @code{height} bits. In this case, you must specify
+@code{:height} and @code{:width}, both to indicate that the string
+contains just the bits rather than a whole XBM file, and to specify the
+size of the image.
+@end itemize
+
+@item :width @var{width}
+The value, @var{width}, specifies the width of the image, in pixels.
+
+@item :height @var{height}
+The value, @var{height}, specifies the height of the image, in pixels.
+@end table
+
+@node XPM Images
+@subsection XPM Images
+@cindex XPM
+
+ To use XPM format, specify @code{xpm} as the image type. The
+additional image property @code{:color-symbols} is also meaningful with
+the @code{xpm} image type:
+
+@table @code
+@item :color-symbols @var{symbols}
+The value, @var{symbols}, should be an alist whose elements have the
+form @code{(@var{name} . @var{color})}. In each element, @var{name} is
+the name of a color as it appears in the image file, and @var{color}
+specifies the actual color to use for displaying that name.
+@end table
+
+@node GIF Images
+@subsection GIF Images
+@cindex GIF
+
+ For GIF images, specify image type @code{gif}. Because of the patents
+in the US covering the LZW algorithm, the continued use of GIF format is
+a problem for the whole Internet; to end this problem, it is a good idea
+for everyone, even outside the US, to stop using GIFS right away
+(@uref{http://www.burnallgifs.org/}). But if you still want to use
+them, Emacs can display them.
+
+@table @code
+@item :index @var{index}
+You can use @code{:index} to specify one image from a GIF file that
+contains more than one image. This property specifies use of image
+number @var{index} from the file. An error is signaled if the GIF file
+doesn't contain an image with index @var{index}.
+@end table
+
+@ignore
+This could be used to implement limited support for animated GIFs.
+For example, the following function displays a multi-image GIF file
+at point-min in the current buffer, switching between sub-images
+every 0.1 seconds.
+
+(defun show-anim (file max)
+ "Display multi-image GIF file FILE which contains MAX subimages."
+ (display-anim (current-buffer) file 0 max t))
+
+(defun display-anim (buffer file idx max first-time)
+ (when (= idx max)
+ (setq idx 0))
+ (let ((img (create-image file nil :image idx)))
+ (save-excursion
+ (set-buffer buffer)
+ (goto-char (point-min))
+ (unless first-time (delete-char 1))
+ (insert-image img))
+ (run-with-timer 0.1 nil 'display-anim buffer file (1+ idx) max nil)))
+@end ignore
+
+@node Postscript Images
+@subsection Postscript Images
+@cindex Postscript images
+
+ To use Postscript for an image, specify image type @code{postscript}.
+This works only if you have Ghostscript installed. You must always use
+these three properties:
+
+@table @code
+@item :pt-width @var{width}
+The value, @var{width}, specifies the width of the image measured in
+points (1/72 inch). @var{width} must be an integer.
+
+@item :pt-height @var{height}
+The value, @var{height}, specifies the height of the image in points
+(1/72 inch). @var{height} must be an integer.
+
+@item :bounding-box @var{box}
+The value, @var{box}, must be a list or vector of four integers, which
+specifying the bounding box of the Postscript image, analogous to the
+@samp{BoundingBox} comment found in Postscript files.
+
+@example
+%%BoundingBox: 22 171 567 738
+@end example
+@end table
+
+ Displaying Postscript images from Lisp data is not currently
+implemented, but it may be implemented by the time you read this.
+See the @file{etc/NEWS} file to make sure.
+
+@node Other Image Types
+@subsection Other Image Types
+@cindex PBM
+
+ For PBM images, specify image type @code{pbm}. Color, gray-scale and
+monochromatic images are supported.
+
+ For JPEG images, specify image type @code{jpeg}.
+
+ For TIFF images, specify image type @code{tiff}.
+
+ For PNG images, specify image type @code{png}.
+
+@node Defining Images
+@subsection Defining Images
+
+ The functions @code{create-image} and @code{defimage} provide
+convenient ways to create image descriptors.
+
+@defun create-image file &optional type &rest props
+@tindex create-image
+This function creates and returns an image descriptor which uses the
+data in @var{file}.
+
+The optional argument @var{type} is a symbol specifying the image type.
+If @var{type} is omitted or @code{nil}, @code{create-image} tries to
+determine the image type from the file's first few bytes, or else
+from the file's name.
+
+The remaining arguments, @var{props}, specify additional image
+properties---for example,
+
+@example
+(create-image "foo.xpm" 'xpm :heuristic-mask t)
+@end example
+
+The function returns @code{nil} if images of this type are not
+supported. Otherwise it returns an image descriptor.
+@end defun
+
+@defmac defimage variable doc &rest specs
+@tindex defimage
+This macro defines @var{variable} as an image name. The second argument,
+@var{doc}, is an optional documentation string. The remaining
+arguments, @var{specs}, specify alternative ways to display the image.
+
+Each argument in @var{specs} has the form of a property list, and each
+one should specify at least the @code{:type} property and the
+@code{:file} property. Here is an example:
+
+@example
+(defimage test-image
+ '((:type xpm :file "~/test1.xpm")
+ (:type xbm :file "~/test1.xbm")))
+@end example
+
+@code{defimage} tests each argument, one by one, to see if it is
+usable---that is, if the type is supported and the file exists. The
+first usable argument is used to make an image descriptor which is
+stored in the variable @var{variable}.
+
+If none of the alternatives will work, then @var{variable} is defined
+as @code{nil}.
+@end defmac
+
+@node Showing Images
+@subsection Showing Images
+
+ You can use an image descriptor by setting up the @code{display}
+property yourself, but it is easier to use the functions in this
+section.
+
+@defun insert-image image &optional string area
+This function inserts @var{image} in the current buffer at point. The
+value @var{image} should be an image descriptor; it could be a value
+returned by @code{create-image}, or the value of a symbol defined with
+@code{defimage}. The argument @var{string} specifies the text to put in
+the buffer to hold the image.
+
+The argument @var{area} specifies whether to put the image in a margin.
+If it is @code{left-margin}, the image appears in the left margin;
+@code{right-margin} specifies the right margin. If @var{area} is
+@code{nil} or omitted, the image is displayed at point within the
+buffer's text.
+
+Internally, this function inserts @var{string} in the buffer, and gives
+it a @code{display} property which specifies @var{image}. @xref{Display
+Property}.
+@end defun
+
+@defun put-image image pos &optional string area
+This function puts image @var{image} in front of @var{pos} in the
+current buffer. The argument @var{pos} should be an integer or a
+marker. It specifies the buffer position where the image should appear.
+The argument @var{string} specifies the text that should hold the image
+as an alternative to the default.
+
+The argument @var{image} must be an image descriptor, perhaps returned
+by @code{create-image} or stored by @code{defimage}.
+
+The argument @var{area} specifies whether to put the image in a margin.
+If it is @code{left-margin}, the image appears in the left margin;
+@code{right-margin} specifies the right margin. If @var{area} is
+@code{nil} or omitted, the image is displayed at point within the
+buffer's text.
+
+Internally, this function creates an overlay, and gives it a
+@code{before-string} property containing text that has a @code{display}
+property whose value is the image. (Whew!)
+@end defun
+
+@defun remove-images start end &optional buffer
+This function removes images in @var{buffer} between positions
+@var{start} and @var{end}. If @var{buffer} is omitted or @code{nil},
+images are removed from the current buffer.
+
+This removes only images that were put into @var{buffer} the way
+@code{put-image} does it, not images that were inserted with
+@code{insert-image} or in other ways.
+@end defun
+
+@node Image Cache
+@subsection Image Cache
+
+ Emacs stores images in an image cache when it displays them, so it can
+display them again more efficiently. It removes an image from the cache
+when it hasn't been displayed for a specified period of time.
+
+When an image is looked up in the cache, its specification is compared
+with cached image specifications using @code{equal}. This means that
+all images with equal specifications share the same image in the cache.
+
+@defvar image-cache-eviction-delay
+@tindex image-cache-eviction-delay
+This variable specifies the number of seconds an image can remain in the
+cache without being displayed. When an image is not displayed for this
+length of time, Emacs removes it from the image cache.
+
+If the value is @code{nil}, Emacs does not remove images from the cache
+except when you explicitly clear it. This mode can be useful for
+debugging.
+@end defvar
+
+@defun clear-image-cache &optional frame
+@tindex clear-image-cache
+This function clears the image cache. If @var{frame} is non-@code{nil},
+only the cache for that frame is cleared. Otherwise all frames' caches
+are cleared.