Unclear statement in tutorial: \robExtCacheCommand

[quarkQuark]

Thanks so much for making this package!

On page 11 of the documentation (3.2 Caching a tikz picture), it says

Note that we do recommend to use \robExtCacheCommand for the macro version \tikz since \tikz has a quite complicated parsing strategy. \cacheTikz takes care of this already.

The grammar is unclear to me ("for the macro version \tikz"?), and \robExtCacheCommand is not mentioned elsewhere in the documentation. Does this mean that \cacheTikz does something that \robExtCacheEnvironment{tikzpicture}{tikzpicture} does not? What does \robExtCacheCommand do, and would an end-user ever need to use it?

Commands called \cacheCommand and \cacheEnvironment are mentioned elsewhere in the documentation. How are these different?

I'm asking about this because my use-case is primarily tikz-cd (commutative diagrams). My understanding is that tikz-cd wraps tikzpicture somehow; it's abstracted enough that it causes problems for the ordinary externalize library (in particular, \cacheTikz probably won't include it), but I suspect it might carry over some of the 'complicated parsing strategy' (depending on what makes it complicated).

[I'm happy to try and figure it out myself, but if you're able to provide a template for how to use this package with tikz-cd and a preamble that would be really helpful!]

[tobiasBora]

Thanks for your report.

So first, I apologize if the doc is not always clear, I’m sure there are quite some typos since I wrote it quite quickly in order to quickly release the v2.0 on CTAN that has some small backward incompatible changes and major speed improvements (and also because I can't afford to spend much more time on this lib right now). Notably, if you see \foo or \robExtFoo, they always refer to the same command and are alias (I do that so that if another package defines \foo, the user can still use this lib using \robExtFoo). The doc should never mention the robExt version, but I made a few copy/paste mistakes.

Regarding \cacheTikz, it does something more than \cacheEnvironment{tikzpicture}{tikzpicture} since it also caches the macro/command \tikz. Sayed differently, if you just write \robExtCacheEnvironment{tikzpicture}{tikzpicture}, it will cache all:

\begin{tikzpicture}
…
\end{tikzpicture}

but it will NOT cache:

\tikz …;

One might be tempted to write:

\cacheCommand{tikz}[O{}m]{tikz}

and this would cache successfully calls like:

\tikz[overlay] {\node{A}};

but it will raise a syntax error if you call somewhere:

\tikz[overlay] \node{A};

(note the absence of {}) since it does not have the expected shape O{}m (yeah, tikz is parsing its arguments in a non-standard way). So you can think of \cacheTikz as caching both the tikzpicture environment and the \tikz ; command.

Then, \cacheCommand (aka \robExtCacheCommand) is used to cache automatically commands (like \foo) while \cacheEnvironment is used to cache automatically environments (hence the name), like \begin{foo}\end{foo}. A end-user would use \cacheCommand whenever they wish to cache a command like \foo{…}.

So this library is compatible with tikz-cd (you see some examples involving the library zx-calculus: this library is actually a wrapping around tikz-cd, and in the ), but you need to be sure to call \cacheEnvironment first:

\cacheEnvironment{tikzcd}{tikz, add to preamble={\usepackage{tikz-cd}}}

and it should cache automatically all tikzcd figures (if you feel fancy, you can define your own tikzcd preset, compile it to compile even faster…)

I hope it answers your questions. I will try to make it clearer in the doc, and add an example with tikz-cd.

[tobiasBora]

I added in the doc an example of use with tikzcd, I fixed the \robExt prefix, and hopefully clarified a bit the intro. I will close this for now, if you still have questions or see other bugs/unclear statements, please let me know.

[tobiasBora]

Btw, if you have other questions that do not qualify as bug, I also created a discussion "forum" here https://github.com/leo-colisson/robust-externalize/discussions

[quarkQuark]

Thank you, that's a really helpful explanation. I was very impressed how thorough the documentation is given how new the project is!

[tobiasBora]

Ahaha thanks. Actually, writing the documentation is actually my way to write LaTeX test code, so when I write a new function I try to test & document it at the same time ^^ Sometimes it can give quite long documentation for this reason.