--- a/man/lispref/glyphs.texi	Sun Jun 13 21:50:59 2004 +0000
+++ b/man/lispref/glyphs.texi	Mon Jun 14 10:24:45 2004 +0000
@@ -70,22 +70,23 @@
 contexts the glyph can be used, and controls the allowable image types
 into which the glyph's image can be instantiated.  @var{type} should be
 one of @code{buffer} (used for glyphs in an extent, the modeline, the
-toolbar, or elsewhere in a buffer), @code{pointer} (used for the
+toolbar, or elsewhere in a frame), @code{pointer} (used for the
 mouse-pointer), or @code{icon} (used for a frame's icon), and defaults
 to @code{buffer}.  @xref{Glyph Types}.
 
 A glyph in XEmacs does @strong{NOT} refer to a single unit of textual
-display (the XEmacs term for this is @dfn{rune}), but rather is an
+display (the XEmacs term for this is @dfn{rune}, and runes are confined
+to the internal implementation of redisplay), but rather is an
 object encapsulating a graphical element, such as an image or widget (an
-element such as a button or text field; @dfn{widget} is the term for
-this under X Windows, and it's called a @dfn{control} under MS Windows).
+element such as a button or text entry field; @dfn{widget} is the term for
+this under X Windows, while @dfn{control} is the term under MS Windows).
 This graphical element could appear in a buffer, a margin, a gutter, or
 a toolbar, or as a mouse pointer or an icon, for example.
 
 Creating a glyph using @code{make-glyph} does not specify @emph{where}
 the glyph will be used, but it does specify @emph{what} the glyph will
-look like.  In particular, @var{spec-list} is used to specify this, and it's
-used to initialize the glyph's @code{image} property, which is an image
+look like.  @var{spec-list} is used to specify this, and it is the
+initializer for the glyph's @code{image} property, which is an image
 specifier. (Note that @dfn{image} as used in the context of a glyph's
 @code{image} property or in the terms @dfn{image specifier}, @dfn{image
 instantiator}, or @dfn{image instance} does not refer to what people
@@ -97,25 +98,31 @@
 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
-@code{canonicalize-spec-list}. @xref{Specifiers}, for more information
-about specifiers.
+@code{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
-is in the Lispref manual, available under Info. (Choose
-Help->Info->Info Contents on the menubar or type C-h i.) You can
-also see @code{make-specifier} for a capsule summary.  What's important to
-keep in mind is that a specifier lets you set a different value for
-any particular buffer, window, frame, device, or console.  This allows
-for a great deal of flexibility; in particular, only one global glyph
+Some understanding of specifiers is necessary in working with glyphs,
+because they do not behave like ordinary variables, and are accessed and
+mutated with special APIs.  @xref{Specifiers}, for more information
+about specifiers.  The docstring of
+@code{make-specifier} gives a capsule summary.  The most important
+aspect of specifiers is that a specifier lets you set a value for
+each buffer, window, frame, device, or console, or it will compute an
+appropriate default if no specific value is set for a particular
+@emph{locale} or @emph{domain} (display contexts; locales are used by
+the programmer create an abstract link between an object such as a
+buffer position and an image, while domains must be concrete enough to
+enable XEmacs to identify the device type: you can't
+usefully display a JPEG on stdout).  Therefore only one global glyph
 needs to exist for a particular purpose (e.g. the icon used to represent
 an iconified frame, the mouse pointer used over particular areas of a
 frame, etc.), and in these cases you do not create your own glyph, but
-rather modify the existing one.
+rather modify the existing one.  You can specify that a given glyph
+appear as a monochrome image on monochrome displays, a color image on
+color displays, and as a string on TTYs.
 
 As well as using @var{spec-list} to initialize the glyph, you can set
-specifications using @code{set-glyph-image}.  Note that, due to a
-possibly questionable historical design decision, a glyph itself is not
+specifications using @code{set-glyph-image}.  Due to an
+arguable historical design decision, a glyph itself is not
 actually a specifier, but rather is an object containing an image
 specifier (as well as other, seldom-used properties).  Therefore, you
 cannot set or access specifications for the glyph's image by directly
@@ -124,8 +131,13 @@
 convenience functions @code{set-glyph-image},
 @code{glyph-image-instance}, and @code{glyph-image}.
 
-Once you have created a glyph, you specify where it will be used as
-follows:
+Once you have created a glyph, you specify where it will be used by
+attaching it to an extent as a @emph{begin-glyph} or @emph{end-glyph}.
+There are also a number of special objects whose appearance is specified
+by a glyph.  Most of these a global objects that you update with
+@code{set-glyph-image}, such as mouse pointers and the glyph that
+denotes a line truncation.  Frame icons, toolbar button icons, and the
+modeline are the main non-text objects which accept glyphs as elements.
 
 @itemize @bullet
 @item
@@ -143,51 +155,51 @@
 set a non-default layout policy for the glyph using
 @code{set-extent-begin-glyph-layout} or @code{set-extent-end-glyph-layout}.
 Alternatively, use the high-level annotations API (see
-@code{make-annotation}). (In point of fact, you can also use the annotations
+@code{make-annotation}). (In fact, you can also use the annotations
 API for glyphs in a buffer, by setting a layout policy of @code{text}.)
 
 @item
-To insert a glyph into the modeline, just put the glyph directly as one
-of the modeline elements. (Unfortunately you can't currently put a begin
-glyph or end glyph on one of the modeline extents---they're ignored.)
+A glyph may be displayed in the modeline by inserting the glyph as one
+of the elements of the modeline format.  (Unfortunately you can't
+currently put a begin glyph or end glyph on one of the modeline
+extents---they're ignored.)
 
 @item
-To insert a glyph into a toolbar, specify it as part of a toolbar
-instantiator (typically set on the specifier @code{default-toolbar}).
-See @code{default-toolbar} for more information. (Note that it is
-standard practice to use a symbol in place of the glyph list in the
-toolbar instantiator; the symbol is evalled to get the glyph list.  This
+To insert a glyph into a toolbar, specify it as the icon part of a toolbar
+button, which in turn must be part of a toolbar instantiator (typically
+set on the specifier @code{default-toolbar}).
+See @code{default-toolbar} for more information. (As a convenience, you
+may use a symbol in place of the glyph list in the toolbar button
+instantiator; the symbol is evalled to get the glyph list.  This
 facilitates both creating the toolbar instantiator and modifying
 individual glyphs in a toolbar later on.  For example, you can change
 the way that the Mail toolbar button looks by modifying the value of the
 variable @code{toolbar-mail-icon} (in general, @code{toolbar-*-icon})
 and then calling @code{(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, because once an
+image has been displayed the pixmap replaces the symbol for those domains.)
 
 @item
-To insert a glyph into a gutter, create or modify a gutter instantiator
-(typically set on the specifier @code{default-gutter}).  Gutter
-instantiators consist of strings or lists of strings, so to insert a
-glyph, create an extent over the string, and use
+To insert a glyph into a gutter, use
 @code{set-extent-begin-glyph} or @code{set-extent-end-glyph} to set a
-glyph to be displayed at the corresponding edge of the extent, just like
-for glyphs in a buffer.
+glyph to be displayed at the corresponding edge of extent in a string,
+similar to the way you insert glyphs in a buffer.  Then insert the
+string into the gutter @ref{Specifying a Gutter}.
 
-@item
-To use a glyph as the icon for a frame, you do not actually create a new
-glyph; rather, you change the specifications for the existing glyph
-@code{frame-icon-glyph}. (Remember that, because of the specifier nature
-of glyphs, you can set different values for any particular buffer or
-frame.)
+@item To use a glyph as the icon for a frame, you do not actually create
+a new glyph; rather, you change the specifications for the existing
+glyph @code{frame-icon-glyph}.  (This is a unique, predefined object.
+Remember that, because of the specifier nature of glyphs, you can set
+different values for any particular buffer or frame.)
 
 @item
 To use a glyph as the mouse pointer, in general you do not create a new
 glyph, but rather you change the specifications of various existing
 glyphs, such as @code{text-pointer-glyph} for the pointer used over
 text, @code{modeline-pointer-glyph} for the pointer used over the
-modeline, etc.  Do an apropos over @code{*-pointer-glyph} to find all of
-them. (Note also that you can temporarily set the mouse pointer to some
+modeline, etc.  Do an apropos over @samp{pointer-glyph} to find all of
+them.  (Note also that you can temporarily set the mouse pointer to some
 specific shape by using @code{set-frame-pointer}, which takes an image
 instance, as obtained from calling @code{glyph-image-instance} on a glyph
 of type @code{pointer} -- either one of the above-mentioned variables or
@@ -224,17 +236,13 @@
 and to provide other features required under Mule.
 
 @item
-To use a glyph as the background pixmap of a face: Note that the
+Glyphs are not actually used as the background pixmaps of faces, but the
+API is similar.  The
 background pixmap of a face is actually an image specifier -- probably
 the only place in XEmacs where an image specifier occurs outside of a
-glyph. Similarly to how the glyph's image specifier works, you don't
-create your own image specifier, but rather add specifications to the
-existing one (using @code{set-face-background-pixmap-file} or
-@code{set-face-background-pixmap}). Note that the image instance that is
-generated in order to actually display the background pixmap is of type
-@code{mono-pixmap}, meaning that it's a two-color image and the
-foreground and background of the image get filled in with the
-corresponding colors from the face.
+glyph.  If you would like to use a glyph's image as a background pixmap,
+you can extract it with @code{glyph-image}, and then add it to a face.
+@xref{Face Convenience Functions}.
 @end itemize
 
 It is extremely rare that you will ever have to specify a value for
@@ -245,7 +253,7 @@
 needs to be specified is when creating icon or pointer glyphs, and in
 both cases the necessary glyphs have already been created at startup and
 are accessed through the appropriate variables,
-e.g. @code{text-pointer-glyph} (or in general, @code{*-pointer-glyph})
+e.g. @code{text-pointer-glyph} (or in general, any @samp{*-pointer-glyph})
 and @code{frame-icon-glyph}.  @xref{Glyph Types}.
 @end defun
 
@@ -272,7 +280,7 @@
 
 It is extremely unlikely that you will ever need to create a pointer
 glyph.  Instead, you probably want to be calling @code{set-glyph-image}
-on an existing glyph, e.g. @code{text-pointer-glyph}.
+on the existing glyph, @code{frame-icon-glyph}.
 @end defun
 
 @node Glyph Properties