path: root/obsolete/support/ttf2tex/ttf2tex.tex

% $Id: ttf2tex.tex,v 0.70 2004/09/30 00:00:00 lehman pub $

\documentclass[a4paper]{ltxdoc}
\usepackage[latin9]{inputenc}
\usepackage[TS1,T1]{fontenc}
\usepackage{lmodern}
\usepackage{tabularx}
\usepackage{longtable}
\usepackage{booktabs}
\usepackage{verbatim}
\usepackage[today]{rcsinfo}
\usepackage{hyperref}
\usepackage{xspace}

\rcsInfo $Id: ttf2tex.tex,v 0.70 2004/09/30 00:00:00 lehman pub $
\setcounter{tocdepth}{1}

%% Tables

\newcolumntype{H}{>{\rmfamily}l}
\newcolumntype{P}{p{75pt}}
\newcolumntype{V}{>{\ttfamily}P}

%% Environments

\makeatletter

\begingroup
  \catcode`\<=\active
  \catcode`\>=\active
  \gdef<{\ensuremath\langle\textit\bgroup}
  \gdef>{\egroup\ensuremath\rangle}
\endgroup

\newenvironment{cmdline}%
  {\catcode`\<=\active
   \catcode`\>=\active
   \def\verbatim@nolig@list{\do\`\do\,\do\'\do\-}%
   \verbatim}
  {\endverbatim}

\newenvironment{options}
  {\catcode`\<=\active
   \catcode`\>=\active
   \def\verbatim@nolig@list{\do\`\do\,\do\'\do\-}%
   \longtable{@{}>{\@noligs\ttfamily}p{0.35\textwidth}@{}p{0.65\textwidth}@{}}}%
  {\endlongtable}

\makeatother

%% Markup

\makeatletter

\DeclareRobustCommand*{\fnurl}{\hyper@normalise\href@fnurl}
\newcommand*{\href@fnurl}[1]{\footnote{\hyper@linkurl{\Hurl{#1}}{#1}}}

\DeclareRobustCommand*{\email}{\hyper@normalise\href@email}
\newcommand*{\href@email}[1]{\href{mailto:#1}{{\texttt{#1}}}}

\newcommand*{\ltxcmd}[1]{\texttt{\textbackslash #1}}
\newcommand*{\ltxpkg}[1]{\texttt{#1}}
\newcommand*{\shenv}[1]{\texttt{\$#1}}
\newcommand*{\shellopt}{\bgroup\@noligs\ttfamily\shell@pt}
\def\shell@pt#1{#1\egroup}
\newcommand*{\shellarg}{\bgroup\@noligs\itshape\shell@rg}
\def\shell@rg#1{\ensuremath\langle#1\ensuremath\rangle\egroup}
\newcommand*{\acr}[1]{\textsc{\MakeLowercase{#1}}}

\makeatother

%% Names, acronyms

\newcommand*{\PS}{Post\-Script\xspace}
\newcommand*{\TT}{True\-Type\xspace}
\newcommand*{\OT}{Open\-Type\xspace}
\newcommand*{\tex}{TeX\xspace}
\newcommand*{\latex}{La\kern-0.07em TeX\xspace}
\newcommand*{\pdftex}{pdfTeX\xspace}
\newcommand*{\tetex}{te\kern-0.07em TeX\xspace}
\newcommand*{\miktex}{MikTeX\xspace}
\newcommand*{\metafont}{Metafont\xspace}
\newcommand*{\xdvi}{\texttt{xdvi}\xspace}
\newcommand*{\dvips}{\texttt{dvips}\xspace}
\newcommand*{\ttftotex}{\texttt{ttf2tex}\xspace}
\newcommand*{\ttftopk}{\texttt{ttf2pk}\xspace}
\newcommand*{\ttftotfm}{\texttt{ttf2tfm}\xspace}
\newcommand*{\vptovf}{\texttt{vptovf}\xspace}
\newcommand*{\ttftoafm}{\texttt{ttf2afm}\xspace}
\newcommand*{\kpathsea}{\texttt{kpathsea}\xspace}

%% Miscellanea

\hyphenation{Free-Type}

\renewcommand*{\abstractname}{End-of-Life Announcement}%
\title{\ttftotex\\A \TT Font Installer for Unix}
\author{Version \rcsInfoRevision}
\date{\today}
\frenchspacing

\begin{document}

\maketitle

\begin{abstract}
\noindent As of September 30, 2004, \ttftotex is no longer maintained or in any way supported by its original author. Active development of the script has in fact already stopped in September 2002. Be advised that, even though \ttftotex may still work, there is no support in case of a problem and there will be no further updates.
\end{abstract}

\tableofcontents

\section{Introduction}

\ttftotex is a script for the Bash shell which generates all files required to use \TT fonts with \tetex from a set of font files. In short, it will do for \TT fonts what fontinst's \ltxcmd{latinfamily} command does for Type~1 \PS fonts. In addition to that, \ttftotex sorts all files, builds the map files required by \ttftopk and \pdftex, and optionally installs everything into either the system-wide local \tex tree or the private \tex tree of the user running \ttftotex. Note that \ttftotex's approach to using \TT fonts with \tex does \emph{not} imply converting them to Type~1 format. With a current version of \tetex and a proper setup, \tex can use \TT fonts via the \ttftopk utility while \pdftex even supports them natively.

\tex itself is actually completely indifferent to the font format since it will merely use the font metrics without accessing the glyph outlines. \ttftopk comes into play when processing the \acr{DVI} file with utilities that do not support \TT fonts natively, such as \dvips or \acr{DVI} readers like \xdvi. \ttftopk will then render the glyphs and provide the result in \acr{PK} font format. \pdftex, on the other hand, has to access the fonts directly when embedding them in a \acr{PDF} file. Fortunately it offers native \TT font support and \ttftotex will supply it with a map file. Please see section \ref{sec:limitations:general} for a discussion of the limitations of this approach.

\section{License}

\ttftotex is copyright \textcopyright\ 2000--2002, 2004 Philipp Lehman. This program is free software; you can redistribute it and\slash or modify it under the terms of the \acr{GNU} General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but \emph{without any warranty}; without even the implied warranty of \emph{merchantability} or \emph{fitness for a particular purpose}. See the \acr{GNU} General Public License for more details.

You should have received a copy of the \acr{GNU} General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, \acr{USA}.

\section{Requirements}\label{sec:requirements}

First of all, you need the Bash shell to run \ttftotex. Ash or plain sh will not work since \ttftotex uses Bash-specific extensions. \ttftotex depends on the utilities \vptovf, \ttftoafm, and \ttftotfm. Both \vptovf and \ttftoafm ship with \tetex and should be available on your system. \ttftotfm is part of the tools that come with an excellent \TT rendering engine called FreeType. You need version 1.3.x or 1.4 of FreeType. 2.x versions will not work because \ttftotfm and \ttftopk have not been ported to FreeType 2 yet. Your Linux distributor or Unix vendor probably provides precompiled FreeType packages. Please consult the canonical sources for your distribution. I'm quite sure that at least all major Linux distributions come with FreeType packages.

Note that you need both the core library and the contributed binaries which might be distributed separately, so make sure you look for names like `freetype' as well as `freetype-contrib' or `freetype-tools'. If your distributor or vendor does not provide FreeType packages you can download\fnurl{http://www.freetype.org/download.html} the source code. You need either the package freetype-1.3.1\fnurl{ftp://ftp.freetype.org/freetype/freetype1/freetype-1.3.1.tar.gz} from the stable branch or the two packages freetype-current\fnurl{ftp://ftp.freetype.org/freetype/unstable/freetype-current.tar.gz} and freetype1-contrib-current\fnurl{ftp://ftp.freetype.org/freetype/unstable/freetype1-contrib-current.tar.gz} from the unstable branch. Note that you have to install the FreeType tools anyway, since you need \ttftopk in order to actually use \TT fonts with \tex and \latex, even though \ttftotex doesn't depend on \ttftopk directly.

There are a few more things you need to do before running \ttftotex for the first time. If you haven't already done so, set up a local \tex tree \shenv{TEXMFLOCAL} and a user \tex tree \shenv{HOMETEXMF} in the global configuration file for \kpathsea, \path{texmf.cnf}. Then run:

\begin{verbatim}
kpsexpand \$TEXMFLOCAL
kpsexpand \$HOMETEXMF
kpsexpand \$TEXMF
\end{verbatim}
%
to verify that these trees are set up properly and included in \shenv{TEXMF}. Also make sure that \shenv{TTFONTS} is set in \path{texmf.cnf}. To verify that, run: \verb|kpsexpand \$TTFONTS|. As to the FreeType tools, make sure that \ttftopk and \ttftotfm were built with \kpathsea support. You can verify that by running them with the \shellopt{--version} option:

\begin{verbatim}
ttf2pk --version
ttf2tfm --version
\end{verbatim}
%
The output should include the \kpathsea version used:

\begin{verbatim}
ttf2pk version 1.4 (kpathsea version 3.3.7)
ttf2tfm version 1.4 (kpathsea version 3.3.7)
\end{verbatim}
%
If it does not, try to find binaries with kpathsea support or build the FreeType tools from source. You might also need to set \shenv{TTF2PKINPUTS} in \path{texmf.cnf} to enable \ttftopk to locate its map file, \path{ttfonts.map}. To find out if doing so is necessary, run: \verb|ttf2pk -t test|. \ttftopk should then print the following error message:

\begin{verbatim}
ttf2pk: ERROR: Cannot find font test in ttfonts.map.
\end{verbatim}
%
This error message implies that \ttftopk managed to locate its map file. The actual error does not matter at this point since we merely want to make sure that \ttftopk is able to find \path{ttfonts.map}. \ttftopk might also exit with the following error message:

\begin{verbatim}
ttf2pk: ERROR: Cannot open file ttfonts.map.
\end{verbatim}
%
This means that \ttftopk did not find its map file at all. In this case you should locate the file \path{ttfonts.map} on your system and define \shenv{TTF2PKINPUTS} in \path{texmf.cnf}. Refer to the documentation of the FreeType tools for details. Note that the file searching mechanism of both \ttftopk and \ttftotfm is explained in the manual page of \ttftotfm. For most systems, the following settings should be fine:

\begin{verbatim}
TTF2PKINPUTS  = .;$TEXMF/ttf2pk//
TTF2TFMINPUTS = .;$TEXMF/ttf2tfm//
\end{verbatim}
%
After that, open the configuration file \path{ttf2tex.cfg} in a text editor and verify that all the paths and file names correspond to your installation. Read the comments given in the file for details. Make sure that there will be exactly one map file for \ttftopk on your system since, unlike \dvips or \pdftex, \ttftopk only supports a single map file called \path{ttfonts.map}. The location of the map file created or updated by \ttftotex is given in the script, make sure that it points to \path{ttfonts.map} if this file already exists. Create symbolic links to resolve any ambiguities if necessary. It is safe to have \ttftotex use an existing map file or a symbolic link pointing to it since it will only append data to the file. \ttftotex will not overwrite it.

\section{Synopsis}\label{sec:synopsis}

\begin{cmdline}
ttf2tex.sh [options] --install --foundry <foundry> --font <font> <family>
\end{cmdline}
%
The \shellopt{--install} or \shellopt{-i} option will create all files, install them, and append all mapping information to your map files using the system-wide local \tex tree. You may use the options in any arbitrary order and mix their long and short forms, but they cannot be concatenated. Options and arguments are as follows:
Mandatory. Use the string \shellarg{foundry} when creating subdirectories. The type foundry is the company which created the font, for example `monotype'. The string \shellarg{foundry} must not contain any spaces.

\begin{options}
--foundry <foundry>\newline -f <foundry> &
Mandatory. Use the string <foundry> when creating subdirectories. The type foundry is the company which created the font, for example `monotype'. This string must not contain any spaces.\\

--font <font>\newline -o <font> &
Mandatory. Use the string <font> when creating subdirectories. This string must not contain any spaces.\\

<family> &
Mandatory. The identifier of the font family, for example \emph{times} or \emph{mns}. The string <family> forms the basis of all file names and is used to identify the font when selecting it under \latex. It must not contain any spaces.\\

--batch\newline -b &
Run in batch mode. By default, \ttftotex will ask for confirmation before processing the fonts. Batch mode skips the confirmation prompt. Please note that \ttftotex itself does not support batch processing. This switch is provided for cases in which it is run from a wrapper script.\\

--log\newline -l &
Write a transcript of your entire \ttftotex session to the file \path{ttf2tex.log} in the working directory. By default, \ttftotex will not create a log file.\\

--typewriter\newline -t &
Treat the font as a typewriter typeface. This option will disable hyphenation for the font by adding a declaration to the font definition file.\\

--expert\newline -x &
Run in expert mode. Use this option to install \OT fonts which offer additional glyphs such as real small caps and old style figures \emph{and} provide valid \PS glyph names. It will implicitly activate \shellopt{--ps-names-only} if required, \shellopt{--caps} will be ignored. See the description of the \shellopt{--ps-names-only} option and section \ref{sec:opentype} for details.\\

--overwrite &
Run in overwrite mode. If this option is used, \ttftotex will overwrite any existing destination files when installing files into the local or private \tex tree. Use with care! Note that the map file for \ttftopk will not be overwritten. If neither \shellopt{--install} nor \shellopt{--user} is used, this option has no effect.\\

--ps-names\newline -n &
Pass the \shellopt{-n} switch to \ttftotfm. This tells \ttftotfm to use the \PS glyph names as given in the font file, but only if a glyph has a valid entry in the active cmap as well. See the \ttftotfm documentation for details.\\

--ps-names-only\newline -N &
Pass the \shellopt{-N} switch to \ttftotfm. This tells \ttftotfm to always use the \PS glyph names as given in the font file and ignore the font's cmaps. See the \ttftotfm documentation for details.\\

--caps <real>\newline -c <real> &
Use the real number <real> to determine the height of (`faked') small caps. The small caps will be <real> times the height of uppercase glyphs. A value of 0.8 for example will create small caps which are 80\% the height of uppercase letters. \shellopt{--help} reports the default value. This option will be ignored if \shellopt{--expert} is used.\\

--slant <real>\newline -s <real> &
Use the real number <real> as obliqueness factor when generating slanted shapes. If this value is larger than zero, the characters slope to the right, otherwise to the left. This number is the tangent of the slant angle, it is usually much smaller than 1. A common choice is 0.167 (about 9.5°). \shellopt{--help} reports the default value.\\
\end{options}

\begin{cmdline}
ttf2tex.sh [options] --user --foundry <foundry> --font <font> <family>
\end{cmdline}
%
The \shellopt{--user} or \shellopt{-u} option will create all the files, install them, and append all mapping information to your map files using the private \tex tree of the user running \ttftotex. Options and arguments as above.

\begin{cmdline}
ttf2tex.sh [options] --foundry <foundry> --font <font> <family>
\end{cmdline}
%
When omitting both \shellopt{--install} and \shellopt{--user}, \ttftotex will build a branch of your \tex tree in the current working directory and allow you to install the files later. Map files will be put into the working branch of \ttftotex as well, no file outside the working directory and its subdirectories will be touched. Options and arguments as above.

\begin{cmdline}
ttf2tex.sh --dump-vectors
\end{cmdline}
%
Dump all internal encoding vectors to the working directory and exit. Any other options given on the command line will be ignored.

\begin{cmdline}
ttf2tex.sh --help
\end{cmdline}
%
Print a brief usage summary including the defaults for \shellopt{--caps} and \shellopt{--slant} and exit. Any other options given on the command line will be ignored.

\section{Usage}

\subsection{Renaming the font files}\label{sec:renaming}

Before invoking \ttftotex, you need to rename the font files in a way that allows \ttftotex to guess the weight and the variant of the font by the name of the file. \ttftotex will search the working directory for all of the files listed in table \ref{tab:files}. These file names are based on the following pattern: \texttt{fam} is the identifier of the whole font family. This string will be used when calling \ttftotex and when selecting the typeface under the new font selection system (\acr{NFSS}) later. The next letter represents the weight of the font. For most text fonts you will only need \texttt{r} and \texttt{b} while some font families come with \texttt{k} and \texttt{d} instead. The next letter, \texttt{i}, indicates an italic font and is omitted for upright shapes. \texttt{16} is a fixed string which indicates Unicode encoding. The `16' is required in the file names although it is in fact a mere matter of naming conventions and not actually used by \ttftotex to determine the encoding. \ttftotex always assumes Unicode encoding.

The weight codes used by \ttftotex are based on the Fontname scheme, a canonical naming system for font files which is also known by the name of its creator as the Karl Berry scheme. \ttftotex follows this scheme to a certain extend. Technically, canonical font naming is by no means required to use the fonts with a single \tex installation, although it is always a good idea when dealing with large numbers of fonts. If you are not interested in canonical naming you will find all you need to know in order to use \ttftotex in table \ref{tab:files}.

\begin{table}
\small
\begin{tabularx}{\textwidth}{@{}X@{}V@{}V@{}V@{}}
\toprule
\multicolumn{1}{@{}H}{Weight} & \multicolumn{1}{@{}H}{Code} & \multicolumn{2}{@{}H}{File name} \\
\cmidrule{3-4}
&& \multicolumn{1}{@{}H}{Upright} & \multicolumn{1}{@{}H}{Italic} \\
\cmidrule(r){1-1}\cmidrule(r){2-2}\cmidrule(r){3-3}\cmidrule{4-4}
ultra light, thin, hairline	& a	& fama16.ttf	& famai16.ttf\\
extra light			& j	& famj16.ttf	& famji16.ttf\\
light				& l	& faml16.ttf	& famli16.ttf\\
book				& k	& famk16.ttf	& famki16.ttf\\
regular				& r	& famr16.ttf	& famri16.ttf\\
medium				& m	& famm16.ttf	& fammi16.ttf\\
demibold			& d	& famd16.ttf	& famdi16.ttf\\
semibold			& s	& fams16.ttf	& famsi16.ttf\\
bold				& b	& famb16.ttf	& fambi16.ttf\\
extra bold			& x	& famx16.ttf	& famxi16.ttf\\
heavy				& h	& famh16.ttf	& famhi16.ttf\\
black				& c	& famc16.ttf	& famci16.ttf\\
ultra bold			& u	& famu16.ttf	& famui16.ttf\\
poster				& p	& famp16.ttf	& fampi16.ttf\\
\bottomrule
\end{tabularx}
\caption{Weights and file names supported by \ttftotex}
\label{tab:files}
\end{table}

\subsection{Canonical font naming}

There is a fairly elaborate canonical naming scheme used for the Type~1 fonts that come with \tetex as well as by fontinst, the \tex Type~1 font installation utility. You can read the documentation of the Fontname naming system online\fnurl{http://www.ctan.org/tex-archive/info/fontname} or download it as a tarball\fnurl{ftp://tug.ctan.org/tex-archive/info/fontname.tar.gz} from any \acr{CTAN} \acr{FTP} mirror. See the file \path{fontname.dvi} for an overview as well as excerpts from various map files and browse the \path{.map} files for the complete listings. Of course these lists can't cover all the fonts out there, so you might still need to create your own identifiers. Note that the way \ttftotex handles fonts differs slightly from what is described there. \ttftotex will only recognize the two variants `upright' and `italic' when parsing the file names and it does not recognize any widths (e.\,g. `condensed' or `narrow') at all. The Fontname naming system as described in the document mentioned above is based on the pattern:

\begin{verbatim}
S TT W [V...] [NN] [E] [DD]
\end{verbatim}
%
\texttt{S} indicates the supplier (foundry), \texttt{TT} the typeface (two letters), \texttt{W} the weight, \texttt{V} the variant(s) (one or more letters), \texttt{NN} the encoding (usually two letters), \texttt{E} the expansion (width) and \texttt{DD} the design size. Square brackets indicate an italic font and omitted for upright shapes. \ttftotex however can only handle the pattern:

\begin{verbatim}
S TT... W [V] 16
\end{verbatim}
%
That is, the design size is omitted (it is not used with linearly scalable fonts anyway, even in the Fontname scheme) and the expansion as well as all variants other than italic have to become part of the font family name which is not limited to two characters. If you want to name the font files according to the canonical scheme, you have to take this into account~-- and can only follow the scheme to a certain extend, although you probably won't run into problems when dealing with most standard typefaces. But if a given font family offers both regular and condensed fonts for example, you will have to split it into two separate families. See section \ref{sec:limitations:ttf2tex} for more details. Finally, \texttt{NN} is fixed to `16'. You won't find the code `16' in the Fontname scheme which only covers 7 and 8-bit encodings since \tex can't handle 16-bit encodings anyway.

\subsection{Running \ttftotex}\label{sec:runscript}

Invoke \ttftotex as described in section \ref{sec:synopsis}.  The \emph{family} argument corresponds to the string \texttt{fam} as explained in section \ref{sec:renaming}. The names used in conjunction with the \shellopt{--foundry} and \shellopt{--font} options must not contain any spaces. By convention, these names will be used to create subdirectories, their sole purpose is to keep your installation clearly arranged.

\subsection{Configuring \pdftex}

\ttftotex will create the file \path{fam.map}, where \texttt{fam} is the identifier of the font family according to section \ref{sec:renaming}. You have to add the name of this map file to the main configuration file for \pdftex, \path{pdftex.cfg}, so that it contains a line like \path{map +fam.map}.

\section{Using the fonts}

\subsection{\TT fonts}

The weight codes employed when renaming the fonts files follow the Fontname scheme while the \acr{NFSS} uses a different set of codes to determine what is called a `series'. You need to know about the \acr{NFSS} series codes which \ttftotex uses when creating font definition files if you want to select weights other than regular and bold. Table \ref{tab:series} lists all supported weights with the corresponding weight and series codes. The Fontname weight codes are what you were using when renaming the font files while the \acr{NFSS} series codes are what you will need when selecting a certain weight under \latex.

\begin{table}
\small
\begin{tabularx}{\textwidth}{@{}X@{}V@{}V@{}V@{}}
\toprule
\multicolumn{1}{@{}H}{Weight} & \multicolumn{1}{@{}H}{Fontname} & \multicolumn{2}{@{}H}{\acr{NFSS}} \\
\cmidrule{3-4}
&& \multicolumn{1}{@{}H}{ttf2tex} & \multicolumn{1}{@{}H}{fontinst} \\
\cmidrule(r){1-1}\cmidrule(r){2-2}\cmidrule(r){3-3}\cmidrule{4-4}
ultra light, thin, hairline	& a	& ul*	& ---\\
extra light			& j	& el*	& ---\\
light				& l	&  l	&  l\\
book				& k	&  k*	&  m\\
regular				& r	&  m	&  m\\
medium				& m	& mb	& mb\\
demibold			& d	& db	& db\\
semibold			& s	& sb	& sb\\
bold				& b	&  b	&  b\\
extra bold			& x	& eb	& eb\\
heavy				& h	& hb*	& eb\\
black				& c	& cb*	& eb\\
ultra bold			& u	& ub	& ub\\
poster				& p	& pb*	& ---\\
\emph{default boldface}		& d,s,b	& bx	& ---\\
\bottomrule
\end{tabularx}
\caption{Weights and \acr{NFSS} series codes with \ttftotex extensions (*)}
\label{tab:series}
\end{table}

The series codes used by \ttftotex correspond to those used by fontinst. There is only one minor difference which you will probably not notice in most cases but which might come in handy if you install a very comprehensive font family. By default, fontinst supports 11 weights and maps them to eight \acr{NFSS} series while \ttftotex uses a one-to-one mapping scheme for all 14 weights defined in the Fontname scheme. For this purpose six new font series specific to \ttftotex are introduced. They are marked with an asterisk in table \ref{tab:series}. This difference is normally not visible from a user perspective as \ttftotex uses aliases to ensure fontinst-like behavior. If, for example, a `heavy' weight is provided, it will be available as both `hb' and `eb' unless an `extra bold' font was provided as well. If a font family comes with multiple weights which would be mapped to `eb' under the fontinst scheme, however, these extensions will allow you to conveniently use all of them without modifying any font definition files.

When looking at table \ref{tab:series}, you will also notice that one series has a special meaning for \ttftotex: the bold extended (\texttt{bx}) series. Bold extended is basically a perfectly valid \acr{NFSS} series and Computer Modern actually provides bold extended fonts. \ttftotex however deliberately (ab)uses it to set a default bold face. The fact that \ltxcmd{bfdefault} defaults to \texttt{bx} while most font families don't come with bold extended fonts provides a way to set a font-specific default bold face in the font definition file. For most font families \texttt{bx} will probably end up as an alias for \texttt{b} in the font definition file, but if one of the more moderate bold weights `semibold' or `demibold' is available, \ttftotex will prefer that. Note that this is intended as a fallback mechanism only. If multiple bold weights are available it is a good idea to set \ltxcmd{bfdefault} to the desired value explicitly.

\subsection{\OT fonts}\label{sec:opentype}

Essentially, there are two types of \OT fonts: those with \PS glyph data (\textsc{cff} fonts, file suffix \path{.otf}) and those with \TT glyph data (file suffix \path{.ttf}). Only the latter variant is supported by \ttftotex since it is the only one currently supported by both \ttftopk and \pdftex. \OT fonts with \TT glyph data (or rather: \TT fonts with \OT extensions, because that's what they are in essence) are installed and used like any other \TT font. Since \tex does not make use of the advanced typesetting features provided by \OT fonts, the main difference is the wealth of glyphs available in these fonts. To exploit that, you need to run \ttftotex with the \shellopt{--expert} option.

When using this option, \ttftotex will create three font families: \texttt{fam}, \texttt{famx}, and \texttt{famj}. \texttt{fam} is generated like any other family but uses real small caps instead of `faked' ones, \texttt{famx} adds expert f-ligatures (`ff', `ffi', `ffl'), and \texttt{famj} adds expert f-ligatures as well as old style figures. Accessing the additional glyphs implies using \PS glyph names. This is equivalent to using the \shellopt{--ps-names-only} option, but only where required. This is the case for all fonts of the \texttt{famx} and \texttt{famj} families as well as all small caps fonts of the \texttt{fam} family. Note that this can only work if the font files actually contain valid \PS glyph names. If you experience problems with missing or faulty glyphs this is most likely not the case~-- and there is nothing \ttftotex can do about that.

\section{Tutorial}

Let's assume you would like to use Monotype's Times New Roman with \latex. You have also prepared everything as explained in section \ref{sec:requirements}. First, create a working directory and copy the font files there. By default, \ttftotex will not overwrite files when installing fonts into your \tex tree, but it does assume that the working directory contains nothing but the font files you want to install. Identify the regular, italic, bold, and bold italic versions by viewing the files either with a utility such as gfontview or with the bare-bones ftview that comes with FreeType (press \texttt{q} to close the window, by the way). In the latter case you might want to run ftdump to get the \PS name of the font and to read the copyright notice as found in the header of the font file:

\begin{verbatim}
gfontview $PWD
ftview -g -r 24 ppem file.ttf
ftdump file.ttf | less
\end{verbatim}
%
The \PS name will usually tell you about the exact weight while the copyright notice contains the name of the font foundry. Rename the files as explained in section \ref{sec:renaming}. You should at least come up with something like this:

\begin{verbatim}
timesr16.ttf    timesri16.ttf
timesb16.ttf    timesbi16.ttf
\end{verbatim}
%
If you went one step further and decided to use more canonical names derived from the Fontname scheme (in this case we could even use the scheme in a strict manner), the font identifier would be \texttt{mns} instead of \texttt{times}:

\begin{verbatim}
mnsr16.ttf      mnsri16.ttf
mnsb16.ttf      mnsbi16.ttf
\end{verbatim}
%
Here \texttt{m} denotes Monotype, \texttt{ns} Times New Roman, \texttt{r}, \texttt{ri}, \texttt{b}, and \texttt{bi} indicate weight and variant and \texttt{16} means Unicode encoding. I will use \texttt{mns} as the font family name for the remainder of this tutorial. After renaming the font files, call \ttftotex with the appropriate font family name:

\begin{verbatim}
ttf2tex.sh --install --foundry monotype --font timesnew mns
\end{verbatim}
%
You will see a lot of messages on the console. These will probably include warning messages about glyphs not being found, since a few glyphs defined in \textsc{t1} encoding are missing from the \textsc{wgl4} glyph set covered by this font. The glyphs which are usually reported as missing in ordinary \TT fonts include the f-ligatures `ff', `ffi', and `ffl'. This only means that the missing ligatures will not be typeset as a single glyph but as a sequence of glyphs~-- just like any other character. Ligatures like these are only found in expert encoded Type~1 \PS and in \OT fonts. Ordinary \TT fonts usually do provide the essential ligatures `fi' and `fl', though. If you want to view a table of all \textsc{t1} encoded glyphs available to \tex and \latex, run plain \tex on \path{testfont.tex} after installing everything and view the resulting \acr{DVI} file:

\begin{verbatim}
echo -e "mnsr8t\n\\\\table\\\\bye" | tex testfont.tex
\end{verbatim}
%
The situation is worse for \textsc{ts1} encoding since it is much more exotic and defines glyphs which are usually not available in text fonts. But you should still get the most common symbols such as currency signs and other frequently used symbols like `copyright' or `registered'. You can use the \ltxpkg{textcomp} package as usual to get access to these symbols. The following command will create a complete table for \textsc{ts1} encoding:

\begin{verbatim}
echo -e "mnsr8c\n\\\\table\\\\bye" | tex testfont.tex
\end{verbatim}
%
\ttftotex will create a map file for \pdftex called \path{mns.map}. You have to add that to the main \pdftex configuration file, \path{pdftex.cfg}:

\begin{verbatim}
% default map file provided by tetex
map pdftex.map
% additional map file created by ttf2tex
map +mns.map
\end{verbatim}
%
That's it. Now you may create a test document to try your new font out. There are no peculiarities specific to \TT fonts when selecting them under \latex. Just keep in mind that, when using \acr{DVI} or \PS as preview format, the first run with the new fonts will take a little longer since \ttftopk has to generate all \acr{PK} fonts required to display the document. Subsequent runs will be much faster because, as with \metafont fonts, \acr{PK} fonts generated by \ttftopk are cached in \shenv{VARTEXFONTS}. To select the fonts simply employ the standard \acr{NFSS} commands as documented in chapter 2 of the \latex font selection guide. This guide ships with \tetex as \path{fntguide.dvi} and is also available in \acr{PDF} format from \acr{CTAN}.\fnurl{http://www.ctan.org/tex-archive/macros/latex/doc/fntguide.pdf} For example, to select Times New Roman anywhere in your document use a command like:

\begin{verbatim}
\fontencoding{T1}\fontfamily{mns}\selectfont
\end{verbatim}
%
To use Times New Roman as the default roman typeface for the whole document, redefine \ltxcmd{rmdefault} in the preamble:

\begin{verbatim}
\renewcommand{\rmdefault}{mns}
\end{verbatim}
%
If your typeface provides more than two weights you can select one of them by using the \ltxcmd{fontseries} command in conjunction with the \acr{NFSS} series codes listed in table \ref{tab:series}. To select the demibold (\texttt{db}) weight for example, use the following command:

\begin{verbatim}
\fontseries{db}\selectfont
\end{verbatim}
%
Compact font switching commands such as \ltxcmd{textbf} or \ltxcmd{bfseries} will work as usual, but keep in mind that they are using \ltxcmd{bfdefault} as the bold weight. If you want \ltxcmd{textbf} and \ltxcmd{bfseries} to use demibold instead, simply redefine \ltxcmd{bfdefault} accordingly:

\begin{verbatim}
\renewcommand{\bfdefault}{db}
\end{verbatim}
%
Finally, you might want to write a \path{.sty} file that sets Times New Roman as the default roman typeface. Here is a sample file, install it as \path{timesnew.sty}:

\begin{verbatim}
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{timesnew}
\RequirePackage[T1]{fontenc}
\RequirePackage{textcomp}
\renewcommand{\rmdefault}{mns}
\endinput
\end{verbatim}
%
Now all you need to do in order to use your new typeface is to put the command \ltxcmd{usepackage{timesnew}} in your document's preamble.

\section{Hints and limitations}\label{sec:limitations}

\subsection{General limitations}\label{sec:limitations:general}

There are two limitations when using \TT fonts with \tex and \latex according to \ttftotex's approach, both of which are beyond \ttftotex's control:  you can't produce resolution independent \PS and you can't use slanted fonts in \acr{PDF} files. The main problem with \PS is the fact that \dvips does not support \TT fonts. When the \acr{DVI} file is processed, \dvips implicitly calls \ttftopk to render the fonts and embeds them in bitmap format in the \PS file. Since the rendering quality of \ttftopk is excellent, the resulting \PS will look fine when printed at the corresponding resolution, but keep in mind that it is not portable. When using \dvips, you face a situation similar to that of \metafont fonts. That doesn't mean that you can't print or view the \PS file on other machines, but the font quality might be unsatisfactory if the resolutions don't match. If you need truly portable files, use \pdftex instead.

As mentioned in the introduction, \pdftex offers native \TT font support. Compared to Type~1 fonts there is only one minor limitation when producing \acr{PDF}: it does not support slanting or extending of \TT fonts. For this reason, some lines in the map file which \ttftotex creates for \pdftex are commented out. Otherwise \pdftex would complain whenever it reads its map files. If you try to use `faked' slanted shapes of \TT fonts with \pdftex, these fonts will be missing in the resulting \acr{PDF} file. You can work around this issue be making sure that all \acr{PK} fonts required to typeset the slanted parts have been generated by \ttftopk before you run \pdftex. But note that this would mean using bitmap fonts since the slanted fonts will end up in bitmap Type~3 format in your \acr{PDF} file~-- something you were probably trying to avoid by using vector fonts in the first place. In short, don't use slanted fonts if you want to produce a \acr{PDF} file. If you want to make sure that no \acr{PK} fonts were embedded in a \acr{PDF} file, simply look at the console output of \pdftex. Here is a short excerpt of \pdftex's output as it is processing a file using the font from the tutorial:

\begin{verbatim}
</var/spool/texmf/pk/modeless/monotype/timesnew/mnsbo16t.600
pk>{/usr/local/share/texmf/pdftex/T1-WGL4.enc}<mnsbi16.ttf><
mnsb16.ttf></var/spool/texmf/pk/modeless/monotype/timesnew/m
nsro16t.600pk><mnsri16.ttf><mnsr16.ttf>
\end{verbatim}
%
You can tell by this that two types of fonts were embedded in the \acr{PDF} file: the fonts with a \path{.ttf} extension are \TT fonts while the ones with the extension \path{.600pk} are \acr{PK} fonts, where 600 is their resolution in dpi. Alternatively, you can use Acrobat Reader's font information dialog or the \path{pdffonts} utility that comes with recent versions of xpdf to verify the format of the fonts embedded in the \acr{PDF} file. All \acr{PK} fonts will be listed as `Type~3'. When printed on a 600\,dpi printer, this file will look excellent and you won't be able to tell the difference between \TT and \acr{PK} fonts at all. When viewed with Acrobat Reader however, the slanted fonts will look very poor. You have probably seen this distortion of embedded bitmap fonts which are scaled and anti-aliased before when using \metafont versions of the Computer Modern fonts. Note that Ghostscript (including all frontends based on it) does a much better job when dealing with bitmap Type~3 fonts.

This issue does not affect `faked' small caps as these are simulated by typesetting (tall) caps at a smaller size which does not imply any manipulation of the glyph outlines. It also doesn't affect \ttftopk and all applications which implicitly rely on it when processing \acr{DVI} files (\dvips, \acr{DVI} viewers), since \ttftopk is capable of manipulating the glyph outlines of \TT fonts.

\subsection{Limitations specific to \ttftotex}\label{sec:limitations:ttf2tex}

\ttftotex supports \textsc{t1} (Cork) and \textsc{ts1} (Text Companion) encoding only and is thus limited to European languages and to typesetting text. If you want to typeset math, you need to use a different font in math mode. If you don't change any default settings apart from what is suggested in this manual, this is precisely what is going to happen.

There is no support for multiple widths within one font family. If you have a large font family which comes with regular as well as condensed or narrow fonts you have to treat all widths as separate families. This is in fact a rather academic issue as there are no compact width switching commands anyway. Since the \acr{NFSS} doesn't have independent concepts of weight and width, separating the width from the weight by splitting up font families even makes sense in a way. After all, you don't use a condensed font the way you use boldface.

Variants are limited to upright and italics. Oblique fonts are treated as italics when running \ttftotex and have to be renamed accordingly. Like the previous point this is essentially a font naming issue. \ttftotex doesn't care if the font file provided for, say, the roman upright shape is in fact a script, an old English, or a titling typeface, but you can't use canonical names for such fonts and you may need to split up the font family.

`Faked' slanted shapes are supported for all typefaces including those which actually provide an oblique variant. Oblique fonts are basically slanted derivatives of the corresponding upright shape. They differ from `faked' slanted shapes in that they were actually drawn by the font designer and not generated by a machine. The italics of most sans serif and typewriter fonts are in fact oblique shapes. If you install such a typeface with \ttftotex and want to use its real oblique shape, simply call the italic version. If you call the slanted version explicitly, you will get a `faked' slanted shape derived from the upright shape by \ttftopk. This is not a limitation but intentional.

\subsection{Problems with \ttftopk}

If \xdvi and \dvips cause problems while \pdftex works fine, this usually indicates a problem with \ttftopk. As mentioned before, \pdftex features native support for \TT fonts while \xdvi and \dvips depend on \ttftopk. Note that this difference is only relevant when creating \acr{PDF} files. When creating \acr{DVI} output, it does not matter whether the \tex binary you are using is based on \pdftex or traditional \tex as the \acr{DVI} file does not contain any fonts. This is a typical error message you might get when running \xdvi or \dvips:

\begin{verbatim}
kpathsea: Running mktexpk --mfmode ljfive --bdpi 600 --mag 1+0/600 --dpi 600 mns
r16t
mktexpk: Running mf \mode:=ljfive; mag:=1+0/600; nonstopmode; input mnsr16t
This is METAFONT, Version 2.7182 (Web2C 7.3.7)
kpathsea: Running mktexmf  mnsr16t

! I can't find file `mnsr16t'.
<*> ...e; mag:=1+0/600; nonstopmode; input mnsr16t
                                                  
Please type another input file name
! Emergency stop.
<*> ...e; mag:=1+0/600; nonstopmode; input mnsr16t
                                                  
Transcript written on mfput.log.
grep: mnsr16t.log: No such file or directory
mktexpk: `mf \mode:=ljfive; mag:=1+0/600; nonstopmode; input mnsr16t' failed to 
make mnsr16t.600pk.
\end{verbatim}
%
Whenever \ttftopk fails, the script \path{mktexpk}, which generates \acr{PK} fonts on demand, falls back to \metafont which will obviously always fail with \TT fonts. To track down the real cause of the problem, run \ttftopk with the \shellopt{-t} option and the font mentioned in the error message from the command line: \verb|ttf2pk -t mnsr16t|. With a working setup, \ttftopk will print the line from its map file that matches the requested font:

\begin{verbatim}
This is ttf2pk version 1.4
mnsr16t   mnsr16.ttf   Encoding=T1-WGL4.enc
\end{verbatim}
%
In case of a problem, there are two possible scenarios:

\begin{verbatim}
This is ttf2pk version 1.4
ttf2pk: ERROR: Cannot open file ttfonts.map.
\end{verbatim}
%
This error message means that \ttftopk can't find its map file at all. In this case you should locate \path{ttfonts.map} on your system and set \shenv{TTF2PKINPUTS} in the global configuration file for \kpathsea, \path{texmf.cnf}, as explained in section \ref{sec:requirements} of this manual.

\begin{verbatim}
This is ttf2pk version 1.4
ttf2pk: ERROR: Cannot find font mnsr16t in ttfonts.map.
\end{verbatim}
%
This error message means that \ttftopk found its map file, but the requested font is not listed. If \ttftotex didn't report any errors while installing the fonts, this usually indicates that there are multiple copies of \path{ttfonts.map} on your system and that \ttftotex and \ttftopk use different ones. In this case you should verify the path to \path{ttfonts.map} as given in the header of \path{ttf2tex.sh}, check the \shenv{TTF2PKINPUTS} variable if set, and make sure that there is only one copy of \path{ttfonts.map} on your system. After that, fix the map file manually or rerun \ttftotex to reinstall the fonts. Please note that \ttftotex does not remove old lines form \path{ttfonts.map}. If there is a problem with \path{ttfonts.map}, always double-check the file and eliminate duplicate mapping lines.

\section{Acknowledgments}

\ttftotex was inspired by a tutorial\fnurl{http://www.radamir.com/tex} written by Damir Rakityansky which explains how to use \TT fonts with \miktex. I would also like to thank Vaggelis Kapoulas, Werner Lemberg, and Bruce D'Arcus for their help, contributions, and feature suggestions.

\end{document}