Mercurial > hg > xemacs-beta

comparison man/lispref/specifiers.texi @ 2028:2ba4f06a264d

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
[xemacs-hg @ 2004-04-19 08:02:27 by stephent] texi doc improvements <87zn98wg4q.fsf@tleepslib.sk.tsukuba.ac.jp>
author stephent
date Mon, 19 Apr 2004 08:02:38 +0000
parents 01dce9d37966
children 6bca5896aab2
comparison
equal deleted inserted replaced
2027:71477bc21fe8 2028:2ba4f06a264d
42 * Creating Specifiers:: Creating specifiers for your own use. 42 * Creating Specifiers:: Creating specifiers for your own use.
43 * Specifier Validation Functions:: 43 * Specifier Validation Functions::
44 Validating the components of a specifier. 44 Validating the components of a specifier.
45 * Other Specification Functions:: 45 * Other Specification Functions::
46 Other ways of working with specifications. 46 Other ways of working with specifications.
47 * Specifier Compatibility Notes::
48 Backward compatibility and GNU Emacs.
47 @end menu 49 @end menu
48 50
49 @node Introduction to Specifiers 51 @node Introduction to Specifiers
50 @section Introduction to Specifiers 52 @section Introduction to Specifiers
51 53
1102 @end defun 1104 @end defun
1103 1105
1104 @defun specifier-matching-instance specifier matchspec &optional domain default no-fallback 1106 @defun specifier-matching-instance specifier matchspec &optional domain default no-fallback
1105 This function returns an instance for @var{specifier} in @var{domain} 1107 This function returns an instance for @var{specifier} in @var{domain}
1106 that matches @var{matchspec}. If no instance can be generated for 1108 that matches @var{matchspec}. If no instance can be generated for
1107 @var{domain}, return @var{default}. 1109 @var{domain}, return @var{default}. @xref{Specifier Compatibility Notes}.
1108 1110
1109 This function is identical to @code{specifier-instance} except that a 1111 This function is identical to @code{specifier-instance} except that a
1110 specification will only be considered if it matches @var{matchspec}. 1112 specification will only be considered if it matches @var{matchspec}.
1111 The definition of ``match,'' and allowed values for @var{matchspec}, are 1113 The definition of ``match,'' and allowed values for @var{matchspec}, are
1112 dependent on the particular type of specifier. Here are some examples: 1114 dependent on the particular type of specifier. Here are some examples:
1337 @result{} nil 1339 @result{} nil
1338 @end example 1340 @end example
1339 1341
1340 Note that since specifiers generalize both frame-local and buffer-local 1342 Note that since specifiers generalize both frame-local and buffer-local
1341 variables in a sensible way, XEmacs is not likely to put a high priority 1343 variables in a sensible way, XEmacs is not likely to put a high priority
1342 on implementing frame-local variables. 1344 on implementing frame-local variables @ref{Specifier Compatibility Notes}.
1343 @c Thanks to Jerry James for the following explanation. He is not
1344 @c responsible for its use here, Stephen Turnbull is.
1345 In fact, some developers think that frame-local variables are evil for
1346 the same reason that buffer-local variables are evil: the declaration is
1347 both global and invisible. That is, you cannot tell whether a variable
1348 is ``normal,'' buffer-local, or frame-local just by looking at it. So
1349 if you have namespace management problems, and some other Lisp package
1350 happens to use a variable name that you already declared frame- or
1351 buffer-local, weird stuff happens, and it is extremely hard to track
1352 down.
1353 1345
1354 1346
1355 @node Creating Specifiers 1347 @node Creating Specifiers
1356 @section Creating New Specifier Objects 1348 @section Creating New Specifier Objects
1357 1349
1601 @end defun 1593 @end defun
1602 1594
1603 @defun specifier-locale-type-from-locale locale 1595 @defun specifier-locale-type-from-locale locale
1604 Given a specifier @var{locale}, this function returns its type. 1596 Given a specifier @var{locale}, this function returns its type.
1605 @end defun 1597 @end defun
1598
1599 @node Specifier Compatibility Notes
1600 @section Specifier Compatibility Notes
1601
1602 This node describes compatibility issues in the use of specifiers known
1603 as of 2004-01-22.
1604 @c I considered basing the main text on 21.4, but then future
1605 @c maintenance of this documentation would be a pain.
1606 The main text refers to XEmacs 21.5.16.
1607
1608 Effort will be made to describe changes in the API or semantics between
1609 XEmacs versions accurately. Any inaccuracy or missing information about
1610 backward and forward compatibility is a bug, and we greatly appreciate
1611 your reports, whether you can provide a patch or not.
1612
1613 A change is reported as @dfn{changed} when we believe that the new or
1614 changed API will cause old code to malfunction. When old code is
1615 believed to be upward compatible with the changed API, the change is
1616 reported as @dfn{added}.
1617
1618 We would like to also describe compatibility with GNU Emacs, but this is
1619 not so high a priority. Inaccuracies or omissions will be addressed at
1620 the priority of a feature request, and as such processing will be
1621 greatly expedited if you can provide a patch.
1622 @c #### xref here to bug reporting and patch submissions
1623
1624 @c #### write and xref a file on compatibility policy
1625
1626 @subsection Compatibility with GNU Emacs
1627
1628 Specifiers are not used in GNU Emacs. If your program depends on
1629 specifers, you will probably have to rewrite the functionality
1630 completely for GNU Emacs. If you wish to maximize portability, you
1631 should plan to encapsulate use of specifiers.
1632
1633 GNU Emacs provides two features for context-sensitive variables,
1634 buffer-local variables and frame-local variables. XEmacs implements
1635 buffer-local variables 100%-compatibly with GNU Emacs. If buffer-local
1636 variables will server your purpose and portability is a major concern,
1637 consider using them instead of specifiers.
1638
1639 XEmacs does not implement frame-local variables at all. In this case
1640 specifiers must be used to provide equivalent functionality.
1641
1642 It is not clear whether XEmacs will provide this feature in the future.
1643 @c Thanks to Jerry James for the following explanation. He is not
1644 @c responsible for its use here, Stephen Turnbull is.
1645 In fact, some core XEmacs developers think that both frame-local
1646 variables and buffer-local variables are evil, because the declaration
1647 is both global and invisible. That is, you cannot tell whether a
1648 variable is ``normal,'' buffer-local, or frame-local just by looking at
1649 it. So if you have namespace management problems, and some other Lisp
1650 package happens to use a variable name that you already declared frame-
1651 or buffer-local, weird stuff happens, and it is extremely hard to track
1652 down.
1653 @c #### Direct comments to xemacs-design?
1654
1655 @subsection Backwards Compatibility with XEmacs 21.4
1656
1657 Sorry, I'm unwilling to find out exactly when these changes were made.
1658
1659 Changed by 21.5.16: the second argument of
1660 @code{specifier-matching-instance} is now a cons of a charset and a
1661 boolean value. Previously it was a charset or a symbol (a name of a
1662 charset). It was not documented in Info.
1663
1664 Changed by 21.5.16: the specifier-specific error symbols
1665 @code{specifier_syntax_error}, @code{specifier_argument_error}, and
1666 @code{specifier_change_error} were removed. (This probably only
1667 affected internal code.)
1668
1669 Added by 21.5.16: @code{map-specifier} got two new arguments,
1670 @code{ms-tag-set} and @code{ms-exact-p}.
1671
1672 Added by 21.5.16: when skipping instantiators, XEmacs warns at level
1673 `debug'.
1674
1675 Added by 21.5.16: new convenience APIs:
1676 @code{instance-to-instantiator},
1677 @code{device-type-matches-spec},
1678 @code{add-tag-to-inst-list},
1679 @code{derive-domain-from-locale},
1680 @code{derive-device-type-from-tag-set},
1681 @code{derive-device-type-from-locale-and-tag-set}, and
1682 @code{derive-specifier-specs-from-locale}.