summaryrefslogtreecommitdiff
path: root/support/latexindent/documentation/subsubsec-no-add-remaining-code-blocks.tex
blob: 437d1b827af73001f5fcf7af48f381183dcb6ada (plain)
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
% arara: pdflatex: { files: [latexindent]}
\subsubsection{The remaining code blocks}
	Referencing the different types of code blocks in \vref{tab:code-blocks}, we have a few
	code blocks yet to cover; these are very similar to the \texttt{commands} code block type
	covered comprehensively in \vref{subsubsec:commands-arguments}, but a small discussion
	defining these remaining code blocks is necessary.

	\paragraph{keyEqualsValuesBracesBrackets}
		\texttt{latexindent.pl} defines this type of code block by the following criteria:
		\begin{itemize}
			\item it must immediately follow either \lstinline!{! OR \lstinline![! OR \lstinline!,! with
			      comments and blank lines allowed.
			\item then it has a name made up of the characters detailed in \vref{tab:code-blocks};
			\item then an $=$ symbol;
			\item then at least one set of curly braces or square brackets (comments and line breaks
			      allowed throughout).
		\end{itemize}
		See the \texttt{keyEqualsValuesBracesBrackets: follow} and
		\texttt{keyEqualsValuesBracesBrackets: name} fields of the fine tuning section in
		\vref{lst:fineTuning}%
		\announce{2019-07-13}{fine tuning: keyEqualsValuesBracesBrackets}

		An example is shown in \cref{lst:pgfkeysbefore}, with the default output given in
		\cref{lst:pgfkeys1:default}.

		\begin{minipage}{.45\textwidth}
			\cmhlistingsfromfile{demonstrations/pgfkeys1.tex}{\texttt{pgfkeys1.tex}}{lst:pgfkeysbefore}
		\end{minipage}%
		\hfill
		\begin{minipage}{.5\textwidth}
			\cmhlistingsfromfile[showtabs=true]{demonstrations/pgfkeys1-default.tex}{\texttt{pgfkeys1.tex} default output}{lst:pgfkeys1:default}
		\end{minipage}%

		In \cref{lst:pgfkeys1:default}, note that the maximum indentation is three tabs, and
		these come from:
		\begin{itemize}
			\item the \lstinline!\pgfkeys! command's mandatory argument;
			\item the \lstinline!start coordinate/.initial! key's mandatory argument;
			\item the \lstinline!start coordinate/.initial! key's body, which is defined as any lines
			      following the name of the key that include its arguments. This is the part controlled by
			      the \emph{body} field for \texttt{noAdditionalIndent} and friends from
			      \cpageref{sec:noadd-indent-rules}.
		\end{itemize}
	\paragraph{namedGroupingBracesBrackets} This type of code block is mostly motivated by
		tikz-based code; we define this code block as follows:
		\begin{itemize}
			\item it must immediately follow either \emph{horizontal space} OR \emph{one or more line
			      breaks} OR \lstinline!{! OR \lstinline![! OR \lstinline!$! OR \lstinline!)! OR
			      \lstinline!(!
			\item the name may contain the characters detailed in \vref{tab:code-blocks};
			\item then at least one set of curly braces or square brackets (comments and line breaks
			      allowed throughout).
		\end{itemize}
		See the \texttt{NamedGroupingBracesBrackets: follow} and
		\texttt{NamedGroupingBracesBrackets: name} fields of the fine tuning section in
		\vref{lst:fineTuning}%
		\announce{2019-07-13}{fine tuning: namedGroupingBracesBrackets}

		A simple example is given in \cref{lst:child1}, with default output in
		\cref{lst:child1:default}.

		\begin{minipage}{.45\textwidth}
			\cmhlistingsfromfile{demonstrations/child1.tex}{\texttt{child1.tex}}{lst:child1}
		\end{minipage}%
		\hfill
		\begin{minipage}{.5\textwidth}
			\cmhlistingsfromfile[showtabs=true]{demonstrations/child1-default.tex}{\texttt{child1.tex} default output}{lst:child1:default}
		\end{minipage}%

		In particular, \texttt{latexindent.pl} considers \texttt{child}, \texttt{parent} and
		\texttt{node} all to be \texttt{namedGroupingBracesBrackets}\footnote{ You may like to
		verify this by using the \texttt{-tt} option and checking \texttt{indent.log}! }.
		Referencing \cref{lst:child1:default}, note that the maximum indentation is two tabs, and
		these come from:
		\begin{itemize}
			\item the \lstinline!child!'s mandatory argument;
			\item the \lstinline!child!'s body, which is defined as any lines following the name of the
			      \texttt{namedGroupingBracesBrackets} that include its arguments. This is the part
			      controlled by the \emph{body} field for \texttt{noAdditionalIndent} and friends from
			      \cpageref{sec:noadd-indent-rules}.
		\end{itemize}

	\paragraph{UnNamedGroupingBracesBrackets} occur in a variety of situations; specifically, we
		define this type of code block as satisfying the following criteria:
		\begin{itemize}
			\item it must immediately follow either \lstinline!{! OR \lstinline![! OR \lstinline!,! OR
			      \lstinline!&! OR \lstinline!)! OR \lstinline!(! OR \lstinline!$!;
			\item then at least one set of curly braces or square brackets (comments and line breaks
			      allowed throughout).
		\end{itemize}
		See the \texttt{UnNamedGroupingBracesBrackets: follow} field of the fine tuning section
		in \vref{lst:fineTuning}%
		\announce{2019-07-13}{fine tuning: namedGroupingBracesBrackets}

		An example is shown in \cref{lst:psforeach1} with default output give in
		\cref{lst:psforeach:default}.

		\begin{minipage}{.45\textwidth}
			\cmhlistingsfromfile{demonstrations/psforeach1.tex}{\texttt{psforeach1.tex}}{lst:psforeach1}
		\end{minipage}%
		\hfill
		\begin{minipage}{.5\textwidth}
			\cmhlistingsfromfile[showtabs=true]{demonstrations/psforeach1-default.tex}{\texttt{psforeach1.tex} default output}{lst:psforeach:default}
		\end{minipage}%

		Referencing \cref{lst:psforeach:default}, there are \emph{three} sets of unnamed braces.
		Note also that the maximum value of indentation is three tabs, and these come from:
		\begin{itemize}
			\item the \lstinline!\psforeach! command's mandatory argument;
			\item the \emph{first} un-named braces mandatory argument;
			\item the \emph{first} un-named braces \emph{body}, which we define as any lines following the
			      first opening \lstinline!{! or \lstinline![! that defined the code block. This is the
			      part controlled by the \emph{body} field for \texttt{noAdditionalIndent} and friends from
			      \cpageref{sec:noadd-indent-rules}.
		\end{itemize}
		Users wishing to customise the mandatory and/or optional arguments on a \emph{per-name}
		basis for the \texttt{UnNamedGroupingBracesBrackets} should use \texttt{always-un-named}.

	\paragraph{filecontents} code blocks behave just as \texttt{environments}, except that
		neither arguments nor items are sought.

\subsubsection{Summary}
	\index{indentation!summary}
	Having considered all of the different types of code blocks, the functions of the fields
	given in \cref{lst:noAdditionalIndentGlobal,lst:indentRulesGlobal} should now make sense.
	\index{specialBeginEnd!noAdditionalIndentGlobal}
	\index{specialBeginEnd!indentRulesGlobal}

	\begin{widepage}
		\begin{minipage}{.47\linewidth}
			\cmhlistingsfromfile[style=noAdditionalIndentGlobal]{../defaultSettings.yaml}[before=\centering,yaml-TCB]{\texttt{noAdditionalIndentGlobal}}{lst:noAdditionalIndentGlobal}
		\end{minipage}%
		\hfill
		\begin{minipage}{.47\linewidth}
			\cmhlistingsfromfile[style=indentRulesGlobal]{../defaultSettings.yaml}[before=\centering,yaml-TCB]{\texttt{indentRulesGlobal}}{lst:indentRulesGlobal}
		\end{minipage}%
	\end{widepage}