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.tex107
1 files changed, 52 insertions, 55 deletions
diff --git a/support/latexindent/documentation/sec-replacements.tex b/support/latexindent/documentation/sec-replacements.tex
index 4362f34720..a31ad0721b 100644
--- a/support/latexindent/documentation/sec-replacements.tex
+++ b/support/latexindent/documentation/sec-replacements.tex
@@ -10,16 +10,16 @@
\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}.
+ 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
@@ -35,23 +35,22 @@
\end{tabular}
\end{table}
- The default value of the \texttt{replacements} field is shown in
- \cref{lst:replacements}; as with all of the other fields, you are encouraged to customise
- and change this as you see fit. The options in this field will \emph{only} be
- considered if the \texttt{-r}, \texttt{-rv} or
- \texttt{-rr} switches are active; when discussing YAML settings related to the
- replacement-mode switches, we will use the style given in \cref{lst:replacements}.
+ The default value of the \texttt{replacements} field is shown in \cref{lst:replacements};
+ as with all of the other fields, you are encouraged to customise and change this as you
+ see fit. The options in this field will \emph{only} be considered if the \texttt{-r},
+ \texttt{-rv} or \texttt{-rr} switches are active; when discussing YAML settings related
+ to the replacement-mode switches, we will use the style given in \cref{lst:replacements}.
\cmhlistingsfromfile[style=replacements]*{../defaultSettings.yaml}[width=0.95\linewidth,before=\centering,replace-TCB]{\texttt{replacements}}{lst:replacements}
- The first entry within the \texttt{replacements} field is \texttt{amalgamate}, and
- is \emph{optional}; by default it is set to 1, so that replacements will be
- amalgamated from each settings file that you specify. As you'll see in the demonstrations
- that follow, there is no need to specify this field.
+ The first entry within the \texttt{replacements} field is \texttt{amalgamate}, and is
+ \emph{optional}; by default it is set to 1, so that replacements will be amalgamated from
+ each settings file that you specify. As you'll see in the demonstrations that follow,
+ there is no need to specify this field.
You'll notice that, by default, there is only \emph{one} entry in the
- \texttt{replacements} field, but it can take as many entries as you would like; each
- one needs to begin with a \texttt{-} on its own line.
+ \texttt{replacements} field, but it can take as many entries as you would like; each one
+ 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
@@ -71,8 +70,8 @@ latexindent.pl -r replace1.tex
\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
+ \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}
@@ -85,19 +84,19 @@ latexindent.pl -r replace1.tex -l=replace1.yaml
\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.
+ 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}
@@ -105,8 +104,8 @@ latexindent.pl -r replace1.tex -l=replace1.yaml
\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.
+ \emph{string}-based replacements, regardless of if \texttt{substitution} is present or
+ not.
\subsection{Examples of replacements}
\begin{example}
@@ -150,19 +149,20 @@ latexindent.pl -r colsep.tex -l=colsep1.yaml
\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
+ 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 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
+ \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}
@@ -241,12 +241,11 @@ latexindent.pl -r displaymath.tex -l=displaymath1.yaml
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.
+ \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.
@@ -355,11 +354,11 @@ latexindent.pl -rr verb1.tex -l=verbatim1.yaml -o=+-rr-mod1
\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.
+ \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}.
@@ -399,11 +398,9 @@ latexindent.pl -r amalg1.tex -l=amalg1-yaml,amalg2-yaml,amalg3-yaml
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.
+ \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}