path: root/support/pdfrack/doc/pdfrack.tex

\documentclass{article}
\usepackage{psfrag,pdfrack}
\usepackage{xspace}
\usepackage{hyperref}
\usepackage[latin1]{inputenc}
\usepackage{srcltx}

\title{The \texttt{pdfrack} manual}
\author{Marc Boyer\\ ONERA \\ France \\ 
\texttt{Marc.Boyer@onera.fr}}

% Tools
\newcommand{\pdfrack}{\texttt{pdfrack}\xspace}
\newcommand{\pdflatex}{\texttt{pdflatex}\xspace}
\newcommand{\Psfrag}{\texttt{psfrag}\xspace}
\newcommand{\dvips}{\texttt{dvips}\xspace}
% Formats
\newcommand{\pdf}{\texttt{pdf}\xspace}
\newcommand{\postscript}{\texttt{postscript}\xspace}
\newcommand{\dvi}{\texttt{dvi}\xspace}
% alias
\newcommand{\B}{\ensuremath{\backslash}}
\newcommand{\command}[1]{\texttt{\textbackslash{}#1}}

\begin{document}

\maketitle

\tableofcontents


\section{Introduction}

What is \pdfrack? The \pdfrack is a \emph{hack} that allow to use
\Psfrag and \pdflatex.

The \pdfrack is not a \emph{complete} solution: it does not handle all
\LaTeX\ files, and you will sometimes need to modify your \LaTeX\ source
files if you want to use it. But it can help you to save time.

\subsection{Why \pdfrack?}
If you want to generate a \pdf file from a \LaTeX\ one, you either can
do it directly, using \pdflatex, or by first generating a
\postscript\footnote{With \LaTeX; you generate a \dvi file, and, with
  some filter, like \texttt{dvips}, you get a \postscript one.}
file and converting this \postscript to a \pdf file. 

The \Psfrag package allow the user to replace some text in a
\postscript figure by another \LaTeX\ text. To use \Psfrag, you must
use a filter from \dvi to \postscript. So, if you compile with 
\pdflatex, the text substutions are lost. Nevertheless, you sometimes
want to use \pdflatex, to be 
able to add hyperlinks in your \pdf, or because your \postscript to
\pdf filter produces a ugly text.

\subsection{Basic idea}

The basic idea of \pdfrack is, from your \LaTeX\ source file, to
produce the figures in \pdf format, \emph{with the \Psfrag
  replacements}. Then, you can compile with \pdflatex, including the
\pdf figures.


\begin{figure}[htbp]
  \centering
  \psfrag{pdflatex}[c][c][.7]{\pdflatex}
  \psfrag{pdfrack}[c][c][.7]{\pdfrack}
  \psfrag{dvips}[c][c][.7]{\dvips}
  \psfrag{latex}[c][c][.7]{\texttt{latex}}
  \psfrag{Fp(x)}{$\mathcal{F}(x)$}
  \psfrag{Gp(x)}{$\mathcal{G}(x)$}
  \pdfrackincludegraphics[width=\textwidth]{BasicIdea}
  \caption{The basic idea of \pdfrack}
  \label{fig:BasicIdea}
\end{figure}


\section{Using it}

\subsection{Installation}

Put the script \texttt{pdfrack.sh} in a directory included in your
path, and \texttt{pdfrack.sty} somewhere where \TeX will find
it\footnote{The variable \texttt{TEXINPUTS} defines where your \TeX
  tool looks for inputs.}.

Moreover, the \texttt{pdfrack.sh} script uses a lot of other scripts
and software.  (\texttt{cut, dvips, epstopdf, grep, head, latex,
  ps2ps, ps2epsi, sort, tail}, and, first of all, a bourne
shell). They all are installed with common Unix/Linux distribution,
so, you should not have to care about it.

\subsection{A very short tutorial}

Assuming you have a \LaTeX\ file, with figures included using the
following pattern:
\begin{verbatim}
\begin{figure}[htbp]
  \centering
  \psfrag{Fp(x)}{$\mathcal{F}(x)$}
  \psfrag{Gp(x)}{$\mathcal{G}(x)$}
  \includegraphics[width=\textwidth]{BasicIdea}
  \caption{The basic idea of \pdfrack}
  \label{fig:BasicIdea}
\end{figure}
\end{verbatim}


They are two ways to use it: the lazy automatic one (option
\texttt{-a}), where all figures founds are converted, and the
hand-made one, where you have to select the figures to be converted
with the script.

\subsubsection{Lazy way}

Just runs the script on your file with the \texttt{-a} option. Now,
you can use \pdflatex (and ignore some warning messages about
\texttt{psfrag}). 

That is to says, assuming that your file has name \texttt{file.tex}, just run 
\begin{verbatim}
pdfrack.sh -a file.tex
pdflatex file
\end{verbatim}

You have to rerun the script each time the files or the
\texttt{psfrag} commands are modified.


\subsubsection{Hand made way}

In the hand-made one, you simply have to:
\begin{itemize}
\item include the \pdfrack package \verb+\usepackage{pdfrack}+
\item replace the \verb+\includegraphics+ commands by
  \verb+\pdfrackincludegraphics+  for all figures selected for
  translation 
\end{itemize}

Then, just run the command \texttt{pdfrack.sh} on your file. It should
produce some output like:
\begin{verbatim}
----------------------------------------------
  ---> Converting figure BasicIdea
Using LaTeX: producting dvi
This is e-TeX, Version 3.14159-2.1 (Web2C 7.4.5)
entering extended mode
Method 2: Trying conversion with dvips -|->  ps2eps -|-> eps2eps -|-> epstopdf
Converting dvi -> ps (dvips)
Converting ps -> eps (ps2eps)
     Cleaning eps with eps2eps filter
Converting eps -> pdf (epstopdf)
Removing temporary files
\end{verbatim}
for each figure, and generates a standalone \pdf figure \emph{with the
  psfrag replacements}.

Then, you can run \pdflatex on your file.

In the lazy automatic one, you simply have to run the command
\texttt{pdfrack.sh} with option \texttt{-a}, and it will produce the
same kind of output, plus some warning like \texttt{Non-PDF special
  ignored!} when running \texttt{pdflatex}.


\medbreak

Sometimes, the bounding box of the generated file is not very good. Try
different values for the \texttt{-m} options, and try to use or no the
\texttt{-p} and \texttt{-e} options. If offers you 16
possibilities. If none work, your are unlucky.

See also the \texttt{README} file to have more details.

\subsection{Limitations}

The \pdfrack package is based on a bourne-shell script that parse the
file to find the \verb+\begin{figure}+ and \verb+\end{figure}+
tags. So, you must use this to way of including figure (or change the
script).

Note that the \texttt{\%} is is general seen as a comment, even if
prefixed with $\backslash$. So, avoid to use it.

If your \LaTeX\ code is too complex, then, \texttt{pdfrack} will ne be
able to handle it. Then, you should write a simpler \LaTeX file, with
your figure(s) and use this file to generate the pdf figures.


\subsection{Options}


\subsubsection{Summary}
\label{sec:opt-sum}

\begin{description}
\item[-h] help
\item[-m] method: integer in 0..3 (default is 2)
  the number of the method used to convert \dvi to \pdf
  if one method fails, try another, and add -p and/or -e options \verb+:-)+
\item[-p] filter each postscript file with \texttt{ps2ps}
\item[-e] filter each encapsulated postscript file with
  \texttt{eps2eps}
\item[-a]  auto/all, translate all figures included with \verb+\includegraphics+ (avoid 
	the use of \texttt{pdfrackincludegraphics})
\item[-i] force use of \texttt{ps2epsi} instead of \texttt{ps2eps}
\item[-k] keep (all tempory files are keeped, usefull for debug)
\item[-H] own header file (default is to extract from file.tex file)
\item[-M] master file (to handle sub files)
\end{description}


\subsubsection{Filter options: \texttt{-m, -p, -e, -i}}
\label{sec:opt-filter}

The main source of troubles is the generation of a \pdf from the \dvi
of \postscript file, and especially the size of the ``Bounding box''. If the
default method fails, you should try some values of the \texttt{-m}
option. 

You also can add the \texttt{-p} and \texttt{-e} options. In theory,
they are useless, since \texttt{-p} force a \postscript to \postscript
translation, and since \texttt{-e} does the same with encapsulated
postscript. But in practice, it may help.

In general, the filter \texttt{ps2eps} does a better job than 
\texttt{ps2epsi}. Then, by default, the script uses it. The option
\texttt{-i} is there to force the use of \texttt{ps2epsi}.

\subsubsection{Auto option}

You can avoid the use of the command \texttt{pdfrackincludegraphics},
with the option \texttt{-a}. It will generate a \pdf figure for all
figures included with \texttt{includegraphics}, even those without any
\psfrag replacement.

\subsubsection{Other header option: \texttt{-H}}

To generate the \pdf file with the \psfrag replacements, the script
use the header of your \LaTeX\ file. But, it may be insufficient: by
example, your \psfrag replacement can use some command defined neither
in your header, neither in the \texttt{figure} environment. Then, you
can write another header that will be used to generate the \pdf
figures. 

\subsubsection{Handling subfiles: \texttt{-M}}
\label{sec:opt-subfiles}

If your master file made some input of some other \LaTeX\ code, with
\command{input}, \verb+\include+ or any other command\footnote{Like the
  \command{Input} of the \texttt{srcltx} package.}, it is not
parsed by the \pdfrack script.

You have to explicitly call the \pdfrack script on each sub file, with
the option \texttt{-M} that specify the name of the master file, or
the option \texttt{-H} to specify another header file.

\section{How does it works?}

The core of \pdfrack is a \texttt{pdfrack.sh} script that try, for
each figure in your \LaTeX\ source, to produce a small \LaTeX\ file
with only the figure. Then, this file is compiled with \LaTeX,
converted into \postscript, and then, we have a \postscript figure,
with the replacements.

Now, the system should convert a \postscript file to a \pdf one, with
the right bounding box... I am not at all a guru of \postscript
(neither \pdf), so, I try to use some tools like \texttt{ps2ps},
\texttt{ps2eps}, \texttt{ps2pdf} and so on. There is an option in the
script \texttt{-m} that allow the user to chose one or the other.

\begin{figure}[htbp]
  \centering
  \pdfrackincludegraphics[width=\textwidth]{Details}
  \caption{Inside \pdfrack}
\end{figure}

\section{Temporary files}
\label{sec:tmp-files}

This script creates a lot of temporary files in the current directory.
It could then overwrite an existing file. In fact, after several years
of use, no user never complain about it, but, in case, here is a list
a created files.

If your input is called \texttt{paper.tex}, the script will create (and remove
 if \texttt{-k} is not set) the files:
  \texttt{paper.tex.header}
  \texttt{paper.tex.figlines}
  \texttt{paper.tex.figure}
And for each figure \texttt{fig.eps} used (with
"\texttt{pdfrackincludegraphics[..]{fig}}"), it  
will creates (and remove, if \texttt{-k} is not set)
  \texttt{fig.tex}, \texttt{fig.log}, \texttt{fig.aux},
  \texttt{fig.dvi}.


\section{Knowns bugs and limitations}

\begin{enumerate}
\item \textbf{Only a subpart of my figure appears}\label{enum:subpart}
  The main problem is the computation of the ``Bounding box'' of the
  postscript figure. If the default method fails, try the \texttt{-m}
  option, with different values. Adding the \texttt{-e} may also
  help. See paragraph~\ref{sec:opt-filter}.
\item \textbf{The figure is alone on a full page. Its seems to big.} \\
  See item~\ref{enum:subpart}
\item \textbf{I am a Windows user}\\
  Neither am I\footnote{This is not always true: when I am forced to
    write Word document, I use a Windows machine thought an
    \texttt{rdesktop} connection.}... This solution is
  based on some well known Unix command-line tools, like the bourne
  shell, \texttt{ps2eps, cut, tail, grep}... To use my script on
  windows, you should install a solution like Cygwin.
\item \texttt{I uses two times the same file, with different
    replacements,  but only one replacement is made.} \\
  Yes... For each \postscript file, a \pdf file is generated, with the
  same name. Then, if the same file is used two times, with two
  different \psfrag replacements, the same name is used twice, and
  only one \pdf file rests. The simpler solution is to copy the
  \postscript file, or to use some link capacity (like \texttt{ln}). 
\item \texttt{The figures in included files (with \command{include},
    \command{input} are not taken into account}\\ 
  See paragraph~\ref{sec:opt-subfiles}.
\item \textbf{My problem is not in the known bugs list !} \\
  Just email me. 
\end{enumerate}

\section{Why this name ?}

I think a good solution for using \texttt{pdflatex} and
\texttt{psfrag} should be named \texttt{pdfrag} or \texttt{pdffrag}. I
do not think that my solution is really good. It is just a hack. Then
\texttt{pdfrack} comes from:
\begin{verbatim}
    pdf
  + psfrag
  +    hack
  ---------
    pdfrack
\end{verbatim}


\section{Other solutions}

There are, of course, other solutions:a
\begin{description}
\item[dvips + ps2pdf + hyperref:] Did you really need
  \texttt{pdflatex}? Sometimes, you only want to what the "cool"
  hyperlinks in your \pdf. In this case, just use
  \verb+\usepackage{hyperref}+ in your code and use \texttt{dvips} and
  \texttt{ps2pdf}.
\item[pst-pdf, pd4pdf] See also these two packages (\texttt{ps4pdf} is
  deprecated and replaced by \texttt{pst-pdf}). which also seem to try
  to generate Pdf figure from Postscript code. You can get it from  CTAN.
\item[pstool] Another package, presented as ``a replacement for
  \texttt{pst-pdf} in the r\^ole of supporting the \psfrag package
  (which it loads) in \pdflatex''. 
\item[pdffrag] There also is a perl-based script, \texttt{pdffrag},
  developed by Fran\c{c}ois Rouge,
  \url{http://elessar.lautre.net/spip.php?article5} 
\item[DrawAt] Matthijs Douze (another member from ENSEEIHT) has
  developped DrawAt, a solution for MacOS X only. 
  \url{http://www.enseeiht.fr/~douze/drawat/index.html}
\item[unpsfrag] Félix Valado Pomarinho has developped a perl script:
  \texttt{unpsfrag}
\item[fragmaster] Tilman Vogel developped \texttt{fragmaster}, another
  perl-oriented solution. 
  \url{http://www.tat.physik.uni-tuebingen.de/~vogel/fragmaster}
\item[{pstoedit and [X]fig}] With \texttt{[X]fig}, you can already make a
  figure and, setting the special flag to a text zone, you already can
  put on your figures some LaTeX code, and export in the combined mode
  either in postcript or pdf. 

  In the combined Postscript/LaTeX, if your file is named
  \texttt{figure.fig}, it creates a \texttt{figure.pstex} file which
  is the postcript version of your fig figure \emph{without the
  special-tagged texts}, and a \texttt{figure.pstex\_t} file which
  juste include the \texttt{figure.pstex} (with the
  \verb+\includegraphics+ command) \emph{and} adds the LaTeX text at
  the right place.  

  In the combined Pdf/LaTeX, this is the same except that
  \texttt{figure.pstex} is named \texttt{figure.pdf} and
  \texttt{figure.pstex\_t} is named \texttt{figure.pdf\_t} and includes
  \texttt{figure.pdf}.

  If you like to avoid the graphic
  interface, this ca be done in command line with \texttt{fig2dev}.
\begin{verbatim}
fig2dev -L pstex_t figure.fig figure.pstex_t 
fig2dev -L pstex figure.fig figure.pstex
\end{verbatim}

  If you do not have a fig figure, you can transform a postcript file
  into a fig one with \texttt{pstoedit} with command line like:
\begin{verbatim}
  pstoedit -dis -f fig example.eps > example.fig
\end{verbatim}
\item[figfrag] With \texttt{figfrag}
  (\url{http://www.ctan.org/tex-archive/graphics/figfrag/}
  you can use the psfrag feature in your fig picture and create a
  standalone eps figure with the psfrag replacements.
\end{description}


\end{document}