diff options
Diffstat (limited to 'Master/texmf-dist/doc/support/latexindent/sec-fine-tuning.tex')
| -rw-r--r-- | Master/texmf-dist/doc/support/latexindent/sec-fine-tuning.tex | 109 |
1 files changed, 109 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/support/latexindent/sec-fine-tuning.tex b/Master/texmf-dist/doc/support/latexindent/sec-fine-tuning.tex new file mode 100644 index 00000000000..9a2cbbb5c81 --- /dev/null +++ b/Master/texmf-dist/doc/support/latexindent/sec-fine-tuning.tex @@ -0,0 +1,109 @@ +% 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. + + \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=0.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} + 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^(?:(?<!\\)\{)^ 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 + \lstinline!(...)! + \item \lstinline^(?<!\\)\{)^ means a \lstinline^{^ but it can \emph{not} + be immediately preceded by a \lstinline!\! + \end{enumerate} + \item in the \texttt{arguments:before} field + \begin{enumerate} + \item \lstinline^\d\h*^ means a digit (i.e. a number), followed by 0 or more horizontal + spaces + \item \lstinline^;?,?^ means \emph{possibly} a semi-colon, and possibly a comma + \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. + + 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 + \begin{commandshell} +latexindent.pl finetuning1.tex -l=fine-tuning1.yaml +\end{commandshell} + and the associated (desired) output is given in \cref{lst:finetuning1-mod1}. + + \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} |