[COMMIT] Update some documentation, comments;
add some entries to etc/NEWS
Aidan Kehoe
kehoea
Sat Nov 11 11:09:34 EST 2006
Ar an t-ocht? l? de m? na Samhain, scr?obh Ilya N. Golubev:
> Your `objects.c' revision 1.32 of 2006/11/05 22:31:45 +0 changed the
> allowed MATCHSPEC values when instancing fonts. Still
> `specifier-matching-instance' docstring describes old MATCHSPEC
> format. (Let alone any `NEWS' entry.) Please fix.
Fixed, thank you for the bug report.
> Never checked whether this is the only item that depends on that
> executable code change.
APPROVE COMMIT
NOTE: This patch has been committed.
etc/ChangeLog addition:
2006-11-11 Aidan Kehoe <kehoea at parhasard.net>
* NEWS:
Add information on set-charset-registries, and the change to
define-specifier-tag.
man/ChangeLog addition:
2006-11-11 Aidan Kehoe <kehoea at parhasard.net>
* lispref/faces.texi (Face Convenience Functions):
Add information on how to specify a face's font for a given Mule
charset.
* lispref/specifiers.texi (Specifiers):
* lispref/specifiers.texi (Simple Specifier Usage):
* lispref/specifiers.texi (Specifiers In-Depth):
* lispref/specifiers.texi (Specifier Tag Functions):
* lispref/specifiers.texi (Specifier Instantiation Functions):
Update the documentation of specifiers to reflect the new support
for Mule character sets and associating tags with them.
src/ChangeLog addition:
2006-11-11 Aidan Kehoe <kehoea at parhasard.net>
* specifier.c:
Update the specifier-matching-instance documentation to reflect
the new format of font-specifier MATCHSPECs.
XEmacs Trunk source patch:
Diff command: cvs -q diff -Nu
Files affected: src/specifier.c
===================================================================
RCS man/lispref/specifiers.texi
===================================================================
RCS man/lispref/faces.texi
===================================================================
RCS etc/NEWS
===================================================================
RCS
Index: etc/NEWS
===================================================================
RCS file: /pack/xemacscvs/XEmacs/xemacs/etc/NEWS,v
retrieving revision 1.76
diff -u -u -r1.76 NEWS
--- etc/NEWS 2005/07/17 20:08:40 1.76
+++ etc/NEWS 2006/11/11 15:40:46
@@ -67,6 +67,19 @@
type of mapping between characters and keysyms that it affected is no longer
in place.
+** The set-charset-registry function is deprecated.
+
+set-charset-registries replaces it; this function takes a vector of X11
+CHARSET_REGISTRY and CHARSET_ENCODINGs, and doesn't support regexp or XLFD
+wildcarding. It improves lookup performance (especially failures) for those
+X servers with large numbers of fonts.
+
+** define-specifier-tag now has an optional CHARSET-PREDICATE parameter.
+
+This allows you to create specifier tags that match over Mule character sets
+when instantiating fonts, finally making it possible to explicitly set a
+font for a charset in given face with set-face-font.
+
* Changes in XEmacs 21.4
========================
Index: man/lispref/faces.texi
===================================================================
RCS file: /pack/xemacscvs/XEmacs/xemacs/man/lispref/faces.texi,v
retrieving revision 1.7
diff -u -u -r1.7 faces.texi
--- man/lispref/faces.texi 2005/07/20 07:36:44 1.7
+++ man/lispref/faces.texi 2006/11/11 15:40:56
@@ -404,6 +404,11 @@
This function sets the font of face @var{face}. The argument @var{font}
should be a string or a font object as returned by @code{make-font}
(@pxref{Fonts}).
+
+If you want to set a face's font for a given Mule character set, you
+need to include some tags in @var{tag-set} that match that character
+set. See the documentation of @code{define-specifier-tag} and its
+ at code{charset-predicate} argument.
@end deffn
@deffn Command set-face-underline-p face underline-p &optional locale tag-set how-to-add
@@ -453,8 +458,10 @@
@var{face}.
@end defun
- at defun face-font-instance face &optional domain
-This function returns the font specifier of face @var{face}.
+ at defun face-font-instance face &optional domain charset
+This function returns the font specifier of face @var{face} in domain
+ at var{domain} (defaulting to the selected device) with Mule charset
+ at var{charset} (defaulting to ASCII).
@xref{Fonts}.
@end defun
Index: man/lispref/specifiers.texi
===================================================================
RCS file: /pack/xemacscvs/XEmacs/xemacs/man/lispref/specifiers.texi,v
retrieving revision 1.15
diff -u -u -r1.15 specifiers.texi
--- man/lispref/specifiers.texi 2005/09/26 08:41:57 1.15
+++ man/lispref/specifiers.texi 2006/11/11 15:41:06
@@ -10,9 +10,9 @@
A specifier is an object used to keep track of a property whose value
should vary according to @emph{display context}, a window, a frame, or
-device. The value of many built-in properties, such as the font,
-foreground, background, and such properties of a face and variables
-such as @code{modeline-shadow-thickness} and
+device, or a Mule character set. The value of many built-in properties,
+such as the font, foreground, background, and such properties of a face
+and variables such as @code{modeline-shadow-thickness} and
@code{top-toolbar-height}, is actually a specifier object. The
specifier object, in turn, is ``instantiated'' in a particular situation
to yield the real value of the property in the current context.
@@ -213,7 +213,7 @@
@end example
In this case, @code{specifier-instance} returns an opaque object;
-programs can't work on it, they can only pass it around. Worse, in some
+Lisp programs can't work on it, they can only pass it around. Worse, in some
environments the instantiation will fail, resulting in a different value
(when another instantiation succeeds), or worse yet, an error, if all
attempts to instantiate the specifier fail. @code{specifier-instance} is
@@ -361,29 +361,54 @@
the type of specifier). In a given specification, there may be more
than one inst-pair with the same tag set; this is unlike for locales.
-The tag set is used to restrict the sorts of devices over which the
-instantiator is valid and to uniquely identify instantiators added by a
-particular application, so that different applications can work on the
-same specifier and not interfere with each other. Each tag can have a
- at dfn{predicate} associated with it, which is a function of one argument
-(a device) that specifies whether the tag matches that particular
-device. (If a tag does not have a predicate, it matches all devices.)
-All tags in a tag set must match a device for the associated inst-pair
-to be instantiable over that device. (A null tag set is perfectly
-valid, and trivially matches all devices.)
-
-The valid device types (normally @code{x}, @code{tty}, @code{stream},
- at code{mswindows}, @code{msprinter}, and possibly @code{carbon}) and
-device classes (normally @code{color}, @code{grayscale}, and
- at code{mono}) can always be used as tags, and match devices of the
-associated type or class (@pxref{Consoles and Devices}). User-defined
-tags may be defined, with an optional predicate specified. An
-application can create its own tag, use it to mark all its
-instantiators, and be fairly confident that it will not interfere with
-other applications that modify the same specifier---Functions that add
-a specification to a specifier usually only overwrite existing
-inst-pairs with the same tag set as was given, and a particular tag or
-tag set can be specified when removing instantiators.
+The tag set is used to restrict the sorts of devices and character sets
+over which the instantiator is valid and to uniquely identify
+instantiators added by a particular application, so that different
+applications can work on the same specifier and not interfere with each
+other.
+
+Each tag can have a @dfn{device-predicate} associated with it, which is
+a function of one argument (a device) that specifies whether the tag
+matches that particular device. (If a tag does not have a predicate, it
+matches all devices.) All tags in a tag set must match a device for the
+associated inst-pair to be instantiable over that device. (A null tag
+set is perfectly valid, and trivially matches all devices.)
+
+Each tag can also have a @dfn{charset-predicate} associated with it;
+this is a function that takes one charset argument, and specifies
+whether that tag matches that particular charset. When instantiating a
+face over a given domain with a given charset, the
+ at code{charset-predicate} attribute of a tag is consulted at footnote{Not
+quite the case; the result of the functions are pre-calculated and
+cached whenever @code{define-specifier-tag} or @code{make-charset} is
+called.} to decide whether this inst-pair matches the charset. If the
+ at code{charset-predicate} function of a tag is unspecified, that tag
+defaults to matching all charsets.
+
+When @code{charset-predicate}s are being taken into account, the
+matching process becomes two-stage. The first stage pays attention to
+the charset predicates and the device predicates; only if there is no
+match does the second stage take place, in which charset predicates are
+ignored, and only the device predicates are relevant.
+
+The valid device types in a build (normally @code{x}, @code{tty},
+ at code{stream}, @code{mswindows}, @code{msprinter}, and possibly
+ at code{carbon}) and device classes (normally @code{color},
+ at code{grayscale}, and @code{mono}) can always be used as tags, and match
+devices of the associated type or class (@pxref{Consoles and Devices}).
+There are also built-in tags related to font instantiation and
+translation to Unicode; they are identical to the symbols used with
+ at code{specifier-matching-instance}, see the documentation of that
+function for their names.
+
+User-defined tags may be defined, with optional device and charset
+predicates specified. An application can create its own tag, use it to
+mark all its instantiators, and be fairly confident that it will not
+interfere with other applications that modify the same
+specifier---functions that add a specification to a specifier usually
+only overwrite existing inst-pairs with the same tag set as was given,
+and a particular tag or tag set can be specified when removing
+instantiators.
When a specifier is instantiated in a domain, both the locale and the tag
set can be viewed as specifying necessary conditions that must apply in
@@ -1141,16 +1166,24 @@
opposed to a list) because the order of the tags or the number of times
a particular tag occurs does not matter.
-Each tag has a predicate associated with it, which specifies whether
+Each tag has a device predicate associated with it, which specifies whether
that tag applies to a particular device. The tags which are device
types and classes match devices of that type or class. User-defined
-tags can have any predicate, or none (meaning that all devices match).
+tags can have any device predicate, or none (meaning that all devices match).
When attempting to instantiate a specifier, a particular instantiator is
only considered if the device of the domain being instantiated over matches
all tags in the tag set attached to that instantiator.
+Each tag can also have a charset predicate, specifying whether that tag
+applies to a particular charset. There are a few tags with predefined
+charset predicates created to allow sensible fallbacks in the face
+code---see the output of @code{(specifier-fallback (face-font
+'default))} for these.
+
Most of the time, a tag set is not specified, and the instantiator gets
-a null tag set, which matches all devices.
+a null tag set, which matches all devices and all character sets (when
+possible; fonts with an inappropriate repertoire will not match, for
+example).
@defun valid-specifier-tag-p tag
This function returns non- at code{nil} if @var{tag} is a valid specifier
@@ -1175,11 +1208,15 @@
the tag set.
@end defun
- at defun define-specifier-tag tag &optional predicate
-This function defines a new specifier tag. If @var{predicate} is
+ at defun define-specifier-tag tag &optional device-predicate charset-predicate
+This function defines a new specifier tag. If @var{device-predicate} is
specified, it should be a function of one argument (a device) that
specifies whether the tag matches that particular device. If
- at var{predicate} is omitted, the tag matches all devices.
+ at var{device-predicate} is omitted, the tag matches all devices.
+
+If @var{charset-predicate} is specified, it should be a function taking
+one character set argument that specifies whether the tag matches that
+particular character set.
You can redefine an existing user-defined specifier tag. However, you
cannot redefine the built-in specifier tags (the device types and
@@ -1196,9 +1233,13 @@
This function returns a list of all currently-defined specifier tags.
This includes the built-in ones (the device types and classes).
@end defun
+
+ at defun specifier-tag-device-predicate tag
+This function returns the device predicate for the given specifier tag.
+ at end defun
- at defun specifier-tag-predicate tag
-This function returns the predicate for the given specifier tag.
+ at defun specifier-tag-charset-predicate tag
+This function returns the charset predicate for the given specifier tag.
@end defun
@node Specifier Instantiation Functions
@@ -1280,13 +1321,29 @@
implemented.)
@item
For font specifiers, @var{matchspec} should be a list (@var{charset}
-. @var{second-stage-p}), and the specification (a font string) must have
-a registry that matches the charset's registry. (This only makes sense
-with Mule support.) This makes it easy to choose a font that can
-display a particular character. (This is what redisplay does, in fact.)
- at var{second-stage-p} means to ignore the font's registry and instead
-look at the characters in the font to see if the font can support the
-charset. This currently only makes sense under MS Windows.
+. @var{stage}). On X11 the specification (a font string) should, for
+clarity, have a registry that matches the charset's registry, but the
+redisplay code will specify the XLFD CHARSET_REGISTRY and
+CHARSET_ENCODING fields itself. This makes minimal sense without Mule
+support. @var{stage} can be one of the symbols @code{'initial} and
+ at code{'final}; on X11, @code{'initial} means ``search for fonts using
+the charset registry of this charset'' and @code{'final} means ``search
+for fonts using `iso10646-1' as their charset registries, with the
+expectation that characters will be translated to Unicode at
+redisplay.'' Their meanings are similar on MS Windows, with the
+difference that the actual repertoire of the font is checked when
+deciding if a matchspec with @code{'final} matches.
+
+For example, the following code emulates what redisplay does when
+deciding what font to use for ethiopic with the default face (ignoring,
+for the moment, fallbacks):
+ at example
+(or
+ (specifier-matching-instance (face-font 'default)
+ (cons 'ethiopic 'initial))
+ (specifier-matching-instance (face-font 'default)
+ (cons 'ethiopic 'final)))
+ at end example
@end itemize
@end defun
Index: src/specifier.c
===================================================================
RCS file: /pack/xemacscvs/XEmacs/xemacs/src/specifier.c,v
retrieving revision 1.48
diff -u -u -r1.48 specifier.c
--- src/specifier.c 2006/11/11 09:50:34 1.48
+++ src/specifier.c 2006/11/11 15:41:18
@@ -3241,14 +3241,21 @@
display table is not there. (Chartable specifiers are not yet
implemented.)
--- For font specifiers, MATCHSPEC should be a list (CHARSET . SECOND-STAGE-P),
- and the specification (a font string) must have a registry that matches
- the charset's registry. (This only makes sense with Mule support.) This
- makes it easy to choose a font that can display a particular
- character. (This is what redisplay does, in fact.) SECOND-STAGE-P means
- to ignore the font's registry and instead look at the characters in the
- font to see if the font can support the charset. This currently only makes
- sense under MS Windows.
+-- For font specifiers, MATCHSPEC should be a cons (CHARSET . STAGE).
+ The defined stages are currently `initial' and `final'. On X11, 'initial
+ is used when the font matching process is looking for fonts that match
+ the desired registries of the charset--see the `charset-registries'
+ function. If that match process fails, then the 'final stage comes into
+ play; this means that a more general lookup is desired, and that a font
+ doesn't necessarily have to match the desired XLFD for the face, just the
+ charset repertoire for this charset. It also means that the charset
+ registry and encoding used will be `iso10646-1', and the characters will
+ be converted to display using that registry.
+
+ See `define-specifier-tag' for details on how to create a tag that
+ specifies a given character set and stage combination. You can supply
+ such a tag to `set-face-font' in order to set a face's font for that
+ character set and stage combination.
*/
(specifier, matchspec, domain, default_, no_fallback))
{
--
Santa Maradona, priez pour moi!
More information about the XEmacs-Beta
mailing list
