Sergey A. Babkin or (Do not edit this file, it is generated from FONTS.html!!!) THE FONT INSTALLATION GUIDE for the TTF to Type1 converter and fonts generated by it ======================================================== There is historically a number of problems with the support of the 8-bit character encodings. This installation guide pays a lot of attention to the 8-bit issues, because these issues are responsible for the most of troubles during the installation of fonts. But they are not the only things covered in this guide, so it's worth reading even if all you need is plain ASCII. For convenience of reading I have marked the paragraphs dealing solely with 8-bit problems with characters *8*. To simplify this installation the distribution package of the converter contains a number of scripts written in shell and Perl. So, to run them you will need a shell interpreter (Bourne-shell, POSIX-shell, Korn-shell are OK, ba-shell is probably also OK but not tested yet). The Perl scripts were tested with Perl5 but probably should work with Perl4 too. All the scripts are located in the `scripts' subdirectory. This guide considers the following issues of installation of the fonts: - X11 - Ghostscript - MS Windows - Netscape Navigator/Communicator - Linux RPM package - FrameMaker - StarOffice X11 === To simplify the conversion a set of scripts is provided with ttf2pt1. They are collected in the `scripts' subdirectory. `Convert' is the master conversion script provided with ttf2pt1. When installed into a public directory it's named `ttf2pt1_convert' to avoid name collisions with the other programs. It's called as: convert [config-file] If the configuration file is not specified as an argument then the file `convert.cfg' in the current directory is used. This file contains a set of configuration variables. The distribution contains a sample file file `convert.cfg.sample'. Please copy it to `convert.cfg', look inside it and change the configuration variables. The more stable configuration variables, such as the path names of the scripts and encoding files are located in `convert' itself, they are automatically updated when installing ttf2pt1. Put all the TTF fonts you want to convert into some directory (this may be just the directory that already contains all the Windows fonts on a mounted FAT filesystem). If you have fonts in different source encoding then put the fonts in each of the encodings into a separate directory. Up to 10 source directories are supported. If you (in a rather unlikely case) have more source directories then you can make two separate runs of the converter, converting up to 10 directories at a time. The variables in the configuration file are: SRCDIRS - the list of directories (with absolute paths) with TTF fonts. Each line contains at least 3 fields: the name of the directory, the language of the fonts in it (if you have fonts for different languages you have to put them into the separate directories) and the encoding of the fonts. Again, if you have some of the TTF typefaces in one encoding, and some in another (say, CP-1251 and KOI-8), you have to put them into the separate source directories. Some lines may contain 4 fields. Then the fourth field is the name of the external map to convert the Unicode fonts into the desirable encoding. This map is used instead of the built-in map for the specified language. *8* An interesting thing is that some languages have more than one widely used character encodings. For example, the widely used encodings for Russian are IBM CP-866 (MS-DOS and Unix), KOI-8 (Unix and VAX, also the standard Internet encoding), IBM CP-1251 (MS Windows). That's why I have provided the means to generate the converted fonts in more than one encoding. See the file encodings/README for details about the encoding tables. Actually, if you plan to use these fonts with Netscape Navigator better use the aliases cp-866 instead of ibm-866 and windows-1251 instead of ibm-1251 because that's what Netscape wants. DSTDIR - directory for the resulting Type1 fonts. Be careful! This directory gets completely wiped out before conversion, so don't use any already existing directory for this purpose. DSTENC{language} - the list of encodings in which the destination fonts will be generated for each language. Each font of that language will be generated in each of the specified encodings. If you don't want any translation, just specify both SRCENC and DSTENC as iso8859-1 (or if you want any other encoding specified in the fonts.dir, copy the description of 8859-1 with new name and use this new name for SRCENC and DSTENC). FOUNDRY - the foundry name to be used in the fonts.dir file. I have set it to `fromttf' to avoid name conflicts with any existing font for sure. But this foundry name is not registered in X11 standards and if you want to get the full standard compliance or have a font server that enforces such a compliance, use `misc'. The next few parameters control the general behavior of the converter. They default values are set to something reasonable. CORRECTWIDTH - if the value is set to YES then use the converter option -w, otherwise don't use it. See the description of this option in the README file. REMOVET1A - if the value is set to YES then after conversion remove the un-encoded .t1a font files and the intermediate .xpfa font metric files. INSTALLFONTMAP - a Ghostscript parameter, if the value is set to YES then install the entries for the new fonts right into the main Fontmap file. Otherwise just leave the file Fontmap.ttf in the Ghostscript configuration directory. HINTSUBST - if the value is set to YES use the option -H, otherwise don't use it. This option enables the hint substitution technique. If you have not installed the X11 patch described above, use this option with great caution. See further description of this option in the README file. ENFORCEISO - if the value is set to YES then disguise the resulting fonts as the fonts in ISOLatin1 encoding. Historically this was neccessary due to the way the installer scripts created the X11 font configuration files. It is not neccessary any more for this purpose. But if you plan to use these fonts with some other application that expects ISOLatin1 encoding then better enable this option. ALLGLYPHS - if the value is set to YES then include all the glyphs from the source fonts into the resulting fonts, even if these glyphs are inaccessible. If it's set to NO then include only the glyphs which have codes assigned to them. The glyphs without codes can not be used directly. But some clever programs, such as the Type 1 library from XFree86 3.9 and higher can change the encoding on the fly and use another set of glyphs. If you have not installed the X11 patch described above, use this option with great caution. See further description of the option option -a in the README file. GENUID - if the value is set to YES then use the option -uA of the converter to generate UniqueIDs for the converted fonts. The standard X11 Type 1 library does not use this ID, so it may only be neccessary for the other applications. The script is clever enough to generate different UniqueID for the same font converted to multiple encodings. Also after conversion it checks all the fonts generacted during the session for duplicated UniqueID and shows those. Still, this does not quarantee that these UniqueIDs won't overlap with some other fonts. The UniqueIDs are generated as hash values from the font names, so it's guaranteed that if the `convert' script runs multiple times it will generate the same UniqueIDs during each run. See further description of this option in the README file. GENUID - if the value is set to YES then create the .pfb files, otherwise the .pfa files. The .pfb files are more compact but contain binary data, so you may experience some troubles when transferring them through the network. The following parameters are used to locate the other scripts and configuration files. By default the scripts do a bit of guessing for them: they search in the ttf2pt1 installation directory if ttf2pt1 was installed or otherwise suppose that you are running `convert' with `scripts' subdirectory being the current directory. ENCDIR - directory containing the descriptions of encodings MAPDIR - directory containing the external map files Besides that a few parameters are built into the `convert' script itself. You probably won't need to change them: T1ASM, TTF2PT1, TRANS, T1FDIR, FORCEISO - paths to the other script Also there are a few parameters controlling the installation of fonts for Ghostscript. Please look at their description in the Ghostscript section of documentation or in the ttf2pt1_x2gs(1) manual page before running `convert'. If these parameters are set, `convert' will call the `x2gs' script automatically to install the newly converted fonts in Ghostscript. After creating the configuration file run the `convert' script. Look at the result and the log file in DSTDIR. Add the directory with newly converted fonts to the configuration of X server or font server. For most of the systems this step is very straightforward. For HP-UX it's rather tricky and poorly documented, so the file FONTS.hpux gives a short description. If you don't have the privileges of the root user, you still can configure your private font server. Just use some non-standard port number (see FONTS.hpux for an example, exept that you won't need all the HP-related stuff on any other system). Known Problems -------------- - One catch is that the X11 Type 1 font library has a rather low limit on the font size. Because of this the fonts with more complicated outlines and the enabled hint substitution may not fit into this limit. The same applies to the fonts with very complicated outlines or with very many glyphs (especially the fonts with over 256 glyphs). So you will need to excercise caution with these options if you plan using these fonts with X11. Some vendors such as HP provide the Type 1 implementation licensed from Adobe which should have no such problem. But there is a solution even for the generic X11. A patch located in the subdirectory `app/X11' fixes this problem as well as some other minor problems. Its description is provided in app/X11/README. To fix the X11 font library, you have to get the X11 sources. I can recommend the ftp sites of the XFree86 project ftp://ftp.xfree86.org or of the Open Group ftp://ftp.x.org. This patch was made on the sources of XFree86 so you may have better success with applying it to the XFree86 distribution. After you have got the sources, make sure that you can compile them. Then apply the patch as described. Make sure that it was applied properly. Compile the sources again (actually, you need only the fonts library, the fonts server, and possibly the X server). It would be prudent now to save your old font library, font server and, possibly, X server. Then install the new recently compiled versions of these files. Of course, if you know someone who already has compiled these files for the same OS as yours, you can just copy the binary fles from him. Alas, building the X11 system from the source code is not the easiest thing in the world and if you have no experience it can be quite difficult. In this case just avoid the aforementioned features or check each converted font to make sure that it works properly. - The Type1 font library from the standard X11 distribution does not work on HP-UX (at least, up to 10.01). The font server supplied with HP-UX up to 10.01 is also broken. Starting from HP-UX 10.20 (I don't know about 10.10) they supply a proprietary font library and the converted fonts work fine with it, provided that they are configured properly (see the file FONTS.hpux). - The fonts.scale files created by the older versions of the ttf2pt1 installation program (up to release 3.1) have conflicted with the language definitions of the Xfsft font server and parts of it included into XFree86. To overcome this incompatibility the never versions creats the fonts.scale file describing all the fonts as belonging to the adobe-fontspecific encoding and the fonts.alias file with the proper names. The drawback of this solution is that xlsfonts gives the list of twice more fonts. But as a side effect the option ENFORCEISO in `convert.cfg' is not required for X11 any more. - The conversion script has no support for Eastern multi-plane fonts. Contribution of such a support would be welcome. Ghostscript =========== The fonts generated with ttf2pt1 work fine with Ghostscript by themselves. The script `x2gs' (or `ttf2pt1_x2gs' when installed into a public directory, to avoid name conflicts with other programs) links the font files from the X11 direcotry into the Ghostscript directory and automatically creates the description file (Fontmap) in Ghostscript format. It's called as: x2gs [config-file] If the configuration file is not specified as an argument then the file `convert.cfg' in the current directory is used, just like the `convert' script does. Indeed, this configuration file is used for both scripts. The Ghostscript-related parameters in the configuration file are: DSTDIR - the X11 font directory used by `x2gs' as the source of the fonts. This parameter is common with the X11 configuration. GSDIR - the base directory of Ghostsript. If this parameter is set to an empty string then `convert' won't call `x2gs'. So if you want to get only the X11 fonts installed then set this parameter to an empty string. This directory may vary on various system, so please check your system and set this value accordingly before running the script. GSFONTDIR - the font directory of Ghostscript. In the standard Ghostscript installation it's a subdirectory of GSDIR but some systems may use completely different directories. GSCONFDIR - the configuration subdirectory of Ghostscript that contains the Fontmap file. INSTALLFONTMAP - if the value is set to YES then install the entries for the new fonts right into the main Fontmap file. Otherwise just leave the file Fontmap.ttf in the Ghostscript configuration directory. After preparing the configuration file run the script. It symbolicaly links all the font files and creates the description file Fontmap.ttf in GSCONDFIR. After that there are two choices. If the option INSTALLFONTMAP was set to YES then the font descriptions are also automatically installed into the master Fontmap file. The script is clever enough to detect if it was run multiple times with the same directories and if so it replaces the old Fontmap entries with the new ones instead of just accumulating all of them. You may also run it multiple times for multiple X11 directories and all the results will be properly collected in the Fontmap. But it's your responsibility to watch that the names of the font files don't overlap. If the X11 font directory gets renamed then you have to remove its font entries from the Fontmap and only after that re-run `x2gs' for the new directory. On the other hand if the option INSTALLFONTMAP was set to NO then go to the GSCONFDIR directory and insert the contents of Fontmap.ttf into the Fontmap file manually. This step may be left manual to make the installation a little bit more safe. After that you may also want to redefine some of the aliases in Fontmap to refer to the newly installed fonts. But the redefinition of the aliases may be dangerous if the width of characters in the new font will be different from the old font. Alas, there is no visible solution of this problem yet. MS Windows =========== Ttf2pt1 can be built on Windows either with native compiler or in POSIX emulation mode. Native MS Windows compilers require a different way to build the converter instead of the Makefile (their make programs commonly are quite weird and limited in capabilities). An example of batch file winbuild.bat is provided for MS Visual C/C++. Probably it can be easily adapted for other 32-bit Windows and DOS compilers. The important part is to define the preprocessor symbol WINDOWS during compilation. Cygnus make almost supports full Makefiles but not quite. Seems like its POSIX support is also of the same quality "almost but not quite". So another command file cygbuild.sh is provided for Cygnus GNU C, also with the preprocessor symbol WINDOWS defined. It is intended to be run from the Cygnus BASH shell. To run the programs produced by the Cygnus compiler the Cygnus library file CYGWIN1.DLL should be copied first into C:\WINDOWS. To run the accompanying scripts Perl for Windows will be required as well as other tools from the Cygnus set. The Windows support was not particularly tested, so in case of problems with building or running the converter please let us know. The pre-built code (possibly of an older version) of ttf2pt1 for MS Windows is available from the GnuWin32 project from http://gnuwin32.sourceforge.net/packages/ttf2pt1.htm Netscape Navigator/Communicator =============================== Basically, the biggest problem with Netscape Navigator is that it has built-in fixed PostScript font names and built-in fixed glyph tables for them. Oh, no, that's two! Let's start over: basically the two biggest problems of Netscape Navigator are that (one)it has built-in fixed PostScript font names and (two) built-in fixed glyph tables for them and (three) it always assumes that the fonts have ISOLatin1 encoding. OK, let's start over again: basically the three biggest problems of Netscape Navigator are that (one) it has built-in fixed PostScript font names, (two) built-in fixed glyph tables for them and (three) it always assumes that the fonts have ISOLatin1 encoding and (four) it does not remember the scaled font size between the sessions. You did not expect such a Spanish Inquisition, did you ? (*) Luckily, we have solutions for all of these problems. They are located in the subdirectory `app/netscape' and described in app/netscape/README. ------- *) See Monty Python's Flying Circus, episode 15 *8* Netscape and cyrillic fonts --------------------------- (courtesy of Zvezdan Petkovic) If you use TrueType fonts in your X, as I do, and you always get KOI8-R encoded pages, then your Netscape does not recognise windows-1251 encoding. Microsoft TrueType fonts simply declare all encodings they can support including KOI8-R. For some reason, KOI8-R always wins over ISO-8859-5 in Netscape under X. If you are reading other cyrillic languages besides Russian, you might want to either erase KOI8-R entries from the fonts.dir and fonts.scale files, or alternatively fix Netscape. I put this line in my .Xdefaults. Netscape*documentFonts.charset*koi8-r: iso-8859-5 Notice that you can still read Russian sites without trouble because Netscape translates KOI8-R to ISO-8859-5 on the fly. I read both Russian and Serbian sites with no trouble. Note: If anybody knows the way to tell Netscape under Unix how to recognise {windows,ibm,cp}-1251 encoded fonts, I'd like to hear about that. Linux RPM package ================= The spec file for the creation of a Linux RPM package is located in app/RPM. It has been contributed by Johan Vromans. When make all is ran in the main directory it among the other things creates the version of itself adapted to Linux in app/RPM, you may want to copy that version back to the main directory. Warning: Please note that the install section is incomplete, and the installed scripts won't work until the paths inside them are corrected. FrameMaker ========== The fonts and AFM files generated by the version 3.2 and higher should work with Framemaker without problems. The AFM files generated by the previous versions of the converter require a line added to them: EncodingScheme FontSpecific And the underscores in the font names of the font and AFM files generated by the older versions may need to be changed to dashes. NOTE by Jason Baietto: Ignore the directions in the Frame on-line docs that say to put a "serverdict begin 0 exitserver" line in the pfa files. Doing this caused both my printer and ghostscript to choke on the resulting output from FrameMaker, so I would not advise doing this (though your mileage may vary). StarOffice ========== StarOffice 5.1x has been reported to crash if the .afm file contains spaces in the values of such statements as Version, Weight etc. These spaces are permitted by the Adobe spec, so this is a problem of StarOffice. The easiest way to fix these .afm files for StarOffice is to remove spaces in these strings or remove these strings (in case if they are optional) at all. This can be done automatically with a sed script. It seems that StarOffice 5.2 has this problem fixed, so we decided to spend no efforts on providing workarounds for 5.1 with ttf2pt1.