% arara: pdflatex: {shell: yes, files: [latexindent]} \section{Fine tuning}\label{sec:finetuning} \texttt{latexindent.pl} operates by looking for the code blocks detailed in \vref{tab:code-blocks}. \announce{2019-07-13}{details of fine tuning of code blocks} The fine tuning of the details of such code blocks is controlled by the \texttt{fineTuning} field, detailed in \cref{lst:fineTuning}. This field is for those that would like to peek under the bonnet/hood and make some fine tuning to \texttt{latexindent.pl}'s operating. \index{warning!fine tuning} \index{regular expressions!fine tuning} \index{regular expressions!environments} \index{regular expressions!ifElseFi} \index{regular expressions!commands} \index{regular expressions!keyEqualsValuesBracesBrackets} \index{regular expressions!NamedGroupingBracesBrackets} \index{regular expressions!UnNamedGroupingBracesBrackets} \index{regular expressions!arguments} \index{regular expressions!modifyLineBreaks} \index{regular expressions!lowercase alph a-z} \index{regular expressions!uppercase alph A-Z} \index{regular expressions!numeric 0-9} \index{regular expressions!at least one +} \index{regular expressions!horizontal space \textbackslash{h}} \begin{warning} Making changes to the fine tuning may have significant consequences for your indentation scheme, proceed with caution! \end{warning} \begin{widepage} \cmhlistingsfromfile[style=fineTuning]*{../defaultSettings.yaml}[width=.95\linewidth,before=\centering,yaml-TCB]{\texttt{fineTuning}}{lst:fineTuning} \end{widepage} The fields given in \cref{lst:fineTuning} are all \emph{regular expressions}. 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. We make the following comments with reference to \cref{lst:fineTuning}: \begin{enumerate} \item the \texttt{environments:name} field details that the \emph{name} of an environment can contain: \begin{enumerate} \item \texttt{a-z} lower case letters \item \texttt{A-Z} upper case letters \item \texttt{@} the \texttt{@} 'letter' \item \lstinline!\*! stars \item \texttt{0-9} numbers \item \lstinline!_! underscores \item \lstinline!\! backslashes \end{enumerate} \index{regular expressions!at least one +} The \texttt{+} at the end means \emph{at least one} of the above characters. \item the \texttt{ifElseFi:name} field: \begin{enumerate} \item \lstinline^@?^ means that it \emph{can possibly} begin with \lstinline^@^ \item followed by \texttt{if} \item followed by 0 or more characters from \texttt{a-z}, \texttt{A-Z} and \texttt{@} \item the \texttt{?} the end means \emph{non-greedy}, which means `stop the match as soon as possible' \end{enumerate} \item the \texttt{keyEqualsValuesBracesBrackets} contains some interesting syntax: \begin{enumerate} \item \lstinline!|! means `or' \item \lstinline^(?:(?^ is designed for 'beamer'-type commands; the \lstinline^.*?^ means anything in between \lstinline^<...>^ \end{enumerate} \item the \texttt{modifyLineBreaks} field refers to fine tuning settings detailed in \vref{sec:modifylinebreaks}. In particular: \begin{enumerate} \item \texttt{betterFullStop} is in relation to the one sentence per line routine, detailed in \vref{sec:onesentenceperline} \item \texttt{doubleBackSlash} is in relation to the \texttt{DBSStartsOnOwnLine} and \texttt{DBSFinishesWithLineBreak} polyswitches surrounding double back slashes, see \vref{subsec:dbs} \item \texttt{comma} is in relation to the \texttt{CommaStartsOnOwnLine} and \texttt{CommaFinishesWithLineBreak} polyswitches surrounding commas in optional and mandatory arguments; see \vref{tab:poly-switch-mapping} \end{enumerate} \end{enumerate} It is not obvious from \cref{lst:fineTuning}, but each of the \texttt{follow}, \texttt{before} and \texttt{between} fields allow trailing comments, line breaks, and horizontal spaces between each character. \begin{example} As a demonstration, consider the file given in \cref{lst:finetuning1}, together with its default output using the command \begin{commandshell} latexindent.pl finetuning1.tex \end{commandshell} is given in \cref{lst:finetuning1-default}. \begin{cmhtcbraster}[raster column skip=.01\linewidth] \cmhlistingsfromfile{demonstrations/finetuning1.tex}{\texttt{finetuning1.tex}}{lst:finetuning1} \cmhlistingsfromfile{demonstrations/finetuning1-default.tex}{\texttt{finetuning1.tex} default}{lst:finetuning1-default} \end{cmhtcbraster} It's clear from \cref{lst:finetuning1-default} that the indentation scheme has not worked as expected. We can \emph{fine tune} the indentation scheme by employing the settings given in \cref{lst:fine-tuning1} and running the command \index{switches!-l demonstration} \begin{commandshell} latexindent.pl finetuning1.tex -l=fine-tuning1.yaml \end{commandshell} and the associated (desired) output is given in \cref{lst:finetuning1-mod1}. \index{regular expressions!at least one +} \begin{cmhtcbraster}[raster column skip=.01\linewidth] \cmhlistingsfromfile{demonstrations/finetuning1-mod1.tex}{\texttt{finetuning1.tex} using \cref{lst:fine-tuning1}}{lst:finetuning1-mod1} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/fine-tuning1.yaml}[yaml-TCB]{\texttt{finetuning1.yaml}}{lst:fine-tuning1} \end{cmhtcbraster} \end{example} \begin{example} Let's have another demonstration; consider the file given in \cref{lst:finetuning2}, together with its default output using the command \begin{commandshell} latexindent.pl finetuning2.tex \end{commandshell} is given in \cref{lst:finetuning2-default}. \begin{cmhtcbraster}[raster column skip=.01\linewidth, raster left skip=-3.75cm, raster right skip=0cm,] \cmhlistingsfromfile{demonstrations/finetuning2.tex}{\texttt{finetuning2.tex}}{lst:finetuning2} \cmhlistingsfromfile{demonstrations/finetuning2-default.tex}{\texttt{finetuning2.tex} default}{lst:finetuning2-default} \end{cmhtcbraster} It's clear from \cref{lst:finetuning2-default} that the indentation scheme has not worked as expected. We can \emph{fine tune} the indentation scheme by employing the settings given in \cref{lst:fine-tuning2} and running the command \index{switches!-l demonstration} \begin{commandshell} latexindent.pl finetuning2.tex -l=fine-tuning2.yaml \end{commandshell} and the associated (desired) output is given in \cref{lst:finetuning2-mod1}. \begin{cmhtcbraster}[raster column skip=.01\linewidth, raster left skip=-3.75cm, raster right skip=0cm,] \cmhlistingsfromfile{demonstrations/finetuning2-mod1.tex}{\texttt{finetuning2.tex} using \cref{lst:fine-tuning2}}{lst:finetuning2-mod1} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/fine-tuning2.yaml}[yaml-TCB]{\texttt{finetuning2.yaml}}{lst:fine-tuning2} \end{cmhtcbraster} In particular, note that the settings in \cref{lst:fine-tuning2} specify that \texttt{NamedGroupingBracesBrackets} and \texttt{UnNamedGroupingBracesBrackets} can follow \texttt{"} and that we allow \lstinline!---! between arguments. \end{example} \begin{example} You can tweak the \texttt{fineTuning} using the \texttt{-y} switch, but to be sure to use quotes appropriately. For example, starting with the code in \cref{lst:finetuning3} and running the following command \begin{commandshell} latexindent.pl -m -y='modifyLineBreaks:oneSentencePerLine:manipulateSentences: 1, modifyLineBreaks:oneSentencePerLine:sentencesBeginWith:a-z: 1, fineTuning:modifyLineBreaks:betterFullStop: "(?:\.|;|:(?![a-z]))|(?:(?