diff options
Diffstat (limited to 'support/latexindent/documentation/sec-fine-tuning.tex')
-rw-r--r-- | support/latexindent/documentation/sec-fine-tuning.tex | 51 |
1 files changed, 25 insertions, 26 deletions
diff --git a/support/latexindent/documentation/sec-fine-tuning.tex b/support/latexindent/documentation/sec-fine-tuning.tex index 0510e8e66c..669bff5737 100644 --- a/support/latexindent/documentation/sec-fine-tuning.tex +++ b/support/latexindent/documentation/sec-fine-tuning.tex @@ -2,8 +2,9 @@ \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}. + \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. @@ -29,7 +30,7 @@ \end{warning} \begin{widepage} - \cmhlistingsfromfile*[style=fineTuning]*{../defaultSettings.yaml}[width=.95\linewidth,before=\centering,yaml-TCB]{\texttt{fineTuning}}{lst:fineTuning} + \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 @@ -38,8 +39,8 @@ 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: + \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 @@ -50,25 +51,23 @@ \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. + 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' + \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^(?:(?<!\\)\{)^ the \lstinline^(?:...)^ uses a \emph{non-capturing} group -- you don't necessarily need to worry about what this means, but just know that for the - \texttt{fineTuning} feature you should only ever use \emph{non}-capturing - groups, and \emph{not} capturing groups, which are simply + \texttt{fineTuning} feature you should only ever use \emph{non}-capturing groups, and + \emph{not} capturing groups, which are simply \lstinline!(...)! \item \lstinline^(?<!\\)\{)^ means a \lstinline^{^ but it can \emph{not} be immediately preceded by a \lstinline!\! @@ -90,14 +89,14 @@ \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} + \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. + \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 @@ -179,15 +178,15 @@ latexindent.pl -m -y='modifyLineBreaks:oneSentencePerLine:manipulateSentences: 1 We can tweak the \texttt{fineTuning} for how trailing comments are classified. For motivation, let's consider the code given in \cref{lst:finetuning4} - \cmhlistingsfromfile*{demonstrations/finetuning4.tex}{\texttt{finetuning4.tex}}{lst:finetuning4} + \cmhlistingsfromfile{demonstrations/finetuning4.tex}{\texttt{finetuning4.tex}}{lst:finetuning4} We will compare the settings given in \cref{lst:href1,lst:href2}. \begin{cmhtcbraster}[raster column skip=.01\linewidth, raster left skip=0cm, raster right skip=-0.5cm,] - \cmhlistingsfromfile*[style=yaml-LST]*{demonstrations/href1.yaml}[MLB-TCB]{\texttt{href1.yaml}}{lst:href1} - \cmhlistingsfromfile*[style=yaml-LST]*{demonstrations/href2.yaml}[MLB-TCB]{\texttt{href2.yaml}}{lst:href2} + \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/href1.yaml}[MLB-TCB]{\texttt{href1.yaml}}{lst:href1} + \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/href2.yaml}[MLB-TCB]{\texttt{href2.yaml}}{lst:href2} \end{cmhtcbraster} Upon running the following commands @@ -198,16 +197,16 @@ latexindent.pl -m finetuning4.tex -o=+-mod2 -l=href2 we receive the respective output in \cref{lst:finetuning4-mod1,lst:finetuning4-mod2}. \begin{widepage} - \cmhlistingsfromfile*{demonstrations/finetuning4-mod1.tex}{\texttt{finetuning4.tex} using \cref{lst:href1}}{lst:finetuning4-mod1} + \cmhlistingsfromfile{demonstrations/finetuning4-mod1.tex}{\texttt{finetuning4.tex} using \cref{lst:href1}}{lst:finetuning4-mod1} - \cmhlistingsfromfile*{demonstrations/finetuning4-mod2.tex}{\texttt{finetuning4.tex} using \cref{lst:href2}}{lst:finetuning4-mod2} + \cmhlistingsfromfile{demonstrations/finetuning4-mod2.tex}{\texttt{finetuning4.tex} using \cref{lst:href2}}{lst:finetuning4-mod2} \end{widepage} We note that in: \begin{itemize} - \item \cref{lst:finetuning4-mod1} the trailing comments are assumed to be everything following the - first comment symbol, which has meant that everything following it has been moved to the - end of the line; this is undesirable, clearly! + \item \cref{lst:finetuning4-mod1} the trailing comments are assumed to be everything following + the first comment symbol, which has meant that everything following it has been moved to + the end of the line; this is undesirable, clearly! \item \cref{lst:finetuning4-mod2} has fine-tuned the trailing comment matching, and says that \% cannot be immediately preceeded by the words `Handbook', `for' or `Spoken', which means that @@ -224,7 +223,7 @@ latexindent.pl -m finetuning4.tex -o=+-mod3 -l=href3 then we receive the same output given in \cref{lst:finetuning4-mod2}; see also \texttt{paragraphsStopAt} in \vref{lst:paragraphsStopAt}. - \cmhlistingsfromfile*[style=yaml-LST]*{demonstrations/href3.yaml}[MLB-TCB]{\texttt{href3.yaml}}{lst:href3} + \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/href3.yaml}[MLB-TCB]{\texttt{href3.yaml}}{lst:href3} With reference to the \texttt{body} field in \cref{lst:href3}, we note that the \texttt{body} field can be interpreted as: the fewest number of zero or more characters that are not right braces. This |