From c7892fe1a11367872de6f3ee0fa074b39824e59c Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Mon, 31 Oct 2022 03:04:01 +0000 Subject: CTAN sync 202210310303 --- .../latexindent/documentation/sec-fine-tuning.tex | 311 --------------------- 1 file changed, 311 deletions(-) delete mode 100644 support/latexindent/documentation/sec-fine-tuning.tex (limited to 'support/latexindent/documentation/sec-fine-tuning.tex') diff --git a/support/latexindent/documentation/sec-fine-tuning.tex b/support/latexindent/documentation/sec-fine-tuning.tex deleted file mode 100644 index 8798b276ab..0000000000 --- a/support/latexindent/documentation/sec-fine-tuning.tex +++ /dev/null @@ -1,311 +0,0 @@ -% arara: pdflatex: { 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,enhanced jigsaw,breakable,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. - - \index{warning!capture groups} - \begin{warning} - For the \texttt{fineTuning} feature you should only ever use \emph{non}-capturing groups, - such as \lstinline!(?:...)! and \emph{not} capturing groups, which are \lstinline!(...)! - \end{warning} - - \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]))|(?:(?