info/lispref.info-34

   1 This is ../info/lispref.info, produced by makeinfo version 4.0 from
   2 lispref/lispref.texi.
   3
   4 INFO-DIR-SECTION XEmacs Editor
   5 START-INFO-DIR-ENTRY
   6 * Lispref: (lispref).           XEmacs Lisp Reference Manual.
   7 END-INFO-DIR-ENTRY
   8
   9    Edition History:
  10
  11    GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
  12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
  13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
  14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
  15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
  16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
  17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
  18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
  19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
  20
  21    Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
  22 Foundation, Inc.  Copyright (C) 1994, 1995 Sun Microsystems, Inc.
  23 Copyright (C) 1995, 1996 Ben Wing.
  24
  25    Permission is granted to make and distribute verbatim copies of this
  26 manual provided the copyright notice and this permission notice are
  27 preserved on all copies.
  28
  29    Permission is granted to copy and distribute modified versions of
  30 this manual under the conditions for verbatim copying, provided that the
  31 entire resulting derived work is distributed under the terms of a
  32 permission notice identical to this one.
  33
  34    Permission is granted to copy and distribute translations of this
  35 manual into another language, under the above conditions for modified
  36 versions, except that this permission notice may be stated in a
  37 translation approved by the Foundation.
  38
  39    Permission is granted to copy and distribute modified versions of
  40 this manual under the conditions for verbatim copying, provided also
  41 that the section entitled "GNU General Public License" is included
  42 exactly as in the original, and provided that the entire resulting
  43 derived work is distributed under the terms of a permission notice
  44 identical to this one.
  45
  46    Permission is granted to copy and distribute translations of this
  47 manual into another language, under the above conditions for modified
  48 versions, except that the section entitled "GNU General Public License"
  49 may be included in a translation approved by the Free Software
  50 Foundation instead of in the original English.
  51
  52 \1f
  53 File: lispref.info,  Node: Abbrev Expansion,  Next: Standard Abbrev Tables,  Prev: Abbrev Files,  Up: Abbrevs
  54
  55 Looking Up and Expanding Abbreviations
  56 ======================================
  57
  58    Abbrevs are usually expanded by commands for interactive use,
  59 including `self-insert-command'.  This section describes the
  60 subroutines used in writing such functions, as well as the variables
  61 they use for communication.
  62
  63  - Function: abbrev-symbol abbrev &optional table
  64      This function returns the symbol representing the abbrev named
  65      ABBREV.  The value returned is `nil' if that abbrev is not
  66      defined.  The optional second argument TABLE is the abbrev table
  67      to look it up in.  If TABLE is `nil', this function tries first
  68      the current buffer's local abbrev table, and second the global
  69      abbrev table.
  70
  71  - Function: abbrev-expansion abbrev &optional table
  72      This function returns the string that ABBREV would expand into (as
  73      defined by the abbrev tables used for the current buffer).  The
  74      optional argument TABLE specifies the abbrev table to use, as in
  75      `abbrev-symbol'.
  76
  77  - Command: expand-abbrev
  78      This command expands the abbrev before point, if any.  If point
  79      does not follow an abbrev, this command does nothing.  The command
  80      returns `t' if it did expansion, `nil' otherwise.
  81
  82  - Command: abbrev-prefix-mark &optional arg
  83      Mark current point as the beginning of an abbrev.  The next call to
  84      `expand-abbrev' will use the text from here to point (where it is
  85      then) as the abbrev to expand, rather than using the previous word
  86      as usual.
  87
  88  - User Option: abbrev-all-caps
  89      When this is set non-`nil', an abbrev entered entirely in upper
  90      case is expanded using all upper case.  Otherwise, an abbrev
  91      entered entirely in upper case is expanded by capitalizing each
  92      word of the expansion.
  93
  94  - Variable: abbrev-start-location
  95      This is the buffer position for `expand-abbrev' to use as the start
  96      of the next abbrev to be expanded.  (`nil' means use the word
  97      before point instead.)  `abbrev-start-location' is set to `nil'
  98      each time `expand-abbrev' is called.  This variable is also set by
  99      `abbrev-prefix-mark'.
 100
 101  - Variable: abbrev-start-location-buffer
 102      The value of this variable is the buffer for which
 103      `abbrev-start-location' has been set.  Trying to expand an abbrev
 104      in any other buffer clears `abbrev-start-location'.  This variable
 105      is set by `abbrev-prefix-mark'.
 106
 107  - Variable: last-abbrev
 108      This is the `abbrev-symbol' of the last abbrev expanded.  This
 109      information is left by `expand-abbrev' for the sake of the
 110      `unexpand-abbrev' command.
 111
 112  - Variable: last-abbrev-location
 113      This is the location of the last abbrev expanded.  This contains
 114      information left by `expand-abbrev' for the sake of the
 115      `unexpand-abbrev' command.
 116
 117  - Variable: last-abbrev-text
 118      This is the exact expansion text of the last abbrev expanded,
 119      after case conversion (if any).  Its value is `nil' if the abbrev
 120      has already been unexpanded.  This contains information left by
 121      `expand-abbrev' for the sake of the `unexpand-abbrev' command.
 122
 123  - Variable: pre-abbrev-expand-hook
 124      This is a normal hook whose functions are executed, in sequence,
 125      just before any expansion of an abbrev.  *Note Hooks::.  Since it
 126      is a normal hook, the hook functions receive no arguments.
 127      However, they can find the abbrev to be expanded by looking in the
 128      buffer before point.
 129
 130    The following sample code shows a simple use of
 131 `pre-abbrev-expand-hook'.  If the user terminates an abbrev with a
 132 punctuation character, the hook function asks for confirmation.  Thus,
 133 this hook allows the user to decide whether to expand the abbrev, and
 134 aborts expansion if it is not confirmed.
 135
 136      (add-hook 'pre-abbrev-expand-hook 'query-if-not-space)
 137
 138      ;; This is the function invoked by `pre-abbrev-expand-hook'.
 139
 140      ;; If the user terminated the abbrev with a space, the function does
 141      ;; nothing (that is, it returns so that the abbrev can expand).  If the
 142      ;; user entered some other character, this function asks whether
 143      ;; expansion should continue.
 144
 145      ;; If the user answers the prompt with `y', the function returns
 146      ;; `nil' (because of the `not' function), but that is
 147      ;; acceptable; the return value has no effect on expansion.
 148
 149      (defun query-if-not-space ()
 150        (if (/= ?\  (preceding-char))
 151            (if (not (y-or-n-p "Do you want to expand this abbrev? "))
 152                (error "Not expanding this abbrev"))))
 153
 154 \1f
 155 File: lispref.info,  Node: Standard Abbrev Tables,  Prev: Abbrev Expansion,  Up: Abbrevs
 156
 157 Standard Abbrev Tables
 158 ======================
 159
 160    Here we list the variables that hold the abbrev tables for the
 161 preloaded major modes of XEmacs.
 162
 163  - Variable: global-abbrev-table
 164      This is the abbrev table for mode-independent abbrevs.  The abbrevs
 165      defined in it apply to all buffers.  Each buffer may also have a
 166      local abbrev table, whose abbrev definitions take precedence over
 167      those in the global table.
 168
 169  - Variable: local-abbrev-table
 170      The value of this buffer-local variable is the (mode-specific)
 171      abbreviation table of the current buffer.
 172
 173  - Variable: fundamental-mode-abbrev-table
 174      This is the local abbrev table used in Fundamental mode; in other
 175      words, it is the local abbrev table in all buffers in Fundamental
 176      mode.
 177
 178  - Variable: text-mode-abbrev-table
 179      This is the local abbrev table used in Text mode.
 180
 181  - Variable: c-mode-abbrev-table
 182      This is the local abbrev table used in C mode.
 183
 184  - Variable: lisp-mode-abbrev-table
 185      This is the local abbrev table used in Lisp mode and Emacs Lisp
 186      mode.
 187
 188 \1f
 189 File: lispref.info,  Node: Extents,  Next: Specifiers,  Prev: Abbrevs,  Up: Top
 190
 191 Extents
 192 *******
 193
 194    An "extent" is a region of text (a start position and an end
 195 position) that is displayed in a particular face and can have certain
 196 other properties such as being read-only.  Extents can overlap each
 197 other.  XEmacs efficiently handles buffers with large numbers of
 198 extents in them.
 199
 200  - Function: extentp object
 201      This returns `t' if OBJECT is an extent.
 202
 203 * Menu:
 204
 205 * Intro to Extents::       Extents are regions over a buffer or string.
 206 * Creating and Modifying Extents::
 207                            Basic extent functions.
 208 * Extent Endpoints::       Accessing and setting the bounds of an extent.
 209 * Finding Extents::        Determining which extents are in an object.
 210 * Mapping Over Extents::   More sophisticated functions for extent scanning.
 211 * Extent Properties::      Extents have built-in and user-definable properties.
 212 * Detached Extents::       Extents that are not in a buffer.
 213 * Extent Parents::         Inheriting properties from another extent.
 214 * Duplicable Extents::     Extents can be marked to be copied into strings.
 215 * Extents and Events::     Extents can interact with the keyboard and mouse.
 216 * Atomic Extents::         Treating a block of text as a single entity.
 217
 218 \1f
 219 File: lispref.info,  Node: Intro to Extents,  Next: Creating and Modifying Extents,  Up: Extents
 220
 221 Introduction to Extents
 222 =======================
 223
 224    An extent is a region of text within a buffer or string that has
 225 certain properties associated with it.  The properties of an extent
 226 primarily affect the way the text contained in the extent is displayed.
 227 Extents can freely overlap each other in a buffer or string.  Extents
 228 are invisible to functions that merely examine the text of a buffer or
 229 string.
 230
 231    _Please note:_ An alternative way to add properties to a buffer or
 232 string is to use text properties.  *Note Text Properties::.
 233
 234    An extent is logically a Lisp object consisting of a start position,
 235 an end position, a buffer or string to which these positions refer, and
 236 a property list.  As text is inserted into a buffer, the start and end
 237 positions of the extent are automatically adjusted as necessary to keep
 238 the extent referring to the same text in the buffer.  If text is
 239 inserted at the boundary of an extent, the extent's `start-open' and
 240 `end-open' properties control whether the text is included as part of
 241 the extent.  If the text bounded by an extent is deleted, the extent
 242 becomes "detached"; its start and end positions are no longer
 243 meaningful, but it maintains all its other properties and can later be
 244 reinserted into a buffer. (None of these considerations apply to
 245 strings, because text cannot be inserted into or deleted from a string.)
 246
 247    Each extent has a face or list of faces associated with it, which
 248 controls the way in which the text bounded by the extent is displayed.
 249 If an extent's face is `nil' or its properties are partially undefined,
 250 the corresponding properties from the default face for the frame is
 251 used.  If two or more extents overlap, or if a list of more than one
 252 face is specified for a particular extent, the corresponding faces are
 253 merged to determine the text's displayed properties.  Every extent has
 254 a "priority" that determines which face takes precedence if the faces
 255 conflict. (If two extents have the same priority, the one that comes
 256 later in the display order takes precedence.  *Note display order:
 257 Extent Endpoints.) Higher-numbered priority values correspond to a
 258 higher priority, and priority values can be negative.  Every extent is
 259 created with a priority of 0, but this can be changed with
 260 `set-extent-priority'.  Within a single extent with a list of faces,
 261 faces earlier in the list have a higher priority than faces later in
 262 the list.
 263
 264    Extents can be set to respond specially to key and mouse events
 265 within the extent.  An extent's `keymap' property controls the effect of
 266 key and mouse strokes within the extent's text, and the `mouse-face'
 267 property controls whether the extent is highlighted when the mouse moves
 268 over it.  *Note Extents and Events::.
 269
 270    An extent can optionally have a "begin-glyph" or "end-glyph"
 271 associated with it.  A begin-glyph or end-glyph is a pixmap or string
 272 that will be displayed either at the start or end of an extent or in the
 273 margin of the line that the start or end of the extent lies in,
 274 depending on the extent's layout policy.  Begin-glyphs and end-glyphs
 275 are used to implement annotations, and you should use the annotation API
 276 functions in preference to the lower-level extent functions.  For more
 277 information, *Note Annotations::.
 278
 279    If an extent has its `detachable' property set, it will become
 280 "detached" (i.e. no longer in the buffer) when all its text is deleted.
 281 Otherwise, it will simply shrink down to zero-length and sit in the
 282 same place in the buffer.  By default, the `detachable' property is set
 283 on newly-created extents.  *Note Detached Extents::.
 284
 285    If an extent has its `duplicable' property set, it will be
 286 remembered when a string is created from text bounded by the extent.
 287 When the string is re-inserted into a buffer, the extent will also be
 288 re-inserted.  This mechanism is used in the kill, yank, and undo
 289 commands.  *Note Duplicable Extents::.
 290
 291 \1f
 292 File: lispref.info,  Node: Creating and Modifying Extents,  Next: Extent Endpoints,  Prev: Intro to Extents,  Up: Extents
 293
 294 Creating and Modifying Extents
 295 ==============================
 296
 297  - Function: make-extent from to &optional buffer-or-string
 298      This function makes an extent for the range [FROM, TO) in
 299      BUFFER-OR-STRING (a buffer or string).  BUFFER-OR-STRING defaults
 300      to the current buffer.  Insertions at point TO will be outside of
 301      the extent; insertions at FROM will be inside the extent, causing
 302      the extent to grow (*note Extent Endpoints::).  This is the same
 303      way that markers behave.  The extent is initially detached if both
 304      FROM and TO are `nil', and in this case BUFFER-OR-STRING defaults
 305      to `nil', meaning the extent is in no buffer or string (*note
 306      Detached Extents::).
 307
 308  - Function: delete-extent extent
 309      This function removes EXTENT from its buffer and destroys it.
 310      This does not modify the buffer's text, only its display
 311      properties.  The extent cannot be used thereafter.  To remove an
 312      extent in such a way that it can be re-inserted later, use
 313      `detach-extent'.  *Note Detached Extents::.
 314
 315  - Function: extent-object extent
 316      This function returns the buffer or string that EXTENT is in.  If
 317      the return value is `nil', this means that the extent is detached;
 318      however, a detached extent will not necessarily return a value of
 319      `nil'.
 320
 321  - Function: extent-live-p object
 322      This function returns `t' if OBJECT is an extent that has not been
 323      deleted, and `nil' otherwise.
 324
 325 \1f
 326 File: lispref.info,  Node: Extent Endpoints,  Next: Finding Extents,  Prev: Creating and Modifying Extents,  Up: Extents
 327
 328 Extent Endpoints
 329 ================
 330
 331    Every extent has a start position and an end position, and logically
 332 affects the characters between those positions.  Normally the start and
 333 end positions must both be valid positions in the extent's buffer or
 334 string.  However, both endpoints can be `nil', meaning the extent is
 335 detached.  *Note Detached Extents::.
 336
 337    Whether the extent overlaps its endpoints is governed by its
 338 `start-open' and `end-open' properties.  Insertion of a character at a
 339 closed endpoint will expand the extent to include that character;
 340 insertion at an open endpoint will not.  Similarly, functions such as
 341 `extent-at' that scan over all extents overlapping a particular
 342 position will include extents with a closed endpoint at that position,
 343 but not extents with an open endpoint.
 344
 345    Note that the `start-closed' and `end-closed' properties are
 346 equivalent to `start-open' and `end-open' with the opposite sense.
 347
 348    Both endpoints can be equal, in which case the extent includes no
 349 characters but still exists in the buffer or string.  Zero-length
 350 extents are used to represent annotations (*note Annotations::) and can
 351 be used as a more powerful form of a marker.  Deletion of all the
 352 characters in an extent may or may not result in a zero-length extent;
 353 this depends on the `detachable' property (*note Detached Extents::).
 354 Insertion at the position of a zero-length extent expands the extent if
 355 both endpoints are closed; goes before the extent if it has the
 356 `start-open' property; and goes after the extent if it has the
 357 `end-open' property.  Zero-length extents with both the `start-open'
 358 and `end-open' properties are treated as if their starting point were
 359 closed.  Deletion of a character on a side of a zero-length extent
 360 whose corresponding endpoint is closed causes the extent to be detached
 361 if its `detachable' property is set; if the corresponding endpoint is
 362 open, the extent remains in the buffer, moving as necessary.
 363
 364    Extents are ordered within a buffer or string by increasing start
 365 position, and then by decreasing end position (this is called the
 366 "display order").
 367
 368  - Function: extent-start-position extent
 369      This function returns the start position of EXTENT.
 370
 371  - Function: extent-end-position extent
 372      This function returns the end position of EXTENT.
 373
 374  - Function: extent-length extent
 375      This function returns the length of EXTENT in characters.  If the
 376      extent is detached, this returns `0'.  If the extent is not
 377      detached, this is equivalent to
 378           (- (extent-end-position EXTENT) (extent-start-position EXTENT))
 379
 380  - Function: set-extent-endpoints extent start end &optional
 381           buffer-or-string
 382      This function sets the start and end position of EXTENT to START
 383      and END.  If both are `nil', this is equivalent to `detach-extent'.
 384
 385      BUFFER-OR-STRING specifies the new buffer or string that the
 386      extent should be in, and defaults to EXTENT's buffer or string.
 387      (If `nil', and EXTENT is in no buffer and no string, it defaults
 388      to the current buffer.)
 389
 390      See documentation on `detach-extent' for a discussion of undo
 391      recording.
 392
 393 \1f
 394 File: lispref.info,  Node: Finding Extents,  Next: Mapping Over Extents,  Prev: Extent Endpoints,  Up: Extents
 395
 396 Finding Extents
 397 ===============
 398
 399    The following functions provide a simple way of determining the
 400 extents in a buffer or string.  A number of more sophisticated
 401 primitives for mapping over the extents in a range of a buffer or string
 402 are also provided (*note Mapping Over Extents::).  When reading through
 403 this section, keep in mind the way that extents are ordered (*note
 404 Extent Endpoints::).
 405
 406  - Function: extent-list &optional buffer-or-string from to flags
 407           property value
 408      This function returns a list of the extents in BUFFER-OR-STRING.
 409      BUFFER-OR-STRING defaults to the current buffer if omitted.  FROM
 410      and TO can be used to limit the range over which extents are
 411      returned; if omitted, all extents in the buffer or string are
 412      returned.
 413
 414      More specifically, if a range is specified using FROM and TO, only
 415      extents that overlap the range (i.e. begin or end inside of the
 416      range) are included in the list.  FROM and TO default to the
 417      beginning and end of BUFFER-OR-STRING, respectively.
 418
 419      FLAGS controls how end cases are treated.  For a discussion of
 420      this, and exactly what "overlap" means, see `map-extents'.
 421
 422      The optional arguments PROPERTY and VALUE can be used to further
 423      restrict which extents are returned.  They have the same meaning
 424      as for `map-extents'.
 425
 426      If you want to map a function over the extents in a buffer or
 427      string, consider using `map-extents' or `mapcar-extents' instead.
 428
 429      See also the function `extents-at'.
 430
 431    Functions that create extents must be prepared for the possibility
 432 that there are other extents in the same area, created by other
 433 functions.  To deal with this, functions typically mark their own
 434 extents by setting a particular property on them.  The following
 435 function makes it easier to locate those extents.
 436
 437  - Function: extent-at pos &optional object property before at-flag
 438      This function finds the "smallest" extent (i.e., the last one in
 439      the display order) at (i.e., overlapping) POS in OBJECT (a buffer
 440      or string) having PROPERTY set.  OBJECT defaults to the current
 441      buffer.  PROPERTY defaults to `nil', meaning that any extent will
 442      do.  Returns `nil' if there is no matching extent at POS.  If the
 443      fourth argument BEFORE is not `nil', it must be an extent; any
 444      returned extent will precede that extent.  This feature allows
 445      `extent-at' to be used by a loop over extents.
 446
 447      AT-FLAG controls how end cases are handled (i.e. what "at" really
 448      means), and should be one of:
 449
 450     `nil'
 451
 452     `after'
 453           An extent is at POS if it covers the character after POS.
 454           This is consistent with the way that text properties work.
 455
 456     `before'
 457           An extent is at POS if it covers the character before POS.
 458
 459     `at'
 460           An extent is at POS if it overlaps or abuts POS.  This
 461           includes all zero-length extents at POS.
 462
 463      Note that in all cases, the start-openness and end-openness of the
 464      extents considered is ignored.  If you want to pay attention to
 465      those properties, you should use `map-extents', which gives you
 466      more control.
 467
 468    The following low-level functions are provided for explicitly
 469 traversing the extents in a buffer according to the display order.
 470 These functions are mostly intended for debugging--in normal operation,
 471 you should probably use `mapcar-extents' or `map-extents', or loop
 472 using the BEFORE argument to `extent-at', rather than creating a loop
 473 using `next-extent'.
 474
 475  - Function: next-extent extent
 476      Given an extent EXTENT, this function returns the next extent in
 477      the buffer or string's display order.  If EXTENT is a buffer or
 478      string, this returns the first extent in the buffer or string.
 479
 480  - Function: previous-extent extent
 481      Given an extent EXTENT, this function returns the previous extent
 482      in the buffer or string's display order.  If EXTENT is a buffer or
 483      string, this returns the last extent in the buffer or string.
 484
 485 \1f
 486 File: lispref.info,  Node: Mapping Over Extents,  Next: Extent Properties,  Prev: Finding Extents,  Up: Extents
 487
 488 Mapping Over Extents
 489 ====================
 490
 491    The most basic and general function for mapping over extents is
 492 called `map-extents'.  You should read through the definition of this
 493 function to familiarize yourself with the concepts and optional
 494 arguments involved.  However, in practice you may find it more
 495 convenient to use the function `mapcar-extents' or to create a loop
 496 using the `before' argument to `extent-at' (*note Finding Extents::).
 497
 498  - Function: map-extents function &optional object from to maparg flags
 499           property value
 500      This function maps FUNCTION over the extents which overlap a
 501      region in OBJECT.  OBJECT is normally a buffer or string but could
 502      be an extent (see below).  The region is normally bounded by
 503      [FROM, TO) (i.e. the beginning of the region is closed and the end
 504      of the region is open), but this can be changed with the FLAGS
 505      argument (see below for a complete discussion).
 506
 507      FUNCTION is called with the arguments (extent, MAPARG).  The
 508      arguments OBJECT, FROM, TO, MAPARG, and FLAGS are all optional and
 509      default to the current buffer, the beginning of OBJECT, the end of
 510      OBJECT, `nil', and `nil', respectively.  `map-extents' returns the
 511      first non-`nil' result produced by FUNCTION, and no more calls to
 512      FUNCTION are made after it returns non-`nil'.
 513
 514      If OBJECT is an extent, FROM and TO default to the extent's
 515      endpoints, and the mapping omits that extent and its predecessors.
 516      This feature supports restarting a loop based on `map-extents'.
 517      Note: OBJECT must be attached to a buffer or string, and the
 518      mapping is done over that buffer or string.
 519
 520      An extent overlaps the region if there is any point in the extent
 521      that is also in the region. (For the purpose of overlap,
 522      zero-length extents and regions are treated as closed on both ends
 523      regardless of their endpoints' specified open/closedness.) Note
 524      that the endpoints of an extent or region are considered to be in
 525      that extent or region if and only if the corresponding end is
 526      closed.  For example, the extent [5,7] overlaps the region [2,5]
 527      because 5 is in both the extent and the region.  However, (5,7]
 528      does not overlap [2,5] because 5 is not in the extent, and neither
 529      [5,7] nor (5,7] overlaps the region [2,5) because 5 is not in the
 530      region.
 531
 532      The optional FLAGS can be a symbol or a list of one or more
 533      symbols, modifying the behavior of `map-extents'.  Allowed symbols
 534      are:
 535
 536     `end-closed'
 537           The region's end is closed.
 538
 539     `start-open'
 540           The region's start is open.
 541
 542     `all-extents-closed'
 543           Treat all extents as closed on both ends for the purpose of
 544           determining whether they overlap the region, irrespective of
 545           their actual open- or closedness.
 546
 547     `all-extents-open'
 548           Treat all extents as open on both ends.
 549
 550     `all-extents-closed-open'
 551           Treat all extents as start-closed, end-open.
 552
 553     `all-extents-open-closed'
 554           Treat all extents as start-open, end-closed.
 555
 556     `start-in-region'
 557           In addition to the above conditions for extent overlap, the
 558           extent's start position must lie within the specified region.
 559           Note that, for this condition, open start positions are
 560           treated as if 0.5 was added to the endpoint's value, and open
 561           end positions are treated as if 0.5 was subtracted from the
 562           endpoint's value.
 563
 564     `end-in-region'
 565           The extent's end position must lie within the region.
 566
 567     `start-and-end-in-region'
 568           Both the extent's start and end positions must lie within the
 569           region.
 570
 571     `start-or-end-in-region'
 572           Either the extent's start or end position must lie within the
 573           region.
 574
 575     `negate-in-region'
 576           The condition specified by a `*-in-region' flag must _not_
 577           hold for the extent to be considered.
 578
 579      At most one of `all-extents-closed', `all-extents-open',
 580      `all-extents-closed-open', and `all-extents-open-closed' may be
 581      specified.
 582
 583      At most one of `start-in-region', `end-in-region',
 584      `start-and-end-in-region', and `start-or-end-in-region' may be
 585      specified.
 586
 587      If optional arg PROPERTY is non-`nil', only extents with that
 588      property set on them will be visited.  If optional arg VALUE is
 589      non-`nil', only extents whose value for that property is `eq' to
 590      VALUE will be visited.
 591
 592    If you want to map over extents and accumulate a list of results,
 593 the following function may be more convenient than `map-extents'.
 594
 595  - Function: mapcar-extents function &optional predicate
 596           buffer-or-string from to flags property value
 597      This function applies FUNCTION to all extents which overlap a
 598      region in BUFFER-OR-STRING.  The region is delimited by FROM and
 599      TO.  FUNCTION is called with one argument, the extent.  A list of
 600      the values returned by FUNCTION is returned.  An optional
 601      PREDICATE may be used to further limit the extents over which
 602      FUNCTION is mapped.  The optional arguments FLAGS, PROPERTY, and
 603      VALUE may also be used to control the extents passed to PREDICATE
 604      or FUNCTION, and have the same meaning as in `map-extents'.
 605
 606  - Function: map-extent-children function &optional object from to
 607           maparg flags property value
 608      This function is similar to `map-extents', but differs in that:
 609
 610         * It only visits extents which start in the given region.
 611
 612         * After visiting an extent E, it skips all other extents which
 613           start inside E but end before E's end.
 614
 615      Thus, this function may be used to walk a tree of extents in a
 616      buffer:
 617           (defun walk-extents (buffer &optional ignore)
 618             (map-extent-children 'walk-extents buffer))
 619
 620  - Function: extent-in-region-p extent &optional from to flags
 621      This function returns `t' if `map-extents' would visit EXTENT if
 622      called with the given arguments.
 623
 624 \1f
 625 File: lispref.info,  Node: Extent Properties,  Next: Detached Extents,  Prev: Mapping Over Extents,  Up: Extents
 626
 627 Properties of Extents
 628 =====================
 629
 630    Each extent has a property list associating property names with
 631 values.  Some property names have predefined meanings, and can usually
 632 only assume particular values.  Assigning other values to such a
 633 property either cause the value to be converted into a legal value
 634 (e.g., assigning anything but `nil' to a Boolean property will cause
 635 the value of `t' to be assigned to the property) or will cause an
 636 error.  Property names without predefined meanings can be assigned any
 637 value.  An undefined property is equivalent to a property with a value
 638 of `nil', or with a particular default value in the case of properties
 639 with predefined meanings.  Note that, when an extent is created, the
 640 `end-open' and `detachable' properties are set on it.
 641
 642    If an extent has a parent, all of its properties actually derive
 643 from that parent (or from the root ancestor if the parent in turn has a
 644 parent), and setting a property of the extent actually sets that
 645 property on the parent.  *Note Extent Parents::.
 646
 647  - Function: extent-property extent property &optional default
 648      This function returns EXTENT's value for PROPERTY, or DEFAULT if
 649      no such property exists.
 650
 651  - Function: extent-properties extent
 652      This function returns a list of all of EXTENT's properties that do
 653      not have the value of `nil' (or the default value, for properties
 654      with predefined meanings).
 655
 656  - Function: set-extent-property extent property value
 657      This function sets PROPERTY to VALUE in EXTENT. (If PROPERTY has a
 658      predefined meaning, only certain values are allowed, and some
 659      values may be converted to others before being stored.)
 660
 661  - Function: set-extent-properties extent plist
 662      Change some properties of EXTENT.  PLIST is a property list.  This
 663      is useful to change many extent properties at once.
 664
 665    The following table lists the properties with predefined meanings,
 666 along with their allowable values.
 667
 668 `detached'
 669      (Boolean) Whether the extent is detached.   Setting this is the
 670      same as calling `detach-extent'.  *Note Detached Extents::.
 671
 672 `destroyed'
 673      (Boolean) Whether the extent has been deleted.  Setting this is
 674      the same as calling `delete-extent'.
 675
 676 `priority'
 677      (integer) The extent's redisplay priority.  Defaults to 0.  *Note
 678      priority: Intro to Extents.  This property can also be set with
 679      `set-extent-priority' and accessed with `extent-priority'.
 680
 681 `start-open'
 682      (Boolean) Whether the start position of the extent is open,
 683      meaning that characters inserted at that position go outside of
 684      the extent.  *Note Extent Endpoints::.
 685
 686 `start-closed'
 687      (Boolean) Same as `start-open' but with the opposite sense.
 688      Setting this property clears `start-open' and vice-versa.
 689
 690 `end-open'
 691      (Boolean) Whether the end position of the extent is open, meaning
 692      that characters inserted at that position go outside of the
 693      extent.  This is `t' by default.  *Note Extent Endpoints::.
 694
 695 `end-closed'
 696      (Boolean) Same as `end-open' but with the opposite sense.  Setting
 697      this property clears `end-open' and vice-versa.
 698
 699 `read-only'
 700      (Boolean) Whether text within this extent will be unmodifiable.
 701
 702 `face'
 703      (face, face name, list of faces or face names, or `nil') The face
 704      in which to display the extent's text.  This property can also be
 705      set with `set-extent-face' and accessed with `extent-face'.  Note
 706      that if a list of faces is specified, the faces are merged
 707      together, with faces earlier in the list having priority over
 708      faces later in the list.
 709
 710 `mouse-face'
 711      (face, face name, list of faces or face names, or `nil') The face
 712      used to display the extent when the mouse moves over it.  This
 713      property can also be set with `set-extent-mouse-face' and accessed
 714      with `extent-mouse-face'.  Note that if a list of faces is
 715      specified, the faces are merged together, with faces earlier in
 716      the list having priority over faces later in the list.  *Note
 717      Extents and Events::.
 718
 719 `pointer'
 720      (pointer glyph)  The glyph used as the pointer when the mouse
 721      moves over the extent.  This takes precedence over the
 722      `text-pointer-glyph' and `nontext-pointer-glyph' variables.  If
 723      for any reason this glyph is an invalid pointer, the standard
 724      glyphs will be used as fallbacks.  *Note Mouse Pointer::.
 725
 726 `detachable'
 727      (Boolean) Whether this extent becomes detached when all of the
 728      text it covers is deleted.  This is `t' by default.  *Note
 729      Detached Extents::.
 730
 731 `duplicable'
 732      (Boolean) Whether this extent should be copied into strings, so
 733      that kill, yank, and undo commands will restore or copy it.  *Note
 734      Duplicable Extents::.
 735
 736 `unique'
 737      (Boolean) Meaningful only in conjunction with `duplicable'.  When
 738      this is set, there may be only one instance of this extent
 739      attached at a time.  *Note Duplicable Extents::.
 740
 741 `invisible'
 742      (Boolean) If `t', text under this extent will not be displayed -
 743      it will look as if the text is not there at all.
 744
 745 `keymap'
 746      (keymap or `nil') This keymap is consulted for mouse clicks on this
 747      extent or keypresses made while `point' is within the extent.
 748      *Note Extents and Events::.
 749
 750 `copy-function'
 751      This is a hook that is run when a duplicable extent is about to be
 752      copied from a buffer to a string (or the kill ring).  *Note
 753      Duplicable Extents::.
 754
 755 `paste-function'
 756      This is a hook that is run when a duplicable extent is about to be
 757      copied from a string (or the kill ring) into a buffer.  *Note
 758      Duplicable Extents::.
 759
 760 `begin-glyph'
 761      (glyph or `nil') This extent's begin glyph.  *Note Annotations::.
 762
 763 `end-glyph'
 764      (glyph or `nil') This extent's end glyph.  *Note Annotations::.
 765
 766 `begin-glyph-layout'
 767      (`text', `whitespace', `inside-margin', or `outside-margin') The
 768      layout policy for this extent's begin glyph.  Defaults to `text'.
 769      *Note Annotations::.
 770
 771 `end-glyph-layout'
 772      (`text', `whitespace', `inside-margin', or `outside-margin') The
 773      layout policy for this extent's end glyph.  Defaults to `text'.
 774      *Note Annotations::.
 775
 776 `initial-redisplay-function'
 777      (any funcallable object) The function to be called the first time
 778      (a part of) the extent is redisplayed.  It will be called with the
 779      extent as its argument.
 780
 781      This is used by `lazy-shot' to implement lazy font-locking.  The
 782      functionality is still experimental, and may change without further
 783      notice.
 784
 785    The following convenience functions are provided for accessing
 786 particular properties of an extent.
 787
 788  - Function: extent-face extent
 789      This function returns the `face' property of EXTENT.  This might
 790      also return a list of face names.  Do not modify this list
 791      directly!  Instead, use `set-extent-face'.
 792
 793      Note that you can use `eq' to compare lists of faces as returned
 794      by `extent-face'.  In other words, if you set the face of two
 795      different extents to two lists that are `equal' but not `eq', then
 796      the return value of `extent-face' on the two extents will return
 797      the identical list.
 798
 799  - Function: extent-mouse-face extent
 800      This function returns the `mouse-face' property of EXTENT.  This
 801      might also return a list of face names.  Do not modify this list
 802      directly!  Instead, use `set-extent-mouse-face'.
 803
 804      Note that you can use `eq' to compare lists of faces as returned
 805      by `extent-mouse-face', just like for `extent-face'.
 806
 807  - Function: extent-priority extent
 808      This function returns the `priority' property of EXTENT.
 809
 810  - Function: extent-keymap extent
 811      This function returns the `keymap' property of EXTENT.
 812
 813  - Function: extent-begin-glyph-layout extent
 814      This function returns the `begin-glyph-layout' property of EXTENT,
 815      i.e. the layout policy associated with the EXTENT's begin glyph.
 816
 817  - Function: extent-end-glyph-layout extent
 818      This function returns the `end-glyph-layout' property of EXTENT,
 819      i.e. the layout policy associated with the EXTENT's end glyph.
 820
 821  - Function: extent-begin-glyph extent
 822      This function returns the `begin-glyph' property of EXTENT, i.e.
 823      the glyph object displayed at the beginning of EXTENT.  If there
 824      is none, `nil' is returned.
 825
 826  - Function: extent-end-glyph extent
 827      This function returns the `end-glyph' property of EXTENT, i.e. the
 828      glyph object displayed at the end of EXTENT.  If there is none,
 829      `nil' is returned.
 830
 831    The following convenience functions are provided for setting
 832 particular properties of an extent.
 833
 834  - Function: set-extent-priority extent priority
 835      This function sets the `priority' property of EXTENT to PRIORITY.
 836
 837  - Function: set-extent-face extent face
 838      This function sets the `face' property of EXTENT to FACE.
 839
 840  - Function: set-extent-mouse-face extent face
 841      This function sets the `mouse-face' property of EXTENT to FACE.
 842
 843  - Function: set-extent-keymap extent keymap
 844      This function sets the `keymap' property of EXTENT to KEYMAP.
 845      KEYMAP must be either a keymap object, or `nil'.
 846
 847  - Function: set-extent-begin-glyph-layout extent layout
 848      This function sets the `begin-glyph-layout' property of EXTENT to
 849      LAYOUT.
 850
 851  - Function: set-extent-end-glyph-layout extent layout
 852      This function sets the `end-glyph-layout' property of EXTENT to
 853      LAYOUT.
 854
 855  - Function: set-extent-begin-glyph extent begin-glyph &optional layout
 856      This function sets the `begin-glyph' and `glyph-layout' properties
 857      of EXTENT to BEGIN-GLYPH and LAYOUT, respectively. (LAYOUT
 858      defaults to `text' if not specified.)
 859
 860  - Function: set-extent-end-glyph extent end-glyph &optional layout
 861      This function sets the `end-glyph' and `glyph-layout' properties
 862      of EXTENT to END-GLYPH and LAYOUT, respectively. (LAYOUT defaults
 863      to `text' if not specified.)
 864
 865  - Function: set-extent-initial-redisplay-function extent function
 866      This function sets the `initial-redisplay-function' property of the
 867      extent to FUNCTION.
 868
 869 \1f
 870 File: lispref.info,  Node: Detached Extents,  Next: Extent Parents,  Prev: Extent Properties,  Up: Extents
 871
 872 Detached Extents
 873 ================
 874
 875    A detached extent is an extent that is not attached to a buffer or
 876 string but can be re-inserted.  Detached extents have a start position
 877 and end position of `nil'.  Extents can be explicitly detached using
 878 `detach-extent'.  An extent is also detached when all of its characters
 879 are all killed by a deletion, if its `detachable' property is set; if
 880 this property is not set, the extent becomes a zero-length extent.
 881 (Zero-length extents with the `detachable' property set behave
 882 specially.  *Note zero-length extents: Extent Endpoints.)
 883
 884  - Function: detach-extent extent
 885      This function detaches EXTENT from its buffer or string.  If
 886      EXTENT has the `duplicable' property, its detachment is tracked by
 887      the undo mechanism.  *Note Duplicable Extents::.
 888
 889  - Function: extent-detached-p extent
 890      This function returns `nil' if EXTENT is detached, and `t'
 891      otherwise.
 892
 893  - Function: copy-extent extent &optional object
 894      This function makes a copy of EXTENT.  It is initially detached.
 895      Optional argument OBJECT defaults to EXTENT's object (normally a
 896      buffer or string, but could be `nil').
 897
 898  - Function: insert-extent extent &optional start end no-hooks object
 899      This function inserts EXTENT from START to END in OBJECT (a buffer
 900      or string).  If EXTENT is detached from a different buffer or
 901      string, or in most cases when EXTENT is already attached, the
 902      extent will first be copied as if with `copy-extent'.  This
 903      function operates the same as if `insert' were called on a string
 904      whose extent data calls for EXTENT to be inserted, except that if
 905      NO-HOOKS is non-`nil', EXTENT's `paste-function' will not be
 906      invoked.  *Note Duplicable Extents::.
 907
 908 \1f
 909 File: lispref.info,  Node: Extent Parents,  Next: Duplicable Extents,  Prev: Detached Extents,  Up: Extents
 910
 911 Extent Parents
 912 ==============
 913
 914    An extent can have a parent extent set for it.  If this is the case,
 915 the extent derives all its properties from that extent and has no
 916 properties of its own.  The only "properties" that the extent keeps are
 917 the buffer or string it refers to and the start and end points.  (More
 918 correctly, the extent's own properties are shadowed.  If you later
 919 change the extent to have no parent, its own properties will become
 920 visible again.)
 921
 922    It is possible for an extent's parent to itself have a parent, and
 923 so on.  Through this, a whole tree of extents can be created, all
 924 deriving their properties from one root extent.  Note, however, that
 925 you cannot create an inheritance loop--this is explicitly disallowed.
 926
 927    Parent extents are used to implement the extents over the modeline.
 928
 929  - Function: set-extent-parent extent parent
 930      This function sets the parent of EXTENT to PARENT.  If PARENT is
 931      `nil', the extent is set to have no parent.
 932
 933  - Function: extent-parent extent
 934      This function return the parents (if any) of EXTENT, or `nil'.
 935
 936  - Function: extent-children extent
 937      This function returns a list of the children (if any) of EXTENT.
 938      The children of an extent are all those extents whose parent is
 939      that extent.  This function does not recursively trace children of
 940      children.
 941
 942  - Function: extent-descendants extent
 943      This function returns a list of all descendants of EXTENT,
 944      including EXTENT.  This recursively applies `extent-children' to
 945      any children of EXTENT, until no more children can be found.
 946
 947 \1f
 948 File: lispref.info,  Node: Duplicable Extents,  Next: Extents and Events,  Prev: Extent Parents,  Up: Extents
 949
 950 Duplicable Extents
 951 ==================
 952
 953    If an extent has the `duplicable' property, it will be copied into
 954 strings, so that kill, yank, and undo commands will restore or copy it.
 955
 956    Specifically:
 957
 958    * When a string is created using `buffer-substring' or
 959      `buffer-string', any duplicable extents in the region corresponding
 960      to the string will be copied into the string (*note Buffer
 961      Contents::).  When the string in inserted into a buffer using
 962      `insert', `insert-before-markers', `insert-buffer' or
 963      `insert-buffer-substring', the extents in the string will be copied
 964      back into the buffer (*note Insertion::).  The extents in a string
 965      can, of course, be retrieved explicitly using the standard extent
 966      primitives over the string.
 967
 968    * Similarly, when text is copied or cut into the kill ring, any
 969      duplicable extents will be remembered and reinserted later when
 970      the text is pasted back into a buffer.
 971
 972    * When `concat' is called on strings, the extents in the strings are
 973      copied into the resulting string.
 974
 975    * When `substring' is called on a string, the relevant extents are
 976      copied into the resulting string.
 977
 978    * When a duplicable extent is detached by `detach-extent' or string
 979      deletion, or inserted by `insert-extent' or string insertion, the
 980      action is recorded by the undo mechanism so that it can be undone
 981      later.  Note that if an extent gets detached and then a later undo
 982      causes the extent to get reinserted, the new extent will not be
 983      `eq' to the original extent.
 984
 985    * Extent motion, face changes, and attachment via `make-extent' are
 986      not recorded by the undo mechanism.  This means that extent changes
 987      which are to be undo-able must be performed by character editing,
 988      or by insertion and detachment of duplicable extents.
 989
 990    * A duplicable extent's `copy-function' property, if non-`nil',
 991      should be a function, and will be run when a duplicable extent is
 992      about to be copied from a buffer to a string (or the kill ring).
 993      It is called with three arguments: the extent and the buffer
 994      positions within it which are being copied.  If this function
 995      returns `nil', then the extent will not be copied; otherwise it
 996      will.
 997
 998    * A duplicable extent's `paste-function' property, if non-`nil',
 999      should be a function, and will be run when a duplicable extent is
1000      about to be copied from a string (or the kill ring) into a buffer.
1001      It is called with three arguments: the original extent and the
1002      buffer positions which the copied extent will occupy. (This hook
1003      is run after the corresponding text has already been inserted into
1004      the buffer.) Note that the extent argument may be detached when
1005      this function is run.  If this function returns `nil', no extent
1006      will be inserted.  Otherwise, there will be an extent covering the
1007      range in question.
1008
1009      Note: if the extent to be copied is already attached to the buffer
1010      and overlaps the new range, the extent will simply be extended and
1011      the `paste-function' will not be called.
1012
1013 \1f
1014 File: lispref.info,  Node: Extents and Events,  Next: Atomic Extents,  Prev: Duplicable Extents,  Up: Extents
1015
1016 Interaction of Extents with Keyboard and Mouse Events
1017 =====================================================
1018
1019    If an extent has the `mouse-face' property set, it will be
1020 highlighted when the mouse passes over it.  Highlighting is accomplished
1021 by merging the extent's face with the face or faces specified by the
1022 `mouse-face' property.  The effect is as if a pseudo-extent with the
1023 `mouse-face' face were inserted after the extent in the display order
1024 (*note Extent Endpoints::, display order).
1025
1026  - Variable: mouse-highlight-priority
1027      This variable holds the priority to use when merging in the
1028      highlighting pseudo-extent.  The default is 1000.  This is
1029      purposely set very high so that the highlighting pseudo-extent
1030      shows up even if there are other extents with various priorities
1031      at the same location.
1032
1033    You can also explicitly cause an extent to be highlighted.  Only one
1034 extent at a time can be highlighted in this fashion, and any other
1035 highlighted extent will be de-highlighted.
1036
1037  - Function: highlight-extent extent &optional highlight-p
1038      This function highlights (if HIGHLIGHT-P is non-`nil') or
1039      de-highlights (if HIGHLIGHT-P is `nil') EXTENT, if EXTENT has the
1040      `mouse-face' property. (Nothing happens if EXTENT does not have
1041      the `mouse-face' property.)
1042
1043  - Function: force-highlight-extent extent &optional highlight-p
1044      This function is similar to `highlight-extent' but highlights or
1045      de-highlights the extent regardless of whether it has the
1046      `mouse-face' property.
1047
1048    If an extent has a `keymap' property, this keymap will be consulted
1049 for mouse clicks on the extent and keypresses made while `point' is
1050 within the extent.  The behavior of mouse clicks and keystrokes not
1051 defined in the keymap is as normal for the buffer.
1052
1053 \1f
1054 File: lispref.info,  Node: Atomic Extents,  Prev: Extents and Events,  Up: Extents
1055
1056 Atomic Extents
1057 ==============
1058
1059    If the Lisp file `atomic-extents' is loaded, then the atomic extent
1060 facility is available.  An "atomic extent" is an extent for which
1061 `point' cannot be positioned anywhere within it.  This ensures that
1062 when selecting text, either all or none of the extent is selected.
1063
1064    To make an extent atomic, set its `atomic' property.
1065
1066 \1f
1067 File: lispref.info,  Node: Specifiers,  Next: Faces and Window-System Objects,  Prev: Extents,  Up: Top
1068
1069 Specifiers
1070 **********
1071
1072    A specifier is an object used to keep track of a property whose value
1073 may vary depending on the particular situation (e.g. particular buffer
1074 displayed in a particular window) that it is used in.  The value of many
1075 built-in properties, such as the font, foreground, background, and such
1076 properties of a face and variables such as `modeline-shadow-thickness'
1077 and `top-toolbar-height', is actually a specifier object.  The
1078 specifier object, in turn, is "instanced" in a particular situation to
1079 yield the real value of the property in that situation.
1080
1081  - Function: specifierp object
1082      This function returns non-`nil' if OBJECT is a specifier.
1083
1084 * Menu:
1085
1086 * Introduction to Specifiers::  Specifiers provide a clean way for
1087                                 display and other properties to vary
1088                                 (under user control) in a wide variety
1089                                 of contexts.
1090 * Specifiers In-Depth::         Gory details about specifier innards.
1091 * Specifier Instancing::        Instancing means obtaining the ``value'' of
1092                                 a specifier in a particular context.
1093 * Specifier Types::             Specifiers come in different flavors.
1094 * Adding Specifications::       Specifications control a specifier's ``value''
1095                                 by giving conditions under which a
1096                                 particular value is valid.
1097 * Retrieving Specifications::   Querying a specifier's specifications.
1098 * Specifier Tag Functions::     Working with specifier tags.
1099 * Specifier Instancing Functions::
1100                                 Functions to instance a specifier.
1101 * Specifier Example::           Making all this stuff clearer.
1102 * Creating Specifiers::         Creating specifiers for your own use.
1103 * Specifier Validation Functions::
1104                                 Validating the components of a specifier.
1105 * Other Specification Functions::
1106                                 Other ways of working with specifications.
1107
1108 \1f
1109 File: lispref.info,  Node: Introduction to Specifiers,  Next: Specifiers In-Depth,  Up: Specifiers
1110
1111 Introduction to Specifiers
1112 ==========================
1113
1114    Sometimes you may want the value of a property to vary depending on
1115 the context the property is used in.  A simple example of this in XEmacs
1116 is buffer-local variables.  For example, the variable
1117 `modeline-format', which controls the format of the modeline, can have
1118 different values depending on the particular buffer being edited.  The
1119 variable has a default value which most modes will use, but a
1120 specialized package such as Calendar might change the variable so as to
1121 tailor the modeline to its own purposes.
1122
1123    Other properties (such as those that can be changed by the
1124 `modify-frame-parameters' function, for example the color of the text
1125 cursor) can have frame-local values, although it might also make sense
1126 for them to have buffer-local values.  In other cases, you might want
1127 the property to vary depending on the particular window within the
1128 frame that applies (e.g. the top or bottom window in a split frame), the
1129 device type that that frame appears on (X or tty), etc.  Perhaps you can
1130 envision some more complicated scenario where you want a particular
1131 value in a specified buffer, another value in all other buffers
1132 displayed on a particular frame, another value in all other buffers
1133 displayed in all other frames on any mono (two-color, e.g. black and
1134 white only) displays, and a default value in all other circumstances.
1135
1136    A "specifier" is a generalization of this, allowing a great deal of
1137 flexibility in controlling exactly what value a property has in which
1138 circumstances.  It is most commonly used for display properties, such as
1139 an image or the foreground color of a face.  As a simple example, you
1140 can specify that the foreground of the default face be
1141
1142    * blue for a particular buffer
1143
1144    * green for all other buffers
1145
1146    As a more complicated example, you could specify that the foreground
1147 of the default face be
1148
1149    * forest green for all buffers displayed in a particular Emacs
1150      window, or green if the X server doesn't recognize the color
1151      `forest green'
1152
1153    * blue for all buffers displayed in a particular frame
1154
1155    * red for all other buffers displayed on a color device
1156
1157    * white for all other buffers
1158