% arara: pdflatex: { files: [latexindent]} \section{defaultSettings.yaml}\label{sec:defuseloc} \texttt{latexindent.pl} loads its settings from \texttt{defaultSettings.yaml}. The idea is to separate the behaviour of the script from the internal working -- this is very similar to the way that we separate content from form when writing our documents in \LaTeX. If you look in \texttt{defaultSettings.yaml} you'll find the switches that govern the behaviour of \texttt{latexindent.pl}. If you're not sure where \texttt{defaultSettings.yaml} resides on your computer, don't worry as \texttt{indent.log} will tell you where to find it. \texttt{defaultSettings.yaml} is commented, but here is a description of what each switch is designed to do. The default value is given in each case; whenever you see \emph{integer} in \emph{this} section, assume that it must be greater than or equal to \texttt{0} unless otherwise stated. For most of the settings in \texttt{defaultSettings.yaml} that are specified as integers, then we understand \texttt{0} to represent `off' and \texttt{1} to represent `on'. For fields that allow values other than \texttt{0} or \texttt{1}, it is hoped that the 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} 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. \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}.}. \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. 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} \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}. \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. \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}. \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}.% \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} \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} \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}. \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. \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. 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} 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} 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}. \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{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} 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} \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. \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}. \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. \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}. \begin{cmhlistings}{Motivating \texttt{preambleCommandsBeforeEnvironments}}{lst:motivatepreambleCommandsBeforeEnvironments} ... preheadhook={\begin{mdframed}[style=myframedstyle]}, postfoothook=\end{mdframed}, ... \end{cmhlistings} \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}. 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} removeTrailingWhitespace: 1 \end{yaml} \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}.% \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} lookForAlignDelims: tabular: 1 tabularx: 1 longtable: 1 array: 1 matrix: 1 ... \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* '(?!. 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} 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} 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} 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} 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>} \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! \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} 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} latexindent.pl tabular-DM-1.tex -l=dontMeasure1a.yaml -o=+-mod1a \end{commandshell} 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} \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} \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}.) \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} 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} 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} latexindent.pl special3.tex -l=special-verb1 \end{commandshell} 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} 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} 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} 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}} \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}.% \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} 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} 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. \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} latexindent.pl mult-nested.tex -l=max-indentation1 \end{commandshell} 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} 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}). \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,] \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,] [ opt arg text ] \end{lstlisting} \\\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@\*>