summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-external.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-external.tex')
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-external.tex57
1 files changed, 51 insertions, 6 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-external.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-external.tex
index 742e9bd8d7b..fc4606b0848 100644
--- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-external.tex
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-external.tex
@@ -123,7 +123,9 @@ As we see in Figure~\ref{fig1}, the world is flat.
\item A more complex situation arises when a graphic file named
\meta{file name prefix}|.|\meta{suffix} \emph{does} exist. In
this case, this graphic file is included using the
- |\includegraphics| command. Furthermore, the text between
+ |\includegraphics| command%
+ \footnote{Actually, the command key \texttt{/pgf/images/include external} is invoked which calls an appropriate \texttt{\textbackslash includegraphics} command.}.
+ Furthermore, the text between
|\beginpgfgraphicnamed| and |\endpgfgraphicnamed| is ignored.
When the text is ``ignored,'' what actually happens is that all
@@ -266,11 +268,37 @@ way: You input the file |pgfexternal.tex|.
in your main file.
\end{filedescription}
-As a final remark, note that the |baseline| option does not work
-together with pictures written to an external graphic file. The simple
-reason is that there is no way to store this baseline information is
-an external graphic file.
+As a final remark, note that the |baseline| option does not work directly
+with pictures written to an external graphic file. The simple
+reason is that there is no way to store this baseline information in
+an external graphic file. To allow the |baseline| option (or any \TeX\ construction
+with non-zero depth), the baseline information is stored into a separate file.
+This file is named \marg{image file}|.dpth| and contains something like |5pt|.
+
+So, if you need baseline information, you will have to keep the external graphic file
+together with its~|.dpth| file. Furthermore, the short command in |\input pgfexternal.tex|
+is no longer enough because it ignores any baseline information. You will need to use
+|\input pgfexternalwithdepth.tex| instead (it is shown below). It is slightly longer,
+but it can be used in the same way as |pgfexternal.tex|.
+
+\begin{key}{/pgf/images/include external (initially \textbackslash pgfimage\{\#1\})}
+\label{pgf:includeexternalkey}
+\index{External Graphics!Bounding Box Issues}
+ This key constitutes the public interface to exchange the |\includegraphics| command used for the image inclusion.
+
+ Redefining this key allows to provide bounding box or viewport options:
+\begin{codeexample}[code only]
+\pgfkeys{/pgf/images/include external/.code={\includegraphics[viewport=0 0 211.28 175.686]{#1}}}
+\end{codeexample}
+ Do not forget the |.code| here which redefines the command.
+
+ One application could be image externalization and bounding box restrictions:
+ As far as I know, a |.pdf| graphics with restricted bounding box
+ is always cropped (which is not always desired). One solution could be to use |latex| and |dvips|
+ which doesn't have this restriction. Another is to manually provide the |viewport| option as shown above.
+ A possible value for |viewport| can be found in the |.pdf| image, search for |/MediaBox = [ ... ]|.
+\end{key}
\subsection{A Complete Example}
@@ -415,7 +443,7 @@ Output written on survey.pdf (1 page, 10006 bytes).
Transcript written on survey.log.
\end{codeexample}
-To our editor, we send the following files:
+ To our editor, we send the following files:
\begin{itemize}
\item The last |survey.tex| shown above.
\item The graphic file |survey-f1.pdf|.
@@ -427,6 +455,23 @@ To our editor, we send the following files:
(Alternatively, we can also directly add this line to our
|survey.tex| file).
\end{itemize}
+In case we have used the |baseline| option, we also need to include any |.dpth| files and we need to use the file |pgfexternalwithdepth.tex| instead of |pgfexternal.tex|. This file also checks for the existence of |.dpth| files containing baseline information, its contents is
+\begin{codeexample}[code only]
+\long\def\beginpgfgraphicnamed#1#2\endpgfgraphicnamed{%
+ \begingroup
+ \setbox1=\hbox{\includegraphics{#1}}%
+ \openin1=#1.dpth
+ \ifeof1 \box1
+ \else
+ \read1 to\pgfincludeexternalgraphicsdp\closein1
+ \dimen0=\pgfincludeexternalgraphicsdp\relax
+ \hbox{\lower\dimen0 \box1 }%
+ \fi
+ \endgroup
+}
+\end{codeexample}
+Again, we could simply copy these lines to our |survey.tex| file.
+
%%% Local Variables:
%%% mode: latex