summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/epspdfconversion/example/epspdfconversion_docu.tex
blob: 59f86c523910b0b21aa480362e907a52329dcd2e (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

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

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

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

\usepackage{amsmath}
\usepackage{amssymb}

%Anführungen mit \enquote{++++}
\usepackage[babel,%
english= american, %american, 
german=quotes %, guillemets, swiss
]{csquotes}


%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}


\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}
}

\usepackage{ltxtable}


%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 enables the use of the epspdf tools (see \url{http://tex.aanhet.net/epspdf/}) from within (pdf)LaTeX \enquote{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. 

While this package can be used for the conversion of eps-files to pdf, the \verb"epspdf"-tools itself can do the conversion both ways.\footnote{It might be possible to add support for conversion like pdf->pdf or pdf->eps and so on. If you are interested, contact me.}

Use this package at your own risk.\footnote{I am by no means an {\TeX}pert. 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.}

I am using this package 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}

If you are using a recent version of TeXLive ($\geqslant$ 2008), you can skip steps 1-4.

\begin{enumerate}
  \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 the package needs a recent version of the epstopf-package as a prerequisite, at least version 2.2.
    
  \item Make sure that you can use \verb"epspdf" from the command line. I am using Mac OS X. After the installation of epspdf (or with TeXLive / MacTeX $\geqslant$ 2008), the following command is working from the command line (assuming the file \verb"/Users/daniel/Desktop/testimage.eps" exists):
\begin{verbatim}
macbook-daniel:~ daniel$ which epstopdf
/usr/texbin/epstopdf
macbook-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 is already included in your distribution.
  \item The package requires that shell escapes are enabled. You should get a warning in your .log-file if this is not the case.
  
  
  
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.'' Try \verb"--enable-write18" if you are using MikTeX. Look for \enquote{shell escape} and \enquote{write18} in the Help-Section of your preferred application for Typesetting on how to enable it (TeXShop, WinEdt, ....).

  

\end{enumerate}

\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 a pdf that is then included.

By default, if you include your eps-figure \emph{with} the \verb".eps" extension, as in
\begin{verbatim}
\includegraphics[width=0.5\textwidth]{image.eps}
\end{verbatim} 
, there will be a conversion to pdf named \verb"image-epspdf-to.pdf" that is then used in your document. The next run will only call a conversion if the original .eps-file is newer (has been updated in the meanwhile). This is to save typesetting time. You can change this behaviour with the option \verb"update=false", see below.

If you insist on using \verb"\includegraphics" without the extension, as in
\begin{verbatim}
\includegraphics[width=0.5\textwidth]{image}
\end{verbatim} 
, the situation is more complicated. If you are using  \verb"\includegraphics" without the extension, pdfLaTeX when used with epstopdf or {\pack} looks for files that can be used in the following order:
\begin{verbatim}
Package grfext Info: Graphics extension search list:
(grfext)             [.png,.pdf,.jpg,.mps,.jpeg,.jbig2,.jb2,.PNG,.PDF,
.JPG,.JPEG,.JBIG2,.JB2,.eps]
\end{verbatim}
If - for whatever reason, a file \verb"image.png" exists, this one will be used, not the .eps or the converted pdf. However, you can use the option prepend the \enquote{Graphics extension search list} will look like this:
\begin{verbatim}
Package grfext Info: Graphics extension search list:
(grfext)             [.eps,.png,.pdf,.jpg,.mps,.jpeg,.jbig2,.jb2,.PNG,.PDF,
.JPG,.JPEG,.JBIG2,.JB2]
\end{verbatim}
This implies that image.eps is found first and used with a conversion to pdf is necessary. Complicated? Consider to use \verb"\includegraphics" with the extension, that avoids confusion which file actually makes it into you document. See options prepend, prefersuffix, update, suffix below and try to figure out how many different scenarios there are. 

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.  Table \ref{optiontable} gives an overview. The explanations are more or less taken from the documentationof  epspdf and epstopdf.



%Put the following code in your main document. store the table in an extra-tex-file named LongTable.tex that might live in a subfolder Tables

\LTXtable{\textwidth}{optionstable.tex}



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.


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". Other options than \verb"target=..." remain in effect.


\section{\textbackslash\texttt{epspdfconversioncmdline}}

Many of the options described above change the command that is used to call epspdf for the conversion from .eps to .pdf. %

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 eps->pdf conversion.


\section{A test}

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


\begin{center}
\includegraphics[width=0.5\textwidth]{image.eps}
\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}
\fbox{\includegraphics[width=4cm]{image2.eps}}
}% <= New group ended; grayscaling,bbox set to previous value.
\includegraphics[width=4cm]{image2.eps}
\end{verbatim}
\normalsize

The figure \verb"image2.eps" will be exceptionally in color, other figures in gray, according to the general rule for this document:

{% <= New group started
\epspdfconversionsetup{nogray,bbox=false}
\fbox{\includegraphics[width=4cm]{image2.eps}}
}% <= New group ended; grayscaling,bbox set to previous value.
\includegraphics[width=4cm]{image.eps}
 
\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}
# FOR USERS OF epstopdf v1.5 and later only:
add_cus_dep('eps', 'pdf', 0, 'cus_dep_require_primary_run');
\end{verbatim}
\normalsize

Note that both epstopdf and latexmk are under active development. Please check the latexmk-documentation to if you have difficulties with setting up a latexmk-configuration that works together with epstopdf and {\pack}.

\section{--help of epstopdf}

The help of epspdf (version 0.4.1) reads:
%
\small
\begin{verbatim}
macbook-daniel:~ daniel$ epspdf --help
Epspdf version 0.4.1
Copyright (C) 2006, 2008, 2009 Siep Kroonenberg
Epspdf 0.4.0
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

    -g, --gray, --grey               Convert to grayscale;
                                     success not guaranteed
    -G, --GRAY, --GREY               Try harder to convert to grayscale
    -p, --pagenumber=PAGENUMBER      Page to be converted or selected
    -b, --bbox, --BoundingBox        Compute tight boundingbox
    -n, --no-hires                   Don't use hires boundingbox
    -r, --hires                      Use hires boundingbox
    -T, --target=TARGET              Target use of pdf; one of
                                     default, printer, prepress, screen, ebook
    -N, --pdfversion=PDFVERSION      Pdf version to be generated
    -V, --version=PDFVERSION         Deprecated; use `-N' or `--pdfversion'.
    -I                               Ignore pdftops even if available
                                     (default: use if available)
    -U                               Use pdftops if available
                                     (overrides previous -I setting)
    -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 -level3,
                                     don't include -eps or page number options;
                                     these will be generated by the program
    -i, --info                       Info: display detected filetype
    -s                               Save (some) settings
    -d                               Debug: don't remove temp files

    -v                               Prints version info
    -h, --help                       Show this message
macbook-daniel:~ daniel$ 
\end{verbatim}
\normalsize



\vfill

\section{Version-history, ToDo's}







\begin{description}
  \item[ToDo's] add support for ps->pdf, pdf->pdf / add support for tif and others in pdflatex via convert / add support for pdf-inclusion in latex (not pdf-latex) / add support for more file-types (tif, jpeg,...) in latex (not pdf-latex). Please report errors and missing features.
  \item[v.0.5, 2009-09-02:] this update makes use of changes in the epstopdf-package v2.2\begin{itemize}
  \item new options 
        update,verbose,prefersuffix,suffix,outdir
        (they are really epstopdf options, but can be set 
        as options for this package)
  \item default is that converted files have a suffix
  \item info in logfile about the setup that is used for epstopdf
  \item new options hires, no-hires
\end{itemize} 
  \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}