1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
|
% arara: pdflatex: {shell: yes, 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.
\yamltitle{commandCodeBlocks}*{fields}
The \texttt{commandCodeBlocks} field%
\announce{2017-08-21}*{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}
\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
\begin{commandshell}
latexindent.pl pstricks1.tex -l noRoundParentheses.yaml
\end{commandshell}
we obtain the output given in \cref{lst:pstricks1-nrp}.
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile{demonstrations/pstricks1-nrp.tex}{\texttt{pstricks1.tex} using \cref{lst:noRoundParentheses}}{lst:pstricks1-nrp}
\end{minipage}
\hfill
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/noRoundParentheses.yaml}[yaml-TCB]{\texttt{noRoundParentheses.yaml}}{lst:noRoundParentheses}
\end{minipage}
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
\begin{commandshell}
latexindent.pl pstricks1.tex -l defFunction.yaml
\end{commandshell}
then the output is as in \cref{lst:pstricks1-indent-rules}.
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile[showspaces=true]{demonstrations/pstricks1-indent-rules.tex}{\texttt{pstricks1.tex} using \cref{lst:defFunction}}{lst:pstricks1-indent-rules}
\end{minipage}
\hfill
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/defFunction.yaml}[yaml-TCB]{\texttt{defFunction.yaml}}{lst:defFunction}
\end{minipage}
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, as they are each set to $1$; 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
\begin{commandshell}
latexindent.pl tikz-node1.tex -l draw.yaml
\end{commandshell}
we receive the output given in \cref{lst:tikz-node1-draw}.
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile[showspaces=true]{demonstrations/tikz-node1-draw.tex}{\texttt{tikz-node1.tex} using \cref{lst:draw}}{lst:tikz-node1-draw}
\end{minipage}
\hfill
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/draw.yaml}[yaml-TCB]{\texttt{draw.yaml}}{lst:draw}
\end{minipage}
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-to}, and running the command
\begin{commandshell}
latexindent.pl tikz-node1.tex -l no-to.yaml
\end{commandshell}
given in \cref{lst:tikz-node1-no-to}.
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile{demonstrations/tikz-node1-no-to.tex}{\texttt{tikz-node1.tex} using \cref{lst:no-to}}{lst:tikz-node1-no-to}
\end{minipage}
\hfill
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/no-to.yaml}[yaml-TCB]{\texttt{no-to.yaml}}{lst:no-to}
\end{minipage}
In this case, \texttt{latexindent.pl} sees that:
\begin{itemize}
\item the \lstinline!\draw! command finishes after the \lstinline!(c)! as (\texttt{stringsAllowedBetweenArguments} has \texttt{to} set to $0$)
\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}
\yamltitle{commandNameSpecial}*{fields}
There are some special command names%
\announce{2017-08-21}{commandNameSpecial} that do not fit within the names recognized 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 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{minipage}{.45\textwidth}
\cmhlistingsfromfile{demonstrations/ifnextchar.tex}{\texttt{ifnextchar.tex}}{lst:ifnextchar}
\end{minipage}
\hfill
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile{demonstrations/ifnextchar-default.tex}{\texttt{ifnextchar.tex} default output}{lst:ifnextchar-default}
\end{minipage}
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 \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{minipage}{.45\textwidth}
\cmhlistingsfromfile{demonstrations/ifnextchar-off.tex}{\texttt{ifnextchar.tex} using \cref{lst:no-ifnextchar}}{lst:ifnextchar-off}
\end{minipage}
\hfill
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/no-ifnextchar.yaml}[yaml-TCB]{\texttt{no-ifnextchar.yaml}}{lst:no-ifnextchar}
\end{minipage}
|
