latexindent (13jul19)

git-svn-id: svn://tug.org/texlive/trunk@51635 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 372 insertions, 0 deletions

diff --git a/Master/texmf-dist/doc/support/latexindent/sec-replacements.tex b/Master/texmf-dist/doc/support/latexindent/sec-replacements.tex
new file mode 100644
index 00000000000..6bc7223d4d1
--- /dev/null
+++ b/Master/texmf-dist/doc/support/latexindent/sec-replacements.tex
@@ -0,0 +1,372 @@
+% arara: pdflatex: {shell: yes, files: [latexindent]}
+\section{The -r, -rv and -rr switches}\label{sec:replacements}
+ \fancyhead[R]{\bfseries\thepage%
+	 \tikz[remember picture,overlay] {
+		 \node at (1,0){\includegraphics{logo-bw}}; }
+ }
+
+ You can instruct \texttt{latexindent.pl} to perform replacements/substitutions on your
+ \announce*{2019-07-13}{replacement mode switches}
+ file by using any of the \texttt{-r}, \texttt{-rv} or
+ \texttt{-rr} switches:
+ \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.
+ \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}
+ \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}.
+
+ \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.
+
+ 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.
+
+\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}.
+
+	Beginning with the code in \cref{lst:replace1} and running the command
+	\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
+	\begin{commandshell}
+latexindent.pl -r replace1.tex -l=replace1.yaml
+\end{commandshell}
+	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}
+
+	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.
+
+\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.
+		\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}
+
+		\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.
+
+		Using the YAML in \cref{lst:colsep-yaml}, and running the command
+		\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
+		\begin{commandshell}
+latexindent.pl -r colsep.tex -l=colsep1.yaml
+\end{commandshell}
+		then we achieve the output in \cref{lst:colsep-mod1}.
+		\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
+		\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
+		\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,
+		\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}
+
+	\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}.
+
+		\cmhlistingsfromfile*{demonstrations/displaymath.tex}{\texttt{displaymath.tex}}{lst:displaymath}
+
+		We use the settings in \cref{lst:displaymath1} and run the command
+		\begin{commandshell}
+latexindent.pl -r displaymath.tex -l=displaymath1.yaml
+\end{commandshell}
+		to receive the output given in \cref{lst:displaymath-mod1}.
+
+		\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
+		\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
+		\begin{commandshell}
+latexindent.pl -r phrase.tex -l=hspace.yaml
+\end{commandshell}
+		which gives the output in \cref{lst:phrase-mod1}.
+
+		\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}
+
+	\begin{example}
+		We begin with the code in \cref{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
+		\begin{commandshell}
+latexindent.pl -r references.tex -l=reference.yaml
+\end{commandshell}
+		which gives the output in \cref{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}
+
+		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{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,
+		\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,
+		\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}