summaryrefslogtreecommitdiff
path: root/graphics/pgf/base/doc/text-en/pgfmanual-en-library-external.tex
blob: ee3a890518145f2e58650048564846d29bb26267 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
% Copyright 2019 by Christian Feuersaenger
%
% This file may be distributed and/or modified
%
% 1. under the LaTeX Project Public License and/or
% 2. under the GNU Free Documentation License.
%
% See the file doc/generic/pgf/licenses/LICENSE for more details.


\section{Externalization Library}
\label{section-libs-external}

{
\pgfkeys{
    /pdflinks/search key prefixes in/.add={/tikz/external/,}{}
}
{\noindent {\emph{by Christian Feuersänger}}}

\begin{tikzlibrary}{external}
    This library provides a high-level automatic or semi-automatic export
    feature for \tikzname\ pictures. Its purpose is to convert each picture to
    a separate \pdf\ without changing the document as such.

    It also externalizes |\label|  information (and other aux file related
    stuff) using auxiliary files.
\end{tikzlibrary}


\subsection{Overview}

There are several reasons why external images for at least some pictures are of
interest:
%
\begin{enumerate}
    \item Larger picture require a considerable amount of time, which is
        necessary for every compilation. However, only few images will change
        from run to run. It can simply save time to export finished images and
        include them as final graphics.
    \item It may be desirable to have final images for some graphics, for
        example to include them in third--party programs or to communicate them
        electronically.
    \item It may be necessary to typeset a file in environments where \pgfname\
        and \tikzname\ are not available. In this case, external images are the
        only way to ensure compatibility.
\end{enumerate}
%
The purpose of this library is to provide a way to export any \tikzname-picture
to separate \pdf\ (or \eps) images without changing the main document. It is
actually a simple user interface to the |\beginpgfgraphicnamed| $\dotsc$
|\endpgfgraphicnamed| framework of \pgfname\ which is discussed in
section~\ref{section-external}.


\subsection{Requirements}

For most users, the library does not need special attention since requirements
are met anyway. It collects all tokens between |\begin{tikzpicture}| and the
next following |\end{tikzpicture}| and replaces them by the appropriate
graphics or it takes steps to generate such an image.
%For Con\TeX t and plain \TeX\ users, the appropriate begin and end picture
%statements apply.

It can't expand macros during this step, so the only requirement is that every
picture's end is directly reachable from its beginning, without further macro
expansion. Furthermore, the library assumes that all \LaTeX\ pictures are ended
with |\end{tikzpicture}|.
%In Con\TeX t, the end command is assumed to be |\stoptikzpicture| and for plain
%\TeX\ it is |\endtikzpicture|.

The library always searches for the \emph{next} picture's end,
|\end{tikzpicture}|. As a consequence, you can't use nested pictures directly.
You \emph{can} nest pictures, but you have to avoid that the nested picture's
|\end| command is found before the outer |\end| command (for example using
bracing constructs or by writing the nested picture into a separate macro
call).

Consider using the |\tikzexternaldisable| method in case you'd like to skip
selected pictures which do not meet the requirements.


\subsection{A Word About Con\TeX t And Plain \TeX}

Currently, the basic layer backend |\beginpgfgraphicnamed| $\dotsc$
|\endpgfgraphicnamed| relies on \LaTeX\ only, so externalization is currently
only supported for \LaTeX.
%The library comes in three different versions, one for \LaTeX, one for Con\TeX
%t and one for plain \TeX. For reasons of simplicity, examples in this manual
%only refer to \LaTeX\ (especially |pdflatex|).


\subsection{Externalizing Graphics}

After loading the library, a call to |\tikzexternalize| is necessary to
activate the externalization.
%
\begin{codeexample}[code only]
\documentclass{article}
% main document, called main.tex
\usepackage{tikz}

\usetikzlibrary{external}
\tikzexternalize % activate!

\begin{document}
\begin{tikzpicture}
  \node {root}
    child {node {left}}
    child {node {right}
      child {node {child}}
      child {node {child}}
    };
\end{tikzpicture}

A simple image is \tikz \fill (0,0) circle(5pt);.
\end{document}
\end{codeexample}

The method works as follows: if the document is typeset normally, the library
searches for replacement images for every picture. Filenames are generated
automatically in the default configuration. In our case, the two file names
will be |main-figure0| and |main-figure1|. If they exist, those images are
simply included and the pictures as such are not processed. If graphics files
do not exist, steps are taken to generate the missing ones. Since (currently)
only one output file can be set, each missing image needs to be generated by a
separate run of \LaTeX\ in which the |\jobname| is set to the desired image
file name. In the default configuration |mode=convert with system call|, these
commands are issued automatically by using the |\write18| method to call system
commands. It is also possible to output every required file name or to generate
a |makefile|; users will need to issue the required commands manually (or with
|make|). The probably most comfortable way is to use the default configuration
with
%
\begin{codeexample}[code only, tikz syntax=false]
pdflatex -shell-escape main
\end{codeexample}
%
\noindent which authorizes |pdflatex| to call itself recursively to generate
the images. When it finishes, all images are generated and the document already
includes them.

From this point on, successive runs of \LaTeX\ will use the final graphics
files, the pictures won't be used anymore.
Section~\ref{section-libs-external-nopgf} contains details about how to submit
such a file to environments where \pgfname\ is not available.

\begin{command}{\tikzexternalize\oarg{optional arguments}}
    This command activates the externalization. It installs commands to replace
    every \tikzname-picture. It needs to be called before |\begin{document}|
    because it may need to install its separate shipout routine.

    The \meta{optional arguments} can be any of the keys described below.

    Note that the generation/modification of auxiliary files like |.aux|,
    |.toc| etc.\ is usually suppressed while a single image is externalized
    (details for |\label| support follow).

    It is also possible to write |\tikzexternalize|\marg{main job name} if the
    argument is delimited by curly braces. This case is mainly for backwards
    compatibility and is no longer necessary. Since it might be useful in rare
    circumstances, it is documented in section~\ref{sec:external:detail}.

    A detailed description about the process of externalization is provided in
    section~\ref{sec:external:detail}.

    \begin{command}{\tikzexternalrealjob}
        After the library is loaded, this macro will \emph{always} contain the
        correct main job's name (in the example above, it is |main|). It is to
        be used instead of |\jobname| when the externalization is in effect.
    \end{command}
    %
    \begin{command}{\pgfactualjobname}
        Once |\tikzexternalize| has been called, |\pgfactualjobname| contains
        the name of the currently generated output file (which may be |main| or
        |main-figure0| or |main-figure1| in our example above).
    \end{command}
    %
    \begin{command}{\jobname}
        The value of |\jobname| is one of |\tikzexternalrealjob| or
        |\pgfactualjobname|, depending on the configuration. In short: if
        auxiliary file support (|\label| and |\ref|) is activated,
        |\jobname=\tikzexternalrealjob| (since that's the base file name of
        auxiliary files).
    \end{command}
\end{command}

\begin{key}{/tikz/external/system call=\marg{template}}
\label{extlib:systemcall:option}
    A template string used to generate system calls. Inside of \marg{template},
    the macro |\image| can be used as placeholder for the image which is about
    to be generated while |\texsource| contains the main file name (in truth,
    it contains |\input|\marg{main file name}, but that doesn't matter).

    The default depends on the value of |\pgfsysdriver|. For
    |pgfsys-pdftex.def|, it is
    %
\begin{codeexample}[code only]
\tikzset{external/system call={pdflatex \tikzexternalcheckshellescape -halt-on-error
    -interaction=batchmode -jobname "\image" "\texsource"}}
\end{codeexample}
    %
    \noindent where \declareandlabel{\tikzexternalcheckshellescape} inserts the
    value of the configuration key |shell escape| if and only if the current
    document has been typeset with |-shell-escape|\footnote{Note that this is
    always true for the default configuration. This security consideration
    applies mainly for \texttt{mode=list and make} which will also work
    \emph{without} shell escapes.}.

    Other drivers result in slightly different calls. There is support for
    |lualatex|, |xelatex|, and |dvips|. The precise values are written to the
    |.log| file as soon as you attempt to compile a document.

    The argument \marg{template} will be expanded using |\edef|, so any control
    sequences will be expanded. During this evaluation, `|\\|' will result in a
    normal backslash, `|\|'. Furthermore, double quotes `|"|', single quotes
    `|'|', semicolons and dashes `|-|' will be made to normal characters if any
    package uses them as macros. This ensures compatibility with the |german|
    package, for example.
\end{key}

\begin{key}{/tikz/external/shell escape=\marg{command-line arg} (initially -shell-escape)}
    Contains the command line option for |latex| which enables the |\write18|
    feature. For \TeX-Live, this is |-shell-escape|. For MiK\TeX, you should
    use |\tikzexternalize[shell escape=-enable-write18]|.
\end{key}


\subsubsection{Support for Labels and References In External Files}

The |external| library comes with extra support for |\label| and |\ref| (and
other commands which usually store information in the |.aux| file) inside an
external files.

In particular, it supports the two use-cases
%
\begin{enumerate}
    \item[a)] |\ref| to something in the main document inside an externalized
        graphics or
    \item[b)] |\label| in the externalized graphics which is referenced in the
        main document.
\end{enumerate}

The only restriction is that you need to compile your document multiple times
(as usual for references).

\paragraph{NOTE:}
support for a) is unavailable for versions up to and including \pgfname\ 3.0.1.

\begin{key}{/tikz/external/aux in dpth=\marg{boolean} (initially true)}
    Allows to enable or disable the feature which handles references and labels
    as part of image externalization. Disabling it will safe one |\newwrite|
    command, i.e.\ a write register.

    Also see the |disable dependency files| feature.

    Here are some implementation details on how references within/from external
    graphics work for those who would like to know the details:

    For point a), a |\ref| inside of an externalized graphics works by reading
    the main document's |.aux| file. To this end, the standard
    |mode=convert with system call| detects such references and reschedules the
    externalization to |\end{document}.|\footnote{Note that this requires the
    \texttt{atveryend} package. The purpose to reschedule the externalization
    is to access the main job's aux file, but only after it has been written
    completely.} Other values of |mode| require just one attempt to externalize
    the picture.

    Note that |\pageref| is not supported (sorry).

    Point b) works as follows: a |\label| inside of an externalized graphics
    causes the |external| library to generate separate auxiliary files for every
    external image. These files are called \meta{imagename}|.dpth|. The
    extension |.dpth| indicates that the file also contains the image's depth
    (the |baseline| key of \tikzname). Furthermore, anything which would have
    been written to an |.aux| file will be redirected to the |.dpth| file --
    but only things which occur inside of the externalized |tikzpicture|
    environment. When the main document loads the image, it will copy the
    |.dpth| file into the main |.aux| file. Then, successive compilations of
    the main document contain the external |\label| information. In other
    words, a |\label| in an external graphics needs the following work flow:
    %
    \begin{enumerate}
        \item The external graphics needs to be generated together with its
            |.dpth| (usually automatically by \tikzname).
        \item The main document includes the external graphics and copies the
            |.dpth| content into its main |.aux| file.
        \item The main document needs to be translated once again to re-read
            its |.aux| file\footnote{Note that it is not possible to activate
            the content of an auxiliary file after \texttt{\textbackslash
            begin\{document\}} in \LaTeX.}.
    \end{enumerate}

    This does also work if a |\label|/|\ref| combination is implemented itsself
    by a |tikzpicture| (a feature offered by |pgfplots|).
\end{key}


\subsubsection{Customizing the Generated File Names}

The default filename for externalized graphics is `\meta{real file
name}|-figure_|\meta{number}' where \meta{number} ranges from $0$ to whatever
is required. However, there are a couple of ways to change the generated
filenames:
%
\begin{itemize}
    \item Changing the overall file name using a |prefix|,
    \item Changing the file name for a single figure using
        |\tikzsetnextfilename|,
    \item Changing the file name for a restricted set of figures using
        |figure name|.
\end{itemize}

\begin{key}{/tikz/external/prefix=\marg{file name prefix} (initially empty)}
    A shortcut for |\tikzsetexternalprefix|\marg{file name prefix}, see below.
\end{key}

\begin{command}{\tikzsetexternalprefix\marg{file name prefix}}
    Assigns a common prefix used by all file names. For example,
    %
\begin{codeexample}[code only]
\tikzsetexternalprefix{figures/}
\end{codeexample}
    %
    will prepend |figures/| to every external graphics file name.

    Please note that |\tikzsetexternalprefix| is the \emph{only} way to assign
    a prefix in case you want to prepare your document for environments where
    \pgfname\ is not installed (see section~\ref{section-libs-external-nopgf}).
\end{command}

\begin{command}{\tikzsetnextfilename\marg{file name}}
    Sets the file name for the \emph{next} \tikzname\ picture or |\tikz| short
    command. It will \emph{only} be used for the next picture.

    Pictures for which no explicit file name has been set (or the next file
    name is empty) will get automatically generated file names.

    Please note that |prefix| will still be prepended to \marg{file name}.
    %
\begin{codeexample}[code only]
\documentclass{article}
% main document, called main.tex
\usepackage{tikz}

\usetikzlibrary{external}
\tikzexternalize[prefix=figures/] % activate

\begin{document}

\tikzsetnextfilename{trees}
\begin{tikzpicture} % will be written to 'figures/trees.pdf'
  \node {root}
    child {node {left}}
    child {node {right}
      child {node {child}}
      child {node {child}}
    };
\end{tikzpicture}

\tikzsetnextfilename{simple}
A simple image is \tikz \fill (0,0) circle(5pt);. % will be written to 'figures/simple.pdf'

\begin{tikzpicture} % will be written to 'figures/main-figure0.pdf'
   \draw[help lines] (0,0) grid (5,5);
\end{tikzpicture}
\end{document}
\end{codeexample}
    %
\begin{codeexample}[code only, tikz syntax=false]
pdflatex -shell-escape main
\end{codeexample}
    %
\end{command}

\begin{key}{/tikz/external/figure name=\marg{name}}
    Same as |\tikzsetfigurename|\marg{name}.
\end{key}

\begin{command}{\tikzsetfigurename\marg{name}}
    Changes the names of \emph{all} following figures. It is possible to change
    |figure name| during the document either using
    |\tikzset{external/figure name|=\marg{name}|}| or with this command. A
    unique counter will be used for each different \marg{name}, and each
    counter will start at $0$.

    The value of |prefix| will be applied after |figure name| has been
    evaluated.
    %
\begin{codeexample}[code only]
\documentclass{article}
% main document, called main.tex
\usepackage{tikz}

\usetikzlibrary{external}
\tikzexternalize % activate

\begin{document}

\begin{tikzpicture} % will be written to 'main-figure0.pdf'
  \node {root}
    child {node {left}}
    child {node {right}
      child {node {child}}
      child {node {child}}
    };
\end{tikzpicture}

{
  \tikzsetfigurename{subset_}
  A simple image is \tikz \fill (0,0) circle(5pt);. % will be written to 'subset_0.pdf'

  \begin{tikzpicture} % will be written to 'subset_1.pdf'
     \draw[help lines] (0,0) grid (5,5);
  \end{tikzpicture}
}% here, the old file name will be restored:

\begin{tikzpicture} % will be written to 'main-figure1.pdf'
   \draw (0,0) -- (5,5);
\end{tikzpicture}
\end{document}
\end{codeexample}
    %
    The scope of |figure name| ends with the next closing brace.

    Remark: Use |\tikzset{external/figure name/.add={prefix_}{_suffix_}}| to
    add a |prefix_| and a |_suffix_| to the actual value of |figure name|.
\end{command}

\begin{command}{\tikzappendtofigurename\marg{suffix}}
    Appends \meta{suffix} to the actual value of |figure name|.

    It is a shortcut for |\tikzset{external/figure name/.add={}|\marg{suffix}|}|
    (a shortcut which is also supported if \tikzname\ is not installed, see
    below).
\end{command}


\subsubsection{Remaking Figures or Skipping Figures}

\begin{command}{\tikzpicturedependsonfile\marg{file name}}
    Adds a dependency for the \emph{next} picture which is about to be
    externalized. If the command is invoked within a picture environment, it
    adds a dependency for the surrounding picture. Dependencies are written
    into \meta{target file}|.dep| in the format

    \meta{target file}|.\tikzexternalimgextension: |\meta{file name}.

    The effect is that if \meta{file name} changes, the external graphics
    associated with the picture shall be remade.

    This command uses the contents of
    \declareandlabel{\tikzexternalimgextension} to check for graphics. If you
    encounter difficulties with image extensions, consider redefining this
    macro (after |\tikzexternalize|).

    \paragraph{Limitations:}
    this command is currently only supported for |mode=list and make| and the
    generated |makefile|.
\end{command}

\begin{command}{\tikzexternalfiledependsonfile\marg{external graphics}\marg{file name}}
    A variant of |\tikzpicturedependsonfile| which adds a dependency for an
    \meta{external graphics}. The argument \meta{external graphics} must be the
    path as it would have been generated by the |external| library, i.e.\ without
    file extension but including any prefixes.
\end{command}

\begin{key}{/tikz/external/disable dependency files}
    Allows to (irreversibly) disable the generation of file dependencies.
    Disabling it will safe one |\newwrite| command, i.e.\ a write register.
    Note that the write register is only allocated if the feature has been used
    at all. This key needs to be provided as argument to |\tikzexternalize| (or
    it needs to be set before calling |\tikzexternalize|).

    Also see the |aux in dpth| key.
\end{key}

\begin{key}{/tikz/external/force remake=\marg{boolean} (default true)}
    A boolean which is used to customize the up-to-date checks of all following
    figures. Every up-to-date check will fail, resulting in automatic
    regeneration of every following figure.
    %
\begin{codeexample}[code only]
\tikzset{external/force remake}
\begin{tikzpicture}
    \draw (0,0) circle(5pt);
\end{tikzpicture}
\end{codeexample}
    %
    You can also use |force remake| inside of a local \TeX\ group to remake
    only selected pictures. The example
    %
\begin{codeexample}[code only]
\tikz \draw (0,0) -- (1,1);

{
\tikzset{external/force remake}
\begin{tikzpicture}
   \draw (0,0) circle(5pt);
\end{tikzpicture}
}

\tikz \draw (0,0) -- (1,1);
\end{codeexample}
    will only apply |force remake| to the second figure.

    Up-to-date checks are applied for |mode=convert with system call| and the
    makefile generated by |mode=list and make|.
\end{key}

\begin{key}{/tikz/external/remake next=\marg{boolean} (default true)}
    A variant of |force remake| which applies only to the next image.
\end{key}

\begin{key}{/tikz/external/export next=\marg{boolean} (default true)}
    A boolean which can be used to disable the export mechanism for single pictures.
\end{key}

\begin{key}{/tikz/external/export=\marg{boolean} (initially true)}
    A boolean which can be used to disable the export mechanism for all
    pictures inside of the current \TeX-scope.
    %
\begin{codeexample}[code only]
\begin{document}
\begin{tikzpicture} % will be exported
    ...
\end{tikzpicture}

{
\tikzset{external/export=false}
\begin{tikzpicture} % won't be exported
    ...
\end{tikzpicture}
...
}

\begin{tikzpicture} % will be exported
    ...
\end{tikzpicture}
\end{document}
\end{codeexample}
    %
    For \LaTeX, the feature lasts until the next |\end|\marg{$\cdot$} (this
    holds for every call to |\tikzset|).
\end{key}

\begin{key}{/tikz/external/up to date check=\marg{choice} (initially md5)}
    The |external| lib has to decide when some existing figure is up-to-date.
    In such a case, it can be used without remaking it. Outdated pictures will
    be remade.

    The key |up to date check| allows to choose among a couple of heuristics
    which are supposed to catch the most important reasons to remake a figure.

    The |up to date check| can be overrule by any of the |force remake| or
    |remake next| keys: if one of them is true, the figure is not up-to-date.

    The choice \declare{simple} is based on the existence of the file: the file
    is up-to-date if and only if it exists.

    The choice \declare{md5} generates an MD5 checksum of the picture for which
    the up-to-date check is running. The MD5 is compared against the MD5 of the
    previous run, which, in turn, will be written into an extra file with the
    extension |.md5|. This file will be modified if and only if the MD5
    comparison indicates a difference. The MD5 computation is based on the
    pdf\TeX\ method |\pdfmdfivesum|. If it is unavailable for some reason, the
    choice |diff| will be used instead.

    The choice \declare{diff} is the same as MD5 -- except that it compares the
    picture content as-is instead of a hash. The |.md5| file will be used to
    compare an old version with the current one -- but its content is some
    ``normalized'' version of the picture for internal use.

    \paragraph{Attention:}
    the content--based strategies |md5| and |diff| operate on the picture
    content -- and only on the picture content. Here, ``picture content'' only
    includes the top--level tokens; no expansion is applied and no included
    files are part of the strategies. If you change preamble styles, you have
    to rebuild the figures manually (for example by deleting the generated
    graphics files). If you have include files, consider using
    |\tikzpicturedependsonfile| and its variants. Since this key provides
    heuristics, you should always remake your figures before you finally
    publish your document. Example: Suppose we have the following picture which
    depends on a command |\mycommand|:
    %
\begin{codeexample}[code only]
\def\mycommand{My comment}

\begin{tikzpicture}

\node at (0,0) {\mycommand};

\end{tikzpicture}
\end{codeexample}
    %
    What happens if you change ``My comment'' to ``My super comment''? Well,
    |external| will \emph{not} pick it up; you will need to handle this
    manually. However, if you modify anything between |\begin{tikzpicture}| and
    |\end{tikzpicture}|, the |external| library \emph{will} pick it up and
    regenerate the picture.

    The |up to date check| is applied for |mode=convert with system call| and
    |mode=list and make|.
\end{key}

\begin{command}{\tikzexternaldisable}
    Allows to disable the complete externalization. While |export next| will
    still collect the contents of picture environments, this command uninstalls
    the hooks for the |external| library completely. Thus, nested picture
    environments or environments where |\end{tikzpicture}| is not directly
    reachable won't produce compilation failures -- although it is not possible
    to externalize them automatically.

    The externalization remains disabled until the end of the next \TeX\ group
    (or environment) or until the next call to |\tikzexternalenable|.
\end{command}

\begin{command}{\tikzexternalenable}
    Re-enables a previously running externalization after |\tikzexternaldisable|.
\end{command}


\subsubsection{Customizing the Externalization}

\begin{key}{/tikz/external/figure list=\marg{boolean} (initially true)}
    A boolean which configures whether a figure list shall be generated. A
    figure list is an output file named \marg{jobname}|.figlist| which is
    filled with file names of each figure, one per line.

    This file is not used by \TeX\ anymore, its purpose is to issue the
    required conversion commands |pdflatex -jobname |\marg{picture file name}
    \marg{main file} manually (or in a script). See
    section~\ref{sec:external:detail} for the details about the expected system
    call (or activate |mode=convert with system call| and inspect your log
    file).
    %
\begin{codeexample}[code only]
\documentclass{article}
% main document, called main.tex
\usepackage{tikz}

\usetikzlibrary{external}
\tikzexternalize[
   mode=graphics if exists,
   figure list=true,
   prefix=figures/]

\begin{document}

\tikzsetnextfilename{trees}
\begin{tikzpicture}
  \node {root}
    child {node {left}}
    child {node {right}
      child {node {child}}
      child {node {child}}
    };
\end{tikzpicture}

\tikzsetnextfilename{simple}
A simple image is \tikz \fill (0,0) circle(5pt);.

\begin{tikzpicture}
   \draw[help lines] (0,0) grid (5,5);
\end{tikzpicture}
\end{document}
\end{codeexample}

\begin{codeexample}[code only, tikz syntax=false]
pdflatex main
\end{codeexample}
    %
    generates |main.figlist| containing
    %
\begin{codeexample}[code only, tikz syntax=false]
figures/trees
figures/simple
figures/main-figure0
\end{codeexample}
    %
\end{key}

\begin{key}{/tikz/external/mode=\marg{choice} (initially convert with system call)}
    Configures what to do with \tikzname\ pictures (unless we are currently
    externalizing one particular image, in that case, these modes are ignored).

    The preconfigured mode |convert with system call| checks whether external
    graphics files are up-to-date and includes them if that is the case. Any
    picture which is not up-to-date will be generated automatically using a
    system call. The system call can be configured using the |system call|
    template. The up-to-date check is applied according to the
    |up to date check| key. As soon as |convert with system call| is set, the
    |figure list| will be disabled -- such a file is not required. In case you
    still need or want it, you can enable it after setting |mode|.

    Please note that system calls may be disabled for security reasons. For
    pdflatex, they can be enabled using
    %
\begin{codeexample}[code only, tikz syntax=false]
pdflatex -shell-escape
\end{codeexample}
    %
    while other \TeX\ variants may need other switches. The feature is
    sometimes called |\write18|.

    The choice |only graphics| always tries to replace pictures with external
    graphics. It is an error if the graphics file does not exist.

    The choice |no graphics| (or, equivalently, |only pictures|) typesets
    \tikzname\ pictures without checking for external graphics.

    A mixture is |graphics if exists|, it checks whether a suitable graphics
    file exists and includes it if that is the case. If it does not exist, the
    picture is typeset using \TeX.

    Mode |list only| skips every \tikzname\ picture; it only generates the file
    \marg{main file}|.figlist| containing file names for every picture, the
    contents of any picture environment is thrown away and a replacement text
    is shown. This implies |figure list=true|. See also the |list and make|
    mode which includes available graphics.

    The mode |list and make| is similar to |list only|: it generates the same
    file \marg{main file}|.figlist|, but any images which exist already are
    included as graphics instead of ignoring them. Furthermore, this mode
    generates an additional file: \marg{main file}.makefile. This allows to use
    a work flow like
    %
\begin{codeexample}[code only, tikz syntax=false]
% step 1: generate main.makefile:
pdflatex main
% step 2: generate ALL graphics on 2 processors:
make -j 2 -f main.makefile
% step 3: include the graphics:
pdflatex main
\end{codeexample}
    %
    \noindent This last make method is optional: |list and make| just assumes
    that images are generated somehow (not necessarily with the generated
    makefile). The generated makefile allows parallel externalization of
    graphics on multi-core systems and it supports any file dependencies
    configured with |\tikzpicturedependsonfile|. Furthermore, it respects the
    |force remake| and |remake next| keys.
\end{key}

\begin{key}{/tikz/external/verbose IO=\marg{boolean} (initially true)}
    A boolean which configures whether I/O operations shall be listed in the
    logfile.
\end{key}

\begin{key}{/tikz/external/verbose optimize=\marg{boolean} (initially true)}
    A boolean which configures whether optimization operations shall be listed
    in the logfile.
\end{key}

\begin{key}{/tikz/external/verbose=\marg{boolean} (initially true)}
    Sets all verbosity flags to \meta{boolean}.
\end{key}

\begin{key}{/tikz/external/optimize=\marg{boolean} (initially true)}
    Configures whether the conversion process shall be optimized. This affects
    only the case when |\jobname| differs from the main file name, i.e.\ when
    single pictures are converted.

    In that case, the main file is compiled as usual -- but everything except
    the selected picture is thrown away. If optimization is enabled, all other
    pictures won't be processed at all. Furthermore, expensive commands which
    do not contribute to the selected picture will be thrown away as well.

    The default implementation discards |\includegraphics| commands which are
    \emph{not} inside of the selected picture to reduce conversion time.

    It is possible to add commands which shall be optimized away, see below.
\end{key}

\begin{key}{/tikz/external/optimize command away=\meta{\textbackslash command}\marg{required argument count}}
    Installs commands to optimize \meta{\textbackslash command} away. As is
    described above, optimization applies to the case when single pictures are
    converted: one usually doesn't need to process (probably expensive)
    commands which do not contribute to the selected picture.

    The argument \marg{required argument count} is either empty or a
    non-negative integer between $0$ and $9$. It denotes the number of
    arguments which should be consumed after \meta{\textbackslash command}. In
    any case, one argument in square brackets after the command will be
    recognized as well. To be more precise, the following cases for arguments
    of \meta{\textbackslash command} are supported:
    %
    \begin{enumerate}
        \item If \marg{required argument count} is empty (the default),
            \meta{\textbackslash command} may take one optional argument in
            square brackets and one in curly braces (which is also optional).
        \item If \marg{required argument count} is not empty,
            \marg{\textbackslash command} may take one optional argument in
            square brackets. Furthermore, it expects exactly \marg{required
            argument count} following arguments.
    \end{enumerate}

    Example:
    %
\begin{codeexample}[code only]
\tikzset{external/optimize command away=\includegraphics}
\end{codeexample}

\begin{codeexample}[code only]
\newcommand{\myExpensiveMacro}[1]{Very expensive!}

\tikzset{external/optimize command away=\myExpensiveMacro}
\end{codeexample}

\begin{codeexample}[code only]
\newcommand{\myExpensiveMacroWithThreeArgs}[3]{Very expensive!}

\tikzset{external/optimize command away={\myExpensiveMacroWithThreeArgs}{3}}
\end{codeexample}

\begin{codeexample}[code only]
% A command with optional argument:
\newcommand{\aFurtherExample}[3][]{Very expensive!}

% consume only two arguments: the first optional one will be processed
% anyway:
\tikzset{external/optimize command away={\myExpensiveMacroWithThreeArgs}{2}}
\end{codeexample}
    %
    The argument \meta{\textbackslash command} must be the name of a single
    macro. Any occurrence of this macro, together with its arguments, will be
    removed.
    %
\begin{codeexample}[code only]
\begin{tikzpicture}
    % this picture is currently converted!
\end{tikzpicture}

This here is outside of the converted picture and contains \myExpensiveMacro. It will be discarded.

This call: \myExpensiveMacro[argument=value]{Argument} as well.
And this here: \myExpensiveMacro{Argument} also.
\end{codeexample}

    The default is to optimize |\includegraphics| away.

    This key is actually a style which sets the |optimize/install| and
    |optimize/restore| keys.
\end{key}

\begin{key}{/tikz/external/optimize/install}
    A command key which contains code to install optimizations. You can append
    code here (or clear the macro) if you need to modify the optimization.
\end{key}

\begin{key}{/tikz/external/optimize/restore}
    A command key which contains code to undo optimizations. You can append
    code here (or clear the macro) if you need to modify the optimization.
\end{key}

\begin{key}{/tikz/external/only named=\marg{boolean} (initially false)}
    If enabled, only pictures for which file names have been set explicitly
    using |\tikzsetnextfilename| will be considered, no file names will be
    generated automatically.
\end{key}

\begin{key}{/pgf/images/include external (initially \textbackslash pgfimage\{\#1\})}
\index{External Graphics!Bounding Box Issues}
    This command key constitutes the public interface to exchange the
    |\includegraphics| command used for the image inclusion. If can be
    overwritten using |include external/.code=|\marg{\TeX\ code}.

    Its description can be found in the corresponding basic layer documentation
    on page~\pageref{pgf:includeexternalkey}.

    Just one example here: you can use
    %
\begin{codeexample}[code only]
\pgfkeys{/pgf/images/include external/.code={\includegraphics[viewport=0 0 211.28 175.686]{#1}}}
\end{codeexample}
    %
    to manually change the viewport (bounding box) for included graphics.

    Another example (of probably limited use) is
    %
\begin{codeexample}[code only]
\pgfkeys{/pgf/images/include external/.code={\href{file:#1}{\pgfimage{#1}}}}
\end{codeexample}
    %
    \noindent which will generate a clickable hyperlink around the image.
    Clicking on it opens the single exported file\footnote{This requires all
    external graphics files in the same base directory as the main |.pdf|
    file.}.

    If you want to limit the effects of this key to just one externalized
    figure, use
    %
\begin{codeexample}[code only]
{
  \pgfkeys{/pgf/images/include external/.code={\includegraphics[viewport=0 0 211.28 175.686]{#1}}}
  \begin{tikzpicture}
     ...
  \end{tikzpicture}
}% this brace ends the effect of `include external'
\end{codeexample}
    %
\end{key}

\begin{command}{\tikzifexternalizing\marg{true code}\marg{false code}}
    This command can be used to check whether an image is currently written to
    its separate graphics file (if the ``grab'' procedure is running). If so,
    the \marg{true code} will be executed. If not, that means if the main
    document is being typeset normally, the \marg{false code} will be invoked.

    This command must be used \emph{after} |\tikzexternalize|.
\end{command}

\begin{command}{\tikzifexternalizingnext\marg{true code}\marg{false code}}
    Like |\tikzifexternalizing|, but this variant also checks if the next
    following figure is the one which is about to be written to its separate
    graphics file.
\end{command}


\subsubsection{Details About The Process}
\label{sec:external:detail}

The standard run |pdflatex |\meta{main document} causes the |external| library
to check every occurrence of |\begin{tikzpicture}| and every |\tikz| short
command. If it finds a picture which shall be exported, it queries the
respective file name and checks whether the file exists already. If so, it
includes the external graphics. If not, it requires an externalization which
can be done automatically (the default), semi-automatically (with
|mode=list and make|) or manually (by issuing the requires system calls
somehow).

The library can detect whether it runs in ``conversion mode'', i.e.\ if it
should only process a single image. To do so, it checks whether the internal
macro \declareandlabel{\tikzexternalrealjob} exists. If so, its contents is
assumed to be \meta{main document} (without the suffix |.tex|). Usually, this
macro is set by the conversion system call,
%
\begin{codeexample}[code only, tikz syntax=false]
pdflatex -jobname "main-figure0" "\def\tikzexternalrealjob{main}\input{main}"
\end{codeexample}
%
\noindent where |main-figure0| is the picture we are currently externalizing
and |main.tex| is the main document.

As soon as ``conversion mode'' has been detected, \pgfname\ changes the output
routine. The complete file |main.tex| is processed as normal, but only the part
of the desired picture will be written to the output file, in our case
|main-figure0.pdf|. The rest of the document is silently thrown away. Of
course, such a conversion process is quite expensive since we need to do it for
every picture. Since everything except the current picture is thrown away, the
library skips all other pictures. Furthermore, any |\includegraphics| commands
which are outside of the converted \tikzname-picture will be skipped as well.
Thus, the conversion process should be much faster than typesetting the
complete document, but it still requires its time. Eventually, the call
|\input{main}| returns and the picture is ready. From this point on, the
external graphics will be used.

There is another possibility to communicate \meta{main document} to the
subprocess performing the externalization: namely to write
`|\tikzexternalize{main}|' into the document. In this case, the conversion
system call will be
%
\begin{codeexample}[code only, tikz syntax=false]
pdflatex -jobname "main-figure0" "main"
\end{codeexample}
%
\noindent and the contents of |\tikzexternalrealjob| is set automatically. This
case is detected by |\tikzexternalize|, and the |system call| is updated
automatically (by patching its |\texsource| template argument). It is not
necessary to change the |system call| manually.

The sequence in which system calls are performed and the decision whether they
are issued automatically is governed by the |mode| key, consult its
documentation for details.


\subsection{Using External Graphics Without \textmd{\pgfname}\ Installed}
\label{section-libs-external-nopgf}

Given that every picture has been exported correctly, one may want to compile a
file without \pgfname\ and \tikzname\ installed. \tikzname\ comes with a
minimal package which contains just enough commands to replace every
|tikzpicture| environment and the |\tikz| short command with the appropriate
external graphics. It can be found at
%
\begin{codeexample}[code only, tikz syntax=false]
latex/pgf/utilities/tikzexternal.sty
\end{codeexample}
%
\noindent and needs to be used instead of |\usepackage{tikz}|. So, we comment
|\usepackage{tikz}| and |\usetikzlibrary{external}|, load packages |graphicx|
and |tikzexternal|, and finally our example from the beginning becomes
%
\begin{codeexample}[code only]
\documentclass{article}
% main document, called main.tex
%\usepackage{tikz}

\usepackage{graphicx}
\usepackage{tikzexternal}

%\usetikzlibrary{external}
\tikzexternalize

\begin{document}
\begin{tikzpicture}
  \node {root}
    child {node {left}}
    child {node {right}
      child {node {child}}
      child {node {child}}
    };
\end{tikzpicture}

A simple image is \tikz \fill (0,0) circle(5pt);.

Furthermore, we might want to draw \tikz[baseline]\draw (0,-1) rectangle (1,1);
\end{document}
\end{codeexample}
%
\noindent where the following files are necessary to compile the document:
%
\begin{codeexample}[code only, tikz syntax=false]
tikzexternal.sty
main.tex
main-figure0.pdf
main-figure1.pdf
main-figure2.pdf
\end{codeexample}
%
\noindent If there are any `|.dpth|' files, for example |main-figure2.dpth|,
these files are also required. They contain information for the \tikzname\
|baseline| option (or |\label|s inside external graphics).

Just copy the |.sty| file into the directory of your |main.tex| file and use it
as part of your document.

Please keep in mind, that only |tikzpicture| environments and |\tikz| short
images are available within the externalization framework. Additionally, calls
to |\tikzset| and |\pgfkeys| won't lead to compilation errors because they are
simply ignored. But since |pgfkeys| is not available, any option supplied to
|\tikzexternalize| is \emph{ignored}.

\paragraph{Attention:}
Since the simple replacement |\usepackage{tikzexternal}| doesn't support the
key--value interface, you \emph{need} to use |\tikzsetexternalprefix| instead
of the |prefix| option and |\tikzsetfigurename| instead of the |figure name|
option since |\tikzset| is not available in such a context.

\paragraph{Remark:}
Some of the features of this library are mainly useful to improve the speed of
successive document compilations. In other words: you can't use all features in
this context, keep it simple.


\subsection{\texttt{eps} Graphics Export}

It is also possible to use \eps\ graphics instead of \pdf\ files. There are
different ways to produce them, for example to use |pdflatex| and call
|pdftops -eps |\marg{pdf file} \marg{eps file} afterwards. You could add this
command to the |system call| option.

Alternatively, you can use |latex| and |dvips| for image conversion as is
explained for the |system call| option, see
page~\pageref{extlib:systemcall:option}. See the documentation for the basic
level externalization in section~\ref{section-external} for restrictions of
other drivers.


\subsection{Bitmap Graphics Export}

Occasionally, you may have an extremely large graphics which takes long times
to render. It might be interesting to generate a bitmap (raster) image, which
displays much faster (for example in a presentation). I have used this feature
to speed-up the display of large shadings.

The |external| library can be customized to export bitmap images -- with the
help of external programs. Due to the dependence of external programs, you may
need to adjust these commands manually. For example, on my computer, the
ImageMagick Suite is installed which comes with the |convert| tool. Together
with |pdflatex|, I can define the following style:
%
\begin{codeexample}[code only]
\tikzset{
    % Defines a custom style which generates BOTH, .pdf and .png export
    % but prefers the .png on inclusion.
    %
    % This style is not pre-defined, you may need to copy-paste and
    % adjust it.
    png export/.style={
        external/system call/.add=
            {}
            {; convert -density 300 -transparent white "\image.pdf" "\image.png"},
        %
        /pgf/images/external info,
        /pgf/images/include external/.code={%
            \includegraphics
                [width=\pgfexternalwidth,height=\pgfexternalheight]
                {##1.png}%
        },
    }
}
\end{codeexample}
%
\noindent The example above defines a new style called `|png export|' which,
when it is set with |\tikzset{png export}| somewhere in the document, modifies
the configuration for both file generation and file input. The file generation
is modified by appending the ImageMagick command to |system call| (separated by
`|;|' as usual on Linux). This is, in principle, enough to generate a |.png|
file. The |include external| command is overwritten such that it uses the
|.png| file instead of the |.pdf| file (which exists as well in the
configuration above). But since a |.png| file can have a much higher resolution
than the desired image dimensions, we have to add |width| and |height|
explicitly. Usually, the |external| library does not provide size information
(it is unnecessary for |.pdf| or |.eps| since these formats have their bounding
box information). To enable size information, the style uses the
|external info| key, which, in turn, provides the |\pgfexternalwidth| and
|\pgfexternalheight| commands.

Now we can use |\tikzset{png export}| either document-wide or just for one
particular image. The configuration remains in effect until the end of the
current environment (or until the next closing curly brace `|}|').

\begin{key}{/pgf/images/external info=\marg{boolean} (initially false)}
    If this key is activated, the size for any externalized image will be
    stored explicitly into the associated |.dpth| file.

    When the file is included by |\pgfincludeexternalgraphics| (or
    automatically by the |external| library), the width is available as
    \declareandlabel{\pgfexternalwidth} and the height as
    \declareandlabel{\pgfexternalheight}.
\end{key}


\subsection{Compatibility Issues}

\subsubsection{References In External Pictures}

It is allowed if a picture contains references, for example
|\tikz \node {Reference to \ref{a:label}};|.

There is just one issue: if the main job is currently compiling, its |.aux|
file is not in its final state (even worse: it may not be readable at all). The
picture externalization, however, needs the main |.aux| file to query any
references.

Thus, you \emph{will} need to invoke
|pdflatex -jobname |\meta{image}| |\meta{mainfile} \emph{manually}
for any image which contains references.

This problem arises only for |mode=convert with system call|. In this case,
the |external| library creates a special |\jobname.auxlock| file to check
whether the main |.aux| file is currently usable.


\subsubsection{Compatibility With Other Libraries or Packages}

The |external| library has the following compatibility issues:
%
\begin{enumerate}
    \item The |external| library comes with special support for
        |\usetikzlibrary{fadings}|: the |fadings| library may define local
        pictures which would be externalized (although they shouldn't). There
        is special handling to suppress this bug if |\tikzexternalize| is
        called \emph{after} |\usetikzlibrary{fadings}| or if all fadings are
        defined \emph{before} |\tikzexternalize|.
    \item Problems have been reported when using |\tikzexternalize| (or the
        basic layer externalization) together with |\usepackage{glossary}|.
        This problem disappears if |\tikzexternalize| is called \emph{before}
        |\usepackage{glossary}|.
    \item Problems with |\usepackage{pdfpages}| and |\usepackage{vmargin}|: The
        |external| library replaces the current shipout routine of \TeX\ during
        its externalization. This might raise problems with other packages
        which also manipulate the shipout routine (like the mentioned ones). To
        fix those problems, use
        %
\begin{codeexample}[code only]

\usetikzlibrary{external}

\tikzifexternalizing{%
    % don't include package XYZ here
}{%
    \usepackage{pdfpages}
    \usepackage{vmargin}
    ...
}%
\end{codeexample}
        %
        This uses the requested packages for the main document, but not for the
        single, exported graphics.
\end{enumerate}

In general, the |\tikzifexternalizing| feature might be used to solve package
conflicts and the |\tikzexternaldisable| and |\tikzexternalenable| features can
be used to solve problems with single pictures.


\subsubsection{Compatibility With Bounding Box Restrictions}

Bounding box restrictions provide no problem when used with \eps\ graphics.
However, they pose problems for |pdflatex|, so you may need to use the
|latex|/|dvips| combination if you use bounding box restrictions and
externalization. Currently, the only possibility for bounding box restrictions
and |pdflatex| is to use a combination of |trim left|/|trim right|/|baseline|:
these keys do not \emph{really} truncate the bounding box, they only store
horizontal and vertical shifts (also see the |trim lowlevel| key in this
context).


\subsubsection{Interoperability With The Basic Layer Externalization}

This library is fully compatible with
|\beginpgfgraphicnamed|$\dotsc$|\endpgfgraphicnamed| environments. However, you
will need to use the |export next=false| key to avoid conflicts:
%
\begin{codeexample}[code only]
\beginpgfgraphicnamed{picture4}
\tikzset{external/export next=false}
\begin{tikzpicture}
   \draw (0,0) -- (4,4);
\end{tikzpicture}
\endpgfgraphicnamed
\end{codeexample}
%
Please keep in mind that file prefixes do not apply to the basic layer.
}