diff options
Diffstat (limited to 'Master/texmf-dist/doc/support/latexindent/subsec-commands-and-their-options.tex')
-rw-r--r-- | Master/texmf-dist/doc/support/latexindent/subsec-commands-and-their-options.tex | 442 |
1 files changed, 221 insertions, 221 deletions
diff --git a/Master/texmf-dist/doc/support/latexindent/subsec-commands-and-their-options.tex b/Master/texmf-dist/doc/support/latexindent/subsec-commands-and-their-options.tex index 7ed4d4eaeb3..ff44ad229e2 100644 --- a/Master/texmf-dist/doc/support/latexindent/subsec-commands-and-their-options.tex +++ b/Master/texmf-dist/doc/support/latexindent/subsec-commands-and-their-options.tex @@ -1,251 +1,251 @@ % arara: pdflatex: { files: [latexindent]} \subsection{Commands and the strings between their arguments}\label{subsec:commands-string-between} The \texttt{command} code blocks will - always look for optional (square bracketed) and mandatory (curly braced) arguments which - can contain comments, line breaks and `beamer' commands \lstinline!<.*?>! between them. - There are switches that can allow them to contain other strings, which we discuss next. + always look for optional (square bracketed) and mandatory (curly braced) arguments which + can contain comments, line breaks and `beamer' commands \lstinline!<.*?>! between them. + There are switches that can allow them to contain other strings, which we discuss next. \yamltitle{commandCodeBlocks}*{fields} - The \texttt{commandCodeBlocks} field \announce{2018-04-27}*{commandCodeBlocks} contains a - few switches detailed in \cref{lst:commandCodeBlocks}.% + The \texttt{commandCodeBlocks} field \announce{2018-04-27}*{commandCodeBlocks} contains a + few switches detailed in \cref{lst:commandCodeBlocks}.% - \cmhlistingsfromfile[style=commandCodeBlocks]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{commandCodeBlocks}}{lst:commandCodeBlocks} + \cmhlistingsfromfile[style=commandCodeBlocks]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{commandCodeBlocks}}{lst:commandCodeBlocks} \yamltitle{roundParenthesesAllowed}{0|1} - The need for this field was mostly motivated by commands found in code used to generate - images in \texttt{PSTricks} and \texttt{tikz}; for example, let's consider the code given - in \cref{lst:pstricks1}. - - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile{demonstrations/pstricks1.tex}{\texttt{pstricks1.tex}}{lst:pstricks1} - \end{minipage} - \hfill - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile{demonstrations/pstricks1-default.tex}{\texttt{pstricks1} default output}{lst:pstricks1-default} - \end{minipage} - - Notice that the \lstinline!\defFunction! command has an optional argument, followed by a - mandatory argument, followed by a round-parenthesis argument, $(u,v)$. - - By default, because \texttt{roundParenthesesAllowed} is set to $1$ in - \cref{lst:commandCodeBlocks}, then \texttt{latexindent.pl} will allow round parenthesis - between optional and mandatory arguments. In the case of the code in - \cref{lst:pstricks1}, \texttt{latexindent.pl} finds \emph{all} the arguments of - \lstinline!defFunction!, both before and after \lstinline!(u,v)!. - - The default output from running \texttt{latexindent.pl} on \cref{lst:pstricks1} actually - leaves it unchanged (see \cref{lst:pstricks1-default}); note in particular, this is - because of \texttt{noAdditionalIndentGlobal} as discussed on - \cpageref{page:command:noAddGlobal}. - - Upon using the YAML settings in \cref{lst:noRoundParentheses}, and running the command - \index{switches!-l demonstration} - \begin{commandshell} + The need for this field was mostly motivated by commands found in code used to generate + images in \texttt{PSTricks} and \texttt{tikz}; for example, let's consider the code given + in \cref{lst:pstricks1}. + + \begin{minipage}{.45\textwidth} + \cmhlistingsfromfile{demonstrations/pstricks1.tex}{\texttt{pstricks1.tex}}{lst:pstricks1} + \end{minipage} + \hfill + \begin{minipage}{.45\textwidth} + \cmhlistingsfromfile{demonstrations/pstricks1-default.tex}{\texttt{pstricks1} default output}{lst:pstricks1-default} + \end{minipage} + + Notice that the \lstinline!\defFunction! command has an optional argument, followed by a + mandatory argument, followed by a round-parenthesis argument, $(u,v)$. + + By default, because \texttt{roundParenthesesAllowed} is set to $1$ in + \cref{lst:commandCodeBlocks}, then \texttt{latexindent.pl} will allow round parenthesis + between optional and mandatory arguments. In the case of the code in + \cref{lst:pstricks1}, \texttt{latexindent.pl} finds \emph{all} the arguments of + \lstinline!defFunction!, both before and after \lstinline!(u,v)!. + + The default output from running \texttt{latexindent.pl} on \cref{lst:pstricks1} actually + leaves it unchanged (see \cref{lst:pstricks1-default}); note in particular, this is + because of \texttt{noAdditionalIndentGlobal} as discussed on + \cpageref{page:command:noAddGlobal}. + + Upon using the YAML settings in \cref{lst:noRoundParentheses}, and running the command + \index{switches!-l demonstration} + \begin{commandshell} latexindent.pl pstricks1.tex -l noRoundParentheses.yaml \end{commandshell} - we obtain the output given in \cref{lst:pstricks1-nrp}. - - \begin{cmhtcbraster}[raster column skip=.1\linewidth] - \cmhlistingsfromfile{demonstrations/pstricks1-nrp.tex}{\texttt{pstricks1.tex} using \cref{lst:noRoundParentheses}}{lst:pstricks1-nrp} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/noRoundParentheses.yaml}[yaml-TCB]{\texttt{noRoundParentheses.yaml}}{lst:noRoundParentheses} - \end{cmhtcbraster} - - Notice the difference between \cref{lst:pstricks1-default} and \cref{lst:pstricks1-nrp}; - in particular, in \cref{lst:pstricks1-nrp}, because round parentheses are \emph{not} - allowed, \texttt{latexindent.pl} finds that the \lstinline!\defFunction! command finishes - at the first opening round parenthesis. As such, the remaining braced, mandatory, - arguments are found to be \texttt{UnNamedGroupingBracesBrackets} (see - \vref{tab:code-blocks}) which, by default, assume indentation for their body, and hence - the tabbed indentation in \cref{lst:pstricks1-nrp}. - - Let's explore this using the YAML given in \cref{lst:defFunction} and run the command - \index{switches!-l demonstration} - \begin{commandshell} + we obtain the output given in \cref{lst:pstricks1-nrp}. + + \begin{cmhtcbraster}[raster column skip=.1\linewidth] + \cmhlistingsfromfile{demonstrations/pstricks1-nrp.tex}{\texttt{pstricks1.tex} using \cref{lst:noRoundParentheses}}{lst:pstricks1-nrp} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/noRoundParentheses.yaml}[yaml-TCB]{\texttt{noRoundParentheses.yaml}}{lst:noRoundParentheses} + \end{cmhtcbraster} + + Notice the difference between \cref{lst:pstricks1-default} and \cref{lst:pstricks1-nrp}; + in particular, in \cref{lst:pstricks1-nrp}, because round parentheses are \emph{not} + allowed, \texttt{latexindent.pl} finds that the \lstinline!\defFunction! command finishes + at the first opening round parenthesis. As such, the remaining braced, mandatory, + arguments are found to be \texttt{UnNamedGroupingBracesBrackets} (see + \vref{tab:code-blocks}) which, by default, assume indentation for their body, and hence + the tabbed indentation in \cref{lst:pstricks1-nrp}. + + Let's explore this using the YAML given in \cref{lst:defFunction} and run the command + \index{switches!-l demonstration} + \begin{commandshell} latexindent.pl pstricks1.tex -l defFunction.yaml \end{commandshell} - then the output is as in \cref{lst:pstricks1-indent-rules}. + then the output is as in \cref{lst:pstricks1-indent-rules}. - \begin{cmhtcbraster}[raster column skip=.1\linewidth] - \cmhlistingsfromfile[showspaces=true]{demonstrations/pstricks1-indent-rules.tex}{\texttt{pstricks1.tex} using \cref{lst:defFunction}}{lst:pstricks1-indent-rules} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/defFunction.yaml}[yaml-TCB]{\texttt{defFunction.yaml}}{lst:defFunction} - \end{cmhtcbraster} + \begin{cmhtcbraster}[raster column skip=.1\linewidth] + \cmhlistingsfromfile[showspaces=true]{demonstrations/pstricks1-indent-rules.tex}{\texttt{pstricks1.tex} using \cref{lst:defFunction}}{lst:pstricks1-indent-rules} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/defFunction.yaml}[yaml-TCB]{\texttt{defFunction.yaml}}{lst:defFunction} + \end{cmhtcbraster} - Notice in \cref{lst:pstricks1-indent-rules} that the \emph{body} of the - \lstinline!defFunction! command i.e, the subsequent lines containing arguments after the - command name, have received the single space of indentation specified by - \cref{lst:defFunction}. + Notice in \cref{lst:pstricks1-indent-rules} that the \emph{body} of the + \lstinline!defFunction! command i.e, the subsequent lines containing arguments after the + command name, have received the single space of indentation specified by + \cref{lst:defFunction}. \yamltitle{stringsAllowedBetweenArguments}*{fields} - \texttt{tikz} users may well specify code such as that given in - \cref{lst:tikz-node1}; processing this code using - \texttt{latexindent.pl} gives the default output in \cref{lst:tikz-node1-default}. - - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile[columns=fixed]{demonstrations/tikz-node1.tex}{\texttt{tikz-node1.tex}}{lst:tikz-node1} - \end{minipage} - \hfill - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile[columns=fixed]{demonstrations/tikz-node1-default.tex}{\texttt{tikz-node1} default output}{lst:tikz-node1-default} - \end{minipage} - - With reference to \vref{lst:commandCodeBlocks}, we see that the strings - \begin{quote} - to, node, ++ - \end{quote} - are all allowed to appear between arguments; importantly, you are encouraged to add - further names to this field as necessary. This means that when \texttt{latexindent.pl} - processes \cref{lst:tikz-node1}, it consumes: - \begin{itemize} - \item the optional argument \lstinline![thin]! - \item the round-bracketed argument \lstinline!(c)! because \texttt{roundParenthesesAllowed} is - $1$ by default - \item the string \lstinline!to! (specified in \texttt{stringsAllowedBetweenArguments}) - \item the optional argument \lstinline![in=110,out=-90]! - \item the string \lstinline!++! (specified in \texttt{stringsAllowedBetweenArguments}) - \item the round-bracketed argument \lstinline!(0,-0.5cm)! because - \texttt{roundParenthesesAllowed} is $1$ by default - \item the string \lstinline!node! (specified in \texttt{stringsAllowedBetweenArguments}) - \item the optional argument \lstinline![below,align=left,scale=0.5]! - \end{itemize} - - We can explore this further, for example using \cref{lst:draw} and running the command - \index{switches!-l demonstration} - \begin{commandshell} + \texttt{tikz} users may well specify code such as that given in + \cref{lst:tikz-node1}; processing this code using + \texttt{latexindent.pl} gives the default output in \cref{lst:tikz-node1-default}. + + \begin{minipage}{.45\textwidth} + \cmhlistingsfromfile[columns=fixed]{demonstrations/tikz-node1.tex}{\texttt{tikz-node1.tex}}{lst:tikz-node1} + \end{minipage} + \hfill + \begin{minipage}{.45\textwidth} + \cmhlistingsfromfile[columns=fixed]{demonstrations/tikz-node1-default.tex}{\texttt{tikz-node1} default output}{lst:tikz-node1-default} + \end{minipage} + + With reference to \vref{lst:commandCodeBlocks}, we see that the strings + \begin{quote} + to, node, ++ + \end{quote} + are all allowed to appear between arguments; importantly, you are encouraged to add + further names to this field as necessary. This means that when \texttt{latexindent.pl} + processes \cref{lst:tikz-node1}, it consumes: + \begin{itemize} + \item the optional argument \lstinline![thin]! + \item the round-bracketed argument \lstinline!(c)! because \texttt{roundParenthesesAllowed} is + $1$ by default + \item the string \lstinline!to! (specified in \texttt{stringsAllowedBetweenArguments}) + \item the optional argument \lstinline![in=110,out=-90]! + \item the string \lstinline!++! (specified in \texttt{stringsAllowedBetweenArguments}) + \item the round-bracketed argument \lstinline!(0,-0.5cm)! because + \texttt{roundParenthesesAllowed} is $1$ by default + \item the string \lstinline!node! (specified in \texttt{stringsAllowedBetweenArguments}) + \item the optional argument \lstinline![below,align=left,scale=0.5]! + \end{itemize} + + We can explore this further, for example using \cref{lst:draw} and running the command + \index{switches!-l demonstration} + \begin{commandshell} latexindent.pl tikz-node1.tex -l draw.yaml \end{commandshell} - we receive the output given in \cref{lst:tikz-node1-draw}. + we receive the output given in \cref{lst:tikz-node1-draw}. - \begin{cmhtcbraster}[raster column skip=.1\linewidth] - \cmhlistingsfromfile[showspaces=true]{demonstrations/tikz-node1-draw.tex}{\texttt{tikz-node1.tex} using \cref{lst:draw}}{lst:tikz-node1-draw} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/draw.yaml}[yaml-TCB]{\texttt{draw.yaml}}{lst:draw} - \end{cmhtcbraster} + \begin{cmhtcbraster}[raster column skip=.1\linewidth] + \cmhlistingsfromfile[showspaces=true]{demonstrations/tikz-node1-draw.tex}{\texttt{tikz-node1.tex} using \cref{lst:draw}}{lst:tikz-node1-draw} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/draw.yaml}[yaml-TCB]{\texttt{draw.yaml}}{lst:draw} + \end{cmhtcbraster} - Notice that each line after the \lstinline!\draw! command (its `body') in - \cref{lst:tikz-node1-draw} has been given the appropriate two-spaces worth of indentation - specified in \cref{lst:draw}. + Notice that each line after the \lstinline!\draw! command (its `body') in + \cref{lst:tikz-node1-draw} has been given the appropriate two-spaces worth of indentation + specified in \cref{lst:draw}. - Let's compare this with the output from using the YAML settings in \cref{lst:no-strings}, - and running the command \index{switches!-l demonstration} - \begin{commandshell} + Let's compare this with the output from using the YAML settings in \cref{lst:no-strings}, + and running the command \index{switches!-l demonstration} + \begin{commandshell} latexindent.pl tikz-node1.tex -l no-strings.yaml \end{commandshell} - given in \cref{lst:tikz-node1-no-strings}. - - \begin{cmhtcbraster}[raster column skip=.1\linewidth] - \cmhlistingsfromfile{demonstrations/tikz-node1-no-strings.tex}{\texttt{tikz-node1.tex} using \cref{lst:no-strings}}{lst:tikz-node1-no-strings} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/no-strings.yaml}[yaml-TCB]{\texttt{no-strings.yaml}}{lst:no-strings} - \end{cmhtcbraster} - - In this case, \texttt{latexindent.pl} sees that: - \begin{itemize} - \item the \lstinline!\draw! command finishes after the \lstinline!(c)!, as - \texttt{stringsAllowedBetweenArguments} has been set to $0$ so there are no strings - allowed between arguments; - \item it finds a \texttt{namedGroupingBracesBrackets} called \texttt{to} (see - \vref{tab:code-blocks}) \emph{with} argument \lstinline![in=110,out=-90]! - \item it finds another \texttt{namedGroupingBracesBrackets} but this time called \texttt{node} - with argument \lstinline![below,align=left,scale=0.5]! - \end{itemize} - - Referencing \vref{lst:commandCodeBlocks}, \announce{2018-04-27}*{amalgamate feature in - commandCodeBlocks}, we see that the first field in the - \texttt{stringsAllowedBetweenArguments} is \texttt{amalgamate} and is set to \texttt{1} - by default. This is for users who wish to specify their settings in multiple YAML files. - For example, by using the settings in either \cref{lst:amalgamate-demo} - or\cref{lst:amalgamate-demo1} is equivalent to using the settings in - \cref{lst:amalgamate-demo2}.% - - \begin{cmhtcbraster}[raster columns=3, - raster left skip=-3.5cm, - raster right skip=-2cm, - raster column skip=.03\linewidth] - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/amalgamate-demo.yaml}[yaml-TCB]{\texttt{amalgamate-demo.yaml}}{lst:amalgamate-demo} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/amalgamate-demo1.yaml}[yaml-TCB]{\texttt{amalgamate-demo1.yaml}}{lst:amalgamate-demo1} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/amalgamate-demo2.yaml}[yaml-TCB]{\texttt{amalgamate-demo2.yaml}}{lst:amalgamate-demo2} - \end{cmhtcbraster} - - We specify \texttt{amalgamate} to be set to \texttt{0} and in which case any settings - loaded prior to those specified, including the default, will be overwritten. For example, - using the settings in \cref{lst:amalgamate-demo3} means that only the strings specified - in that field will be used. - - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/amalgamate-demo3.yaml}[yaml-TCB]{\texttt{amalgamate-demo3.yaml}}{lst:amalgamate-demo3} - - It is important to note that the \texttt{amalgamate} field, if used, must be in the first - field, and specified using the syntax given in - \cref{lst:amalgamate-demo1,lst:amalgamate-demo2,lst:amalgamate-demo3}. - - We may explore this feature further with the code in \cref{lst:for-each}, whose default - output is given in \cref{lst:for-each-default}. - - \begin{cmhtcbraster}[raster column skip=.1\linewidth] - \cmhlistingsfromfile{demonstrations/for-each.tex}{\texttt{for-each.tex}}{lst:for-each} - \cmhlistingsfromfile{demonstrations/for-each-default.tex}{\texttt{for-each} default output}{lst:for-each-default} - \end{cmhtcbraster} - - Let's compare this with the output from using the YAML settings in \cref{lst:foreach}, - and running the command \index{switches!-l demonstration} - \begin{commandshell} + given in \cref{lst:tikz-node1-no-strings}. + + \begin{cmhtcbraster}[raster column skip=.1\linewidth] + \cmhlistingsfromfile{demonstrations/tikz-node1-no-strings.tex}{\texttt{tikz-node1.tex} using \cref{lst:no-strings}}{lst:tikz-node1-no-strings} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/no-strings.yaml}[yaml-TCB]{\texttt{no-strings.yaml}}{lst:no-strings} + \end{cmhtcbraster} + + In this case, \texttt{latexindent.pl} sees that: + \begin{itemize} + \item the \lstinline!\draw! command finishes after the \lstinline!(c)!, as + \texttt{stringsAllowedBetweenArguments} has been set to $0$ so there are no strings + allowed between arguments; + \item it finds a \texttt{namedGroupingBracesBrackets} called \texttt{to} (see + \vref{tab:code-blocks}) \emph{with} argument \lstinline![in=110,out=-90]! + \item it finds another \texttt{namedGroupingBracesBrackets} but this time called \texttt{node} + with argument \lstinline![below,align=left,scale=0.5]! + \end{itemize} + + Referencing \vref{lst:commandCodeBlocks}, \announce{2018-04-27}*{amalgamate feature in + commandCodeBlocks}, we see that the first field in the + \texttt{stringsAllowedBetweenArguments} is \texttt{amalgamate} and is set to \texttt{1} + by default. This is for users who wish to specify their settings in multiple YAML files. + For example, by using the settings in either \cref{lst:amalgamate-demo} + or\cref{lst:amalgamate-demo1} is equivalent to using the settings in + \cref{lst:amalgamate-demo2}.% + + \begin{cmhtcbraster}[raster columns=3, + raster left skip=-3.5cm, + raster right skip=-2cm, + raster column skip=.03\linewidth] + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/amalgamate-demo.yaml}[yaml-TCB]{\texttt{amalgamate-demo.yaml}}{lst:amalgamate-demo} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/amalgamate-demo1.yaml}[yaml-TCB]{\texttt{amalgamate-demo1.yaml}}{lst:amalgamate-demo1} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/amalgamate-demo2.yaml}[yaml-TCB]{\texttt{amalgamate-demo2.yaml}}{lst:amalgamate-demo2} + \end{cmhtcbraster} + + We specify \texttt{amalgamate} to be set to \texttt{0} and in which case any settings + loaded prior to those specified, including the default, will be overwritten. For example, + using the settings in \cref{lst:amalgamate-demo3} means that only the strings specified + in that field will be used. + + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/amalgamate-demo3.yaml}[yaml-TCB]{\texttt{amalgamate-demo3.yaml}}{lst:amalgamate-demo3} + + It is important to note that the \texttt{amalgamate} field, if used, must be in the first + field, and specified using the syntax given in + \cref{lst:amalgamate-demo1,lst:amalgamate-demo2,lst:amalgamate-demo3}. + + We may explore this feature further with the code in \cref{lst:for-each}, whose default + output is given in \cref{lst:for-each-default}. + + \begin{cmhtcbraster}[raster column skip=.1\linewidth] + \cmhlistingsfromfile{demonstrations/for-each.tex}{\texttt{for-each.tex}}{lst:for-each} + \cmhlistingsfromfile{demonstrations/for-each-default.tex}{\texttt{for-each} default output}{lst:for-each-default} + \end{cmhtcbraster} + + Let's compare this with the output from using the YAML settings in \cref{lst:foreach}, + and running the command \index{switches!-l demonstration} + \begin{commandshell} latexindent.pl for-each.tex -l foreach.yaml \end{commandshell} - given in \cref{lst:for-each-mod1}. + given in \cref{lst:for-each-mod1}. - \begin{cmhtcbraster}[raster column skip=.1\linewidth] - \cmhlistingsfromfile{demonstrations/for-each-mod1.tex}{\texttt{for-each.tex} using \cref{lst:foreach}}{lst:for-each-mod1} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/foreach.yaml}[yaml-TCB]{\texttt{foreach.yaml}}{lst:foreach} - \end{cmhtcbraster} + \begin{cmhtcbraster}[raster column skip=.1\linewidth] + \cmhlistingsfromfile{demonstrations/for-each-mod1.tex}{\texttt{for-each.tex} using \cref{lst:foreach}}{lst:for-each-mod1} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/foreach.yaml}[yaml-TCB]{\texttt{foreach.yaml}}{lst:foreach} + \end{cmhtcbraster} - You might like to compare the output given in \cref{lst:for-each-default} and - \cref{lst:for-each-mod1}. Note,in particular, in \cref{lst:for-each-default} that the - \texttt{foreach} command has not included any of the subsequent strings, and that the - braces have been treated as a \texttt{namedGroupingBracesBrackets}. In - \cref{lst:for-each-mod1} the \texttt{foreach} command has been allowed to have - \lstinline!\x/\y! and \texttt{in} between arguments because of the settings given in - \cref{lst:foreach}. + You might like to compare the output given in \cref{lst:for-each-default} and + \cref{lst:for-each-mod1}. Note,in particular, in \cref{lst:for-each-default} that the + \texttt{foreach} command has not included any of the subsequent strings, and that the + braces have been treated as a \texttt{namedGroupingBracesBrackets}. In + \cref{lst:for-each-mod1} the \texttt{foreach} command has been allowed to have + \lstinline!\x/\y! and \texttt{in} between arguments because of the settings given in + \cref{lst:foreach}. \yamltitle{commandNameSpecial}*{fields} - There are some special command names \announce{2018-04-27}*{commandNameSpecial} that do - not fit within the names recognised by \texttt{latexindent.pl}, the first one of which is - \lstinline!\@ifnextchar[!. From the perspective of \texttt{latexindent.pl}, the whole of - the text \lstinline!\@ifnextchar[! is a command, because it is immediately followed by - sets of mandatory arguments. However, without the \texttt{commandNameSpecial} field, - \texttt{latexindent.pl} would not be able to label it as such, because the \lstinline![! - is, necessarily, not matched by a closing \lstinline!]!.% - - For example, consider the sample file in \cref{lst:ifnextchar}, which has default output - in \cref{lst:ifnextchar-default}. - - \begin{cmhtcbraster}[raster column skip=.1\linewidth] - \cmhlistingsfromfile{demonstrations/ifnextchar.tex}{\texttt{ifnextchar.tex}}{lst:ifnextchar} - \cmhlistingsfromfile{demonstrations/ifnextchar-default.tex}{\texttt{ifnextchar.tex} default output}{lst:ifnextchar-default} - \end{cmhtcbraster} - - Notice that in \cref{lst:ifnextchar-default} the \texttt{parbox} command has been able to - indent its body, because \texttt{latexindent.pl} has successfully found the command - \lstinline!\@ifnextchar! first; the pattern-matching of \texttt{latexindent.pl} starts - from \emph{the inner most <thing> and works outwards}, discussed in more detail on - \cpageref{page:phases}. - - For demonstration, we can compare this output with that given in - \cref{lst:ifnextchar-off} in which the settings from \cref{lst:no-ifnextchar} have - dictated that no special command names, including the \lstinline!\@ifnextchar[! command, - should not be searched for specially; as such, the \texttt{parbox} command has been - \emph{unable} to indent its body successfully, because the \lstinline!\@ifnextchar[! - command has not been found. - - \begin{cmhtcbraster}[raster column skip=.1\linewidth] - \cmhlistingsfromfile{demonstrations/ifnextchar-off.tex}{\texttt{ifnextchar.tex} using \cref{lst:no-ifnextchar}}{lst:ifnextchar-off} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/no-ifnextchar.yaml}[yaml-TCB]{\texttt{no-ifnextchar.yaml}}{lst:no-ifnextchar} - \end{cmhtcbraster} - - The \texttt{amalgamate} field can be used for \texttt{commandNameSpecial}, just as for - \texttt{stringsAllowedBetweenArguments}. The same condition holds as stated previously, - which we state again here: \index{warning!amalgamate field} - - \begin{warning} - It is important to note that the \texttt{amalgamate} field, if used, in either - \texttt{commandNameSpecial} or \texttt{stringsAllowedBetweenArguments} must be in the - first field, and specified using the syntax given in - \cref{lst:amalgamate-demo1,lst:amalgamate-demo2,lst:amalgamate-demo3}. - \end{warning} + There are some special command names \announce{2018-04-27}*{commandNameSpecial} that do + not fit within the names recognised by \texttt{latexindent.pl}, the first one of which is + \lstinline!\@ifnextchar[!. From the perspective of \texttt{latexindent.pl}, the whole of + the text \lstinline!\@ifnextchar[! is a command, because it is immediately followed by + sets of mandatory arguments. However, without the \texttt{commandNameSpecial} field, + \texttt{latexindent.pl} would not be able to label it as such, because the \lstinline![! + is, necessarily, not matched by a closing \lstinline!]!.% + + For example, consider the sample file in \cref{lst:ifnextchar}, which has default output + in \cref{lst:ifnextchar-default}. + + \begin{cmhtcbraster}[raster column skip=.1\linewidth] + \cmhlistingsfromfile{demonstrations/ifnextchar.tex}{\texttt{ifnextchar.tex}}{lst:ifnextchar} + \cmhlistingsfromfile{demonstrations/ifnextchar-default.tex}{\texttt{ifnextchar.tex} default output}{lst:ifnextchar-default} + \end{cmhtcbraster} + + Notice that in \cref{lst:ifnextchar-default} the \texttt{parbox} command has been able to + indent its body, because \texttt{latexindent.pl} has successfully found the command + \lstinline!\@ifnextchar! first; the pattern-matching of \texttt{latexindent.pl} starts + from \emph{the inner most <thing> and works outwards}, discussed in more detail on + \cpageref{page:phases}. + + For demonstration, we can compare this output with that given in + \cref{lst:ifnextchar-off} in which the settings from \cref{lst:no-ifnextchar} have + dictated that no special command names, including the \lstinline!\@ifnextchar[! command, + should not be searched for specially; as such, the \texttt{parbox} command has been + \emph{unable} to indent its body successfully, because the \lstinline!\@ifnextchar[! + command has not been found. + + \begin{cmhtcbraster}[raster column skip=.1\linewidth] + \cmhlistingsfromfile{demonstrations/ifnextchar-off.tex}{\texttt{ifnextchar.tex} using \cref{lst:no-ifnextchar}}{lst:ifnextchar-off} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/no-ifnextchar.yaml}[yaml-TCB]{\texttt{no-ifnextchar.yaml}}{lst:no-ifnextchar} + \end{cmhtcbraster} + + The \texttt{amalgamate} field can be used for \texttt{commandNameSpecial}, just as for + \texttt{stringsAllowedBetweenArguments}. The same condition holds as stated previously, + which we state again here: \index{warning!amalgamate field} + + \begin{warning} + It is important to note that the \texttt{amalgamate} field, if used, in either + \texttt{commandNameSpecial} or \texttt{stringsAllowedBetweenArguments} must be in the + first field, and specified using the syntax given in + \cref{lst:amalgamate-demo1,lst:amalgamate-demo2,lst:amalgamate-demo3}. + \end{warning} |