summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/support/latexindent/subsubsec-no-add-remaining-code-blocks.tex
blob: e9f6c36ebb629b54dcc1969b5adf86c7a960f5da (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
% 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}

		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}
		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}

		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}
	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.

	\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}