summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/robust-externalize/robust-externalize.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/robust-externalize/robust-externalize.tex')
-rw-r--r--macros/latex/contrib/robust-externalize/robust-externalize.tex120
1 files changed, 118 insertions, 2 deletions
diff --git a/macros/latex/contrib/robust-externalize/robust-externalize.tex b/macros/latex/contrib/robust-externalize/robust-externalize.tex
index f06333b9fe..93d7f664e0 100644
--- a/macros/latex/contrib/robust-externalize/robust-externalize.tex
+++ b/macros/latex/contrib/robust-externalize/robust-externalize.tex
@@ -105,7 +105,7 @@
{\Large\bfseries Cache anything (\tikzname, tikz-cd, python…),\\in a robust, efficient and pure way.}
\vspace{1em}
- {Léo Colisson \quad Version 2.5}\\[3mm]
+ {Léo Colisson \quad Version 2.6}\\[3mm]
{\href{https://github.com/leo-colisson/robust-externalize}{\texttt{github.com/leo-colisson/robust-externalize}}}
\end{center}
@@ -2000,6 +2000,89 @@ We provide a list of placeholders that are useful to escape parts of the strings
\end{pgfmanualentry}
\begin{pgfmanualentry}
+ \extractcommand\placeholderRemoveSpacesUntil\marg{placeholder}\opt{\oarg{nb of additional letters to remove}}\marg{separator}\@@
+ \makeatletter%
+ \def\extrakeytext{style, }
+ \extractkey/robExt/placeholder remove spaces until=\marg{placeholder}\marg{separator}\@nil
+ \extractkey/robExt/remove spaces until=\marg{separator}\@nil
+ \extractkey/robExt/placeholder strictly remove spaces until=\marg{placeholder}\marg{separator}\@nil
+ \extractkey/robExt/strictly remove spaces until=\marg{separator}\@nil
+ \makeatother%
+ \pgfmanualbody
+ (new in v2.6) Removes all the spaces before |separator|, together with the separator itself and the next character (unless you use the |strictly| version, in that case the next character is not dropped, or if you change the default value of |additional letters to remove| that defaults to 1). Note that |prepend all lines| automatically apply it to the |__ROBEXT_MAIN_CONTENT_ORIG__| placeholder, i.e. the text typed by the user.
+
+ This is useful, for instance, if your editor tends to automatically remove the indentation of your python code while indenting automatically the document.
+\begin{codeAndResult}
+%% See that the python code can be freely indented now:
+\begin{CacheMeCode}{python print code and result, remove spaces until={>>>}}
+ >>> for i in range(2):
+ >>> print(f"Hello {i}")
+\end{CacheMeCode}
+\end{codeAndResult}
+\end{pgfmanualentry}
+
+
+\begin{pgfmanualentry}
+ \extractcommand\placeholderPrependAllLines\marg{placeholder}\marg{text}\@@
+ \makeatletter%
+ \def\extrakeytext{style, }
+ \extractkey/robExt/placeholder prepend all lines=\marg{placeholder}\marg{text}\@nil
+ \extractkey/robExt/prepend all lines=\marg{text}\@nil
+ \makeatother%
+ \pgfmanualbody
+ (new in v2.6) Prepend all lines with |text|. This can be useful, for instance, if you want to indent a whole block of python code automatically. Note that the text is evaluated, so in case you want to insert multiple spaces, use |\space| like in:\\
+ |prepend all lines={\space\space\space\space}|\\
+\begin{codeAndResult}
+\begin{PlaceholderFromCode}{__TMP__}
+ >>> def f(x): % hye # 42
+ >>> return 42
+ >>>
+ >>> def g(z):
+ >>> return 48
+\end{PlaceholderFromCode}
+\placeholderRemoveSpacesUntil{__TMP__}{>>>}
+\placeholderPrependAllLines{__TMP__}{My text\space\space\space\space}
+\printPlaceholderNoReplacement{__TMP__}
+\end{codeAndResult}
+Note that |prepend all lines| automatically adds the text to the |__ROBEXT_MAIN_CONTENT_ORIG__| placeholder, i.e. the text typed by the user.
+\end{pgfmanualentry}
+
+\begin{pgfmanualentry}
+ \extractcommand\placeholderRemoveLeadingSpaces\marg{placeholder}\@@
+ \makeatletter%
+ \def\extrakeytext{style, }
+ \extractkey/robExt/placeholder remove leading spaces=\marg{placeholder}\@nil
+ \extractkey/robExt/remove leading spaces\@nil
+ \extractkey/robExt/remove leading spaces if not disabled\@nil
+ \extractkey/robExt/do not remove leading spaces\@nil
+ \makeatother%
+ \pgfmanualbody
+ (new in v2.6) Remove the indentation of a placeholder (the |__ROBEXT_MAIN_CONTENT_ORIG__| placeholder, containing the content typed by the user, is used when not specified), by removing on each line the highest possible number of leading spaces (the same number of spaces is removed on all lines).
+\begin{codeAndResult}
+\begin{PlaceholderFromCode}{__TMP__}
+ def f(x): % hye # 42
+ return 42
+
+ def g(z):
+ return 48
+\end{PlaceholderFromCode}
+\placeholderRemoveLeadingSpaces{__TMP__}
+\printPlaceholderNoReplacement{__TMP__}
+\end{codeAndResult}
+Note that |remove leading spaces if not disabled| is like |remove leading spaces|, except that it is not run if the |do not remove leading spaces| style is applied before. This is used inside some styles like |python| that cares about indentation to remove the leading spaces (before v2.6, it was forbidden to add any indentation to the python code), while allowing the user to disable it temporarily (who knows why?) by using the style:
+\begin{verbatim}
+do not remove leading spaces, python
+\end{verbatim}
+Since |remove leading spaces if not disabled| is enabled by default on python, it is therefore fine to indent your python code like in:
+\begin{codeAndResult}
+\begin{CacheMeCode}{python print code and result}
+ for i in range(3):
+ print(f"Hello {i}")
+\end{CacheMeCode}
+\end{codeAndResult}
+\end{pgfmanualentry}
+
+\begin{pgfmanualentry}
\extractcommand\placeholderHalveNumberHashesInplace\marg{placeholder}\@@
\extractcommand\placeholderDoubleNumberHashesInplace\marg{placeholder}\@@
\makeatletter%
@@ -2074,6 +2157,30 @@ Compare \evalPlaceholder{__MACRO_EVALUATED__} and \evalPlaceholder{__MACRO_NOT_E
Note that this works well for commands that expand completely, but some more complex commands might not expand properly (like |cref|). I need to investigate how to solve this issue, meanwhile you can still disable externalization for these pictures.
\end{pgfmanualentry}
+\begin{pgfmanualentry}
+ \extractcommand\lenToCm\opt{\oarg{unit}}\marg{expression}\@@
+ \extractcommand\lenToCmNoUnit\opt{\oarg{unit}}\marg{expression}\@@
+ \pgfmanualbody
+ |\lenToCm{.75\linewidth}| will output the length of |.75\linewidth| in cm by default, like |10cm|. If you want to change the unit, you can use the optional argument to specify a different unit (like |in| for inches, see |\dim_to_decimal_in_unit| for details). You can remove the unit at the end using |\lenToCmNoUnit{.75\linewidth}| (needs v2.6) to obtain something like |10| instead of |10cm|. These commands are helpful with |set placeholder eval| to send length from \LaTeX{} to your environment:
+\begin{codeAndResult}
+\begin{CacheMeCode}{python, set placeholder eval={__LINEWIDTH__}{\lenToCmNoUnit[in]{.75\linewidth}}}
+import matplotlib.pyplot as plt
+import matplotlib
+from matplotlib.pyplot import figure
+figure(figsize=(__LINEWIDTH__, __LINEWIDTH__))
+year = [2014, 2015, 2016, 2017, 2018, 2019]
+tutorial_count = [39, 117, 111, 110, 67, 29]
+plt.plot(year, tutorial_count, color="#6c3376", linewidth=2)
+plt.title("Simple plot")
+plt.xlabel('Year')
+plt.ylabel('Number of futurestud.io Tutorials')
+print(get_filename_from_extension(".pgf"))
+# https://stackoverflow.com/a/52587591/4987648
+plt.savefig("__ROBEXT_OUTPUT_PDF__", bbox_inches="tight")
+\end{CacheMeCode}
+\end{codeAndResult}
+\end{pgfmanualentry}
+
\subsubsection{Groups: the import system}\label{sec:importSystem}
(This whole system was added v2.0.)
@@ -2340,6 +2447,7 @@ This content is cached $\delta$.
\def\extrakeytext{style, }
\extractkey/robExt/new preset=\marg{name preset}\marg{preset options}\@nil
\extractkey/robExt/add to preset=\marg{name preset}\marg{preset options}\@nil
+ \extractkey/robExt/add before preset=\marg{name preset}\marg{preset options}\@nil
\makeatother%
\pgfmanualbody
You can then create your own style (or preset) in |\robExtConfigure| (that is basically an alias for |\pgfkeys{/robExt/.cd,#1}|) containing your template, add your own placeholders and commands to configure them etc. We provide two helper functions since v2.0:\\
@@ -2390,6 +2498,7 @@ This content is cached $\delta$.
This content is cached $\delta$.
\end{CacheMe}
\end{codeexample}
+The |before| variation (from 2.6) simply adds the style before the existing style. May be useful to disable default options of a style.
\end{pgfmanualentry}
\begin{pgfmanualentry}
@@ -3837,7 +3946,7 @@ with open(get_verbatim_output(), "w") as f:
\end{CacheMeCode}
\end{codeAndResult}
-\textbf{Importantly: you do not want to indent the whole content of CacheMeCode, or the spaces will also appear in the final code.}
+Note that if you use a version before 2.6, you cannot indent further the python code (i.e.\ the first line must not start with any space). This is fixed in 2.6 with the addition of |remove leading spaces if not disabled| in the python preset by default, that will remove automatically any unnecessary indentation. If you use automatic indentation in your text editor, you might also like to use |remove spaces until| so that automatically indenting your whole document does not ruin the indentation of the python code.
You can also generate some images. This code will produce the image in \cref{fig:pythonGeneratedImage2}:
\begin{codeexample}[code only]
@@ -4802,6 +4911,13 @@ Options > Configure TeXstudio > Editor > Replace tabs in text with spaces
\section{Changelog}
\begin{itemize}
+\item v2.6:
+ \begin{itemize}
+ \item Added |\lenToCmNoUnit|
+ \item Added |\placeholderPrependAllLines| and alike
+ \item Added |remove spaces until| and alike
+ \item Added |placeholderRemoveLeadingSpaces| and alike
+ \end{itemize}
\item v2.5:
\begin{itemize}
\item Add tikzit support