summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/epspdfconversion/documentation/epspdfconversion_docu.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/epspdfconversion/documentation/epspdfconversion_docu.tex')
-rw-r--r--Master/texmf-dist/doc/latex/epspdfconversion/documentation/epspdfconversion_docu.tex121
1 files changed, 95 insertions, 26 deletions
diff --git a/Master/texmf-dist/doc/latex/epspdfconversion/documentation/epspdfconversion_docu.tex b/Master/texmf-dist/doc/latex/epspdfconversion/documentation/epspdfconversion_docu.tex
index 190af28cb02..505edc98ebb 100644
--- a/Master/texmf-dist/doc/latex/epspdfconversion/documentation/epspdfconversion_docu.tex
+++ b/Master/texmf-dist/doc/latex/epspdfconversion/documentation/epspdfconversion_docu.tex
@@ -9,12 +9,14 @@
\usepackage{tabularx}
-%DRAWING, IMAGES
+%DRAWING, IMAGES
\usepackage[final]{graphicx}
\usepackage{epic}%
\usepackage{color}%
-\usepackage[pdfversion=1.3,GRAY]{epspdfconversion}
+\usepackage[pdfversion=1.3,bbox=true,GRAY]{epspdfconversion}
+
+%\epstopdfsetup{update=false}
%DIMENSIONS
@@ -37,7 +39,7 @@ menucolor=black,
pagecolor=black,
urlcolor=dunkelblau,
hypertexnames=true,
-pdftitle = {The package epspdfconversion v0.3},
+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}
@@ -71,7 +73,7 @@ pdfauthor = {daniel.becker@uni-rostock.de}
\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}
+\date{25. November 2007, version 0.4}
\maketitle
@@ -79,33 +81,35 @@ pdfauthor = {daniel.becker@uni-rostock.de}
\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 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 epspdf-tools itself can do the conversion both ways.
+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 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.
+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 epspdf-tools helps a lot to prepare a final pdf that is, for example, accepted by your print shop (really grayscale, prepress-ready, ...).
+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 epspdf are \\ \url{http://www.ctan.org/tex-archive/support/epspdf/} or\\ \url{http://www.ctan.org/tex-archive/help/Catalogue/entries/epspdf.html}
+ 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 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):
+ \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 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.}
+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.
- \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.
+
+ 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}
@@ -118,9 +122,12 @@ where ``OPTIONSHERE'' can be either empty or be filled with the options describe
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.
+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.
-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).
+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}
@@ -132,12 +139,14 @@ In a section below, I include two figures, \verb"testimage.eps" and \verb"testim
\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.}
+{\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} {0.9\textwidth} {
+\begin{tabularx} {1.0\textwidth} {
>{\hsize=.8\hsize}X|
>{\hsize=1.2\hsize}X}
\toprule
@@ -148,7 +157,9 @@ option & explanation \\ \midrule
%
\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"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 \\ & \\
%
@@ -183,7 +194,7 @@ Important: When there are several options in the first column, divided by |, thi
\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.}
+\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:
%%
@@ -197,12 +208,12 @@ Thanks to Heiko Oberdiek, changing the options somewhere in the middle of your .
\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}
+\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{red}{New in 0.3:} the name of the command has changed}
+\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}
@@ -220,18 +231,72 @@ For example, to restore the behaviour of the epstopdf-package, you could write
{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.....
+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 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.
+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}
+\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}
@@ -317,15 +382,19 @@ File: testimage.pdf Graphic file (type pdf)
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[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.