%%!TEX TS-program = pdflatexmk
%%!TEX encoding = UTF-8 Unicode
\documentclass[11pt]{article}
\usepackage[utf8]{inputenc}

%\usepackage{tmmlucida}
% \usepackage[expert]{fourier} 
\usepackage{fourier}
\usepackage[scaled=0.85]{berasans}
\usepackage[scaled=0.85]{beramono}

\newcommand{\MacTeX}{Mac\kern-.13em\TeX}
\newcommand{\BibTeX}{B\textsc{i\kern-.025em  b}\kern-.13em\TeX}
\newcommand{\TS}{\textsf{\TeX Shop}}
\newcommand{\cmd}[1]{\textsf{#1}}

\newcommand{\eps}{\cmd{eps}}
\newcommand{\pdf}{\cmd{pdf}}
\newcommand{\png}{\cmd{png}}
\newcommand{\jpg}{\cmd{jpg}}
\newcommand{\tiff}{\cmd{tiff}}
\newcommand{\sips}{\cmd{sips}}
\newcommand{\convert}{\cmd{convert}}
\newcommand{\graphicx}{\cmd{graphicx}}
\newcommand{\epstopdf}{\cmd{epstopdf}}
\newcommand{\shellescape}{\cmd{-{}-shell-escape}} 

\usepackage{url}
\usepackage[letterpaper, margin=1.25in]{geometry}

\usepackage{microtype}

\usepackage[compact]{titlesec}

\usepackage{graphicx}

\usepackage{hyperref}


\title{Using \eps\ and \tiff\ Graphics \\ with \cmd{pdflatex}}
\author{by \\H. Schulz and R. Koch}
\date{2012/05/26}

\begin{document}
\maketitle

\section*{Introduction}

Users who include \eps\ and \tiff\ figures in documents are sometimes surprised to find that they have a problem when compiling those files using \cmd{pdflatex}. By default \cmd{pdflatex} can include \jpg, \png\ and \pdf\ files but not \eps\ or \tiff\ files. This document discusses methods  of including \eps\ and \tiff\ files in documents compiled with \cmd{pdflatex}. In the end these techniques use Ghostscript or Apple's distiller to convert \eps\ files to \pdf\ format, and Apple's built-in \sips\ program or \convert\ from ImageMagick  to
convert \tiff\ files to \png\ format. 

\section*{Conversion of \eps\ to \pdf\ is Automatic in TeX Live 2011 and Later}

Since \eps\ illustrations cause such trouble for users switching from \TeX\ to pdf\TeX, the authors of TeX Live 2011 made a concerted effort to solve the problem once and for all. Instead of having to explicitly use the \epstopdf\ package the good news is that conversion of \eps\ files to \pdf\ files is now automatic in TeX Live 2011 and later if you use the \graphicx\ package, as almost all users do.

Here's how it works. Suppose your document contains the line
\begin{verbatim}
     \includegraphics{foo.eps}
\end{verbatim}
then the \graphicx\ package will automatically convert \cmd{foo.eps} to \cmd{foo-eps-converted-to.pdf} and load that pdf file. When the file is typeset again, \cmd{foo.eps} will be converted again only if it is newer than \cmd{foo-eps-converted-to.pdf}, but in any case \cmd{foo-eps-converted-to.pdf} will be loaded.

Some users omit the extension and just write
\begin{verbatim}
     \includegraphics{foo}
\end{verbatim}
which will also work as above: the file \cmd{foo.eps} will be converted to \cmd{foo-eps-converted-to.pdf} and so forth. But there is one tricky point. Suppose the source folder contains both \cmd{foo.eps} and a completely unrelated file named \cmd{foo.pdf}. Then the graphics command will load \cmd{foo.pdf} first and not even notice the \eps\ file. 

Incidentally, the system  names the converted file \cmd{foo-eps-converted-to.pdf} rather than \cmd{foo.pdf} precisely because a few users might have source files containing unrelated \eps\ and \pdf\ files with the same name; these users wouldn't appreciate an automatic conversion that destroyed their original \pdf\ file!

Users upgrading from earlier versions of TeX Live will be familiar with the command
\begin{verbatim}
    \usepackage{epstopdf}
\end{verbatim}
This command is not needed in TeX Live 2011 and later, although it does no harm, because the \graphicx\ package automatically loads it. Users may also be familiar with the \TeX\ command-line flag ``\shellescape'', which gives \TeX\ the ability to call external programs during typesetting. This flag is also not needed in TeX Live 2011 or later for \eps\ to \pdf\ conversion because the system implements ``restricted-shell-escape'' which allows a small list of special system commands to be executed even if shell escape is not set. 

\section*{Converting TIFF Files}

The most common graphic file formats are  \eps, \pdf, \png, \jpg\ and \tiff. In particular, many scanners output \tiff\ files. The authors of TeX Live 2011 were unable to automate conversion of \tiff\ to \png\  because \sips\  is only available on the Macintosh and  \convert\ could not be added to the list
of trusted programs ---  on Windows machines there is an unrelated program named  \convert\ which would cause security concerns if called indiscriminately from \TeX. So it is necessary to convert \tiff\ to \png\ by hand. There are several ways to do this:
\begin{itemize}
\item
Apple's Preview program will convert \tiff\ files to \png\ format. Open the \tiff\ file in Preview and then Export the result as a \png. 
\item
It is often easier to use Terminal in
/Applications/Utilities. If you have the ImageMagick \convert\ program, change directory to the folder containing the \tiff\ file, which we assume is named ``myfile.tiff'', and then
\begin{verbatim}
     convert myfile.tiff myfile.png
\end{verbatim}
If you do not have \convert, use Apple's \sips\ program instead:
\begin{verbatim}
     sips -s format png myfile.tiff --out myfile.png
\end{verbatim}
\item
	\TS\ 2.46 and later and  \TS\ 3.10 and later have built-in \tiff\ to \png\ conversion. With a document window active, select \cmd{Convert TIFF} in the File
menu. A dialog appears listing all \tiff\ files in the folder containing the source file, and in sub-folders of this file. Select \tiff\ files to be converted --- multiple files
can be selected --- and push \cmd{Convert}. See Figure (\ref{fig:ConvertTiffMenu}) one page \pageref{fig:ConvertTiffMenu}.

\begin{figure}
\centering
\includegraphics[width=2.35in]{figs/ConvertTiffMenu}\hfill\includegraphics[width=3.25in]{figs/ConvertTiffMenu2}
\caption{The \cmd{Convert Tiff} Menu in \TS\ 3.10}
\label{fig:ConvertTiffMenu}
\end{figure}

\item
Herbert Schulz wrote a Drop Script which can convert all \tiff\ files in a folder to \png\ in a single operation. Drag the individual \tiff\ file or folder to the Drop Script. This is available as `\cmd{Tif(f) to Png.zip}' at <\url{https://dl.dropbox.com/u/10932738/index.html}>.
\end{itemize}

\section*{Adding More Automatic Conversions to \TeX}

It is possible to modify \TeX\ so it will perform additional conversions automatically during typesetting. The rest of this document is about those
modification, which are not for the faint-hearted.

The modifications require  additions to the header of the source file --- that is the easy part. In the end, these header commands tell \TeX\ to call a conversion program
during typesetting, either Apple's Distiller \cmd{/usr/bin/pstopdf} or Apple's \sips\ or ImageMagick's \convert. The problem is that \TeX\ is usually configured to disallow calling external programs during typesetting, since calling such programs is a security risk. There are two ways around this problem.

\begin{itemize}
\item
The first is to reconfigure \TeX\ by adding the flag \shellescape\ to its calling sequence. The effect is to allow \TeX\ to call {\em any} program, including for instance, a shell command to erase all files in the home directory. How one adds the flag will depend upon which application you are using to typeset your document but adding the flag is usually very easy. Adding \shellescape\ to TeXShop is discussed in more detail in Appendix A on page \pageref{sec:AppendixA}.
\item
The second method, available with \MacTeX(TeX Live)-2012 or later, is to add one or all of \sips, \convert\ and/or \cmd{/usr/bin/pstopdf} to the list of trusted programs for restricted-shell-escape. This involves directly manipulating TeX Live configuration programs. This is discussed in more detail in Appendix B on page \pageref{sec:AppendixB}

\end{itemize}

\section*{More Automatic Conversions}

Once you allow \sips\ and/or \convert\ and/or \cmd{pstopdf} to be automatically executed using one of the methods described in the previous section you can simply add some lines to your document and have conversions happen on the fly. The rest of this section contains information about what has to be added to your document.

\subsection*{Using Apple's Distiller}

By default, conversion of eps files to pdf files is done with Ghostscript. Apple provides an alternate conversion program (often called a distiller), \cmd{pstopdf}. To use
this program instead of Ghostscript, add the following line to the document header immediately following inclusion of the \cmd{graphicx} package: 
\begin{verbatim}
     \usepackage{epstopdf}
     \epstopdfDeclareGraphicsRule{.eps}{pdf}{.pdf}{%
         /usr/bin/pstopdf #1 -o \OutputFile
         }
\end{verbatim}

\newpage

\subsection*{Converting \tiff\ to \png}

%The most common graphic file formats are  \eps, \pdf, \png, \jpg\ and \tiff. In particular, many scanners output \tiff\ files. The authors of TeX Live 2011 were unable to automate conversion of \tiff\ to \png\ using the \convert\ program from ImageMagick because on Windows machines there is an unrelated program named \convert\ which would cause security concerns if called indiscriminately from \TeX.
%
%It is possible to automate this conversion on the Macintosh. But in that case, the \cmd{epstopdf} package must be explicitly loaded. Then add the following commands to the document header immediately following inclusion of the \cmd{graphicx} package:
To automate conversion of \tiff\ to \png, add the following commands to the document header immediately following inclusion of the \cmd{graphicx} package.
\begin{verbatim}
     \usepackage{epstopdf}
     \epstopdfDeclareGraphicsRule{.tif}{png}{.png}{convert #1 \OutputFile}
     \epstopdfDeclareGraphicsRule{.tiff}{png}{.png}{convert #1 \OutputFile}
     \PrependGraphicsExtensions{.tif, .tiff}
\end{verbatim}
If you  wish to use Apple's \sips\ converter rather than \convert\ from MacTeX, replace the above commands with these.
\begin{verbatim}
     \usepackage{epstopdf}
     \epstopdfDeclareGraphicsRule{.tif}{png}{.png}{%
         sips -s format png #1 --out \OutputFile}
     \epstopdfDeclareGraphicsRule{.tiff}{png}{.png}{%
         sips -s format png #1 --out \OutputFile}
     \PrependGraphicsExtensions{.tif, .tiff}
\end{verbatim}


\subsection*{Automating More Conversions}

If you use \tiff\ conversions often you may wish to always load the lines given above automatically. You may do this by creating an \cmd{epstopdf.cfg} file containing only the conversion lines
\begin{verbatim}
     \epstopdfDeclareGraphicsRule{.tif}{png}{.png}{convert #1 \OutputFile}
     \epstopdfDeclareGraphicsRule{.tiff}{png}{.png}{convert #1 \OutputFile}
     \PrependGraphicsExtensions{.tif, .tiff}
\end{verbatim}
or
\begin{verbatim}
     \epstopdfDeclareGraphicsRule{.tif}{png}{.png}{%
         sips -s format png #1 --out \OutputFile}
     \epstopdfDeclareGraphicsRule{.tiff}{png}{.png}{%
         sips -s format png #1 --out \OutputFile}
     \PrependGraphicsExtensions{.tif, .tiff}
\end{verbatim}
and place it in your personal \cmd{texmf} tree at \path{~/Library/texmf/tex/latex/config/}. But remember that others that see your source file may not have your \cmd{epstopdf.cfg} file and a compile will fail for them. You may also place the \cmd{epstopdf.cfg} file in \path{/usr/local/texlive/texmf-local/tex/latex/config/} for use by all users of your system; make sure to run
\begin{verbatim}
sudo mktexlsr
\end{verbatim}
in \cmd{Terminal} giving your administrator's password when requested.

If you create the \cmd{epstopdf.cfg} file you needn't include the \verb|\usepackage{epstopdf}| in your source document.

\section*{Appendix A --- Adding \shellescape\ to \TS}\label{sec:AppendixA}

Note: The following information is only needed by new users of \TS\ or previous users that have manually removed the \shellescape\ flag from their preferences. Other users have that flag already set and need not add it. We'd recommend removing it unless you need it!

It is relatively easy to get the basic ``engines'' to use the \shellescape\ flag. There are two places in the \cmd{Engine} tab of \cmd{TeXShop}\,\(\to\)\,\cmd{Preferences}. Simply add \shellescape, with a surrounding space on each side to the two \cmd{pdfTeX} engine lines. See Figure (\ref{fig:ShellEscape}) on page \pageref{fig:ShellEscape}.

If you have used any of the \cmd{latexmk} engines, e.g., \cmd{pdflatexmk}, you can add the \shellescape\ flag to all of the engines by editing the \path{~/Library/TeXShop/bin/latexmkrcedit} file. Change the line
\begin{verbatim}
     $TSUserCompileOptions = '';
\end{verbatim}
to
\begin{verbatim}
     $TSUserCompileOptions = '--shell-escape';
\end{verbatim}
i.e., from an empty string to one that includes the \shellescape\ flag, and save the file. Remember \path{~/Library/} is the \path{Library} folder in your \path{HOME} folder. In \cmd{Mac OS X 10.7} (Lion) you can open the \path{~/Library/} folder by pressing the \cmd{Opt} key while clicking on the \cmd{Finder}'s \cmd{Go} Menu.

\begin{figure}
\centering
\includegraphics[width=3in]{figs/AddShellEscape}
\caption{Adding the \shellescape\ flag to \TS\ Preferences.}
\label{fig:ShellEscape}
\end{figure}

\section*{Appendix B --- Adding Programs to the Restricted Program List}\label{sec:AppendixB}

Note: This method of adding programs to those accepted for the restricted shell escape mode is only available in \MacTeX(TeX Live)-2012 and later. It is much
more secure than setting the \shellescape\ flag, but it could open a security hole by adding an unsecure program to the list.

In previous examples we used \cmd{pstopdf}, \convert\ or \sips\ as external programs. In the following example we will add Apple's \sips\ program to the allowed list; others can be added as needed but be careful what you are adding.

\newpage
First create a simple text file that contains
\begin{verbatim}
     shell_escape_commands = \
     bibtex,bibtex8,\
     kpsewhich,\
     makeindex,\
     mpost,\
     repstopdf,\
     sips,\
     \end{verbatim}
and name it \path{texmf.cnf}. \textbf{Note: the file must end with at least one completely blank line! I typically use two blank lines to make sure I don't mess it up.} The first part duplicates the default list since this command overrides the default rather than adding to the default. Instead of the \verb|sips,\| line you could add \verb|convert,\|, etc., or multiple commands, each on its own line.

Using the ``Go to Folder'' command in the  \cmd{Finder}'s \cmd{Go} menu, open the
\begin{verbatim}
     /usr/local/texlive/texmf-local/web2c
\end{verbatim}
 folder and copy the \path{texmf.cnf} file there. Finally run the command
 \begin{verbatim}
     sudo mktexlsr
\end{verbatim}
in \cmd{Terminal} giving your administrator's password when requested.

From then on the program(s) you added to the list will be allowed to execute in the default restricted shell escape mode without the need for the all encompassing \shellescape\ flag.

Note: this method can be useful in other situations. For example, the \cmd{tkz-fct} package uses \cmd{gnuplot} to create graphs on the fly. By adding \cmd{gnuplot} to the list of accepted programs there is no need to have the \shellescape\ flag active when using this package.

\end{document}
