diff options
Diffstat (limited to 'Master/texmf-dist/doc/support/latexindent/sec-default-user-local.tex')
-rw-r--r-- | Master/texmf-dist/doc/support/latexindent/sec-default-user-local.tex | 2095 |
1 files changed, 1047 insertions, 1048 deletions
diff --git a/Master/texmf-dist/doc/support/latexindent/sec-default-user-local.tex b/Master/texmf-dist/doc/support/latexindent/sec-default-user-local.tex index 94fbdce46cc..af470923337 100644 --- a/Master/texmf-dist/doc/support/latexindent/sec-default-user-local.tex +++ b/Master/texmf-dist/doc/support/latexindent/sec-default-user-local.tex @@ -19,351 +19,351 @@ specific context and associated commentary should make it clear which values are allowed. \yamltitle{fileExtensionPreference}*{fields} - \texttt{latexindent.pl} can be called to - act on a file without specifying the file extension. For example we can call - \begin{commandshell} + \texttt{latexindent.pl} can be called to + act on a file without specifying the file extension. For example we can call + \begin{commandshell} latexindent.pl myfile \end{commandshell} - in which case the script will look for \texttt{myfile} with the extensions specified in - \texttt{fileExtensionPreference} in their numeric order. If no match is found, the script - will exit. As with all of the fields, you should change and/or add to this as necessary. + in which case the script will look for \texttt{myfile} with the extensions specified in + \texttt{fileExtensionPreference} in their numeric order. If no match is found, the script + will exit. As with all of the fields, you should change and/or add to this as necessary. - \cmhlistingsfromfile[style=fileExtensionPreference]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{fileExtensionPreference}}{lst:fileExtensionPreference} + \cmhlistingsfromfile[style=fileExtensionPreference]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{fileExtensionPreference}}{lst:fileExtensionPreference} - Calling \texttt{latexindent.pl myfile} with the (default) settings specified in - \cref{lst:fileExtensionPreference} means that the script will first look for - \texttt{myfile.tex}, then \texttt{myfile.sty}, \texttt{myfile.cls}, and finally - \texttt{myfile.bib} in order\footnote{Throughout this manual, listings shown with line - numbers represent code taken directly from \texttt{defaultSettings.yaml}.}. + Calling \texttt{latexindent.pl myfile} with the (default) settings specified in + \cref{lst:fileExtensionPreference} means that the script will first look for + \texttt{myfile.tex}, then \texttt{myfile.sty}, \texttt{myfile.cls}, and finally + \texttt{myfile.bib} in order\footnote{Throughout this manual, listings shown with line + numbers represent code taken directly from \texttt{defaultSettings.yaml}.}. - \index{backup files!extension settings} + \index{backup files!extension settings} \subsection{Backup and log file preferences} \yamltitle{backupExtension}*{extension name} - If you call \texttt{latexindent.pl} with the \texttt{-w} switch (to overwrite - \texttt{myfile.tex}) then it will create a backup file before doing any indentation; the - default extension is \texttt{.bak}, so, for example, \texttt{myfile.bak0} would be - created when calling \texttt{latexindent.pl myfile.tex} for the first time. + If you call \texttt{latexindent.pl} with the \texttt{-w} switch (to overwrite + \texttt{myfile.tex}) then it will create a backup file before doing any indentation; the + default extension is \texttt{.bak}, so, for example, \texttt{myfile.bak0} would be + created when calling \texttt{latexindent.pl myfile.tex} for the first time. - By default, every time you subsequently call \texttt{latexindent.pl} with the \texttt{-w} - to act upon \texttt{myfile.tex}, it will create successive back up files: - \texttt{myfile.bak1}, \texttt{myfile.bak2}, etc. + By default, every time you subsequently call \texttt{latexindent.pl} with the \texttt{-w} + to act upon \texttt{myfile.tex}, it will create successive back up files: + \texttt{myfile.bak1}, \texttt{myfile.bak2}, etc. \yamltitle{onlyOneBackUp}*{integer} - \label{page:onlyonebackup} - \index{backup files!number of backup files} - If you don't want a backup for every time that you call \texttt{latexindent.pl} (so you - don't want \texttt{myfile.bak1}, \texttt{myfile.bak2}, etc) and you simply want - \texttt{myfile.bak} (or whatever you chose \texttt{backupExtension} to be) then change - \texttt{onlyOneBackUp} to \texttt{1}; the default value of \texttt{onlyOneBackUp} is - \texttt{0}. - \index{backup files!maximum number of backup files} - \index{backup files!number of backup files} + \label{page:onlyonebackup} + \index{backup files!number of backup files} + If you don't want a backup for every time that you call \texttt{latexindent.pl} (so you + don't want \texttt{myfile.bak1}, \texttt{myfile.bak2}, etc) and you simply want + \texttt{myfile.bak} (or whatever you chose \texttt{backupExtension} to be) then change + \texttt{onlyOneBackUp} to \texttt{1}; the default value of \texttt{onlyOneBackUp} is + \texttt{0}. + \index{backup files!maximum number of backup files} + \index{backup files!number of backup files} \yamltitle{maxNumberOfBackUps}*{integer} - Some users may only want a finite number of backup files, say at most $3$, in which case, - they can change this switch. The smallest value of \texttt{maxNumberOfBackUps} is $0$ - which will \emph{not} prevent backup files being made; in this case, the behaviour will - be dictated entirely by \texttt{onlyOneBackUp}. The default value of - \texttt{maxNumberOfBackUps} is \texttt{0}. + Some users may only want a finite number of backup files, say at most $3$, in which case, + they can change this switch. The smallest value of \texttt{maxNumberOfBackUps} is $0$ + which will \emph{not} prevent backup files being made; in this case, the behaviour will + be dictated entirely by \texttt{onlyOneBackUp}. The default value of + \texttt{maxNumberOfBackUps} is \texttt{0}. \yamltitle{cycleThroughBackUps}*{integer} - \index{backup files!cycle through} - Some users may wish to cycle through backup files, by deleting the oldest backup file and - keeping only the most recent; for example, with \texttt{maxNumberOfBackUps: 4}, and - \texttt{cycleThroughBackUps} set to \texttt{1} then the \texttt{copy} procedure given - below would be obeyed. + \index{backup files!cycle through} + Some users may wish to cycle through backup files, by deleting the oldest backup file and + keeping only the most recent; for example, with \texttt{maxNumberOfBackUps: 4}, and + \texttt{cycleThroughBackUps} set to \texttt{1} then the \texttt{copy} procedure given + below would be obeyed. - \begin{commandshell} + \begin{commandshell} copy myfile.bak1 to myfile.bak0 copy myfile.bak2 to myfile.bak1 copy myfile.bak3 to myfile.bak2 copy myfile.bak4 to myfile.bak3 \end{commandshell} - The default value of \texttt{cycleThroughBackUps} is \texttt{0}. + The default value of \texttt{cycleThroughBackUps} is \texttt{0}. \yamltitle{logFilePreferences}*{fields} - \texttt{latexindent.pl} writes information to \texttt{indent.log}, some - of which can be customized by changing \texttt{logFilePreferences}; see - \cref{lst:logFilePreferences}. If you load your own user settings (see - \vref{sec:indentconfig}) then \texttt{latexindent.pl} will detail them in - \texttt{indent.log}; you can choose not to have the details logged by switching - \texttt{showEveryYamlRead} to \texttt{0}. Once all of your settings have been loaded, you - can see the amalgamated settings in the log file by switching - \texttt{showAmalgamatedSettings} to \texttt{1}, if you wish. - - \cmhlistingsfromfile[style=logFilePreferences,]{../defaultSettings.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{logFilePreferences}}{lst:logFilePreferences} - - When \announce{2018-01-13}{showDecorationStartCodeBlockTrace feature for log file} either - of the \texttt{trace} modes (see \cpageref{page:traceswitch}) are active, you will - receive detailed information in \texttt{indent.log}. You can specify character strings to - appear before and after the notification of a found code block using, respectively, - \texttt{showDecorationStartCodeBlockTrace} and - \texttt{showDecorationFinishCodeBlockTrace}. A demonstration is given in - \vref{app:logfile-demo}.% - - The log file will end with the characters given in \texttt{endLogFileWith}, and will - report the \texttt{GitHub} address of \texttt{latexindent.pl} to the log file if - \texttt{showGitHubInfoFooter} is set to \texttt{1}. - - Note: \texttt{latexindent.pl} no longer uses the \texttt{log4perl} module to handle the - creation of the logfile. \announce{2021-03-14}*{no longer using log4perl}% - - Some of the options \announce{2021-06-19}*{logFilePreferences updated to include Dumper - options} for Perl's \texttt{Dumper} module can be specified in - \cref{lst:logFilePreferences}; see \cite{dumper} and \cite{dumperdemo} for more - information. These options will mostly be helpful for those calling - \texttt{latexindent.pl} with the \texttt{-tt} option described in \cref{sec:commandline}.% + \texttt{latexindent.pl} writes information to \texttt{indent.log}, some + of which can be customized by changing \texttt{logFilePreferences}; see + \cref{lst:logFilePreferences}. If you load your own user settings (see + \vref{sec:indentconfig}) then \texttt{latexindent.pl} will detail them in + \texttt{indent.log}; you can choose not to have the details logged by switching + \texttt{showEveryYamlRead} to \texttt{0}. Once all of your settings have been loaded, you + can see the amalgamated settings in the log file by switching + \texttt{showAmalgamatedSettings} to \texttt{1}, if you wish. + + \cmhlistingsfromfile[style=logFilePreferences,]{../defaultSettings.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{logFilePreferences}}{lst:logFilePreferences} + + When \announce{2018-01-13}{showDecorationStartCodeBlockTrace feature for log file} either + of the \texttt{trace} modes (see \cpageref{page:traceswitch}) are active, you will + receive detailed information in \texttt{indent.log}. You can specify character strings to + appear before and after the notification of a found code block using, respectively, + \texttt{showDecorationStartCodeBlockTrace} and + \texttt{showDecorationFinishCodeBlockTrace}. A demonstration is given in + \vref{app:logfile-demo}.% + + The log file will end with the characters given in \texttt{endLogFileWith}, and will + report the \texttt{GitHub} address of \texttt{latexindent.pl} to the log file if + \texttt{showGitHubInfoFooter} is set to \texttt{1}. + + Note: \texttt{latexindent.pl} no longer uses the \texttt{log4perl} module to handle the + creation of the logfile. \announce{2021-03-14}*{no longer using log4perl}% + + Some of the options \announce{2021-06-19}*{logFilePreferences updated to include Dumper + options} for Perl's \texttt{Dumper} module can be specified in + \cref{lst:logFilePreferences}; see \cite{dumper} and \cite{dumperdemo} for more + information. These options will mostly be helpful for those calling + \texttt{latexindent.pl} with the \texttt{-tt} option described in \cref{sec:commandline}.% \subsection{Verbatim code blocks} \yamltitle{verbatimEnvironments}*{fields} - A field that contains a list of environments that you would like left completely alone -- - no indentation will be performed on environments that you have specified in this field, - see \cref{lst:verbatimEnvironments}. \index{verbatim!environments} - \index{verbatim!commands} - - \begin{cmhtcbraster}[raster column skip=.1\linewidth] - \cmhlistingsfromfile[style=verbatimEnvironments]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{verbatimEnvironments}}{lst:verbatimEnvironments} - \cmhlistingsfromfile[style=verbatimCommands]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{verbatimCommands}}{lst:verbatimCommands} - \end{cmhtcbraster} - - Note that if you put an environment in \texttt{verbatimEnvironments} and in other fields - such as \texttt{lookForAlignDelims} or \texttt{noAdditionalIndent} then - \texttt{latexindent.pl} will \emph{always} prioritize \texttt{verbatimEnvironments}. - - You can, optionally, specify \announce{2021-10-30}{verbatim name feature} the - \texttt{verbatim} field using the \texttt{name} field which takes a regular expression as - its argument; thank you to \cite{XuehaiPan} for contributing this feature. - - For demonstration, then assuming that your file contains the environments - \texttt{latexcode}, \texttt{latexcode*}, \texttt{pythoncode} and \texttt{pythoncode*}, - then the listings given in \cref{lst:nameAsRegex1,lst:nameAsRegex2} are equivalent. - - \begin{cmhtcbraster}[raster column skip=.1\linewidth] - \cmhlistingsfromfile{demonstrations/nameAsRegex1.yaml}[yaml-TCB]{\texttt{nameAsRegex1.yaml}}{lst:nameAsRegex1} - \cmhlistingsfromfile{demonstrations/nameAsRegex2.yaml}[yaml-TCB]{\texttt{nameAsRegex2.yaml}}{lst:nameAsRegex2} - \end{cmhtcbraster} - - With reference to \cref{lst:nameAsRegex2}: - \begin{itemize} - \item the \texttt{name} field as specified here means \emph{any word followed by the word code, - optionally followed by *}; - \item we have used \texttt{nameAsRegex} to identify this field, but you can use any description - you like; - \item the \texttt{lookForThis} field is optional, and can take the values 0 (off) or 1 (on); by - default, it is assumed to be 1 (on). - \end{itemize} + A field that contains a list of environments that you would like left completely alone -- + no indentation will be performed on environments that you have specified in this field, + see \cref{lst:verbatimEnvironments}. \index{verbatim!environments} + \index{verbatim!commands} + + \begin{cmhtcbraster}[raster column skip=.1\linewidth] + \cmhlistingsfromfile[style=verbatimEnvironments]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{verbatimEnvironments}}{lst:verbatimEnvironments} + \cmhlistingsfromfile[style=verbatimCommands]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{verbatimCommands}}{lst:verbatimCommands} + \end{cmhtcbraster} + + Note that if you put an environment in \texttt{verbatimEnvironments} and in other fields + such as \texttt{lookForAlignDelims} or \texttt{noAdditionalIndent} then + \texttt{latexindent.pl} will \emph{always} prioritize \texttt{verbatimEnvironments}. + + You can, optionally, specify \announce{2021-10-30}{verbatim name feature} the + \texttt{verbatim} field using the \texttt{name} field which takes a regular expression as + its argument; thank you to \cite{XuehaiPan} for contributing this feature. + + For demonstration, then assuming that your file contains the environments + \texttt{latexcode}, \texttt{latexcode*}, \texttt{pythoncode} and \texttt{pythoncode*}, + then the listings given in \cref{lst:nameAsRegex1,lst:nameAsRegex2} are equivalent. + + \begin{cmhtcbraster}[raster column skip=.1\linewidth] + \cmhlistingsfromfile{demonstrations/nameAsRegex1.yaml}[yaml-TCB]{\texttt{nameAsRegex1.yaml}}{lst:nameAsRegex1} + \cmhlistingsfromfile{demonstrations/nameAsRegex2.yaml}[yaml-TCB]{\texttt{nameAsRegex2.yaml}}{lst:nameAsRegex2} + \end{cmhtcbraster} + + With reference to \cref{lst:nameAsRegex2}: + \begin{itemize} + \item the \texttt{name} field as specified here means \emph{any word followed by the word code, + optionally followed by *}; + \item we have used \texttt{nameAsRegex} to identify this field, but you can use any description + you like; + \item the \texttt{lookForThis} field is optional, and can take the values 0 (off) or 1 (on); by + default, it is assumed to be 1 (on). + \end{itemize} \yamltitle{verbatimCommands}*{fields} - A field that contains a list of commands that are verbatim commands, for example - \lstinline|\lstinline|; any commands populated in this field are protected from line - breaking routines (only relevant if the \texttt{-m} is active, see - \vref{sec:modifylinebreaks}). - - With reference to \cref{lst:verbatimCommands}, by default \texttt{latexindent.pl} looks - for \lstinline|\verb| immediately followed by another character, and then it takes the - body as anything up to the next occurrence of the character; this means that, for - example, \lstinline|\verb!x+3!| is treated as a \texttt{verbatimCommands}. - - You can, optionally, specify \announce{2021-10-30}{verbatimCommands name feature} the - \texttt{verbatimCommands} field using the \texttt{name} field which takes a regular - expression as its argument; thank you to \cite{XuehaiPan} for contributing this feature. - - For demonstration, then assuming that your file contains the commands - \texttt{verbinline}, \texttt{myinline} then the listings given in - \cref{lst:nameAsRegex3,lst:nameAsRegex4} are equivalent. - - \begin{cmhtcbraster}[raster column skip=.1\linewidth] - \cmhlistingsfromfile{demonstrations/nameAsRegex3.yaml}[yaml-TCB]{\texttt{nameAsRegex3.yaml}}{lst:nameAsRegex3} - \cmhlistingsfromfile{demonstrations/nameAsRegex4.yaml}[yaml-TCB]{\texttt{nameAsRegex4.yaml}}{lst:nameAsRegex4} - \end{cmhtcbraster} - - With reference to \cref{lst:nameAsRegex4}: - \begin{itemize} - \item the \texttt{name} field as specified here means \emph{any word followed by the word - inline}; - \item we have used \texttt{nameAsRegex} to identify this field, but you can use any description - you like; - \item the \texttt{lookForThis} field is optional, and can take the values 0 (off) or 1 (on); by - default, it is assumed to be 1 (on). - \end{itemize} + A field that contains a list of commands that are verbatim commands, for example + \lstinline|\lstinline|; any commands populated in this field are protected from line + breaking routines (only relevant if the \texttt{-m} is active, see + \vref{sec:modifylinebreaks}). + + With reference to \cref{lst:verbatimCommands}, by default \texttt{latexindent.pl} looks + for \lstinline|\verb| immediately followed by another character, and then it takes the + body as anything up to the next occurrence of the character; this means that, for + example, \lstinline|\verb!x+3!| is treated as a \texttt{verbatimCommands}. + + You can, optionally, specify \announce{2021-10-30}{verbatimCommands name feature} the + \texttt{verbatimCommands} field using the \texttt{name} field which takes a regular + expression as its argument; thank you to \cite{XuehaiPan} for contributing this feature. + + For demonstration, then assuming that your file contains the commands + \texttt{verbinline}, \texttt{myinline} then the listings given in + \cref{lst:nameAsRegex3,lst:nameAsRegex4} are equivalent. + + \begin{cmhtcbraster}[raster column skip=.1\linewidth] + \cmhlistingsfromfile{demonstrations/nameAsRegex3.yaml}[yaml-TCB]{\texttt{nameAsRegex3.yaml}}{lst:nameAsRegex3} + \cmhlistingsfromfile{demonstrations/nameAsRegex4.yaml}[yaml-TCB]{\texttt{nameAsRegex4.yaml}}{lst:nameAsRegex4} + \end{cmhtcbraster} + + With reference to \cref{lst:nameAsRegex4}: + \begin{itemize} + \item the \texttt{name} field as specified here means \emph{any word followed by the word + inline}; + \item we have used \texttt{nameAsRegex} to identify this field, but you can use any description + you like; + \item the \texttt{lookForThis} field is optional, and can take the values 0 (off) or 1 (on); by + default, it is assumed to be 1 (on). + \end{itemize} \yamltitle{noIndentBlock}*{fields} - If you have a block of code that you don't want \texttt{latexindent.pl} to touch (even if - \index{verbatim!noIndentBlock} it is \emph{not} a verbatim-like environment) then you can - wrap it in an environment from \texttt{noIndentBlock}; you can use any name you like for - this, provided you populate it as demonstrate in \cref{lst:noIndentBlock}. + If you have a block of code that you don't want \texttt{latexindent.pl} to touch (even if + \index{verbatim!noIndentBlock} it is \emph{not} a verbatim-like environment) then you can + wrap it in an environment from \texttt{noIndentBlock}; you can use any name you like for + this, provided you populate it as demonstrate in \cref{lst:noIndentBlock}. - \cmhlistingsfromfile[style=noIndentBlock]{../defaultSettings.yaml}[width=.4\linewidth,before=\centering,yaml-TCB]{\texttt{noIndentBlock}}{lst:noIndentBlock} + \cmhlistingsfromfile[style=noIndentBlock]{../defaultSettings.yaml}[width=.4\linewidth,before=\centering,yaml-TCB]{\texttt{noIndentBlock}}{lst:noIndentBlock} - Of course, you don't want to have to specify these as null environments in your code, so - you use them with a comment symbol, \lstinline!%!, followed by as many spaces (possibly - none) as you like; see \cref{lst:noIndentBlockdemo} for example. + Of course, you don't want to have to specify these as null environments in your code, so + you use them with a comment symbol, \lstinline!%!, followed by as many spaces (possibly + none) as you like; see \cref{lst:noIndentBlockdemo} for example. - \cmhlistingsfromfile{demonstrations/noindentblock.tex}{\texttt{noIndentBlock.tex}}{lst:noIndentBlockdemo} + \cmhlistingsfromfile{demonstrations/noindentblock.tex}{\texttt{noIndentBlock.tex}}{lst:noIndentBlockdemo} - Important note: it is assumed that the \texttt{noindent} block statements specified in - this way appear on their own line. + Important note: it is assumed that the \texttt{noindent} block statements specified in + this way appear on their own line. - The \announce{2021-06-19}{noIndentBlock specified as regex} \texttt{noIndentBlock} fields - can also be specified in terms of \texttt{begin} and \texttt{end} fields. We use the code - in \cref{lst:noIndentBlock1} to demonstrate this feature.% + The \announce{2021-06-19}{noIndentBlock specified as regex} \texttt{noIndentBlock} fields + can also be specified in terms of \texttt{begin} and \texttt{end} fields. We use the code + in \cref{lst:noIndentBlock1} to demonstrate this feature.% - \cmhlistingsfromfile{demonstrations/noindentblock1.tex}{\texttt{noIndentBlock1.tex}}{lst:noIndentBlock1} + \cmhlistingsfromfile{demonstrations/noindentblock1.tex}{\texttt{noIndentBlock1.tex}}{lst:noIndentBlock1} - The settings given in \cref{lst:noindent1,lst:noindent2} are equivalent: + The settings given in \cref{lst:noindent1,lst:noindent2} are equivalent: - \begin{cmhtcbraster}[raster columns=3, - raster left skip=-3.5cm, - raster right skip=-2cm, - raster column skip=.03\linewidth] - \cmhlistingsfromfile{demonstrations/noindent1.yaml}[yaml-TCB]{\texttt{noindent1.yaml}}{lst:noindent1} - \cmhlistingsfromfile{demonstrations/noindent2.yaml}[yaml-TCB]{\texttt{noindent2.yaml}}{lst:noindent2} - \cmhlistingsfromfile{demonstrations/noindent3.yaml}[yaml-TCB]{\texttt{noindent3.yaml}}{lst:noindent3} - \end{cmhtcbraster} + \begin{cmhtcbraster}[raster columns=3, + raster left skip=-3.5cm, + raster right skip=-2cm, + raster column skip=.03\linewidth] + \cmhlistingsfromfile{demonstrations/noindent1.yaml}[yaml-TCB]{\texttt{noindent1.yaml}}{lst:noindent1} + \cmhlistingsfromfile{demonstrations/noindent2.yaml}[yaml-TCB]{\texttt{noindent2.yaml}}{lst:noindent2} + \cmhlistingsfromfile{demonstrations/noindent3.yaml}[yaml-TCB]{\texttt{noindent3.yaml}}{lst:noindent3} + \end{cmhtcbraster} - Upon running the commands - \begin{commandshell} + Upon running the commands + \begin{commandshell} latexindent.pl -l noindent1.yaml noindent1 latexindent.pl -l noindent2.yaml noindent1 \end{commandshell} - then we receive the output given in \cref{lst:noIndentBlock1-mod1}. + then we receive the output given in \cref{lst:noIndentBlock1-mod1}. - \cmhlistingsfromfile{demonstrations/noindentblock1-mod1.tex}{\texttt{noIndentBlock1.tex} using \cref{lst:noindent1} or \cref{lst:noindent2}}{lst:noIndentBlock1-mod1} + \cmhlistingsfromfile{demonstrations/noindentblock1-mod1.tex}{\texttt{noIndentBlock1.tex} using \cref{lst:noindent1} or \cref{lst:noindent2}}{lst:noIndentBlock1-mod1} - The \texttt{begin}, \texttt{body} and \texttt{end} fields for \texttt{noIndentBlock} are - all \emph{regular expressions}. If the \texttt{body} field is not specified, then it - takes a default value of \lstinline!.*?! which is written explicitly in - \cref{lst:noindent1}. In this context, we interpret \lstinline!.*?! in words as \emph{the - fewest number of characters (possibly none) until the `end' field is reached}. + The \texttt{begin}, \texttt{body} and \texttt{end} fields for \texttt{noIndentBlock} are + all \emph{regular expressions}. If the \texttt{body} field is not specified, then it + takes a default value of \lstinline!.*?! which is written explicitly in + \cref{lst:noindent1}. In this context, we interpret \lstinline!.*?! in words as \emph{the + fewest number of characters (possibly none) until the `end' field is reached}. - The \texttt{lookForThis} field is optional, and can take the values 0 (off) or 1 (on); by - default, it is assumed to be 1 (on). + The \texttt{lookForThis} field is optional, and can take the values 0 (off) or 1 (on); by + default, it is assumed to be 1 (on). - Using \cref{lst:noindent3} demonstrates setting \texttt{lookForThis} to 0 (off); running - the command - \begin{commandshell} + Using \cref{lst:noindent3} demonstrates setting \texttt{lookForThis} to 0 (off); running + the command + \begin{commandshell} latexindent.pl -l noindent3.yaml noindent1 \end{commandshell} - gives the output in \cref{lst:noIndentBlock1-mod3}. - - \cmhlistingsfromfile{demonstrations/noindentblock1-mod3.tex}{\texttt{noIndentBlock1.tex} using \cref{lst:noindent3}}{lst:noIndentBlock1-mod3} - - We will demonstrate this feature later in the documentation in \cref{lst:href3}. - - You can, optionally, specify \announce{2021-10-30}{noIndentBlock name feature} the - \texttt{noIndentBlock} field using the \texttt{name} field which takes a regular - expression as its argument; thank you to \cite{XuehaiPan} for contributing this feature. - - For demonstration, then assuming that your file contains the environments - \texttt{testnoindent}, \texttt{testnoindent*} then the listings given in - \cref{lst:nameAsRegex5,lst:nameAsRegex6} are equivalent. - - \begin{widepage} - \begin{cmhtcbraster}[raster column skip=.1\linewidth] - \cmhlistingsfromfile{demonstrations/nameAsRegex5.yaml}[yaml-TCB]{\texttt{nameAsRegex5.yaml}}{lst:nameAsRegex5} - \cmhlistingsfromfile{demonstrations/nameAsRegex6.yaml}[yaml-TCB]{\texttt{nameAsRegex6.yaml}}{lst:nameAsRegex6} - \end{cmhtcbraster} - \end{widepage} - - With reference to \cref{lst:nameAsRegex6}: - \begin{itemize} - \item the \texttt{name} field as specified here means \emph{any word followed by the word - noindent, optionally followed by *}; - \item we have used \texttt{nameAsRegex} to identify this field, but you can use any description - you like; - \item the \texttt{lookForThis} field is optional, and can take the values 0 (off) or 1 (on); by - default, it is assumed to be 1 (on). - \end{itemize} + gives the output in \cref{lst:noIndentBlock1-mod3}. + + \cmhlistingsfromfile{demonstrations/noindentblock1-mod3.tex}{\texttt{noIndentBlock1.tex} using \cref{lst:noindent3}}{lst:noIndentBlock1-mod3} + + We will demonstrate this feature later in the documentation in \cref{lst:href3}. + + You can, optionally, specify \announce{2021-10-30}{noIndentBlock name feature} the + \texttt{noIndentBlock} field using the \texttt{name} field which takes a regular + expression as its argument; thank you to \cite{XuehaiPan} for contributing this feature. + + For demonstration, then assuming that your file contains the environments + \texttt{testnoindent}, \texttt{testnoindent*} then the listings given in + \cref{lst:nameAsRegex5,lst:nameAsRegex6} are equivalent. + + \begin{widepage} + \begin{cmhtcbraster}[raster column skip=.1\linewidth] + \cmhlistingsfromfile{demonstrations/nameAsRegex5.yaml}[yaml-TCB]{\texttt{nameAsRegex5.yaml}}{lst:nameAsRegex5} + \cmhlistingsfromfile{demonstrations/nameAsRegex6.yaml}[yaml-TCB]{\texttt{nameAsRegex6.yaml}}{lst:nameAsRegex6} + \end{cmhtcbraster} + \end{widepage} + + With reference to \cref{lst:nameAsRegex6}: + \begin{itemize} + \item the \texttt{name} field as specified here means \emph{any word followed by the word + noindent, optionally followed by *}; + \item we have used \texttt{nameAsRegex} to identify this field, but you can use any description + you like; + \item the \texttt{lookForThis} field is optional, and can take the values 0 (off) or 1 (on); by + default, it is assumed to be 1 (on). + \end{itemize} \subsection{filecontents and preamble} \yamltitle{fileContentsEnvironments}*{field} - Before \texttt{latexindent.pl} determines the difference between preamble (if any) and - the main document, it first searches for any of the environments specified in - \texttt{fileContentsEnvironments}, see \cref{lst:fileContentsEnvironments}. The behaviour - of \texttt{latexindent.pl} on these environments is determined by their location - (preamble or not), and the value \texttt{indentPreamble}, discussed next. + Before \texttt{latexindent.pl} determines the difference between preamble (if any) and + the main document, it first searches for any of the environments specified in + \texttt{fileContentsEnvironments}, see \cref{lst:fileContentsEnvironments}. The behaviour + of \texttt{latexindent.pl} on these environments is determined by their location + (preamble or not), and the value \texttt{indentPreamble}, discussed next. - \cmhlistingsfromfile[style=fileContentsEnvironments]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{fileContentsEnvironments}}{lst:fileContentsEnvironments} + \cmhlistingsfromfile[style=fileContentsEnvironments]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{fileContentsEnvironments}}{lst:fileContentsEnvironments} \yamltitle{indentPreamble}{0|1} - The preamble of a document can sometimes contain some trickier code for - \texttt{latexindent.pl} to operate upon. By default, \texttt{latexindent.pl} won't try to - operate on the preamble (as \texttt{indentPreamble} is set to \texttt{0}, by default), - but if you'd like \texttt{latexindent.pl} to try then change \texttt{indentPreamble} to - \texttt{1}. + The preamble of a document can sometimes contain some trickier code for + \texttt{latexindent.pl} to operate upon. By default, \texttt{latexindent.pl} won't try to + operate on the preamble (as \texttt{indentPreamble} is set to \texttt{0}, by default), + but if you'd like \texttt{latexindent.pl} to try then change \texttt{indentPreamble} to + \texttt{1}. \yamltitle{lookForPreamble}*{fields} - Not all files contain preamble; for example, \texttt{sty}, \texttt{cls} and \texttt{bib} - files typically do \emph{not}. Referencing \cref{lst:lookForPreamble}, if you set, for - example, \texttt{.tex} to \texttt{0}, then regardless of the setting of the value of - \texttt{indentPreamble}, preamble will not be assumed when operating upon \texttt{.tex} - files. + Not all files contain preamble; for example, \texttt{sty}, \texttt{cls} and \texttt{bib} + files typically do \emph{not}. Referencing \cref{lst:lookForPreamble}, if you set, for + example, \texttt{.tex} to \texttt{0}, then regardless of the setting of the value of + \texttt{indentPreamble}, preamble will not be assumed when operating upon \texttt{.tex} + files. - \cmhlistingsfromfile[style=lookForPreamble]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{lookForPreamble}{lst:lookForPreamble} + \cmhlistingsfromfile[style=lookForPreamble]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{lookForPreamble}{lst:lookForPreamble} \yamltitle{preambleCommandsBeforeEnvironments}{0|1} - Assuming that \texttt{latexindent.pl} is asked to operate upon the preamble of a - document, when this switch is set to \texttt{0} then environment code blocks will be - sought first, and then command code blocks. When this switch is set to \texttt{1}, - commands will be sought first. The example that first motivated this switch contained the - code given in \cref{lst:motivatepreambleCommandsBeforeEnvironments}. + Assuming that \texttt{latexindent.pl} is asked to operate upon the preamble of a + document, when this switch is set to \texttt{0} then environment code blocks will be + sought first, and then command code blocks. When this switch is set to \texttt{1}, + commands will be sought first. The example that first motivated this switch contained the + code given in \cref{lst:motivatepreambleCommandsBeforeEnvironments}. - \begin{cmhlistings}{Motivating \texttt{preambleCommandsBeforeEnvironments}}{lst:motivatepreambleCommandsBeforeEnvironments} + \begin{cmhlistings}{Motivating \texttt{preambleCommandsBeforeEnvironments}}{lst:motivatepreambleCommandsBeforeEnvironments} ... preheadhook={\begin{mdframed}[style=myframedstyle]}, postfoothook=\end{mdframed}, ... \end{cmhlistings} - \index{indentation!defaultIndent description} + \index{indentation!defaultIndent description} \subsection{Indentation and horizontal space} \yamltitle{defaultIndent}*{horizontal space} - This is the default indentation used in the absence of other details for the code block - with which we are working. The default value is \lstinline!\t! which means a tab; we will - explore customisation beyond \texttt{defaultIndent} in \vref{sec:noadd-indent-rules}. + This is the default indentation used in the absence of other details for the code block + with which we are working. The default value is \lstinline!\t! which means a tab; we will + explore customisation beyond \texttt{defaultIndent} in \vref{sec:noadd-indent-rules}. - If you're interested in experimenting with \texttt{latexindent.pl} then you can - \emph{remove} all indentation by setting \texttt{defaultIndent: ""}. + If you're interested in experimenting with \texttt{latexindent.pl} then you can + \emph{remove} all indentation by setting \texttt{defaultIndent: ""}. \yamltitle{removeTrailingWhitespace}*{fields}\label{yaml:removeTrailingWhitespace} - Trailing white space can be removed both \emph{before} and \emph{after} processing the - document, as detailed in \cref{lst:removeTrailingWhitespace}; each of the fields can take - the values \texttt{0} or \texttt{1}. See - \vref{lst:removeTWS-before,lst:env-mlb5-modAll,lst:env-mlb5-modAll-remove-WS} for before - and after results. Thanks to \cite{vosskuhle} for providing this feature. - - \begin{minipage}{.4\textwidth} - \cmhlistingsfromfile[style=removeTrailingWhitespace]{../defaultSettings.yaml}[before=\centering,yaml-TCB]{removeTrailingWhitespace}{lst:removeTrailingWhitespace} - \end{minipage}% - \hfill - \begin{minipage}{.5\textwidth} - \begin{yaml}[numbers=none]{removeTrailingWhitespace (alt)}[before=\centering]{lst:removeTrailingWhitespace-alt} + Trailing white space can be removed both \emph{before} and \emph{after} processing the + document, as detailed in \cref{lst:removeTrailingWhitespace}; each of the fields can take + the values \texttt{0} or \texttt{1}. See + \vref{lst:removeTWS-before,lst:env-mlb5-modAll,lst:env-mlb5-modAll-remove-WS} for before + and after results. Thanks to \cite{vosskuhle} for providing this feature. + + \begin{minipage}{.4\textwidth} + \cmhlistingsfromfile[style=removeTrailingWhitespace]{../defaultSettings.yaml}[before=\centering,yaml-TCB]{removeTrailingWhitespace}{lst:removeTrailingWhitespace} + \end{minipage}% + \hfill + \begin{minipage}{.5\textwidth} + \begin{yaml}[numbers=none]{removeTrailingWhitespace (alt)}[before=\centering]{lst:removeTrailingWhitespace-alt} removeTrailingWhitespace: 1 \end{yaml} - \end{minipage}% + \end{minipage}% - You can specify \texttt{removeTrailingWhitespace} simply as \texttt{0} or \texttt{1}, if - you wish; in this case, \announce{2017-06-28}{removeTrailingWhitespace} - \texttt{latexindent.pl} will set both \texttt{beforeProcessing} and - \texttt{afterProcessing} to the value you specify; see - \cref{lst:removeTrailingWhitespace-alt}.% + You can specify \texttt{removeTrailingWhitespace} simply as \texttt{0} or \texttt{1}, if + you wish; in this case, \announce{2017-06-28}{removeTrailingWhitespace} + \texttt{latexindent.pl} will set both \texttt{beforeProcessing} and + \texttt{afterProcessing} to the value you specify; see + \cref{lst:removeTrailingWhitespace-alt}.% -\subsection{Aligning at delimiters} +\subsection{Aligning at delimiters}\label{subsec:align-at-delimiters} \yamltitle{lookForAlignDelims}*{fields} - This contains a list of code blocks that are operated upon in a special way by - \texttt{latexindent.pl} (see \cref{lst:aligndelims:basic}). In fact, the fields in - \texttt{lookForAlignDelims} can actually take two different forms: the \emph{basic} - version is shown in \cref{lst:aligndelims:basic} and the \emph{advanced} version in - \cref{lst:aligndelims:advanced}; we will discuss each in turn. \index{delimiters!advanced - settings of lookForAlignDelims} - - \begin{yaml}[numbers=none]{\texttt{lookForAlignDelims} (basic)}[width=.8\linewidth,before=\centering]{lst:aligndelims:basic} + This contains a list of code blocks that are operated upon in a special way by + \texttt{latexindent.pl} (see \cref{lst:aligndelims:basic}). In fact, the fields in + \texttt{lookForAlignDelims} can actually take two different forms: the \emph{basic} + version is shown in \cref{lst:aligndelims:basic} and the \emph{advanced} version in + \cref{lst:aligndelims:advanced}; we will discuss each in turn. \index{delimiters!advanced + settings of lookForAlignDelims} + + \begin{yaml}[numbers=none]{\texttt{lookForAlignDelims} (basic)}[width=.8\linewidth,before=\centering]{lst:aligndelims:basic} lookForAlignDelims: tabular: 1 tabularx: 1 @@ -373,120 +373,120 @@ lookForAlignDelims: ... \end{yaml} - Specifying code blocks in this field instructs \texttt{latexindent.pl} to try and align - each column by its alignment delimiters. It does have some limitations (discussed further - in \cref{sec:knownlimitations}), but in many cases it will produce results such as those - in \cref{lst:tabularbefore:basic,lst:tabularafter:basic}. - - If you find that \texttt{latexindent.pl} does not perform satisfactorily on such - environments then you can set the relevant key to \texttt{0}, for example - \texttt{tabular: 0}; alternatively, if you just want to ignore \emph{specific} instances - of the environment, you could wrap them in something from \texttt{noIndentBlock} (see - \vref{lst:noIndentBlock}). - - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/tabular1.tex}{\texttt{tabular1.tex}}{lst:tabularbefore:basic} - \cmhlistingsfromfile{demonstrations/tabular1-default.tex}{\texttt{tabular1.tex} default output}{lst:tabularafter:basic} - \end{cmhtcbraster} - - If, for example, you wish to remove the alignment of the \lstinline!\\! within a - delimiter-aligned block, then the advanced form of \texttt{lookForAlignDelims} shown in - \cref{lst:aligndelims:advanced} is for you. \index{regular expressions!delimiterRegEx} - \index{regular expressions!ampersand alignment} \index{delimiters!default settings of - lookForAlignDelims} \index{delimiters!ampersand \&} \index{delimiters!advanced settings} - \index{delimiters!lookForAlignDelims} - - \cmhlistingsfromfile[style=lookForAlignDelims]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{lookForAlignDelims} (advanced)}{lst:aligndelims:advanced} - - Note that you can use a mixture of the basic and advanced form: in - \cref{lst:aligndelims:advanced} \texttt{tabular} and \texttt{tabularx} are advanced and - \texttt{longtable} is basic. When using the advanced form, each field should receive at - least 1 sub-field, and \emph{can} (but does not have to) receive any of the following - fields: - \begin{itemize} - \item \texttt{delims}: binary switch (0 or 1) equivalent to simply specifying, for - example, \texttt{tabular: 1} in the basic version shown in \cref{lst:aligndelims:basic}. - If \texttt{delims} is set to \texttt{0} then the align at ampersand routine will not be - called for this code block (default: 1); - \item \texttt{alignDoubleBackSlash}: binary switch (0 or 1) to determine if - \lstinline!\\! - should be aligned (default: 1); - \item \texttt{spacesBeforeDoubleBackSlash}: optionally,% - \announce{2018-01-13}*{update to spacesBeforeDoubleBackSlash in ampersand alignment} - specifies the number (integer $\geq$ 0) of spaces to be inserted before - \lstinline!\\! (default: 1); %\footnote{Previously this only activated if \texttt{alignDoubleBackSlash} was set to \texttt{0}.} - \item \announce{2017-06-19}{multiColumnGrouping} \texttt{multiColumnGrouping}: binary switch (0 - or 1) that details if \texttt{latexindent.pl} should group columns above and below a - \lstinline!\multicolumn! command (default: 0); - \item \announce{2017-06-19}{alignRowsWithoutMaxDelims} \texttt{alignRowsWithoutMaxDelims}: - binary switch (0 or 1) that details if rows that do not contain the maximum number of - delimeters should be formatted so as to have the ampersands aligned (default: 1); - \item \announce{2018-01-13}{spacesBeforeAmpersand in ampersand - alignment}\texttt{spacesBeforeAmpersand}: optionally specifies the number (integer $\geq$ - 0) of spaces to be placed \emph{before} ampersands (default: 1); - \item \announce{2018-01-13}{spacesAfterAmpersand in ampersand - alignment}\texttt{spacesAfterAmpersand}: optionally specifies the number (integer $\geq$ - 0) of spaces to be placed \emph{After} ampersands (default: 1); - \item \announce{2018-01-13}{justification of cells in ampersand - alignment}\texttt{justification}: optionally specifies the justification of each cell as - either \emph{left} or \emph{right} (default: left); - \item \announce{2020-03-21}{align final double back slash}{alignFinalDoubleBackSlash} - optionally specifies if the \emph{final} double back slash should be used for alignment - (default: 0); - \item \announce{2020-03-21}{don't measure feature}{dontMeasure} optionally specifies if - user-specified cells, rows or the largest entries should \emph{not} be measured (default: - 0); - \item \announce{2020-03-21}{delimiter RegEx feature}{delimiterRegEx} optionally specifies the - pattern matching to be used for the alignment delimeter (default: - \lstinline* '(?<!\\)(&)'*); - \item \announce{2020-03-21}{delimiter justification}{delimiterJustification} optionally - specifies the justification for the alignment delimeters (default: left); note that this - feature is only useful if you have delimiters of different lengths in the same column, - discussed in \cref{sec:delimiter-reg-ex}; - \item \announce{2021-12-13}{lookForChildCodeBlocks feature}{lookForChildCodeBlocks} optionally - instructs \texttt{latexindent.pl} to search for child code blocks or not (default: 1), - discussed in \cref{sec:lookForChildCodeBlocks}. - \end{itemize} - - We will explore most of these features using the file \texttt{tabular2.tex} in - \cref{lst:tabular2} (which contains a \lstinline!\multicolumn! command), and the YAML - files in \crefrange{lst:tabular2YAML}{lst:tabular8YAML}; we will explore - \texttt{alignFinalDoubleBackSlash} in \cref{lst:tabular4}; the \texttt{dontMeasure} - feature will be described in \cref{sec:dontMeasure}, and \texttt{delimiterRegEx} in - \cref{sec:delimiter-reg-ex}. - - \cmhlistingsfromfile{demonstrations/tabular2.tex}{\texttt{tabular2.tex}}{lst:tabular2} - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/tabular2.yaml}[yaml-TCB]{\texttt{tabular2.yaml}}{lst:tabular2YAML} - \end{minipage}% - \hfill - \begin{minipage}{.48\textwidth} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/tabular3.yaml}[yaml-TCB]{\texttt{tabular3.yaml}}{lst:tabular3YAML} - \end{minipage}% - - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/tabular4.yaml}[yaml-TCB]{\texttt{tabular4.yaml}}{lst:tabular4YAML} - \end{minipage}% - \hfill - \begin{minipage}{.48\textwidth} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/tabular5.yaml}[yaml-TCB]{\texttt{tabular5.yaml}}{lst:tabular5YAML} - \end{minipage}% - - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/tabular6.yaml}[yaml-TCB]{\texttt{tabular6.yaml}}{lst:tabular6YAML} - \end{minipage}% - \hfill - \begin{minipage}{.48\textwidth} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/tabular7.yaml}[yaml-TCB]{\texttt{tabular7.yaml}}{lst:tabular7YAML} - \end{minipage}% - - \begin{minipage}{.48\textwidth} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/tabular8.yaml}[yaml-TCB]{\texttt{tabular8.yaml}}{lst:tabular8YAML} - \end{minipage}% - - On running the commands \index{delimiters!spacing demonstration} \index{switches!-l - demonstration} - \begin{commandshell} + Specifying code blocks in this field instructs \texttt{latexindent.pl} to try and align + each column by its alignment delimiters. It does have some limitations (discussed further + in \cref{sec:knownlimitations}), but in many cases it will produce results such as those + in \cref{lst:tabularbefore:basic,lst:tabularafter:basic}. + + If you find that \texttt{latexindent.pl} does not perform satisfactorily on such + environments then you can set the relevant key to \texttt{0}, for example + \texttt{tabular: 0}; alternatively, if you just want to ignore \emph{specific} instances + of the environment, you could wrap them in something from \texttt{noIndentBlock} (see + \vref{lst:noIndentBlock}). + + \begin{cmhtcbraster} + \cmhlistingsfromfile{demonstrations/tabular1.tex}{\texttt{tabular1.tex}}{lst:tabularbefore:basic} + \cmhlistingsfromfile{demonstrations/tabular1-default.tex}{\texttt{tabular1.tex} default output}{lst:tabularafter:basic} + \end{cmhtcbraster} + + If, for example, you wish to remove the alignment of the \lstinline!\\! within a + delimiter-aligned block, then the advanced form of \texttt{lookForAlignDelims} shown in + \cref{lst:aligndelims:advanced} is for you. \index{regular expressions!delimiterRegEx} + \index{regular expressions!ampersand alignment} \index{delimiters!default settings of + lookForAlignDelims} \index{delimiters!ampersand \&} \index{delimiters!advanced settings} + \index{delimiters!lookForAlignDelims} + + \cmhlistingsfromfile[style=lookForAlignDelims]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{lookForAlignDelims} (advanced)}{lst:aligndelims:advanced} + + Note that you can use a mixture of the basic and advanced form: in + \cref{lst:aligndelims:advanced} \texttt{tabular} and \texttt{tabularx} are advanced and + \texttt{longtable} is basic. When using the advanced form, each field should receive at + least 1 sub-field, and \emph{can} (but does not have to) receive any of the following + fields: + \begin{itemize} + \item \texttt{delims}: binary switch (0 or 1) equivalent to simply specifying, for + example, \texttt{tabular: 1} in the basic version shown in \cref{lst:aligndelims:basic}. + If \texttt{delims} is set to \texttt{0} then the align at ampersand routine will not be + called for this code block (default: 1); + \item \texttt{alignDoubleBackSlash}: binary switch (0 or 1) to determine if + \lstinline!\\! + should be aligned (default: 1); + \item \texttt{spacesBeforeDoubleBackSlash}: optionally,% + \announce{2018-01-13}*{update to spacesBeforeDoubleBackSlash in ampersand alignment} + specifies the number (integer $\geq$ 0) of spaces to be inserted before + \lstinline!\\! (default: 1); %\footnote{Previously this only activated if \texttt{alignDoubleBackSlash} was set to \texttt{0}.} + \item \announce{2017-06-19}{multiColumnGrouping} \texttt{multiColumnGrouping}: binary switch (0 + or 1) that details if \texttt{latexindent.pl} should group columns above and below a + \lstinline!\multicolumn! command (default: 0); + \item \announce{2017-06-19}{alignRowsWithoutMaxDelims} \texttt{alignRowsWithoutMaxDelims}: + binary switch (0 or 1) that details if rows that do not contain the maximum number of + delimeters should be formatted so as to have the ampersands aligned (default: 1); + \item \announce{2018-01-13}{spacesBeforeAmpersand in ampersand + alignment}\texttt{spacesBeforeAmpersand}: optionally specifies the number (integer $\geq$ + 0) of spaces to be placed \emph{before} ampersands (default: 1); + \item \announce{2018-01-13}{spacesAfterAmpersand in ampersand + alignment}\texttt{spacesAfterAmpersand}: optionally specifies the number (integer $\geq$ + 0) of spaces to be placed \emph{After} ampersands (default: 1); + \item \announce{2018-01-13}{justification of cells in ampersand + alignment}\texttt{justification}: optionally specifies the justification of each cell as + either \emph{left} or \emph{right} (default: left); + \item \announce{2020-03-21}{align final double back slash}{alignFinalDoubleBackSlash} + optionally specifies if the \emph{final} double back slash should be used for alignment + (default: 0); + \item \announce{2020-03-21}{don't measure feature}{dontMeasure} optionally specifies if + user-specified cells, rows or the largest entries should \emph{not} be measured (default: + 0); + \item \announce{2020-03-21}{delimiter RegEx feature}{delimiterRegEx} optionally specifies the + pattern matching to be used for the alignment delimeter (default: + \lstinline* '(?<!\\)(&)'*); + \item \announce{2020-03-21}{delimiter justification}{delimiterJustification} optionally + specifies the justification for the alignment delimeters (default: left); note that this + feature is only useful if you have delimiters of different lengths in the same column, + discussed in \cref{sec:delimiter-reg-ex}; + \item \announce{2021-12-13}{lookForChildCodeBlocks feature}{lookForChildCodeBlocks} optionally + instructs \texttt{latexindent.pl} to search for child code blocks or not (default: 1), + discussed in \cref{sec:lookForChildCodeBlocks}. + \end{itemize} + + We will explore most of these features using the file \texttt{tabular2.tex} in + \cref{lst:tabular2} (which contains a \lstinline!\multicolumn! command), and the YAML + files in \crefrange{lst:tabular2YAML}{lst:tabular8YAML}; we will explore + \texttt{alignFinalDoubleBackSlash} in \cref{lst:tabular4}; the \texttt{dontMeasure} + feature will be described in \cref{sec:dontMeasure}, and \texttt{delimiterRegEx} in + \cref{sec:delimiter-reg-ex}. + + \cmhlistingsfromfile{demonstrations/tabular2.tex}{\texttt{tabular2.tex}}{lst:tabular2} + \begin{minipage}{.45\textwidth} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/tabular2.yaml}[yaml-TCB]{\texttt{tabular2.yaml}}{lst:tabular2YAML} + \end{minipage}% + \hfill + \begin{minipage}{.48\textwidth} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/tabular3.yaml}[yaml-TCB]{\texttt{tabular3.yaml}}{lst:tabular3YAML} + \end{minipage}% + + \begin{minipage}{.45\textwidth} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/tabular4.yaml}[yaml-TCB]{\texttt{tabular4.yaml}}{lst:tabular4YAML} + \end{minipage}% + \hfill + \begin{minipage}{.48\textwidth} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/tabular5.yaml}[yaml-TCB]{\texttt{tabular5.yaml}}{lst:tabular5YAML} + \end{minipage}% + + \begin{minipage}{.45\textwidth} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/tabular6.yaml}[yaml-TCB]{\texttt{tabular6.yaml}}{lst:tabular6YAML} + \end{minipage}% + \hfill + \begin{minipage}{.48\textwidth} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/tabular7.yaml}[yaml-TCB]{\texttt{tabular7.yaml}}{lst:tabular7YAML} + \end{minipage}% + + \begin{minipage}{.48\textwidth} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/tabular8.yaml}[yaml-TCB]{\texttt{tabular8.yaml}}{lst:tabular8YAML} + \end{minipage}% + + On running the commands \index{delimiters!spacing demonstration} \index{switches!-l + demonstration} + \begin{commandshell} latexindent.pl tabular2.tex latexindent.pl tabular2.tex -l tabular2.yaml latexindent.pl tabular2.tex -l tabular3.yaml @@ -496,810 +496,809 @@ latexindent.pl tabular2.tex -l tabular2.yaml,tabular6.yaml latexindent.pl tabular2.tex -l tabular2.yaml,tabular7.yaml latexindent.pl tabular2.tex -l tabular2.yaml,tabular8.yaml \end{commandshell} - we obtain the respective outputs given in - \crefrange{lst:tabular2-default}{lst:tabular2-mod8}. - - \begin{widepage} - \cmhlistingsfromfile{demonstrations/tabular2-default.tex}{\texttt{tabular2.tex} default output}{lst:tabular2-default} - \cmhlistingsfromfile{demonstrations/tabular2-mod2.tex}{\texttt{tabular2.tex} using \cref{lst:tabular2YAML}}{lst:tabular2-mod2} - \cmhlistingsfromfile{demonstrations/tabular2-mod3.tex}{\texttt{tabular2.tex} using \cref{lst:tabular3YAML}}{lst:tabular2-mod3} - \cmhlistingsfromfile{demonstrations/tabular2-mod4.tex}{\texttt{tabular2.tex} using \cref{lst:tabular2YAML,lst:tabular4YAML}}{lst:tabular2-mod4} - \cmhlistingsfromfile{demonstrations/tabular2-mod5.tex}{\texttt{tabular2.tex} using \cref{lst:tabular2YAML,lst:tabular5YAML}}{lst:tabular2-mod5} - \cmhlistingsfromfile{demonstrations/tabular2-mod6.tex}{\texttt{tabular2.tex} using \cref{lst:tabular2YAML,lst:tabular6YAML}}{lst:tabular2-mod6} - \cmhlistingsfromfile{demonstrations/tabular2-mod7.tex}{\texttt{tabular2.tex} using \cref{lst:tabular2YAML,lst:tabular7YAML}}{lst:tabular2-mod7} - \cmhlistingsfromfile{demonstrations/tabular2-mod8.tex}{\texttt{tabular2.tex} using \cref{lst:tabular2YAML,lst:tabular8YAML}}{lst:tabular2-mod8} - \end{widepage} - - Notice in particular: - \begin{itemize} - \item in both \cref{lst:tabular2-default,lst:tabular2-mod2} all rows have been aligned at the - ampersand, even those that do not contain the maximum number of ampersands (3 ampersands, - in this case); - \item in \cref{lst:tabular2-default} the columns have been aligned at the ampersand; - \item in \cref{lst:tabular2-mod2} the \lstinline!\multicolumn! command has grouped the $2$ - columns beneath \emph{and} above it, because \texttt{multiColumnGrouping} is set to $1$ - in \cref{lst:tabular2YAML}; - \item in \cref{lst:tabular2-mod3} rows~3 and~6 have \emph{not} been aligned at the ampersand, - because \texttt{alignRowsWithoutMaxDelims} has been to set to $0$ in - \cref{lst:tabular3YAML}; however, the \lstinline!\\! \emph{have} still been aligned; - \item in \cref{lst:tabular2-mod4} the columns beneath and above the \lstinline!\multicolumn! - commands have been grouped (because \texttt{multiColumnGrouping} is set to $1$), and - there are at least $4$ spaces \emph{before} each aligned ampersand because - \texttt{spacesBeforeAmpersand} is set to $4$; - \item in \cref{lst:tabular2-mod5} the columns beneath and above the \lstinline!\multicolumn! - commands have been grouped (because \texttt{multiColumnGrouping} is set to $1$), and - there are at least $4$ spaces \emph{after} each aligned ampersand because - \texttt{spacesAfterAmpersand} is set to $4$; - \item in \cref{lst:tabular2-mod6} the \lstinline!\\! have \emph{not} been aligned, because - \texttt{alignDoubleBackSlash} is set to \texttt{0}, otherwise the output is the same as - \cref{lst:tabular2-mod2}; - \item in \cref{lst:tabular2-mod7} the \lstinline!\\! \emph{have} been aligned, and because - \texttt{spacesBeforeDoubleBackSlash} is set to \texttt{0}, there are no spaces ahead of - them; the output is otherwise the same as \cref{lst:tabular2-mod2}; - \item in \cref{lst:tabular2-mod8} the cells have been \emph{right}-justified; note that cells - above and below the \lstinline!\multicol! statements have still been group correctly, - because of the settings in \cref{lst:tabular2YAML}. - \end{itemize} + we obtain the respective outputs given in + \crefrange{lst:tabular2-default}{lst:tabular2-mod8}. + + \begin{widepage} + \cmhlistingsfromfile{demonstrations/tabular2-default.tex}{\texttt{tabular2.tex} default output}{lst:tabular2-default} + \cmhlistingsfromfile{demonstrations/tabular2-mod2.tex}{\texttt{tabular2.tex} using \cref{lst:tabular2YAML}}{lst:tabular2-mod2} + \cmhlistingsfromfile{demonstrations/tabular2-mod3.tex}{\texttt{tabular2.tex} using \cref{lst:tabular3YAML}}{lst:tabular2-mod3} + \cmhlistingsfromfile{demonstrations/tabular2-mod4.tex}{\texttt{tabular2.tex} using \cref{lst:tabular2YAML,lst:tabular4YAML}}{lst:tabular2-mod4} + \cmhlistingsfromfile{demonstrations/tabular2-mod5.tex}{\texttt{tabular2.tex} using \cref{lst:tabular2YAML,lst:tabular5YAML}}{lst:tabular2-mod5} + \cmhlistingsfromfile{demonstrations/tabular2-mod6.tex}{\texttt{tabular2.tex} using \cref{lst:tabular2YAML,lst:tabular6YAML}}{lst:tabular2-mod6} + \cmhlistingsfromfile{demonstrations/tabular2-mod7.tex}{\texttt{tabular2.tex} using \cref{lst:tabular2YAML,lst:tabular7YAML}}{lst:tabular2-mod7} + \cmhlistingsfromfile{demonstrations/tabular2-mod8.tex}{\texttt{tabular2.tex} using \cref{lst:tabular2YAML,lst:tabular8YAML}}{lst:tabular2-mod8} + \end{widepage} + + Notice in particular: + \begin{itemize} + \item in both \cref{lst:tabular2-default,lst:tabular2-mod2} all rows have been aligned at the + ampersand, even those that do not contain the maximum number of ampersands (3 ampersands, + in this case); + \item in \cref{lst:tabular2-default} the columns have been aligned at the ampersand; + \item in \cref{lst:tabular2-mod2} the \lstinline!\multicolumn! command has grouped the $2$ + columns beneath \emph{and} above it, because \texttt{multiColumnGrouping} is set to $1$ + in \cref{lst:tabular2YAML}; + \item in \cref{lst:tabular2-mod3} rows~3 and~6 have \emph{not} been aligned at the ampersand, + because \texttt{alignRowsWithoutMaxDelims} has been to set to $0$ in + \cref{lst:tabular3YAML}; however, the \lstinline!\\! \emph{have} still been aligned; + \item in \cref{lst:tabular2-mod4} the columns beneath and above the \lstinline!\multicolumn! + commands have been grouped (because \texttt{multiColumnGrouping} is set to $1$), and + there are at least $4$ spaces \emph{before} each aligned ampersand because + \texttt{spacesBeforeAmpersand} is set to $4$; + \item in \cref{lst:tabular2-mod5} the columns beneath and above the \lstinline!\multicolumn! + commands have been grouped (because \texttt{multiColumnGrouping} is set to $1$), and + there are at least $4$ spaces \emph{after} each aligned ampersand because + \texttt{spacesAfterAmpersand} is set to $4$; + \item in \cref{lst:tabular2-mod6} the \lstinline!\\! have \emph{not} been aligned, because + \texttt{alignDoubleBackSlash} is set to \texttt{0}, otherwise the output is the same as + \cref{lst:tabular2-mod2}; + \item in \cref{lst:tabular2-mod7} the \lstinline!\\! \emph{have} been aligned, and because + \texttt{spacesBeforeDoubleBackSlash} is set to \texttt{0}, there are no spaces ahead of + them; the output is otherwise the same as \cref{lst:tabular2-mod2}; + \item in \cref{lst:tabular2-mod8} the cells have been \emph{right}-justified; note that cells + above and below the \lstinline!\multicol! statements have still been group correctly, + because of the settings in \cref{lst:tabular2YAML}. + \end{itemize} \subsubsection{lookForAlignDelims: spacesBeforeAmpersand} - The \texttt{spacesBeforeAmpersand} \announce{2021-06-19}*{spacesBeforeAmpersand leading - blank column upgrade} can be specified in a few different ways. The \emph{basic} form is - demonstrated in \cref{lst:tabular4YAML}, but we can customise the behaviour further by - specifying if we would like this value to change if it encounters a \emph{leading blank - column}; that is, when the first column contains only zero-width entries. We refer to - this as the \emph{advanced} form.% - - We demonstrate this feature in relation to \cref{lst:aligned1}; upon running the - following command - \begin{commandshell} + The \texttt{spacesBeforeAmpersand} \announce{2021-06-19}*{spacesBeforeAmpersand leading + blank column upgrade} can be specified in a few different ways. The \emph{basic} form is + demonstrated in \cref{lst:tabular4YAML}, but we can customise the behaviour further by + specifying if we would like this value to change if it encounters a \emph{leading blank + column}; that is, when the first column contains only zero-width entries. We refer to + this as the \emph{advanced} form.% + + We demonstrate this feature in relation to \cref{lst:aligned1}; upon running the + following command + \begin{commandshell} latexindent.pl aligned1.tex -o=+-default \end{commandshell} - then we receive the default output given in \cref{lst:aligned1-default}. - - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/aligned1.tex}{\texttt{aligned1.tex}}{lst:aligned1} - \cmhlistingsfromfile{demonstrations/aligned1-default.tex}{\texttt{aligned1-default.tex}}{lst:aligned1-default} - \end{cmhtcbraster} - - The settings in \crefrange{lst:sba1}{lst:sba4} are all equivlanent; we have used the - not-yet discussed \texttt{noAdditionalIndent} field (see \vref{sec:noadd-indent-rules}) - which will assist in the demonstration in what follows. - \begin{cmhtcbraster}[raster columns=2, ] - \cmhlistingsfromfile{demonstrations/sba1.yaml}[yaml-TCB]{\texttt{sba1.yaml}}{lst:sba1} - \cmhlistingsfromfile{demonstrations/sba2.yaml}[yaml-TCB]{\texttt{sba2.yaml}}{lst:sba2} - \cmhlistingsfromfile{demonstrations/sba3.yaml}[yaml-TCB]{\texttt{sba3.yaml}}{lst:sba3} - \cmhlistingsfromfile{demonstrations/sba4.yaml}[yaml-TCB]{\texttt{sba4.yaml}}{lst:sba4} - \end{cmhtcbraster} - Upon running the following commands - \begin{commandshell} + then we receive the default output given in \cref{lst:aligned1-default}. + + \begin{cmhtcbraster} + \cmhlistingsfromfile{demonstrations/aligned1.tex}{\texttt{aligned1.tex}}{lst:aligned1} + \cmhlistingsfromfile{demonstrations/aligned1-default.tex}{\texttt{aligned1-default.tex}}{lst:aligned1-default} + \end{cmhtcbraster} + + The settings in \crefrange{lst:sba1}{lst:sba4} are all equivlanent; we have used the + not-yet discussed \texttt{noAdditionalIndent} field (see \vref{sec:noadd-indent-rules}) + which will assist in the demonstration in what follows. + \begin{cmhtcbraster}[raster columns=2, ] + \cmhlistingsfromfile{demonstrations/sba1.yaml}[yaml-TCB]{\texttt{sba1.yaml}}{lst:sba1} + \cmhlistingsfromfile{demonstrations/sba2.yaml}[yaml-TCB]{\texttt{sba2.yaml}}{lst:sba2} + \cmhlistingsfromfile{demonstrations/sba3.yaml}[yaml-TCB]{\texttt{sba3.yaml}}{lst:sba3} + \cmhlistingsfromfile{demonstrations/sba4.yaml}[yaml-TCB]{\texttt{sba4.yaml}}{lst:sba4} + \end{cmhtcbraster} + Upon running the following commands + \begin{commandshell} latexindent.pl aligned1.tex -l sba1.yaml latexindent.pl aligned1.tex -l sba2.yaml latexindent.pl aligned1.tex -l sba3.yaml latexindent.pl aligned1.tex -l sba4.yaml \end{commandshell} - then we receive the (same) output given in \cref{lst:aligned1-mod1}; we note that there - is \emph{one space} before each ampersand. - - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/aligned1-mod1.tex}{\texttt{aligned1-mod1.tex}}{lst:aligned1-mod1} - \end{cmhtcbraster} - - We note in particular: - \begin{itemize} - \item \cref{lst:sba1} demonstrates the \emph{basic} form for - \texttt{lookForAlignDelims}; in this case, - the default values are specified as in \vref{lst:aligndelims:advanced}; - \item \cref{lst:sba2} demonstrates the \emph{advanced} form for - \texttt{lookForAlignDelims} - and specified \texttt{spacesBeforeAmpersand}. The default value is \texttt{1}; - \item \cref{lst:sba3} demonstrates the new \emph{advanced} way to specify - \texttt{spacesBeforeAmpersand}, and - for us to set the \texttt{default} value that sets the number of spaces before ampersands - which are \emph{not} in leading blank columns. The default value is \texttt{1}. - - We note that \texttt{leadingBlankColumn} has not been specified in \cref{lst:sba3}, and - it will inherit the value from \texttt{default}; - \item \cref{lst:sba4} demonstrates spaces to be used before amperands for - \emph{leading blank columns}. - We note that \emph{default} has not been specified, and it will be set to \texttt{1} by - default. - \end{itemize} - We can customise the space before the ampersand in the \emph{leading blank column} of - \cref{lst:aligned1-mod1} by using either of \cref{lst:sba5,lst:sba6}, which are - equivalent. - - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/sba5.yaml}[yaml-TCB]{\texttt{sba5.yaml}}{lst:sba5} - \cmhlistingsfromfile{demonstrations/sba6.yaml}[yaml-TCB]{\texttt{sba6.yaml}}{lst:sba6} - \end{cmhtcbraster} - - Upon running - \begin{commandshell} + then we receive the (same) output given in \cref{lst:aligned1-mod1}; we note that there + is \emph{one space} before each ampersand. + + \begin{cmhtcbraster} + \cmhlistingsfromfile{demonstrations/aligned1-mod1.tex}{\texttt{aligned1-mod1.tex}}{lst:aligned1-mod1} + \end{cmhtcbraster} + + We note in particular: + \begin{itemize} + \item \cref{lst:sba1} demonstrates the \emph{basic} form for + \texttt{lookForAlignDelims}; in this case, + the default values are specified as in \vref{lst:aligndelims:advanced}; + \item \cref{lst:sba2} demonstrates the \emph{advanced} form for + \texttt{lookForAlignDelims} + and specified \texttt{spacesBeforeAmpersand}. The default value is \texttt{1}; + \item \cref{lst:sba3} demonstrates the new \emph{advanced} way to specify + \texttt{spacesBeforeAmpersand}, and + for us to set the \texttt{default} value that sets the number of spaces before ampersands + which are \emph{not} in leading blank columns. The default value is \texttt{1}. + + We note that \texttt{leadingBlankColumn} has not been specified in \cref{lst:sba3}, and + it will inherit the value from \texttt{default}; + \item \cref{lst:sba4} demonstrates spaces to be used before amperands for + \emph{leading blank columns}. + We note that \emph{default} has not been specified, and it will be set to \texttt{1} by + default. + \end{itemize} + We can customise the space before the ampersand in the \emph{leading blank column} of + \cref{lst:aligned1-mod1} by using either of \cref{lst:sba5,lst:sba6}, which are + equivalent. + + \begin{cmhtcbraster} + \cmhlistingsfromfile{demonstrations/sba5.yaml}[yaml-TCB]{\texttt{sba5.yaml}}{lst:sba5} + \cmhlistingsfromfile{demonstrations/sba6.yaml}[yaml-TCB]{\texttt{sba6.yaml}}{lst:sba6} + \end{cmhtcbraster} + + Upon running + \begin{commandshell} latexindent.pl aligned1.tex -l sba5.yaml latexindent.pl aligned1.tex -l sba6.yaml \end{commandshell} - then we receive the (same) output given in \cref{lst:aligned1-mod5}. We note that the - space before the ampersand in the \emph{leading blank column} has been set to \texttt{0} - by \cref{lst:sba6}. - - We can demonstrated this feature further using the settings in \cref{lst:sba7} which give - the output in \cref{lst:aligned1-mod7}. - - \begin{cmhtcbraster}[raster columns=3, - raster left skip=-3.75cm, - raster right skip=-2cm,] - \cmhlistingsfromfile{demonstrations/aligned1-mod5.tex}{\texttt{aligned1-mod5.tex}}{lst:aligned1-mod5} - \cmhlistingsfromfile{demonstrations/aligned1-mod7.tex}{\texttt{aligned1.tex} using \cref{lst:sba7}}{lst:aligned1-mod7} - \cmhlistingsfromfile{demonstrations/sba7.yaml}[yaml-TCB]{\texttt{sba7.yaml}}{lst:sba7} - \end{cmhtcbraster} + then we receive the (same) output given in \cref{lst:aligned1-mod5}. We note that the + space before the ampersand in the \emph{leading blank column} has been set to \texttt{0} + by \cref{lst:sba6}. + + We can demonstrated this feature further using the settings in \cref{lst:sba7} which give + the output in \cref{lst:aligned1-mod7}. + + \begin{cmhtcbraster}[raster columns=3, + raster left skip=-3.75cm, + raster right skip=-2cm,] + \cmhlistingsfromfile{demonstrations/aligned1-mod5.tex}{\texttt{aligned1-mod5.tex}}{lst:aligned1-mod5} + \cmhlistingsfromfile{demonstrations/aligned1-mod7.tex}{\texttt{aligned1.tex} using \cref{lst:sba7}}{lst:aligned1-mod7} + \cmhlistingsfromfile{demonstrations/sba7.yaml}[yaml-TCB]{\texttt{sba7.yaml}}{lst:sba7} + \end{cmhtcbraster} \subsubsection{lookForAlignDelims: alignFinalDoubleBackSlash} - We explore \announce{2020-03-21}{alignFinalDoubleBackSlash demonstration} the - \texttt{alignFinalDoubleBackSlash} feature by using the file in \cref{lst:tabular4}. Upon - running the following commands \index{delimiters!double backslash demonstration} - \index{switches!-y demonstration} \index{switches!-o demonstration}% - \begin{commandshell} + We explore \announce{2020-03-21}{alignFinalDoubleBackSlash demonstration} the + \texttt{alignFinalDoubleBackSlash} feature by using the file in \cref{lst:tabular4}. Upon + running the following commands \index{delimiters!double backslash demonstration} + \index{switches!-y demonstration} \index{switches!-o demonstration}% + \begin{commandshell} latexindent.pl tabular4.tex -o=+-default latexindent.pl tabular4.tex -o=+-FDBS -y="lookForAlignDelims:tabular:alignFinalDoubleBackSlash:1" \end{commandshell} - then we receive the respective outputs given in \cref{lst:tabular4-default} and - \cref{lst:tabular4-FDBS}. - - \begin{cmhtcbraster}[raster columns=3, - raster left skip=-3.75cm, - raster right skip=-2cm,] - \cmhlistingsfromfile{demonstrations/tabular4.tex}{\texttt{tabular4.tex}}{lst:tabular4} - \cmhlistingsfromfile{demonstrations/tabular4-default.tex}{\texttt{tabular4-default.tex}}{lst:tabular4-default} - \cmhlistingsfromfile{demonstrations/tabular4-FDBS.tex}{\texttt{tabular4-FDBS.tex}}{lst:tabular4-FDBS} - \end{cmhtcbraster} - - We note that in: - \begin{itemize} - \item \cref{lst:tabular4-default}, by default, the \emph{first} set of double back - slashes in the first row of the \texttt{tabular} environment have been used for - alignment; - \item \cref{lst:tabular4-FDBS}, the \emph{final} set of double back slashes in the - first row have been used, because we specified \texttt{alignFinalDoubleBackSlash} as 1. - \end{itemize} - - As of Version 3.0, the alignment routine works on mandatory and optional arguments within - commands, and also within `special' code blocks (see \texttt{specialBeginEnd} on - \cpageref{yaml:specialBeginEnd}); for example, assuming that you have a command called - \lstinline!\matrix! and that it is populated within \texttt{lookForAlignDelims} (which it - is, by default), and that you run the command - \begin{commandshell} + then we receive the respective outputs given in \cref{lst:tabular4-default} and + \cref{lst:tabular4-FDBS}. + + \begin{cmhtcbraster}[raster columns=3, + raster left skip=-3.75cm, + raster right skip=-2cm,] + \cmhlistingsfromfile{demonstrations/tabular4.tex}{\texttt{tabular4.tex}}{lst:tabular4} + \cmhlistingsfromfile{demonstrations/tabular4-default.tex}{\texttt{tabular4-default.tex}}{lst:tabular4-default} + \cmhlistingsfromfile{demonstrations/tabular4-FDBS.tex}{\texttt{tabular4-FDBS.tex}}{lst:tabular4-FDBS} + \end{cmhtcbraster} + + We note that in: + \begin{itemize} + \item \cref{lst:tabular4-default}, by default, the \emph{first} set of double back + slashes in the first row of the \texttt{tabular} environment have been used for + alignment; + \item \cref{lst:tabular4-FDBS}, the \emph{final} set of double back slashes in the + first row have been used, because we specified \texttt{alignFinalDoubleBackSlash} as 1. + \end{itemize} + + As of Version 3.0, the alignment routine works on mandatory and optional arguments within + commands, and also within `special' code blocks (see \texttt{specialBeginEnd} on + \cpageref{yaml:specialBeginEnd}); for example, assuming that you have a command called + \lstinline!\matrix! and that it is populated within \texttt{lookForAlignDelims} (which it + is, by default), and that you run the command + \begin{commandshell} latexindent.pl matrix1.tex \end{commandshell} - then the before-and-after results shown in \cref{lst:matrixbefore,lst:matrixafter} are - achievable by default. - - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/matrix1.tex}{\texttt{matrix1.tex}}{lst:matrixbefore} - \cmhlistingsfromfile{demonstrations/matrix1-default.tex}{\texttt{matrix1.tex} default output}{lst:matrixafter} - \end{cmhtcbraster} - - If you have blocks of code that you wish to align at the \& character that are \emph{not} - wrapped in, for example, \lstinline!\begin{tabular}! \ldots \lstinline!\end{tabular}!, - then you can use the mark up illustrated in \cref{lst:alignmentmarkup}; the default - output is shown in \cref{lst:alignmentmarkup-default}. Note that the \lstinline!%*! must - be next to each other, but that there can be any number of spaces (possibly none) between - the \lstinline!*! and \lstinline!\begin{tabular}!; note also that you may use any - environment name that you have specified in \texttt{lookForAlignDelims}. - - \begin{cmhtcbraster}[raster left skip=-1.5cm,] - \cmhlistingsfromfile{demonstrations/align-block.tex}{\texttt{align-block.tex}}{lst:alignmentmarkup} - \cmhlistingsfromfile{demonstrations/align-block-default.tex}{\texttt{align-block.tex} default output}{lst:alignmentmarkup-default} - \end{cmhtcbraster} - - With reference to \vref{tab:code-blocks} and the, yet undiscussed, fields of - \texttt{noAdditionalIndent} and \texttt{indentRules} (see \vref{sec:noadd-indent-rules}), - these comment-marked blocks are considered \texttt{environments}. + then the before-and-after results shown in \cref{lst:matrixbefore,lst:matrixafter} are + achievable by default. + + \begin{cmhtcbraster} + \cmhlistingsfromfile{demonstrations/matrix1.tex}{\texttt{matrix1.tex}}{lst:matrixbefore} + \cmhlistingsfromfile{demonstrations/matrix1-default.tex}{\texttt{matrix1.tex} default output}{lst:matrixafter} + \end{cmhtcbraster} + + If you have blocks of code that you wish to align at the \& character that are \emph{not} + wrapped in, for example, \lstinline!\begin{tabular}! \ldots \lstinline!\end{tabular}!, + then you can use the mark up illustrated in \cref{lst:alignmentmarkup}; the default + output is shown in \cref{lst:alignmentmarkup-default}. Note that the \lstinline!%*! must + be next to each other, but that there can be any number of spaces (possibly none) between + the \lstinline!*! and \lstinline!\begin{tabular}!; note also that you may use any + environment name that you have specified in \texttt{lookForAlignDelims}. + + \begin{cmhtcbraster}[raster left skip=-1.5cm,] + \cmhlistingsfromfile{demonstrations/align-block.tex}{\texttt{align-block.tex}}{lst:alignmentmarkup} + \cmhlistingsfromfile{demonstrations/align-block-default.tex}{\texttt{align-block.tex} default output}{lst:alignmentmarkup-default} + \end{cmhtcbraster} + + With reference to \vref{tab:code-blocks} and the, yet undiscussed, fields of + \texttt{noAdditionalIndent} and \texttt{indentRules} (see \vref{sec:noadd-indent-rules}), + these comment-marked blocks are considered \texttt{environments}. \subsubsection{lookForAlignDelims: the dontMeasure feature}\label{sec:dontMeasure} - The \announce{2020-03-21}{don't measure feature} \texttt{lookForAlignDelims} field can, - optionally, receive the \texttt{dontMeasure} option which can be specified in a few - different ways. We will explore this feature in relation to the code given in - \cref{lst:tabular-DM}; the default output is shown in \cref{lst:tabular-DM-default}. - \index{delimiters!dontMeasure feature}% - - \begin{cmhtcbraster}[raster left skip=-1.5cm,] - \cmhlistingsfromfile{demonstrations/tabular-DM.tex}{\texttt{tabular-DM.tex}}{lst:tabular-DM} - \cmhlistingsfromfile{demonstrations/tabular-DM-default.tex}{\texttt{tabular-DM.tex} default output}{lst:tabular-DM-default} - \end{cmhtcbraster} - - The \texttt{dontMeasure} field can be specified as \texttt{largest}, and in which case, - the largest element will not be measured; with reference to the YAML file given in - \cref{lst:dontMeasure1}, we can run the command \index{switches!-l demonstration} - \begin{commandshell} + The \announce{2020-03-21}{don't measure feature} \texttt{lookForAlignDelims} field can, + optionally, receive the \texttt{dontMeasure} option which can be specified in a few + different ways. We will explore this feature in relation to the code given in + \cref{lst:tabular-DM}; the default output is shown in \cref{lst:tabular-DM-default}. + \index{delimiters!dontMeasure feature}% + + \begin{cmhtcbraster}[raster left skip=-1.5cm,] + \cmhlistingsfromfile{demonstrations/tabular-DM.tex}{\texttt{tabular-DM.tex}}{lst:tabular-DM} + \cmhlistingsfromfile{demonstrations/tabular-DM-default.tex}{\texttt{tabular-DM.tex} default output}{lst:tabular-DM-default} + \end{cmhtcbraster} + + The \texttt{dontMeasure} field can be specified as \texttt{largest}, and in which case, + the largest element will not be measured; with reference to the YAML file given in + \cref{lst:dontMeasure1}, we can run the command \index{switches!-l demonstration} + \begin{commandshell} latexindent.pl tabular-DM.tex -l=dontMeasure1.yaml \end{commandshell} - and receive the output given in \cref{lst:tabular-DM-mod1}. + and receive the output given in \cref{lst:tabular-DM-mod1}. - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/tabular-DM-mod1.tex}{\texttt{tabular-DM.tex} using \cref{lst:dontMeasure1}}{lst:tabular-DM-mod1} - \cmhlistingsfromfile{demonstrations/dontMeasure1.yaml}[yaml-TCB]{\texttt{dontMeasure1.yaml}}{lst:dontMeasure1} - \end{cmhtcbraster} + \begin{cmhtcbraster} + \cmhlistingsfromfile{demonstrations/tabular-DM-mod1.tex}{\texttt{tabular-DM.tex} using \cref{lst:dontMeasure1}}{lst:tabular-DM-mod1} + \cmhlistingsfromfile{demonstrations/dontMeasure1.yaml}[yaml-TCB]{\texttt{dontMeasure1.yaml}}{lst:dontMeasure1} + \end{cmhtcbraster} - We note that the \emph{largest} column entries have not contributed to the measuring - routine. + We note that the \emph{largest} column entries have not contributed to the measuring + routine. - The \texttt{dontMeasure} field can also be specified in the form demonstrated in - \cref{lst:dontMeasure2}. On running the following commands, \index{switches!-l - demonstration} - \begin{commandshell} + The \texttt{dontMeasure} field can also be specified in the form demonstrated in + \cref{lst:dontMeasure2}. On running the following commands, \index{switches!-l + demonstration} + \begin{commandshell} latexindent.pl tabular-DM.tex -l=dontMeasure2.yaml \end{commandshell} - we receive the output in \cref{lst:tabular-DM-mod2}. \index{regular - expressions!dontMeasure feature, cell} + we receive the output in \cref{lst:tabular-DM-mod2}. \index{regular + expressions!dontMeasure feature, cell} - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/tabular-DM-mod2.tex}{\texttt{tabular-DM.tex} using \cref{lst:dontMeasure2} or \cref{lst:dontMeasure3}}{lst:tabular-DM-mod2} - \cmhlistingsfromfile{demonstrations/dontMeasure2.yaml}[yaml-TCB]{\texttt{dontMeasure2.yaml}}{lst:dontMeasure2} - \end{cmhtcbraster} + \begin{cmhtcbraster} + \cmhlistingsfromfile{demonstrations/tabular-DM-mod2.tex}{\texttt{tabular-DM.tex} using \cref{lst:dontMeasure2} or \cref{lst:dontMeasure3}}{lst:tabular-DM-mod2} + \cmhlistingsfromfile{demonstrations/dontMeasure2.yaml}[yaml-TCB]{\texttt{dontMeasure2.yaml}}{lst:dontMeasure2} + \end{cmhtcbraster} - We note that in \cref{lst:dontMeasure2} we have specified entries not to be measured, one - entry per line. + We note that in \cref{lst:dontMeasure2} we have specified entries not to be measured, one + entry per line. - The \texttt{dontMeasure} field can also be specified in the forms demonstrated in - \cref{lst:dontMeasure3} and \cref{lst:dontMeasure4}. Upon running the commands - \index{switches!-l demonstration} - \begin{commandshell} + The \texttt{dontMeasure} field can also be specified in the forms demonstrated in + \cref{lst:dontMeasure3} and \cref{lst:dontMeasure4}. Upon running the commands + \index{switches!-l demonstration} + \begin{commandshell} latexindent.pl tabular-DM.tex -l=dontMeasure3.yaml latexindent.pl tabular-DM.tex -l=dontMeasure4.yaml \end{commandshell} - we receive the output given in \cref{lst:tabular-DM-mod3} \index{regular - expressions!lowercase alph a-z} - \begin{cmhtcbraster}[raster columns=3, - raster left skip=-3.5cm, - raster right skip=-2cm, - raster column skip=.03\linewidth] - \cmhlistingsfromfile{demonstrations/tabular-DM-mod3.tex}{\texttt{tabular-DM.tex} using \cref{lst:dontMeasure3} or \cref{lst:dontMeasure3}}{lst:tabular-DM-mod3} - \cmhlistingsfromfile{demonstrations/dontMeasure3.yaml}[yaml-TCB]{\texttt{dontMeasure3.yaml}}{lst:dontMeasure3} - \cmhlistingsfromfile{demonstrations/dontMeasure4.yaml}[yaml-TCB]{\texttt{dontMeasure4.yaml}}{lst:dontMeasure4} - \end{cmhtcbraster} - We note that in: - \begin{itemize} - \item \cref{lst:dontMeasure3} we have specified entries not to be measured, each one has a - \emph{string} in the \texttt{this} - field, together with an optional specification of \texttt{applyTo} as \texttt{cell}; - \item \cref{lst:dontMeasure4} we have specified entries not to be measured as a - \emph{regular expression} using - the \texttt{regex} field, together with an optional specification of \texttt{applyTo} as - \texttt{cell} field, together with an optional specification of \texttt{applyTo} as - \texttt{cell}. - \end{itemize} - In both cases, the default value of \texttt{applyTo} is \texttt{cell}, and does not need - to be specified. - - We may also specify the \texttt{applyTo} field as \texttt{row}, a demonstration of which - is given in \cref{lst:dontMeasure5}; upon running \index{switches!-l demonstration} - \begin{commandshell} + we receive the output given in \cref{lst:tabular-DM-mod3} \index{regular + expressions!lowercase alph a-z} + \begin{cmhtcbraster}[raster columns=3, + raster left skip=-3.5cm, + raster right skip=-2cm, + raster column skip=.03\linewidth] + \cmhlistingsfromfile{demonstrations/tabular-DM-mod3.tex}{\texttt{tabular-DM.tex} using \cref{lst:dontMeasure3} or \cref{lst:dontMeasure3}}{lst:tabular-DM-mod3} + \cmhlistingsfromfile{demonstrations/dontMeasure3.yaml}[yaml-TCB]{\texttt{dontMeasure3.yaml}}{lst:dontMeasure3} + \cmhlistingsfromfile{demonstrations/dontMeasure4.yaml}[yaml-TCB]{\texttt{dontMeasure4.yaml}}{lst:dontMeasure4} + \end{cmhtcbraster} + We note that in: + \begin{itemize} + \item \cref{lst:dontMeasure3} we have specified entries not to be measured, each one has a + \emph{string} in the \texttt{this} + field, together with an optional specification of \texttt{applyTo} as \texttt{cell}; + \item \cref{lst:dontMeasure4} we have specified entries not to be measured as a + \emph{regular expression} using + the \texttt{regex} field, together with an optional specification of \texttt{applyTo} as + \texttt{cell} field, together with an optional specification of \texttt{applyTo} as + \texttt{cell}. + \end{itemize} + In both cases, the default value of \texttt{applyTo} is \texttt{cell}, and does not need + to be specified. + + We may also specify the \texttt{applyTo} field as \texttt{row}, a demonstration of which + is given in \cref{lst:dontMeasure5}; upon running \index{switches!-l demonstration} + \begin{commandshell} latexindent.pl tabular-DM.tex -l=dontMeasure5.yaml \end{commandshell} - we receive the output in \cref{lst:tabular-DM-mod5}. - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/tabular-DM-mod5.tex}{\texttt{tabular-DM.tex} using \cref{lst:dontMeasure5}}{lst:tabular-DM-mod5} - \cmhlistingsfromfile{demonstrations/dontMeasure5.yaml}[yaml-TCB]{\texttt{dontMeasure5.yaml}}{lst:dontMeasure5} - \end{cmhtcbraster} - - Finally, the \texttt{applyTo} field can be specified as \texttt{row}, together with a - \texttt{regex} expression. For example, for the settings given in - \cref{lst:dontMeasure6}, upon running \index{switches!-l demonstration} - \begin{commandshell} + we receive the output in \cref{lst:tabular-DM-mod5}. + \begin{cmhtcbraster} + \cmhlistingsfromfile{demonstrations/tabular-DM-mod5.tex}{\texttt{tabular-DM.tex} using \cref{lst:dontMeasure5}}{lst:tabular-DM-mod5} + \cmhlistingsfromfile{demonstrations/dontMeasure5.yaml}[yaml-TCB]{\texttt{dontMeasure5.yaml}}{lst:dontMeasure5} + \end{cmhtcbraster} + + Finally, the \texttt{applyTo} field can be specified as \texttt{row}, together with a + \texttt{regex} expression. For example, for the settings given in + \cref{lst:dontMeasure6}, upon running \index{switches!-l demonstration} + \begin{commandshell} latexindent.pl tabular-DM.tex -l=dontMeasure6.yaml \end{commandshell} - we receive the output in \cref{lst:tabular-DM-mod6}. \index{regular - expressions!dontMeasure feature, row} \index{regular expressions!lowercase alph a-z} + we receive the output in \cref{lst:tabular-DM-mod6}. \index{regular + expressions!dontMeasure feature, row} \index{regular expressions!lowercase alph a-z} - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/tabular-DM-mod6.tex}{\texttt{tabular-DM.tex} using \cref{lst:dontMeasure6}}{lst:tabular-DM-mod6} - \cmhlistingsfromfile{demonstrations/dontMeasure6.yaml}[yaml-TCB]{\texttt{dontMeasure6.yaml}}{lst:dontMeasure6} - \end{cmhtcbraster} + \begin{cmhtcbraster} + \cmhlistingsfromfile{demonstrations/tabular-DM-mod6.tex}{\texttt{tabular-DM.tex} using \cref{lst:dontMeasure6}}{lst:tabular-DM-mod6} + \cmhlistingsfromfile{demonstrations/dontMeasure6.yaml}[yaml-TCB]{\texttt{dontMeasure6.yaml}}{lst:dontMeasure6} + \end{cmhtcbraster} \subsubsection{lookForAlignDelims: the delimiterRegEx and delimiterJustification feature}\label{sec:delimiter-reg-ex} - The delimiter alignment \announce{2020-03-21}{delimiterRegEx feature} will, by default, - align code blocks at the ampersand character. The behaviour is controlled by the - \texttt{delimiterRegEx} field within \texttt{lookForAlignDelims}; the default value is - \lstinline*'(?<!\\)(&)'*, which can be read as: \emph{an ampersand, as long as it is not - immediately preceeded by a backslash}. \index{warning!capturing parenthesis for - lookForAlignDelims} \index{capturing parenthesis (regex)} \index{regular - expressions!capturing parenthesis} \index{delimiters!delimiterRegEx} - \index{delimiters!delimiter justification (left or right)}% - - \begin{warning} - Important: note the `capturing' parenthesis in the \lstinline!(&)! which are necessary; - if you intend to customise this field, then be sure to include them appropriately. - \end{warning} - - We demonstrate how to customise this with respect to the code given in - \cref{lst:tabbing}; the default output from \lstinline!latexindent.pl! is given in - \cref{lst:tabbing-default}. - - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/tabbing.tex}{\texttt{tabbing.tex}}{lst:tabbing} - \cmhlistingsfromfile{demonstrations/tabbing-default.tex}{\texttt{tabbing.tex} default output}{lst:tabbing-default} - \end{cmhtcbraster} - - Let's say that we wish to align the code at either the \lstinline!\=! or \lstinline!\>!. - We employ the settings given in \cref{lst:delimiterRegEx1} and run the command - \index{switches!-l demonstration} - \begin{commandshell} + The delimiter alignment \announce{2020-03-21}{delimiterRegEx feature} will, by default, + align code blocks at the ampersand character. The behaviour is controlled by the + \texttt{delimiterRegEx} field within \texttt{lookForAlignDelims}; the default value is + \lstinline*'(?<!\\)(&)'*, which can be read as: \emph{an ampersand, as long as it is not + immediately preceeded by a backslash}. \index{warning!capturing parenthesis for + lookForAlignDelims} \index{capturing parenthesis (regex)} \index{regular + expressions!capturing parenthesis} \index{delimiters!delimiterRegEx} + \index{delimiters!delimiter justification (left or right)}% + + \begin{warning} + Important: note the `capturing' parenthesis in the \lstinline!(&)! which are necessary; + if you intend to customise this field, then be sure to include them appropriately. + \end{warning} + + We demonstrate how to customise this with respect to the code given in + \cref{lst:tabbing}; the default output from \lstinline!latexindent.pl! is given in + \cref{lst:tabbing-default}. + + \begin{cmhtcbraster} + \cmhlistingsfromfile{demonstrations/tabbing.tex}{\texttt{tabbing.tex}}{lst:tabbing} + \cmhlistingsfromfile{demonstrations/tabbing-default.tex}{\texttt{tabbing.tex} default output}{lst:tabbing-default} + \end{cmhtcbraster} + + Let's say that we wish to align the code at either the \lstinline!\=! or \lstinline!\>!. + We employ the settings given in \cref{lst:delimiterRegEx1} and run the command + \index{switches!-l demonstration} + \begin{commandshell} latexindent.pl tabbing.tex -l=delimiterRegEx1.yaml \end{commandshell} - to receive the output given in \cref{lst:tabbing-mod1}. \index{regular - expressions!delimiter regex at \textbackslash= or \textbackslash>} - - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/tabbing-mod1.tex}{\texttt{tabbing.tex} using \cref{lst:delimiterRegEx1}}{lst:tabbing-mod1} - \cmhlistingsfromfile{demonstrations/delimiterRegEx1.yaml}[yaml-TCB]{\texttt{delimiterRegEx1.yaml}}{lst:delimiterRegEx1} - \end{cmhtcbraster} - We note that: - \begin{itemize} - \item in \cref{lst:tabbing-mod1} the code has been aligned, as intended, at both the - \lstinline!\=! and \lstinline!\>!; - \item in \cref{lst:delimiterRegEx1} we have heeded the warning and captured the expression - using grouping parenthesis, specified a backslash using \lstinline!\\! and said that it - must be followed by either \lstinline!=! or \lstinline!>!. - \end{itemize} - We can explore \texttt{delimiterRegEx} a little further using the settings in - \cref{lst:delimiterRegEx2} and run the command - \index{switches!-l demonstration} - \begin{commandshell} + to receive the output given in \cref{lst:tabbing-mod1}. \index{regular + expressions!delimiter regex at \textbackslash= or \textbackslash>} + + \begin{cmhtcbraster} + \cmhlistingsfromfile{demonstrations/tabbing-mod1.tex}{\texttt{tabbing.tex} using \cref{lst:delimiterRegEx1}}{lst:tabbing-mod1} + \cmhlistingsfromfile{demonstrations/delimiterRegEx1.yaml}[yaml-TCB]{\texttt{delimiterRegEx1.yaml}}{lst:delimiterRegEx1} + \end{cmhtcbraster} + We note that: + \begin{itemize} + \item in \cref{lst:tabbing-mod1} the code has been aligned, as intended, at both the + \lstinline!\=! and \lstinline!\>!; + \item in \cref{lst:delimiterRegEx1} we have heeded the warning and captured the expression + using grouping parenthesis, specified a backslash using \lstinline!\\! and said that it + must be followed by either \lstinline!=! or \lstinline!>!. + \end{itemize} + We can explore \texttt{delimiterRegEx} a little further using the settings in + \cref{lst:delimiterRegEx2} and run the command \index{switches!-l demonstration} + \begin{commandshell} latexindent.pl tabbing.tex -l=delimiterRegEx2.yaml \end{commandshell} - to receive the output given in \cref{lst:tabbing-mod2}. \index{regular - expressions!delimiter regex at only \textbackslash>} - - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/tabbing-mod2.tex}{\texttt{tabbing.tex} using \cref{lst:delimiterRegEx2}}{lst:tabbing-mod2} - \cmhlistingsfromfile{demonstrations/delimiterRegEx2.yaml}[yaml-TCB]{\texttt{delimiterRegEx2.yaml}}{lst:delimiterRegEx2} - \end{cmhtcbraster} - We note that only the \lstinline!\>! have been aligned. - - Of course, the other lookForAlignDelims options can be used alongside the - \texttt{delimiterRegEx}; regardless of the type of delimiter being used (ampersand or - anything else), the fields from \vref{lst:aligndelims:advanced} remain the same; for - example, using the settings in \cref{lst:delimiterRegEx3}, and running \index{switches!-l - demonstration} - \begin{commandshell} + to receive the output given in \cref{lst:tabbing-mod2}. \index{regular + expressions!delimiter regex at only \textbackslash>} + + \begin{cmhtcbraster} + \cmhlistingsfromfile{demonstrations/tabbing-mod2.tex}{\texttt{tabbing.tex} using \cref{lst:delimiterRegEx2}}{lst:tabbing-mod2} + \cmhlistingsfromfile{demonstrations/delimiterRegEx2.yaml}[yaml-TCB]{\texttt{delimiterRegEx2.yaml}}{lst:delimiterRegEx2} + \end{cmhtcbraster} + We note that only the \lstinline!\>! have been aligned. + + Of course, the other lookForAlignDelims options can be used alongside the + \texttt{delimiterRegEx}; regardless of the type of delimiter being used (ampersand or + anything else), the fields from \vref{lst:aligndelims:advanced} remain the same; for + example, using the settings in \cref{lst:delimiterRegEx3}, and running \index{switches!-l + demonstration} + \begin{commandshell} latexindent.pl tabbing.tex -l=delimiterRegEx3.yaml \end{commandshell} - to receive the output given in \cref{lst:tabbing-mod3}. - - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/tabbing-mod3.tex}{\texttt{tabbing.tex} using \cref{lst:delimiterRegEx3}}{lst:tabbing-mod3} - \cmhlistingsfromfile{demonstrations/delimiterRegEx3.yaml}[yaml-TCB]{\texttt{delimiterRegEx3.yaml}}{lst:delimiterRegEx3} - \end{cmhtcbraster} - - It is possible that delimiters specified within \texttt{delimiterRegEx} can be of - different lengths. Consider the file in \cref{lst:tabbing1}, and associated YAML in - \cref{lst:delimiterRegEx4}. Note that the \cref{lst:delimiterRegEx4} specifies the option - for the delimiter to be either \lstinline!#! or \lstinline!\>!, \emph{which are different - lengths}. Upon running the command \index{switches!-l demonstration} \index{switches!-o - demonstration} - \begin{commandshell} + to receive the output given in \cref{lst:tabbing-mod3}. + + \begin{cmhtcbraster} + \cmhlistingsfromfile{demonstrations/tabbing-mod3.tex}{\texttt{tabbing.tex} using \cref{lst:delimiterRegEx3}}{lst:tabbing-mod3} + \cmhlistingsfromfile{demonstrations/delimiterRegEx3.yaml}[yaml-TCB]{\texttt{delimiterRegEx3.yaml}}{lst:delimiterRegEx3} + \end{cmhtcbraster} + + It is possible that delimiters specified within \texttt{delimiterRegEx} can be of + different lengths. Consider the file in \cref{lst:tabbing1}, and associated YAML in + \cref{lst:delimiterRegEx4}. Note that the \cref{lst:delimiterRegEx4} specifies the option + for the delimiter to be either \lstinline!#! or \lstinline!\>!, \emph{which are different + lengths}. Upon running the command \index{switches!-l demonstration} \index{switches!-o + demonstration} + \begin{commandshell} latexindent.pl tabbing1.tex -l=delimiterRegEx4.yaml -o=+-mod4 \end{commandshell} - we receive the output in \cref{lst:tabbing1-mod4}. \index{regular expressions!delimiter - regex at \#} - - \begin{cmhtcbraster}[raster columns=3, - raster left skip=-3.5cm, - raster right skip=-2cm, - raster column skip=.03\linewidth] - \cmhlistingsfromfile{demonstrations/tabbing1.tex}{\texttt{tabbing1.tex}}{lst:tabbing1} - \cmhlistingsfromfile{demonstrations/tabbing1-mod4.tex}{\texttt{tabbing1-mod4.tex}}{lst:tabbing1-mod4} - \cmhlistingsfromfile{demonstrations/delimiterRegEx4.yaml}[yaml-TCB]{\texttt{delimiterRegEx4.yaml}}{lst:delimiterRegEx4} - \end{cmhtcbraster} - - You can set the \emph{delimiter} justification as either \texttt{left} (default) or - \texttt{right}, which will only have effect when delimiters in the same column have - different lengths. Using the settings in \cref{lst:delimiterRegEx5} and running the - command \index{switches!-l demonstration} \index{switches!-o demonstration} - \begin{commandshell} + we receive the output in \cref{lst:tabbing1-mod4}. \index{regular expressions!delimiter + regex at \#} + + \begin{cmhtcbraster}[raster columns=3, + raster left skip=-3.5cm, + raster right skip=-2cm, + raster column skip=.03\linewidth] + \cmhlistingsfromfile{demonstrations/tabbing1.tex}{\texttt{tabbing1.tex}}{lst:tabbing1} + \cmhlistingsfromfile{demonstrations/tabbing1-mod4.tex}{\texttt{tabbing1-mod4.tex}}{lst:tabbing1-mod4} + \cmhlistingsfromfile{demonstrations/delimiterRegEx4.yaml}[yaml-TCB]{\texttt{delimiterRegEx4.yaml}}{lst:delimiterRegEx4} + \end{cmhtcbraster} + + You can set the \emph{delimiter} justification as either \texttt{left} (default) or + \texttt{right}, which will only have effect when delimiters in the same column have + different lengths. Using the settings in \cref{lst:delimiterRegEx5} and running the + command \index{switches!-l demonstration} \index{switches!-o demonstration} + \begin{commandshell} latexindent.pl tabbing1.tex -l=delimiterRegEx5.yaml -o=+-mod5 \end{commandshell} - gives the output in \cref{lst:tabbing1-mod5}. \index{regular expressions!delimiter regex - at \# or \textbackslash>} + gives the output in \cref{lst:tabbing1-mod5}. \index{regular expressions!delimiter regex + at \# or \textbackslash>} - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/tabbing1-mod5.tex}{\texttt{tabbing1-mod5.tex}}{lst:tabbing1-mod5} - \cmhlistingsfromfile{demonstrations/delimiterRegEx5.yaml}[yaml-TCB]{\texttt{delimiterRegEx5.yaml}}{lst:delimiterRegEx5} - \end{cmhtcbraster} + \begin{cmhtcbraster} + \cmhlistingsfromfile{demonstrations/tabbing1-mod5.tex}{\texttt{tabbing1-mod5.tex}}{lst:tabbing1-mod5} + \cmhlistingsfromfile{demonstrations/delimiterRegEx5.yaml}[yaml-TCB]{\texttt{delimiterRegEx5.yaml}}{lst:delimiterRegEx5} + \end{cmhtcbraster} - Note that in \cref{lst:tabbing1-mod5} the second set of delimiters have been \emph{right - aligned} -- it is quite subtle! + Note that in \cref{lst:tabbing1-mod5} the second set of delimiters have been \emph{right + aligned} -- it is quite subtle! \subsubsection{lookForAlignDelims: lookForChildCodeBlocks}\label{sec:lookForChildCodeBlocks} - There \announce{2021-12-13}{lookForChildCodeBlocks demonstration} may be scenarios in - which you would prefer to instruct \texttt{latexindent.pl} \emph{not} to search for child - blocks; in which case setting \texttt{lookForChildCodeBlocks} to 0 may be a good way to - proceed. - - Using the settings from \vref{lst:dontMeasure1} on the file in \cref{lst:tabular-DM-1} - and running the command - \begin{commandshell} + There \announce{2021-12-13}{lookForChildCodeBlocks demonstration} may be scenarios in + which you would prefer to instruct \texttt{latexindent.pl} \emph{not} to search for child + blocks; in which case setting \texttt{lookForChildCodeBlocks} to 0 may be a good way to + proceed. + + Using the settings from \vref{lst:dontMeasure1} on the file in \cref{lst:tabular-DM-1} + and running the command + \begin{commandshell} latexindent.pl tabular-DM-1.tex -l=dontMeasure1.yaml -o=+-mod1 \end{commandshell} - gives the output in \cref{lst:tabular-DM-1-mod1}. - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/tabular-DM-1.tex}{\texttt{tabular-DM-1.tex}}{lst:tabular-DM-1} - \cmhlistingsfromfile{demonstrations/tabular-DM-1-mod1.tex}{\texttt{tabular-DM-1-mod1.tex}}{lst:tabular-DM-1-mod1} - \end{cmhtcbraster} - - We can improve the output from \cref{lst:tabular-DM-1-mod1} by employing the settings in - \cref{lst:dontMeasure1a} - \begin{commandshell} + gives the output in \cref{lst:tabular-DM-1-mod1}. + \begin{cmhtcbraster} + \cmhlistingsfromfile{demonstrations/tabular-DM-1.tex}{\texttt{tabular-DM-1.tex}}{lst:tabular-DM-1} + \cmhlistingsfromfile{demonstrations/tabular-DM-1-mod1.tex}{\texttt{tabular-DM-1-mod1.tex}}{lst:tabular-DM-1-mod1} + \end{cmhtcbraster} + + We can improve the output from \cref{lst:tabular-DM-1-mod1} by employing the settings in + \cref{lst:dontMeasure1a} + \begin{commandshell} latexindent.pl tabular-DM-1.tex -l=dontMeasure1a.yaml -o=+-mod1a \end{commandshell} - which gives the output in \cref{lst:dontMeasure1a}. + which gives the output in \cref{lst:dontMeasure1a}. - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/tabular-DM-1-mod1a.tex}{\texttt{tabular-DM-1-mod1a.tex}}{lst:tabular-DM-1-mod1a} - \cmhlistingsfromfile{demonstrations/dontMeasure1a.yaml}[yaml-TCB]{\texttt{dontMeasure1a.yaml}}{lst:dontMeasure1a} - \end{cmhtcbraster} + \begin{cmhtcbraster} + \cmhlistingsfromfile{demonstrations/tabular-DM-1-mod1a.tex}{\texttt{tabular-DM-1-mod1a.tex}}{lst:tabular-DM-1-mod1a} + \cmhlistingsfromfile{demonstrations/dontMeasure1a.yaml}[yaml-TCB]{\texttt{dontMeasure1a.yaml}}{lst:dontMeasure1a} + \end{cmhtcbraster} \subsection{Indent after items, specials and headings} \yamltitle{indentAfterItems}*{fields} - The environment names specified in \texttt{indentAfterItems} tell \texttt{latexindent.pl} - to look for \lstinline!\item! commands; if these switches are set to \texttt{1} then - indentation will be performed so as indent the code after each \texttt{item}. A - demonstration is given in \cref{lst:itemsbefore,lst:itemsafter} - - \begin{cmhtcbraster}[raster columns=3, - raster left skip=-3.5cm, - raster right skip=-2cm, - raster column skip=.03\linewidth] - \cmhlistingsfromfile[style=indentAfterItems]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{indentAfterItems}}{lst:indentafteritems} - \cmhlistingsfromfile{demonstrations/items1.tex}{\texttt{items1.tex}}{lst:itemsbefore} - \cmhlistingsfromfile{demonstrations/items1-default.tex}{\texttt{items1.tex} default output}{lst:itemsafter} - \end{cmhtcbraster} + The environment names specified in \texttt{indentAfterItems} tell \texttt{latexindent.pl} + to look for \lstinline!\item! commands; if these switches are set to \texttt{1} then + indentation will be performed so as indent the code after each \texttt{item}. A + demonstration is given in \cref{lst:itemsbefore,lst:itemsafter} + + \begin{cmhtcbraster}[raster columns=3, + raster left skip=-3.5cm, + raster right skip=-2cm, + raster column skip=.03\linewidth] + \cmhlistingsfromfile[style=indentAfterItems]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{indentAfterItems}}{lst:indentafteritems} + \cmhlistingsfromfile{demonstrations/items1.tex}{\texttt{items1.tex}}{lst:itemsbefore} + \cmhlistingsfromfile{demonstrations/items1-default.tex}{\texttt{items1.tex} default output}{lst:itemsafter} + \end{cmhtcbraster} \yamltitle{itemNames}*{fields} - If you have your own \texttt{item} commands (perhaps you prefer to use \texttt{myitem}, - for example) then you can put populate them in \texttt{itemNames}. For example, users of - the \texttt{exam} document class might like to add \texttt{parts} to - \texttt{indentAfterItems} and \texttt{part} to \texttt{itemNames} to their user settings - (see \vref{sec:indentconfig} for details of how to configure user settings, and - \vref{lst:mysettings} \\ in particular \label{page:examsettings}.) + If you have your own \texttt{item} commands (perhaps you prefer to use \texttt{myitem}, + for example) then you can put populate them in \texttt{itemNames}. For example, users of + the \texttt{exam} document class might like to add \texttt{parts} to + \texttt{indentAfterItems} and \texttt{part} to \texttt{itemNames} to their user settings + (see \vref{sec:indentconfig} for details of how to configure user settings, and + \vref{lst:mysettings} \\ in particular \label{page:examsettings}.) - \cmhlistingsfromfile[style=itemNames]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{itemNames}}{lst:itemNames} + \cmhlistingsfromfile[style=itemNames]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{itemNames}}{lst:itemNames} \yamltitle{specialBeginEnd}*{fields}\label{yaml:specialBeginEnd} - The fields specified \index{specialBeginEnd!introduction} - \announce{2017-08-21}*{specialBeginEnd} in \texttt{specialBeginEnd} are, in their default - state, focused on math mode begin and end statements, but there is no requirement for - this to be the case; \cref{lst:specialBeginEnd} shows the default settings of - \texttt{specialBeginEnd}. \index{specialBeginEnd!default settings}% - - \cmhlistingsfromfile[style=specialBeginEnd]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{specialBeginEnd}}{lst:specialBeginEnd} - - The field \texttt{displayMath} represents \lstinline!\[...\]!, \texttt{inlineMath} - represents \lstinline!$...$! and \texttt{displayMathTex} represents \lstinline!$$...$$!. - You can, of course, rename these in your own YAML files (see \vref{sec:localsettings}); - indeed, you might like to set up your own special begin and end statements. - - A demonstration of the before-and-after results are shown in - \cref{lst:specialbefore,lst:specialafter}. - - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/special1.tex}{\texttt{special1.tex} before}{lst:specialbefore} - \cmhlistingsfromfile{demonstrations/special1-default.tex}{\texttt{special1.tex} default output}{lst:specialafter} - \end{cmhtcbraster} - - For each field, \texttt{lookForThis} is set to \texttt{1} by default, which means that - \texttt{latexindent.pl} will look for this pattern; you can tell \texttt{latexindent.pl} - not to look for the pattern, by setting \texttt{lookForThis} to \texttt{0}. - - There are \announce{2017-08-21}{specialBeforeCommand} examples in which it is - advantageous to search for \texttt{specialBeginEnd} fields \emph{before} searching for - commands, and the \texttt{specialBeforeCommand} switch controls this behaviour. For - example, consider the file shown in \cref{lst:specialLRbefore}.% - - \cmhlistingsfromfile{demonstrations/specialLR.tex}{\texttt{specialLR.tex}}{lst:specialLRbefore} - - Now consider the YAML files shown in - \cref{lst:specialsLeftRight-yaml,lst:specialBeforeCommand-yaml} - \index{specialBeginEnd!searching for special before commands} - - \begin{cmhtcbraster} - \cmhlistingsfromfile[]{demonstrations/specialsLeftRight.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{specialsLeftRight.yaml}}{lst:specialsLeftRight-yaml} - \cmhlistingsfromfile[]{demonstrations/specialBeforeCommand.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{specialBeforeCommand.yaml}}{lst:specialBeforeCommand-yaml} - \end{cmhtcbraster} - - Upon running the following commands \index{switches!-l demonstration} - \begin{widepage} - \begin{commandshell} + The fields specified \index{specialBeginEnd!introduction} + \announce{2017-08-21}*{specialBeginEnd} in \texttt{specialBeginEnd} are, in their default + state, focused on math mode begin and end statements, but there is no requirement for + this to be the case; \cref{lst:specialBeginEnd} shows the default settings of + \texttt{specialBeginEnd}. \index{specialBeginEnd!default settings}% + + \cmhlistingsfromfile[style=specialBeginEnd]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{specialBeginEnd}}{lst:specialBeginEnd} + + The field \texttt{displayMath} represents \lstinline!\[...\]!, \texttt{inlineMath} + represents \lstinline!$...$! and \texttt{displayMathTex} represents \lstinline!$$...$$!. + You can, of course, rename these in your own YAML files (see \vref{sec:localsettings}); + indeed, you might like to set up your own special begin and end statements. + + A demonstration of the before-and-after results are shown in + \cref{lst:specialbefore,lst:specialafter}. + + \begin{cmhtcbraster} + \cmhlistingsfromfile{demonstrations/special1.tex}{\texttt{special1.tex} before}{lst:specialbefore} + \cmhlistingsfromfile{demonstrations/special1-default.tex}{\texttt{special1.tex} default output}{lst:specialafter} + \end{cmhtcbraster} + + For each field, \texttt{lookForThis} is set to \texttt{1} by default, which means that + \texttt{latexindent.pl} will look for this pattern; you can tell \texttt{latexindent.pl} + not to look for the pattern, by setting \texttt{lookForThis} to \texttt{0}. + + There are \announce{2017-08-21}{specialBeforeCommand} examples in which it is + advantageous to search for \texttt{specialBeginEnd} fields \emph{before} searching for + commands, and the \texttt{specialBeforeCommand} switch controls this behaviour. For + example, consider the file shown in \cref{lst:specialLRbefore}.% + + \cmhlistingsfromfile{demonstrations/specialLR.tex}{\texttt{specialLR.tex}}{lst:specialLRbefore} + + Now consider the YAML files shown in + \cref{lst:specialsLeftRight-yaml,lst:specialBeforeCommand-yaml} + \index{specialBeginEnd!searching for special before commands} + + \begin{cmhtcbraster} + \cmhlistingsfromfile[]{demonstrations/specialsLeftRight.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{specialsLeftRight.yaml}}{lst:specialsLeftRight-yaml} + \cmhlistingsfromfile[]{demonstrations/specialBeforeCommand.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{specialBeforeCommand.yaml}}{lst:specialBeforeCommand-yaml} + \end{cmhtcbraster} + + Upon running the following commands \index{switches!-l demonstration} + \begin{widepage} + \begin{commandshell} latexindent.pl specialLR.tex -l=specialsLeftRight.yaml latexindent.pl specialLR.tex -l=specialsLeftRight.yaml,specialBeforeCommand.yaml \end{commandshell} - \end{widepage} - we receive the respective outputs in - \cref{lst:specialLR-comm-first-tex,lst:specialLR-special-first-tex}. - - \begin{minipage}{.49\linewidth} - \cmhlistingsfromfile{demonstrations/specialLR-comm-first.tex}{\texttt{specialLR.tex} using \cref{lst:specialsLeftRight-yaml}}{lst:specialLR-comm-first-tex} - \end{minipage} - \hfill - \begin{minipage}{.49\linewidth} - \cmhlistingsfromfile{demonstrations/specialLR-special-first.tex}{\texttt{specialLR.tex} using \cref{lst:specialsLeftRight-yaml,lst:specialBeforeCommand-yaml}}{lst:specialLR-special-first-tex} - \end{minipage} - - Notice that in: - \begin{itemize} - \item \cref{lst:specialLR-comm-first-tex} the \lstinline!\left! has been treated as a - \emph{command}, with one optional argument; - \item \cref{lst:specialLR-special-first-tex} the \texttt{specialBeginEnd} pattern in - \cref{lst:specialsLeftRight-yaml} - has been obeyed because \cref{lst:specialBeforeCommand-yaml} specifies that the - \texttt{specialBeginEnd} should be sought \emph{before} commands. - \end{itemize} - - You can,optionally, specify \announce{2018-04-27}{update to specialBeginEnd} the - \texttt{middle} field for anything that you specify in \texttt{specialBeginEnd}. For - example, let's consider the \texttt{.tex} file in \cref{lst:special2}. - \index{specialBeginEnd!middle} \index{specialBeginEnd!IfElsFi example}% - - \cmhlistingsfromfile{demonstrations/special2.tex}{\texttt{special2.tex}}{lst:special2} - - Upon saving the YAML settings in \cref{lst:middle-yaml,lst:middle1-yaml} and running the - commands \index{switches!-l demonstration} - \begin{commandshell} + \end{widepage} + we receive the respective outputs in + \cref{lst:specialLR-comm-first-tex,lst:specialLR-special-first-tex}. + + \begin{minipage}{.49\linewidth} + \cmhlistingsfromfile{demonstrations/specialLR-comm-first.tex}{\texttt{specialLR.tex} using \cref{lst:specialsLeftRight-yaml}}{lst:specialLR-comm-first-tex} + \end{minipage} + \hfill + \begin{minipage}{.49\linewidth} + \cmhlistingsfromfile{demonstrations/specialLR-special-first.tex}{\texttt{specialLR.tex} using \cref{lst:specialsLeftRight-yaml,lst:specialBeforeCommand-yaml}}{lst:specialLR-special-first-tex} + \end{minipage} + + Notice that in: + \begin{itemize} + \item \cref{lst:specialLR-comm-first-tex} the \lstinline!\left! has been treated as a + \emph{command}, with one optional argument; + \item \cref{lst:specialLR-special-first-tex} the \texttt{specialBeginEnd} pattern in + \cref{lst:specialsLeftRight-yaml} + has been obeyed because \cref{lst:specialBeforeCommand-yaml} specifies that the + \texttt{specialBeginEnd} should be sought \emph{before} commands. + \end{itemize} + + You can,optionally, specify \announce{2018-04-27}{update to specialBeginEnd} the + \texttt{middle} field for anything that you specify in \texttt{specialBeginEnd}. For + example, let's consider the \texttt{.tex} file in \cref{lst:special2}. + \index{specialBeginEnd!middle} \index{specialBeginEnd!IfElsFi example}% + + \cmhlistingsfromfile{demonstrations/special2.tex}{\texttt{special2.tex}}{lst:special2} + + Upon saving the YAML settings in \cref{lst:middle-yaml,lst:middle1-yaml} and running the + commands \index{switches!-l demonstration} + \begin{commandshell} latexindent.pl special2.tex -l=middle latexindent.pl special2.tex -l=middle1 \end{commandshell} - then we obtain the output given in \cref{lst:special2-mod1,lst:special2-mod2}. - - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/middle.yaml}[yaml-TCB]{\texttt{middle.yaml}}{lst:middle-yaml} - \cmhlistingsfromfile{demonstrations/special2-mod1.tex}{\texttt{special2.tex} using \cref{lst:middle-yaml}}{lst:special2-mod1} - \end{cmhtcbraster} - - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/middle1.yaml}[yaml-TCB]{\texttt{middle1.yaml}}{lst:middle1-yaml} - \cmhlistingsfromfile{demonstrations/special2-mod2.tex}{\texttt{special2.tex} using \cref{lst:middle1-yaml}}{lst:special2-mod2} - \end{cmhtcbraster} - - We note that: - \begin{itemize} - \item in \cref{lst:special2-mod1} the bodies of each of the \texttt{Elsif} statements have been - indented appropriately; - \item the \texttt{Else} statement has \emph{not} been indented appropriately in - \cref{lst:special2-mod1} -- read on! - \item we have specified multiple settings for the \texttt{middle} field using the syntax - demonstrated in \cref{lst:middle1-yaml} so that the body of the \texttt{Else} statement - has been indented appropriately in \cref{lst:special2-mod2}. - \end{itemize} - - You may \announce{2018-08-13}{specialBeginEnd verbatim} specify fields in - \texttt{specialBeginEnd} to be treated as verbatim code blocks by changing - \texttt{lookForThis} to be \texttt{verbatim}. \index{verbatim!specialBeginEnd}% - - For example, beginning with the code in \cref{lst:special3-mod1} and the YAML in - \cref{lst:special-verb1-yaml}, and running \index{switches!-l demonstration} - \begin{commandshell} + then we obtain the output given in \cref{lst:special2-mod1,lst:special2-mod2}. + + \begin{cmhtcbraster} + \cmhlistingsfromfile{demonstrations/middle.yaml}[yaml-TCB]{\texttt{middle.yaml}}{lst:middle-yaml} + \cmhlistingsfromfile{demonstrations/special2-mod1.tex}{\texttt{special2.tex} using \cref{lst:middle-yaml}}{lst:special2-mod1} + \end{cmhtcbraster} + + \begin{cmhtcbraster} + \cmhlistingsfromfile{demonstrations/middle1.yaml}[yaml-TCB]{\texttt{middle1.yaml}}{lst:middle1-yaml} + \cmhlistingsfromfile{demonstrations/special2-mod2.tex}{\texttt{special2.tex} using \cref{lst:middle1-yaml}}{lst:special2-mod2} + \end{cmhtcbraster} + + We note that: + \begin{itemize} + \item in \cref{lst:special2-mod1} the bodies of each of the \texttt{Elsif} statements have been + indented appropriately; + \item the \texttt{Else} statement has \emph{not} been indented appropriately in + \cref{lst:special2-mod1} -- read on! + \item we have specified multiple settings for the \texttt{middle} field using the syntax + demonstrated in \cref{lst:middle1-yaml} so that the body of the \texttt{Else} statement + has been indented appropriately in \cref{lst:special2-mod2}. + \end{itemize} + + You may \announce{2018-08-13}{specialBeginEnd verbatim} specify fields in + \texttt{specialBeginEnd} to be treated as verbatim code blocks by changing + \texttt{lookForThis} to be \texttt{verbatim}. \index{verbatim!specialBeginEnd}% + + For example, beginning with the code in \cref{lst:special3-mod1} and the YAML in + \cref{lst:special-verb1-yaml}, and running \index{switches!-l demonstration} + \begin{commandshell} latexindent.pl special3.tex -l=special-verb1 \end{commandshell} - then the output in \cref{lst:special3-mod1} is unchanged. - \index{specialBeginEnd!specifying as verbatim} + then the output in \cref{lst:special3-mod1} is unchanged. + \index{specialBeginEnd!specifying as verbatim} - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/special-verb1.yaml}[yaml-TCB]{\texttt{special-verb1.yaml}}{lst:special-verb1-yaml} - \cmhlistingsfromfile{demonstrations/special3-mod1.tex}{\texttt{special3.tex} and output using \cref{lst:special-verb1-yaml}}{lst:special3-mod1} - \end{cmhtcbraster} + \begin{cmhtcbraster} + \cmhlistingsfromfile{demonstrations/special-verb1.yaml}[yaml-TCB]{\texttt{special-verb1.yaml}}{lst:special-verb1-yaml} + \cmhlistingsfromfile{demonstrations/special3-mod1.tex}{\texttt{special3.tex} and output using \cref{lst:special-verb1-yaml}}{lst:special3-mod1} + \end{cmhtcbraster} - We can combine the \texttt{specialBeginEnd} with the \texttt{lookForAlignDelims} feature. - We begin with the code in \cref{lst:special-align}. + We can combine the \texttt{specialBeginEnd} with the \texttt{lookForAlignDelims} feature. + We begin with the code in \cref{lst:special-align}. - \cmhlistingsfromfile{demonstrations/special-align.tex}{\texttt{special-align.tex}}{lst:special-align} + \cmhlistingsfromfile{demonstrations/special-align.tex}{\texttt{special-align.tex}}{lst:special-align} - Let's assume that our goal is to align the code at the \texttt{edge} and \texttt{node} - text; we employ the code given in \cref{lst:edge-node1} and run the command - \index{switches!-l demonstration} \index{switches!-o demonstration} - \begin{commandshell} + Let's assume that our goal is to align the code at the \texttt{edge} and \texttt{node} + text; we employ the code given in \cref{lst:edge-node1} and run the command + \index{switches!-l demonstration} \index{switches!-o demonstration} + \begin{commandshell} latexindent.pl special-align.tex -l edge-node1.yaml -o=+-mod1 \end{commandshell} - to receive the output in \cref{lst:special-align-mod1}. \index{specialBeginEnd!combined - with lookForAlignDelims} \index{specialBeginEnd!delimiterRegEx} - \index{specialBeginEnd!alignment at delimiter} \index{specialBeginEnd!tikz example} - \index{regular expressions!delimiter alignment for edge or node} \index{delimiters!within - specialBeginEnd blocks} \index{regular expressions!numeric 0-9} - - \begin{cmhtcbraster}[ raster left skip=-3.5cm,] - \cmhlistingsfromfile{demonstrations/edge-node1.yaml}[yaml-TCB]{\texttt{edge-node1.yaml}}{lst:edge-node1} - \cmhlistingsfromfile{demonstrations/special-align-mod1.tex}{\texttt{special-align.tex} using \cref{lst:edge-node1}}{lst:special-align-mod1} - \end{cmhtcbraster} - - The output in \cref{lst:special-align-mod1} is not quite ideal. We can tweak the settings - within \cref{lst:edge-node1} in order to improve the output; in particular, we employ the - code in \cref{lst:edge-node2} and run the command \index{switches!-l demonstration} - \index{switches!-o demonstration} \index{regular expressions!uppercase alph A-Z} - \begin{commandshell} + to receive the output in \cref{lst:special-align-mod1}. \index{specialBeginEnd!combined + with lookForAlignDelims} \index{specialBeginEnd!delimiterRegEx} + \index{specialBeginEnd!alignment at delimiter} \index{specialBeginEnd!tikz example} + \index{regular expressions!delimiter alignment for edge or node} \index{delimiters!within + specialBeginEnd blocks} \index{regular expressions!numeric 0-9} + + \begin{cmhtcbraster}[ raster left skip=-3.5cm,] + \cmhlistingsfromfile{demonstrations/edge-node1.yaml}[yaml-TCB]{\texttt{edge-node1.yaml}}{lst:edge-node1} + \cmhlistingsfromfile{demonstrations/special-align-mod1.tex}{\texttt{special-align.tex} using \cref{lst:edge-node1}}{lst:special-align-mod1} + \end{cmhtcbraster} + + The output in \cref{lst:special-align-mod1} is not quite ideal. We can tweak the settings + within \cref{lst:edge-node1} in order to improve the output; in particular, we employ the + code in \cref{lst:edge-node2} and run the command \index{switches!-l demonstration} + \index{switches!-o demonstration} \index{regular expressions!uppercase alph A-Z} + \begin{commandshell} latexindent.pl special-align.tex -l edge-node2.yaml -o=+-mod2 \end{commandshell} - to receive the output in \cref{lst:special-align-mod2}. - \index{specialBeginEnd!delimiterRegEx tweaked} \index{regular expressions!at least one +} - \index{regular expressions!horizontal space \textbackslash{h}} + to receive the output in \cref{lst:special-align-mod2}. + \index{specialBeginEnd!delimiterRegEx tweaked} \index{regular expressions!at least one +} + \index{regular expressions!horizontal space \textbackslash{h}} - \begin{cmhtcbraster}[ raster left skip=-3.5cm,] - \cmhlistingsfromfile{demonstrations/edge-node2.yaml}[yaml-TCB]{\texttt{edge-node2.yaml}}{lst:edge-node2} - \cmhlistingsfromfile{demonstrations/special-align-mod2.tex}{\texttt{special-align.tex} using \cref{lst:edge-node2}}{lst:special-align-mod2} - \end{cmhtcbraster} + \begin{cmhtcbraster}[ raster left skip=-3.5cm,] + \cmhlistingsfromfile{demonstrations/edge-node2.yaml}[yaml-TCB]{\texttt{edge-node2.yaml}}{lst:edge-node2} + \cmhlistingsfromfile{demonstrations/special-align-mod2.tex}{\texttt{special-align.tex} using \cref{lst:edge-node2}}{lst:special-align-mod2} + \end{cmhtcbraster} - The \texttt{lookForThis} field can be considered optional; - \announce{2021-06-19}*{lookForThis optional for specialBeginEnd} by default, it is - assumed to be 1, which is demonstrated in \cref{lst:edge-node2}.% + The \texttt{lookForThis} field can be considered optional; + \announce{2021-06-19}*{lookForThis optional for specialBeginEnd} by default, it is + assumed to be 1, which is demonstrated in \cref{lst:edge-node2}.% \yamltitle{indentAfterHeadings}*{fields} - This field enables the user to specify indentation rules that take effect after heading - commands such as \lstinline!\part!, \lstinline!\chapter!, \lstinline!\section!, - \lstinline!\subsection*!, or indeed any user-specified command written in this - field.\footnote{There is a slight difference in interface for this field when comparing - Version 2.2 to Version 3.0; see \vref{app:differences} for details.} - - \cmhlistingsfromfile[style=indentAfterHeadings]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{indentAfterHeadings}}{lst:indentAfterHeadings} - - The default settings do \emph{not} place indentation after a heading, but you can easily - switch them on by changing \texttt{indentAfterThisHeading} from 0 to 1. The - \texttt{level} field tells \texttt{latexindent.pl} the hierarchy of the heading structure - in your document. You might, for example, like to have both \texttt{section} and - \texttt{subsection} set with \texttt{level: 3} because you do not want the indentation to - go too deep. - - You can add any of your own custom heading commands to this field, specifying the - \texttt{level} as appropriate. You can also specify your own indentation in - \texttt{indentRules} (see \vref{sec:noadd-indent-rules}); you will find the default - \texttt{indentRules} contains \lstinline!chapter: " "! which tells - \texttt{latexindent.pl} simply to use a space character after \texttt{chapter} headings - (once \texttt{indent} is set to \texttt{1} for \texttt{chapter}). - - For example, assuming that you have the code in \cref{lst:headings1yaml} saved into - \texttt{headings1.yaml}, and that you have the text from \cref{lst:headings1} saved into - \texttt{headings1.tex}. - - \begin{cmhtcbraster} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/headings1.yaml}[yaml-TCB]{\texttt{headings1.yaml}}{lst:headings1yaml} - \cmhlistingsfromfile{demonstrations/headings1.tex}{\texttt{headings1.tex}}{lst:headings1} - \end{cmhtcbraster} - - If you run the command \index{switches!-l demonstration} - \begin{commandshell} + This field enables the user to specify indentation rules that take effect after heading + commands such as \lstinline!\part!, \lstinline!\chapter!, \lstinline!\section!, + \lstinline!\subsection*!, or indeed any user-specified command written in this + field.\footnote{There is a slight difference in interface for this field when comparing + Version 2.2 to Version 3.0; see \vref{app:differences} for details.} + + \cmhlistingsfromfile[style=indentAfterHeadings]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{indentAfterHeadings}}{lst:indentAfterHeadings} + + The default settings do \emph{not} place indentation after a heading, but you can easily + switch them on by changing \texttt{indentAfterThisHeading} from 0 to 1. The + \texttt{level} field tells \texttt{latexindent.pl} the hierarchy of the heading structure + in your document. You might, for example, like to have both \texttt{section} and + \texttt{subsection} set with \texttt{level: 3} because you do not want the indentation to + go too deep. + + You can add any of your own custom heading commands to this field, specifying the + \texttt{level} as appropriate. You can also specify your own indentation in + \texttt{indentRules} (see \vref{sec:noadd-indent-rules}); you will find the default + \texttt{indentRules} contains \lstinline!chapter: " "! which tells + \texttt{latexindent.pl} simply to use a space character after \texttt{chapter} headings + (once \texttt{indent} is set to \texttt{1} for \texttt{chapter}). + + For example, assuming that you have the code in \cref{lst:headings1yaml} saved into + \texttt{headings1.yaml}, and that you have the text from \cref{lst:headings1} saved into + \texttt{headings1.tex}. + + \begin{cmhtcbraster} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/headings1.yaml}[yaml-TCB]{\texttt{headings1.yaml}}{lst:headings1yaml} + \cmhlistingsfromfile{demonstrations/headings1.tex}{\texttt{headings1.tex}}{lst:headings1} + \end{cmhtcbraster} + + If you run the command \index{switches!-l demonstration} + \begin{commandshell} latexindent.pl headings1.tex -l=headings1.yaml \end{commandshell} - then you should receive the output given in \cref{lst:headings1-mod1}. - - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile[showtabs=true]{demonstrations/headings1-mod1.tex}{\texttt{headings1.tex} using \cref{lst:headings1yaml}}{lst:headings1-mod1} - \end{minipage}% - \hfill - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile[showtabs=true]{demonstrations/headings1-mod2.tex}{\texttt{headings1.tex} second modification}{lst:headings1-mod2} - \end{minipage} - - Now say that you modify the \texttt{YAML} from \cref{lst:headings1yaml} so that the - \texttt{paragraph} \texttt{level} is \texttt{1}; after running \index{switches!-l - demonstration} - \begin{commandshell} + then you should receive the output given in \cref{lst:headings1-mod1}. + + \begin{minipage}{.45\textwidth} + \cmhlistingsfromfile[showtabs=true]{demonstrations/headings1-mod1.tex}{\texttt{headings1.tex} using \cref{lst:headings1yaml}}{lst:headings1-mod1} + \end{minipage}% + \hfill + \begin{minipage}{.45\textwidth} + \cmhlistingsfromfile[showtabs=true]{demonstrations/headings1-mod2.tex}{\texttt{headings1.tex} second modification}{lst:headings1-mod2} + \end{minipage} + + Now say that you modify the \texttt{YAML} from \cref{lst:headings1yaml} so that the + \texttt{paragraph} \texttt{level} is \texttt{1}; after running \index{switches!-l + demonstration} + \begin{commandshell} latexindent.pl headings1.tex -l=headings1.yaml \end{commandshell} - you should receive the code given in \cref{lst:headings1-mod2}; notice that the - \texttt{paragraph} and \texttt{subsection} are at the same indentation level. + you should receive the code given in \cref{lst:headings1-mod2}; notice that the + \texttt{paragraph} and \texttt{subsection} are at the same indentation level. - \index{indentation!maximum indetation} + \index{indentation!maximum indetation} \yamltitle{maximumIndentation}*{horizontal space} - You can control the maximum indentation given to your file by - \announce{2017-08-21}{maximumIndentation} specifying the \texttt{maximumIndentation} - field as horizontal space (but \emph{not} including tabs). This feature uses the - \texttt{Text::Tabs} module \cite{texttabs}, and is \emph{off} by default.% - - For example, consider the example shown in \cref{lst:mult-nested} together with the - default output shown in \cref{lst:mult-nested-default}. - - \begin{cmhtcbraster}[raster column skip=.1\linewidth] - \cmhlistingsfromfile{demonstrations/mult-nested.tex}{\texttt{mult-nested.tex}}{lst:mult-nested} - \cmhlistingsfromfile[showtabs=true]{demonstrations/mult-nested-default.tex}{\texttt{mult-nested.tex} default output}{lst:mult-nested-default} - \end{cmhtcbraster} - - Now say that, for example, you have the \texttt{max-indentation1.yaml} from - \cref{lst:max-indentation1yaml} and that you run the following command: - \index{switches!-l demonstration} - \begin{commandshell} + You can control the maximum indentation given to your file by + \announce{2017-08-21}{maximumIndentation} specifying the \texttt{maximumIndentation} + field as horizontal space (but \emph{not} including tabs). This feature uses the + \texttt{Text::Tabs} module \cite{texttabs}, and is \emph{off} by default.% + + For example, consider the example shown in \cref{lst:mult-nested} together with the + default output shown in \cref{lst:mult-nested-default}. + + \begin{cmhtcbraster}[raster column skip=.1\linewidth] + \cmhlistingsfromfile{demonstrations/mult-nested.tex}{\texttt{mult-nested.tex}}{lst:mult-nested} + \cmhlistingsfromfile[showtabs=true]{demonstrations/mult-nested-default.tex}{\texttt{mult-nested.tex} default output}{lst:mult-nested-default} + \end{cmhtcbraster} + + Now say that, for example, you have the \texttt{max-indentation1.yaml} from + \cref{lst:max-indentation1yaml} and that you run the following command: + \index{switches!-l demonstration} + \begin{commandshell} latexindent.pl mult-nested.tex -l=max-indentation1 \end{commandshell} - You should receive the output shown in \cref{lst:mult-nested-max-ind1}. + You should receive the output shown in \cref{lst:mult-nested-max-ind1}. - \begin{cmhtcbraster} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/max-indentation1.yaml}[yaml-TCB]{\texttt{max-indentation1.yaml}}{lst:max-indentation1yaml} - \cmhlistingsfromfile[showspaces=true]{demonstrations/mult-nested-max-ind1.tex}{\texttt{mult-nested.tex} using \cref{lst:max-indentation1yaml}}{lst:mult-nested-max-ind1} - \end{cmhtcbraster} + \begin{cmhtcbraster} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/max-indentation1.yaml}[yaml-TCB]{\texttt{max-indentation1.yaml}}{lst:max-indentation1yaml} + \cmhlistingsfromfile[showspaces=true]{demonstrations/mult-nested-max-ind1.tex}{\texttt{mult-nested.tex} using \cref{lst:max-indentation1yaml}}{lst:mult-nested-max-ind1} + \end{cmhtcbraster} - Comparing the output in \cref{lst:mult-nested-default,lst:mult-nested-max-ind1} we notice - that the (default) tabs of indentation have been replaced by a single space. + Comparing the output in \cref{lst:mult-nested-default,lst:mult-nested-max-ind1} we notice + that the (default) tabs of indentation have been replaced by a single space. - In general, when using the \texttt{maximumIndentation} feature, any leading tabs will be - replaced by equivalent spaces except, of course, those found in - \texttt{verbatimEnvironments} (see \vref{lst:verbatimEnvironments}) or - \texttt{noIndentBlock} (see \vref{lst:noIndentBlock}). + In general, when using the \texttt{maximumIndentation} feature, any leading tabs will be + replaced by equivalent spaces except, of course, those found in + \texttt{verbatimEnvironments} (see \vref{lst:verbatimEnvironments}) or + \texttt{noIndentBlock} (see \vref{lst:noIndentBlock}). \subsection{The code blocks known latexindent.pl}\label{subsubsec:code-blocks} - As of Version 3.0, \texttt{latexindent.pl} processes documents using code blocks; each of - these are shown in \cref{tab:code-blocks}. \index{regular expressions!uppercase alph A-Z} - \index{regular expressions!lowercase alph a-z} \index{regular expressions!numeric 0-9} - \index{regular expressions!horizontal space \textbackslash{h}} - - \begin{table}[!htp] - \begin{widepage} - \centering - \caption{Code blocks known to \texttt{latexindent.pl}} - \label{tab:code-blocks} - \begin{tabular}{m{.3\linewidth}@{\hspace{.25cm}}m{.4\linewidth}@{\hspace{.25cm}}m{.2\linewidth}} - \toprule - Code block & characters allowed in name & example \\ - \midrule - environments & \lstinline!a-zA-Z@\*0-9_\\! & - \begin{lstlisting}[,nolol=true,] + As of Version 3.0, \texttt{latexindent.pl} processes documents using code blocks; each of + these are shown in \cref{tab:code-blocks}. \index{regular expressions!uppercase alph A-Z} + \index{regular expressions!lowercase alph a-z} \index{regular expressions!numeric 0-9} + \index{regular expressions!horizontal space \textbackslash{h}} + + \begin{table}[!htp] + \begin{widepage} + \centering + \caption{Code blocks known to \texttt{latexindent.pl}} + \label{tab:code-blocks} + \begin{tabular}{m{.3\linewidth}@{\hspace{.25cm}}m{.4\linewidth}@{\hspace{.25cm}}m{.2\linewidth}} + \toprule + Code block & characters allowed in name & example \\ + \midrule + environments & \lstinline!a-zA-Z@\*0-9_\\! & + \begin{lstlisting}[,nolol=true,] \begin{myenv} body of myenv \end{myenv} \end{lstlisting} - \\\cmidrule{2-3} - optionalArguments & \emph{inherits} name from parent (e.g environment name) & - \begin{lstlisting}[,nolol=true,] + \\\cmidrule{2-3} + optionalArguments & \emph{inherits} name from parent (e.g environment name) & + \begin{lstlisting}[,nolol=true,] [ opt arg text ] \end{lstlisting} - \\\cmidrule{2-3} - mandatoryArguments & \emph{inherits} name from parent (e.g environment name) & - \begin{lstlisting}[,nolol=true,] + \\\cmidrule{2-3} + mandatoryArguments & \emph{inherits} name from parent (e.g environment name) & + \begin{lstlisting}[,nolol=true,] { mand arg text } \end{lstlisting} - \\\cmidrule{2-3} - commands & \lstinline!+a-zA-Z@\*0-9_\:! & \lstinline!\mycommand!$\langle$\itshape{arguments}$\rangle$ \\\cmidrule{2-3} - keyEqualsValuesBracesBrackets & \lstinline!a-zA-Z@\*0-9_\/.\h\{\}:\#-! & \lstinline!my key/.style=!$\langle$\itshape{arguments}$\rangle$ \\\cmidrule{2-3} - namedGroupingBracesBrackets & \lstinline!0-9\.a-zA-Z@\*><! & \lstinline!in!$\langle$\itshape{arguments}$\rangle$ \\\cmidrule{2-3} - UnNamedGroupingBracesBrackets & \centering\emph{No name!} & \lstinline!{! or \lstinline![! or \lstinline!,! or \lstinline!\&! or \lstinline!)! or \lstinline!(! or \lstinline!$! followed by $\langle$\itshape{arguments}$\rangle$ \\\cmidrule{2-3} - ifElseFi & \lstinline!@a-zA-Z! but must begin with either \newline \lstinline!\if! of \lstinline!\@if! & - \begin{lstlisting}[,nolol=true,] + \\\cmidrule{2-3} + commands & \lstinline!+a-zA-Z@\*0-9_\:! & \lstinline!\mycommand!$\langle$\itshape{arguments}$\rangle$ \\\cmidrule{2-3} + keyEqualsValuesBracesBrackets & \lstinline!a-zA-Z@\*0-9_\/.\h\{\}:\#-! & \lstinline!my key/.style=!$\langle$\itshape{arguments}$\rangle$ \\\cmidrule{2-3} + namedGroupingBracesBrackets & \lstinline!0-9\.a-zA-Z@\*><! & \lstinline!in!$\langle$\itshape{arguments}$\rangle$ \\\cmidrule{2-3} + UnNamedGroupingBracesBrackets & \centering\emph{No name!} & \lstinline!{! or \lstinline![! or \lstinline!,! or \lstinline!\&! or \lstinline!)! or \lstinline!(! or \lstinline!$! followed by $\langle$\itshape{arguments}$\rangle$ \\\cmidrule{2-3} + ifElseFi & \lstinline!@a-zA-Z! but must begin with either \newline \lstinline!\if! of \lstinline!\@if! & + \begin{lstlisting}[,nolol=true,] \ifnum... ... \else ... \fi \end{lstlisting} \\\cmidrule{2-3} - items & User specified, see \vref{lst:indentafteritems,lst:itemNames} & - \begin{lstlisting}[,nolol=true,] + items & User specified, see \vref{lst:indentafteritems,lst:itemNames} & + \begin{lstlisting}[,nolol=true,] \begin{enumerate} \item ... \end{enumerate} \end{lstlisting} \\\cmidrule{2-3} - specialBeginEnd & User specified, see \vref{lst:specialBeginEnd} & - \begin{lstlisting}[,nolol=true,] + specialBeginEnd & User specified, see \vref{lst:specialBeginEnd} & + \begin{lstlisting}[,nolol=true,] \[ ... \] \end{lstlisting} \\\cmidrule{2-3} - afterHeading & User specified, see \vref{lst:indentAfterHeadings} & - \begin{lstlisting}[,morekeywords={chapter},nolol=true,] + afterHeading & User specified, see \vref{lst:indentAfterHeadings} & + \begin{lstlisting}[,morekeywords={chapter},nolol=true,] \chapter{title} ... \section{title} \end{lstlisting} \\\cmidrule{2-3} - filecontents & User specified, see \vref{lst:fileContentsEnvironments} & - \begin{lstlisting}[,nolol=true,] + filecontents & User specified, see \vref{lst:fileContentsEnvironments} & + \begin{lstlisting}[,nolol=true,] \begin{filecontents} ... \end{filecontents} \end{lstlisting} \\ - \bottomrule - \end{tabular} - \end{widepage} - \end{table} - - We will refer to these code blocks in what follows. \announce{2019-07-13}{fine tuning of - code blocks} Note that the fine tuning of the definition of the code blocks detailed in - \cref{tab:code-blocks} is discussed in \vref{sec:finetuning}.% + \bottomrule + \end{tabular} + \end{widepage} + \end{table} + + We will refer to these code blocks in what follows. \announce{2019-07-13}{fine tuning of + code blocks} Note that the fine tuning of the definition of the code blocks detailed in + \cref{tab:code-blocks} is discussed in \vref{sec:finetuning}.% |