Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-library-external.tex

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