diff options
Diffstat (limited to 'support/latexindent/documentation/sec-replacements.tex')
-rw-r--r-- | support/latexindent/documentation/sec-replacements.tex | 154 |
1 files changed, 73 insertions, 81 deletions
diff --git a/support/latexindent/documentation/sec-replacements.tex b/support/latexindent/documentation/sec-replacements.tex index a36c4199cf..5491df6072 100644 --- a/support/latexindent/documentation/sec-replacements.tex +++ b/support/latexindent/documentation/sec-replacements.tex @@ -1,20 +1,19 @@ % arara: pdflatex: { 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}}; } + \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: - \index{verbatim!rv, replacementrespectverb switch} + \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 + \item the \texttt{-rr} switch will \emph{not} perform indentation, and will perform replacements not respecting verbatim code blocks. \end{itemize} @@ -57,8 +56,8 @@ 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} + 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} @@ -71,8 +70,7 @@ latexindent.pl -r replace1.tex 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} + \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 @@ -113,12 +111,11 @@ latexindent.pl -r replace1.tex -l=replace1.yaml \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} + 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} @@ -131,16 +128,14 @@ latexindent.pl -r colsep.tex -l=colsep.yaml 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} + 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 +} + 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}] @@ -148,10 +143,11 @@ latexindent.pl -r colsep.tex -l=colsep1.yaml \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: + 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 @@ -172,9 +168,8 @@ latexindent.pl -r colsep.tex -l=colsep1.yaml \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} + 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} @@ -187,13 +182,13 @@ latexindent.pl -r colsep.tex -l=multi-line.yaml 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}. + 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} + 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} @@ -207,31 +202,32 @@ latexindent.pl -r colsep.tex -l=multi-line1.yaml 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} + \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}. + 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}. + 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 - \index{switches!-l demonstration} - \index{switches!-r demonstration} + 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} + 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,] @@ -250,11 +246,11 @@ latexindent.pl -r displaymath.tex -l=displaymath1.yaml 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} + 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} @@ -270,28 +266,28 @@ latexindent.pl -r -m displaymath.tex -l=displaymath1.yaml,equation.yaml \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}. + 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} + 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} - The \lstinline!\h+! setting in \cref{lst:hspace} say to replace \emph{at least one horizontal space} with a single space. + 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} @@ -299,40 +295,37 @@ latexindent.pl -r phrase.tex -l=hspace.yaml \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} + 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[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)?!. + 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}. + 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, - \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} + 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 @@ -363,8 +356,8 @@ latexindent.pl -rr verb1.tex -l=verbatim1.yaml -o=+-rr-mod1 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}. + 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} @@ -378,9 +371,8 @@ latexindent.pl -rr verb1.tex -l=verbatim1.yaml -o=+-rr-mod1 \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} + 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 |