A tutorial on font installation for LaTeX under OS X ==================================================== Bruno Voisin, 15 October 2003 This tutorial assumes that you have installed Gerben Wierda's distribution of teTeX and TeX-Live for OS X, through i-Installer, and a front end to this distribution (like TeXShop, iTeXMac, OzTeX or CMacTeX). In the following, for simplicity, I will speak of "gwTeX". It also assumes that you have located and know how to display the following documentation files: - Font Names for TeX, at /Library/teTeX/share/texmf.tetex/doc/fonts/fontname/fontname.dvi or . - Directory Structure for TeX, at /Library/teTeX/share/texmf.tetex/doc/help/tds.dvi or . - dvips manual, at /Library/teTeX/share/texmf.tetex/doc/programs/dvips.pdf. - fontinst manual, at /Library/teTeX/share/texmf.tetex/doc/fontinst/base/fontinst.dvi. - Font Installation Guide, at . The installation procedure depends, of course, on the format of the font to install. If this is TrueType, then you can use the script ttf2tex, from , which takes care of everything. It relies on two additional pieces of software, the bash shell and the FreeType font rendering engine, for both of which Gerben Wierda provides i-packages. At the time of this writing, there are also indications that, starting with version 10.3 (aka Panther) of OS X, the default shell will be bash instead of tcsh. The rest of this document considers another route, which involves four steps: (i) converting the font to PostScript Type 1 format, (ii) creating LaTeX support files, (iii) organising these files and (iv) using the fonts. Before proceeding it may also be noted that the commercial software Textures, produced by Blue Sky TeX Systems at , and only available in Classic at the time of this writing, provides direct access to all the fonts installed in the OS, freeing the user from most of the following. 1. Font conversion ------------------ In any case you must first make sure that the font license allows conversion between formats. Otherwise you must purchase a Type 1 version of the font from its supplier, in either PFA (ascii) or PFB (binary) format. gwTeX can process both. Let's aim for PFB, and assume conversion is allowed. There are several free utilities for performing it, depending on the original format of the font. There is also, of course, the possibility that the font is already in PFB format, sometimes called DOS or Unix format by suppliers; if this is indeed the case, then jump directly to step 2. Classic font files ~~~~~~~~~~~~~~~~~~ First the font can be a Classic font, made of a bitmap font suitcase (used for screen display and bitmap printing) and one or several outline font files (used for PostScript printing). Normally these files should be accompanied by one or several Adobe Font Metric (AFM) files, one per outline font file; these are not used by Mac OS itself, but are an integral part of a PostScript font. The AFM files are required by step 2; if they are absent, don't panic, they can be recreated at will from the data in the outline font files. What we use is t1unmac, from the t1utils package at . t1unmac is included in gwTeX. Let us consider that the font is called "Example", and provided as a suitcase "Example Screen Fonts" and four files Examp, ExampBol, ExampBolIta and ExampIta, together with AFM files Examp.afm, ExampBol.afm, ExampBolIta.afm and ExampIta.afm. Let's also consider that the foundry (a typographer's jargon for supplier) producing the font is some little-known company called, imaginatively enough, Foundry. "Font Names for TeX" tells that the TeX name of the font, also called a Karl-Berry-style name, should start with something like fxm, where the first letter "f" stands for a small foundry and the following two "xm" are some arbitrary two-letter acronym for Example. Then, rename the outline font files as follows: Examp -> fxmr8a ExampBol -> fxmb8a ExampBolIta -> fxmbi8a ExampIta -> fxmri8a and similarly for the AFM files. We won't use the font suitcase at all. Next thing: open Terminal (in /Applications/Utilities), type "cd " (without the quotes but with the space), drag, from the Finder, the folder containing the font files onto the Terminal window (this will insert the path for this folder at the pointer's location inside the window), and press Return. In Terminal, you are now in this folder. Type: t1unmac -r fxmr8a/rsrc fxmr8a.pfb t1unmac -r fxmb8a/rsrc fxmb8a.pfb t1unmac -r fxmbi8a/rsrc fxmbi8a.pfb t1unmac -r fxmri8a/rsrc fxmri8a.pfb with a Return at the end of each line. This will create the required four PFB files. Now, if the AFM files are not provided, you must also create them. For this two more pieces of software are needed: a BinHex converter, such as binhex from the MacUtils package , and PfaEdit from . Gerben Wierda provides i-packages for the two, with a Command-Line Interface (CLI) for each. If you prefer instead a Graphical User Interface (GUI), then you may get one for PfaEdit by (i) installing Apple's X11 from (starting from OS X 10.3, X11 will be provided with the OS) and (ii) installing PfaEdit with X11 support from . In X11, create a new item in the Applications menu, with Name=PfaEdit and Command=/usr/local/bin/pfaedit. Back to Terminal, type: binhex -r fxmr8a/rsrc > fxmr8a.hqx binhex -r fxmb8a/rsrc > fxmb8a.hqx binhex -r fxmbi8a/rsrc > fxmbi8a.hqx binhex -r fxmri8a/rsrc > fxmri8a.hqx Then launch PfaEdit and open the HQX files with it. The File menu offers a font creation item, and in the window opened by this item an Option button is present, allowing the creation of AFM files. OS X font files ~~~~~~~~~~~~~~~ OS X fonts come out in a variety of formats: TrueType fonts in Classic format (i.e. suitcases) or OS X format (i.e. files with .ttf extension), data-fork font files (with .dfont extension) or OpenType fonts (with .otf extension). Each of these files may actually contain several font variants. There are several tools to deal with the font files: - ttf2pt1 from . Converts TTF files to PFA or PFB format. Gerben Wierda provides an i-package for it. - Fondu from . Converts font suitcases, outline font files and data-fork font files to PFB format. Gerben provides an i-package for it. - PfaEdit, described above and which can deal with practically any font. I won't say more about these programs, as I've not used them really. For command-line operation of Fondu or Pfaedit, it may be that you need to access the raw resource part of a font file, or create a binhexed version of this file. The raw resource is accessed by appending /rsrc at the end of the name of the file, as already used above (acknowledgements and thanks to Jonathan Guyer for pointing this tip in a post to the OS X TeX mailing list), and a typical syntax for binhex has already been described (don't forget the ">" for redirecting the output from stdout -- the standard output -- to a file). For more information on these three tools, you can use the command "man" in Terminal, for example, for Fondu: man fondu When in man, press the Space bar to scroll down by one window height, Return to scroll line by line, and "q" to exit. An alternative is to install ManOpen from , a very nice Macintosh utility for viewing Unix manual pages and pretty-printing them. 2. Creation of LaTeX support files ---------------------------------- Once the PFB and AFM files have been created, LaTeX support files for them come next. These include: - TeX Font Metric (TFM) and Virtual Font (VF) files used by the TeX engine; - Font Definition (FD) files used by the LaTeX macros; - Mapping information (MAP) files used by dvips, pdfTeX and dvipdfm. These files may already exist on the internet, in either of the three following locations: - On CTAN at . All support files for the most common foundries and fonts are provided, but beware: often these files are outdated, dating back to obsolete versions of the fonts. It may also be that different foundries provide fonts with practically (or exactly) the same names; then, again, beware: fonts with identical names but from different foundries are different fonts indeed, with distinct metrical parameters, and using the support files for one font with another font yields poor output. Hence the first, foundry-specific, letter in the TeX scheme for naming fonts. - Walter Schmidt, the current maintainer of the PSNFSS package offering support for the standard built-in laser printer fonts, maintains a page of updated support files for a smaller range of PostScript fonts, at . - Y&Y, makers of a commercial distribution of TeX for Windows, and of the AMS, EM, MathTime and Lucida PostScript fonts as well, maintain a page of support files for the fonts from the Adobe Type Library at . These files are based on Y&Y's in-house TeX n' ANSI encoding, also called LY1. LY1 frees the user from the recourse to virtual fonts, but using it requires some familiarity with the concept of encodings. In this respect, the usual TeX encodings are called OT1, T1 and TS1. Consider now that you have to create the support files yourself. The following describes the standard solution based on fontinst, taken from the fontinst manual as well as from the Font Installation Guide. Another alternative involves the tool afm2tfm; it is described in the dvips manual. Both fontinst and afm2tfm are included in gwTeX. Creating the TFM, VF and FD files ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Going back to the Example font, create, in the same folder as the AFM files, a new file called fxm-drv.tex say, and containing the lines: \input fontint.sty \latinfamily{fxm}{} \bye If the font is monospaced, similar to Courier, in which case hyphenation is generally considered harmful, the second line should be replaced by: \latinfamily{fxm}{\hyphenchar\font=-1} Run fxm-drv.tex through TeX. A number of files will be generated, of which the important ones are the Property List (PL) and Virtual Property List (VPL) files, and the Font Definition (FD) files. PL and VPL files are ascii versions of the binary TFM and VF files, respectively. To convert them to their binary equivalent, use the tools pltotf and vptovf included in gwTeX. The whole process can be reduced to typing the following instructions in Terminal: apply pltotf *.pl apply vptovf *.vpl Creating the MAP file ~~~~~~~~~~~~~~~~~~~~~ Next, write the MAP file. For this you must first figure out the PostScript name of each font variant, distinct a priori from both its TeX name (such as fxmr8a) and the name of the original font file (such as Examp). It's generally a more descriptive name, hard-coded into the font variant itself, and which can be obtained by opening either the font file in PfaEdit, or the corresponding AFM file, looking for the FontName entry. For the four variants of the Example font, the PostScript names are typically as follows: Examp Example ExampBol Example-Bold ExampBolIta Example-BoldItalic ExampIta Example-Italic Based on this information, the MAP file, to be saved as example.map say, must contain the lines: fxmr8r Example "TeXBase1Encoding ReEncodeFont" <8r.enc //, for example texmf/fonts/afm/foundry/example for the AFM files for the font Example produced by the foundry Foundry; the MAP file is put in a subdirectory of texmf/dvips; the FD files are put in a subdirectory of texmf/tex/latex. Specific to gwTeX is the organisation of the texmf trees. Local additions, such as fonts and their support files, must reside either in a given user's home folder, in ~/Library/texmf, or in the /Library folder containing all additions to the OS on a given computer, in /Library/teTeX/share/texmf.local. Additions put in a user's home folder will only be visible to this user, while additions put in the /Library folder will be available to all users of a given computer. A safe procedure is to install things first in your home folder, and then, when you have made sure that everything works, to move them into the /Library folder. This latter folder being owned by the System Administrator, i.e. the root user, you cannot move files directly in the Finder: operating in Terminal is required. This means using Unix commands such as mkdir (make directory), cp (copy) and mv (move or rename), all prefaced by sudo (super-user do). The best way to learn how they work is to use the man command, or ManOpen, to display the manual pages for them. Considering the ~/Library/texmf tree, all font and suppport files must be organised as follows: PFB files in ~/Library/texmf/fonts/type1/foundry/example/ AFM files in ~/Library/texmf/fonts/afm/foundry/example/ TFM files in ~/Library/texmf/fonts/tfm/foundry/example/ VF files in ~/Library/texmf/fonts/vf/foundry/example/ MAP file in ~/Library/texmf/dvips/example/ FD files in ~/Library/texmf/tex/latex/example/ If the files are put instead in /Library/teTeX/share/texmf.local, then their organisation must be followed by: sudo texhash to make gwTeX aware of the changes to the texmf tree. 4. Use of the font ------------------ Before starting to actually use the font in LaTeX, one more step is necessary: gwTeX must update the MAP files used by the three applications dvips, pdfTeX and dvipdfm, based on the information in example.map. This is done in Terminal by running: sudo updmap --enable Map example.map Now the font is ready for your LaTeXing pleasure. In any LaTeX document, you can switch to the Example font at any time by typing: \fontfamily{fxm}\selectfont You can alternatively write in the preamble of the document \renewcommand{\rmdefault}{fxm} if the font is a Roman font (like Times), \renewcommand{\sfdefault}{fxm} if it is sans serif (like Helvetica), or \renewcommand{\ttdefault}{fxm} if it is monospaced (like Courier). Then all roman, sans serif or monospaced text, respectively, in this document, will be typeset in the Example font. A third solution is to write a LaTeX package example.sty, of the form say: \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{example} [2003/10/15 v1.0 LaTeX support for the Foundry Example font] \renewcommand{\rmdefault}{fxm} \endinput and to put this package in the directory texmf/tex/latex/example of the relevant texmf tree, and then call for it in a given LaTeX document by writing in the preamble: \usepackage{example} That's all folks!