diff options
Diffstat (limited to 'hw/xfree86/doc/README.fonts')
| -rw-r--r-- | hw/xfree86/doc/README.fonts | 1146 |
1 files changed, 1146 insertions, 0 deletions
diff --git a/hw/xfree86/doc/README.fonts b/hw/xfree86/doc/README.fonts new file mode 100644 index 000000000..fb1c1f5fb --- /dev/null +++ b/hw/xfree86/doc/README.fonts @@ -0,0 +1,1146 @@ + Fonts in XFree86 + + Juliusz Chroboczek, <jch@xfree86.org> + + 17 January 2003 + +1. Introduction + +This document describes the support for fonts in XFree86. Installing fonts +(section 2., page 1) is aimed at the casual user wishing to install fonts in +XFree86; the rest of the document describes the font support in more detail. + +We assume some familiarity with digital fonts. If anything is not clear to +you, please consult Appendix: Background (section 5., page 1) at the end of +this document for background information. + +1.1 Two font systems + +XFree86 includes two font systems: the core X11 fonts system, which is pre- +sent in all implementations of X11, and the Xft fonts system, which is not +currently distributed with implementations of X11 that are not based on +XFree86 but will hopefully be included by them in the future + +The core X11 fonts system is directly derived from the fonts system included +with X11R1 in 1987, which could only use monochrome bitmap fonts. Over the +years, it has been more or less happily coerced into dealing with scalable +fonts and rotated glyphs. + +Xft was designed from the start to provide good support for scalable fonts, +and do so efficiently. Unlike the core fonts system, it supports features +such as anti-aliasing and sub-pixel rasterisation. Perhaps more importantly, +it gives applications full control over the way glyphs are rendered, making +fine typesetting and WYSIWIG display possible. Finally, it allows applica- +tions to use fonts that are not installed system-wide for displaying docu- +ments with embedded fonts. + +Xft is not compatible with the core fonts system: usage of Xft requires mak- +ing fairly extensive changes to toolkits (user-interface libraries). While +XFree86 will continue to maintain the core fonts system, toolkit authors are +encouraged to switch to Xft as soon as possible. + +2. Installing fonts + +This section explains how to configure both Xft and the core fonts system to +access newly-installed fonts. + +2.1 Configuring Xft + +Xft has no configuration mechanism itself, rather it relies upon the fontcon- +fig library to configure and customize fonts. That library is not specific +to XFree86 or indeed on any particular font output mechanism. This discus- +sion describes how fontconfig, rather than Xft, works. + +2.1.1 Installing fonts in Xft + +Fontconfig looks for fonts in a set of well-known directories that include +all of XFree86's standard font directories (`/usr/X11R6/lib/X11/lib/fonts/*') +by default) as well as a directory called `.fonts/' in the user's home direc- +tory. Installing a font for use by Xft applications is as simple as copying +a font file into one of these directories. + + $ cp lucbr.ttf ~/.fonts/ + +Fontconfig will notice the new font at the next opportunity and rebuild its +list of fonts. If you want to trigger this update from the command line (for +example in order to globally update the system-wide Fontconfig information), +you may run the command `fc-cache'. + + $ fc-cache + +2.1.2 Fine-tuning Xft + +Fontconfig's behaviour is controlled by a set of configuration files: a sys- +tem-wide configuration file, `/etc/fonts/fonts.conf', and a user-specific +file called `.fonts.conf' in the user's home directory (this can be overrid- +den with the `FONTCONFIG_FILE' environment variable). + +Every Fontconfig configuration file must start with the following boiler- +plate: + + <?xml version="1.0"?> + <!DOCTYPE fontconfig SYSTEM "fonts.dtd"> + <fontconfig> + +In addition, every Fontconfig configuration file must end with the following +line: + + </fontconfig> + +The default Fontconfig configuration file includes the directory `~/.fonts/' +in the list of directories searched for font files, and this is where user- +specific font files should be installed. In the unlikely case that a new +font directory needs to be added, this can be done with the following syntax: + + <dir>/usr/local/share/fonts/</dir> + +Another useful option is the ability to disable anti-aliasing (font smooth- +ing) for selected fonts. This can be done with the following syntax: + + <match target="font"> + <test qual="any" name="family"> + <string>Lucida Console</string> + </test> + <edit name="antialias" mode="assign"> + <bool>false</bool> + </edit> + </match> + +Anti-aliasing can be disabled for all fonts by the following incantation: + + <match target="font"> + <edit name="antialias" mode="assign"> + <bool>false</bool> + </edit> + </match> + +Xft supports sub-pixel rasterisation on LCD displays. XFree86 should auto- +matically enable this feature on laptops and when using an LCD monitor con- +nected with a DVI cable; you can check whether this was done by typing + + $ xdpyinfo -ext RENDER | grep sub-pixel + +If this doesn't print anything, you will need to configure Render for your +particular LCD hardware manually; this is done with the following syntax: + + <match target="font"> + <edit name="rgba" mode="assign"> + <const>rgb</const> + </edit> + </match> + +The string `rgb' within the `<const>'...`</const>' specifies the order of +pixel components on your display, and should be changed to match your hard- +ware; it can be one of `rgb (normal LCD screen), `bgr' (backwards LCD +screen), `vrgb' (LCD screen rotated clockwise) or `vbgr' (LCD screen rotated +counterclockwise). + +2.1.3 Configuring applications + +Because most current applications use the core fonts system by default, it is +necessary to explicitly configure them to use Xft. How this is done depends +on the application. + +XTerm can be set to use Xft by using the `-fa' command line option or by set- +ting the `XTerm*faceName' resource: + + XTerm*faceName: Courier + +or + + $ xterm -fa "Courier" + +For applications based on GTK+ 2.0 (including GNOME 2 applications), the +environment variable `GDK_USE_XFT' should be set to `1': + + $ export GDK_USE_XFT=1 + +GTK+ 2.2 uses Xft by default. + +For KDE applications, you should select ``Anti-alias fonts'' in the ``Fonts'' +panel of KDE's ``Control Center''. Note that this option is misnamed: it +switches KDE to using Xft but doesn't enable anti-aliasing in case it was +disabled by your Xft configuration file. + +(What about Mozilla?) + +2.1.4 Troubleshooting + +If some Xft-based applications don't seem to notice the changes you are mak- +ing to your configuration files, they may be linked against the XFree86 4.2 +version of Xft. In order to fix the problem, you should relink them against +a current version of Xft; on most systems, it is enough to install the cur- +rent version of the Xft and Fontconfig libraries. + +If, for some reason, you cannot upgrade the shared libraries, please check +the Xft(3) manual page included with XFree86 4.2 for the configuration mecha- +nisms of the previous version of Xft. + +2.2 Configuring the core X11 fonts system + +Installing fonts in the core system is a two step process. First, you need +to create a font directory that contains all the relevant font files as well +as some index files. You then need to inform the X server of the existence +of this new directory by including it in the font path. + +2.2.1 Installing bitmap fonts + +The XFree86 server can use bitmap fonts in both the cross-platform BDF format +and the somewhat more efficient binary PCF format. (XFree86 also supports +the obsolete SNF format.) + +Bitmap fonts are normally distributed in the BDF format. Before installing +such fonts, it is desirable (but not absolutely necessary) to convert the +font files to the PCF format. This is done by using the command `bdftopcf', +e.g. + + $ bdftopcf courier12.bdf + +You will then want to compress the resulting PCF font files: + + $ gzip courier12.pcf + +After the fonts have been converted, you should copy all the font files that +you wish to make available into a arbitrary directory, say +`/usr/local/share/fonts/bitmap/'. You should then create the index file +`fonts.dir' by running the command `mkfontdir' (please see the mkfontdir(1) +manual page for more information): + + $ mkdir /usr/local/share/fonts/bitmap/ + $ cp *.pcf.gz /usr/local/share/fonts/bitmap/ + $ mkfontdir /usr/local/share/fonts/bitmap/ + +All that remains is to tell the X server about the existence of the new font +directory; see Setting the server font path (section 2.2.4, page 1) below. + +2.2.2 Installing scalable fonts + +The XFree86 server supports scalable fonts in four formats: Type 1, Speedo, +TrueType and CIDFont. This section only applies to the former three; for +information on CIDFonts, please see Installing CIDFonts (section 2.2.3, page +1) later in this document. + +Installing scalable fonts is very similar to installing bitmap fonts: you +create a directory with the font files, and run `mkfontdir' to create an +index file called `fonts.dir'. + +There is, however, a big difference: `mkfontdir' cannot automatically recog- +nise scalable font files. For that reason, you must first index all the font +files in a file called `fonts.scale'. While this can be done by hand, it is +best done by using the `mkfontscale' utility. + + $ mkfontscale /usr/local/share/fonts/Type1/ + $ mkfontdir /usr/local/share/fonts/Type1/ + +Under some circumstances, it may be necessary to modify the `fonts.scale' +file generated by mkfontscale; for more information, please see the mkfont- +dir(1) and mkfontscale(1) manual pages and Core fonts and internationalisa- +tion (section 4.1, page 1) later in this document. + +2.2.3 Installing CID-keyed fonts + +The CID-keyed font format was designed by Adobe Systems for fonts with large +character sets. A CID-keyed font, or CIDFont for short, contains a collec- +tion of glyphs indexed by character ID (CID). + +In order to map such glyphs to meaningful indices, Adobe provide a set of +CMap files. The PostScript name of a font generated from a CIDFont consists +of the name of the CIDFont and the name of the CMap separated by two dashes. +For example, the font generated from the CIDFont `Munhwa-Regular' using the +CMap `UniKS-UCS2-H' is called + + Munhwa-Regular--UniKS-UCS2-H + +The CIDFont code in XFree86 requires a very rigid directory structure. The +main directory must be called `CID' (its location defaults to +`/usr/X11R6/lib/X11/fonts/CID' but it may be located anywhere), and it should +contain a subdirectory for every CID collection. Every subdirectory must +contain subdirectories called CIDFont (containing the actual CIDFont files), +CMap (containing all the needed CMaps), AFM (containing the font metric +files) and CFM (initially empty). For example, in the case of the font +Munhwa-Regular that uses the CID collection Adobe-Korea1-0, the directory +structure should be as follows: + + CID/Adobe-Korea1/CIDFont/Munhwa-Regular + CID/Adobe-Korea1/CMap/UniKS-UCS2-H + CID/Adobe-Korea1/AFM/Munhwa-Regular.afm + CID/Adobe-Korea1/CFM/ + CID/fonts.dir + CID/fonts.scale + +After creating this directory structure and copying the relevant files, you +should create a <`tt/fonts.scale/' file. This file has the same format as in +the case of (non-CID) scalable fonts, except that its first column contains +PostScript font names with the extension `.cid' appended rather than actual +filenames: + + 1 + Adobe-Korea1/Munhwa-Regular--UniKS-UCS2-H.cid \ + -adobe-munhwa-medium-r-normal--0-0-0-0-p-0-iso10646-1 + +(both names on the same line). Running `mkfontdir' creates the `fonts.dir' +file: + + $ cd /usr/local/share/fonts/CID + $ mkfontdir + +Finally, you should create the font metrics summary files in the directory +`CFM' by running the command `mkcfm': + + $ mkcfm /usr/local/share/fonts/CID + +If no CFM files are available, the server will still be able to use the CID +fonts but querying them will take a long time. You should run `mkcfm' again +whenever a change is made to any of the CID-keyed fonts, or when the CID- +keyed fonts are copied to a machine with a different architecture. + +2.2.4 Setting the server's font path + +The list of directories where the server looks for fonts is known as the font +path. Informing the server of the existence of a new font directory consists +of putting it on the font path. + +The font path is an ordered list; if a client's request matches multiple +fonts, the first one in the font path is the one that gets used. When match- +ing fonts, the server makes two passes over the font path: during the first +pass, it searches for an exact match; during the second, it searches for +fonts suitable for scaling. + +For best results, scalable fonts should appear in the font path before the +bitmap fonts; this way, the server will prefer bitmap fonts to scalable fonts +when an exact match is possible, but will avoid scaling bitmap fonts when a +scalable font can be used. (The `:unscaled' hack, while still supported, +should no longer be necessary in XFree86 4.0 and later.) + +You may check the font path of the running server by typing the command + + $ xset q + +2.2.4.1 Temporary modification of the font path + +The `xset' utility may be used to modify the font path for the current ses- +sion. The font path is set with the command xset fp; a new element is added +to the front with xset +fp, and added to the end with xset fp+. For example, + + $ xset +fp /usr/local/fonts/Type1 + $ xset fp+ /usr/local/fonts/bitmap + +Conversely, an element may be removed from the front of the font path with +`xset -fp', and removed from the end with `xset fp-'. You may reset the font +path to its default value with `xset fp default'. + +For more information, please consult the xset(1) manual page. + +2.2.4.2 Permanent modification of the font path + +The default font path (the one used just after server startup or after `xset +fp default') is specified in the X server's `XF86Config' file. It is com- +puted by appending all the directories mentioned in the `FontPath' entries of +the `Files' section in the order in which they appear. + + FontPath "/usr/local/fonts/Type1" + ... + FontPath "/usr/local/fonts/bitmap" + +For more information, please consult the XF86Config(5) manual page. + +2.2.5 Troubleshooting + +If you seem to be unable to use some of the fonts you have installed, the +first thing to check is that the `fonts.dir' files are correct and that they +are readable by the server (the X server usually runs as root, beware of NFS- +mounted font directories). If this doesn't help, it is quite possible that +you are trying to use a font in a format that is not supported by your +server. + +XFree86 supports the BDF, PCF, SNF, Type 1, Speedo, TrueType, OpenType and +CIDFont font formats. However, not all XFree86 servers come with all the +font backends configured in. + +On most platforms, the XFree86 servers are modular: the font backends are +included in modules that are loaded at runtime. The modules to be loaded are +specified in the `XF86Config' file using the `Load' directive: + + Load "type1" + +If you have trouble installing fonts in a specific format, you may want to +check the server's log file in order to see whether the relevant modules are +properly loaded. The list of font modules distributed with XFree86 is as +follows: + + o "bitmap": bitmap fonts (`*.bdf', `*.pcf' and `*.snf'); + + o "freetype": TrueType fonts (`*.ttf' and `*.ttc'), OpenType fonts + (`*.otf' and `*.otc') and Type 1 fonts (`*.pfa' and `*.pfb'); + + o "type1": alternate Type 1 backend (`*.pfa' and `*.pfb') and CIDFont + backend; + + o "xtt": alternate TrueType backend (`*.ttf' and `*.ttc'); + + o "speedo": Bitstream Speedo fonts (`*.spd'). + +Please note that the argument of the `Load' directive is case-sensitive. + +3. Fonts included with XFree86 + +3.1 Standard bitmap fonts + +The Sample Implementation of X11 (SI) comes with a large number of bitmap +fonts, including the `fixed' family, and bitmap versions of Courier, Times, +Helvetica and some members of the Lucida family. In the SI, these fonts are +provided in the ISO 8859-1 encoding (ISO Latin Western-European). + +In XFree86, a number of these fonts are provided in Unicode-encoded font +files instead. At build time, these fonts are split into font files encoded +according to legacy encodings, a process which allows us to provide the stan- +dard fonts in a number of regional encodings with no duplication of work. + +For example, the font file + + /usr/X11R6/lib/X11/fonts/misc/6x13.bdf + +with XLFD + + -misc-fixed-medium-r-semicondensed--13-120-75-75-c-60-iso10646-1 + +is a Unicode-encoded version of the standard `fixed' font with added support +for the Latin, Greek, Cyrillic, Georgian, Armenian, IPA and other scripts +plus numerous technical symbols. It contains over 2800 glyphs, covering all +characters of ISO 8859 parts 1-5, 7-10, 13-15, as well as all European IBM +and Microsoft code pages, KOI8, WGL4, and the repertoires of many other char- +acter sets. + +This font is used at build time for generating the font files + + 6x13-ISO8859-1.bdf + 6x13-ISO8859-2.bdf + ... + 6x13-ISO8859-15.bdf + 6x13-KOI8-R.bdf + +with respective XLFDs + + -misc-fixed-medium-r-normal--13-120-75-75-c-60-iso8859-1 + ... + -misc-fixed-medium-r-normal--13-120-75-75-c-60-iso8859-15 + -misc-fixed-medium-r-normal--13-120-75-75-c-60-koi8-r + +The standard short name `fixed' is normally an alias for + + -misc-fixed-medium-r-normal--13-120-75-75-c-60-iso8859-1 + +3.2 The ClearlyU Unicode font family + +The ClearlyU family of fonts provides a set of 12 pt, 100 dpi proportional +fonts with many of the glyphs needed for Unicode text. Together, the fonts +contain approximately 7500 glyphs. + +The main ClearlyU font has the XLFD + + -mutt-clearlyu-medium-r-normal--17-120-100-100-p-101-iso10646-1 + +and resides in the font file + + /usr/X11R6/lib/X11/fonts/misc/cu12.pcf.gz + +Additional ClearlyU fonts include + + -mutt-clearlyu alternate glyphs-medium-r-normal--17-120-100-100-p-91-iso10646-1 + -mutt-clearlyu pua-medium-r-normal--17-120-100-100-p-111-iso10646-1 + -mutt-clearlyu arabic extra-medium-r-normal--17-120-100-100-p-103-fontspecific-0 + -mutt-clearlyu ligature-medium-r-normal--17-120-100-100-p-141-fontspecific-0 + +The Alternate Glyphs font contains additional glyph shapes that are needed +for certain languages. A second alternate glyph font will be provided later +for cases where a character has more than one commonly used alternate shape +(e.g. the Urdu heh). + +The PUA font contains extra glyphs that are useful for certain rendering pur- +poses. + +The Arabic Extra font contains the glyphs necessary for characters that don't +have all of their possible shapes encoded in ISO 10646. The glyphs are +roughly ordered according to the order of the characters in the ISO 10646 +standard. + +The Ligature font contains ligatures for various scripts that may be useful +for improved presentation of text. + +3.3 Standard scalable fonts + +XFree86 includes all the scalable fonts distributed with X11R6. + +3.3.1 Standard Type 1 fonts + +The IBM Courier set of fonts cover ISO 8859-1 and ISO 8859-2 as well as Adobe +Standard Encoding. These fonts have XLFD + + -adobe-courier-medium-*-*--0-0-0-0-m-0-*-* + +and reside in the font files + + /usr/X11R6/lib/X11/fonts/Type1/cour*.pfa + +The Adobe Utopia set of fonts only cover ISO 8859-1 as well as Adobe Standard +Encoding. These fonts have XLFD + + -adobe-utopia-*-*-normal--0-0-0-0-p-0-iso8859-1 + +and reside in the font files + + /usr/X11R6/lib/X11/fonts/Type1/UT*.pfa + +Finally, XFree86 also comes with Type 1 versions of Bitstream Courier and +Charter. These fonts have XLFD + + -bitstream-courier-*-*-normal--0-0-0-0-m-0-iso8859-1 + -bitstream-charter-*-*-normal--0-0-0-0-p-0-iso8859-1 + +and reside in the font files + + /usr/X11R6/lib/X11/fonts/Type1/c*bt_.pfb + +3.3.2 Standard Speedo fonts + +XFree86 includes Speedo versions of the Bitstream Courier and Charter fonts. +In order to use these fonts, you should ensure that your X server is loading +the `Speedo' font backend; see Troubleshooting (section 2.2.5, page 1). + +These fonts cover all of ISO 8859-1 and almost all of ISO 8859-2. They have +XLFD name + + -bitstream-courier-*-*-normal--0-0-0-0-m-0-*-* + -bitstream-charter-*-*-normal--0-0-0-0-p-0-*-* + +and reside in the font files + + /usr/X11R6/lib/X11/fonts/Speedo/font*.spd + +3.4 The Bigelow & Holmes Luxi family + +XFree86 includes the Luxi family of scalable fonts, in both TrueType and +Type 1 format. This family consists of the fonts Luxi Serif, with XLFD + + -b&h-luxi serif-medium-*-normal--*-*-*-*-p-*-*-* + +Luxi Sans, with XLFD + + -b&h-luxi sans-medium-*-normal--*-*-*-*-p-*-*-* + +and Luxi Mono, with XLFD + + -b&h-luxi mono-medium-*-normal--*-*-*-*-m-*-*-* + +Each of these fonts comes Roman, oblique, bold and bold oblique variants The +TrueType version have glyphs covering the basic ASCII Unicode range, the +Latin 1 range, as well as the Extended Latin range and some additional punc- +tuation characters. In particular, these fonts include all the glyphs needed +for ISO 8859 parts 1, 2, 3, 4, 9, 13 and 15, as well as all the glyphs in the +Adobe Standard encoding and the Windows 3.1 character set. + +The glyph coverage of the Type 1 versions is somewhat reduced, and only cov- +ers ISO 8859 parts 1, 2 and 15 as well as the Adobe Standard encoding. + +The Luxi fonts are original designs by Kris Holmes and Charles Bigelow. Luxi +fonts include seriffed, sans serif, and monospaced styles, in roman and +oblique, and normal and bold weights. The fonts share stem weight, x-height, +capital height, ascent and descent, for graphical harmony. + +The character width metrics of Luxi roman and bold fonts match those of core +fonts bundled with popular operating and window systems. + +The license terms for the Luxi fonts are included in the file `COPYRIGHT.BH', +as well as in the License document. + +Charles Bigelow and Kris Holmes from Bigelow and Holmes Inc. developed the +Luxi typeface designs in Ikarus digital format. + +URW++ Design and Development GmbH converted the Ikarus format fonts to True- +Type and Type1 font programs and implemented the grid-fitting "hints" and +kerning tables in the Luxi fonts. + +For more information, please contact <design@bigelowandholmes.com> or +<info@urwpp.de>, or consult the URW++ web site <URL:http://www.urwpp.de>. + +An earlier version of the Luxi fonts was made available under the name +Lucidux. This name should no longer be used due to trademark uncertainties, +and all traces of the Lucidux name have been removed from XFree86. + +4. More about core fonts + +This section describes XFree86-specific enhancements to the core X11 fonts +system. + +4.1 Core fonts and internationalisation + +The scalable font backends (Type 1, Speedo and TrueType) can automatically +re-encode fonts to the encoding specified in the XLFD in `fonts.dir'. For +example, a `fonts.dir' file can contain entries for the Type 1 Courier font +such as + + cour.pfa -adobe-courier-medium-r-normal--0-0-0-0-m-0-iso8859-1 + cour.pfa -adobe-courier-medium-r-normal--0-0-0-0-m-0-iso8859-2 + +which will lead to the font being recoded to ISO 8859-1 and ISO 8859-2 +respectively. + +4.1.1 The fontenc layer + +Three of the scalable backends (Type 1, Speedo, and the FreeType TrueType +backend) use a common fontenc layer for font re-encoding. This allows these +backends to share their encoding data, and allows simple configuration of new +locales independently of font type. + +Please note: the X-TrueType (X-TT) backend does not use the fontenc layer, +but instead uses its own method for font reencoding. If you are only inter- +ested in X-TT you may want to skip to Using Symbol Fonts (section 4.1.5, page +1), as the intervening information does not apply to X-TT. X-TT itself is +described in more detail in X-TrueType (section 4.2.3, page 1). + +In the fontenc layer, an encoding is defined by a name (such as iso8859-1), +possibly a number of aliases (alternate names), and an ordered collection of +mappings. A mapping defines the way the encoding can be mapped into one of +the target encodings known to fontenc; currently, these consist of Unicode, +Adobe glyph names, and arbitrary TrueType ``cmap''s. + +A number of encodings are hardwired into fontenc, and are therefore always +available; the hardcoded encodings cannot easily be redefined. These +include: + + o iso10646-1: Unicode; + + o iso8859-1: ISO Latin-1 (Western Europe); + + o iso8859-2: ISO Latin-2 (Eastern Europe); + + o iso8859-3: ISO Latin-3 (Southern Europe); + + o iso8859-4: ISO Latin-4 (Northern Europe); + + o iso8859-5: ISO Cyrillic; + + o iso8859-6: ISO Arabic; + + o iso8859-7: ISO Greek; + + o iso8859-8: ISO Hebrew; + + o iso8859-9: ISO Latin-5 (Turkish); + + o iso8859-10: ISO Latin-6 (Nordic); + + o iso8859-15: ISO Latin-9, or Latin-0 (Revised Western-European); + + o koi8-r: KOI8 Russian; + + o koi8-u: KOI8 Ukrainian (see RFC 2319); + + o koi8-ru: KOI8 Russian/Ukrainian; + + o koi8-uni: KOI8 ``Unified'' (Russian, Ukrainian, and Byelorussian); + + o koi8-e: KOI8 ``European,'' ISO-IR-111, or ECMA-Cyrillic; + + o microsoft-symbol and apple-roman: these are only likely to be useful + with TrueType symbol fonts. + +Additional encodings can be added by defining encoding files. When a font +encoding is requested that the fontenc layer doesn't know about, the backend +checks the directory in which the font file resides (not necessarily the +directory with fonts.dir!) for a file named `encodings.dir'. If found, this +file is scanned for the requested encoding, and the relevant encoding defini- +tion file is read in. The `mkfontdir' utility, when invoked with the `-e' +option followed by the name of a directory containing encoding files, can be +used to automatically build `encodings.dir' files. Please see the mkfont- +dir(1) manual page for more details. + +A number of encoding files for common encodings are included with XFree86. +Information on writing new encoding files can be found in Format of encodings +directory files (section 4.1.3, page 1) and Format of encoding files (section +4.1.4, page 1) later in this document. + +4.1.2 Backend-specific notes about fontenc + +4.1.2.1 The FreeType backend + +For TrueType and OpenType fonts, the FreeType backend scans the mappings in +order. Mappings with a target of PostScript are ignored; mappings with a +TrueType or Unicode target are checked against all the cmaps in the file. +The first applicable mapping is used. + +For Type 1 fonts, the FreeType backend first searches for a mapping with a +target of PostScript. If one is found, it is used. Otherwise, the backend +searches for a mapping with target Unicode, which is then composed with a +built-in table mapping codes to glyph names. Note that this table only cov- +ers part of the Unicode code points that have been assigned names by Adobe. + +Specifying an encoding value of adobe-fontspecific for a Type 1 font disables +the encoding mechanism. This is useful with symbol and incorrectly encoded +fonts (see Incorrectly encoded fonts (section 4.1.6, page 1) below). + +If a suitable mapping is not found, the FreeType backend defaults to +ISO 8859-1. + +4.1.2.2 Type 1 + +The Type 1 backend behaves similarly to the FreeType backend with Type 1 +fonts, except that it limits all encodings to 8-bit codes. + +4.1.2.3 Speedo + +The Speedo backend searches for a mapping with a target of Unicode, and uses +it if found. If none is found, the backend defaults to ISO 8859-1. + +The Speedo backend limits all encodings to 8-bit codes. + +4.1.3 Format of encoding directory files + +In order to use a font in an encoding that the font backend does not know +about, you need to have an `encodings.dir' file either in the same directory +as the font file used or in a system-wide location +(`/usr/X11R6/lib/X11/fonts/encodings/' by default). + +The `encodings.dir' file has a similar format to `fonts.dir'. Its first line +specifies the number of encodings, while every successive line has two +columns, the name of the encoding, and the name of the encoding file; this +can be relative to the current directory, or absolute. Every encoding name +should agree with the encoding name defined in the encoding file. For exam- +ple, + + 3 + mulearabic-0 /usr/X11R6/lib/X11/fonts/encodings/mulearabic-0.enc + mulearabic-1 /usr/X11R6/lib/X11/fonts/encodings/mulearabic-1.enc + mulearabic-2 /usr/X11R6/lib/X11/fonts/encodings/mulearabic-2.enc + +The name of an encoding must be specified in the encoding file's `STARTENCOD- +ING' or `ALIAS' line. It is not enough to create an `encodings.dir' entry. + +If your platform supports it (it probably does), encoding files may be com- +pressed or gzipped. + +The `encoding.dir' files are best maintained by the `mkfontdir' utility. +Please see the mkfontdir(1) manual page for more information. + +4.1.4 Format of encoding files + +The encoding files are ``free form,'' i.e. any string of whitespace is equiv- +alent to a single space. Keywords are parsed in a non-case-sensitive manner, +meaning that `size', `SIZE', and `SiZE' all parse as the same keyword; on the +other hand, case is significant in glyph names. + +Numbers can be written in decimal, as in `256', in hexadecimal, as in +`0x100', or in octal, as in `0400'. + +Comments are introduced by a hash sign `#'. A `#' may appear at any point in +a line, and all characters following the `#' are ignored, up to the end of +the line. + +The encoding file starts with the definition of the name of the encoding, and +possibly its alternate names (aliases): + + STARTENCODING mulearabic-0 + ALIAS arabic-0 + +The name of the encoding and its aliases should be suitable for use in an +XLFD font name, and therefore contain exactly one dash `-'. + +The encoding file may then optionally declare the size of the encoding. For +a linear encoding (such as ISO 8859-1), the SIZE line specifies the maximum +code plus one: + + SIZE 0x2B + +For a matrix encoding, it should specify two numbers. The first is the num- +ber of the last row plus one, the other, the highest column number plus one. +In the case of `jisx0208.1990-0' (JIS X 0208(1990), double-byte encoding, +high bit clear), it should be + + SIZE 0x75 0x80 + +In the case of a matrix encoding, a `FIRSTINDEX' line may be included to +specify the minimum glyph index in an encoding. The keyword `FIRSTINDEX' is +followed by two integers, the minimum row number followed by the minimum col- +umn number: + + FIRSTINDEX 0x20 0x20 + +In the case of a linear encoding, a `FIRSTINDEX' line is not very useful. If +for some reason however you chose to include on, it should be followed by a +single integer. + +Note that in most font backends inclusion of a `FIRSTINDEX' line has the side +effect of disabling default glyph generation, and this keyword should there- +fore be avoided unless absolutely necessary. + +Codes outside the region defined by the `SIZE' and `FIRSTINDEX' lines are +understood to be undefined. Encodings default to linear encoding with a size +of 256 (0x100). This means that you must declare the size of all 16 bit +encodings. + +What follows is one or more mapping sections. A mapping section starts with +a `STARTMAPPING' line stating the target of the mapping. The target may be +one of: + + o Unicode (ISO 10646): + + STARTMAPPING unicode + + o a given TrueType ``cmap'': + + STARTMAPPING cmap 3 1 + + o PostScript glyph names: + + STARTMAPPING postscript + +Every line in a mapping section maps one from the encoding being defined to +the target of the mapping. In mappings with a Unicode or TrueType mapping, +codes are mapped to codes: + + 0x21 0x0660 + 0x22 0x0661 + ... + +As an abbreviation, it is possible to map a contiguous range of codes in a +single line. A line consisting of three integers + + <it/start/ <it/end/ <it/target/ + +is an abbreviation for the range of lines + + start target + + start+1 target+1 + + ... + + end target+end-start + +For example, the line + + 0x2121 0x215F 0x8140 + +is an abbreviation for + + 0x2121 0x8140 + 0x2122 0x8141 + ... + 0x215F 0x817E + +Codes not listed are assumed to map through the identity (i.e. to the same +numerical value). In order to override this default mapping, you may specify +a range of codes to be undefined by using an `UNDEFINE' line: + + UNDEFINE 0x00 0x2A + +or, for a single code, + + UNDEFINE 0x1234 + +PostScript mappings are different. Every line in a PostScript mapping maps a +code to a glyph name + + 0x41 A + 0x42 B + ... + +and codes not explicitly listed are undefined. + +A mapping section ends with an ENDMAPPING line + + ENDMAPPING + +After all the mappings have been defined, the file ends with an ENDENCODING +line + + ENDENCODING + +In order to make future extensions to the format possible, lines starting +with an unknown keyword are silently ignored, as are mapping sections with an +unknown target. + +4.1.5 Using symbol fonts + +Type 1 symbol fonts should be installed using the adobe-fontspecific encod- +ing. + +In an ideal world, all TrueType symbol fonts would be installed using one of +the microsoft-symbol and apple-roman encodings. A number of symbol fonts, +however, are not marked as such; such fonts should be installed using +microsoft-cp1252, or, for older fonts, microsoft-win3.1. + +In order to guarantee consistent results (especially between Type 1 and True- +Type versions of the same font), it is possible to define a special encoding +for a given font. This has already been done for the ZapfDingbats font; see +the file `encodings/adobe-dingbats.enc'. + +4.1.6 Hints about using badly encoded fonts + +A number of text fonts are incorrectly encoded. Incorrect encoding is some- +times done by design, in order to make a font for an exotic script appear +like an ordinary Western text font on systems which are not easily extended +with new locale data. It is often the result of the font designer's laziness +or incompetence; for some reason, most people seem to find it easier to +invent idiosyncratic glyph names rather than follow the Adobe glyph list. + +There are two ways of dealing with such fonts: using them with the encoding +they were designed for, and creating an ad hoc encoding file. + +4.1.6.1 Using fonts with the designer's encoding + +In the case of Type 1 fonts, the font designer can specify a default encod- +ing; this encoding is requested by using the `adobe-fontspecific' encoding in +the XLFD name. Sometimes, the font designer omitted to specify a reasonable +default encoding, in which case you should experiment with `adobe-standard', +`iso8859-1', `microsoft-cp1252', and `microsoft-win3.1'. (The encoding +`microsoft-symbol' doesn't make sense for Type 1 fonts). + +TrueType fonts do not have a default encoding. However, most TrueType fonts +are designed with either Microsoft or Apple platforms in mind, so one of +`microsoft-symbol', `microsoft-cp1252', `microsoft-win3.1', or `apple-roman' +should yield reasonable results. + +4.1.6.2 Specifying an ad hoc encoding file + +It is always possible to define an encoding file to put the glyphs in a font +in any desired order. Again, see the `encodings/adobe-dingbats.enc' file to +see how this is done. + +4.1.6.3 Specifying font aliases + +By following the directions above, you will find yourself with a number of +fonts with unusual names --- with encodings such as `adobe-fontspecific', +`microsoft-win3.1' etc. In order to use these fonts with standard applica- +tions, it may be useful to remap them to their proper names. + +This is done by writing a `fonts.alias' file. The format of this file is very +simple: it consists of a series of lines each mapping an alias name to a font +name. A `fonts.alias' file might look as follows: + + "-ogonki-alamakota-medium-r-normal--0-0-0-0-p-0-iso8859-2" \ + "-ogonki-alamakota-medium-r-normal--0-0-0-0-p-0-adobe-fontspecific" + +(both XLFD names on a single line). The syntax of the `fonts.alias' file is +more precisely described in the mkfontdir(1) manual page. + +4.2 Additional notes about scalable core fonts + +The FreeType backend (module `freetype', formerly known as xfsft) is able to +deal with both TrueType and Type 1 fonts. This puts it in conflict with the +X-TT and Type 1 backends respectively. + +If both the FreeType and the Type 1 backends are loaded, the FreeType backend +will be used for Type 1 fonts. If both the FreeType and X-TT backends are +loaded, X-TT will be used for TrueType fonts. + +4.2.1 Delayed glyph rasterisation + +Both FreeType and X-TT delay glyph rasterisation up to the time at which a +glyph is first used. For this reason, they only provide an approximate value +for the ``average width'' font property. + +Both backends also support an optimisation for character-cell fonts (fonts +with all glyph metrics equal, or terminal fonts). A font with an XLFD speci- +fying a character-cell spacing `c', as in + + -misc-mincho-medium-r-normal--0-0-0-0-c-0-jisx0208.1990-0 + +will not rasterise glyphs at metrics computation time, but instead trust the +font really to be a character-cell font. You are encouraged to make use of +this optimisation when useful, but be warned that not all monospaced fonts +are character-cell fonts. + +4.2.2 About the FreeType backend + +The FreeType backend (formerly xfsft) is a backend based on version 2 of the +FreeType library (see the FreeType web site <URL:http://www.freetype.org/>) +and has support for the ``fontenc'' style of internationalisation (see The +fontenc layer (section 4.1.1, page 1)). This backend supports TrueType font +files (`*.ttf'), OpenType font files (`*.otf'), TrueType Collections +(`*.ttc'), OpenType Collections (`*.otc') and Type 1 font files (`*.pfa' and +`*.pfb'). + +In order to access the faces in a TrueType Collection file, the face number +must be specified in the fonts.dir file before the filename within colons. +For example, + + :2:mincho.ttc -misc-mincho-medium-r-normal--0-0-0-0-c-0-jisx0208.1990-0 + +refers to face 2 in the `mincho.ttc' TrueType Collection file. + +The FreeType backend uses the fontenc layer in order to support recoding of +fonts; this was described in The fontenc layer (section 4.1.1, page 1) and +especially FreeType-specific notes about fontenc (section 4.1.2.1, page 1) +earlier in this document. + +4.2.3 About the X-TrueType TrueType backend + +The `X-TrueType' backend is a backend based on version 1 of the FreeType +library. X-TrueType doesn't use the `fontenc' layer for managing font encod- +ings, but instead uses its own database of encodings. + +X-TrueType extends the `fonts.dir' syntax with a number of options, collec- +tively known as `TTCap'. A `TTCap' entry follows the general syntax + + :option=value: + +and should be specified before the filename. + +The most useful TTCap option is used to specify the face number to use with +TTCs; this is the `fn' TTCap option. For example, face 2 of font file `min- +cho.ttc' is specified using: + + :fn=2:mincho.ttc -misc-mincho-medium-r-normal--0-0-0-0-c-0-jisx0208.1990-0 + +More information on the TTCap syntax, and on X-TrueType in general, may be +found on the X-TrueType home page <URL:http://x-tt.dsl.gr.jp/>. + +5. Appendix: background and terminology + +5.1 Characters and glyphs + +A computer text-processing system inputs keystrokes and outputs glyphs, small +pictures that are assembled on paper or on a computer screen. Keystrokes and +glyphs do not, in general, coincide: for example, if the system does generate +ligatures, then to the sequence of two keystrokes <f><i> will typically cor- +respond a single glyph. Similarly, if the system shapes Arabic glyphs in a +vaguely reasonable manner, then multiple different glyphs may correspond to a +single keystroke. + +The complex transformation rules from keystrokes to glyphs are usually fac- +tored into two simpler transformations, from keystrokes to characters and +from characters to glyphs. You may want to think of characters as the basic +unit of text that is stored e.g. in the buffer of your text editor. While +the definition of a character is intrinsically application-specific, a number +of standardised collections of characters have been defined. + +A coded character set is a set of characters together with a mapping from +integer codes --- known as codepoints --- to characters. Examples of coded +character sets include US-ASCII, ISO 8859-1, KOI8-R, and JIS X 0208(1990). + +A coded character set need not use 8 bit integers to index characters. Many +early systems used 6 bit character sets, while 16 bit (or more) character +sets are necessary for ideographic writing systems. + +5.2 Font files, fonts, and XLFD + +Traditionally, typographers speak about typefaces and founts. A typeface is +a particular style or design, such as Times Italic, while a fount is a +molten-lead incarnation of a given typeface at a given size. + +Digital fonts come in font files. A font file contains the information nec- +essary for generating glyphs of a given typeface, and applications using font +files may access glyph information in an arbitrary order. + +Digital fonts may consist of bitmap data, in which case they are said to be +bitmap fonts. They may also consist of a mathematical description of glyph +shapes, in which case they are said to be scalable fonts. Common formats for +scalable font files are Type 1 (sometimes incorrectly called ATM fonts or +PostScript fonts), TrueType and Speedo. + +The glyph data in a digital font needs to be indexed somehow. How this is +done depends on the font file format. In the case of Type 1 fonts, glyphs +are identified by glyph names. In the case of TrueType fonts, glyphs are +indexed by integers corresponding to one of a number of indexing schemes +(usually Unicode --- see below). + +The X11 core fonts system uses the data in a font file to generate font +instances, which are collections of glyphs at a given size indexed according +to a given encoding. + +X11 core font instances are usually specified using a notation known as the X +Logical Font Description (XLFD). An XLFD starts with a dash `-', and con- +sists of fourteen fields separated by dashes, for example: + + -adobe-courier-medium-r-normal--12-120-75-75-m-70-iso8859-1 + +Or particular interest are the last two fields `iso8859-1', which specify the +font instance's encoding. + +A scalable font is specified by an XLFD which contains zeroes instead of some +fields: + + -adobe-courier-medium-r-normal--0-0-0-0-m-0-iso8859-1 + +X11 font instances may also be specified by short name. Unlike an XLFD, a +short name has no structure and is simply a conventional name for a font +instance. Two short names are of particular interest, as the server will not +start if font instances with these names cannot be opened. These are +`fixed', which specifies the fallback font to use when the requested font +cannot be opened, and `cursor', which specifies the set of glyphs to be used +by the mouse pointer. + +Short names are usually implemented as aliases to XLFDs; the standard `fixed' +and `cursor' aliases are defined in + + /usr/X11R6/lib/X11/font/misc/fonts.alias + +5.3 Unicode + +Unicode (<URL:http://www.unicode.org>) is a coded character set with the goal +of uniquely identifying all characters for all scripts, current and histori- +cal. While Unicode was explicitly not designed as a glyph encoding scheme, +it is often possible to use it as such. + +Unicode is an open character set, meaning that codepoint assignments may be +added to Unicode at any time (once specified, though, an assignment can never +be changed). For this reason, a Unicode font will be sparse, meaning that it +only defines glyphs for a subset of the character registry of Unicode. + +The Unicode standard is defined in parallel with the international standard +ISO 10646. Assignments in the two standards are always equivalent, and we +often use the terms Unicode and ISO 10646 interchangeably. + +When used in the X11 core fonts system, Unicode-encoded fonts should have the +last two fields of their XLFD set to `iso10646-1'. + +6. References + +XFree86 comes with extensive documentation in the form of manual pages and +typeset documents. Before installing fonts, you really should read the font- +config(3) and mkfontdir(1) manual pages; other manual pages of interest +include X(7), Xserver(1), xset(1), Xft(3), xlsfonts(1) and showfont(1). In +addition, you may want to read the X Logical Font Description document, by +Jim Flowers, which is provided in the file `xc/doc/xlfd.PS.Z'. + +The latest released version of the XFree86 documentation (including this doc- +ument and all manual pages) is available as current XFree86 documentation +<URL:http://www.xfree86.org/current/>. + +The comp.fonts FAQ <URL:http://www.netmeg.net/faq/computers/fonts/>, which is +unfortunately no longer being maintained, contains a wealth of information +about digital fonts. + +Xft and Fontconfig are described on Keith Packard's Fontconfig site +<URL:http://www.fontconfig.org>. + +The xfsft home page <URL:http://www.dcs.ed.ac.uk/home/jec/programs/xfsft/> +has been superseded by this document, and is now obsolete; you may however +still find some of the information that it contains useful. Joerg Pommnitz' +xfsft page <URL:http://www.joerg-pommnitz.de/TrueType/xfsft.html> is the +canonical source for the `ttmkfdir' utility, which is the ancestor of +mkfontscale. + +The author's software pages <URL:http://www.pps.jussieu.fr/~jch/software/> +might or might not contain related scribbles and development versions of +software. + +The documentation of X-TrueType is available from the X-TrueType home page +<URL:http://x-tt.dsl.gr.jp/>. + +A number of East-Asian CIDFonts are available from O'Reilly's FTP site +<URL:ftp://ftp.oreilly.com/pub/examples/nutshell/cjkv/adobe/>. + +While the Unicode consortium site <URL:http://www.unicode.org> may be of +interest, you are more likely to find what you need in Markus Kuhn's UTF-8 +and Unicode FAQ <URL:http://www.cl.cam.ac.uk/~mgk25/unicode.html>. + +The IANA RFC documents, available from a number of sites throughout the +world, often provide interesting information about character set issues; see +for example RFC 373. + + Generated from XFree86: xc/programs/Xserver/hw/xfree86/doc/sgml/fonts.sgml,v 1.20 2003/01/20 03:43:07 dawes Exp $ + + +$XFree86: xc/programs/Xserver/hw/xfree86/doc/README.fonts,v 1.22 2003/01/20 04:10:01 dawes Exp $ |