diff options
Diffstat (limited to 'support/latexindent/documentation/sec-replacements.tex')
-rw-r--r-- | support/latexindent/documentation/sec-replacements.tex | 619 |
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} |