path: root/Master/texmf-dist/doc/latex/epspdfconversion/documentation/epspdfconversion_docu.tex

\pdfminorversion=3 

\documentclass[11pt]{scrartcl}
\usepackage[T1]{fontenc}
\usepackage[latin1]{inputenc}
\usepackage{microtype}
\usepackage[british]{babel}
\usepackage{booktabs}
\usepackage{tabularx}
 

%DRAWING, IMAGES
\usepackage[final]{graphicx}
\usepackage{epic}%
\usepackage{color}%

\usepackage[pdfversion=1.3,GRAY]{epspdfconversion}


%DIMENSIONS
\usepackage[a4paper,left=1.3in,right=1.3in,top=1.3in,bottom=1.3in]{geometry}%
\setlength{\parindent}{0mm}
\addtolength{\parskip}{1mm}


\definecolor{dunkelblau}{rgb}{0.063,0.030,0.670}

%LAYOUT
\usepackage[bookmarks,bookmarksopen]{hyperref}%pdftex
\hypersetup{
colorlinks=true, 
linkcolor=dunkelblau,  
anchorcolor=black, 
citecolor=black, 
filecolor=black, 
menucolor=black, 
pagecolor=black, 
urlcolor=dunkelblau,
hypertexnames=true, 
pdftitle = {The package epspdfconversion v0.3}, 
pdfsubject = {documentation of the package epspdfconversion.sty }, 
pdfkeywords = {epspdf, conversion, LaTeX, eps, eps->pdf}, 
pdfauthor = {daniel.becker@uni-rostock.de}
}




%marginnotes:
\newcommand{\query}[1]{\marginpar{%
 \vskip-\baselineskip %raise the marginpar a bit 
 \raggedright\tiny \hrule\smallskip#1\par\smallskip\hrule}} 

\newcommand{\removequeries}{\renewcommand{\query}[1]{}}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%% END OF PREAMBLE, START OF TEXT %%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{document}



\newcommand{\pack}{{{\texttt{epspdfconversion}}}}

\hypersetup{pageanchor=false}

\title{The package {\pack}}
\author{Daniel Becker\\ \texttt{\href{mailto:daniel.becker@uni-rostock.de}{daniel.becker@uni-rostock.de}}
\thanks{Many thanks to Siep Kroonenberg and Heiko Oberdiek for their help.}
} 
\date{02. October 2007, version 0.3}

\maketitle

\tableofcontents

\section{What is it for?}

This package can be used to use the epspdf tools (see \url{http://tex.aanhet.net/epspdf/}) from within (pdf)LaTeX ``on the fly''. It is similar to and based on the epstopdf package.\footnote{You might also want to read the documentation of epstopdf. See \url{http://www.ctan.org/tex-archive/macros/latex/contrib/oberdiek/epstopdf.pdf}.} It is possible to pass several options to the epspdf conversion-command. 

This package can be used for the conversion of eps-files to pdf. The epspdf-tools itself can do the conversion both ways.

I am by no means an {\TeX}pert. Use this package at your own risk. What I did is to take the epsdpdf-package (\url{http://www.ctan.org/tex-archive/help/Catalogue/entries/epstopdf.html}) and adjusted it to my needs and then gave this the new name {\pack}. Heiko Oberdiek then improved the code a lot.

This package is helpful in general when you include eps-figures in a (pdf)LaTeX-document. The author uses it for the inclusion of eps-figures that are produced en-masse by a software packages like Stata, Mathematica or Maple and that are often updated. The package makes sure that I can include the eps-figures easily and the updating of the corresponding pdf's is done ``on-the-fly''. Using the epspdf-tools helps a lot to prepare a final pdf that is, for example, accepted by your print shop (really grayscale, prepress-ready, ...).

\section{Installation}

\begin{itemize}
  \item Go to \url{http://tex.aanhet.net/epspdf/} and follow the installation instructions there.
  
  Alternative URL's for epspdf are \\ \url{http://www.ctan.org/tex-archive/support/epspdf/} or\\ \url{http://www.ctan.org/tex-archive/help/Catalogue/entries/epspdf.html}
  
    See also Bruno Voisin's notes at \url{http://tug.org/pipermail/macostex-archives/2007-April/030318.html}.
    
  \item Make sure that you can use epspdf from the command line. I am using Mac OS X. After the installation of epspdf, the following command is working from the command line (assuming the file /Users/daniel/Desktop/testimage.eps exists):
\begin{verbatim}
[ibook-daniel:~] daniel% epspdf /Users/daniel/Desktop/testimage.eps
\end{verbatim}
It results in a file \verb"/Users/daniel/Desktop/testimage.pdf". 

I did no testing for other Systems (Windows,...) -- simply follow the instructions at the epspdf-website. It would be nice if you let me know whether this .sty-file works for you.\footnote{The package seems to work as expected  with a Linux/TeXLive2007 and with a Windows/MikTeX2.5 installation.}
  \item Put the sty-file {\pack}.sty for this package where TeX can find it. For example in the same directory as your main .tex file. Or -- again on Mac OS X -- in \verb"~/Library/texmf/tex/latex/" where the ``\verb"~"'' stands for your home directory.
  \item The package requires that shell escapes are enabled. You should get a warning in your .log-file if this is not the case.\footnote{However, a test with MikTeX and the command-line option -shell-escape resulted in the warning ``Package epstopdf Warning: Shell escape feature is not enabled.'' Nevertheless, the shell escape worked fine.}
  \item the package loads the epstopf-package as it is based on that.
\end{itemize}

\section{Usage}

Put in the preamble of your .tex-file the line
\begin{verbatim}
\usepackage[OPTIONSHERE]{epspdfconversion}
\end{verbatim}
where ``OPTIONSHERE'' can be either empty or be filled with the options described below.

If you typeset your document, and (pdf)LaTeX detects that you want to use an eps-figure, the {\pack}-package makes sure that it is converted to pdf to include it in your final pdf. 

There are two possibilities.\footnote{This functionality is provided by the  epstopdf package.} If you include your eps-figure \emph{with} the .eps extension, every typesetting procedure will trigger a conversion to pdf again. This makes sense if your eps-figure changes very often. Or, alternatively, you can include  the figure without the extension. Then there will be only a conversion if there is no corresponding .pdf-file.

In a section below, I include two figures, \verb"testimage.eps" and \verb"testimage-static.eps" with the following lines. \verb"testimage-static.eps" is converted to pdf only once, the other eps-file with every run of pdf(LaTeX).

\label{bilderbefehle}
\begin{verbatim}
\begin{center}
\includegraphics[width=0.5\textwidth]{testimage.eps}\\
\includegraphics[width=0.5\textwidth]{testimage-static}
\end{center} 
\end{verbatim}

\section{Options}

{\pack} accepts several options. All options change the conversion command that is used for the conversion of .eps to pdf. Table \ref{optiontable} gives an overview. The explanations are more or less taken from the epspdf-documentation.\query{\textcolor{red}{New in 0.3:} The list of options is a bit longer than before.}

\begin{table}[htbp]
\begin{center} 
\small
\begin{tabularx} {0.9\textwidth} {
>{\hsize=.8\hsize}X|
>{\hsize=1.2\hsize}X}  
\toprule
option & explanation \\ \midrule
& \\
%
\verb"help" & You will be shown the help of the epspdf command in your logfile. This option does not overrule all the others as previously.\\  & \\
%
\verb"simple" & the epspdf-conversion will be done with no option at all. Don't use it together with any of the options below.\\  & \\
%
\verb"gray | grey | GRAY | GREY" & gray | grey : convert eps-figures to grayscale (success not guaranteed); GRAY | GREY: Try harder to convert to grayscale (success still not guaranteed) \\  & \\
%
\verb"default | printer |" \verb"prepress | screen | ebook |" \verb"target=default |" \verb"target=printer | " \verb"target=prepess |" \verb"target=screen | " \verb"target=ebook"  & target use of pdf \\  & \\
%
\verb"pdfversion=default |" \verb"pdfversion=1.2 |" \verb"pdfversion=1.3 |" \verb"pdfversion=1.4"  & Pdf version to be generated. Setting another version than those on the left will result in an error. `default' means
whatever Ghostscript's default is. \\  & \\
%
\verb"bbox |" \verb"bbox=true" & Compute tight boundingbox\\  & \\
%
\verb"bbox=false" & don't compute tight boundingbox\\  & \\
%
\verb"nopdftops" & Ignore pdftops even if available (default: use if available)\\  & \\
%
\verb"pdftops" & use pdftops if available\\  & \\
%
\verb"custom={-dPDFX}" & This option allows you to pass a string to the ghostscript-commandline. On the left it would be  Here you can set custom options for conversion to pdf, 
view \href{http://pages.cs.wisc.edu/~ghost/doc/cvs/Use.htm}{Use.htm} and \href{http://pages.cs.wisc.edu/~ghost/doc/cvs/Ps2pdf.htm}{ps2pdf.htm} from 
the Ghostscript documentation set. The example on the left adds \verb"-dPDFX" to the ghostscript-call by epstopdf \\  & \\
%
\verb"psoptions={-level2}" & This sets the options for pdftops; the default is -level2, don?t include -eps or page number options; these will be generated by epstopdf itself \\  & \\
%
\verb"pagenumber={1}" & Page (in the eps-file) to be converted\\  & \\
%
\bottomrule
\end{tabularx}
\end{center}
\caption{Options for the package {\pack}.}
\label{optiontable}
\end{table}

Important: When there are several options in the first column, divided by |, this means that you should \emph{choose only one} of them. For example, it does not make sense have this in the preamble:
\begin{verbatim}
\usepackage[pdfversion=1.3,pdfversion=1.4]{epspdfconversion}
\end{verbatim}

\verb"\pdfminorversion": When you choose the options pdfversion=1.2 or pdfversion=1.3, you need to set \verb"\pdfminorversion" accordingly. The package checks if you have done that properly and shows a warning if not.\query{\textcolor{red}{New in 0.3:} This check is a new feature. Again thanks to Heiko Oberdiek.}

%You will find an entry like that in your log-file:
%%
%\begin{verbatim}
%package epspdfconversion info =>
%the conversion command defined in the preamble is: epspdf inputfile.eps
%\end{verbatim}

Thanks to Heiko Oberdiek, changing the options somewhere in the middle of your .tex document is supported. Writing
\begin{verbatim}
\epspdfconversionsetup{target=prepress,bbox}
\end{verbatim}
changes the options of {\pack} to \verb"target=prepress,bbox".
\query{\textcolor{red}{New in 0.3:} You don't need to redefine the conversion command to switch to other settings}

\section{The command \textbackslash\texttt{epspdfconversioncmdline}}

The options described above change the command that is used to call epspdf for the conversion from .eps to .pdf. %
\query{\textcolor{red}{New in 0.3:} the name of the command has changed}
Typing \verb"\epspdfconversioncmdline" somewhere in your source-.tex file will output the call that you have defined in your preamble. For example, this file has in the preamble

\begin{verbatim}
\usepackage[pdfversion=1.3,GRAY]{epspdfconversion}
\end{verbatim}

and the \verb"\epspdfconversioncmdline" then is:  \verb"epspdf --GRAY --version=1.3".

This means that you can use \verb"\renewcommand" to define you own \verb"\epspdfconversioncmdline". 

For example, to restore the behaviour of the epstopdf-package, you could write
%
\begin{verbatim}
\renewcommand{\epspdfconversioncmdline}%
{epstopdf }
\end{verbatim}
%
This allows you to use whatever tool you want for your conversion. But epstopdf really seems the way to go for eps->pdf.....

\section{A test}

What follows is the output of the two \verb"\includegraphics"-commands from page \pageref{bilderbefehle}. The first of the two figures is converted with every run of (pdf)LaTeX, the second is the \verb"testimage-static.pdf" that is already present.


\begin{center}
\includegraphics[width=0.5\textwidth]{testimage.eps}\\
\includegraphics[width=0.5\textwidth]{testimage-static}
\end{center} 


\section{--help of epstopdf}

The help of epspdf reads
%
\small
\begin{verbatim}
[ibook-daniel:~] daniel% epspdf --help
Convert between [e]ps and pdf formats
Usage: epspdf.rb [options] infile [outfile]

Default for outfile is file.pdf if infile is file.eps or file.ps
Default for outfile is file.eps if infile is file.pdf

    -I                               Ignore pdftops even if available
                                     (default: use if available)
    -U                               Use pdftops if available
                                     (overrides previous -I setting)
    -T, --target=TARGET              Target use of pdf; one of
                                     default, printer, prepress, screen, ebook
    -V, --version=VERSION            Pdf version to be generated;
                                     one of 1.2, 1.3, 1.4, default
    -C, --custom=CUSTOMOPTIONS       Custom options for conversion to pdf,
                                     view Use.htm and ps2pdf.htm from
                                     the Ghostscript documentation set
    -P, --psoptions=PSOPTIONS        Options for pdftops; default -level2,
                                     don't include -eps or page number options;
                                     these will be generated by the program
    -p, --pagenumber=PAGENUMBER      Page to be converted or selected
    -b, --bbox, --BoundingBox        Compute tight boundingbox
    -g, --gray, --grey               Convert to grayscale;
                                     success not guaranteed
    -G, --GRAY, --GREY               Try harder to convert to grayscale;
                                     success still not guaranteed
    -i, --info                       Info: display detected filetype
    -s                               Save (some) settings
    -d                               Debug: don't remove temp files

    -h, --help                       Show this message
\end{verbatim}
\normalsize


\section{What {\pack} writes in your log-file}
The package reports in the log-file what it is doing

%
\small
\begin{verbatim}
This is pdfTeXk, Version 3.141592-1.40.3 (Web2C 7.5.6) 
(format=pdflatex 2007.9.28)  2 OCT 2007 13:50
entering extended mode
\write18 enabled.
 %&-line parsing enabled.

[... Schnipp ....]

(/Users/daniel/Library/texmf/tex/latex/epspdfconversion/epspdfconversion.sty
Package: epspdfconversion 2007/10/02 v0.3 Conversion eps->pdf with epspdf-tools
 on the fly

(/usr/local/texlive/2007/texmf-dist/tex/latex/oberdiek/epstopdf.sty
Package: epstopdf 2006/08/26 v1.3 Conversion with epstopdf on the fly (HO)
)
(/usr/local/texlive/2007/texmf-dist/tex/latex/oberdiek/kvoptions.sty
Package: kvoptions 2006/08/22 v2.4 Connects package keyval with LaTeX options (
HO)
)
system(epspdf --help)...executed.

Package epspdfconversion Info: epspdf --version=1.2 <file>
(epspdfconversion)              on input line 186.
)

[... Schnipp ....]

system(epspdf --version=1.2 testimage.eps)...executed.

 <testimage.pdf, id=69, 505.89pt x 289.08pt>
File: testimage.pdf Graphic file (type pdf)
 <use testimage.pdf>
<testimage-static.pdf, id=70, 505.89pt x 289.08pt>
File: testimage-static.pdf Graphic file (type pdf)
 <use testimage-static.pdf>
[4 <./testimage.pdf> <./testimage-static.pdf>] (./epspdfconversion.aux) ) 

[... Schnipp ....]
\end{verbatim}
\normalsize

\section{Version-history, ToDo's}

\begin{description}
  \item[ToDo's] Nothing at the moment. Please report errors and missing features. 
  \item[v.0.3, 2007-10-02:] \begin{itemize}
  \item check whether \verb"\pdfminorversion" has been set in accordance with option pdfversion=...
  \item Use the kvoptions-package for the implemention of options. It uses key value syntax that can be used both as package options and a separate setup macro.
  \item Almost all options of epstopdf are now available as an option of this package.
  \item The command \verb"\epspdfconversionsetup" is new and allows a change of the options for this package anywhere in your document.
  \item The command \verb"\epspdfconversioncmdline" has been renamed to\\ \verb"\epspdfconversioncmdline".
  \item the documentation has been updated
\end{itemize}   
  \item[v.0.2, 2007-09-21:] the package is now simply based on epstopdf. It essentially defines \verb"\@namedef{Gin@rule@.eps}#1{{pdf}{.pdf}{`\epspdfconversioncmdline #1}}" differently than epstopdf. The code has been cleaned up. Improvements of documentation and additional warning about pdfminorversion....
  \item[v.0.1, 2007-09-21:] first try
\end{description}

\end{document}