summaryrefslogtreecommitdiff
path: root/graphics/pgf/base/doc/pgfmanual-en-library-external.tex
diff options
context:
space:
mode:
Diffstat (limited to 'graphics/pgf/base/doc/pgfmanual-en-library-external.tex')
-rw-r--r--graphics/pgf/base/doc/pgfmanual-en-library-external.tex1226
1 files changed, 1226 insertions, 0 deletions
diff --git a/graphics/pgf/base/doc/pgfmanual-en-library-external.tex b/graphics/pgf/base/doc/pgfmanual-en-library-external.tex
new file mode 100644
index 0000000000..e7ddea7836
--- /dev/null
+++ b/graphics/pgf/base/doc/pgfmanual-en-library-external.tex
@@ -0,0 +1,1226 @@
+% 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 itself
+ 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/.append=
+ {; 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.
+}