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, CMacTEX or TEX Tools). 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:
The installation procedure depends, of course, on the format of the font to install. If the font is a platform-independent TrueType file, with extension .ttf, then you can use the script ttf2tex, 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:
Before proceeding it may also be noted that the commercial Textures, produced by Blue Sky TEX Systems, 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.
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 (Printer Font Ascii) or PFB (Printer Font 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 PFA or PFB format, sometimes called Windows or Unix format by suppliers; if this is indeed the case, then jump directly to step 2.
Classic fonts can be either non-PostScript, made of a bitmap or TrueType outline font suitcase, or PostScript, made of both a suitcase (used for screen display and non-PostScript printing) and one or several outline font files (used for PostScript printing). We consider only PostScript fonts here; non-PostScript ones will be considered later together with OS X fonts.
PostScript fonts are normally accompanied by Adobe Font Metric (AFM) files, one per outline font file. AFM files are not used by Mac OS, but they are an integral part of a PostScript font. They are required by step 2; if they are absent, don’t panic, they can be recreated at will from the outline font files.
PostScript outline font files are already Type 1 fonts, but packaged in a Macintosh-specific format that gwTEX cannot handle; this format is sometimes called LWFN, because the files are of type ‘LWFN’ (for LaserWriter Font), or POST, because the PostScript data in them are contained in resources of type ‘POST’. PFA and PFB files, by contrast, are platform-independent formats that gwTEX can handle. For performing the conversion we use t1unmac, from the t1utils package. 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, is 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 one more piece of software is handy: pf2afm, from the Ghostscript distribution; there is an i-package for this distribution, and most likely you have installed it already, at the same time as gwTEX (acknowledgements and thanks to Thomas Schmitz for pointing this solution).
Back to Terminal, type:
apply pf2afm *.pfb
This will create the four AFM files.
OS X fonts come out in a variety of formats: platform-independent files, in either TrueType format (with .ttf extension) or OpenType format (with .otf extension), and Macintosh-specific suitcases, in either Classic format (with no extension) or OS X format (with .dfont extension). Each of these files or suitcases may actually contain several variants of the font (i.e. upright or italic, normal weight or bold).
There are several tools to deal with such files:
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 suitcase, or create a binhexed version of it. 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). As for BinHex, its syntax requires redirection of the output from stdout – the standard output – to a file. This is performed as follows:
binhex -r fxmr8a/rsrc > fxmr8a.hqx binhex -r fxmb8a/rsrc > fxmb8a.hqx binhex -r fxmbi8a/rsrc > fxmbi8a.hqx binhex -r fxmri8a/rsrc > fxmri8a.hqx
PfaEdit’s GUI won’t see the original font file fxmr8a, but it will see fxmr8a.hqx.
For more information about these 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, a very nice OS X utility for viewing Unix manual pages and pretty-printing them.
Once the PFB and AFM files have been created, LATEX support files for them come next. These include:
These files may already exist on the internet, at either of the three following locations:
The choice of the support files to download, or of the method for creating them should you need to, depends on one of the most confusing issues of TEX, causing most of the problems experienced when moving to TEX from another text processing system: encodings. Drawing a font chart, as explained in step 4, may help clarify this issue.
The encoding of a font defines the number and ordering of characters in a TFM file, which is TEX’s interface between the input to be processed (i.e. the TEX file) and the glyphs – the geometrical shapes – to be taken from the font file (i.e. from the PFB file). Several encodings coexist; for Latin alphabets the most common ones are called OT1, T1, TS1 and LY1.
OT1 is the encoding of the original TEX fonts, known as CM (Computer Modern). Technically it is a 7-bit encoding, providing access to only 128 characters per font. As a consequence, accented letters are not included: they are constructed as composites, i.e. non-accented letters + accents, at the time LATEX is run. Unfortunately, LATEX cannot hyphenate any word containing a composite.
T1 is a more recent encoding, used in the updated TEX fonts known as EC (European Computer modern). It is also called Cork encoding, from the name of the Irish city where the TUG meeting was held where it was presented. Technically it is an 8-bit encoding, providing access to 256 characters per font. As a consequence accented letters for most European languages are included as single characters, allowing hyphenation. Each T1-encoded font is accompanied by a TS1-encoded one, also called Text Companion font and containing special characters like \dagger or \bullet for which there was no room left inside T1.
LY1 encoding, also called TEX n’ ANSI, is an alternative 8-bit encoding functionally equivalent to T1 and TS1 but more compatible with Windows, allowing the use of LY1-encoded fonts in other Windows applications. It has been developed by Y&Y.
For a PostScript font, the relation between the OT1, T1, TS1 metrics and the PFB font file is indirect: based on the data in the AFM file an intermediary TFM file is created, in a raw encoding known as TEX Base 1 or 8R, and the virtual font mechanism is then used to create TFM files in the OT1, T1 and TS1 encodings, by remapping the 8R design to the OT1, T1 and TS1 designs. By contrast, the relation between the LY1 metrics and the PFB font file is direct: based on the data in the AFM file, a TFM file in LY1 encoding is created directly.
The support files available on CTAN and at Walter Schmidt’s site are based on OT1, T1 and TS1 encodings, while those at Y&Y’s site are based on LY1 encoding. There is no need to install support files for both sets of encodings, one is enough. No harm, though, will be caused by having the two sets installed side-by-side: the files names are indeed different, and step 4 explains how the font encoding can be selected at the time LATEX is run.
Consider now that you have to create the support files yourself. Two tools allow this: fontinst, described in the fontinst manual, and afm2tfm, described in the dvips manual. Both tools are included in gwTEX.
The standard procedure for creating OT1, T1 and TS1 metrics, described in the Font Installation Guide, is based on fontinst. 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
This will create the required TFM and VF files.
The standard procedure for creating LY1 metrics, described in a dedicated page at Y&Y’s site, follows similar lines but is based on afm2tfm. Back to Terminal, in the same folder as the AFM files, type:
afm2tfm fxmr8a -T texnansx.enc -v fxmr8y afm2tfm fxmb8a -T texnansx.enc -v fxmb8y afm2tfm fxmbi8a -T texnansx.enc -v fxmbi8y afm2tfm fxmri8a -T texnansx.enc -v fxmri8y afm2tfm fxmr8a -s .167 -T texnansx.enc -v fxmro8y afm2tfm fxmb8a -s .167 -T texnansx.enc -v fxmbo8y
This will create both TFM files, with names ending in 8a.tfm, and VPL files, with names ending in 8y.vpl. The TFM files are unnecessary and may be thrown away. LY1 encoding uses other TFM files, derived from the VPL files by changing their extension according to:
mv fxmr8y.vpl fxmr8y.pl mv fxmb8y.vpl fxmb8y.pl mv fxmbi8y.vpl fxmbi8y.pl mv fxmri8y.vpl fxmri8y.pl mv fxmro8y.vpl fxmro8y.pl mv fxmbo8y.vpl fxmbo8y.pl
then applying pltotf to them, ignoring all the error messages that arise:
apply pltotf *.pl
This will create the required TFM files.
The FD file is not generated automatically as with fontinst, it must be written manually. It will be a file ly1fxm.fd with content:
\ProvidesFile{ly1fxm.fd}
[2003/10/22 v1.2 LaTeX font definitions for LY1/fxm]
\DeclareFontFamily{LY1}{fxm}{}
\DeclareFontShape{LY1}{fxm}{m} {n} {<->fxmr8y} {}
\DeclareFontShape{LY1}{fxm}{m} {it}{<->fxmri8y}{}
\DeclareFontShape{LY1}{fxm}{m} {sl}{<->fxmro8y}{}
\DeclareFontShape{LY1}{fxm}{b} {n} {<->fxmb8y} {}
\DeclareFontShape{LY1}{fxm}{b} {it}{<->fxmbi8y}{}
\DeclareFontShape{LY1}{fxm}{b} {sl}{<->fxmbo8y}{}
\DeclareFontShape{LY1}{fxm}{bx}{n} {<->ssub * fxm/b/n} {}
\DeclareFontShape{LY1}{fxm}{bx}{it}{<->ssub * fxm/b/it}{}
\DeclareFontShape{LY1}{fxm}{bx}{sl}{<->ssub * fxm/b/sl}{}
\endinput
Next, write the MAP file. For this you must 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 in a text editor, 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 for 8R encoding the lines:
fxmr8r Example "TeXBase1Encoding ReEncodeFont" <8r.enc <fxmr8a.pfb fxmb8r Example-Bold "TeXBase1Encoding ReEncodeFont" <8r.enc <fxmb8a.pfb fxmri8r Example-Italic "TeXBase1Encoding ReEncodeFont" <8r.enc <fxmri8a.pfb fxmbi8r Example-BoldItalic "TeXBase1Encoding ReEncodeFont" <8r.enc <fxmbi8a.pfb fxmro8r Example "0.167 SlantFont TeXBase1Encoding ReEncodeFont" <8r.enc <fxmr8a.pfb fxmbo8r Example-Bold "0.167 SlantFont TeXBase1Encoding ReEncodeFont" <8r.enc <fxmb8a.pfb
and for LY1 encoding the lines:
fxmr8y Example "TeXnANSIEncoding ReEncodeFont" <texnansi.enc <fxmr8a.pfb fxmb8y Example-Bold "TeXnANSIEncoding ReEncodeFont" <texnansi.enc <fxmb8a.pfb fxmri8y Example-Italic "TeXnANSIEncoding ReEncodeFont" <texnansi.enc <fxmri8a.pfb fxmbi8y Example-BoldItalic "TeXnANSIEncoding ReEncodeFont" <texnansi.enc <fxmbi8a.pfb fxmro8y Example "0.167 SlantFont TeXnANSIEncoding ReEncodeFont" <texnansi.enc <fxmr8a.pfb fxmbo8y Example-Bold "0.167 SlantFont TeXnANSIEncoding ReEncodeFont" <texnansi.enc <fxmb8a.pfb
The two sets of instructions may safely be put together in the same file.
In both cases, each line starts with the name of a TFM file, goes on with the PostScript name of the corresponding font variant, moves on to some reencoding information, and ends up with the name of the corresponding PFB file. The last two lines define an oblique variant, distinct from the italic one, and obtained by slanting the upright variant by a given factor 0.167. It is accessed in LATEX through the declaration \slshape or command \textsl.
More elaborate manipulations can also be performed, like the creation of a small caps variant. They are described in the Font Installation Guide for fontinst, and in the dvips manual for afm2tfm.
This step is dictated by the structure of the TEX Directory System (TDS): inside the texmf tree,
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.
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. Let's see how it is invoked in a LATEX document.
First, especially if you write text in a non-Latin alphabet, or in a Latin alphabet with accents, two encodings must be chosen: the font encoding, and the input encoding. The font encoding, which defines the number and ordering of characters in a metrics file, has been discussed in step 2. The input encoding defines the mapping from the keyboard to the metrics file, allowing direct input of accented letters, for example by pressing the key ‘ç’ on a French keyboard instead of typing the LATEX control sequence ‘\c c’. Think of the input encoding as indicating to LATEX that, when the key ‘ç’ is pressed, the character ‘ç’ from the metrics file is looked for, and the font encoding as indicating how this character ‘ç’ is translated into the glyph ‘ç’ from the PostScript font file.
The font and input encodings are specified separately, via two dedicated packages: fontenc and inputenc, respectively.
OT1 is the default font encoding, used if nothing else is specified. It can also be specified explicitly, by writing in the preamble of the document:
\usepackage[OT1]{fontenc}
T1 and TS1 are specified by writing instead:
\usepackage[T1]{fontenc}
\usepackage{textcomp}
and LY1 by writing:
\usepackage[LY1]{fontenc}
Each computer platform has a preferred input encoding: for Mac OS it is generally Mac OS Roman, specified by
\usepackage[applemac]{inputenc}
for Unix it is generally ISO Latin 1, specified by
\usepackage[latin1]{inputenc}
and for Windows it is generally Windows Latin 1, specified by
\usepackage[ansinew]{inputenc}
Most text editors on OS X give the option of choosing the input encoding among these three (and more). A safe choice, if you plan to exchange files with other platforms, is to use ISO Latin 1.
Once the encodings have been taken care of, you can select the Example font in a LATEX document 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/22 v1.2 LaTeX support for the Foundry Example font]
\renewcommand{\rmdefault}{fxm}
\endinput
and to put this package in the folder 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}
An idea of what you’ve exactly gained by spending all this time installing the font can be obtained by drawing a chart of its characters and producing some sample text; thanks, again, to Thomas Schmitz for suggesting this step. There are at least three chart-drawing files in gwTEX:
and one sample-producing file:
Before processing, the files must be copied to some writable location, for example by being dragged onto the Desktop. Then:
The font name here is actually the name of a TFM file, corresponding to one variant of the font. It can be, for the font Example in normal weight and upright shape:
| fxmr8r | for 8R encoding |
| fxmr7t | for OT1 encoding |
| fxmr8t | for T1 encoding |
| fxmr8c | for TS1 encoding |
| fxmr8y | for LY1 encoding |
The family name is the common acronym at the beginning of the names of all variants of the font, in our example fxm.
That’s all folks!