pgf (15jan23)

git-svn-id: svn://tug.org/texlive/trunk@65553 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 1226 insertions, 0 deletions

diff --git a/Master/texmf-dist/doc/generic/pgf/pgfmanual-en-library-external.tex b/Master/texmf-dist/doc/generic/pgf/pgfmanual-en-library-external.tex
new file mode 100644
index 00000000000..e7ddea78365
--- /dev/null
+++ b/Master/texmf-dist/doc/generic/pgf/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.
+}