summaryrefslogtreecommitdiff
path: root/support/latexindent/documentation/subsubsec-no-add-remaining-code-blocks.tex
blob: 300e39756c6601a2fe9d2d8e0c5ebdaa0c571de6 (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
% 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}