summaryrefslogtreecommitdiff
path: root/support/latexindent/documentation/sec-replacements.tex
blob: 5491df6072ab90f90e2d662f4372dd55e5c8a881 (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
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
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
% arara: pdflatex: { files: [latexindent]}
\section{The -r, -rv and -rr switches}\label{sec:replacements}
 \fancyhead[R]{\bfseries\thepage%
 \tikz[remember picture,overlay] {
 \node at (1,0){\includegraphics{logo-bw}}; }
 }

 You can instruct \texttt{latexindent.pl} to perform replacements/substitutions on your
 \announce{2019-07-13}{replacement mode switches} file by using any of the \texttt{-r},
 \texttt{-rv} or \texttt{-rr} switches: \index{verbatim!rv, replacementrespectverb switch}
 \begin{itemize}
	 \item the \texttt{-r} switch will perform indentation and replacements, not respecting verbatim
	       code blocks;
	 \item the \texttt{-rv} switch will perform indentation and replacements, and \emph{will}
	       respect verbatim code blocks;
	 \item the \texttt{-rr} switch will \emph{not} perform indentation, and will perform
	       replacements not respecting verbatim code blocks.
 \end{itemize}

 We will demonstrate each of the \texttt{-r}, \texttt{-rv} and \texttt{-rr} switches, but
 a summary is given in \cref{tab:replacementswitches}.

 \begin{table}[!htb]
	 \centering
	 \caption{The replacement mode switches}\label{tab:replacementswitches}
	 \begin{tabular}{rcc}
		 \toprule
		 switch       & indentation? & respect verbatim? \\
		 \midrule
		 \texttt{-r}  & \faCheck     & \faClose          \\
		 \texttt{-rv} & \faCheck     & \faCheck          \\
		 \texttt{-rr} & \faClose     & \faClose          \\
		 \bottomrule
	 \end{tabular}
 \end{table}

 The default value of the \texttt{replacements} field is shown in \cref{lst:replacements};
 as with all of the other fields, you are encouraged to customise and change this as you
 see fit. The options in this field will \emph{only} be considered if the \texttt{-r},
 \texttt{-rv} or \texttt{-rr} switches are active; when discussing YAML settings related
 to the replacement-mode switches, we will use the style given in \cref{lst:replacements}.

 \cmhlistingsfromfile[style=replacements]{../defaultSettings.yaml}[width=0.95\linewidth,before=\centering,replace-TCB]{\texttt{replacements}}{lst:replacements}

 The first entry within the \texttt{replacements} field is \texttt{amalgamate}, and is
 \emph{optional}; by default it is set to 1, so that replacements will be amalgamated from
 each settings file that you specify. As you'll see in the demonstrations that follow,
 there is no need to specify this field.

 You'll notice that, by default, there is only \emph{one} entry in the
 \texttt{replacements} field, but it can take as many entries as you would like; each one
 needs to begin with a \texttt{-} on its own line.

\subsection{Introduction to replacements}
	Let's explore the action of the default settings, and then we'll demonstrate the feature
	with further examples. With reference to \cref{lst:replacements}, the default action will
	replace every instance of the text \texttt{latexindent.pl} with \texttt{pl.latexindent}.

	Beginning with the code in \cref{lst:replace1} and running the command \index{switches!-r
	demonstration}
	\begin{commandshell}
latexindent.pl -r replace1.tex
\end{commandshell}
	gives the output given in \cref{lst:replace1-r1}.

	\begin{cmhtcbraster}[raster column skip=.01\linewidth]
		\cmhlistingsfromfile{demonstrations/replace1.tex}{\texttt{replace1.tex}}{lst:replace1}
		\cmhlistingsfromfile{demonstrations/replace1-r1.tex}{\texttt{replace1.tex} default}{lst:replace1-r1}
	\end{cmhtcbraster}

	If we don't wish to perform this replacement, then we can tweak the default settings of
	\vref{lst:replacements} by changing \texttt{lookForThis} to 0; we perform this action in
	\cref{lst:replace1-yaml}, and run the command \index{switches!-l demonstration}
	\index{switches!-r demonstration}
	\begin{commandshell}
latexindent.pl -r replace1.tex -l=replace1.yaml
\end{commandshell}
	which gives the output in \cref{lst:replace1-mod1}.

	\begin{cmhtcbraster}[raster column skip=.01\linewidth]
		\cmhlistingsfromfile{demonstrations/replace1-mod1.tex}{\texttt{replace1.tex} using \cref{lst:replace1-yaml}}{lst:replace1-mod1}
		\cmhlistingsfromfile[style=yaml-LST]{demonstrations/replace1.yaml}[replace-TCB]{\texttt{replace1.yaml}}{lst:replace1-yaml}
	\end{cmhtcbraster}

	Note that in \cref{lst:replace1-yaml} we have specified \texttt{amalgamate} as 0 so that
	the default replacements are overwritten.

	We haven't yet discussed the \texttt{when} field; don't worry, we'll get to it as part of
	the discussion in what follows.

\subsection{The two types of replacements}
	There are two types of replacements:
	\begin{enumerate}
		\item \emph{string}-based replacements, which replace the string in
		      \emph{this} with the string in \emph{that}.
		      If you specify \texttt{this} and you do not specify \texttt{that}, then the \texttt{that}
		      field will be assumed to be empty.
		      \index{regular expressions!replacement switch, -r}
		\item \emph{regex}-based replacements, which use the \texttt{substitution} field.
	\end{enumerate}
	We will demonstrate both in the examples that follow.

	\texttt{latexindent.pl} chooses which type of replacement to make based on which fields
	have been specified; if the \texttt{this} field is specified, then it will make
	\emph{string}-based replacements, regardless of if \texttt{substitution} is present or
	not.

\subsection{Examples of replacements}
	\begin{example}
		We begin with code given in \cref{lst:colsep}

		\cmhlistingsfromfile{demonstrations/colsep.tex}{\texttt{colsep.tex}}{lst:colsep}

		Let's assume that our goal is to remove both of the \texttt{arraycolsep} statements; we
		can achieve this in a few different ways.

		Using the YAML in \cref{lst:colsep-yaml}, and running the command \index{switches!-l
		demonstration} \index{switches!-r demonstration}
		\begin{commandshell}
latexindent.pl -r colsep.tex -l=colsep.yaml
\end{commandshell}
		then we achieve the output in \cref{lst:colsep-mod0}.
		\begin{cmhtcbraster}[raster column skip=.01\linewidth]
			\cmhlistingsfromfile{demonstrations/colsep-mod0.tex}{\texttt{colsep.tex} using \cref{lst:colsep}}{lst:colsep-mod0}
			\cmhlistingsfromfile[style=yaml-LST]{demonstrations/colsep.yaml}[replace-TCB]{\texttt{colsep.yaml}}{lst:colsep-yaml}
		\end{cmhtcbraster}
		Note that in \cref{lst:colsep-yaml}, we have specified \emph{two} separate fields, each with their own `\emph{this}' field;
		furthermore, for both of the separate fields, we have not specified `\texttt{that}', so the \texttt{that} field
		is assumed to be blank by \texttt{latexindent.pl};

		We can make the YAML in \cref{lst:colsep-yaml} more concise by exploring the
		\texttt{substitution} field. Using the settings in \cref{lst:colsep1} and running the
		command \index{switches!-l demonstration} \index{switches!-r demonstration}
		\begin{commandshell}
latexindent.pl -r colsep.tex -l=colsep1.yaml
\end{commandshell}
		then we achieve the output in \cref{lst:colsep-mod1}. \index{regular
		expressions!substitution field, arraycolsep} \index{regular expressions!at least one +}
		\begin{cmhtcbraster}[raster column skip=.01\linewidth,
				raster force size=false,
				raster column 1/.style={add to width=-.1\textwidth}]
			\cmhlistingsfromfile{demonstrations/colsep-mod1.tex}{\texttt{colsep.tex} using \cref{lst:colsep1}}{lst:colsep-mod1}
			\cmhlistingsfromfile[style=yaml-LST]{demonstrations/colsep1.yaml}[replace-TCB,width=0.6\textwidth]{\texttt{colsep1.yaml}}{lst:colsep1}
		\end{cmhtcbraster}

		The code given in \cref{lst:colsep1} is an example of a \emph{regular expression}, which
		we may abbreviate to \emph{regex} in what follows. This manual is not intended to be a
		tutorial on regular expressions; you might like to read, for example,
		\cite{masteringregexp} for a detailed covering of the topic. With reference to
		\cref{lst:colsep1}, we do note the following:
		\begin{itemize}
			\item the general form of the \texttt{substitution} field is
			      \lstinline!s/regex/replacement/modifiers!. You can place any regular expression you like
			      within this;
			\item we have `escaped' the backslash by using \lstinline!\\!
			\item we have used \lstinline!\d+! to represent \emph{at least} one digit
			\item the \texttt{s} \emph{modifier} (in the \texttt{sg} at the end of the line) instructs
			      \texttt{latexindent.pl} to treat your file as one single line;
			\item the \texttt{g} \emph{modifier} (in the \texttt{sg} at the end of the line) instructs
			      \texttt{latexindent.pl} to make the substitution \emph{globally} throughout your file;
			      you might try removing the \texttt{g} modifier from \cref{lst:colsep1} and observing the
			      difference in output.
		\end{itemize}
		You might like to see \href{https://perldoc.perl.org/perlre.html#Modifiers}{https://perldoc.perl.org/perlre.html\#Modifiers}
		for details of modifiers; in general, I recommend starting with the \texttt{sg} modifiers for this feature.
	\end{example}

	\begin{example}
		We'll keep working with the file in \vref{lst:colsep} for this example.

		Using the YAML in \cref{lst:multi-line}, and running the command \index{switches!-l
		demonstration} \index{switches!-r demonstration}
		\begin{commandshell}
latexindent.pl -r colsep.tex -l=multi-line.yaml
\end{commandshell}
		then we achieve the output in \cref{lst:colsep-mod2}.
		\begin{cmhtcbraster}[raster column skip=.01\linewidth]
			\cmhlistingsfromfile{demonstrations/colsep-mod2.tex}{\texttt{colsep.tex} using \cref{lst:multi-line}}{lst:colsep-mod2}
			\cmhlistingsfromfile[style=yaml-LST]{demonstrations/multi-line.yaml}[replace-TCB]{\texttt{multi-line.yaml}}{lst:multi-line}
		\end{cmhtcbraster}
		With reference to \cref{lst:multi-line}, we have specified a \emph{multi-line} version of \texttt{this} by employing the \emph{literal}
		YAML style \lstinline!|-!. See, for example, \href{https://stackoverflow.com/questions/3790454/in-yaml-how-do-i-break-a-string-over-multiple-lines}{https://stackoverflow.com/questions/3790454/in-yaml-how-do-i-break-a-string-over-multiple-lines}
		for further options, all of which can be used in your YAML file.

		This is a natural point to explore the \texttt{when} field, specified in
		\vref{lst:replacements}. This field can take two values: \emph{before} and \emph{after},
		which respectively instruct \texttt{latexindent.pl} to perform the replacements
		\emph{before} indentation or \emph{after} it. The default value is \texttt{before}.

		Using the YAML in \cref{lst:multi-line1}, and running the command \index{switches!-l
		demonstration} \index{switches!-r demonstration}
		\begin{commandshell}
latexindent.pl -r colsep.tex -l=multi-line1.yaml
\end{commandshell}
		then we achieve the output in \cref{lst:colsep-mod3}.
		\begin{cmhtcbraster}[raster column skip=.01\linewidth]
			\cmhlistingsfromfile{demonstrations/colsep-mod3.tex}{\texttt{colsep.tex} using \cref{lst:multi-line1}}{lst:colsep-mod3}
			\cmhlistingsfromfile[style=yaml-LST]{demonstrations/multi-line1.yaml}[replace-TCB]{\texttt{multi-line1.yaml}}{lst:multi-line1}
		\end{cmhtcbraster}
		We note that, because we have specified \texttt{when: after}, that \texttt{latexindent.pl} has not found the string specified
		in \cref{lst:multi-line1} within the file in \vref{lst:colsep}. As it has looked for the string within \cref{lst:multi-line1} \emph{after} the indentation has been performed. After
		indentation, the string as written in \cref{lst:multi-line1} is no longer part of the file, and has therefore not been replaced.

		As a final note on this example, if you use the \texttt{-rr} switch, as follows,
		\index{switches!-l demonstration} \index{switches!-rr demonstration}
		\begin{commandshell}
latexindent.pl -rr colsep.tex -l=multi-line1.yaml
\end{commandshell}
		then the \texttt{when} field is ignored, no indentation is done, and the output is as in
		\cref{lst:colsep-mod2}.
	\end{example}

	\begin{example}
		An important part of the substitution routine is in \emph{capture groups}.

		Assuming that we start with the code in \cref{lst:displaymath}, let's assume that our
		goal is to replace each occurrence of \lstinline!$$...$$! with
		\lstinline!\begin{equation*}...\end{equation*}!. This example is partly motivated by
		\href{https://tex.stackexchange.com/questions/242150/good-looking-latex-code}{tex
		stackexchange question 242150}.

		\cmhlistingsfromfile{demonstrations/displaymath.tex}{\texttt{displaymath.tex}}{lst:displaymath}

		We use the settings in \cref{lst:displaymath1} and run the command \index{switches!-l
		demonstration} \index{switches!-r demonstration}
		\begin{commandshell}
latexindent.pl -r displaymath.tex -l=displaymath1.yaml
\end{commandshell}
		to receive the output given in \cref{lst:displaymath-mod1}. \index{regular
		expressions!substitution field, equation}

		\begin{cmhtcbraster}[raster left skip=-3.75cm,
				raster right skip=-2cm,]
			\cmhlistingsfromfile{demonstrations/displaymath-mod1.tex}{\texttt{displaymath.tex} using \cref{lst:displaymath1}}{lst:displaymath-mod1}
			\cmhlistingsfromfile[style=yaml-LST]{demonstrations/displaymath1.yaml}[replace-TCB]{\texttt{displaymath1.yaml}}{lst:displaymath1}
		\end{cmhtcbraster}

		A few notes about \cref{lst:displaymath1}:
		\begin{enumerate}
			\item we have used the \texttt{x} modifier, which allows us to have white space within the
			      regex;
			\item we have used a capture group, \lstinline!(.*?)! which captures the content between the
			      \lstinline!$$...$$! into the special variable, \lstinline!$1!;
			\item we have used the content of the capture group, \lstinline!$1!, in the replacement text.
		\end{enumerate}
		See \href{https://perldoc.perl.org/perlre.html#Capture-groups}{https://perldoc.perl.org/perlre.html\#Capture-groups} for a discussion
		of capture groups.

		The features of the replacement switches can, of course, be combined with others from the
		toolkit of \texttt{latexindent.pl}. For example, we can combine the poly-switches of
		\vref{sec:poly-switches}, which we do in \cref{lst:equation}; upon running the command
		\index{switches!-l demonstration} \index{switches!-m demonstration} \index{switches!-r
		demonstration}
		\begin{commandshell}
latexindent.pl -r -m displaymath.tex -l=displaymath1.yaml,equation.yaml
\end{commandshell}
		then we receive the output in \cref{lst:displaymath-mod2}.

		\begin{cmhtcbraster}[
				raster force size=false,
				raster column 1/.style={add to width=-.1\textwidth},
				raster column skip=.06\linewidth]
			\cmhlistingsfromfile{demonstrations/displaymath-mod2.tex}{\texttt{displaymath.tex} using \cref{lst:displaymath1,lst:equation}}{lst:displaymath-mod2}
			\cmhlistingsfromfile[style=yaml-LST]{demonstrations/equation.yaml}[MLB-TCB,width=0.55\textwidth]{\texttt{equation.yaml}}{lst:equation}
		\end{cmhtcbraster}
	\end{example}

	\begin{example}
		This example is motivated by
		\href{https://tex.stackexchange.com/questions/490086/bring-several-lines-together-to-fill-blank-spaces-in-texmaker}{tex
		stackexchange question 490086}. We begin with the code in \cref{lst:phrase}.

		\cmhlistingsfromfile{demonstrations/phrase.tex}{\texttt{phrase.tex}}{lst:phrase}

		Our goal is to make the spacing uniform between the phrases. To achieve this, we employ
		the settings in \cref{lst:hspace}, and run the command \index{switches!-l demonstration}
		\index{switches!-r demonstration}
		\begin{commandshell}
latexindent.pl -r phrase.tex -l=hspace.yaml
\end{commandshell}
		which gives the output in \cref{lst:phrase-mod1}. \index{regular expressions!at least one
		+} \index{regular expressions!horizontal space \textbackslash{h}}

		\begin{cmhtcbraster}
			\cmhlistingsfromfile{demonstrations/phrase-mod1.tex}{\texttt{phrase.tex} using \cref{lst:hspace}}{lst:phrase-mod1}
			\cmhlistingsfromfile[style=yaml-LST]{demonstrations/hspace.yaml}[replace-TCB]{\texttt{hspace.yaml}}{lst:hspace}
		\end{cmhtcbraster}

		The \lstinline!\h+! setting in \cref{lst:hspace} say to replace \emph{at least one
		horizontal space} with a single space.
	\end{example}

	\begin{example}
		We begin with the code in \cref{lst:references}.

		\cmhlistingsfromfile{demonstrations/references.tex}{\texttt{references.tex}}{lst:references}

		Our goal is to change each reference so that both the text and the reference are
		contained within one hyperlink. We achieve this by employing \cref{lst:reference} and
		running the command \index{switches!-l demonstration} \index{switches!-r demonstration}
		\begin{commandshell}
latexindent.pl -r references.tex -l=reference.yaml
\end{commandshell}
		which gives the output in \cref{lst:references-mod1}. \index{regular
		expressions!horizontal space \textbackslash{h}}

		\cmhlistingsfromfile{demonstrations/references-mod1.tex}{\texttt{references.tex} using \cref{lst:reference}}{lst:references-mod1}

		\cmhlistingsfromfile[style=yaml-LST]{demonstrations/reference.yaml}[replace-TCB]{\texttt{reference.yaml}}{lst:reference}

		Referencing \cref{lst:reference}, the \lstinline!|! means \emph{or}, we have used
		\emph{capture groups}, together with an example of an \emph{optional} pattern,
		\lstinline!(?:eq)?!.
	\end{example}

	\begin{example}
		Let's explore the three replacement mode switches (see \vref{tab:replacementswitches}) in
		the context of an example that contains a verbatim code block, \cref{lst:verb1}; we will
		use the settings in \cref{lst:verbatim1-yaml}.

		\begin{cmhtcbraster}
			\cmhlistingsfromfile{demonstrations/verb1.tex}{\texttt{verb1.tex}}{lst:verb1}
			\cmhlistingsfromfile[style=yaml-LST]{demonstrations/verbatim1.yaml}[replace-TCB]{\texttt{verbatim1.yaml}}{lst:verbatim1-yaml}
		\end{cmhtcbraster}

		Upon running the following commands, \index{verbatim!comparison with -r and -rr switches}
		\index{switches!-l demonstration} \index{switches!-o demonstration} \index{switches!-r
		demonstration} \index{switches!-rv demonstration} \index{switches!-rr demonstration}
		\begin{commandshell}
latexindent.pl -r verb1.tex -l=verbatim1.yaml -o=+mod1
latexindent.pl -rv verb1.tex -l=verbatim1.yaml -o=+-rv-mod1
latexindent.pl -rr verb1.tex -l=verbatim1.yaml -o=+-rr-mod1
\end{commandshell}
		we receive the respective output in \crefrange{lst:verb1-mod1}{lst:verb1-rr-mod1}

		\begin{cmhtcbraster}[raster columns=3,
				raster left skip=-3.75cm,
				raster right skip=-2cm,]
			\cmhlistingsfromfile{demonstrations/verb1-mod1.tex}{\texttt{verb1-mod1.tex}}{lst:verb1-mod1}
			\cmhlistingsfromfile{demonstrations/verb1-rv-mod1.tex}{\texttt{verb1-rv-mod1.tex}}{lst:verb1-rv-mod1}
			\cmhlistingsfromfile{demonstrations/verb1-rr-mod1.tex}{\texttt{verb1-rr-mod1.tex}}{lst:verb1-rr-mod1}
		\end{cmhtcbraster}
	\end{example}

	We note that:
	\begin{enumerate}
		\item in \cref{lst:verb1-mod1} indentation has been performed, and that the replacements
		      specified in \cref{lst:verbatim1-yaml} have been performed, even within the verbatim code
		      block;
		\item in \cref{lst:verb1-rv-mod1} indentation has been performed, but that the replacements
		      have \emph{not} been performed within the verbatim environment, because the \texttt{rv}
		      switch is active;
		\item in \cref{lst:verb1-rr-mod1} indentation has \emph{not} been performed, but that
		      replacements have been performed, not respecting the verbatim code block.
	\end{enumerate}
	See the summary within \vref{tab:replacementswitches}.

	\begin{example}
		Let's explore the \texttt{amalgamate} field from \vref{lst:replacements} in the context
		of the file specified in \cref{lst:amalg1}.

		\cmhlistingsfromfile{demonstrations/amalg1.tex}{\texttt{amalg1.tex}}{lst:amalg1}

		Let's consider the YAML files given in \crefrange{lst:amalg1-yaml}{lst:amalg3-yaml}.

		\begin{cmhtcbraster}[raster columns=3,
				raster left skip=-3.75cm,
				raster right skip=-2cm,]
			\cmhlistingsfromfile[style=yaml-LST]{demonstrations/amalg1-yaml.yaml}[replace-TCB]{\texttt{amalg1-yaml.yaml}}{lst:amalg1-yaml}
			\cmhlistingsfromfile[style=yaml-LST]{demonstrations/amalg2-yaml.yaml}[replace-TCB]{\texttt{amalg2-yaml.yaml}}{lst:amalg2-yaml}
			\cmhlistingsfromfile[style=yaml-LST]{demonstrations/amalg3-yaml.yaml}[replace-TCB]{\texttt{amalg3-yaml.yaml}}{lst:amalg3-yaml}
		\end{cmhtcbraster}

		Upon running the following commands, \index{switches!-l demonstration} \index{switches!-r
		demonstration}
		\begin{commandshell}
latexindent.pl -r amalg1.tex -l=amalg1-yaml
latexindent.pl -r amalg1.tex -l=amalg1-yaml,amalg2-yaml
latexindent.pl -r amalg1.tex -l=amalg1-yaml,amalg2-yaml,amalg3-yaml
\end{commandshell}
		we receive the respective output in \crefrange{lst:amalg1-mod1}{lst:amalg1-mod123}.

		\begin{cmhtcbraster}[raster columns=3,
				raster left skip=-3.75cm,
				raster right skip=-2cm,]
			\cmhlistingsfromfile{demonstrations/amalg1-mod1.tex}{\texttt{amalg1.tex} using \cref{lst:amalg1-yaml}}{lst:amalg1-mod1}
			\cmhlistingsfromfile{demonstrations/amalg1-mod12.tex}{\texttt{amalg1.tex} using \cref{lst:amalg1-yaml,lst:amalg2-yaml}}{lst:amalg1-mod12}
			\cmhlistingsfromfile{demonstrations/amalg1-mod123.tex}{\texttt{amalg1.tex} using \cref{lst:amalg1-yaml,lst:amalg2-yaml,lst:amalg3-yaml}}{lst:amalg1-mod123}
		\end{cmhtcbraster}
		We note that:
		\begin{enumerate}
			\item in \cref{lst:amalg1-mod1} the replacements from \cref{lst:amalg1-yaml} have been used;
			\item in \cref{lst:amalg1-mod12} the replacements from \cref{lst:amalg1-yaml,lst:amalg2-yaml}
			      have \emph{both} been used, because the default value of \texttt{amalgamate} is 1;
			\item in \cref{lst:amalg1-mod123} \emph{only} the replacements from \cref{lst:amalg3-yaml} have
			      been used, because the value of \texttt{amalgamate} has been set to 0.
		\end{enumerate}
	\end{example}