% Copyright 2008 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 uncomment
|\usepackage{tikz}| and 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.
}
