summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/epspdfconversion/documentation/epspdfconversion_docu.tex
blob: 505edc98ebbde200d76335159f7b7e36b1666f06 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
\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,bbox=true,GRAY]{epspdfconversion}

%\epstopdfsetup{update=false}


%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.4}, 
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{25. November 2007, version 0.4}

\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 that uses the script \verb"epstopdf" for the actual conversion while this packages uses \verb"epspdf" (Note the \verb"epsTOpdf" vs \verb"epspdf").\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 \verb"epspdf" conversion-command. 

This package can be used for the conversion of eps-files to pdf. The \verb"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 epstopdf-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 \verb"epspdf"-tools (and not \verb"epstopdf") 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 \verb"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 \verb"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 \verb"epspdf"-website. It would be nice if you let me know whether this package 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.
  
  If you are using MikTeX, you can use the package-manager to install {\pack}. If you are using a recent version of TeXLive, it might be included in your distribution already.
  \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.''} Look for ``shell escape'' in the Help-Section of your preferred application for Typesetting on how to enable it (TeXShop, WinEdt, ....).
  \item the package needs the epstopf-package as a prerequisite.\query{\textcolor{red}{New in 0.4:} It is recommended that epstopdf is at version 1.5 or higher} Usually, it is already part of your installation of {\TeX}. It is recommended that epstopdf is at least at version 1.5. 
\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. 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.

If you have at least version 1.5 of the epstopdf-package installed, the situation is better: If you include your eps-figure with the extension .eps, the conversion eps->pdf is only done if the pdf-version of your figure is either missing or outdated because the eps-file has been modified.\query{\textcolor{red}{New in 0.4:} Why you should install epstopdf at least in version 1.5....} This saves a lot of time for the typesetting process. If you include the file without the extension, the same rule applies.\footnote{This functionality is provided by loading the epstopdf-package with options [update,prepend] in the background. See the documentation for the epstopdf-package.} It is easy to switch back to the old behaviour where all figures included with the extension .eps are converted with every run of pdflatex. Simply put \verb"\epstopdfsetup{update=false}" in your .tex-source file. This might be useful if you play around a lot with the several options this package provides for the conversion.


Below, I include a figure \verb"testimage.eps" and another \verb"testimage-static.eps" with the following lines.

\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.4:} The list of options is a bit longer than before.}



\begin{table}[htbp]
\begin{center} 
\small
\begin{tabularx} {1.0\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"nogray | nogrey" & nogray | nogrey : do not try to convert eps-figures to grayscale \\  & \\
%
\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{blue}{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{blue}{New in 0.3:} You don't need to redefine the whole 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{blue}{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 epspdf really seems the way to go for eps->pdf.....


\section{A test}

What follows is the output of the \verb"\includegraphics"-command from page \pageref{bilderbefehle}.


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

\section{Switching options temporarily}

It is possible to switch the options only temporarily using curly braces. Consider you have set the options \verb"GRAY" such that all your figures appear in grayscale. Now you want color for a single figure. This can be done like this:
%
\small
\begin{verbatim}
{% <= New group started
\epspdfconversionsetup{nogray,bbox=false}

\begin{center}
\fbox{\includegraphics[width=8cm]{testimage2.eps}}
\end{center}
}% <= New group ended; grayscaling,bbox set to previous value.

\begin{center}
\fbox{\includegraphics[width=8cm]{testimage3.eps}}
\end{center}
\end{verbatim}
\normalsize

Figure \verb"testimage2.eps" will be in color, figure \verb"testimage3.eps" will then be converted according to the general rule for you document:

{% <= New group started
\epspdfconversionsetup{nogray,bbox=false}

\begin{center}
\fbox{\includegraphics[width=6cm]{testimage2.eps}}
\end{center}
}% <= New group ended; grayscaling,bbox set to previous value.

\begin{center}
\fbox{\includegraphics[width=6cm]{testimage3.eps}}
\end{center}
 
\section{A note for users of latexmk}

latexmk is a perl script for running LaTeX, BibTex, Makeindex etc the correct number of times. See \url{http://www.phys.psu.edu/~collins/software/latexmk/}. It can be configured to run pdflatex if an eps-image has been updated (since version V. 3.21i). In your local configuration file, you should have something like this:

\small
\begin{verbatim}
# Custom dependency and function(s) for epstopdf package

# FOR USERS OF epstopf v1.4 and before: should also work with v1.5 and later
# note: you may get extras runs if you use the .eps extension in the 
#\includegraphics command
#add_cus_dep('eps', 'pdf', 0, 'cus_dep_delete_dest');

# FOR USERS OF epstopdf v1.5 and later only:
# load it as \usepackage[update,prepend]{epstopdf}
# triggers a pdflatex-run such that epstopdf will update the pdf-version of the image
add_cus_dep('eps', 'pdf', 0, 'cus_dep_require_primary_run');
\end{verbatim}
\normalsize

\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.4, 2007-11-24:] the epstopdf-package is now loaded with options [update,prepend] (works only when epstopdf version 1.5 is used) An update of epstopd.sty (part of the oberdiek-bundle) is recommended. Added options nogrey,nogray
  \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}