1 files changed, 54 insertions, 24 deletions

diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-external.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-external.tex
index 7399ed6f185..7d2130b035b 100644
--- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-external.tex
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-external.tex
@@ -41,7 +41,7 @@ The library always searches for the \emph{next} picture's end, |\end{tikzpicture
 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 only supported for \LaTeX\ yet.
+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}
@@ -70,7 +70,7 @@ A simple image is \tikz \fill (0,0) circle(5pt);.
 
 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]
+\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.
@@ -114,7 +114,7 @@ From this point on, successive runs of \LaTeX\ will use the final graphics files
 	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.}.
 
 	For |eps| output, you can (and need to) use
-\begin{codeexample}[code only]
+\begin{codeexample}[code only, tikz syntax=false]
 \tikzset{external/system call={latex \tikzexternalcheckshellescape -halt-on-error
     -interaction=batchmode -jobname "\image" "\texsource";
     dvips -o "\image".ps "\image".dvi}}
@@ -128,11 +128,11 @@ From this point on, successive runs of \LaTeX\ will use the final graphics files
 \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 of 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.
 
 There are, however, some points which need your attention when you try to use
 \begin{enumerate}
-	\item[a)] |\ref| to something in the main document inside of an externalized graphics or
+	\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}
 
@@ -142,9 +142,14 @@ Point b) is realized automatically by the external library. In detail, a |\label
 \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 one further time 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.}.
+	\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}
 There is just one special case: if a |\label|/|\ref| combination is realized itsself by a |tikzpicture| which should be externalized, you need to proceed as for case a) since |mode=convert with system call| can't handle that stuff on its own. Thus, |\label| works automatically, just translate the main document often enough.
+\begin{key}{/tikz/external/aux in dpth=\marg{boolean} (initially true)}
+	Allows to disable the feature. Disabling it will safe one |\newwrite| command, i.e.\ a write register.
+
+	Also see the |disable dependency files| feature.
+\end{key}
 
 
 
@@ -204,7 +209,7 @@ A simple image is \tikz \fill (0,0) circle(5pt);. % will be written to 'figures/
 \end{tikzpicture}
 \end{document}
 \end{codeexample}
-\begin{codeexample}[code only]
+\begin{codeexample}[code only, tikz syntax=false]
 pdflatex -shell-escape main
 \end{codeexample}
 \end{command}
@@ -276,6 +281,11 @@ pdflatex -shell-escape main
 \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.
@@ -337,6 +347,25 @@ pdflatex -shell-escape main
 	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.
+
+	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.
 
@@ -352,7 +381,7 @@ pdflatex -shell-escape main
 \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 you log file).
+	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}
@@ -386,11 +415,11 @@ A simple image is \tikz \fill (0,0) circle(5pt);.
 \end{document}
 \end{codeexample}
 
-\begin{codeexample}[code only]
+\begin{codeexample}[code only, tikz syntax=false]
 pdflatex main
 \end{codeexample}
 generates |main.figlist| containing
-\begin{codeexample}[code only]
+\begin{codeexample}[code only, tikz syntax=false]
 figures/trees
 figures/simple
 figures/main-figure0
@@ -400,10 +429,11 @@ figures/main-figure0
 \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 simple: if the file does not exist, it is not up-to-date. Furthermore, if one of the |force remake| or |remake next| keys is true, the figure is not up-to-date. In all other case, the file is considered to be up-to-date. 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|.
+	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]
+\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|.
@@ -417,7 +447,7 @@ pdflatex -shell-escape
 	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]
+\begin{codeexample}[code only, tikz syntax=false]
 % step 1: generate main.makefile:
 pdflatex main
 % step 2: generate ALL graphics on 2 processors:
@@ -425,7 +455,7 @@ make -j 2 main.makefile
 % step 3: include the graphics:
 pdflatex main
 \end{codeexample}
-	\noindent This last make method is, however unnecessary: |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.
+	\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}
@@ -454,7 +484,7 @@ pdflatex main
 \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-negativ 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:
+	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.
@@ -556,7 +586,7 @@ And this here: \myExpensiveMacro{Argument} also.
 The standard run |pdflatex |\meta{main document} causes the |external| library to check every occurrence of |\begin{tikzpicture}| and every |\tikz| shortcommand. 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]
+\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.
@@ -565,7 +595,7 @@ As soon as ``conversion mode'' has been detected, \pgfname\ changes the output r
 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]
+\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.
@@ -577,7 +607,7 @@ The sequence in which system calls are performed and the decision whether they a
 \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]
+\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
@@ -608,14 +638,14 @@ 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]
+\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 of external graphics).
+\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.
 
@@ -623,7 +653,7 @@ Please keep in mind, that only |tikzpicture| environments and |\tikz| short imag
 
 \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.
+\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{\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.
@@ -655,11 +685,11 @@ The |external| library can be customized to export bitmap images -- with the hel
     }
 }
 \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.
+\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 actual environment (or until the next closing curly brace `|}|').
+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=\mchoice{true,false} (initially false)}
+\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}.