summaryrefslogtreecommitdiff
path: root/support/latexindent/documentation/subsubsec-no-add-remaining-code-blocks.tex
blob: f72ac43d3958692ae6389dc99ca97cbd43883a56 (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
138
% arara: pdflatex: {shell: yes, 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}