+specifiers.
+
+An image specifier is used for images (pixmaps, widgets and the like).
+It is used to describe the actual image in a glyph. It is instanced
+as an image-instance. Note that \"image\" as used in XEmacs does not
+actually refer to what the term \"image\" normally means (a picture,
+e.g. in .GIF or .JPG format, and called a \"pixmap\" in XEmacs), but
+includes all types of graphical elements, including pixmaps, widgets
+\(buttons, sliders, text fields, etc.) and even strings of text.
+
+Note that, in practice, you rarely, if ever, need to actually create
+an image specifier! (The function `make-image-specifier' exists mainly
+for completeness.) Pretty much the only use for image specifiers is to
+control how glyphs are displayed, and the image specifier associated
+with a glyph (the `image' property of a glyph) is created
+automatically when a glyph is created (see `make-glyph') and need not
+\(and cannot, for that matter) ever be changed. In fact, the design
+decision to create a separate image specifier type, rather than make
+glyphs themselves be specifiers, is debatable -- the other properties
+of glyphs are rarely used and could conceivably have been incorporated
+into the glyph's instantiator. The rarely used glyph types (buffer,
+pointer, icon) could also have been incorporated into the instantiator.
+
+Image instantiators come in many formats: `xbm', `xpm', `gif', `jpeg',
+etc. This describes the format of the data describing the image. The
+resulting image instances also come in many types -- `mono-pixmap',
+`color-pixmap', `text', `pointer', etc. This refers to the behavior of
+the image and the sorts of places it can appear. (For example, a
+color-pixmap image has fixed colors specified for it, while a
+mono-pixmap image comes in two unspecified shades \"foreground\" and
+\"background\" that are determined from the face of the glyph or
+surrounding text; a text image appears as a string of text and has an
+unspecified foreground, background, and font; a pointer image behaves
+like a mono-pixmap image but can only be used as a mouse pointer
+\[mono-pixmap images cannot be used as mouse pointers]; etc.) It is
+important to keep the distinction between image instantiator format and
+image instance type in mind. Typically, a given image instantiator
+format can result in many different image instance types (for example,
+`xpm' can be instanced as `color-pixmap', `mono-pixmap', or `pointer';
+whereas `cursor-font' can be instanced only as `pointer'), and a
+particular image instance type can be generated by many different
+image instantiator formats (e.g. `color-pixmap' can be generated by `xpm',
+`gif', `jpeg', etc.).
+
+See `make-image-instance' for a more detailed discussion of image
+instance types.
+
+An image instantiator should be a string or a vector of the form
+
+ [FORMAT :KEYWORD VALUE ...]
+
+i.e. a format symbol followed by zero or more alternating keyword-value
+pairs. FORMAT should be one of
+
+'nothing
+ Don't display anything; no keywords are valid for this.
+ Can only be instanced as `nothing'.
+'string
+ Display this image as a text string. Can only be instanced
+ as `text', although support for instancing as `mono-pixmap'
+ and `color-pixmap' should be added.
+'formatted-string
+ Display this image as a text string, with replaceable fields;
+ not currently implemented. (It is, instead, equivalent to `string'.)
+'xbm
+ An X bitmap; only if X or MS Windows support was compiled into this
+ XEmacs. Can be instanced as `mono-pixmap', `color-pixmap', or `pointer'.
+'xpm
+ An XPM pixmap; only if XPM support was compiled into this XEmacs.
+ Can be instanced as `color-pixmap', `mono-pixmap', or `pointer'.
+'xface
+ An X-Face bitmap, used to encode people's faces in e-mail messages;
+ only if X-Face support was compiled into this XEmacs. Can be
+ instanced as `mono-pixmap', `color-pixmap', or `pointer'.
+'gif
+ A GIF87 or GIF89 image; only if GIF support was compiled into this
+ XEmacs. NOTE: only the first frame of animated gifs will be displayed.
+ Can be instanced as `color-pixmap'.
+'jpeg
+ A JPEG image; only if JPEG support was compiled into this XEmacs.
+ Can be instanced as `color-pixmap'.
+'png
+ A PNG image; only if PNG support was compiled into this XEmacs.
+ Can be instanced as `color-pixmap'.
+'tiff
+ A TIFF image; only if TIFF support was compiled into this XEmacs.
+ Can be instanced as `color-pixmap'.
+'bmp
+ A MS Windows BMP image; only if MS Windows support was compiled into
+ this XEmacs. Can be instanced as `color-pixmap'.
+'cursor-font
+ One of the standard cursor-font names, such as \"watch\" or
+ \"right_ptr\" under X. Under X, this is, more specifically, any
+ of the standard cursor names from appendix B of the Xlib manual
+ [also known as the file <X11/cursorfont.h>] minus the XC_ prefix.
+ On other window systems, the valid names will be specific to the
+ type of window system. Can only be instanced as `pointer'.
+'mswindows-resource
+ An MS Windows pointer resource. Specifies a resource to retrieve
+ directly from the system (an OEM resource) or from a file, particularly
+ an executable file. If the resource is to be retrieved from a file, use
+ :file and optionally :resource-id. Otherwise use :resource-id. Always
+ specify :resource-type to specify the type (cursor, bitmap or icon) of
+ the resource. Possible values for :resource-id are listed below. Can
+ be instanced as `pointer' or `color-pixmap'.
+'font
+ A glyph from a font; i.e. the name of a font, and glyph index into it
+ of the form \"FONT fontname index [[mask-font] mask-index]\".
+ Currently can only be instanced as `pointer', although this should
+ probably be fixed.
+'subwindow
+ An embedded windowing system window. Can only be instanced as
+ `subwindow'.
+'button
+ A button widget; either a push button, radio button or toggle button.
+ Can only be instanced as `widget'.
+'combo-box
+ A drop list of selectable items in a widget, for editing text.
+ Can only be instanced as `widget'.
+'edit-field
+ A text editing widget. Can only be instanced as `widget'.
+'label
+ A static, text-only, widget; for displaying text. Can only be instanced
+ as `widget'.
+'layout
+ A widget for controlling the positioning of children underneath it.
+ Through the use of nested layouts, a widget hierarchy can be created
+ which can have the appearance of any standard dialog box or similar
+ arrangement; all of this is counted as one \"glyph\" and could appear
+ in many of the places that expect a single glyph. Can only be instanced
+ as `widget'.
+'native-layout
+ The native version of a layout widget. #### Document me better!
+ Can only be instanced as `widget'.
+'progress-gauge
+ A sliding widget, for showing progress. Can only be instanced as
+ `widget'.
+'tab-control
+ A tab widget; a series of user selectable tabs. Can only be instanced
+ as `widget'.
+'tree-view
+ A folding widget. Can only be instanced as `widget'.
+'scrollbar
+ A scrollbar widget. Can only be instanced as `widget'.
+'autodetect
+ XEmacs tries to guess what format the data is in. If X support
+ exists, the data string will be checked to see if it names a filename.
+ If so, and this filename contains XBM or XPM data, the appropriate
+ sort of pixmap or pointer will be created. [This includes picking up
+ any specified hotspot or associated mask file.] Otherwise, if `pointer'
+ is one of the allowable image-instance types and the string names a
+ valid cursor-font name, the image will be created as a pointer.
+ Otherwise, the image will be displayed as text. If no X support
+ exists, the image will always be displayed as text. Can be instanced as
+ `mono-pixmap', `color-pixmap', `pointer', or `text'.
+'inherit
+ Inherit from the background-pixmap property of a face. Can only be
+ instanced as `mono-pixmap'.
+
+The valid keywords are:
+
+:data
+ Inline data. For most formats above, this should be a string. For
+ XBM images, this should be a list of three elements: width, height, and
+ a string of bit data. This keyword is valid for all of the bitmap/pixmap
+ formats, as well as `string', `formatted-string', `font', `cursor-font',
+ and `autodetect'.
+:file
+ Data is contained in a file. The value is the name of this file.
+ If both :data and :file are specified, the image is created from
+ what is specified in :data and the string in :file becomes the
+ value of the `image-instance-file-name' function when applied to
+ the resulting image-instance. This keyword is valid for all of the
+ bitmap/pixmap formats as well as `mswindows-resource'.
+:foreground
+:background
+ For `xbm', `xface', `cursor-font', `widget' and `font'. These keywords
+ allow you to explicitly specify foreground and background colors.
+ The argument should be anything acceptable to `make-color-instance'.
+ This will cause what would be a `mono-pixmap' to instead be colorized
+ as a two-color color-pixmap, and specifies the foreground and/or
+ background colors for a pointer instead of black and white.
+:mask-data
+ For `xbm' and `xface'. This specifies a mask to be used with the
+ bitmap. The format is a list of width, height, and bits, like for
+ :data.
+:mask-file
+ For `xbm' and `xface'. This specifies a file containing the mask data.
+ If neither a mask file nor inline mask data is given for an XBM image,
+ and the XBM image comes from a file, XEmacs will look for a mask file
+ with the same name as the image file but with \"Mask\" or \"msk\"
+ appended. For example, if you specify the XBM file \"left_ptr\"
+ [usually located in \"/usr/include/X11/bitmaps\"], the associated
+ mask file \"left_ptrmsk\" will automatically be picked up.
+:hotspot-x
+:hotspot-y
+ For `xbm' and `xface'. These keywords specify a hotspot if the image
+ is instantiated as a `pointer'. Note that if the XBM image file
+ specifies a hotspot, it will automatically be picked up if no
+ explicit hotspot is given.
+:color-symbols
+ Only for `xpm'. This specifies an alist that maps strings
+ that specify symbolic color names to the actual color to be used
+ for that symbolic color (in the form of a string or a color-specifier
+ object). If this is not specified, the contents of `xpm-color-symbols'
+ are used to generate the alist.
+:resource-id
+ Only for `mswindows-resource'. This must be either an integer (which
+ directly specifies a resource number) or a string. Valid strings are
+
+ -- For bitmaps:
+
+ \"close\", \"uparrow\", \"dnarrow\", \"rgarrow\", \"lfarrow\",
+ \"reduce\", \"zoom\", \"restore\", \"reduced\", \"zoomd\",
+ \"restored\", \"uparrowd\", \"dnarrowd\", \"rgarrowd\", \"lfarrowd\",
+ \"mnarrow\", \"combo\", \"uparrowi\", \"dnarrowi\", \"rgarrowi\",
+ \"lfarrowi\", \"size\", \"btsize\", \"check\", \"checkboxes\", and
+ \"btncorners\".
+
+ -- For cursors:
+
+ \"normal\", \"ibeam\", \"wait\", \"cross\", \"up\", \"sizenwse\",
+ \"sizenesw\", \"sizewe\", \"sizens\", \"sizeall\", and \"no\".
+
+ -- For icons:
+
+ \"sample\", \"hand\", \"ques\", \"bang\", \"note\", and \"winlogo\".
+:resource-type
+ Only for `mswindows-resource'. This must be a symbol, either `cursor',
+ `icon', or `bitmap', specifying the type of resource to be retrieved.
+:face
+ Only for `inherit'. This specifies the face to inherit from.
+ For widgets this also specifies the face to use for display. It defaults
+ to gui-element-face.
+
+Keywords accepted as menu item specs are also accepted by widgets.
+These are `:selected', `:active', `:suffix', `:keys', `:style',
+`:filter', `:config', `:included', `:key-sequence', `:accelerator',
+`:label' and `:callback'.
+
+If instead of a vector, the instantiator is a string, it will be
+converted into a vector by looking it up according to the specs in the
+`console-type-image-conversion-list' (q.v.) for the console type of
+the domain (usually a window; sometimes a frame or device) over which
+the image is being instantiated.
+
+If the instantiator specifies data from a file, the data will be read
+in at the time that the instantiator is added to the image (which may
+be well before when the image is actually displayed), and the
+instantiator will be converted into one of the inline-data forms, with
+the filename retained using a :file keyword. This implies that the
+file must exist when the instantiator is added to the image, but does
+not need to exist at any other time (e.g. it may safely be a temporary
+file).
+"