path: root/info/tex-font-errors-cheatsheet/tex-font-cheatsheet.tex

%% tex-font-cheatsheet.tex
%% Copyright (C) 2009, 2010 Nico Schlömer
%
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3
% of this license or (at your option) any later version.
% The latest version of this license is in
%   http://www.latex-project.org/lppl.txt
% and version 1.3 or later is part of all distributions of LaTeX
% version 2005/12/01 or later.
%
% This work has the LPPL maintenance status `maintained'.
%
% The Current Maintainer of this work is Nico Schlömer.
%
\documentclass[10pt]{scrartcl}

\usepackage{lmodern}
\usepackage[T1]{fontenc}
\usepackage{microtype}

\usepackage{fixltx2e}
\usepackage{csquotes}

% \usepackage{MinionPro}
% \usepackage{MyriadPro}
% \usepackage{beramono}
\renewcommand{\familydefault}{\sfdefault}

\usepackage[margin=0.5in]{geometry}

\usepackage{listings}  % include highlighted source code
\lstset{% general command to set parameter(s)
basicstyle=\ttfamily, % print whole listing small
keywordstyle=\color{myDarkBlue},
identifierstyle=,
commentstyle=\color{myDarkGreen},
stringstyle=\color{myAccentRed},
showstringspaces=false,     % no special string spaces
frame=single,
language=[LaTeX]Tex
}

\usepackage{tabularx}
\usepackage{booktabs}

\usepackage{tikz}
\usetikzlibrary{shapes}
\usetikzlibrary{arrows}
\usetikzlibrary{decorations}

\usepackage{fancyvrb}

% define colors from the KDE color scheme
\usepackage{xcolor}
\definecolor{myDarkBlue}{RGB}{27,45,131}
\definecolor{myLightBlue}{RGB}{197,217,240}

% \definecolor{myDarkGreen}{RGB}{0,102,47}
% \definecolor{myLightGreen}{RGB}{171,215,188}
\definecolor{myDarkGreen}{RGB}{83,147,22}
\definecolor{myLightGreen}{RGB}{180,213,151}

\definecolor{myDarkYellow}{RGB}{249,186,7}
\definecolor{myLightYellow}{RGB}{255,245,146}
\definecolor{myDarkGray}{RGB}{0,0,28}
\definecolor{myLightGray}{RGB}{235,236,237}
\definecolor{myAccentYellow}{RGB}{255,220,0}
\definecolor{myAccentRed}{RGB}{231,35,0}


\newcommand{\ttffile}{\texttt{\$TTF\_FILE}}
\newcommand{\encfile}{\texttt{\$ENC\_FILE}}

\newcommand{\sampleshort}{
\begin{tabular}{p{2.5ex}@{}p{2.5ex}@{}p{2.5ex}@{}p{2.5ex}@{}p{2.5ex}@{}p{2.5ex}@{}p{2.5ex}@{}p{2.5ex}@{}p{2.5ex}@{}p{2.5ex}@{}p{2.5ex}@{}p{2.5ex}@{}p{2.5ex}@{}p{2.5ex}@{}p{2.5ex}}
0 & 1 & 2 & 3 & 4 & 5 & 6 & 7 & 9 &\\
a & b & c & d & e & f & g & h & i & j & k & l & m\\
n & o & p & q & r & s & t & u & v & w & x & y & z\\
A & B & C & D & E & F & G & H & I & J & K & L & M\\
N & O & P & Q & R & S & T & U & V & W & X & Y & Z
\end{tabular}%
% {0}{1}{2}{3}{4}{5}{6}{7}{8}{9}\\
% {a}{b}{c}{d}{e}{f}{g}{h}{i}{j}{k}{l}{m}{n}{o}{p}{q}{r}{s}{t}{u}{v}{w}{x}{y}{z}\\
% {A}{B}{C}{D}{E}{F}{G}{H}{I}{J}{K}{L}{M}{N}{O}{P}{Q}{R}{S}{T}\\
% {U}{V}{W}{X}{Y}{Z}
}

\newcommand{\sample}{
\begin{tabular}{p{2.5ex}@{}p{2.5ex}@{}p{2.5ex}@{}p{2.5ex}@{}p{2.5ex}@{}p{2.5ex}@{}p{2.5ex}@{}p{2.5ex}@{}p{2.5ex}@{}p{2.5ex}@{}p{2.5ex}@{}p{2.5ex}@{}p{2.5ex}@{}p{2.5ex}@{}p{2.5ex}}
0 & 1 & 2 & 3 & 4 & 5 & 6 & 7 & 9 &   &\\
a & b & c & d & e & f & g & h & i & j & k & l & m & n\\
o & p & q & r & s & t & u & v & w & x & y & z\\
A & B & C & D & E & F & G & H & I & J & K & L & M & N\\
O & P & Q & R & S & T & U & V & W & X & Y & Z
\end{tabular}%
% {0}{1}{2}{3}{4}{5}{6}{7}{8}{9}\\
% {a}{b}{c}{d}{e}{f}{g}{h}{i}{j}{k}{l}{m}{n}{o}{p}{q}{r}{s}{t}{u}{v}{w}{x}{y}{z}\\
% {A}{B}{C}{D}{E}{F}{G}{H}{I}{J}{K}{L}{M}{N}{O}{P}{Q}{R}{S}{T}\\
% {U}{V}{W}{X}{Y}{Z}
}

\begin{document}

\centering

% ============================================================================
% START page 1
% ============================================================================
\section*{\TeX{} font errors: Cheatsheet}

\begin{tikzpicture}
[auto,
decision/.style = {diamond, draw=myDarkBlue, thick, fill=myLightBlue, text width=4.5em, text badly centered,inner sep=1pt},
block/.style    = {rectangle, draw=myDarkBlue, thick, fill=myLightBlue, text width=5em, text centered, rounded corners, minimum height=4em},
line/.style     = {draw, thick, -latex',shorten >=2pt},
error/.style    = {draw=myAccentRed, thick, fill=red!20, minimum height=2em},
error_number/.style  = {starburst, fill=myAccentYellow, draw=myAccentRed, line width=2pt,starburst points=17},
warning_number/.style  = {starburst, fill=myAccentYellow, draw=myAccentRed, line width=0.5pt,starburst points=7},
crookedoutput/.style   = {draw=myDarkYellow, thick, fill=myLightYellow, text width=5cm,minimum height=2em, inner sep=2ex},
output/.style   = {draw=myDarkGreen, thick, fill=myLightYellow, text width=5cm,minimum height=2em, inner sep=2ex}
]

% \node[starburst, fill=myAccentYellow, draw=myAccentRed, line width=2pt] {\bf BANG!};

% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
% *** matrix
% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
\matrix [column sep=5mm,row sep=7mm]
{
% row 0
% &
% \node [block] (sty_latex) {\LaTeX +sty};&
\node [block] (declare_latex) {\LaTeX};&
\node [block] (tex) {\TeX{}\textsuperscript{2}}; \\
% row 1
% \node [error_number] (no_sty) {1};&
% \node [decision] (sty_exist) {STY file found?};&

\node [decision] (fd_exist) {Font declared?\textsuperscript{1}}; &
\node [decision] (tfm_exist) {TFM file\textsuperscript{3} found?};&
\node [error_number] (no_tfm) {2};\\
% row 3
&
\node [decision] (vf_exist) {VF file\textsuperscript{3} found?}; &
\node [decision] (rtfm_exist) {Raw TFM file\textsuperscript{3}~found?};\\
% row 4
&
\node [decision] (fi_suff) {Font info sufficient?};&\\
% row 4b
&
\node [decision] (map_exist) {Map file in \TeX's cache?};
&\node [error_number] (no_map) {4};\\
% row 5
&
\node [decision] (enc_exist) {ENC file found?};&
\node [error_number] (no_encoding) {5};\\
% row 6
&
\node [decision] (ttf_exist) {PFM/TTF file found?};&
\node [error_number] (no_ttf) {6};\\
};
% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
% *** END matrix
% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
% *** output nodes
% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
\node (fallback_output) at (-10,7) [crookedoutput] {\fontfamily{cmr}\fontseries{m}\fontshape{n}\selectfont An output file with a fallback font (usually \texttt{cmr}) will be generated .\\\sampleshort\\ };
\node (output_flawless)at(-7,-12) [output,text width=7cm]   {\fontfamily{MinionPro-TOsF}\fontseries{m}\fontshape{n}\selectfont Done!\\
\sampleshort\\
Depending on whether or not your TFM/VF file contains kerning and ligature tables, the quality of your document might vary (see note~${}^4$). Compare, for example,
\begin{center}
\begin{tabular}{cc}
\toprule
% good  & bad\\\midrule
Table & {T}able\\
ffi   & {f}{f}i\\
---   & {-}{-}{-}\\
?`    & {?}`\\\bottomrule
\end{tabular}
\end{center}
};
% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
% *** END output nodes
% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -


% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
% *** paths
% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
\begin{scope}[every path/.style=line]
% \path (sty_latex) -- (sty_exist);
% \path (sty_exist)-- node [near start] {no} (no_sty);
% \path (sty_exist)-- node [near start] {yes} (fd_exist);
\path (tex) -- (tfm_exist);
\path (declare_latex) -- (fd_exist);
% \path (fd_exist) -- node [midway] {no} (no_fd);
\path (fd_exist) -- node [near start] {no}
                    node [above,near end] {\tikz\node [warning_number] (no_fd) {1};} (fallback_output);
\path (fd_exist) -- node [near start] {yes} (tfm_exist);
\path (tfm_exist) -- node [near start] {no} (no_tfm);
\path (tfm_exist) -- node [near start] {yes} (vf_exist);
\path (vf_exist) -- node [near start] {no\textsuperscript{4}} (fi_suff);
\path (map_exist) -- node [near start] {yes} (enc_exist);
\path (enc_exist) -- node [near start] {yes} (ttf_exist);
\path (ttf_exist) -- node [near start] {yes} (output_flawless);
\path (vf_exist) -- node [near start] {yes} (rtfm_exist);
\path [double,-] (rtfm_exist) -- node [near start,above] {\tikz\node [error_number] (no_fd) {3};} (tfm_exist);
\path (rtfm_exist) -- node [near start] {yes} (fi_suff);
\path (fi_suff)    -- node [near start] {yes} (map_exist);
\path (fi_suff)    -- node [near start] {no} (no_map);
\path (rtfm_exist) -- node [right,near start] {no} (no_tfm);
\path (map_exist) -- node [near start] {no} (no_map);
\path (enc_exist) -- node [near start] {no} (no_encoding);
\path (ttf_exist) -- node [near start] {no} (no_ttf);
% \path (rmap_exist) -- node [midway] {yes}(rencttf_exist);
% \path (rencttf_exist) -- node [midway] {yes} (output_flawless);
\end{scope}
% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
% *** END paths
% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -


% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
% *** notes
% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
\begin{scope}[xshift=-8cm,yshift=-1.5cm]
\node (0,0)[rectangle, draw=myDarkGray, thick, fill=myLightGray, text width=9cm, text centered, rounded corners, inner sep=2ex]{
\begin{minipage}[t]{9cm}
\begin{center}
Notes
\end{center}
\begin{tabularx}{\textwidth}{lX}
\textsuperscript{1} & To use a font in {\LaTeX}, you need to connect \LaTeX's font definition -- given as \texttt{fontfamily} (e.g., Computer Modern Roman, \texttt{cmr}), \texttt{fontseries} (e.g., bold, \texttt{b}), and \texttt{fontsshape} (e.g, upright, \texttt{n}) -- with an actual {\TeX} font. This happens most commonly in an FD file, but can also be accomplished in the {\LaTeX} source file itself.\\[2mm]
\textsuperscript{2} & Even if you're not fluent in \TeX, it's quite easy to actually test a font with it, and that's what you should do if things are not working as expected in \LaTeX. On the command line, just go \texttt{pdftex~testfont}, then give your font's (\TeX) name, ask {\TeX} to \texttt{$\backslash$sample}, and say \texttt{$\backslash$bye}. What you'll get is a nice prototype document of your font.\\[2mm]
\textsuperscript{3} & Your font definition declares a \TeX{} font name and \TeX{} looks for \texttt{[r]TeX-font-name.\{tfm,vf\}}.\\[2mm]
\textsuperscript{4} & If no further errors occur, your document will probably compile fine without a font-related warning message at all. However, you appear to use the raw TFM directly without the VF detour. This way, {\TeX} will not have access to kerning and ligature information; hence, for example, \enquote{\texttt{{-}{-}{-}}} and \enquote{\texttt{Ta}} will be rendered as \enquote{{-}{-}{-}} and \enquote{{T}{a}} instead of the correct \enquote{---} and \enquote{Ta}.
\end{tabularx}
\end{minipage}};
\end{scope}
% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
% *** END notes
% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

\end{tikzpicture}
% ============================================================================
% END page 1
% ============================================================================


% ============================================================================
% page 2
% ============================================================================
\section*{Errors and warnings as given by \TeX}

\begin{minipage}{\textwidth}
The following error messages were generated with the TTF font Comic Sans in \LaTeX{}. The \TeX{} font name was chosen to be \texttt{jcs} and T1 encoding was used.
\end{minipage}

\bigskip

\newlength{\errormsgboxwidth}
\setlength{\errormsgboxwidth}{15cm}

\begin{tikzpicture}[%
error_number/.style  = {starburst, fill=myAccentYellow, draw=myAccentRed, line width=2pt,starburst points=17},%
errormsg/.style      = {rectangle, draw=myDarkGray, fill=myLightGray, thick, rounded corners, inner sep=2ex},%
remedy/.style        = {},%
warning_number/.style  = {starburst, fill=myAccentYellow, draw=myAccentRed, line width=0.5pt,starburst points=7}%
]
\matrix [column sep=5mm,row sep=7mm]
{
% \node [error_number] {1};
% &\node [errormsg] {\begin{minipage}[t]{\errormsgboxwidth}
% \begin{Verbatim}
% ! LaTeX Error: File `auto1.sty' not found.
% Type X to quit or <RETURN> to proceed, or enter new name. (Default extension: sty)
% \end{Verbatim}
% \end{minipage}};\\
% &
% \node [remedy] {\begin{minipage}[t]{\errormsgboxwidth}
% Check that you didn't misspell the package name and thatyou updated \TeX's cache with
% \begin{Verbatim}
% $> texhash
% \end{Verbatim}
% \end{minipage}};\\
% % 
\node [warning_number] {1};&
\node [errormsg] {\begin{minipage}[t]{\errormsgboxwidth}%
\begin{Verbatim}
LaTeX Font Warning: Font shape `OT1/jcs/m/n' undefined
(Font)              using `OT1/jcs/m/n' instead on input line 23.
\end{Verbatim}
\end{minipage}
};\\
&
\node [remedy] {\begin{minipage}[t]{\errormsgboxwidth}
If you select the font explicitly by
\begin{lstlisting}
\fontfamily{jcs}\fontseries{m}\fontshape{n}\selectfont Sample text.
\end{lstlisting}
you might run into the same issue. The problem is that \LaTeX{} can't find a definition (in an FD file or in the source file itself) that links the font family \texttt{jcs} with series \texttt{m} and shape \texttt{n} \emph{and the current encoding} to a specific internal \TeX{} font.

That said, the problem is mostly the encoding. Are you using
\begin{lstlisting}[language=TeX]
\DeclareFontFamily{T1}{jcs}{}
\DeclareFontShape{T1}{jcs}{m}{n} {<-> jcsr8t } {}
\end{lstlisting}
that is, T1 encoding? Well, \LaTeX's default is OT1, so it's probably just enough to force T1 encoding in your source file with
\begin{lstlisting}
\usepackage[T1]{fontenc}
\end{lstlisting}
\end{minipage}};\\
%
% 3:
\node [error_number] {2};&
\node [errormsg] {\begin{minipage}[t]{\errormsgboxwidth}
\begin{Verbatim}
kpathsea: Running mktextfm jcsr8t
mktextfm: Running mf-nowin -progname=mf \mode:=ljfour; mag:=1; nonstopmode;
input jcsr8t
This is METAFONT, Version 2.718281 (Web2C 7.5.7)


kpathsea: Running mktexmf jcsr8t
! I can't find file jcsr8t'.
<*> ...=ljfour; mag:=1; nonstopmode; input jcsr8t

Please type another input file name
! Emergency stop.
<*> ...=ljfour; mag:=1; nonstopmode; input jcsr8t

Transcript written on mfput.log.
grep: jcsr8t.log: No such file or directory
mktextfm: `mf-nowin -progname=mf \mode:=ljfour; mag:=1; nonstopmode; input jcsr8t'
failed to make jcsr8t.tfm.
kpathsea: Appending font creation commands to missfont.log.

! Font T1/jcs/m/n/10=jcsr8t at 10.0pt not loadable: Metric (TFM) file not found.
<to be read again>
                   relax
\end{Verbatim}
\end{minipage}};\\
&
\node [remedy] {\begin{minipage}[t]{\errormsgboxwidth}
Now, somewhere in \TeX's data (in an FD file corresponding to your font or in the source file), one of \TeX's internal font names is specified, (like \texttt{jcsr8t} here). Unfortunately, {\TeX} can't find a file named \texttt{jcsr8t.tfm} now; you can verify this with
\begin{lstlisting}[language=bash]
$> kpsewhich jcsr8t.tfm
\end{lstlisting}
which doesn't give any location. \emph{This file is needed to use the font.} If you are sure that the file is there, update \TeX's cache (\texttt{texhash}).
\end{minipage}};\\
};
\end{tikzpicture}


\begin{tikzpicture}[%
error_number/.style  = {starburst, fill=myAccentYellow, draw=myAccentRed, line width=2pt,starburst points=17},%
errormsg/.style      = {rectangle, draw=myDarkGray, fill=myLightGray, thick, rounded corners, inner sep=2ex},%
remedy/.style        = {},%
warning_number/.style  = {starburst, fill=myAccentYellow, draw=myAccentRed, line width=0.5pt,starburst points=7}%
]
\matrix [column sep=5mm,row sep=7mm]
{
%
% 4:
\node [error_number] {3};&
\node [errormsg] {\begin{minipage}[t]{\errormsgboxwidth}
\begin{Verbatim}
! TeX capacity exceeded, sorry [max level recursion of virtual fonts=10].
\end{Verbatim}
\end{minipage}};\\%
&%
\node [remedy] {\begin{minipage}[t]{\errormsgboxwidth}%
This error message arises when there is a TFM file and a VF file that points to a raw TFM file that happens to be the original TFM file itself. From there, \TeX{} finds the corresponding VF file again and so on: happy looping until \TeX{} is tired.

There probably was an error when creating the font files which resulted in not distinguishing raw TFM and TFM file. If you created the font files yourself, make sure that \emph{these are actually different files}.
\end{minipage}};\\
%
% 5:
\node [error_number] {4};&
\node [errormsg] {\begin{minipage}[t]{\errormsgboxwidth}
\begin{Verbatim}
kpathsea: Running mktexpk --mfmode / --bdpi 600 --mag 0+420/600 --dpi 420 rjcsr8t
mktexpk: don't know how to create bitmap font for rjcsr8t.
kpathsea: Appending font creation commands to missfont.log.

!pdfTeX error: pdflatex (file rjcsr8t): Font rjcsr8t at 420 not found
 ==> Fatal error occurred, no output PDF file produced!
\end{Verbatim}
\end{minipage}};\\
&
\node [remedy] {\begin{minipage}[t]{\errormsgboxwidth}
Probably the most common error message in \LaTeX{} fonts.

It's being triggered when the information in the (raw) TFM file is not sufficient to create the actual font, and thus again is a font installation error.
\begin{itemize}
\item Check that you did not interchange raw TFM and TFM font file (the raw TFM file should be a lot smaller).
\item Check that \TeX{} finds your VF file if there is one.
\end{itemize}

Another possible cause is that the raw TFM is declared in no MAP file, or that \TeX's map cache isn't updated. Look for a map file with an entry starting with the raw TFM name, for example,
\begin{lstlisting}[breaklines,breakatwhitespace]
rjcsr8t Comic-Sans " T1Encoding ReEncodeFont " <Comic-Sans.ttf <T1-WGL4.enc
\end{lstlisting}
In Linux, this could for example be done by
\begin{lstlisting}[language=bash]
$> find /path/to/mapfiles | xargs grep rjcsr8t
\end{lstlisting}
If you can't find it, create a proper map file, and update \TeX's map cache:
\begin{lstlisting}[language=bash]
$> updmap --enable Map=/path/to/mapfile.map
\end{lstlisting}
\end{minipage}};\\
%
% 6:
\node [error_number] {5};&
\node [errormsg] {\begin{minipage}[t]{\errormsgboxwidth}
\begin{Verbatim}
!pdfTeX error: pdflatex (file T1-WGL4.enc): cannot open encoding file for reading
 ==> Fatal error occurred, no output PDF file produced!
\end{Verbatim}
\end{minipage}};\\
&
\node [remedy] {\begin{minipage}[t]{\errormsgboxwidth}
Probably easy: \LaTeX{} can't find the encoding file. Can you? In this case, you probably forgot to update \TeX's cache:
\begin{lstlisting}[language=bash]
$> texhash
\end{lstlisting}
\end{minipage}};\\
%
% 7:
\node [error_number] {6};&
\node [errormsg] {\begin{minipage}[t]{\errormsgboxwidth}
\begin{Verbatim}
!pdfTeX error: pdflatex (file Comic-Sans.ttf): cannot open TrueType font file
for reading
 ==> Fatal error occurred, no output PDF file produced!
\end{Verbatim}
\end{minipage}};\\
&
\node [remedy] {\begin{minipage}[t]{\errormsgboxwidth}
The actual font file appears to be missing. Again, this might be a matter of updating \TeX's cache; also make sure that the user can actually access the font file (read: get file permissions right).
\end{minipage}};\\
};
\end{tikzpicture}
% ============================================================================
% END 2nd page
% ============================================================================

\end{document}