--- a/lisp/ChangeLog	Tue Feb 22 22:52:03 2005 +0000
+++ b/lisp/ChangeLog	Tue Feb 22 23:38:50 2005 +0000
@@ -1,3 +1,23 @@
+2005-02-21  Ben Wing  <ben@xemacs.org>
+
+	* glyphs.el:
+	* glyphs.el (make-image-specifier):
+	* glyphs.el (glyph-property):
+	* glyphs.el (convert-glyph-property-into-specifier):
+	* glyphs.el (set-glyph-property):
+	* glyphs.el (glyph-image):
+	* glyphs.el (set-glyph-image):
+	* glyphs.el (glyph-contrib-p):
+	* glyphs.el (glyph-contrib-p-instance):
+	* glyphs.el (set-glyph-contrib-p):
+	* glyphs.el (glyph-baseline):
+	* glyphs.el (set-glyph-baseline):
+	* glyphs.el (make-glyph):
+	Update documentation of `make-glyph' and `make-image-specifier'
+	to more clearly document image instantiators and describe how
+	errors are handled in make-glyph.  Also fix symbol references in
+	doc strings to use `symbol' format, not 'symbol.
+
 2005-02-21  Stephen J. Turnbull  <stephen@xemacs.org>
 
 	* about.el (about-xemacs):

--- a/lisp/glyphs.el	Tue Feb 22 22:52:03 2005 +0000
+++ b/lisp/glyphs.el	Tue Feb 22 23:38:50 2005 +0000
@@ -1,7 +1,7 @@
 ;;; glyphs.el --- Lisp interface to C glyphs
 
 ;; Copyright (C) 1994, 1997 Free Software Foundation, Inc.
-;; Copyright (C) 1995, 1996, 2000 Ben Wing.
+;; Copyright (C) 1995, 1996, 2000, 2005 Ben Wing.
 
 ;; Author: Chuck Thompson <cthomp@cs.uiuc.edu>, Ben Wing <ben@xemacs.org>
 ;; Maintainer: XEmacs Development Team
@@ -47,149 +47,129 @@
 of instantiators.  See `make-specifier' for more information about
 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.
+The main purpose of this doc string is to describe the possible formats for
+image instantiators, as given as an argument to `make-glyph' or
+`set-glyph-image'.
 
 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
+pairs.  The vector form of an image instantiator explicitly specifies the
+format of the image and other relevant properties.  The string form
+specifies only a filename or gives inline data of an unspecified format,
+and XEmacs must guess the actual format.  Once it has done this, it
+internally converts the instantiator into the vector format.  This is
+described in more detail below.
 
-'nothing
+Following is a list of the possible values for FORMAT.  After each
+description, the allowable keywords for the format are listed in brackets,
+followed by the possible image instance types that can be generated from
+this format. (Image instance types will be discussed below.)
+
+`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
+   [] (nothing)
+`string'
+   Display this image as a text string.  Support for instantiating as
+   `mono-pixmap' and `color-pixmap' should probably be added.
+   [:data] (text)
+`formatted-string'
+   Display this image as a text string, with replaceable fields.
+   Not currently implemented -- it's treated like `string'.
+   [:data] (text)
+`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.
+   [:data, :file] (color-pixmap, pointer)
+`jpeg'
+   A JPEG image; only if JPEG support was compiled into this XEmacs.
+   [:data, :file] (color-pixmap, pointer)
+`png'
+   A PNG image; only if PNG support was compiled into this XEmacs.
+   [:data, :file] (color-pixmap, pointer)
+`tiff'
+   A TIFF image; only if TIFF support was compiled into this XEmacs.
+   [:data, :file] (color-pixmap, pointer)
+`bmp'
+   A MS Windows BMP image; only if MS Windows support was compiled into
+   this XEmacs.
+   [:data, :file] (color-pixmap, pointer)
+`xbm'
+   An X bitmap; exists if any window-system support was compiled into this
+   XEmacs.
+   [:data, :file, :foreground, :background, :mask-data, :mask-file,
+   :hotspot-x, :hotspot-y] (mono-pixmap, color-pixmap, 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
+   [:data, :file, :color-symbols] (mono-pixmap, color-pixmap, 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
+   only if X-Face support was compiled into this XEmacs.
+   [:data, :file, :foreground, :background, :mask-data, :mask-file,
+   :hotspot-x, :hotspot-y] (mono-pixmap, color-pixmap, pointer)
+`cursor-font'
+   X and GTK only.  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
+   type of window system.
+   [:data, :foreground, :background] (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
+   the resource.  Possible values for :resource-id are listed below.
+   [:file, :resource-type, :resource-id] (pointer, 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
+   Currently can only be instantiated as `pointer', although this should
    probably be fixed.
-'subwindow
-   An embedded windowing system window.  Can only be instanced as
-   `subwindow'.
-'button
+   [:data, :foreground, :background] (pointer)
+`subwindow'
+   An embedded windowing system window.
+   [:pixel-width, :pixel-height] (subwindow)
+`button'
    A button widget; either a push button, radio button or toggle button.
-   Can only be instanced as `widget'.
-'combo-box
+   [WIDGET-KEYWORDS, GUI-KEYWORDS, :image] (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
+   [GUI-KEYWORDS, :width, :height, :pixel-width, :face, :items] (widget)
+`edit-field'
+   A text editing widget.
+   [WIDGET-KEYWORDS, GUI-KEYWORDS] (widget)
+`label'
+   A static, text-only, widget; for displaying text.
+   [WIDGET-KEYWORDS, :descriptor] (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
+   in many of the places that expect a single glyph.
+   [WIDGET-KEYWORDS, GUI-KEYWORDS, :orientation, :justify, :vertically-justify,
+   :horizontally-justify, :border, :margin-width, :items] (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
+   [WIDGET-KEYWORDS, GUI-KEYWORDS] (widget)
+`progress-gauge'
+   A sliding widget, for showing progress.
+   [WIDGET-KEYWORDS, GUI-KEYWORDS, :value] (widget)
+`tab-control'
+   A tab widget; a series of user selectable tabs.
+   [WIDGET-KEYWORDS, GUI-KEYWORDS, :orientation, :items] (widget)
+`tree-view'
+   A folding widget.
+   [WIDGET-KEYWORDS, GUI-KEYWORDS, :items] (widget)
+`scrollbar'
+   A scrollbar widget.
+   [GUI-KEYWORDS, :pixel-width, :face, :items] (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
@@ -198,11 +178,11 @@
    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'.
+   exists, the image will always be displayed as text.
+   [:data] (mono-pixmap, color-pixmap, pointer, text)
+`inherit'
+   Inherit from the background-pixmap property of a face.
+   [:face] (mono-pixmap)
 
 The valid keywords are:
 
@@ -264,7 +244,7 @@
    \"lfarrowi\", \"size\", \"btsize\", \"check\", \"checkboxes\", and
    \"btncorners\".
 
-   -- For cursors:
+   -- For pointers:
 
    \"normal\", \"ibeam\", \"wait\", \"cross\", \"up\", \"sizenwse\",
    \"sizenesw\", \"sizewe\", \"sizens\", \"sizeall\", and \"no\".
@@ -273,17 +253,27 @@
 
    \"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.
+   Only for `mswindows-resource'.  This must be a symbol, either `cursor'
+   (i.e. pointer), `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.
+:pixel-width, :pixel-height
+   Width and height of element, in pixels.  For `subwindow', the values
+   must be integers.  For widgets, the values can be integers or
+   expressions that evaluate to integers.
 
-Keywords accepted as menu item specs are also accepted by widgets.
+\[WIDGET-KEYWORDS] stands for the standard keywords accepted by widgets:
 These are `:selected', `:active', `:suffix', `:keys', `:style',
 `:filter', `:config', `:included', `:key-sequence', `:accelerator',
-`:label' and `:callback'.
+`:label', `:callback', `:initial-focus', and `:descriptor'.
+#### Document me.
+
+\[GUI-KEYWORDS] stands for keywords accepted by many widgets.
+These are `:width', `:height', `:pixel-width', `:pixel-height', and `:face'.
+#### Document me.
 
 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
@@ -299,7 +289,148 @@
 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).
-"
+
+NOTE: 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.
+
+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 instantiated \(see
+`specifier-instance') 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.
+
+There is an important distinction to be made between image instantiators
+and image instances, and \"image instantiator formats\" and \"image
+instance types\", analogous to the distinction between source and
+destination.  An image instantiator describes the source data for an image.
+An image instance encapsulates the resulting window-system object used to
+display the image.  Image instantiator formats are the formats of the
+source: This includes familiar and less-familiar graphics formats such as
+`gif', `jpeg', `png' and `xpm'; widget types such as `button', `edit-field'
+and `combo-box'; and other beasts such as `string' (plain text, which could
+potentially behave like text when placed in a buffer, such as wrapping),
+`font' (a single character from a particular font, specified by the index
+into the font), etc.  Image instance types are the (destination) types of
+the resulting image instance.  Different image instance types correspond to
+fundamentally different appearance and behaviors for the resulting image,
+specifically:
+
+-- `color-pixmap' (a color image);
+-- `mono-pixmap' (a \"monochrome\" image, technically a two-color image
+   that comes in two unspecified shades \"foreground\" and \"background\",
+   determined from the face [see `make-face'] of the glyph or surrounding
+   text);
+-- `text' (a string of text appearing somewhere in a buffer's text or
+   margins, which has an unspecified foreground, background, and font
+   derived from the surrounding text or other external property and which
+   behaves in many respects like an image but can wrap across the end of a
+   line to the beginning of the next);
+-- `pointer' (the mouse pointer for a window; this is a combination of a
+   rectangular pixmap image, a monochrome mask that specifies the
+   transparency of the image [i.e. in which places the underlying screen
+   image can show through, and how much of it], and a \"hotspot\" that
+   indicates which pixel in the pointer's image is considered the actual
+   pointer location -- for example, this will be located near the tip of
+   an arrow, in the middle of a crosshairs, somewhere along an i-beam, etc.);
+-- `widget' (a window-system object or \"widget\" that interacts with the
+   user, such as a button, edit-field or combo-box);
+-- `subwindow' (a rectangular area that another program can draw into);
+-- `nothing' (no display).
+
+There is not a one-to-one mapping between source (image instantiator)
+formats and destination (image instance) types.  For example, the source
+format `xpm' can generate the image instance types `color-pixmap',
+`mono-pixmap', or `pointer', and the image instance type `color-pixmap' can
+be generated by any of `gif', `jpeg', `png', `tiff', `xpm', `xbm' and
+`xface'.
+
+In general, the user or programmer specifies the image instantiator format,
+while the appropriate image instance type is determined automatically by
+XEmacs from the image instantiator format, from the data in the
+instantiator and from the particular situation the image (and the glyph
+that holds it) is being used in. (However, it's possible to explicitly
+create image instances and control their types; see `make-image-instance'.)
+For example, a glyph used to specify the shape of a mouse pointer can only
+result in `pointer'-type image instances, and a glyph used for an icon can
+only result in `color-pixmap' image instances.  A glyph used in a buffer
+can potentially result in any image instance type except for `pointer', but
+particular instantiator formats have only a limited set of image instance
+types they will support.  Here is an example of how the image instance type
+for an `xpm' instantiator (which can potentially support `color-pixmap',
+`mono-pixmap', or `pointer') is determined:
+
+1. If the glyph is being used for a mouse pointer (hence its `glyph-type'
+   is `pointer'), it can be instantiated only a `pointer'-type image instance.
+2. If the glyph is being used for an icon (hence its `glyph-type' is `icon'),
+   it can be instantiated only a `color-pixmap'-type image instance.
+3. Otherwise, the glyph is being used somewhere inside a frame (`glyph-type'
+   of `buffer') and any image instance type except `pointer' can be
+   supported.  In this case, this means `color-pixmap' or `mono-pixmap'.
+   Which one will result depends on the particular data being processed,
+   since XPM images can specify whether they are color or mono.
+
+Note again that \"mono\" does *NOT* simply mean \"an image with two
+colors\".  The latter image has two prespecified colors, e.g. red and blue
+or black and white, and will always appear with those colors, no matter
+what the context.  A mono image has two *unspecified* colors, symbolically
+named \"foreground\" and \"background\", and the actual values for those
+colors depends on context.  A mono pixmap displayed among text will take
+its foreground and background from that of the text and hence blend in
+nicely; a two-color color pixmap won't do that.
+
+Note also that `color-pixmap' image instances can be generated from the
+supported pixmap formats that are inherently mono (i.e. `xbm' and `xface')
+by specifying :foreground and :background values.
+
+A table of the various image instantiator formats and the possible
+destination (image instance) types that can be generated from them is as
+follows:
+
+
+                   color-pixmap mono-pixmap text pointer widget subwindow noth.
+-------------------------------------------------------------------------------
+nothing                                                                     +
+string                                        +
+formatted-string                              +
+xbm                     +            +              +
+xpm                     +            +              +
+xface                   +            +              +
+gif                     +                           +
+jpeg                    +                           +
+png                     +                           +
+tiff                    +                           +
+bmp                     +                           +
+cursor-font                                         +
+mswindows-resource      +                           +
+font                                                +
+subwindow                                                           +
+button                                                     +
+combo-box                                                  +
+edit-field                                                 +
+label                                                      +
+layout                                                     +
+native-layout                                              +
+progress-gauge                                             +
+tab-control                                                +
+tree-view                                                  +
+scrollbar                                                  +
+autodetect              +            +        +     +
+inherit                              +
+
+See `make-image-instance' for a more detailed discussion of image
+instance types."
   (make-specifier-and-init 'image spec-list))
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; glyphs
@@ -328,11 +459,11 @@
   specifying a font or color name), or a list of specifications, each
   of which is a cons of a locale and a list of instantiators.
   Specifically, if LOCALE is a particular locale (a buffer, window,
-  frame, device, or 'global), a list of instantiators for that locale
+  frame, device, or `global'), a list of instantiators for that locale
   will be returned.  Otherwise, if LOCALE is a locale type (one of
-  the symbols 'buffer, 'window, 'frame, 'device, 'device-class, or
-  'device-type), the specifications for all locales of that type will
-  be returned.  Finally, if LOCALE is 'all, the specifications for all
+  the symbols `buffer', `window', `frame', `device', `device-class', or
+  `device-type'), the specifications for all locales of that type will
+  be returned.  Finally, if LOCALE is `all', the specifications for all
   locales of all types will be returned.
 
 The specifications in a specifier determine what the value of
@@ -340,7 +471,7 @@
   which is typically a particular Emacs window along with the buffer
   it contains and the frame and device it lies within.  The value
   is derived from the instantiator associated with the most specific
-  locale (in the order buffer, window, frame, device, and 'global)
+  locale (in the order buffer, window, frame, device, and `global')
   that matches the domain in question.  In other words, given a domain
   (i.e. an Emacs window, usually), the specifier for PROPERTY will first
   be searched for a specification whose locale is the buffer contained
@@ -368,7 +499,7 @@
     ;; if a user-property does not have a specifier but a
     ;; locale was specified, put a specifier there.
     ;; If there was already a value there, convert it to a
-    ;; specifier with the value as its 'global instantiator.
+    ;; specifier with the value as its `global' instantiator.
     (if (not (specifierp specifier))
 	(let ((new-specifier (make-specifier 'generic)))
 	  (if (or (not (null specifier))
@@ -436,7 +567,7 @@
   -- If VALUE is a simple instantiator (e.g. a string naming a font or
      color) or a list of instantiators, then the instantiator(s) will
      be added as a specification of the property for the given LOCALE
-     (which defaults to 'global if omitted).
+     (which defaults to `global' if omitted).
   -- If VALUE is a list of specifications (each of which is a cons of
      a locale and a list of instantiators), then LOCALE must be nil
      (it does not make sense to explicitly specify a locale in this
@@ -448,12 +579,12 @@
      `copy-specifier' and LOCALE has the same semantics (if it is
      a particular locale, the specification for the locale will be
      copied; if a locale type, specifications for all locales of
-     that type will be copied; if nil or 'all, then all
+     that type will be copied; if nil or `all', then all
      specifications will be copied).
 
-HOW-TO-ADD should be either nil or one of the symbols 'prepend,
-  'append, 'remove-tag-set-prepend, 'remove-tag-set-append, 'remove-locale,
-  'remove-locale-type, or 'remove-all.  See `copy-specifier' and
+HOW-TO-ADD should be either nil or one of the symbols `prepend',
+  `append', `remove-tag-set-prepend', `remove-tag-set-append', `remove-locale',
+  `remove-locale-type', or `remove-all.'  See `copy-specifier' and
   `add-spec-to-specifier' for a description of what each of
   these means.  Most of the time, you do not need to worry about
   this argument; the default behavior usually is fine.
@@ -462,7 +593,7 @@
   by `glyph-property-instance') as an instantiator in place of
   an actual instantiator.  In such a case, the instantiator used
   to create that instance object will be used (for example, if
-  you set a font-instance object as the value of the 'font
+  you set a font-instance object as the value of the `font'
   property, then the font name used to create that object will
   be used instead).  If some cases, however, doing this
   conversion does not make sense, and this will be noted in
@@ -473,7 +604,7 @@
   given, then this function will attempt to add VALUE as the
   instantiator for the given LOCALE, using `add-spec-to-specifier'.
   If the value of the property is not a specifier, it will
-  automatically be converted into a 'generic specifier.
+  automatically be converted into a `generic' specifier.
 
 
 The following symbols have predefined meanings:
@@ -527,7 +658,7 @@
 
 LOCALE may be a locale (the instantiators for that particular locale
   will be returned), a locale type (the specifications for all locales
-  of that type will be returned), 'all (all specifications will be
+  of that type will be returned), `all' (all specifications will be
   returned), or nil (the actual specifier object will be returned).
 
 See `glyph-property' for more information."
@@ -561,10 +692,10 @@
   object.
 
 If SPEC is an alist, LOCALE must be omitted.  If SPEC is a
-  specifier object, LOCALE can be a locale, a locale type, 'all,
+  specifier object, LOCALE can be a locale, a locale type, `all',
   or nil; see `copy-specifier' for its semantics.  Otherwise LOCALE
   specifies the locale under which the specified instantiator(s)
-  will be added, and defaults to 'global.
+  will be added, and defaults to `global.'
 
 See `set-glyph-property' for more information."
   ; (interactive (glyph-interactive "image"))
@@ -575,17 +706,17 @@
 
 LOCALE may be a locale (the instantiators for that particular locale
   will be returned), a locale type (the specifications for all locales
-  of that type will be returned), 'all (all specifications will be
+  of that type will be returned), `all' (all specifications will be
   returned), or nil (the actual specifier object will be returned).
 
 See `glyph-property' for more information."
   (glyph-property glyph 'contrib-p locale))
 
 (defun glyph-contrib-p-instance (glyph &optional domain default no-fallback)
-  "Return the instance of GLYPH's 'contrib-p property in DOMAIN.
+  "Return the instance of GLYPH's `contrib-p' property in DOMAIN.
 
 Normally DOMAIN will be a window or nil (meaning the selected window),
-  and an instance object describing what the 'contrib-p property is in
+  and an instance object describing what the `contrib-p' property is in
   that particular window and buffer will be returned.
 
 See `glyph-property-instance' for more information."
@@ -599,10 +730,10 @@
   locale to an instantiator list), or a boolean specifier object.
 
 If SPEC is an alist, LOCALE must be omitted.  If SPEC is a
-  specifier object, LOCALE can be a locale, a locale type, 'all,
+  specifier object, LOCALE can be a locale, a locale type, `all',
   or nil; see `copy-specifier' for its semantics.  Otherwise LOCALE
   specifies the locale under which the specified instantiator(s)
-  will be added, and defaults to 'global.
+  will be added, and defaults to `global.'
 
 See `set-glyph-property' for more information."
   ; (interactive (glyph-interactive "contrib-p"))
@@ -613,7 +744,7 @@
 
 LOCALE may be a locale (the instantiators for that particular locale
   will be returned), a locale type (the specifications for all locales
-  of that type will be returned), 'all (all specifications will be
+  of that type will be returned), `all' (all specifications will be
   returned), or nil (the actual specifier object will be returned).
 
 See `glyph-property' for more information."
@@ -638,10 +769,10 @@
   locale to an instantiator list), or a generic specifier object.
 
 If SPEC is an alist, LOCALE must be omitted.  If SPEC is a
-  specifier object, LOCALE can be a locale, a locale type, 'all,
+  specifier object, LOCALE can be a locale, a locale type, `all',
   or nil; see `copy-specifier' for its semantics.  Otherwise LOCALE
   specifies the locale under which the specified instantiator(s)
-  will be added, and defaults to 'global.
+  will be added, and defaults to `global.'
 
 See `set-glyph-property' for more information."
   ; (interactive (glyph-interactive "baseline"))
@@ -668,13 +799,46 @@
 normally think of as an image (which in XEmacs is called a
 \"pixmap\"), but to any graphical element -- a pixmap, a widget, or
 even a block of text, when used in the places that call for a glyph.)
-The format of the SPEC-LIST is typically an image instantiator (a
-string or a vector; see `make-image-specifier' for a detailed description
-of the valid image instantiators), but can also be a list of such
-instantiators (each one in turn is tried until an image is
-successfully produced), a cons of a locale (frame, buffer, etc.)  and
-an instantiator, a list of such conses, or any other form accepted by
-`canonicalize-spec-list'.
+
+SPEC-LIST is typically an image instantiator, describing the source for the
+image data.  This is either a vector of the form [FORMAT :KEYWORD DATA ...],
+for example
+
+  [jpeg :file \"/user/john/images/myimage.jpg\"]
+
+or
+
+  [xbm :data \"/* XPM */\nstatic char * copy[] = {\n...\"]
+
+or it is a string, either giving a file name or directly specifying inline
+data.  See `make-image-specifier' for a detailed description of valid image
+instantiators.  If the instantiator is a string, XEmacs will convert it
+into vector form by trying to guess whether a file name or inline data is
+intended, and what kind of data is inline or in the file.  Usually it does
+a pretty good job.  See `console-type-image-conversion-list' for details of
+how this works.
+
+If the instantiator specifies data from a file, the data will be read in
+when `make-glyph' is called and substituted inline into the instantiator,
+using the :data keyword.  This means that the file must exist when the
+glyph is created, but does not need to exist afterwards (e.g. it may safely
+be a temporary file).
+
+When errors occur in the process of reading image data from a file
+\(e.g. the file does not exist or the data is of the wrong format or
+corrupted), no Lisp error will currently be signalled.  Instead, the
+instantiator is skipped and warnings will be issued at level `debug'. \(A
+glyph with no instantiators in it cannot be displayed.) Normally, such
+warnings are ignored entirely, but you can change this by setting
+`log-warning-minimum-level'.  This is useful if you're trying to debug why
+particular instantiators are not being processed. (#### We should probably
+provide a way of getting errors in such circumstances, or even make this
+the default behavior.)
+
+Technically, SPEC-LIST can also be a list of image instantiators (each one
+in turn is tried until an image is successfully produced), a cons of a
+locale (frame, buffer, etc.) and an instantiator, a list of such conses,
+or any other form accepted by `canonicalize-spec-list'.
 
 If you're not familiar with specifiers, you should be in order to
 understand how glyphs work.  The clearest introduction to specifiers
@@ -734,7 +898,7 @@
    value of the variable `toolbar-mail-icon' (in general, `toolbar-*-icon')
    and then calling `(set-specifier-dirty-flag default-toolbar)'.
    (#### Unfortunately this doesn't quite work the way it should; the
-   change will appear in new frames, but not existing ones.
+   change will appear in new frames, but not existing ones.)
 
 -- To insert a glyph into a gutter, create or modify a gutter instantiator
    (typically set on the specifier `default-gutter').  Gutter instantiators
@@ -781,9 +945,6 @@
    which controls the appearance of characters.  You can also set an
    overriding display table for use with text displayed in a particular
    face; see `set-face-display-table' and `make-display-table'.
-   #### Note: Display tables do not currently support general Mule
-   characters.  They will be overhauled at some point to support this
-   and to provide other features required under Mule.
 
 -- To use a glyph as the background pixmap of a face: Note that the
    background pixmap of a face is actually an image specifier -- probably
@@ -972,7 +1133,7 @@
       (set-glyph-image (symbol-value harg) value))))
 
 ;; It might or might not be garbage, but it's rude.  Make these
-;; 'compatible instead of 'obsolete.  -slb
+;; `compatible' instead of `obsolete.'  -slb
 (defun define-obsolete-pointer-glyph (old new)
   (define-compatible-variable-alias old new)
   (dontusethis-set-symbol-value-handler