summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-external.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-external.tex')
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-external.tex29
1 files changed, 17 insertions, 12 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-external.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-external.tex
index 7d2130b035b..793d4c94618 100644
--- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-external.tex
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-external.tex
@@ -105,20 +105,15 @@ From this point on, successive runs of \LaTeX\ will use the final graphics files
\label{extlib:systemcall:option}
A template string used to generate system calls. Inside of \marg{template}, the macro |\image| can be used as placeholder for the image which is about to be generated while |\texsource| contains the main file name (in truth, it contains |\input|\marg{main file name}, but that doesn't matter).
- The default is
+ The default depends on the value of |\pgfsysdriver|. For |pgfsys-pdftex.def|, it is
\begin{codeexample}[code only]
\tikzset{external/system call={pdflatex \tikzexternalcheckshellescape -halt-on-error
- -interaction=batchmode -jobname "\image" "\texsource"}
+ -interaction=batchmode -jobname "\image" "\texsource"}}
\end{codeexample}
\noindent where \declareandlabel{\tikzexternalcheckshellescape} inserts the value of the configuration key |shell escape|
if and only if the current document has been typeset with |-shell-escape|\footnote{Note that this is always true for the default configuration. This security consideration applies mainly for \texttt{mode=list and make} which will also work \emph{without} shell escapes.}.
- For |eps| output, you can (and need to) use
-\begin{codeexample}[code only, tikz syntax=false]
-\tikzset{external/system call={latex \tikzexternalcheckshellescape -halt-on-error
- -interaction=batchmode -jobname "\image" "\texsource";
- dvips -o "\image".ps "\image".dvi}}
-\end{codeexample}
+ Other drivers result in slightly different calls. There is support for |lualatex|, |xelatex|, and |dvips|. The precise values are written to the |.log| file as soon as you attempt to compile a document.
The argument \marg{template} will be expanded using |\edef|, so any control sequences will be expanded. During this evaluation, `|\\|' will result in a normal backslash, `|\|'. Furthermore, double quotes `|"|', single quotes `|'|', semicolons and dashes `|-|' will be made to normal characters if any package uses them as macros. This ensures compatibility with the |german| package, for example.
\end{key}
@@ -138,13 +133,13 @@ There are, however, some points which need your attention when you try to use
For point a), a |\ref| inside of an externalized graphics works \emph{only} if you issue the required system call \emph{manually} or by |make|. The initial configuration |mode=convert with system call| does \emph{not} support |\ref|. But you can copy--paste the system call generated by |mode=convert with system call| and issue it manually. The reason is that |\ref| information is stored in the main |.aux| file -- but this auxiliary file is not completely written when |mode=convert with system call| is invoked (there is a race condition). Note that |\pageref| is not supported (sorry). Thus: if you have |\ref| inside of external graphics, consider using |mode=list and make| or copy--paste the system call for the image(s) and issue it manually.
-Point b) is realized automatically by the external library. In detail, a |\label| inside of an externalized graphics causes the external library to generate separate auxiliary files for every external image. These files are called \meta{imagename}|.dpth|. The extension |.dpth| indicates that the file also contains the image's depth (the |baseline| key of \tikzname). Furthermore, anything which would have been written to an |.aux| file will be redirected to the |.dpth| file -- but only things which occur inside of the externalized |tikzpicture| environment. When the main document loads the image, it will copy the |.dpth| file into the main |.aux| file. Then, successive compilations of the main document contain the external |\label| information. In other words, a |\label| in an external graphics needs the following work flow:
+Point b) is implemented automatically by the external library. In detail, a |\label| inside of an externalized graphics causes the external library to generate separate auxiliary files for every external image. These files are called \meta{imagename}|.dpth|. The extension |.dpth| indicates that the file also contains the image's depth (the |baseline| key of \tikzname). Furthermore, anything which would have been written to an |.aux| file will be redirected to the |.dpth| file -- but only things which occur inside of the externalized |tikzpicture| environment. When the main document loads the image, it will copy the |.dpth| file into the main |.aux| file. Then, successive compilations of the main document contain the external |\label| information. In other words, a |\label| in an external graphics needs the following work flow:
\begin{enumerate}
\item The external graphics needs to be generated together with its |.dpth| (usually automatically by \tikzname).
\item The main document includes the external graphics and copies the |.dpth| content into its main |.aux| file.
\item The main document needs to be translated once again to re-read its |.aux| file\footnote{Note that it is not possible to activate the content of an auxiliary file after \texttt{\textbackslash begin\{document\}} in \LaTeX.}.
\end{enumerate}
-There is just one special case: if a |\label|/|\ref| combination is realized itsself by a |tikzpicture| which should be externalized, you need to proceed as for case a) since |mode=convert with system call| can't handle that stuff on its own. Thus, |\label| works automatically, just translate the main document often enough.
+There is just one special case: if a |\label|/|\ref| combination is implemented itsself by a |tikzpicture| which should be externalized, you need to proceed as for case a) since |mode=convert with system call| can't handle that stuff on its own. Thus, |\label| works automatically, just translate the main document often enough.
\begin{key}{/tikz/external/aux in dpth=\marg{boolean} (initially true)}
Allows to disable the feature. Disabling it will safe one |\newwrite| command, i.e.\ a write register.
@@ -361,7 +356,17 @@ pdflatex -shell-escape main
The choice \declare{diff} is the same as MD5 -- except that it compares the picture content as-is instead of a hash. The |.md5| file will be used to compare an old version with the current one -- but its content is some ``normalized'' version of the picture for internal use.
- \paragraph{Attention:} the content--based strategies |md5| and |diff| operate on the picture content -- and only on the picture content. Here, ``picture content'' only includes the top--level tokens; no expansion is applied and no included files are part of the strategies. If you change preamble styles, you have to rebuild the figures manually (for example by deleting the generated graphics files). If you have include files, consider using |\tikzpicturedependsonfile| and its variants. Since this key provides heuristics, you should always remake your figures before you finally publish your document.
+ \paragraph{Attention:} the content--based strategies |md5| and |diff| operate on the picture content -- and only on the picture content. Here, ``picture content'' only includes the top--level tokens; no expansion is applied and no included files are part of the strategies. If you change preamble styles, you have to rebuild the figures manually (for example by deleting the generated graphics files). If you have include files, consider using |\tikzpicturedependsonfile| and its variants. Since this key provides heuristics, you should always remake your figures before you finally publish your document. Example: Suppose we have the following picture which depends on a command |\mycommand|:
+\begin{codeexample}[code only]
+\def\mycommand{My comment}
+
+\begin{tikzpicture}
+
+\node at (0,0) {\mycommand};
+
+\end{tikzpicture}
+\end{codeexample}
+ What happens if you change ``My comment'' to ``My super comment''? Well, |external| will \emph{not} pick it up; you will need to handle this manually. However, if you modify anything between |\begin{tikzpicture}| and |\end{tikzpicture}|, the external library \emph{will} pick it up and regenerate the picture.
The |up to date check| is applied for |mode=convert with system call| and |mode=list and make|.
\end{key}
@@ -451,7 +456,7 @@ pdflatex -shell-escape
% step 1: generate main.makefile:
pdflatex main
% step 2: generate ALL graphics on 2 processors:
-make -j 2 main.makefile
+make -j 2 -f main.makefile
% step 3: include the graphics:
pdflatex main
\end{codeexample}