diff man/lispref/glyphs.texi @ 2953:c7d4a681eb2c

[xemacs-hg @ 2005-09-26 08:41:45 by ben] add specifier-instantiator and friends specifier.c: Add `specifier-instantiator' and related primitives. lispref/glyphs.texi, lispref/lispref.texi, lispref/specifiers.texi: Use "instantiation" not "instancing". Fix some places where "specifier" is used to mean "instantiator".
author ben
date Mon, 26 Sep 2005 08:41:57 +0000
parents 13a418960a88
children 1cecc3e9f0a0
line wrap: on
line diff
--- a/man/lispref/glyphs.texi	Mon Sep 26 08:29:31 2005 +0000
+++ b/man/lispref/glyphs.texi	Mon Sep 26 08:41:57 2005 +0000
@@ -88,25 +88,25 @@
 @section Images
 
 @menu
-* Image Specifiers::			Specifying an image's appearance.
+* Image Instantiators::			Specifying an image's appearance.
 * Image Instantiator Conversion::	Lazy realization of graphics.
 * Image Instantiator Formats::		A catalog of image descriptors.
 * Image Instances::			Classes of graphical objects.
 @end menu
 
 
-@node Image Specifiers
-@subsection Image Specifiers
-@cindex image specifiers
+@node Image Instantiators
+@subsection Image Instantiators
+@cindex image instantiators
 
-  An image specifier is a description of the actual graphical
+  An @dfn{image instantiator} is a description of the actual graphical
 realization of a glyph.  For example, a typical image description is
 @emph{the file system path to a PNG file}.  Since redisplay doesn't know
 about files, and in any case the image may need to be manipulated
 (@emph{e.g.}, a face's background pixmap must be clipped and tiled), the
 PNG file must be converted internally to a window system bitmap or
 pixmap object.  We describe this process by writing that when XEmacs
-displays the image, it @dfn{instantiates} the @dfn{image instantiator}
+displays the image, it @dfn{instantiates} the image instantiator
 into an @dfn{image instance}.  Image instances are an internal object
 type (similar to font instances and color instances), describing how the
 image appears in a particular domain.  On the other hand, image
@@ -114,8 +114,8 @@
 appear, are represented using Lisp strings or vectors.
 
 Furthermore the graphical realization will vary, and for some devices
-may not even be a bitmapped graphic.  These variations may be controlled
-by the program by specifying different @dfn{image instantiators} in
+may not even be a bitmapped graphic.  These variations may be
+controlled by the program by specifying different instantiators in
 different locales.  This is implemented with an @dfn{image specifier},
 a specifier whose specifications are image instantiators.
 
@@ -156,9 +156,9 @@
 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, @code{xpm} can be instanced as @code{color-pixmap},
+For example, @code{xpm} can be instantiated as @code{color-pixmap},
 @code{mono-pixmap}, or @code{pointer}; whereas @code{cursor-font} can be
-instanced only as @code{pointer}.  On the other hand, a particular image
+instantiated only as @code{pointer}.  On the other hand, a particular image
 instance type can be generated by many different image instantiator
 formats (e.g.  @code{color-pixmap} can be generated by @code{xpm},
 @code{gif}, @code{jpeg}, etc.).
@@ -372,11 +372,11 @@
 @table @code
 @item nothing
 Don't display anything; no keywords are valid for this format.  Can only be
-instanced as @code{nothing}.
+instantiated as @code{nothing}.
 
 @item string
-Display this image as a text string.  Can only be instanced
-as @code{text}, although support for instancing as @code{mono-pixmap}
+Display this image as a text string.  Can only be instantiated
+as @code{text}, although support for instantiation as @code{mono-pixmap}
 should be added.  The valid keyword is @code{:data}.  The value should
 be a string, and it is interpreted as a string of characters.
 
@@ -432,7 +432,7 @@
 @item xpm
 An XPM pixmap; only available if XPM support was compiled into this XEmacs.
 
-Can be instanced as @code{color-pixmap}, @code{mono-pixmap}, or
+Can be instantiated as @code{color-pixmap}, @code{mono-pixmap}, or
 @code{pointer}.
 
 XPM is an add-on library for X that was designed to rectify the
@@ -476,7 +476,7 @@
 An X-Face bitmap, used to encode people's faces in e-mail messages;
 only available if X-Face support was compiled into this XEmacs.
 
-Will be instanced as @code{mono-pixmap}, @code{color-pixmap}, or
+Will be instantiated as @code{mono-pixmap}, @code{color-pixmap}, or
 @code{pointer}, depending on the target instance type and the presence
 of color keywords.
 
@@ -526,7 +526,7 @@
 Note that PNG is the standard format for images distributed with XEmacs,
 so it is highly recommended that PNG support be built in.
 
-All of these instantiators will be instanced as @code{color-pixmap}.
+All of these instantiators will be instantiated as @code{color-pixmap}.
 
 The valid keywords and their values are
 @table @code
@@ -539,7 +539,7 @@
 
 @item cursor-font
 Most window systems provide a set of standard cursors, which in X11 is
-called a cursor font.  Can only be instanced as @code{pointer}.  This
+called a cursor font.  Can only be instantiated as @code{pointer}.  This
 should probably be fixed.
 
 The valid keyword is @code{:data}.  Its value should be a string
@@ -555,14 +555,14 @@
 A glyph from a font; i.e. the name of a font, and glyph index into it
 of the form @samp{@var{font} fontname index [[mask-font] mask-index]}.
 Only if X support was compiled into this XEmacs.  Currently can only be
-instanced as @code{pointer}.  This should probably be fixed.
+instantiated as @code{pointer}.  This should probably be fixed.
 @c #### The above description is not very helpful, so it's not obvious
 @c how to instantiate a font image.
 
 @item 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.  Can be instanced as @code{pointer} or
+an executable file.  Can be instantiated as @code{pointer} or
 @code{color-pixmap}.
 
 The valid keywords and their values are
@@ -601,23 +601,23 @@
 @end table
 
 @item subwindow
-An embedded windowing system window.  Can only be instanced as
+An embedded windowing system window.  Can only be instantiated as
 @code{subwindow}.  Not implemented.
 @c #### Check status of subwindows ... I thought Andy implemented them.
 
 @item button
 A button widget; either a push button, radio button or toggle button.
-Can only be instanced as @code{widget}.
+Can only be instantiated as @code{widget}.
 
 @item combo-box
 A drop list of selectable items in a widget, for editing text.
-Can only be instanced as @code{widget}.
+Can only be instantiated as @code{widget}.
 
 @item edit-field
-A text editing widget.  Can only be instanced as @code{widget}.
+A text editing widget.  Can only be instantiated as @code{widget}.
 
 @item label
-A static, text-only, widget; for displaying text.  Can only be instanced
+A static, text-only, widget; for displaying text.  Can only be instantiated
 as @code{widget}.
 
 @item layout
@@ -625,19 +625,19 @@
 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 @dfn{glyph} and could appear
-in many of the places that expect a single glyph.  Can only be instanced
+in many of the places that expect a single glyph.  Can only be instantiated
 as @code{widget}.
 
 @item native-layout
 The native version of a layout widget.
-Can only be instanced as @code{widget}.
+Can only be instantiated as @code{widget}.
 
 @item progress-gauge
-A sliding widget, for showing progress.  Can only be instanced as
+A sliding widget, for showing progress.  Can only be instantiated as
 @code{widget}.
 
 @item tab-control
-A tab widget; a series of user selectable tabs.  Can only be instanced
+A tab widget; a series of user selectable tabs.  Can only be instantiated
 as @code{widget}.
 
 The required keyword is @code{:items}.  Its value should be a list of
@@ -654,10 +654,10 @@
 (The above is incomplete and may be inaccurate.)
 
 @item tree-view
-A folding widget.  Can only be instanced as @code{widget}.
+A folding widget.  Can only be instantiated as @code{widget}.
 
 @item scrollbar
-A scrollbar widget.  Can only be instanced as @code{widget}.
+A scrollbar widget.  Can only be instantiated as @code{widget}.
 
 @item autodetect
 XEmacs tries to guess what format the data is in.  If X support exists,
@@ -672,7 +672,7 @@
 
 @item inherit
 Inherit from the background-pixmap property of a face.  Can only be
-instanced as @code{mono-pixmap}.
+instantiated as @code{mono-pixmap}.
 @end table
 
 There are two convenience variables for use with the XBM and XPM image
@@ -719,7 +719,7 @@
 @end defun
 
 @menu
-* Image Instance Types::         Each image instances has a particular type.
+* Image Instance Types::         Each image instance has a particular type.
 * Image Instance Functions::	 Functions for working with image instances.
 @end menu
 
@@ -834,7 +834,7 @@
 This function creates a new image-instance object.
 
 @var{data} is an image instantiator, which describes the image
-(@pxref{Image Specifiers}).
+(@pxref{Image Instantiators}).
 
 @var{dest-types} should be a list of allowed image instance types that
 can be generated.  The @var{dest-types} list is unordered.  If multiple
@@ -991,7 +991,7 @@
 @end defun
 
 Mono pixmaps and pointers may have their foreground and background
-colors set when instanced.  Use these functions to access color
+colors set when instantiated.  Use these functions to access color
 information.
 
 @defun image-instance-foreground image-instance
@@ -1104,7 +1104,7 @@
 of the data, such as a string, a PNG file, or an MS Windows resource.
 This is followed by properties (keyword-value pairs) specifying such
 information as the name of a file containing an image, or pixmap data
-directly.  @xref{Image Specifiers}.
+directly.  @xref{Image Instantiators}.
 
 The optional @var{type} specifies the type of the glyph.  @var{type}
 should be one of @code{buffer} (used for glyphs in an extent, the
@@ -1488,7 +1488,7 @@
 Native widgets are manipulated as @emph{glyphs} (@pxref{Glyphs}).  Thus
 they are created using @code{make-glyph}, with a format of one of the
 widget types and a @code{:data} property specific to the widget being
-instanced.
+instantiated.
 
 However, there is a technical difference between widgets and other kinds
 of glyphs that is theoretically important.  Because widgets
@@ -1838,7 +1838,7 @@
 
 If @var{property} does not name a built-in property, its value will
 simply be returned unless it is a specifier object, in which case it
-will be instanced using @code{specifier-instance}.
+will be instantiated using @code{specifier-instance}.
 
 Optional arguments @var{default} and @var{no-fallback} are the same as
 in @code{specifier-instance}.  @xref{Specifiers}.
@@ -2065,7 +2065,7 @@
 Specifiers", and can handle more image types than those shown above.
 You can also put the raw image data into a string (e.g., if you put the
 contents of a JPEG file into a string), and use that to create a glyph.
-@xref{Image Specifiers}, for more information.
+@xref{Image Instantiators}, for more information.
 
 @quotation
 @strong{Caution}: In order for XEmacs to read a particular graphics file
@@ -2079,7 +2079,7 @@
 supported, you can use the @code{featurep} function, with one of:
 @code{gif}, @code{tiff}, @code{jpeg}, @code{xpm}, @code{xbm},
 @code{png}, or @code{xface}.  For an up-to-date list, @ref{Image
-Specifiers}.  Example:
+Instantiators}.  Example:
 
 @example
 ;; Returns `t' if TIFF is supported: