| 1 |
% Copyright 2019 by Christian Feuersaenger |
| 2 |
% |
| 3 |
% This file may be distributed and/or modified |
| 4 |
% |
| 5 |
% 1. under the LaTeX Project Public License and/or |
| 6 |
% 2. under the GNU Free Documentation License. |
| 7 |
% |
| 8 |
% See the file doc/generic/pgf/licenses/LICENSE for more details. |
| 9 |
|
| 10 |
|
| 11 |
\section{Externalization Library} |
| 12 |
\label{section-libs-external} |
| 13 |
|
| 14 |
{ |
| 15 |
\pgfkeys{ |
| 16 |
/pdflinks/search key prefixes in/.add={/tikz/external/,}{} |
| 17 |
} |
| 18 |
{\noindent {\emph{by Christian Feuersänger}}} |
| 19 |
|
| 20 |
\begin{tikzlibrary}{external} |
| 21 |
This library provides a high-level automatic or semi-automatic export |
| 22 |
feature for \tikzname\ pictures. Its purpose is to convert each picture to |
| 23 |
a separate \pdf\ without changing the document as such. |
| 24 |
|
| 25 |
It also externalizes |\label| information (and other aux file related |
| 26 |
stuff) using auxiliary files. |
| 27 |
\end{tikzlibrary} |
| 28 |
|
| 29 |
|
| 30 |
\subsection{Overview} |
| 31 |
|
| 32 |
There are several reasons why external images for at least some pictures are of |
| 33 |
interest: |
| 34 |
% |
| 35 |
\begin{enumerate} |
| 36 |
\item Larger picture require a considerable amount of time, which is |
| 37 |
necessary for every compilation. However, only few images will change |
| 38 |
from run to run. It can simply save time to export finished images and |
| 39 |
include them as final graphics. |
| 40 |
\item It may be desirable to have final images for some graphics, for |
| 41 |
example to include them in third--party programs or to communicate them |
| 42 |
electronically. |
| 43 |
\item It may be necessary to typeset a file in environments where \pgfname\ |
| 44 |
and \tikzname\ are not available. In this case, external images are the |
| 45 |
only way to ensure compatibility. |
| 46 |
\end{enumerate} |
| 47 |
% |
| 48 |
The purpose of this library is to provide a way to export any \tikzname-picture |
| 49 |
to separate \pdf\ (or \eps) images without changing the main document. It is |
| 50 |
actually a simple user interface to the |\beginpgfgraphicnamed| $\dotsc$ |
| 51 |
|\endpgfgraphicnamed| framework of \pgfname\ which is discussed in |
| 52 |
section~\ref{section-external}. |
| 53 |
|
| 54 |
|
| 55 |
\subsection{Requirements} |
| 56 |
|
| 57 |
For most users, the library does not need special attention since requirements |
| 58 |
are met anyway. It collects all tokens between |\begin{tikzpicture}| and the |
| 59 |
next following |\end{tikzpicture}| and replaces them by the appropriate |
| 60 |
graphics or it takes steps to generate such an image. |
| 61 |
%For Con\TeX t and plain \TeX\ users, the appropriate begin and end picture |
| 62 |
%statements apply. |
| 63 |
|
| 64 |
It can't expand macros during this step, so the only requirement is that every |
| 65 |
picture's end is directly reachable from its beginning, without further macro |
| 66 |
expansion. Furthermore, the library assumes that all \LaTeX\ pictures are ended |
| 67 |
with |\end{tikzpicture}|. |
| 68 |
%In Con\TeX t, the end command is assumed to be |\stoptikzpicture| and for plain |
| 69 |
%\TeX\ it is |\endtikzpicture|. |
| 70 |
|
| 71 |
The library always searches for the \emph{next} picture's end, |
| 72 |
|\end{tikzpicture}|. As a consequence, you can't use nested pictures directly. |
| 73 |
You \emph{can} nest pictures, but you have to avoid that the nested picture's |
| 74 |
|\end| command is found before the outer |\end| command (for example using |
| 75 |
bracing constructs or by writing the nested picture into a separate macro |
| 76 |
call). |
| 77 |
|
| 78 |
Consider using the |\tikzexternaldisable| method in case you'd like to skip |
| 79 |
selected pictures which do not meet the requirements. |
| 80 |
|
| 81 |
|
| 82 |
\subsection{A Word About Con\TeX t And Plain \TeX} |
| 83 |
|
| 84 |
Currently, the basic layer backend |\beginpgfgraphicnamed| $\dotsc$ |
| 85 |
|\endpgfgraphicnamed| relies on \LaTeX\ only, so externalization is currently |
| 86 |
only supported for \LaTeX. |
| 87 |
%The library comes in three different versions, one for \LaTeX, one for Con\TeX |
| 88 |
%t and one for plain \TeX. For reasons of simplicity, examples in this manual |
| 89 |
%only refer to \LaTeX\ (especially |pdflatex|). |
| 90 |
|
| 91 |
|
| 92 |
\subsection{Externalizing Graphics} |
| 93 |
|
| 94 |
After loading the library, a call to |\tikzexternalize| is necessary to |
| 95 |
activate the externalization. |
| 96 |
% |
| 97 |
\begin{codeexample}[code only] |
| 98 |
\documentclass{article} |
| 99 |
% main document, called main.tex |
| 100 |
\usepackage{tikz} |
| 101 |
|
| 102 |
\usetikzlibrary{external} |
| 103 |
\tikzexternalize % activate! |
| 104 |
|
| 105 |
\begin{document} |
| 106 |
\begin{tikzpicture} |
| 107 |
\node {root} |
| 108 |
child {node {left}} |
| 109 |
child {node {right} |
| 110 |
child {node {child}} |
| 111 |
child {node {child}} |
| 112 |
}; |
| 113 |
\end{tikzpicture} |
| 114 |
|
| 115 |
A simple image is \tikz \fill (0,0) circle(5pt);. |
| 116 |
\end{document} |
| 117 |
\end{codeexample} |
| 118 |
|
| 119 |
The method works as follows: if the document is typeset normally, the library |
| 120 |
searches for replacement images for every picture. Filenames are generated |
| 121 |
automatically in the default configuration. In our case, the two file names |
| 122 |
will be |main-figure0| and |main-figure1|. If they exist, those images are |
| 123 |
simply included and the pictures as such are not processed. If graphics files |
| 124 |
do not exist, steps are taken to generate the missing ones. Since (currently) |
| 125 |
only one output file can be set, each missing image needs to be generated by a |
| 126 |
separate run of \LaTeX\ in which the |\jobname| is set to the desired image |
| 127 |
file name. In the default configuration |mode=convert with system call|, these |
| 128 |
commands are issued automatically by using the |\write18| method to call system |
| 129 |
commands. It is also possible to output every required file name or to generate |
| 130 |
a |makefile|; users will need to issue the required commands manually (or with |
| 131 |
|make|). The probably most comfortable way is to use the default configuration |
| 132 |
with |
| 133 |
% |
| 134 |
\begin{codeexample}[code only, tikz syntax=false] |
| 135 |
pdflatex -shell-escape main |
| 136 |
\end{codeexample} |
| 137 |
% |
| 138 |
\noindent which authorizes |pdflatex| to call itself recursively to generate |
| 139 |
the images. When it finishes, all images are generated and the document already |
| 140 |
includes them. |
| 141 |
|
| 142 |
From this point on, successive runs of \LaTeX\ will use the final graphics |
| 143 |
files, the pictures won't be used anymore. |
| 144 |
Section~\ref{section-libs-external-nopgf} contains details about how to submit |
| 145 |
such a file to environments where \pgfname\ is not available. |
| 146 |
|
| 147 |
\begin{command}{\tikzexternalize\oarg{optional arguments}} |
| 148 |
This command activates the externalization. It installs commands to replace |
| 149 |
every \tikzname-picture. It needs to be called before |\begin{document}| |
| 150 |
because it may need to install its separate shipout routine. |
| 151 |
|
| 152 |
The \meta{optional arguments} can be any of the keys described below. |
| 153 |
|
| 154 |
Note that the generation/modification of auxiliary files like |.aux|, |
| 155 |
|.toc| etc.\ is usually suppressed while a single image is externalized |
| 156 |
(details for |\label| support follow). |
| 157 |
|
| 158 |
It is also possible to write |\tikzexternalize|\marg{main job name} if the |
| 159 |
argument is delimited by curly braces. This case is mainly for backwards |
| 160 |
compatibility and is no longer necessary. Since it might be useful in rare |
| 161 |
circumstances, it is documented in section~\ref{sec:external:detail}. |
| 162 |
|
| 163 |
A detailed description about the process of externalization is provided in |
| 164 |
section~\ref{sec:external:detail}. |
| 165 |
|
| 166 |
\begin{command}{\tikzexternalrealjob} |
| 167 |
After the library is loaded, this macro will \emph{always} contain the |
| 168 |
correct main job's name (in the example above, it is |main|). It is to |
| 169 |
be used instead of |\jobname| when the externalization is in effect. |
| 170 |
\end{command} |
| 171 |
% |
| 172 |
\begin{command}{\pgfactualjobname} |
| 173 |
Once |\tikzexternalize| has been called, |\pgfactualjobname| contains |
| 174 |
the name of the currently generated output file (which may be |main| or |
| 175 |
|main-figure0| or |main-figure1| in our example above). |
| 176 |
\end{command} |
| 177 |
% |
| 178 |
\begin{command}{\jobname} |
| 179 |
The value of |\jobname| is one of |\tikzexternalrealjob| or |
| 180 |
|\pgfactualjobname|, depending on the configuration. In short: if |
| 181 |
auxiliary file support (|\label| and |\ref|) is activated, |
| 182 |
|\jobname=\tikzexternalrealjob| (since that's the base file name of |
| 183 |
auxiliary files). |
| 184 |
\end{command} |
| 185 |
\end{command} |
| 186 |
|
| 187 |
\begin{key}{/tikz/external/system call=\marg{template}} |
| 188 |
\label{extlib:systemcall:option} |
| 189 |
A template string used to generate system calls. Inside of \marg{template}, |
| 190 |
the macro |\image| can be used as placeholder for the image which is about |
| 191 |
to be generated while |\texsource| contains the main file name (in truth, |
| 192 |
it contains |\input|\marg{main file name}, but that doesn't matter). |
| 193 |
|
| 194 |
The default depends on the value of |\pgfsysdriver|. For |
| 195 |
|pgfsys-pdftex.def|, it is |
| 196 |
% |
| 197 |
\begin{codeexample}[code only] |
| 198 |
\tikzset{external/system call={pdflatex \tikzexternalcheckshellescape -halt-on-error |
| 199 |
-interaction=batchmode -jobname "\image" "\texsource"}} |
| 200 |
\end{codeexample} |
| 201 |
% |
| 202 |
\noindent where \declareandlabel{\tikzexternalcheckshellescape} inserts the |
| 203 |
value of the configuration key |shell escape| if and only if the current |
| 204 |
document has been typeset with |-shell-escape|\footnote{Note that this is |
| 205 |
always true for the default configuration. This security consideration |
| 206 |
applies mainly for \texttt{mode=list and make} which will also work |
| 207 |
\emph{without} shell escapes.}. |
| 208 |
|
| 209 |
Other drivers result in slightly different calls. There is support for |
| 210 |
|lualatex|, |xelatex|, and |dvips|. The precise values are written to the |
| 211 |
|.log| file as soon as you attempt to compile a document. |
| 212 |
|
| 213 |
The argument \marg{template} will be expanded using |\edef|, so any control |
| 214 |
sequences will be expanded. During this evaluation, `|\\|' will result in a |
| 215 |
normal backslash, `|\|'. Furthermore, double quotes `|"|', single quotes |
| 216 |
`|'|', semicolons and dashes `|-|' will be made to normal characters if any |
| 217 |
package uses them as macros. This ensures compatibility with the |german| |
| 218 |
package, for example. |
| 219 |
\end{key} |
| 220 |
|
| 221 |
\begin{key}{/tikz/external/shell escape=\marg{command-line arg} (initially -shell-escape)} |
| 222 |
Contains the command line option for |latex| which enables the |\write18| |
| 223 |
feature. For \TeX-Live, this is |-shell-escape|. For MiK\TeX, you should |
| 224 |
use |\tikzexternalize[shell escape=-enable-write18]|. |
| 225 |
\end{key} |
| 226 |
|
| 227 |
|
| 228 |
\subsubsection{Support for Labels and References In External Files} |
| 229 |
|
| 230 |
The |external| library comes with extra support for |\label| and |\ref| (and |
| 231 |
other commands which usually store information in the |.aux| file) inside an |
| 232 |
external files. |
| 233 |
|
| 234 |
In particular, it supports the two use-cases |
| 235 |
% |
| 236 |
\begin{enumerate} |
| 237 |
\item[a)] |\ref| to something in the main document inside an externalized |
| 238 |
graphics or |
| 239 |
\item[b)] |\label| in the externalized graphics which is referenced in the |
| 240 |
main document. |
| 241 |
\end{enumerate} |
| 242 |
|
| 243 |
The only restriction is that you need to compile your document multiple times |
| 244 |
(as usual for references). |
| 245 |
|
| 246 |
\paragraph{NOTE:} |
| 247 |
support for a) is unavailable for versions up to and including \pgfname\ 3.0.1. |
| 248 |
|
| 249 |
\begin{key}{/tikz/external/aux in dpth=\marg{boolean} (initially true)} |
| 250 |
Allows to enable or disable the feature which handles references and labels |
| 251 |
as part of image externalization. Disabling it will safe one |\newwrite| |
| 252 |
command, i.e.\ a write register. |
| 253 |
|
| 254 |
Also see the |disable dependency files| feature. |
| 255 |
|
| 256 |
Here are some implementation details on how references within/from external |
| 257 |
graphics work for those who would like to know the details: |
| 258 |
|
| 259 |
For point a), a |\ref| inside of an externalized graphics works by reading |
| 260 |
the main document's |.aux| file. To this end, the standard |
| 261 |
|mode=convert with system call| detects such references and reschedules the |
| 262 |
externalization to |\end{document}.|\footnote{Note that this requires the |
| 263 |
\texttt{atveryend} package. The purpose to reschedule the externalization |
| 264 |
is to access the main job's aux file, but only after it has been written |
| 265 |
completely.} Other values of |mode| require just one attempt to externalize |
| 266 |
the picture. |
| 267 |
|
| 268 |
Note that |\pageref| is not supported (sorry). |
| 269 |
|
| 270 |
Point b) works as follows: a |\label| inside of an externalized graphics |
| 271 |
causes the |external| library to generate separate auxiliary files for every |
| 272 |
external image. These files are called \meta{imagename}|.dpth|. The |
| 273 |
extension |.dpth| indicates that the file also contains the image's depth |
| 274 |
(the |baseline| key of \tikzname). Furthermore, anything which would have |
| 275 |
been written to an |.aux| file will be redirected to the |.dpth| file -- |
| 276 |
but only things which occur inside of the externalized |tikzpicture| |
| 277 |
environment. When the main document loads the image, it will copy the |
| 278 |
|.dpth| file into the main |.aux| file. Then, successive compilations of |
| 279 |
the main document contain the external |\label| information. In other |
| 280 |
words, a |\label| in an external graphics needs the following work flow: |
| 281 |
% |
| 282 |
\begin{enumerate} |
| 283 |
\item The external graphics needs to be generated together with its |
| 284 |
|.dpth| (usually automatically by \tikzname). |
| 285 |
\item The main document includes the external graphics and copies the |
| 286 |
|.dpth| content into its main |.aux| file. |
| 287 |
\item The main document needs to be translated once again to re-read |
| 288 |
its |.aux| file\footnote{Note that it is not possible to activate |
| 289 |
the content of an auxiliary file after \texttt{\textbackslash |
| 290 |
begin\{document\}} in \LaTeX.}. |
| 291 |
\end{enumerate} |
| 292 |
|
| 293 |
This does also work if a |\label|/|\ref| combination is implemented itself |
| 294 |
by a |tikzpicture| (a feature offered by |pgfplots|). |
| 295 |
\end{key} |
| 296 |
|
| 297 |
|
| 298 |
\subsubsection{Customizing the Generated File Names} |
| 299 |
|
| 300 |
The default filename for externalized graphics is `\meta{real file |
| 301 |
name}|-figure_|\meta{number}' where \meta{number} ranges from $0$ to whatever |
| 302 |
is required. However, there are a couple of ways to change the generated |
| 303 |
filenames: |
| 304 |
% |
| 305 |
\begin{itemize} |
| 306 |
\item Changing the overall file name using a |prefix|, |
| 307 |
\item Changing the file name for a single figure using |
| 308 |
|\tikzsetnextfilename|, |
| 309 |
\item Changing the file name for a restricted set of figures using |
| 310 |
|figure name|. |
| 311 |
\end{itemize} |
| 312 |
|
| 313 |
\begin{key}{/tikz/external/prefix=\marg{file name prefix} (initially empty)} |
| 314 |
A shortcut for |\tikzsetexternalprefix|\marg{file name prefix}, see below. |
| 315 |
\end{key} |
| 316 |
|
| 317 |
\begin{command}{\tikzsetexternalprefix\marg{file name prefix}} |
| 318 |
Assigns a common prefix used by all file names. For example, |
| 319 |
% |
| 320 |
\begin{codeexample}[code only] |
| 321 |
\tikzsetexternalprefix{figures/} |
| 322 |
\end{codeexample} |
| 323 |
% |
| 324 |
will prepend |figures/| to every external graphics file name. |
| 325 |
|
| 326 |
Please note that |\tikzsetexternalprefix| is the \emph{only} way to assign |
| 327 |
a prefix in case you want to prepare your document for environments where |
| 328 |
\pgfname\ is not installed (see section~\ref{section-libs-external-nopgf}). |
| 329 |
\end{command} |
| 330 |
|
| 331 |
\begin{command}{\tikzsetnextfilename\marg{file name}} |
| 332 |
Sets the file name for the \emph{next} \tikzname\ picture or |\tikz| short |
| 333 |
command. It will \emph{only} be used for the next picture. |
| 334 |
|
| 335 |
Pictures for which no explicit file name has been set (or the next file |
| 336 |
name is empty) will get automatically generated file names. |
| 337 |
|
| 338 |
Please note that |prefix| will still be prepended to \marg{file name}. |
| 339 |
% |
| 340 |
\begin{codeexample}[code only] |
| 341 |
\documentclass{article} |
| 342 |
% main document, called main.tex |
| 343 |
\usepackage{tikz} |
| 344 |
|
| 345 |
\usetikzlibrary{external} |
| 346 |
\tikzexternalize[prefix=figures/] % activate |
| 347 |
|
| 348 |
\begin{document} |
| 349 |
|
| 350 |
\tikzsetnextfilename{trees} |
| 351 |
\begin{tikzpicture} % will be written to 'figures/trees.pdf' |
| 352 |
\node {root} |
| 353 |
child {node {left}} |
| 354 |
child {node {right} |
| 355 |
child {node {child}} |
| 356 |
child {node {child}} |
| 357 |
}; |
| 358 |
\end{tikzpicture} |
| 359 |
|
| 360 |
\tikzsetnextfilename{simple} |
| 361 |
A simple image is \tikz \fill (0,0) circle(5pt);. % will be written to 'figures/simple.pdf' |
| 362 |
|
| 363 |
\begin{tikzpicture} % will be written to 'figures/main-figure0.pdf' |
| 364 |
\draw[help lines] (0,0) grid (5,5); |
| 365 |
\end{tikzpicture} |
| 366 |
\end{document} |
| 367 |
\end{codeexample} |
| 368 |
% |
| 369 |
\begin{codeexample}[code only, tikz syntax=false] |
| 370 |
pdflatex -shell-escape main |
| 371 |
\end{codeexample} |
| 372 |
% |
| 373 |
\end{command} |
| 374 |
|
| 375 |
\begin{key}{/tikz/external/figure name=\marg{name}} |
| 376 |
Same as |\tikzsetfigurename|\marg{name}. |
| 377 |
\end{key} |
| 378 |
|
| 379 |
\begin{command}{\tikzsetfigurename\marg{name}} |
| 380 |
Changes the names of \emph{all} following figures. It is possible to change |
| 381 |
|figure name| during the document either using |
| 382 |
|\tikzset{external/figure name|=\marg{name}|}| or with this command. A |
| 383 |
unique counter will be used for each different \marg{name}, and each |
| 384 |
counter will start at $0$. |
| 385 |
|
| 386 |
The value of |prefix| will be applied after |figure name| has been |
| 387 |
evaluated. |
| 388 |
% |
| 389 |
\begin{codeexample}[code only] |
| 390 |
\documentclass{article} |
| 391 |
% main document, called main.tex |
| 392 |
\usepackage{tikz} |
| 393 |
|
| 394 |
\usetikzlibrary{external} |
| 395 |
\tikzexternalize % activate |
| 396 |
|
| 397 |
\begin{document} |
| 398 |
|
| 399 |
\begin{tikzpicture} % will be written to 'main-figure0.pdf' |
| 400 |
\node {root} |
| 401 |
child {node {left}} |
| 402 |
child {node {right} |
| 403 |
child {node {child}} |
| 404 |
child {node {child}} |
| 405 |
}; |
| 406 |
\end{tikzpicture} |
| 407 |
|
| 408 |
{ |
| 409 |
\tikzsetfigurename{subset_} |
| 410 |
A simple image is \tikz \fill (0,0) circle(5pt);. % will be written to 'subset_0.pdf' |
| 411 |
|
| 412 |
\begin{tikzpicture} % will be written to 'subset_1.pdf' |
| 413 |
\draw[help lines] (0,0) grid (5,5); |
| 414 |
\end{tikzpicture} |
| 415 |
}% here, the old file name will be restored: |
| 416 |
|
| 417 |
\begin{tikzpicture} % will be written to 'main-figure1.pdf' |
| 418 |
\draw (0,0) -- (5,5); |
| 419 |
\end{tikzpicture} |
| 420 |
\end{document} |
| 421 |
\end{codeexample} |
| 422 |
% |
| 423 |
The scope of |figure name| ends with the next closing brace. |
| 424 |
|
| 425 |
Remark: Use |\tikzset{external/figure name/.add={prefix_}{_suffix_}}| to |
| 426 |
add a |prefix_| and a |_suffix_| to the actual value of |figure name|. |
| 427 |
\end{command} |
| 428 |
|
| 429 |
\begin{command}{\tikzappendtofigurename\marg{suffix}} |
| 430 |
Appends \meta{suffix} to the actual value of |figure name|. |
| 431 |
|
| 432 |
It is a shortcut for |\tikzset{external/figure name/.add={}|\marg{suffix}|}| |
| 433 |
(a shortcut which is also supported if \tikzname\ is not installed, see |
| 434 |
below). |
| 435 |
\end{command} |
| 436 |
|
| 437 |
|
| 438 |
\subsubsection{Remaking Figures or Skipping Figures} |
| 439 |
|
| 440 |
\begin{command}{\tikzpicturedependsonfile\marg{file name}} |
| 441 |
Adds a dependency for the \emph{next} picture which is about to be |
| 442 |
externalized. If the command is invoked within a picture environment, it |
| 443 |
adds a dependency for the surrounding picture. Dependencies are written |
| 444 |
into \meta{target file}|.dep| in the format |
| 445 |
|
| 446 |
\meta{target file}|.\tikzexternalimgextension: |\meta{file name}. |
| 447 |
|
| 448 |
The effect is that if \meta{file name} changes, the external graphics |
| 449 |
associated with the picture shall be remade. |
| 450 |
|
| 451 |
This command uses the contents of |
| 452 |
\declareandlabel{\tikzexternalimgextension} to check for graphics. If you |
| 453 |
encounter difficulties with image extensions, consider redefining this |
| 454 |
macro (after |\tikzexternalize|). |
| 455 |
|
| 456 |
\paragraph{Limitations:} |
| 457 |
this command is currently only supported for |mode=list and make| and the |
| 458 |
generated |makefile|. |
| 459 |
\end{command} |
| 460 |
|
| 461 |
\begin{command}{\tikzexternalfiledependsonfile\marg{external graphics}\marg{file name}} |
| 462 |
A variant of |\tikzpicturedependsonfile| which adds a dependency for an |
| 463 |
\meta{external graphics}. The argument \meta{external graphics} must be the |
| 464 |
path as it would have been generated by the |external| library, i.e.\ without |
| 465 |
file extension but including any prefixes. |
| 466 |
\end{command} |
| 467 |
|
| 468 |
\begin{key}{/tikz/external/disable dependency files} |
| 469 |
Allows to (irreversibly) disable the generation of file dependencies. |
| 470 |
Disabling it will safe one |\newwrite| command, i.e.\ a write register. |
| 471 |
Note that the write register is only allocated if the feature has been used |
| 472 |
at all. This key needs to be provided as argument to |\tikzexternalize| (or |
| 473 |
it needs to be set before calling |\tikzexternalize|). |
| 474 |
|
| 475 |
Also see the |aux in dpth| key. |
| 476 |
\end{key} |
| 477 |
|
| 478 |
\begin{key}{/tikz/external/force remake=\marg{boolean} (default true)} |
| 479 |
A boolean which is used to customize the up-to-date checks of all following |
| 480 |
figures. Every up-to-date check will fail, resulting in automatic |
| 481 |
regeneration of every following figure. |
| 482 |
% |
| 483 |
\begin{codeexample}[code only] |
| 484 |
\tikzset{external/force remake} |
| 485 |
\begin{tikzpicture} |
| 486 |
\draw (0,0) circle(5pt); |
| 487 |
\end{tikzpicture} |
| 488 |
\end{codeexample} |
| 489 |
% |
| 490 |
You can also use |force remake| inside of a local \TeX\ group to remake |
| 491 |
only selected pictures. The example |
| 492 |
% |
| 493 |
\begin{codeexample}[code only] |
| 494 |
\tikz \draw (0,0) -- (1,1); |
| 495 |
|
| 496 |
{ |
| 497 |
\tikzset{external/force remake} |
| 498 |
\begin{tikzpicture} |
| 499 |
\draw (0,0) circle(5pt); |
| 500 |
\end{tikzpicture} |
| 501 |
} |
| 502 |
|
| 503 |
\tikz \draw (0,0) -- (1,1); |
| 504 |
\end{codeexample} |
| 505 |
will only apply |force remake| to the second figure. |
| 506 |
|
| 507 |
Up-to-date checks are applied for |mode=convert with system call| and the |
| 508 |
makefile generated by |mode=list and make|. |
| 509 |
\end{key} |
| 510 |
|
| 511 |
\begin{key}{/tikz/external/remake next=\marg{boolean} (default true)} |
| 512 |
A variant of |force remake| which applies only to the next image. |
| 513 |
\end{key} |
| 514 |
|
| 515 |
\begin{key}{/tikz/external/export next=\marg{boolean} (default true)} |
| 516 |
A boolean which can be used to disable the export mechanism for single pictures. |
| 517 |
\end{key} |
| 518 |
|
| 519 |
\begin{key}{/tikz/external/export=\marg{boolean} (initially true)} |
| 520 |
A boolean which can be used to disable the export mechanism for all |
| 521 |
pictures inside of the current \TeX-scope. |
| 522 |
% |
| 523 |
\begin{codeexample}[code only] |
| 524 |
\begin{document} |
| 525 |
\begin{tikzpicture} % will be exported |
| 526 |
... |
| 527 |
\end{tikzpicture} |
| 528 |
|
| 529 |
{ |
| 530 |
\tikzset{external/export=false} |
| 531 |
\begin{tikzpicture} % won't be exported |
| 532 |
... |
| 533 |
\end{tikzpicture} |
| 534 |
... |
| 535 |
} |
| 536 |
|
| 537 |
\begin{tikzpicture} % will be exported |
| 538 |
... |
| 539 |
\end{tikzpicture} |
| 540 |
\end{document} |
| 541 |
\end{codeexample} |
| 542 |
% |
| 543 |
For \LaTeX, the feature lasts until the next |\end|\marg{$\cdot$} (this |
| 544 |
holds for every call to |\tikzset|). |
| 545 |
\end{key} |
| 546 |
|
| 547 |
\begin{key}{/tikz/external/up to date check=\marg{choice} (initially md5)} |
| 548 |
The |external| lib has to decide when some existing figure is up-to-date. |
| 549 |
In such a case, it can be used without remaking it. Outdated pictures will |
| 550 |
be remade. |
| 551 |
|
| 552 |
The key |up to date check| allows to choose among a couple of heuristics |
| 553 |
which are supposed to catch the most important reasons to remake a figure. |
| 554 |
|
| 555 |
The |up to date check| can be overrule by any of the |force remake| or |
| 556 |
|remake next| keys: if one of them is true, the figure is not up-to-date. |
| 557 |
|
| 558 |
The choice \declare{simple} is based on the existence of the file: the file |
| 559 |
is up-to-date if and only if it exists. |
| 560 |
|
| 561 |
The choice \declare{md5} generates an MD5 checksum of the picture for which |
| 562 |
the up-to-date check is running. The MD5 is compared against the MD5 of the |
| 563 |
previous run, which, in turn, will be written into an extra file with the |
| 564 |
extension |.md5|. This file will be modified if and only if the MD5 |
| 565 |
comparison indicates a difference. The MD5 computation is based on the |
| 566 |
pdf\TeX\ method |\pdfmdfivesum|. If it is unavailable for some reason, the |
| 567 |
choice |diff| will be used instead. |
| 568 |
|
| 569 |
The choice \declare{diff} is the same as MD5 -- except that it compares the |
| 570 |
picture content as-is instead of a hash. The |.md5| file will be used to |
| 571 |
compare an old version with the current one -- but its content is some |
| 572 |
``normalized'' version of the picture for internal use. |
| 573 |
|
| 574 |
\paragraph{Attention:} |
| 575 |
the content--based strategies |md5| and |diff| operate on the picture |
| 576 |
content -- and only on the picture content. Here, ``picture content'' only |
| 577 |
includes the top--level tokens; no expansion is applied and no included |
| 578 |
files are part of the strategies. If you change preamble styles, you have |
| 579 |
to rebuild the figures manually (for example by deleting the generated |
| 580 |
graphics files). If you have include files, consider using |
| 581 |
|\tikzpicturedependsonfile| and its variants. Since this key provides |
| 582 |
heuristics, you should always remake your figures before you finally |
| 583 |
publish your document. Example: Suppose we have the following picture which |
| 584 |
depends on a command |\mycommand|: |
| 585 |
% |
| 586 |
\begin{codeexample}[code only] |
| 587 |
\def\mycommand{My comment} |
| 588 |
|
| 589 |
\begin{tikzpicture} |
| 590 |
|
| 591 |
\node at (0,0) {\mycommand}; |
| 592 |
|
| 593 |
\end{tikzpicture} |
| 594 |
\end{codeexample} |
| 595 |
% |
| 596 |
What happens if you change ``My comment'' to ``My super comment''? Well, |
| 597 |
|external| will \emph{not} pick it up; you will need to handle this |
| 598 |
manually. However, if you modify anything between |\begin{tikzpicture}| and |
| 599 |
|\end{tikzpicture}|, the |external| library \emph{will} pick it up and |
| 600 |
regenerate the picture. |
| 601 |
|
| 602 |
The |up to date check| is applied for |mode=convert with system call| and |
| 603 |
|mode=list and make|. |
| 604 |
\end{key} |
| 605 |
|
| 606 |
\begin{command}{\tikzexternaldisable} |
| 607 |
Allows to disable the complete externalization. While |export next| will |
| 608 |
still collect the contents of picture environments, this command uninstalls |
| 609 |
the hooks for the |external| library completely. Thus, nested picture |
| 610 |
environments or environments where |\end{tikzpicture}| is not directly |
| 611 |
reachable won't produce compilation failures -- although it is not possible |
| 612 |
to externalize them automatically. |
| 613 |
|
| 614 |
The externalization remains disabled until the end of the next \TeX\ group |
| 615 |
(or environment) or until the next call to |\tikzexternalenable|. |
| 616 |
\end{command} |
| 617 |
|
| 618 |
\begin{command}{\tikzexternalenable} |
| 619 |
Re-enables a previously running externalization after |\tikzexternaldisable|. |
| 620 |
\end{command} |
| 621 |
|
| 622 |
|
| 623 |
\subsubsection{Customizing the Externalization} |
| 624 |
|
| 625 |
\begin{key}{/tikz/external/figure list=\marg{boolean} (initially true)} |
| 626 |
A boolean which configures whether a figure list shall be generated. A |
| 627 |
figure list is an output file named \marg{jobname}|.figlist| which is |
| 628 |
filled with file names of each figure, one per line. |
| 629 |
|
| 630 |
This file is not used by \TeX\ anymore, its purpose is to issue the |
| 631 |
required conversion commands |pdflatex -jobname |\marg{picture file name} |
| 632 |
\marg{main file} manually (or in a script). See |
| 633 |
section~\ref{sec:external:detail} for the details about the expected system |
| 634 |
call (or activate |mode=convert with system call| and inspect your log |
| 635 |
file). |
| 636 |
% |
| 637 |
\begin{codeexample}[code only] |
| 638 |
\documentclass{article} |
| 639 |
% main document, called main.tex |
| 640 |
\usepackage{tikz} |
| 641 |
|
| 642 |
\usetikzlibrary{external} |
| 643 |
\tikzexternalize[ |
| 644 |
mode=graphics if exists, |
| 645 |
figure list=true, |
| 646 |
prefix=figures/] |
| 647 |
|
| 648 |
\begin{document} |
| 649 |
|
| 650 |
\tikzsetnextfilename{trees} |
| 651 |
\begin{tikzpicture} |
| 652 |
\node {root} |
| 653 |
child {node {left}} |
| 654 |
child {node {right} |
| 655 |
child {node {child}} |
| 656 |
child {node {child}} |
| 657 |
}; |
| 658 |
\end{tikzpicture} |
| 659 |
|
| 660 |
\tikzsetnextfilename{simple} |
| 661 |
A simple image is \tikz \fill (0,0) circle(5pt);. |
| 662 |
|
| 663 |
\begin{tikzpicture} |
| 664 |
\draw[help lines] (0,0) grid (5,5); |
| 665 |
\end{tikzpicture} |
| 666 |
\end{document} |
| 667 |
\end{codeexample} |
| 668 |
|
| 669 |
\begin{codeexample}[code only, tikz syntax=false] |
| 670 |
pdflatex main |
| 671 |
\end{codeexample} |
| 672 |
% |
| 673 |
generates |main.figlist| containing |
| 674 |
% |
| 675 |
\begin{codeexample}[code only, tikz syntax=false] |
| 676 |
figures/trees |
| 677 |
figures/simple |
| 678 |
figures/main-figure0 |
| 679 |
\end{codeexample} |
| 680 |
% |
| 681 |
\end{key} |
| 682 |
|
| 683 |
\begin{key}{/tikz/external/mode=\marg{choice} (initially convert with system call)} |
| 684 |
Configures what to do with \tikzname\ pictures (unless we are currently |
| 685 |
externalizing one particular image, in that case, these modes are ignored). |
| 686 |
|
| 687 |
The preconfigured mode |convert with system call| checks whether external |
| 688 |
graphics files are up-to-date and includes them if that is the case. Any |
| 689 |
picture which is not up-to-date will be generated automatically using a |
| 690 |
system call. The system call can be configured using the |system call| |
| 691 |
template. The up-to-date check is applied according to the |
| 692 |
|up to date check| key. As soon as |convert with system call| is set, the |
| 693 |
|figure list| will be disabled -- such a file is not required. In case you |
| 694 |
still need or want it, you can enable it after setting |mode|. |
| 695 |
|
| 696 |
Please note that system calls may be disabled for security reasons. For |
| 697 |
pdflatex, they can be enabled using |
| 698 |
% |
| 699 |
\begin{codeexample}[code only, tikz syntax=false] |
| 700 |
pdflatex -shell-escape |
| 701 |
\end{codeexample} |
| 702 |
% |
| 703 |
while other \TeX\ variants may need other switches. The feature is |
| 704 |
sometimes called |\write18|. |
| 705 |
|
| 706 |
The choice |only graphics| always tries to replace pictures with external |
| 707 |
graphics. It is an error if the graphics file does not exist. |
| 708 |
|
| 709 |
The choice |no graphics| (or, equivalently, |only pictures|) typesets |
| 710 |
\tikzname\ pictures without checking for external graphics. |
| 711 |
|
| 712 |
A mixture is |graphics if exists|, it checks whether a suitable graphics |
| 713 |
file exists and includes it if that is the case. If it does not exist, the |
| 714 |
picture is typeset using \TeX. |
| 715 |
|
| 716 |
Mode |list only| skips every \tikzname\ picture; it only generates the file |
| 717 |
\marg{main file}|.figlist| containing file names for every picture, the |
| 718 |
contents of any picture environment is thrown away and a replacement text |
| 719 |
is shown. This implies |figure list=true|. See also the |list and make| |
| 720 |
mode which includes available graphics. |
| 721 |
|
| 722 |
The mode |list and make| is similar to |list only|: it generates the same |
| 723 |
file \marg{main file}|.figlist|, but any images which exist already are |
| 724 |
included as graphics instead of ignoring them. Furthermore, this mode |
| 725 |
generates an additional file: \marg{main file}.makefile. This allows to use |
| 726 |
a work flow like |
| 727 |
% |
| 728 |
\begin{codeexample}[code only, tikz syntax=false] |
| 729 |
% step 1: generate main.makefile: |
| 730 |
pdflatex main |
| 731 |
% step 2: generate ALL graphics on 2 processors: |
| 732 |
make -j 2 -f main.makefile |
| 733 |
% step 3: include the graphics: |
| 734 |
pdflatex main |
| 735 |
\end{codeexample} |
| 736 |
% |
| 737 |
\noindent This last make method is optional: |list and make| just assumes |
| 738 |
that images are generated somehow (not necessarily with the generated |
| 739 |
makefile). The generated makefile allows parallel externalization of |
| 740 |
graphics on multi-core systems and it supports any file dependencies |
| 741 |
configured with |\tikzpicturedependsonfile|. Furthermore, it respects the |
| 742 |
|force remake| and |remake next| keys. |
| 743 |
\end{key} |
| 744 |
|
| 745 |
\begin{key}{/tikz/external/verbose IO=\marg{boolean} (initially true)} |
| 746 |
A boolean which configures whether I/O operations shall be listed in the |
| 747 |
logfile. |
| 748 |
\end{key} |
| 749 |
|
| 750 |
\begin{key}{/tikz/external/verbose optimize=\marg{boolean} (initially true)} |
| 751 |
A boolean which configures whether optimization operations shall be listed |
| 752 |
in the logfile. |
| 753 |
\end{key} |
| 754 |
|
| 755 |
\begin{key}{/tikz/external/verbose=\marg{boolean} (initially true)} |
| 756 |
Sets all verbosity flags to \meta{boolean}. |
| 757 |
\end{key} |
| 758 |
|
| 759 |
\begin{key}{/tikz/external/optimize=\marg{boolean} (initially true)} |
| 760 |
Configures whether the conversion process shall be optimized. This affects |
| 761 |
only the case when |\jobname| differs from the main file name, i.e.\ when |
| 762 |
single pictures are converted. |
| 763 |
|
| 764 |
In that case, the main file is compiled as usual -- but everything except |
| 765 |
the selected picture is thrown away. If optimization is enabled, all other |
| 766 |
pictures won't be processed at all. Furthermore, expensive commands which |
| 767 |
do not contribute to the selected picture will be thrown away as well. |
| 768 |
|
| 769 |
The default implementation discards |\includegraphics| commands which are |
| 770 |
\emph{not} inside of the selected picture to reduce conversion time. |
| 771 |
|
| 772 |
It is possible to add commands which shall be optimized away, see below. |
| 773 |
\end{key} |
| 774 |
|
| 775 |
\begin{key}{/tikz/external/optimize command away=\meta{\textbackslash command}\marg{required argument count}} |
| 776 |
Installs commands to optimize \meta{\textbackslash command} away. As is |
| 777 |
described above, optimization applies to the case when single pictures are |
| 778 |
converted: one usually doesn't need to process (probably expensive) |
| 779 |
commands which do not contribute to the selected picture. |
| 780 |
|
| 781 |
The argument \marg{required argument count} is either empty or a |
| 782 |
non-negative integer between $0$ and $9$. It denotes the number of |
| 783 |
arguments which should be consumed after \meta{\textbackslash command}. In |
| 784 |
any case, one argument in square brackets after the command will be |
| 785 |
recognized as well. To be more precise, the following cases for arguments |
| 786 |
of \meta{\textbackslash command} are supported: |
| 787 |
% |
| 788 |
\begin{enumerate} |
| 789 |
\item If \marg{required argument count} is empty (the default), |
| 790 |
\meta{\textbackslash command} may take one optional argument in |
| 791 |
square brackets and one in curly braces (which is also optional). |
| 792 |
\item If \marg{required argument count} is not empty, |
| 793 |
\marg{\textbackslash command} may take one optional argument in |
| 794 |
square brackets. Furthermore, it expects exactly \marg{required |
| 795 |
argument count} following arguments. |
| 796 |
\end{enumerate} |
| 797 |
|
| 798 |
Example: |
| 799 |
% |
| 800 |
\begin{codeexample}[code only] |
| 801 |
\tikzset{external/optimize command away=\includegraphics} |
| 802 |
\end{codeexample} |
| 803 |
|
| 804 |
\begin{codeexample}[code only] |
| 805 |
\newcommand{\myExpensiveMacro}[1]{Very expensive!} |
| 806 |
|
| 807 |
\tikzset{external/optimize command away=\myExpensiveMacro} |
| 808 |
\end{codeexample} |
| 809 |
|
| 810 |
\begin{codeexample}[code only] |
| 811 |
\newcommand{\myExpensiveMacroWithThreeArgs}[3]{Very expensive!} |
| 812 |
|
| 813 |
\tikzset{external/optimize command away={\myExpensiveMacroWithThreeArgs}{3}} |
| 814 |
\end{codeexample} |
| 815 |
|
| 816 |
\begin{codeexample}[code only] |
| 817 |
% A command with optional argument: |
| 818 |
\newcommand{\aFurtherExample}[3][]{Very expensive!} |
| 819 |
|
| 820 |
% consume only two arguments: the first optional one will be processed |
| 821 |
% anyway: |
| 822 |
\tikzset{external/optimize command away={\myExpensiveMacroWithThreeArgs}{2}} |
| 823 |
\end{codeexample} |
| 824 |
% |
| 825 |
The argument \meta{\textbackslash command} must be the name of a single |
| 826 |
macro. Any occurrence of this macro, together with its arguments, will be |
| 827 |
removed. |
| 828 |
% |
| 829 |
\begin{codeexample}[code only] |
| 830 |
\begin{tikzpicture} |
| 831 |
% this picture is currently converted! |
| 832 |
\end{tikzpicture} |
| 833 |
|
| 834 |
This here is outside of the converted picture and contains \myExpensiveMacro. It will be discarded. |
| 835 |
|
| 836 |
This call: \myExpensiveMacro[argument=value]{Argument} as well. |
| 837 |
And this here: \myExpensiveMacro{Argument} also. |
| 838 |
\end{codeexample} |
| 839 |
|
| 840 |
The default is to optimize |\includegraphics| away. |
| 841 |
|
| 842 |
This key is actually a style which sets the |optimize/install| and |
| 843 |
|optimize/restore| keys. |
| 844 |
\end{key} |
| 845 |
|
| 846 |
\begin{key}{/tikz/external/optimize/install} |
| 847 |
A command key which contains code to install optimizations. You can append |
| 848 |
code here (or clear the macro) if you need to modify the optimization. |
| 849 |
\end{key} |
| 850 |
|
| 851 |
\begin{key}{/tikz/external/optimize/restore} |
| 852 |
A command key which contains code to undo optimizations. You can append |
| 853 |
code here (or clear the macro) if you need to modify the optimization. |
| 854 |
\end{key} |
| 855 |
|
| 856 |
\begin{key}{/tikz/external/only named=\marg{boolean} (initially false)} |
| 857 |
If enabled, only pictures for which file names have been set explicitly |
| 858 |
using |\tikzsetnextfilename| will be considered, no file names will be |
| 859 |
generated automatically. |
| 860 |
\end{key} |
| 861 |
|
| 862 |
\begin{key}{/pgf/images/include external (initially \textbackslash pgfimage\{\#1\})} |
| 863 |
\index{External Graphics!Bounding Box Issues} |
| 864 |
This command key constitutes the public interface to exchange the |
| 865 |
|\includegraphics| command used for the image inclusion. If can be |
| 866 |
overwritten using |include external/.code=|\marg{\TeX\ code}. |
| 867 |
|
| 868 |
Its description can be found in the corresponding basic layer documentation |
| 869 |
on page~\pageref{pgf:includeexternalkey}. |
| 870 |
|
| 871 |
Just one example here: you can use |
| 872 |
% |
| 873 |
\begin{codeexample}[code only] |
| 874 |
\pgfkeys{/pgf/images/include external/.code={\includegraphics[viewport=0 0 211.28 175.686]{#1}}} |
| 875 |
\end{codeexample} |
| 876 |
% |
| 877 |
to manually change the viewport (bounding box) for included graphics. |
| 878 |
|
| 879 |
Another example (of probably limited use) is |
| 880 |
% |
| 881 |
\begin{codeexample}[code only] |
| 882 |
\pgfkeys{/pgf/images/include external/.code={\href{file:#1}{\pgfimage{#1}}}} |
| 883 |
\end{codeexample} |
| 884 |
% |
| 885 |
\noindent which will generate a clickable hyperlink around the image. |
| 886 |
Clicking on it opens the single exported file\footnote{This requires all |
| 887 |
external graphics files in the same base directory as the main |.pdf| |
| 888 |
file.}. |
| 889 |
|
| 890 |
If you want to limit the effects of this key to just one externalized |
| 891 |
figure, use |
| 892 |
% |
| 893 |
\begin{codeexample}[code only] |
| 894 |
{ |
| 895 |
\pgfkeys{/pgf/images/include external/.code={\includegraphics[viewport=0 0 211.28 175.686]{#1}}} |
| 896 |
\begin{tikzpicture} |
| 897 |
... |
| 898 |
\end{tikzpicture} |
| 899 |
}% this brace ends the effect of `include external' |
| 900 |
\end{codeexample} |
| 901 |
% |
| 902 |
\end{key} |
| 903 |
|
| 904 |
\begin{command}{\tikzifexternalizing\marg{true code}\marg{false code}} |
| 905 |
This command can be used to check whether an image is currently written to |
| 906 |
its separate graphics file (if the ``grab'' procedure is running). If so, |
| 907 |
the \marg{true code} will be executed. If not, that means if the main |
| 908 |
document is being typeset normally, the \marg{false code} will be invoked. |
| 909 |
|
| 910 |
This command must be used \emph{after} |\tikzexternalize|. |
| 911 |
\end{command} |
| 912 |
|
| 913 |
\begin{command}{\tikzifexternalizingnext\marg{true code}\marg{false code}} |
| 914 |
Like |\tikzifexternalizing|, but this variant also checks if the next |
| 915 |
following figure is the one which is about to be written to its separate |
| 916 |
graphics file. |
| 917 |
\end{command} |
| 918 |
|
| 919 |
|
| 920 |
\subsubsection{Details About The Process} |
| 921 |
\label{sec:external:detail} |
| 922 |
|
| 923 |
The standard run |pdflatex |\meta{main document} causes the |external| library |
| 924 |
to check every occurrence of |\begin{tikzpicture}| and every |\tikz| short |
| 925 |
command. If it finds a picture which shall be exported, it queries the |
| 926 |
respective file name and checks whether the file exists already. If so, it |
| 927 |
includes the external graphics. If not, it requires an externalization which |
| 928 |
can be done automatically (the default), semi-automatically (with |
| 929 |
|mode=list and make|) or manually (by issuing the requires system calls |
| 930 |
somehow). |
| 931 |
|
| 932 |
The library can detect whether it runs in ``conversion mode'', i.e.\ if it |
| 933 |
should only process a single image. To do so, it checks whether the internal |
| 934 |
macro \declareandlabel{\tikzexternalrealjob} exists. If so, its contents is |
| 935 |
assumed to be \meta{main document} (without the suffix |.tex|). Usually, this |
| 936 |
macro is set by the conversion system call, |
| 937 |
% |
| 938 |
\begin{codeexample}[code only, tikz syntax=false] |
| 939 |
pdflatex -jobname "main-figure0" "\def\tikzexternalrealjob{main}\input{main}" |
| 940 |
\end{codeexample} |
| 941 |
% |
| 942 |
\noindent where |main-figure0| is the picture we are currently externalizing |
| 943 |
and |main.tex| is the main document. |
| 944 |
|
| 945 |
As soon as ``conversion mode'' has been detected, \pgfname\ changes the output |
| 946 |
routine. The complete file |main.tex| is processed as normal, but only the part |
| 947 |
of the desired picture will be written to the output file, in our case |
| 948 |
|main-figure0.pdf|. The rest of the document is silently thrown away. Of |
| 949 |
course, such a conversion process is quite expensive since we need to do it for |
| 950 |
every picture. Since everything except the current picture is thrown away, the |
| 951 |
library skips all other pictures. Furthermore, any |\includegraphics| commands |
| 952 |
which are outside of the converted \tikzname-picture will be skipped as well. |
| 953 |
Thus, the conversion process should be much faster than typesetting the |
| 954 |
complete document, but it still requires its time. Eventually, the call |
| 955 |
|\input{main}| returns and the picture is ready. From this point on, the |
| 956 |
external graphics will be used. |
| 957 |
|
| 958 |
There is another possibility to communicate \meta{main document} to the |
| 959 |
subprocess performing the externalization: namely to write |
| 960 |
`|\tikzexternalize{main}|' into the document. In this case, the conversion |
| 961 |
system call will be |
| 962 |
% |
| 963 |
\begin{codeexample}[code only, tikz syntax=false] |
| 964 |
pdflatex -jobname "main-figure0" "main" |
| 965 |
\end{codeexample} |
| 966 |
% |
| 967 |
\noindent and the contents of |\tikzexternalrealjob| is set automatically. This |
| 968 |
case is detected by |\tikzexternalize|, and the |system call| is updated |
| 969 |
automatically (by patching its |\texsource| template argument). It is not |
| 970 |
necessary to change the |system call| manually. |
| 971 |
|
| 972 |
The sequence in which system calls are performed and the decision whether they |
| 973 |
are issued automatically is governed by the |mode| key, consult its |
| 974 |
documentation for details. |
| 975 |
|
| 976 |
|
| 977 |
\subsection{Using External Graphics Without \textmd{\pgfname}\ Installed} |
| 978 |
\label{section-libs-external-nopgf} |
| 979 |
|
| 980 |
Given that every picture has been exported correctly, one may want to compile a |
| 981 |
file without \pgfname\ and \tikzname\ installed. \tikzname\ comes with a |
| 982 |
minimal package which contains just enough commands to replace every |
| 983 |
|tikzpicture| environment and the |\tikz| short command with the appropriate |
| 984 |
external graphics. It can be found at |
| 985 |
% |
| 986 |
\begin{codeexample}[code only, tikz syntax=false] |
| 987 |
latex/pgf/utilities/tikzexternal.sty |
| 988 |
\end{codeexample} |
| 989 |
% |
| 990 |
\noindent and needs to be used instead of |\usepackage{tikz}|. So, we comment |
| 991 |
|\usepackage{tikz}| and |\usetikzlibrary{external}|, load packages |graphicx| |
| 992 |
and |tikzexternal|, and finally our example from the beginning becomes |
| 993 |
% |
| 994 |
\begin{codeexample}[code only] |
| 995 |
\documentclass{article} |
| 996 |
% main document, called main.tex |
| 997 |
%\usepackage{tikz} |
| 998 |
|
| 999 |
\usepackage{graphicx} |
| 1000 |
\usepackage{tikzexternal} |
| 1001 |
|
| 1002 |
%\usetikzlibrary{external} |
| 1003 |
\tikzexternalize |
| 1004 |
|
| 1005 |
\begin{document} |
| 1006 |
\begin{tikzpicture} |
| 1007 |
\node {root} |
| 1008 |
child {node {left}} |
| 1009 |
child {node {right} |
| 1010 |
child {node {child}} |
| 1011 |
child {node {child}} |
| 1012 |
}; |
| 1013 |
\end{tikzpicture} |
| 1014 |
|
| 1015 |
A simple image is \tikz \fill (0,0) circle(5pt);. |
| 1016 |
|
| 1017 |
Furthermore, we might want to draw \tikz[baseline]\draw (0,-1) rectangle (1,1); |
| 1018 |
\end{document} |
| 1019 |
\end{codeexample} |
| 1020 |
% |
| 1021 |
\noindent where the following files are necessary to compile the document: |
| 1022 |
% |
| 1023 |
\begin{codeexample}[code only, tikz syntax=false] |
| 1024 |
tikzexternal.sty |
| 1025 |
main.tex |
| 1026 |
main-figure0.pdf |
| 1027 |
main-figure1.pdf |
| 1028 |
main-figure2.pdf |
| 1029 |
\end{codeexample} |
| 1030 |
% |
| 1031 |
\noindent If there are any `|.dpth|' files, for example |main-figure2.dpth|, |
| 1032 |
these files are also required. They contain information for the \tikzname\ |
| 1033 |
|baseline| option (or |\label|s inside external graphics). |
| 1034 |
|
| 1035 |
Just copy the |.sty| file into the directory of your |main.tex| file and use it |
| 1036 |
as part of your document. |
| 1037 |
|
| 1038 |
Please keep in mind, that only |tikzpicture| environments and |\tikz| short |
| 1039 |
images are available within the externalization framework. Additionally, calls |
| 1040 |
to |\tikzset| and |\pgfkeys| won't lead to compilation errors because they are |
| 1041 |
simply ignored. But since |pgfkeys| is not available, any option supplied to |
| 1042 |
|\tikzexternalize| is \emph{ignored}. |
| 1043 |
|
| 1044 |
\paragraph{Attention:} |
| 1045 |
Since the simple replacement |\usepackage{tikzexternal}| doesn't support the |
| 1046 |
key--value interface, you \emph{need} to use |\tikzsetexternalprefix| instead |
| 1047 |
of the |prefix| option and |\tikzsetfigurename| instead of the |figure name| |
| 1048 |
option since |\tikzset| is not available in such a context. |
| 1049 |
|
| 1050 |
\paragraph{Remark:} |
| 1051 |
Some of the features of this library are mainly useful to improve the speed of |
| 1052 |
successive document compilations. In other words: you can't use all features in |
| 1053 |
this context, keep it simple. |
| 1054 |
|
| 1055 |
|
| 1056 |
\subsection{\texttt{eps} Graphics Export} |
| 1057 |
|
| 1058 |
It is also possible to use \eps\ graphics instead of \pdf\ files. There are |
| 1059 |
different ways to produce them, for example to use |pdflatex| and call |
| 1060 |
|pdftops -eps |\marg{pdf file} \marg{eps file} afterwards. You could add this |
| 1061 |
command to the |system call| option. |
| 1062 |
|
| 1063 |
Alternatively, you can use |latex| and |dvips| for image conversion as is |
| 1064 |
explained for the |system call| option, see |
| 1065 |
page~\pageref{extlib:systemcall:option}. See the documentation for the basic |
| 1066 |
level externalization in section~\ref{section-external} for restrictions of |
| 1067 |
other drivers. |
| 1068 |
|
| 1069 |
|
| 1070 |
\subsection{Bitmap Graphics Export} |
| 1071 |
|
| 1072 |
Occasionally, you may have an extremely large graphics which takes long times |
| 1073 |
to render. It might be interesting to generate a bitmap (raster) image, which |
| 1074 |
displays much faster (for example in a presentation). I have used this feature |
| 1075 |
to speed-up the display of large shadings. |
| 1076 |
|
| 1077 |
The |external| library can be customized to export bitmap images -- with the |
| 1078 |
help of external programs. Due to the dependence of external programs, you may |
| 1079 |
need to adjust these commands manually. For example, on my computer, the |
| 1080 |
ImageMagick Suite is installed which comes with the |convert| tool. Together |
| 1081 |
with |pdflatex|, I can define the following style: |
| 1082 |
% |
| 1083 |
\begin{codeexample}[code only] |
| 1084 |
\tikzset{ |
| 1085 |
% Defines a custom style which generates BOTH, .pdf and .png export |
| 1086 |
% but prefers the .png on inclusion. |
| 1087 |
% |
| 1088 |
% This style is not pre-defined, you may need to copy-paste and |
| 1089 |
% adjust it. |
| 1090 |
png export/.style={ |
| 1091 |
external/system call/.append= |
| 1092 |
{; convert -density 300 -transparent white "\image.pdf" "\image.png"}, |
| 1093 |
% |
| 1094 |
/pgf/images/external info, |
| 1095 |
/pgf/images/include external/.code={% |
| 1096 |
\includegraphics |
| 1097 |
[width=\pgfexternalwidth,height=\pgfexternalheight] |
| 1098 |
{##1.png}% |
| 1099 |
}, |
| 1100 |
} |
| 1101 |
} |
| 1102 |
\end{codeexample} |
| 1103 |
% |
| 1104 |
\noindent The example above defines a new style called `|png export|' which, |
| 1105 |
when it is set with |\tikzset{png export}| somewhere in the document, modifies |
| 1106 |
the configuration for both file generation and file input. The file generation |
| 1107 |
is modified by appending the ImageMagick command to |system call| (separated by |
| 1108 |
`|;|' as usual on Linux). This is, in principle, enough to generate a |.png| |
| 1109 |
file. The |include external| command is overwritten such that it uses the |
| 1110 |
|.png| file instead of the |.pdf| file (which exists as well in the |
| 1111 |
configuration above). But since a |.png| file can have a much higher resolution |
| 1112 |
than the desired image dimensions, we have to add |width| and |height| |
| 1113 |
explicitly. Usually, the |external| library does not provide size information |
| 1114 |
(it is unnecessary for |.pdf| or |.eps| since these formats have their bounding |
| 1115 |
box information). To enable size information, the style uses the |
| 1116 |
|external info| key, which, in turn, provides the |\pgfexternalwidth| and |
| 1117 |
|\pgfexternalheight| commands. |
| 1118 |
|
| 1119 |
Now we can use |\tikzset{png export}| either document-wide or just for one |
| 1120 |
particular image. The configuration remains in effect until the end of the |
| 1121 |
current environment (or until the next closing curly brace `|}|'). |
| 1122 |
|
| 1123 |
\begin{key}{/pgf/images/external info=\marg{boolean} (initially false)} |
| 1124 |
If this key is activated, the size for any externalized image will be |
| 1125 |
stored explicitly into the associated |.dpth| file. |
| 1126 |
|
| 1127 |
When the file is included by |\pgfincludeexternalgraphics| (or |
| 1128 |
automatically by the |external| library), the width is available as |
| 1129 |
\declareandlabel{\pgfexternalwidth} and the height as |
| 1130 |
\declareandlabel{\pgfexternalheight}. |
| 1131 |
\end{key} |
| 1132 |
|
| 1133 |
|
| 1134 |
\subsection{Compatibility Issues} |
| 1135 |
|
| 1136 |
\subsubsection{References In External Pictures} |
| 1137 |
|
| 1138 |
It is allowed if a picture contains references, for example |
| 1139 |
|\tikz \node {Reference to \ref{a:label}};|. |
| 1140 |
|
| 1141 |
There is just one issue: if the main job is currently compiling, its |.aux| |
| 1142 |
file is not in its final state (even worse: it may not be readable at all). The |
| 1143 |
picture externalization, however, needs the main |.aux| file to query any |
| 1144 |
references. |
| 1145 |
|
| 1146 |
Thus, you \emph{will} need to invoke |
| 1147 |
|pdflatex -jobname |\meta{image}| |\meta{mainfile} \emph{manually} |
| 1148 |
for any image which contains references. |
| 1149 |
|
| 1150 |
This problem arises only for |mode=convert with system call|. In this case, |
| 1151 |
the |external| library creates a special |\jobname.auxlock| file to check |
| 1152 |
whether the main |.aux| file is currently usable. |
| 1153 |
|
| 1154 |
|
| 1155 |
\subsubsection{Compatibility With Other Libraries or Packages} |
| 1156 |
|
| 1157 |
The |external| library has the following compatibility issues: |
| 1158 |
% |
| 1159 |
\begin{enumerate} |
| 1160 |
\item The |external| library comes with special support for |
| 1161 |
|\usetikzlibrary{fadings}|: the |fadings| library may define local |
| 1162 |
pictures which would be externalized (although they shouldn't). There |
| 1163 |
is special handling to suppress this bug if |\tikzexternalize| is |
| 1164 |
called \emph{after} |\usetikzlibrary{fadings}| or if all fadings are |
| 1165 |
defined \emph{before} |\tikzexternalize|. |
| 1166 |
\item Problems have been reported when using |\tikzexternalize| (or the |
| 1167 |
basic layer externalization) together with |\usepackage{glossary}|. |
| 1168 |
This problem disappears if |\tikzexternalize| is called \emph{before} |
| 1169 |
|\usepackage{glossary}|. |
| 1170 |
\item Problems with |\usepackage{pdfpages}| and |\usepackage{vmargin}|: The |
| 1171 |
|external| library replaces the current shipout routine of \TeX\ during |
| 1172 |
its externalization. This might raise problems with other packages |
| 1173 |
which also manipulate the shipout routine (like the mentioned ones). To |
| 1174 |
fix those problems, use |
| 1175 |
% |
| 1176 |
\begin{codeexample}[code only] |
| 1177 |
|
| 1178 |
\usetikzlibrary{external} |
| 1179 |
|
| 1180 |
\tikzifexternalizing{% |
| 1181 |
% don't include package XYZ here |
| 1182 |
}{% |
| 1183 |
\usepackage{pdfpages} |
| 1184 |
\usepackage{vmargin} |
| 1185 |
... |
| 1186 |
}% |
| 1187 |
\end{codeexample} |
| 1188 |
% |
| 1189 |
This uses the requested packages for the main document, but not for the |
| 1190 |
single, exported graphics. |
| 1191 |
\end{enumerate} |
| 1192 |
|
| 1193 |
In general, the |\tikzifexternalizing| feature might be used to solve package |
| 1194 |
conflicts and the |\tikzexternaldisable| and |\tikzexternalenable| features can |
| 1195 |
be used to solve problems with single pictures. |
| 1196 |
|
| 1197 |
|
| 1198 |
\subsubsection{Compatibility With Bounding Box Restrictions} |
| 1199 |
|
| 1200 |
Bounding box restrictions provide no problem when used with \eps\ graphics. |
| 1201 |
However, they pose problems for |pdflatex|, so you may need to use the |
| 1202 |
|latex|/|dvips| combination if you use bounding box restrictions and |
| 1203 |
externalization. Currently, the only possibility for bounding box restrictions |
| 1204 |
and |pdflatex| is to use a combination of |trim left|/|trim right|/|baseline|: |
| 1205 |
these keys do not \emph{really} truncate the bounding box, they only store |
| 1206 |
horizontal and vertical shifts (also see the |trim lowlevel| key in this |
| 1207 |
context). |
| 1208 |
|
| 1209 |
|
| 1210 |
\subsubsection{Interoperability With The Basic Layer Externalization} |
| 1211 |
|
| 1212 |
This library is fully compatible with |
| 1213 |
|\beginpgfgraphicnamed|$\dotsc$|\endpgfgraphicnamed| environments. However, you |
| 1214 |
will need to use the |export next=false| key to avoid conflicts: |
| 1215 |
% |
| 1216 |
\begin{codeexample}[code only] |
| 1217 |
\beginpgfgraphicnamed{picture4} |
| 1218 |
\tikzset{external/export next=false} |
| 1219 |
\begin{tikzpicture} |
| 1220 |
\draw (0,0) -- (4,4); |
| 1221 |
\end{tikzpicture} |
| 1222 |
\endpgfgraphicnamed |
| 1223 |
\end{codeexample} |
| 1224 |
% |
| 1225 |
Please keep in mind that file prefixes do not apply to the basic layer. |
| 1226 |
} |