# HG changeset patch # User stephent # Date 1147150830 0 # Node ID f5d8dba84d4f0d0ee8a352cdc74b4d9ec22de919 # Parent b41588b239f8c853a0af45057cf528ad912bd93c [xemacs-hg @ 2006-05-09 05:00:26 by stephent] Xft customization docs, first cut. <87slnjn69l.fsf@tleepslib.sk.tsukuba.ac.jp> diff -r b41588b239f8 -r f5d8dba84d4f man/ChangeLog --- a/man/ChangeLog Mon May 08 21:51:38 2006 +0000 +++ b/man/ChangeLog Tue May 09 05:00:30 2006 +0000 @@ -1,3 +1,9 @@ +2006-05-09 Stephen J. Turnbull + + * xemacs/custom.texi (Xft Font Customization): New node. + (Faces): Create menu, add new node. + * xemacs/xemacs.texi (Top): add new node to detail menu. + 2006-04-29 Aidan Kehoe * lispref/objects.texi (Character Type): diff -r b41588b239f8 -r f5d8dba84d4f man/xemacs/custom.texi --- a/man/xemacs/custom.texi Mon May 08 21:51:38 2006 +0000 +++ b/man/xemacs/custom.texi Tue May 09 05:00:30 2006 +0000 @@ -1,4 +1,6 @@ +@c FIXME -- we demand a detail menu! + @node Customization, Quitting, Emulation, Top @chapter Customization @cindex customization @@ -2034,6 +2036,14 @@ The display attributes of faces may be specified either in Lisp or through the X resource manager. +Basic Xft support has been merged into the mainline, and it looks pretty +good. However, customization UI and documentation still leaves a lot to +be desired. Here's a first cut, as a separate node. + +@menu +* Xft Font Customization:: +@end menu + @subsection Customizing Faces You can change the face of an extent with the functions in @@ -2215,6 +2225,406 @@ @var{frame} argument is provided, the face is changed only in that frame; otherwise, it is changed in all frames. + +@node Xft Font Customization, , , Faces +@section Xft Font Customization + +This section was written by @email{stephen@@xemacs.org,Stephen Turnbull}, +and is very much a work in progress. I've tried to provide pointers to +as much of the relevant information as possible, but many of the APIs +and UIs are in flux, so it seemed more work than it was worth to +completely translate the tables of constants, and so on. Feel free to +ask for clarifications, @emph{etc.} Please Cc +@email{xemacs-beta@@xemacs.org,the XEmacs Beta Testers' mailing list}, +as that is the issue tracking channel of record, and there are a few +others who can answer the questions or improve documentation when I'm +not able to respond quickly. + +@c Don't blame Ben (or Eric and Matthias, for that matter). Feel free to +@c add, edit, and share the blame, everybody! + +@c #### Make these @urlref's!! +As of mid-2005, we have added support for the +@file{Xft} library, which provides a more robust @emph{font +configuration} mechanism via Keith Packard's @file{fontconfig} library; +improved glyph rendering, including antialiasing, via the +@file{freetype} library; and client-side rendering (saving bandwidth and +server memory) via the @file{XRender extension}. + +@c #### Describe Alexey Gladkov and Yury Konovalov's work. + +@subheading Font configuration + +In XEmacs, font configuration is handled via @emph{faces}. Currently +XEmacs uses a special type of @emph{font specifier} to map XEmacs +locales to font names. Especially under X11, this can cause annoying +problems because of the unreliability of X servers' mappings from +@samp{XLFD} names to X11 fonts, over which XEmacs has no influence +whatsoever. However, the @file{fontconfig} library which is used with +@file{Xft} provides much more reliable mapping, along with a more +reliably parsable naming scheme similar to that used by TrueType fonts +on MS Windows and the Macintosh. + +@subheading fontconfig + +Fontconfig is dramatically different from the X model in several ways. +In particular, when queried for a font @emph{fontconfig always returns a +font}, whereas X queries may return ``not found.'' However, the font +returned need not be anything like the desired font. This is not really +a problem in practice, because users generally have a pretty good idea +of what fonts are available on their display. However, users should be +aware that as of XEmacs 21.5.26 the font selection internals have not +been revised to account for this radically different model, so some +surprising results are possible. + +From the user's point of view, @file{fontconfig} provides a naming +convention which is @emph{precise}, @emph{accurate}, and +@emph{convenient}. Precision means that all properties available in the +programming API can be individually specified. Accuracy means that the +truename of the font is exactly the list of all properties specified by +the font. Thus, the anomolies that occur with XLFDs on many servers +(including modern Linux distributions with XFree86 or X.org servers) +cannot occur. Convenience is subjective, of course. However, +@file{fontconfig} provides a configuration system which (1) explicitly +specifies the defaults and substitutions that will be made in processing +user queries, (2) allows the user to specify search configuration, +abbreviations, substitutions, and defaults that override the system's, +in the same format as used by system files, and (3) allows flexible +aliases that can resolve to any of several actual fonts depending on +which fonts are installed. + +Further, a @dfn{standard minimal configuration} is defined that ensures +that at least the @emph{serif}, @emph{sans-serif}, and @emph{monospace} +font aliases are available on all @file{fontconfig} systems. + +@subheading fontconfig font names + +@file{fontconfig} font names are very regular, and constitute a precise +and extensible specification of a font's properties. + +The basic @file{fontconfig} font name has three components: the font +family name, the size, and a list of named attribute fields. All +attribute names and values are strings encoded in Unicode UTF-8, or +decimal numbers with optional decimal point and fraction. The +characters @samp{-}, @samp{:}, @samp{,}, @samp{=}, and @samp{\} are +syntactically significant to @file{fontconfig}. They may be used in +font name components by the familiar mechanism of backslash escaping. +This simply removes any special meaning from the following character. +It is always safe to use an escape even if it is not needed. + +Most string values are case-insensitive, but this is attribute-specific. + +The @dfn{font family name} is an arbitrary string, which may contain any +character, including spaces, hyphens, and commas. Don't forget to +escape hyphens, colons, commas, and backslashes! + +The @dfn{size} is a decimal number with optional decimal point and +fractional part. It is interpreted as point size. + +A @dfn{named attribute field} is a key-value pair separated by an equal +sign. Some attributes have predefined semantics. (These include such +familiar attributes as @samp{slant} and @samp{dpi} -- note that +@file{fontconfig} does not distinguish between vertical and horizontal +resolution! + +The basic syntax of a font name is simple and regular. The @emph{font +family name} comes first, followed by a hyphen and the @emph{size}, +followed by a list of @emph{named attribute fields}, each introduced by +a colon: + +@example +@var{font family name}-@var{size}:@var{key1}=@var{value1}:@var{key2}=@var{value2}... +@end example + +There are four extensions to the basic syntax. First, all of the +fields are optional. If size is omitted, the hyphen should be omitted +as well. There should never be a trailing colon. Note that +@file{fontconfig} does @emph{not} interpret an omitted field as +``default to current.'' @file{fontconfig} does not have access to that +context. Instead, omitted fields are filled in according to a set of +defaults specified in the system @file{fonts.conf} file and in the +user's @file{.fonts.cont} file. The user's configuration gets +precedence, of course. + +The second is that the @emph{font family name}, the @emph{size}, and the +@emph{value} component of a @emph{named attribute field} may be a +comma-separated list of values. This is called a @dfn{pattern}. In +queries, @file{fontconfig} tries to match each entry in the list in +order. (I suspect that order of attributes is also significant. +@emph{I.e.}, font family always gets highest precedence, followed by +size, followed by the remaining named attributes. Testing and reports +to the @email{xemacs-beta@@xemacs.org,XEmacs Beta Testers mailing list} +are very welcome!) + +The third is the definition of @dfn{constants} to represent numerical +values. For example, both @samp{slant} and @samp{weight} are defined as +integer attributes, but the magnitudes are arbitrary; only the ordering +and relative distances are useful. (``Relative distance'' is used to +implement the concept that although strictly speaking @emph{italic} and +@emph{oblique} are different faces, most users don't know the +difference, and even professional typographers would agree that they are +much closer to each other than either is to @emph{roman}.) So +@emph{constants} like @samp{roman} (0) and @samp{italic} (100) are +defined for @samp{slant}, and @samp{medium} (100) and @samp{bold} (200) +are defined for @samp{weight}. + +The fourth is that a @dfn{style} may be defined as an alias for an +instance of a @emph{named attribute field}, that is, specifying both key +and value. The @emph{styles} @samp{bold}, an alias for +@samp{weight=200}, and @samp{italic}, an alias for @samp{slant=100}, are +commonly used. + +Styles and constants can be defined by the application. XEmacs +currently defines none, but suggestions are welcome if some convenient +alias is lacking from @file{fontconfig}. Note that we will not provide +additional aliases where standard ones exist, @emph{e.g.}, @samp{heavy} +as an additional alias for @samp{bold} would almost certainly be +rejected. These cause more confusion than they are worth, and would +decrease portability of user specifications to other applications. + +(Attributes can also be defined, but they must be implemented by the +fonts to be useful. Until XEmacs provides its own fonts with +non-standardized attributes, this is not useful.) + +Here are some examples of font names and query patterns: + +@example +Times-12 12-point Times Roman +Times-12:bold 12-point Times Bold +Courier:italic Courier Italic in the default size +Monospace:matrix=1 .1 0 1 The user's preferred monospace font + with artificial obliquing +Mikachan\-PB-16 16-point Mikachan-PB +LucidaTypewriter,Courier-9 9-point LucidaTypewriter if available, + otherwise 9-point Courier +@end example + +Note how @emph{styles} are used in the second and third examples, how +@samp{matrix} has a complex value containing spaces, and the +escaped hyphen in the font family name @samp{Mikachan\-PB}. + +@c #### FIXME here and also in fontconfig.texi (in general-docs package). +Here is a (somewhat outdated) list of current standard named attributes: + +@example +Property CPP symbol Type Description + +family FC_FAMILY String Font family name +style FC_STYLE String Font style. Overrides weight and slant +slant FC_SLANT Int Italic, oblique or roman +weight FC_WEIGHT Int Light, medium, demibold, bold or black +size FC_SIZE Double Point size +aspect FC_ASPECT Double Stretch glyphs horizontally, then hint +pixelsize FC_PIXEL_SIZE Double Pixel size +spacing FC_SPACING Int Proportional, monospace or charcell +foundry FC_FOUNDRY String Font foundry name +antialias FC_ANTIALIAS Bool Should glyphs be antialiased? +hinting FC_HINTING Bool Should the rasterizer use hinting? +verticallayout FC_VERTICAL_LAYOUT Bool Use vertical layout +autohint FC_AUTOHINT Bool Use autohinter instead of normal hinter +globaladvance FC_GLOBAL_ADVANCE Bool Use font global advance data +file FC_FILE String The filename holding the font +index FC_INDEX Int The index of the font within the file +ftface FC_FT_FACE FT_Face Use the specified FreeType face object +rasterizer FC_RASTERIZER String Which rasterizer is in use +outline FC_OUTLINE Bool Whether the glyphs are outlines +scalable FC_SCALABLE Bool Whether glyphs can be scaled +scale FC_SCALE Double Point->pixel conversion scale factor +dpi FC_DPI Double Target dots per inch +rgba FC_RGBA Int unknown, rgb, bgr, vrgb, vbgr, none + - subpixel geometry +source FC_SOURCE String X11, freetype +minspace FC_MINSPACE Bool Eliminate leading from line spacing +charset FC_CHARSET CharSet Unicode chars encoded by the font +lang FC_LANG String List of RFC-3066-style languages + this font supports +fontversion FC_FONTVERSION Int From 'head' table +@end example + +Here is a list of current standard constants: + +@example +Constant Property CPP symbol + +light weight FC_WEIGHT_LIGHT +medium weight FC_WEIGHT_MEDIUM +demibold weight FC_WEIGHT_DEMIBOLD +bold weight FC_WEIGHT_BOLD +black weight FC_WEIGHT_BLACK +roman slant FC_SLANT_ROMAN +italic slant FC_SLANT_ITALIC +oblique slant FC_SLANT_OBLIQUE +proportional spacing FC_PROPORTIONAL +mono spacing FC_MONO +charcell spacing FC_CHARCELL +unknown rgba FC_RGBA_UNKNOWN +rgb rgba FC_RGBA_RGB +bgr rgba FC_RGBA_BGR +vrgb rgba FC_RGBA_VRGB +vbgr rgba FC_RGBA_VBGR +none rgba FC_RGBA_NONE +@end example + +Note that this is the @file{fontconfig} API list; you can expect that +XEmacs will define corresponding keywords by substituting @samp{:} for +the leading @samp{FC_}, @samp{-} for @samp{_}, removing the key of the +attribute if present, and lowercasing the name. Thus +@samp{FC_WEIGHT_BOLD} becomes @samp{:bold}. +@kbd{M-x apropos RET fc-.*-mapping} will give a list of variables each +of which lists such keywords and their meanings. + +@subheading Font menus + +The @samp{Options->Font} and @samp{Options->Font Sizes} menus are +broken, by design, not just by @file{Xft}. The problem is that many +fonts are unavailable because they don't match the current size---which +is very strange, since @file{Xft} fonts are of course scalable. But the +whole idea of requiring that the font match the size is strange. And +the @samp{Options->Font Weights} menu is just disabled, and has been for +eons. + +@subheading X resources + +Currently there are @emph{four} treatments of font resources. There are +the @samp{XEmacs.@var{face}.attributeFont} resources used to set a +single global font specification. In the widgets, some (still) have a +@samp{font} resource using the automatic @file{Xt} resource conversion +to X's @samp{FontStruct}, some have separate @samp{font} and @samp{xftFont} +resources with the former automatically converted to @samp{FontStruct} +by @file{Xt} and the latter left as a string, to be converted to a +fontconfig @samp{FcPattern} by +@samp{FcParseName} later, and some have a single @samp{font} resource +which is converted to @samp{FontStruct} by @file{Xt} or the latter left +as a string, depending on whether @file{Xft} was enabled by +@samp{configure} or not. + +Eventually these should be converted to use the face +approach, perhaps with some way to set specifications for individual +widgets, frames, or buffers. This will require some careful design work +to incorporate face support in the widgets. Stephen's current thinking +is that XEmacs should just accept any +or all of @samp{font}, @samp{fontSet}, and @samp{fontList} resources, +treat them all as lists of font names, either @samp{XLFD}- or +@file{fontconfig}-style, parse them ourselves (ie, not use the @file{Xt} +resource manager), and add them to font specifiers as appropriate. But +this will require a bit of thought to obey POLA vis-a-vis usual @file{Xt} +conventions. + +@subheading Specifiers, charsets, and languages + +Traditionally Mule uses a rather rigid and low-level abstraction, the +@emph{charset}, to characterize font repertoires. Unfortunately, +support for a given charset is generally neither necessary nor +sufficient to support a language. Worse, in XEmacs's current +implementation Xft doesn't help much. Instead you need to add the fonts +for different charsets to the font specifier in the right order. + +There currently is no explicit way to specify that a particular font be +used only for a given language. However, since many fonts support only +a limited repertoire such as ISO 8859/1, you can use the precedence of +specifications for a given specifier locale to get something of this +effect for non-Latin character sets. This will normally work rather +poorly for multiple Latin character sets, however, because the +repertoires tend to have large amounts of overlap. Support for +specifying font by @emph{language} as well as by character set is +planned. + +Because fonts supporting other languages tend to support English as +well, if you want to use one font for English and another for the other +language, you must use the @code{append} method when adding font +specifications for the @emph{other} language. + +However, this simple method leaves you with a problem if you want to +change the other language's font: you have to remove the existing +specification so it won't shadow the new one when you append. + +In order to provide a convenient way to change ``other-language fonts'', +I use @code{remove-tag-set-append} and @code{define-specifier-tag} like +this: + +@example +(define-specifier-tag 'lang-ja) +;; No, I don't try to do real work with this font! But it makes it +;; obvious that I got the requested font. :-) +(set-face-font 'default "AirCut-14") +(set-face-font 'default "Kochi Mincho-14" nil '(lang-ja) 'append) +;; Oops, too sober. Try something to match AirCut. +(set-face-font 'default "Mikachan-14" + nil '(lang-ja) 'remove-tag-set-append) +@end example + +The only way to configure widget fonts at the present time is to use X +resources (or hack the source and rebuild). Currently supported widgets +are +@itemize +@item +menubars +@item +tab controls +@end itemize + +Here are the resources I use. @strong{Warning:} @emph{This interface +will change. Pay attention to beta announcements, and complain loudly +if changes aren't documented here!} The tab control and menubar have +separate Font and XftFont resources, and use the X resource manager to +instantiate a FontStruct from the Font resource. There is no converter +facility for XftFont yet, and creating one that handles both FontStruct +and XftFont depending on XEmacs's configuration and the font name seems +error-prone at best. Probably we will use a simple string +representation for this resource, and convert to a face in XEmacs rather +than a font in Xt/Xft. +@example +XEmacs*Tabs.xftFont: Bitstream Vera Sans-16 +XEmacs*menubar*xftFont: Bitstream Vera Sans-16 +XEmacs.modeline.attributeFont: Bitstream Charter-16 +XEmacs.default.attributeFont: Bitstream Vera Sans Mono-16 +@end example +I highly recommend use of a proportional font in the modeline because it +allows a lot more text to fit there. +@c Previously the font sizes were quite varied, and there was a comment +@c that this weirdness gave good balance. This isn't true on my main +@c platform, Mac OS X, and needs to be rechecked on Linux, where it was +@c observed. + +@subheading Known Problems + +@table @code +@item Options->Font +@itemx Options->Font Size +These menus don't work. All fonts are greyed out. All sizes are +available, but many (most?) faces don't change size, in particular, +@samp{default} does not. + +@item Antialiased text bleeding outside of reported extent +This is most obvious with the underscore character in that +font, and with cursors. The bottom of the underscore is antialiased, +and insertions or deletions in the same line before the underscore leave +a series of "phantom" underlines. + +I think this is probably an Xft bug, but I'm not sure. +@end table + +@subheading Variables Used with Xft and Fontconfig + +@defvar xft-debug-level + +Level of debugging messages to issue to stderr for @var{Xft}. +A nonnegative integer. Set to 0 to suppress all warnings. +Default is 1 to ensure a minimum of debugging output at initialization. +Higher levels give more information. +@end defvar + +@defvar xft-version + +The major version number of the Xft library compiled with. +@end defvar + +@defvar xft-xlfd-font-regexp + +Regular expression matching XLFD font names. +@end defvar + + @node Frame Components @section Frame Components diff -r b41588b239f8 -r f5d8dba84d4f man/xemacs/xemacs.texi --- a/man/xemacs/xemacs.texi Mon May 08 21:51:38 2006 +0000 +++ b/man/xemacs/xemacs.texi Tue May 09 05:00:30 2006 +0000 @@ -605,6 +605,10 @@ * Init Examples:: How to do some things with an init file. * Terminal Init:: Each terminal type can have an init file. +Faces + +* Xft Font Customization:: Configuring the next generation of fonts. + Dealing with XEmacs Trouble * Stuck Recursive:: `[...]' in mode line around the parentheses.