summaryrefslogtreecommitdiff
path: root/support/latexindent/documentation/sec-replacements.tex
diff options
context:
space:
mode:
Diffstat (limited to 'support/latexindent/documentation/sec-replacements.tex')
-rw-r--r--support/latexindent/documentation/sec-replacements.tex619
1 files changed, 314 insertions, 305 deletions
diff --git a/support/latexindent/documentation/sec-replacements.tex b/support/latexindent/documentation/sec-replacements.tex
index 5491df6072..08468ba295 100644
--- a/support/latexindent/documentation/sec-replacements.tex
+++ b/support/latexindent/documentation/sec-replacements.tex
@@ -9,29 +9,29 @@
\announce{2019-07-13}{replacement mode switches} file by using any of the \texttt{-r},
\texttt{-rv} or \texttt{-rr} switches: \index{verbatim!rv, replacementrespectverb switch}
\begin{itemize}
- \item the \texttt{-r} switch will perform indentation and replacements, not respecting verbatim
- code blocks;
- \item the \texttt{-rv} switch will perform indentation and replacements, and \emph{will}
- respect verbatim code blocks;
- \item the \texttt{-rr} switch will \emph{not} perform indentation, and will perform
- replacements not respecting verbatim code blocks.
+ \item the \texttt{-r} switch will perform indentation and replacements, not respecting verbatim
+ code blocks;
+ \item the \texttt{-rv} switch will perform indentation and replacements, and \emph{will}
+ respect verbatim code blocks;
+ \item the \texttt{-rr} switch will \emph{not} perform indentation, and will perform
+ replacements not respecting verbatim code blocks.
\end{itemize}
We will demonstrate each of the \texttt{-r}, \texttt{-rv} and \texttt{-rr} switches, but
a summary is given in \cref{tab:replacementswitches}.
\begin{table}[!htb]
- \centering
- \caption{The replacement mode switches}\label{tab:replacementswitches}
- \begin{tabular}{rcc}
- \toprule
- switch & indentation? & respect verbatim? \\
- \midrule
- \texttt{-r} & \faCheck & \faClose \\
- \texttt{-rv} & \faCheck & \faCheck \\
- \texttt{-rr} & \faClose & \faClose \\
- \bottomrule
- \end{tabular}
+ \centering
+ \caption{The replacement mode switches}\label{tab:replacementswitches}
+ \begin{tabular}{rcc}
+ \toprule
+ switch & indentation? & respect verbatim? \\
+ \midrule
+ \texttt{-r} & \faCheck & \faClose \\
+ \texttt{-rv} & \faCheck & \faCheck \\
+ \texttt{-rr} & \faClose & \faClose \\
+ \bottomrule
+ \end{tabular}
\end{table}
The default value of the \texttt{replacements} field is shown in \cref{lst:replacements};
@@ -52,347 +52,356 @@
needs to begin with a \texttt{-} on its own line.
\subsection{Introduction to replacements}
- Let's explore the action of the default settings, and then we'll demonstrate the feature
- with further examples. With reference to \cref{lst:replacements}, the default action will
- replace every instance of the text \texttt{latexindent.pl} with \texttt{pl.latexindent}.
+ Let's explore the action of the default settings, and then we'll demonstrate the feature
+ with further examples. With reference to \cref{lst:replacements}, the default action will
+ replace every instance of the text \texttt{latexindent.pl} with \texttt{pl.latexindent}.
- Beginning with the code in \cref{lst:replace1} and running the command \index{switches!-r
- demonstration}
- \begin{commandshell}
+ Beginning with the code in \cref{lst:replace1} and running the command \index{switches!-r
+ demonstration}
+ \begin{commandshell}
latexindent.pl -r replace1.tex
\end{commandshell}
- gives the output given in \cref{lst:replace1-r1}.
-
- \begin{cmhtcbraster}[raster column skip=.01\linewidth]
- \cmhlistingsfromfile{demonstrations/replace1.tex}{\texttt{replace1.tex}}{lst:replace1}
- \cmhlistingsfromfile{demonstrations/replace1-r1.tex}{\texttt{replace1.tex} default}{lst:replace1-r1}
- \end{cmhtcbraster}
-
- If we don't wish to perform this replacement, then we can tweak the default settings of
- \vref{lst:replacements} by changing \texttt{lookForThis} to 0; we perform this action in
- \cref{lst:replace1-yaml}, and run the command \index{switches!-l demonstration}
- \index{switches!-r demonstration}
- \begin{commandshell}
+ gives the output given in \cref{lst:replace1-r1}.
+
+ \begin{cmhtcbraster}[raster column skip=.01\linewidth]
+ \cmhlistingsfromfile{demonstrations/replace1.tex}{\texttt{replace1.tex}}{lst:replace1}
+ \cmhlistingsfromfile{demonstrations/replace1-r1.tex}{\texttt{replace1.tex} default}{lst:replace1-r1}
+ \end{cmhtcbraster}
+
+ If we don't wish to perform this replacement, then we can tweak the default settings of
+ \vref{lst:replacements} by changing \texttt{lookForThis} to 0; we perform this action in
+ \cref{lst:replace1-yaml}, and run the command \index{switches!-l demonstration}
+ \index{switches!-r demonstration}
+ \begin{commandshell}
latexindent.pl -r replace1.tex -l=replace1.yaml
\end{commandshell}
- which gives the output in \cref{lst:replace1-mod1}.
+ which gives the output in \cref{lst:replace1-mod1}.
- \begin{cmhtcbraster}[raster column skip=.01\linewidth]
- \cmhlistingsfromfile{demonstrations/replace1-mod1.tex}{\texttt{replace1.tex} using \cref{lst:replace1-yaml}}{lst:replace1-mod1}
- \cmhlistingsfromfile[style=yaml-LST]{demonstrations/replace1.yaml}[replace-TCB]{\texttt{replace1.yaml}}{lst:replace1-yaml}
- \end{cmhtcbraster}
+ \begin{cmhtcbraster}[raster column skip=.01\linewidth]
+ \cmhlistingsfromfile{demonstrations/replace1-mod1.tex}{\texttt{replace1.tex} using \cref{lst:replace1-yaml}}{lst:replace1-mod1}
+ \cmhlistingsfromfile[style=yaml-LST]{demonstrations/replace1.yaml}[replace-TCB]{\texttt{replace1.yaml}}{lst:replace1-yaml}
+ \end{cmhtcbraster}
- Note that in \cref{lst:replace1-yaml} we have specified \texttt{amalgamate} as 0 so that
- the default replacements are overwritten.
+ Note that in \cref{lst:replace1-yaml} we have specified \texttt{amalgamate} as 0 so that
+ the default replacements are overwritten.
- We haven't yet discussed the \texttt{when} field; don't worry, we'll get to it as part of
- the discussion in what follows.
+ We haven't yet discussed the \texttt{when} field; don't worry, we'll get to it as part of
+ the discussion in what follows.
\subsection{The two types of replacements}
- There are two types of replacements:
- \begin{enumerate}
- \item \emph{string}-based replacements, which replace the string in
- \emph{this} with the string in \emph{that}.
- If you specify \texttt{this} and you do not specify \texttt{that}, then the \texttt{that}
- field will be assumed to be empty.
- \index{regular expressions!replacement switch, -r}
- \item \emph{regex}-based replacements, which use the \texttt{substitution} field.
- \end{enumerate}
- We will demonstrate both in the examples that follow.
-
- \texttt{latexindent.pl} chooses which type of replacement to make based on which fields
- have been specified; if the \texttt{this} field is specified, then it will make
- \emph{string}-based replacements, regardless of if \texttt{substitution} is present or
- not.
+ There are two types of replacements:
+ \begin{enumerate}
+ \item \emph{string}-based replacements, which replace the string in
+ \emph{this} with the string in \emph{that}.
+ If you specify \texttt{this} and you do not specify \texttt{that}, then the \texttt{that}
+ field will be assumed to be empty.
+ \index{regular expressions!replacement switch, -r}
+ \item \emph{regex}-based replacements, which use the \texttt{substitution} field.
+ \end{enumerate}
+ We will demonstrate both in the examples that follow.
+
+ \texttt{latexindent.pl} chooses which type of replacement to make based on which fields
+ have been specified; if the \texttt{this} field is specified, then it will make
+ \emph{string}-based replacements, regardless of if \texttt{substitution} is present or
+ not.
\subsection{Examples of replacements}
- \begin{example}
- We begin with code given in \cref{lst:colsep}
+ \begin{example}
+ We begin with code given in \cref{lst:colsep}
- \cmhlistingsfromfile{demonstrations/colsep.tex}{\texttt{colsep.tex}}{lst:colsep}
+ \cmhlistingsfromfile{demonstrations/colsep.tex}{\texttt{colsep.tex}}{lst:colsep}
- Let's assume that our goal is to remove both of the \texttt{arraycolsep} statements; we
- can achieve this in a few different ways.
+ Let's assume that our goal is to remove both of the \texttt{arraycolsep} statements; we
+ can achieve this in a few different ways.
- Using the YAML in \cref{lst:colsep-yaml}, and running the command \index{switches!-l
- demonstration} \index{switches!-r demonstration}
- \begin{commandshell}
+ Using the YAML in \cref{lst:colsep-yaml}, and running the command \index{switches!-l
+ demonstration} \index{switches!-r demonstration}
+ \begin{commandshell}
latexindent.pl -r colsep.tex -l=colsep.yaml
\end{commandshell}
- then we achieve the output in \cref{lst:colsep-mod0}.
- \begin{cmhtcbraster}[raster column skip=.01\linewidth]
- \cmhlistingsfromfile{demonstrations/colsep-mod0.tex}{\texttt{colsep.tex} using \cref{lst:colsep}}{lst:colsep-mod0}
- \cmhlistingsfromfile[style=yaml-LST]{demonstrations/colsep.yaml}[replace-TCB]{\texttt{colsep.yaml}}{lst:colsep-yaml}
- \end{cmhtcbraster}
- Note that in \cref{lst:colsep-yaml}, we have specified \emph{two} separate fields, each with their own `\emph{this}' field;
- furthermore, for both of the separate fields, we have not specified `\texttt{that}', so the \texttt{that} field
- is assumed to be blank by \texttt{latexindent.pl};
-
- We can make the YAML in \cref{lst:colsep-yaml} more concise by exploring the
- \texttt{substitution} field. Using the settings in \cref{lst:colsep1} and running the
- command \index{switches!-l demonstration} \index{switches!-r demonstration}
- \begin{commandshell}
+ then we achieve the output in \cref{lst:colsep-mod0}.
+ \begin{cmhtcbraster}[raster column skip=.01\linewidth]
+ \cmhlistingsfromfile{demonstrations/colsep-mod0.tex}{\texttt{colsep.tex} using \cref{lst:colsep}}{lst:colsep-mod0}
+ \cmhlistingsfromfile[style=yaml-LST]{demonstrations/colsep.yaml}[replace-TCB]{\texttt{colsep.yaml}}{lst:colsep-yaml}
+ \end{cmhtcbraster}
+ Note that in \cref{lst:colsep-yaml}, we have specified \emph{two} separate fields, each
+ with their own `\emph{this}' field; furthermore, for both of the separate fields, we have
+ not specified `\texttt{that}', so the \texttt{that} field is assumed to be blank by
+ \texttt{latexindent.pl};
+
+ We can make the YAML in \cref{lst:colsep-yaml} more concise by exploring the
+ \texttt{substitution} field. Using the settings in \cref{lst:colsep1} and running the
+ command \index{switches!-l demonstration} \index{switches!-r demonstration}
+ \begin{commandshell}
latexindent.pl -r colsep.tex -l=colsep1.yaml
\end{commandshell}
- then we achieve the output in \cref{lst:colsep-mod1}. \index{regular
- expressions!substitution field, arraycolsep} \index{regular expressions!at least one +}
- \begin{cmhtcbraster}[raster column skip=.01\linewidth,
- raster force size=false,
- raster column 1/.style={add to width=-.1\textwidth}]
- \cmhlistingsfromfile{demonstrations/colsep-mod1.tex}{\texttt{colsep.tex} using \cref{lst:colsep1}}{lst:colsep-mod1}
- \cmhlistingsfromfile[style=yaml-LST]{demonstrations/colsep1.yaml}[replace-TCB,width=0.6\textwidth]{\texttt{colsep1.yaml}}{lst:colsep1}
- \end{cmhtcbraster}
-
- The code given in \cref{lst:colsep1} is an example of a \emph{regular expression}, which
- we may abbreviate to \emph{regex} in what follows. This manual is not intended to be a
- tutorial on regular expressions; you might like to read, for example,
- \cite{masteringregexp} for a detailed covering of the topic. With reference to
- \cref{lst:colsep1}, we do note the following:
- \begin{itemize}
- \item the general form of the \texttt{substitution} field is
- \lstinline!s/regex/replacement/modifiers!. You can place any regular expression you like
- within this;
- \item we have `escaped' the backslash by using \lstinline!\\!
- \item we have used \lstinline!\d+! to represent \emph{at least} one digit
- \item the \texttt{s} \emph{modifier} (in the \texttt{sg} at the end of the line) instructs
- \texttt{latexindent.pl} to treat your file as one single line;
- \item the \texttt{g} \emph{modifier} (in the \texttt{sg} at the end of the line) instructs
- \texttt{latexindent.pl} to make the substitution \emph{globally} throughout your file;
- you might try removing the \texttt{g} modifier from \cref{lst:colsep1} and observing the
- difference in output.
- \end{itemize}
- You might like to see \href{https://perldoc.perl.org/perlre.html#Modifiers}{https://perldoc.perl.org/perlre.html\#Modifiers}
- for details of modifiers; in general, I recommend starting with the \texttt{sg} modifiers for this feature.
- \end{example}
-
- \begin{example}
- We'll keep working with the file in \vref{lst:colsep} for this example.
-
- Using the YAML in \cref{lst:multi-line}, and running the command \index{switches!-l
- demonstration} \index{switches!-r demonstration}
- \begin{commandshell}
+ then we achieve the output in \cref{lst:colsep-mod1}. \index{regular
+ expressions!substitution field, arraycolsep} \index{regular expressions!at least one +}
+ \begin{cmhtcbraster}[raster column skip=.01\linewidth,
+ raster force size=false,
+ raster column 1/.style={add to width=-.1\textwidth}]
+ \cmhlistingsfromfile{demonstrations/colsep-mod1.tex}{\texttt{colsep.tex} using \cref{lst:colsep1}}{lst:colsep-mod1}
+ \cmhlistingsfromfile[style=yaml-LST]{demonstrations/colsep1.yaml}[replace-TCB,width=0.6\textwidth]{\texttt{colsep1.yaml}}{lst:colsep1}
+ \end{cmhtcbraster}
+
+ The code given in \cref{lst:colsep1} is an example of a \emph{regular expression}, which
+ we may abbreviate to \emph{regex} in what follows. This manual is not intended to be a
+ tutorial on regular expressions; you might like to read, for example,
+ \cite{masteringregexp} for a detailed covering of the topic. With reference to
+ \cref{lst:colsep1}, we do note the following:
+ \begin{itemize}
+ \item the general form of the \texttt{substitution} field is
+ \lstinline!s/regex/replacement/modifiers!. You can place any regular expression you like
+ within this;
+ \item we have `escaped' the backslash by using \lstinline!\\!
+ \item we have used \lstinline!\d+! to represent \emph{at least} one digit
+ \item the \texttt{s} \emph{modifier} (in the \texttt{sg} at the end of the line) instructs
+ \texttt{latexindent.pl} to treat your file as one single line;
+ \item the \texttt{g} \emph{modifier} (in the \texttt{sg} at the end of the line) instructs
+ \texttt{latexindent.pl} to make the substitution \emph{globally} throughout your file;
+ you might try removing the \texttt{g} modifier from \cref{lst:colsep1} and observing the
+ difference in output.
+ \end{itemize}
+ You might like to see
+ \href{https://perldoc.perl.org/perlre.html#Modifiers}{https://perldoc.perl.org/perlre.html\#Modifiers}
+ for details of modifiers; in general, I recommend starting with the \texttt{sg} modifiers
+ for this feature.
+ \end{example}
+
+ \begin{example}
+ We'll keep working with the file in \vref{lst:colsep} for this example.
+
+ Using the YAML in \cref{lst:multi-line}, and running the command \index{switches!-l
+ demonstration} \index{switches!-r demonstration}
+ \begin{commandshell}
latexindent.pl -r colsep.tex -l=multi-line.yaml
\end{commandshell}
- then we achieve the output in \cref{lst:colsep-mod2}.
- \begin{cmhtcbraster}[raster column skip=.01\linewidth]
- \cmhlistingsfromfile{demonstrations/colsep-mod2.tex}{\texttt{colsep.tex} using \cref{lst:multi-line}}{lst:colsep-mod2}
- \cmhlistingsfromfile[style=yaml-LST]{demonstrations/multi-line.yaml}[replace-TCB]{\texttt{multi-line.yaml}}{lst:multi-line}
- \end{cmhtcbraster}
- With reference to \cref{lst:multi-line}, we have specified a \emph{multi-line} version of \texttt{this} by employing the \emph{literal}
- YAML style \lstinline!|-!. See, for example, \href{https://stackoverflow.com/questions/3790454/in-yaml-how-do-i-break-a-string-over-multiple-lines}{https://stackoverflow.com/questions/3790454/in-yaml-how-do-i-break-a-string-over-multiple-lines}
- for further options, all of which can be used in your YAML file.
-
- This is a natural point to explore the \texttt{when} field, specified in
- \vref{lst:replacements}. This field can take two values: \emph{before} and \emph{after},
- which respectively instruct \texttt{latexindent.pl} to perform the replacements
- \emph{before} indentation or \emph{after} it. The default value is \texttt{before}.
-
- Using the YAML in \cref{lst:multi-line1}, and running the command \index{switches!-l
- demonstration} \index{switches!-r demonstration}
- \begin{commandshell}
+ then we achieve the output in \cref{lst:colsep-mod2}.
+ \begin{cmhtcbraster}[raster column skip=.01\linewidth]
+ \cmhlistingsfromfile{demonstrations/colsep-mod2.tex}{\texttt{colsep.tex} using \cref{lst:multi-line}}{lst:colsep-mod2}
+ \cmhlistingsfromfile[style=yaml-LST]{demonstrations/multi-line.yaml}[replace-TCB]{\texttt{multi-line.yaml}}{lst:multi-line}
+ \end{cmhtcbraster}
+ With reference to \cref{lst:multi-line}, we have specified a \emph{multi-line} version of
+ \texttt{this} by employing the \emph{literal} YAML style \lstinline!|-!. See, for
+ example,
+ \href{https://stackoverflow.com/questions/3790454/in-yaml-how-do-i-break-a-string-over-multiple-lines}{https://stackoverflow.com/questions/3790454/in-yaml-how-do-i-break-a-string-over-multiple-lines}
+ for further options, all of which can be used in your YAML file.
+
+ This is a natural point to explore the \texttt{when} field, specified in
+ \vref{lst:replacements}. This field can take two values: \emph{before} and \emph{after},
+ which respectively instruct \texttt{latexindent.pl} to perform the replacements
+ \emph{before} indentation or \emph{after} it. The default value is \texttt{before}.
+
+ Using the YAML in \cref{lst:multi-line1}, and running the command \index{switches!-l
+ demonstration} \index{switches!-r demonstration}
+ \begin{commandshell}
latexindent.pl -r colsep.tex -l=multi-line1.yaml
\end{commandshell}
- then we achieve the output in \cref{lst:colsep-mod3}.
- \begin{cmhtcbraster}[raster column skip=.01\linewidth]
- \cmhlistingsfromfile{demonstrations/colsep-mod3.tex}{\texttt{colsep.tex} using \cref{lst:multi-line1}}{lst:colsep-mod3}
- \cmhlistingsfromfile[style=yaml-LST]{demonstrations/multi-line1.yaml}[replace-TCB]{\texttt{multi-line1.yaml}}{lst:multi-line1}
- \end{cmhtcbraster}
- We note that, because we have specified \texttt{when: after}, that \texttt{latexindent.pl} has not found the string specified
- in \cref{lst:multi-line1} within the file in \vref{lst:colsep}. As it has looked for the string within \cref{lst:multi-line1} \emph{after} the indentation has been performed. After
- indentation, the string as written in \cref{lst:multi-line1} is no longer part of the file, and has therefore not been replaced.
-
- As a final note on this example, if you use the \texttt{-rr} switch, as follows,
- \index{switches!-l demonstration} \index{switches!-rr demonstration}
- \begin{commandshell}
+ then we achieve the output in \cref{lst:colsep-mod3}.
+ \begin{cmhtcbraster}[raster column skip=.01\linewidth]
+ \cmhlistingsfromfile{demonstrations/colsep-mod3.tex}{\texttt{colsep.tex} using \cref{lst:multi-line1}}{lst:colsep-mod3}
+ \cmhlistingsfromfile[style=yaml-LST]{demonstrations/multi-line1.yaml}[replace-TCB]{\texttt{multi-line1.yaml}}{lst:multi-line1}
+ \end{cmhtcbraster}
+ We note that, because we have specified \texttt{when: after}, that
+ \texttt{latexindent.pl} has not found the string specified in \cref{lst:multi-line1}
+ within the file in \vref{lst:colsep}. As it has looked for the string within
+ \cref{lst:multi-line1} \emph{after} the indentation has been performed. After
+ indentation, the string as written in \cref{lst:multi-line1} is no longer part of the
+ file, and has therefore not been replaced.
+
+ As a final note on this example, if you use the \texttt{-rr} switch, as follows,
+ \index{switches!-l demonstration} \index{switches!-rr demonstration}
+ \begin{commandshell}
latexindent.pl -rr colsep.tex -l=multi-line1.yaml
\end{commandshell}
- then the \texttt{when} field is ignored, no indentation is done, and the output is as in
- \cref{lst:colsep-mod2}.
- \end{example}
+ then the \texttt{when} field is ignored, no indentation is done, and the output is as in
+ \cref{lst:colsep-mod2}.
+ \end{example}
- \begin{example}
- An important part of the substitution routine is in \emph{capture groups}.
+ \begin{example}
+ An important part of the substitution routine is in \emph{capture groups}.
- Assuming that we start with the code in \cref{lst:displaymath}, let's assume that our
- goal is to replace each occurrence of \lstinline!$$...$$! with
- \lstinline!\begin{equation*}...\end{equation*}!. This example is partly motivated by
- \href{https://tex.stackexchange.com/questions/242150/good-looking-latex-code}{tex
- stackexchange question 242150}.
+ Assuming that we start with the code in \cref{lst:displaymath}, let's assume that our
+ goal is to replace each occurrence of \lstinline!$$...$$! with
+ \lstinline!\begin{equation*}...\end{equation*}!. This example is partly motivated by
+ \href{https://tex.stackexchange.com/questions/242150/good-looking-latex-code}{tex
+ stackexchange question 242150}.
- \cmhlistingsfromfile{demonstrations/displaymath.tex}{\texttt{displaymath.tex}}{lst:displaymath}
+ \cmhlistingsfromfile{demonstrations/displaymath.tex}{\texttt{displaymath.tex}}{lst:displaymath}
- We use the settings in \cref{lst:displaymath1} and run the command \index{switches!-l
- demonstration} \index{switches!-r demonstration}
- \begin{commandshell}
+ We use the settings in \cref{lst:displaymath1} and run the command \index{switches!-l
+ demonstration} \index{switches!-r demonstration}
+ \begin{commandshell}
latexindent.pl -r displaymath.tex -l=displaymath1.yaml
\end{commandshell}
- to receive the output given in \cref{lst:displaymath-mod1}. \index{regular
- expressions!substitution field, equation}
-
- \begin{cmhtcbraster}[raster left skip=-3.75cm,
- raster right skip=-2cm,]
- \cmhlistingsfromfile{demonstrations/displaymath-mod1.tex}{\texttt{displaymath.tex} using \cref{lst:displaymath1}}{lst:displaymath-mod1}
- \cmhlistingsfromfile[style=yaml-LST]{demonstrations/displaymath1.yaml}[replace-TCB]{\texttt{displaymath1.yaml}}{lst:displaymath1}
- \end{cmhtcbraster}
-
- A few notes about \cref{lst:displaymath1}:
- \begin{enumerate}
- \item we have used the \texttt{x} modifier, which allows us to have white space within the
- regex;
- \item we have used a capture group, \lstinline!(.*?)! which captures the content between the
- \lstinline!$$...$$! into the special variable, \lstinline!$1!;
- \item we have used the content of the capture group, \lstinline!$1!, in the replacement text.
- \end{enumerate}
- See \href{https://perldoc.perl.org/perlre.html#Capture-groups}{https://perldoc.perl.org/perlre.html\#Capture-groups} for a discussion
- of capture groups.
-
- The features of the replacement switches can, of course, be combined with others from the
- toolkit of \texttt{latexindent.pl}. For example, we can combine the poly-switches of
- \vref{sec:poly-switches}, which we do in \cref{lst:equation}; upon running the command
- \index{switches!-l demonstration} \index{switches!-m demonstration} \index{switches!-r
- demonstration}
- \begin{commandshell}
+ to receive the output given in \cref{lst:displaymath-mod1}. \index{regular
+ expressions!substitution field, equation}
+
+ \begin{cmhtcbraster}[raster left skip=-3.75cm,
+ raster right skip=-2cm,]
+ \cmhlistingsfromfile{demonstrations/displaymath-mod1.tex}{\texttt{displaymath.tex} using \cref{lst:displaymath1}}{lst:displaymath-mod1}
+ \cmhlistingsfromfile[style=yaml-LST]{demonstrations/displaymath1.yaml}[replace-TCB]{\texttt{displaymath1.yaml}}{lst:displaymath1}
+ \end{cmhtcbraster}
+
+ A few notes about \cref{lst:displaymath1}:
+ \begin{enumerate}
+ \item we have used the \texttt{x} modifier, which allows us to have white space within the
+ regex;
+ \item we have used a capture group, \lstinline!(.*?)! which captures the content between the
+ \lstinline!$$...$$! into the special variable, \lstinline!$1!;
+ \item we have used the content of the capture group, \lstinline!$1!, in the replacement text.
+ \end{enumerate}
+ See
+ \href{https://perldoc.perl.org/perlre.html#Capture-groups}{https://perldoc.perl.org/perlre.html\#Capture-groups}
+ for a discussion of capture groups.
+
+ The features of the replacement switches can, of course, be combined with others from the
+ toolkit of \texttt{latexindent.pl}. For example, we can combine the poly-switches of
+ \vref{sec:poly-switches}, which we do in \cref{lst:equation}; upon running the command
+ \index{switches!-l demonstration} \index{switches!-m demonstration} \index{switches!-r
+ demonstration}
+ \begin{commandshell}
latexindent.pl -r -m displaymath.tex -l=displaymath1.yaml,equation.yaml
\end{commandshell}
- then we receive the output in \cref{lst:displaymath-mod2}.
-
- \begin{cmhtcbraster}[
- raster force size=false,
- raster column 1/.style={add to width=-.1\textwidth},
- raster column skip=.06\linewidth]
- \cmhlistingsfromfile{demonstrations/displaymath-mod2.tex}{\texttt{displaymath.tex} using \cref{lst:displaymath1,lst:equation}}{lst:displaymath-mod2}
- \cmhlistingsfromfile[style=yaml-LST]{demonstrations/equation.yaml}[MLB-TCB,width=0.55\textwidth]{\texttt{equation.yaml}}{lst:equation}
- \end{cmhtcbraster}
- \end{example}
-
- \begin{example}
- This example is motivated by
- \href{https://tex.stackexchange.com/questions/490086/bring-several-lines-together-to-fill-blank-spaces-in-texmaker}{tex
- stackexchange question 490086}. We begin with the code in \cref{lst:phrase}.
-
- \cmhlistingsfromfile{demonstrations/phrase.tex}{\texttt{phrase.tex}}{lst:phrase}
-
- Our goal is to make the spacing uniform between the phrases. To achieve this, we employ
- the settings in \cref{lst:hspace}, and run the command \index{switches!-l demonstration}
- \index{switches!-r demonstration}
- \begin{commandshell}
+ then we receive the output in \cref{lst:displaymath-mod2}.
+
+ \begin{cmhtcbraster}[
+ raster force size=false,
+ raster column 1/.style={add to width=-.1\textwidth},
+ raster column skip=.06\linewidth]
+ \cmhlistingsfromfile{demonstrations/displaymath-mod2.tex}{\texttt{displaymath.tex} using \cref{lst:displaymath1,lst:equation}}{lst:displaymath-mod2}
+ \cmhlistingsfromfile[style=yaml-LST]{demonstrations/equation.yaml}[MLB-TCB,width=0.55\textwidth]{\texttt{equation.yaml}}{lst:equation}
+ \end{cmhtcbraster}
+ \end{example}
+
+ \begin{example}
+ This example is motivated by
+ \href{https://tex.stackexchange.com/questions/490086/bring-several-lines-together-to-fill-blank-spaces-in-texmaker}{tex
+ stackexchange question 490086}. We begin with the code in \cref{lst:phrase}.
+
+ \cmhlistingsfromfile{demonstrations/phrase.tex}{\texttt{phrase.tex}}{lst:phrase}
+
+ Our goal is to make the spacing uniform between the phrases. To achieve this, we employ
+ the settings in \cref{lst:hspace}, and run the command \index{switches!-l demonstration}
+ \index{switches!-r demonstration}
+ \begin{commandshell}
latexindent.pl -r phrase.tex -l=hspace.yaml
\end{commandshell}
- which gives the output in \cref{lst:phrase-mod1}. \index{regular expressions!at least one
- +} \index{regular expressions!horizontal space \textbackslash{h}}
+ which gives the output in \cref{lst:phrase-mod1}. \index{regular expressions!at least one
+ +} \index{regular expressions!horizontal space \textbackslash{h}}
- \begin{cmhtcbraster}
- \cmhlistingsfromfile{demonstrations/phrase-mod1.tex}{\texttt{phrase.tex} using \cref{lst:hspace}}{lst:phrase-mod1}
- \cmhlistingsfromfile[style=yaml-LST]{demonstrations/hspace.yaml}[replace-TCB]{\texttt{hspace.yaml}}{lst:hspace}
- \end{cmhtcbraster}
+ \begin{cmhtcbraster}
+ \cmhlistingsfromfile{demonstrations/phrase-mod1.tex}{\texttt{phrase.tex} using \cref{lst:hspace}}{lst:phrase-mod1}
+ \cmhlistingsfromfile[style=yaml-LST]{demonstrations/hspace.yaml}[replace-TCB]{\texttt{hspace.yaml}}{lst:hspace}
+ \end{cmhtcbraster}
- The \lstinline!\h+! setting in \cref{lst:hspace} say to replace \emph{at least one
- horizontal space} with a single space.
- \end{example}
+ The \lstinline!\h+! setting in \cref{lst:hspace} say to replace \emph{at least one
+ horizontal space} with a single space.
+ \end{example}
- \begin{example}
- We begin with the code in \cref{lst:references}.
+ \begin{example}
+ We begin with the code in \cref{lst:references}.
- \cmhlistingsfromfile{demonstrations/references.tex}{\texttt{references.tex}}{lst:references}
+ \cmhlistingsfromfile{demonstrations/references.tex}{\texttt{references.tex}}{lst:references}
- Our goal is to change each reference so that both the text and the reference are
- contained within one hyperlink. We achieve this by employing \cref{lst:reference} and
- running the command \index{switches!-l demonstration} \index{switches!-r demonstration}
- \begin{commandshell}
+ Our goal is to change each reference so that both the text and the reference are
+ contained within one hyperlink. We achieve this by employing \cref{lst:reference} and
+ running the command \index{switches!-l demonstration} \index{switches!-r demonstration}
+ \begin{commandshell}
latexindent.pl -r references.tex -l=reference.yaml
\end{commandshell}
- which gives the output in \cref{lst:references-mod1}. \index{regular
- expressions!horizontal space \textbackslash{h}}
+ which gives the output in \cref{lst:references-mod1}. \index{regular
+ expressions!horizontal space \textbackslash{h}}
- \cmhlistingsfromfile{demonstrations/references-mod1.tex}{\texttt{references.tex} using \cref{lst:reference}}{lst:references-mod1}
+ \cmhlistingsfromfile{demonstrations/references-mod1.tex}{\texttt{references.tex} using \cref{lst:reference}}{lst:references-mod1}
- \cmhlistingsfromfile[style=yaml-LST]{demonstrations/reference.yaml}[replace-TCB]{\texttt{reference.yaml}}{lst:reference}
+ \cmhlistingsfromfile[style=yaml-LST]{demonstrations/reference.yaml}[replace-TCB]{\texttt{reference.yaml}}{lst:reference}
- Referencing \cref{lst:reference}, the \lstinline!|! means \emph{or}, we have used
- \emph{capture groups}, together with an example of an \emph{optional} pattern,
- \lstinline!(?:eq)?!.
- \end{example}
+ Referencing \cref{lst:reference}, the \lstinline!|! means \emph{or}, we have used
+ \emph{capture groups}, together with an example of an \emph{optional} pattern,
+ \lstinline!(?:eq)?!.
+ \end{example}
- \begin{example}
- Let's explore the three replacement mode switches (see \vref{tab:replacementswitches}) in
- the context of an example that contains a verbatim code block, \cref{lst:verb1}; we will
- use the settings in \cref{lst:verbatim1-yaml}.
+ \begin{example}
+ Let's explore the three replacement mode switches (see \vref{tab:replacementswitches}) in
+ the context of an example that contains a verbatim code block, \cref{lst:verb1}; we will
+ use the settings in \cref{lst:verbatim1-yaml}.
- \begin{cmhtcbraster}
- \cmhlistingsfromfile{demonstrations/verb1.tex}{\texttt{verb1.tex}}{lst:verb1}
- \cmhlistingsfromfile[style=yaml-LST]{demonstrations/verbatim1.yaml}[replace-TCB]{\texttt{verbatim1.yaml}}{lst:verbatim1-yaml}
- \end{cmhtcbraster}
+ \begin{cmhtcbraster}
+ \cmhlistingsfromfile{demonstrations/verb1.tex}{\texttt{verb1.tex}}{lst:verb1}
+ \cmhlistingsfromfile[style=yaml-LST]{demonstrations/verbatim1.yaml}[replace-TCB]{\texttt{verbatim1.yaml}}{lst:verbatim1-yaml}
+ \end{cmhtcbraster}
- Upon running the following commands, \index{verbatim!comparison with -r and -rr switches}
- \index{switches!-l demonstration} \index{switches!-o demonstration} \index{switches!-r
- demonstration} \index{switches!-rv demonstration} \index{switches!-rr demonstration}
- \begin{commandshell}
+ Upon running the following commands, \index{verbatim!comparison with -r and -rr switches}
+ \index{switches!-l demonstration} \index{switches!-o demonstration} \index{switches!-r
+ demonstration} \index{switches!-rv demonstration} \index{switches!-rr demonstration}
+ \begin{commandshell}
latexindent.pl -r verb1.tex -l=verbatim1.yaml -o=+mod1
latexindent.pl -rv verb1.tex -l=verbatim1.yaml -o=+-rv-mod1
latexindent.pl -rr verb1.tex -l=verbatim1.yaml -o=+-rr-mod1
\end{commandshell}
- we receive the respective output in \crefrange{lst:verb1-mod1}{lst:verb1-rr-mod1}
-
- \begin{cmhtcbraster}[raster columns=3,
- raster left skip=-3.75cm,
- raster right skip=-2cm,]
- \cmhlistingsfromfile{demonstrations/verb1-mod1.tex}{\texttt{verb1-mod1.tex}}{lst:verb1-mod1}
- \cmhlistingsfromfile{demonstrations/verb1-rv-mod1.tex}{\texttt{verb1-rv-mod1.tex}}{lst:verb1-rv-mod1}
- \cmhlistingsfromfile{demonstrations/verb1-rr-mod1.tex}{\texttt{verb1-rr-mod1.tex}}{lst:verb1-rr-mod1}
- \end{cmhtcbraster}
- \end{example}
-
- We note that:
- \begin{enumerate}
- \item in \cref{lst:verb1-mod1} indentation has been performed, and that the replacements
- specified in \cref{lst:verbatim1-yaml} have been performed, even within the verbatim code
- block;
- \item in \cref{lst:verb1-rv-mod1} indentation has been performed, but that the replacements
- have \emph{not} been performed within the verbatim environment, because the \texttt{rv}
- switch is active;
- \item in \cref{lst:verb1-rr-mod1} indentation has \emph{not} been performed, but that
- replacements have been performed, not respecting the verbatim code block.
- \end{enumerate}
- See the summary within \vref{tab:replacementswitches}.
-
- \begin{example}
- Let's explore the \texttt{amalgamate} field from \vref{lst:replacements} in the context
- of the file specified in \cref{lst:amalg1}.
-
- \cmhlistingsfromfile{demonstrations/amalg1.tex}{\texttt{amalg1.tex}}{lst:amalg1}
-
- Let's consider the YAML files given in \crefrange{lst:amalg1-yaml}{lst:amalg3-yaml}.
-
- \begin{cmhtcbraster}[raster columns=3,
- raster left skip=-3.75cm,
- raster right skip=-2cm,]
- \cmhlistingsfromfile[style=yaml-LST]{demonstrations/amalg1-yaml.yaml}[replace-TCB]{\texttt{amalg1-yaml.yaml}}{lst:amalg1-yaml}
- \cmhlistingsfromfile[style=yaml-LST]{demonstrations/amalg2-yaml.yaml}[replace-TCB]{\texttt{amalg2-yaml.yaml}}{lst:amalg2-yaml}
- \cmhlistingsfromfile[style=yaml-LST]{demonstrations/amalg3-yaml.yaml}[replace-TCB]{\texttt{amalg3-yaml.yaml}}{lst:amalg3-yaml}
- \end{cmhtcbraster}
-
- Upon running the following commands, \index{switches!-l demonstration} \index{switches!-r
- demonstration}
- \begin{commandshell}
+ we receive the respective output in \crefrange{lst:verb1-mod1}{lst:verb1-rr-mod1}
+
+ \begin{cmhtcbraster}[raster columns=3,
+ raster left skip=-3.75cm,
+ raster right skip=-2cm,]
+ \cmhlistingsfromfile{demonstrations/verb1-mod1.tex}{\texttt{verb1-mod1.tex}}{lst:verb1-mod1}
+ \cmhlistingsfromfile{demonstrations/verb1-rv-mod1.tex}{\texttt{verb1-rv-mod1.tex}}{lst:verb1-rv-mod1}
+ \cmhlistingsfromfile{demonstrations/verb1-rr-mod1.tex}{\texttt{verb1-rr-mod1.tex}}{lst:verb1-rr-mod1}
+ \end{cmhtcbraster}
+ \end{example}
+
+ We note that:
+ \begin{enumerate}
+ \item in \cref{lst:verb1-mod1} indentation has been performed, and that the replacements
+ specified in \cref{lst:verbatim1-yaml} have been performed, even within the verbatim code
+ block;
+ \item in \cref{lst:verb1-rv-mod1} indentation has been performed, but that the replacements
+ have \emph{not} been performed within the verbatim environment, because the \texttt{rv}
+ switch is active;
+ \item in \cref{lst:verb1-rr-mod1} indentation has \emph{not} been performed, but that
+ replacements have been performed, not respecting the verbatim code block.
+ \end{enumerate}
+ See the summary within \vref{tab:replacementswitches}.
+
+ \begin{example}
+ Let's explore the \texttt{amalgamate} field from \vref{lst:replacements} in the context
+ of the file specified in \cref{lst:amalg1}.
+
+ \cmhlistingsfromfile{demonstrations/amalg1.tex}{\texttt{amalg1.tex}}{lst:amalg1}
+
+ Let's consider the YAML files given in \crefrange{lst:amalg1-yaml}{lst:amalg3-yaml}.
+
+ \begin{cmhtcbraster}[raster columns=3,
+ raster left skip=-3.75cm,
+ raster right skip=-2cm,]
+ \cmhlistingsfromfile[style=yaml-LST]{demonstrations/amalg1-yaml.yaml}[replace-TCB]{\texttt{amalg1-yaml.yaml}}{lst:amalg1-yaml}
+ \cmhlistingsfromfile[style=yaml-LST]{demonstrations/amalg2-yaml.yaml}[replace-TCB]{\texttt{amalg2-yaml.yaml}}{lst:amalg2-yaml}
+ \cmhlistingsfromfile[style=yaml-LST]{demonstrations/amalg3-yaml.yaml}[replace-TCB]{\texttt{amalg3-yaml.yaml}}{lst:amalg3-yaml}
+ \end{cmhtcbraster}
+
+ Upon running the following commands, \index{switches!-l demonstration} \index{switches!-r
+ demonstration}
+ \begin{commandshell}
latexindent.pl -r amalg1.tex -l=amalg1-yaml
latexindent.pl -r amalg1.tex -l=amalg1-yaml,amalg2-yaml
latexindent.pl -r amalg1.tex -l=amalg1-yaml,amalg2-yaml,amalg3-yaml
\end{commandshell}
- we receive the respective output in \crefrange{lst:amalg1-mod1}{lst:amalg1-mod123}.
-
- \begin{cmhtcbraster}[raster columns=3,
- raster left skip=-3.75cm,
- raster right skip=-2cm,]
- \cmhlistingsfromfile{demonstrations/amalg1-mod1.tex}{\texttt{amalg1.tex} using \cref{lst:amalg1-yaml}}{lst:amalg1-mod1}
- \cmhlistingsfromfile{demonstrations/amalg1-mod12.tex}{\texttt{amalg1.tex} using \cref{lst:amalg1-yaml,lst:amalg2-yaml}}{lst:amalg1-mod12}
- \cmhlistingsfromfile{demonstrations/amalg1-mod123.tex}{\texttt{amalg1.tex} using \cref{lst:amalg1-yaml,lst:amalg2-yaml,lst:amalg3-yaml}}{lst:amalg1-mod123}
- \end{cmhtcbraster}
- We note that:
- \begin{enumerate}
- \item in \cref{lst:amalg1-mod1} the replacements from \cref{lst:amalg1-yaml} have been used;
- \item in \cref{lst:amalg1-mod12} the replacements from \cref{lst:amalg1-yaml,lst:amalg2-yaml}
- have \emph{both} been used, because the default value of \texttt{amalgamate} is 1;
- \item in \cref{lst:amalg1-mod123} \emph{only} the replacements from \cref{lst:amalg3-yaml} have
- been used, because the value of \texttt{amalgamate} has been set to 0.
- \end{enumerate}
- \end{example}
+ we receive the respective output in \crefrange{lst:amalg1-mod1}{lst:amalg1-mod123}.
+
+ \begin{cmhtcbraster}[raster columns=3,
+ raster left skip=-3.75cm,
+ raster right skip=-2cm,]
+ \cmhlistingsfromfile{demonstrations/amalg1-mod1.tex}{\texttt{amalg1.tex} using \cref{lst:amalg1-yaml}}{lst:amalg1-mod1}
+ \cmhlistingsfromfile{demonstrations/amalg1-mod12.tex}{\texttt{amalg1.tex} using \cref{lst:amalg1-yaml,lst:amalg2-yaml}}{lst:amalg1-mod12}
+ \cmhlistingsfromfile{demonstrations/amalg1-mod123.tex}{\texttt{amalg1.tex} using \cref{lst:amalg1-yaml,lst:amalg2-yaml,lst:amalg3-yaml}}{lst:amalg1-mod123}
+ \end{cmhtcbraster}
+ We note that:
+ \begin{enumerate}
+ \item in \cref{lst:amalg1-mod1} the replacements from \cref{lst:amalg1-yaml} have been used;
+ \item in \cref{lst:amalg1-mod12} the replacements from \cref{lst:amalg1-yaml,lst:amalg2-yaml}
+ have \emph{both} been used, because the default value of \texttt{amalgamate} is 1;
+ \item in \cref{lst:amalg1-mod123} \emph{only} the replacements from \cref{lst:amalg3-yaml} have
+ been used, because the value of \texttt{amalgamate} has been set to 0.
+ \end{enumerate}
+ \end{example}