summaryrefslogtreecommitdiff
path: root/support/latexindent/documentation/sec-default-user-local.tex
blob: 85738608b9f408e53601f935fc9765e75603dad9 (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
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
% arara: pdflatex: {shell: yes, files: [latexindent]}
\section{defaultSettings.yaml}\label{sec:defuseloc}
 \texttt{latexindent.pl} loads its settings from \texttt{defaultSettings.yaml}. The idea
 is to separate the behaviour of the script from the internal working -- this is very
 similar to the way that we separate content from form when writing our documents in
 \LaTeX.

 If you look in \texttt{defaultSettings.yaml} you'll find the switches that govern the
 behaviour of \texttt{latexindent.pl}. If you're not sure where
 \texttt{defaultSettings.yaml} resides on your computer, don't worry as
 \texttt{indent.log} will tell you where to find it. \texttt{defaultSettings.yaml} is
 commented, but here is a description of what each switch is designed to do. The default
 value is given in each case; whenever you see \emph{integer} in \emph{this} section,
 assume that it must be greater than or equal to \texttt{0} unless otherwise stated.

 For most of the settings in \texttt{defaultSettings.yaml} that are specified as integers,
 then we understand \texttt{0} to represent `off' and \texttt{1} to represent `on'. For
 fields that allow values other than \texttt{0} or \texttt{1}, it is hoped that the
 specific context and associated commentary should make it clear which values are allowed.

\yamltitle{fileExtensionPreference}*{fields}
	\texttt{latexindent.pl} can be called to
	act on a file without specifying the file extension. For example we can call
	\begin{commandshell}
latexindent.pl myfile
\end{commandshell}
	in which case the script will look for \texttt{myfile} with the extensions specified in
	\texttt{fileExtensionPreference} in their numeric order. If no match is found, the script
	will exit. As with all of the fields, you should change and/or add to this as necessary.

	\cmhlistingsfromfile[style=fileExtensionPreference]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{fileExtensionPreference}}{lst:fileExtensionPreference}

	Calling \texttt{latexindent.pl myfile} with the (default) settings specified in
	\cref{lst:fileExtensionPreference} means that the script will first look for
	\texttt{myfile.tex}, then \texttt{myfile.sty}, \texttt{myfile.cls}, and finally
	\texttt{myfile.bib} in order\footnote{Throughout this manual, listings shown with line
		numbers represent code taken directly from \texttt{defaultSettings.yaml}.}.

	\index{backup files!extension settings}

\subsection{Backup and log file preferences}
\yamltitle{backupExtension}*{extension name}

	If you call \texttt{latexindent.pl} with the \texttt{-w} switch (to overwrite
	\texttt{myfile.tex}) then it will create a backup file before doing any indentation; the
	default extension is \texttt{.bak}, so, for example, \texttt{myfile.bak0} would be
	created when calling \texttt{latexindent.pl myfile.tex} for the first time.

	By default, every time you subsequently call \texttt{latexindent.pl} with the \texttt{-w}
	to act upon \texttt{myfile.tex}, it will create successive back up files:
	\texttt{myfile.bak1}, \texttt{myfile.bak2}, etc.

\yamltitle{onlyOneBackUp}*{integer}
	\label{page:onlyonebackup}
	\index{backup files!number of backup files}
	If you don't want a backup for every time that you call \texttt{latexindent.pl} (so you
	don't want \texttt{myfile.bak1}, \texttt{myfile.bak2}, etc) and you simply want
	\texttt{myfile.bak} (or whatever you chose \texttt{backupExtension} to be) then change
	\texttt{onlyOneBackUp} to \texttt{1}; the default value of \texttt{onlyOneBackUp} is
	\texttt{0}.
	\index{backup files!maximum number of backup files}
	\index{backup files!number of backup files}

\yamltitle{maxNumberOfBackUps}*{integer}
	Some users may only want a finite number of backup files, say at most $3$, in which case,
	they can change this switch. The smallest value of \texttt{maxNumberOfBackUps} is $0$
	which will \emph{not} prevent backup files being made; in this case, the behaviour will
	be dictated entirely by \texttt{onlyOneBackUp}. The default value of
	\texttt{maxNumberOfBackUps} is \texttt{0}.

\yamltitle{cycleThroughBackUps}*{integer}
	\index{backup files!cycle through}
	Some users may wish to cycle through backup files, by deleting the oldest backup file and
	keeping only the most recent; for example, with \texttt{maxNumberOfBackUps: 4}, and
	\texttt{cycleThroughBackUps} set to \texttt{1} then the \texttt{copy} procedure given
	below would be obeyed.

	\begin{commandshell}
copy myfile.bak1 to myfile.bak0
copy myfile.bak2 to myfile.bak1
copy myfile.bak3 to myfile.bak2
copy myfile.bak4 to myfile.bak3
\end{commandshell}
	The default value of \texttt{cycleThroughBackUps} is \texttt{0}.

\yamltitle{logFilePreferences}*{fields}
	\texttt{latexindent.pl} writes information to \texttt{indent.log}, some
	of which can be customized by changing \texttt{logFilePreferences}; see
	\cref{lst:logFilePreferences}. If you load your own user settings (see
	\vref{sec:indentconfig}) then \texttt{latexindent.pl} will detail them in
	\texttt{indent.log}; you can choose not to have the details logged by switching
	\texttt{showEveryYamlRead} to \texttt{0}. Once all of your settings have been loaded, you
	can see the amalgamated settings in the log file by switching
	\texttt{showAmalgamatedSettings} to \texttt{1}, if you wish.

	\cmhlistingsfromfile[style=logFilePreferences,]*{../defaultSettings.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{logFilePreferences}}{lst:logFilePreferences}

	When%
	\announce{2018-01-13}{showDecorationStartCodeBlockTrace feature for log file} either of
	the \texttt{trace} modes (see \cpageref{page:traceswitch}) are active, you will receive
	detailed information in \texttt{indent.log}. You can specify character strings to appear
	before and after the notification of a found code block using, respectively,
	\texttt{showDecorationStartCodeBlockTrace} and
	\texttt{showDecorationFinishCodeBlockTrace}. A demonstration is given in
	\vref{app:logfile-demo}.

	The log file will end with the characters given in \texttt{endLogFileWith}, and will
	report the \texttt{GitHub} address of \texttt{latexindent.pl} to the log file if
	\texttt{showGitHubInfoFooter} is set to \texttt{1}.

	Note: \texttt{latexindent.pl} no longer uses the \texttt{log4perl} module to handle the
	creation of the logfile.%
	\announce{2021-03-14}*{no longer using log4perl}

	Some of the options%
	\announce{2021-06-19}*{logFilePreferences updated to include Dumper options}for Perl's
	\texttt{Dumper} module can be specified in \cref{lst:logFilePreferences}; see
	\cite{dumper} and \cite{dumperdemo} for more information. These options will mostly be
	helpful for those calling \texttt{latexindent.pl} with the \texttt{-tt} option described
	in \cref{sec:commandline}.

\subsection{Verbatim code blocks}
\yamltitle{verbatimEnvironments}*{fields}

	A field that contains a list of environments that you would like left completely alone --
	no indentation will be performed on environments that you have specified in this field,
	see \cref{lst:verbatimEnvironments}.
	\index{verbatim!environments}
	\index{verbatim!commands}

	\begin{cmhtcbraster}[raster column skip=.1\linewidth]
		\cmhlistingsfromfile[style=verbatimEnvironments]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{verbatimEnvironments}}{lst:verbatimEnvironments}
		\cmhlistingsfromfile[style=verbatimCommands]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{verbatimCommands}}{lst:verbatimCommands}
	\end{cmhtcbraster}

	Note that if you put an environment in	\texttt{verbatimEnvironments} and in other fields
	such as \texttt{lookForAlignDelims} or \texttt{noAdditionalIndent} then
	\texttt{latexindent.pl} will \emph{always} prioritize \texttt{verbatimEnvironments}.

\yamltitle{verbatimCommands}*{fields}
	A field that contains a list of commands that are verbatim commands, for example
	\lstinline|\lstinline|; any commands populated in this field are protected from line
	breaking routines (only relevant if the \texttt{-m} is active, see
	\vref{sec:modifylinebreaks}).

	With reference to \cref{lst:verbatimCommands}, by default \texttt{latexindent.pl} looks
	for
	\lstinline|\verb| immediately followed by another character, and then it takes the
	body as anything up to the next occurrence of the character; this means that, for
	example, \lstinline|\verb!x+3!| is treated as a \texttt{verbatimCommands}.

\yamltitle{noIndentBlock}*{fields}
	If you have a block of code that you don't want \texttt{latexindent.pl} to touch (even if
	\index{verbatim!noIndentBlock} it is \emph{not} a verbatim-like environment) then you can
	wrap it in an environment from \texttt{noIndentBlock}; you can use any name you like for
	this, provided you populate it as demonstrate in \cref{lst:noIndentBlock}.

	\cmhlistingsfromfile[style=noIndentBlock]*{../defaultSettings.yaml}[width=.4\linewidth,before=\centering,yaml-TCB]{\texttt{noIndentBlock}}{lst:noIndentBlock}

	Of course, you don't want to have to specify these as null environments in your code, so
	you use them with a comment symbol, \lstinline!%!, followed by as many spaces (possibly
	none) as you like; see \cref{lst:noIndentBlockdemo} for example.

	\cmhlistingsfromfile{demonstrations/noindentblock.tex}{\texttt{noIndentBlock.tex}}{lst:noIndentBlockdemo}

	Important note: it is assumed that the \texttt{noindent} block statements specified in
	this way appear on their own line.

	The%
	\announce{2021-06-19}{noIndentBlock specified as regex} \texttt{noIndentBlock} fields can also be specified in terms of \texttt{begin} and
	\texttt{end} fields. We use the code in \cref{lst:noIndentBlock1} to demonstrate this
	feature.

	\cmhlistingsfromfile{demonstrations/noindentblock1.tex}{\texttt{noIndentBlock1.tex}}{lst:noIndentBlock1}

	The settings given in \cref{lst:noindent1,lst:noindent2} are equivalent:

	\begin{cmhtcbraster}[raster columns=3,
			raster left skip=-3.5cm,
			raster right skip=-2cm,
			raster column skip=.03\linewidth]
		\cmhlistingsfromfile{demonstrations/noindent1.yaml}[yaml-TCB]{\texttt{noindent1.yaml}}{lst:noindent1}
		\cmhlistingsfromfile{demonstrations/noindent2.yaml}[yaml-TCB]{\texttt{noindent2.yaml}}{lst:noindent2}
		\cmhlistingsfromfile{demonstrations/noindent3.yaml}[yaml-TCB]{\texttt{noindent3.yaml}}{lst:noindent3}
	\end{cmhtcbraster}

	Upon running the commands
	\begin{commandshell}
latexindent.pl -l noindent1.yaml noindent1
latexindent.pl -l noindent2.yaml noindent1
\end{commandshell}
	then we receive the output given in \cref{lst:noIndentBlock1-mod1}.

	\cmhlistingsfromfile{demonstrations/noindentblock1-mod1.tex}{\texttt{noIndentBlock1.tex} using \cref{lst:noindent1} or \cref{lst:noindent2}}{lst:noIndentBlock1-mod1}

	The \texttt{begin}, \texttt{body} and \texttt{end} fields for \texttt{noIndentBlock} are
	all \emph{regular expressions}. If the \texttt{body} field is not specified, then it
	takes a default value of
	\lstinline!.*?! which is written explicitly in \cref{lst:noindent1}. In this
	context, we interpret \lstinline!.*?! in words as \emph{the fewest number of characters
		(possibly none) until the `end' field is reached}.

	The \texttt{lookForThis} field is optional, and can take the values 0 (off) or 1 (on); by
	default, it is assumed to be 1 (on).

	Using \cref{lst:noindent3} demonstrates setting \texttt{lookForThis} to 0 (off); running
	the command
	\begin{commandshell}
latexindent.pl -l noindent3.yaml noindent1
\end{commandshell}
	gives the output in \cref{lst:noIndentBlock1-mod3}.

	\cmhlistingsfromfile{demonstrations/noindentblock1-mod3.tex}{\texttt{noIndentBlock1.tex} using \cref{lst:noindent3}}{lst:noIndentBlock1-mod3}

	We will demonstrate this feature later in the documentation in \cref{lst:href3}.

\subsection{filecontents and preamble}
\yamltitle{fileContentsEnvironments}*{field}

	Before \texttt{latexindent.pl} determines the difference between preamble (if any) and
	the main document, it first searches for any of the environments specified in
	\texttt{fileContentsEnvironments}, see \cref{lst:fileContentsEnvironments}. The behaviour
	of \texttt{latexindent.pl} on these environments is determined by their location
	(preamble or not), and the value \texttt{indentPreamble}, discussed next.

	\cmhlistingsfromfile[style=fileContentsEnvironments]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{fileContentsEnvironments}}{lst:fileContentsEnvironments}

\yamltitle{indentPreamble}{0|1}

	The preamble of a document can sometimes contain some trickier code for
	\texttt{latexindent.pl} to operate upon. By default, \texttt{latexindent.pl} won't try to
	operate on the preamble (as \texttt{indentPreamble} is set to \texttt{0}, by default),
	but if you'd like \texttt{latexindent.pl} to try then change \texttt{indentPreamble} to
	\texttt{1}.

\yamltitle{lookForPreamble}*{fields}

	Not all files contain preamble; for example, \texttt{sty}, \texttt{cls} and \texttt{bib}
	files typically do \emph{not}. Referencing \cref{lst:lookForPreamble}, if you set, for
	example, \texttt{.tex} to \texttt{0}, then regardless of the setting of the value of
	\texttt{indentPreamble}, preamble will not be assumed when operating upon \texttt{.tex}
	files.

	\cmhlistingsfromfile[style=lookForPreamble]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{lookForPreamble}{lst:lookForPreamble}
\yamltitle{preambleCommandsBeforeEnvironments}{0|1}
	Assuming that \texttt{latexindent.pl} is asked to operate upon the preamble of a
	document, when this switch is set to \texttt{0} then environment code blocks will be
	sought first, and then command code blocks. When this switch is set to \texttt{1},
	commands will be sought first. The example that first motivated this switch contained the
	code given in \cref{lst:motivatepreambleCommandsBeforeEnvironments}.

	\begin{cmhlistings}{Motivating \texttt{preambleCommandsBeforeEnvironments}}{lst:motivatepreambleCommandsBeforeEnvironments}
...
preheadhook={\begin{mdframed}[style=myframedstyle]},
postfoothook=\end{mdframed},
...
\end{cmhlistings}

	\index{indentation!defaultIndent description}

\subsection{Indentation and horizontal space}
\yamltitle{defaultIndent}*{horizontal space}
	This is the default indentation used in the absence of other details for the code block
	with which we are working. The default value is \lstinline!\t! which means a tab; we will
	explore customisation beyond \texttt{defaultIndent} in \vref{sec:noadd-indent-rules}.

	If you're interested in experimenting with \texttt{latexindent.pl} then you can
	\emph{remove} all indentation by setting \texttt{defaultIndent: ""}.

\yamltitle{removeTrailingWhitespace}*{fields}\label{yaml:removeTrailingWhitespace}

	Trailing white space can be removed both \emph{before} and \emph{after} processing the
	document, as detailed in \cref{lst:removeTrailingWhitespace}; each of the fields can take
	the values \texttt{0} or \texttt{1}. See
	\vref{lst:removeTWS-before,lst:env-mlb5-modAll,lst:env-mlb5-modAll-remove-WS} for before
	and after results. Thanks to \cite{vosskuhle} for providing this feature.

	\begin{minipage}{.4\textwidth}
		\cmhlistingsfromfile[style=removeTrailingWhitespace]*{../defaultSettings.yaml}[before=\centering,yaml-TCB]{removeTrailingWhitespace}{lst:removeTrailingWhitespace}
	\end{minipage}%
	\hfill
	\begin{minipage}{.5\textwidth}
		\begin{yaml}[numbers=none]{removeTrailingWhitespace (alt)}[before=\centering]{lst:removeTrailingWhitespace-alt}
removeTrailingWhitespace: 1
\end{yaml}
	\end{minipage}%

	You can specify \texttt{removeTrailingWhitespace} simply as \texttt{0} or \texttt{1}, if
	you wish; in this case,%
	\announce{2017-06-28}{removeTrailingWhitespace} \texttt{latexindent.pl} will set both
	\texttt{beforeProcessing} and \texttt{afterProcessing} to the value you specify; see
	\cref{lst:removeTrailingWhitespace-alt}.

\subsection{Aligning at delimiters}
\yamltitle{lookForAlignDelims}*{fields}
	This contains a list of code blocks that are operated upon in a special way by
	\texttt{latexindent.pl} (see \cref{lst:aligndelims:basic}). In fact, the fields in
	\texttt{lookForAlignDelims} can actually take two different forms: the \emph{basic}
	version is shown in \cref{lst:aligndelims:basic} and the \emph{advanced} version in
	\cref{lst:aligndelims:advanced}; we will discuss each in turn.
	\index{delimiters!advanced settings of lookForAlignDelims}

	\begin{yaml}[numbers=none]{\texttt{lookForAlignDelims} (basic)}[width=.8\linewidth,before=\centering]{lst:aligndelims:basic}
lookForAlignDelims:
   tabular: 1
   tabularx: 1
   longtable: 1
   array: 1
   matrix: 1
   ...
	\end{yaml}

	Specifying code blocks in this field instructs \texttt{latexindent.pl} to try and align
	each column by its alignment delimiters. It does have some limitations (discussed further
	in \cref{sec:knownlimitations}), but in many cases it will produce results such as those
	in \cref{lst:tabularbefore:basic,lst:tabularafter:basic}.

	If you find that \texttt{latexindent.pl} does not perform satisfactorily on such
	environments then you can set the relevant key to \texttt{0}, for example
	\texttt{tabular: 0}; alternatively, if you just want to ignore \emph{specific} instances
	of the environment, you could wrap them in something from \texttt{noIndentBlock} (see
	\vref{lst:noIndentBlock}).

	\begin{cmhtcbraster}
		\cmhlistingsfromfile{demonstrations/tabular1.tex}{\texttt{tabular1.tex}}{lst:tabularbefore:basic}
		\cmhlistingsfromfile{demonstrations/tabular1-default.tex}{\texttt{tabular1.tex} default output}{lst:tabularafter:basic}
	\end{cmhtcbraster}

	If, for example, you wish to remove the alignment of the \lstinline!\\! within a
	delimiter-aligned block, then the advanced form of \texttt{lookForAlignDelims} shown in
	\cref{lst:aligndelims:advanced} is for you.
	\index{regular expressions!delimiterRegEx}
	\index{regular expressions!ampersand alignment}
	\index{delimiters!default settings of lookForAlignDelims}
	\index{delimiters!ampersand \&}
	\index{delimiters!advanced settings}
	\index{delimiters!lookForAlignDelims}

	\cmhlistingsfromfile[style=lookForAlignDelims]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{lookForAlignDelims} (advanced)}{lst:aligndelims:advanced}

	Note that you can use a mixture of the basic and advanced form: in
	\cref{lst:aligndelims:advanced} \texttt{tabular} and \texttt{tabularx} are advanced and
	\texttt{longtable} is basic. When using the advanced form, each field should receive at
	least 1 sub-field, and \emph{can} (but does not have to) receive any of the following
	fields:
	\begin{itemize}
		\item \texttt{delims}: binary switch (0 or 1) equivalent to simply specifying, for
		      example, \texttt{tabular: 1} in the basic version shown in \cref{lst:aligndelims:basic}.
		      If \texttt{delims} is set to \texttt{0} then the align at ampersand routine will not be
		      called for this code block (default: 1);
		\item \texttt{alignDoubleBackSlash}: binary switch (0 or 1) to determine if
		      \lstinline!\\!
		      should be aligned (default: 1);
		\item \texttt{spacesBeforeDoubleBackSlash}: optionally,%
		      \announce{2018-01-13}*{update to spacesBeforeDoubleBackSlash in ampersand alignment}
		      specifies the number (integer $\geq$ 0) of spaces to be inserted before
		      \lstinline!\\! (default: 1); %\footnote{Previously this only activated if \texttt{alignDoubleBackSlash} was set to \texttt{0}.}
		\item \announce{2017-06-19}{multiColumnGrouping} \texttt{multiColumnGrouping}: binary switch (0
		      or 1) that details if \texttt{latexindent.pl} should group columns above and below a
		      \lstinline!\multicolumn! command (default: 0);
		\item \announce{2017-06-19}{alignRowsWithoutMaxDelims} \texttt{alignRowsWithoutMaxDelims}:
		      binary switch (0 or 1) that details if rows that do not contain the maximum number of
		      delimeters should be formatted so as to have the ampersands aligned (default: 1);
		\item \announce{2018-01-13}{spacesBeforeAmpersand in ampersand alignment}\texttt{spacesBeforeAmpersand}: optionally specifies the number (integer $\geq$
		      0) of spaces to be placed \emph{before} ampersands (default: 1);
		\item \announce{2018-01-13}{spacesAfterAmpersand in ampersand alignment}\texttt{spacesAfterAmpersand}: optionally specifies the number (integer $\geq$
		      0) of spaces to be placed \emph{After} ampersands (default: 1);
		\item \announce{2018-01-13}{justification of cells in ampersand alignment}\texttt{justification}: optionally specifies the justification of each cell as
		      either \emph{left} or \emph{right} (default: left);
		\item \announce{2020-03-21}{align final double back slash}{alignFinalDoubleBackSlash}
		      optionally specifies if the \emph{final} double back slash should be used for alignment
		      (default: 0);
		\item \announce{2020-03-21}{don't measure feature}{dontMeasure} optionally specifies if
		      user-specified cells, rows or the largest entries should \emph{not} be measured (default:
		      0);
		\item \announce{2020-03-21}{delimiter RegEx feature}{delimiterRegEx} optionally specifies the
		      pattern matching to be used for the alignment delimeter (default:
		      \lstinline3 '(?<!\\)(&)'3);
		\item \announce{2020-03-21}{delimiter justification}{delimiterJustification} optionally
		      specifies the justification for the alignment delimeters (default: left); note that this
		      feature is only useful if you have delimiters of different lengths in the same column,
		      discussed in \cref{sec:delimiter-reg-ex}.
	\end{itemize}

	We will explore most of these features using the file \texttt{tabular2.tex} in
	\cref{lst:tabular2} (which contains a \lstinline!\multicolumn! command), and the YAML
	files in \crefrange{lst:tabular2YAML}{lst:tabular8YAML}; we will explore
	\texttt{alignFinalDoubleBackSlash} in \cref{lst:tabular4}; the \texttt{dontMeasure}
	feature will be described in \cref{sec:dontMeasure}, and \texttt{delimiterRegEx} in
	\cref{sec:delimiter-reg-ex}.

	\cmhlistingsfromfile{demonstrations/tabular2.tex}{\texttt{tabular2.tex}}{lst:tabular2}
	\begin{minipage}{.45\textwidth}
		\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/tabular2.yaml}[yaml-TCB]{\texttt{tabular2.yaml}}{lst:tabular2YAML}
	\end{minipage}%
	\hfill
	\begin{minipage}{.48\textwidth}
		\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/tabular3.yaml}[yaml-TCB]{\texttt{tabular3.yaml}}{lst:tabular3YAML}
	\end{minipage}%

	\begin{minipage}{.45\textwidth}
		\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/tabular4.yaml}[yaml-TCB]{\texttt{tabular4.yaml}}{lst:tabular4YAML}
	\end{minipage}%
	\hfill
	\begin{minipage}{.48\textwidth}
		\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/tabular5.yaml}[yaml-TCB]{\texttt{tabular5.yaml}}{lst:tabular5YAML}
	\end{minipage}%

	\begin{minipage}{.45\textwidth}
		\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/tabular6.yaml}[yaml-TCB]{\texttt{tabular6.yaml}}{lst:tabular6YAML}
	\end{minipage}%
	\hfill
	\begin{minipage}{.48\textwidth}
		\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/tabular7.yaml}[yaml-TCB]{\texttt{tabular7.yaml}}{lst:tabular7YAML}
	\end{minipage}%

	\begin{minipage}{.48\textwidth}
		\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/tabular8.yaml}[yaml-TCB]{\texttt{tabular8.yaml}}{lst:tabular8YAML}
	\end{minipage}%

	On running the commands
	\index{delimiters!spacing demonstration}
	\index{switches!-l demonstration}
	\begin{commandshell}
latexindent.pl tabular2.tex 
latexindent.pl tabular2.tex -l tabular2.yaml
latexindent.pl tabular2.tex -l tabular3.yaml
latexindent.pl tabular2.tex -l tabular2.yaml,tabular4.yaml
latexindent.pl tabular2.tex -l tabular2.yaml,tabular5.yaml
latexindent.pl tabular2.tex -l tabular2.yaml,tabular6.yaml
latexindent.pl tabular2.tex -l tabular2.yaml,tabular7.yaml
latexindent.pl tabular2.tex -l tabular2.yaml,tabular8.yaml
\end{commandshell}
	we obtain the respective outputs given in
	\crefrange{lst:tabular2-default}{lst:tabular2-mod8}.

	\begin{widepage}
		\cmhlistingsfromfile{demonstrations/tabular2-default.tex}{\texttt{tabular2.tex} default output}{lst:tabular2-default}
		\cmhlistingsfromfile{demonstrations/tabular2-mod2.tex}{\texttt{tabular2.tex} using \cref{lst:tabular2YAML}}{lst:tabular2-mod2}
		\cmhlistingsfromfile{demonstrations/tabular2-mod3.tex}{\texttt{tabular2.tex} using \cref{lst:tabular3YAML}}{lst:tabular2-mod3}
		\cmhlistingsfromfile{demonstrations/tabular2-mod4.tex}{\texttt{tabular2.tex} using \cref{lst:tabular2YAML,lst:tabular4YAML}}{lst:tabular2-mod4}
		\cmhlistingsfromfile{demonstrations/tabular2-mod5.tex}{\texttt{tabular2.tex} using \cref{lst:tabular2YAML,lst:tabular5YAML}}{lst:tabular2-mod5}
		\cmhlistingsfromfile{demonstrations/tabular2-mod6.tex}{\texttt{tabular2.tex} using \cref{lst:tabular2YAML,lst:tabular6YAML}}{lst:tabular2-mod6}
		\cmhlistingsfromfile{demonstrations/tabular2-mod7.tex}{\texttt{tabular2.tex} using \cref{lst:tabular2YAML,lst:tabular7YAML}}{lst:tabular2-mod7}
		\cmhlistingsfromfile{demonstrations/tabular2-mod8.tex}{\texttt{tabular2.tex} using \cref{lst:tabular2YAML,lst:tabular8YAML}}{lst:tabular2-mod8}
	\end{widepage}

	Notice in particular:
	\begin{itemize}
		\item in both \cref{lst:tabular2-default,lst:tabular2-mod2} all rows have been aligned at the
		      ampersand, even those that do not contain the maximum number of ampersands (3 ampersands,
		      in this case);
		\item in \cref{lst:tabular2-default} the columns have been aligned at the ampersand;
		\item in \cref{lst:tabular2-mod2} the \lstinline!\multicolumn! command has grouped the $2$
		      columns beneath \emph{and} above it, because \texttt{multiColumnGrouping} is set to $1$
		      in \cref{lst:tabular2YAML};
		\item in \cref{lst:tabular2-mod3} rows~3 and~6 have \emph{not} been aligned at the ampersand,
		      because \texttt{alignRowsWithoutMaxDelims} has been to set to $0$ in
		      \cref{lst:tabular3YAML}; however, the \lstinline!\\! \emph{have} still been aligned;
		\item in \cref{lst:tabular2-mod4} the columns beneath and above the \lstinline!\multicolumn!
		      commands have been grouped (because \texttt{multiColumnGrouping} is set to $1$), and
		      there are at least $4$ spaces \emph{before} each aligned ampersand because
		      \texttt{spacesBeforeAmpersand} is set to $4$;
		\item in \cref{lst:tabular2-mod5} the columns beneath and above the \lstinline!\multicolumn!
		      commands have been grouped (because \texttt{multiColumnGrouping} is set to $1$), and
		      there are at least $4$ spaces \emph{after} each aligned ampersand because
		      \texttt{spacesAfterAmpersand} is set to $4$;
		\item in \cref{lst:tabular2-mod6} the \lstinline!\\! have \emph{not} been aligned, because
		      \texttt{alignDoubleBackSlash} is set to \texttt{0}, otherwise the output is the same as
		      \cref{lst:tabular2-mod2};
		\item in \cref{lst:tabular2-mod7} the \lstinline!\\! \emph{have} been aligned, and because
		      \texttt{spacesBeforeDoubleBackSlash} is set to \texttt{0}, there are no spaces ahead of
		      them; the output is otherwise the same as \cref{lst:tabular2-mod2};
		\item in \cref{lst:tabular2-mod8} the cells have been \emph{right}-justified; note that cells
		      above and below the \lstinline!\multicol! statements have still been group correctly,
		      because of the settings in \cref{lst:tabular2YAML}.
	\end{itemize}

\subsubsection{lookForAlignDelims: spacesBeforeAmpersand}
	The \texttt{spacesBeforeAmpersand}%
	\announce{2021-06-19}*{spacesBeforeAmpersand leading blank column upgrade} can be
	specified in a few different ways. The \emph{basic} form is demonstrated in
	\cref{lst:tabular4YAML}, but we can customise the behaviour further by specifying if we
	would like this value to change if it encounters a \emph{leading blank column}; that is,
	when the first column contains only zero-width entries. We refer to this as the
	\emph{advanced} form.

	We demonstrate this feature in relation to \cref{lst:aligned1}; upon running the
	following command
	\begin{commandshell}
latexindent.pl aligned1.tex -o=+-default
\end{commandshell}
	then we receive the default output given in \cref{lst:aligned1-default}.

	\begin{cmhtcbraster}
		\cmhlistingsfromfile{demonstrations/aligned1.tex}{\texttt{aligned1.tex}}{lst:aligned1}
		\cmhlistingsfromfile{demonstrations/aligned1-default.tex}{\texttt{aligned1-default.tex}}{lst:aligned1-default}
	\end{cmhtcbraster}

	The settings in \crefrange{lst:sba1}{lst:sba4} are all equivlanent; we have used the
	not-yet discussed \texttt{noAdditionalIndent} field (see \vref{sec:noadd-indent-rules})
	which will assist in the demonstration in what follows.
	\begin{cmhtcbraster}[raster columns=2, ]
		\cmhlistingsfromfile{demonstrations/sba1.yaml}[yaml-TCB]{\texttt{sba1.yaml}}{lst:sba1}
		\cmhlistingsfromfile{demonstrations/sba2.yaml}[yaml-TCB]{\texttt{sba2.yaml}}{lst:sba2}
		\cmhlistingsfromfile{demonstrations/sba3.yaml}[yaml-TCB]{\texttt{sba3.yaml}}{lst:sba3}
		\cmhlistingsfromfile{demonstrations/sba4.yaml}[yaml-TCB]{\texttt{sba4.yaml}}{lst:sba4}
	\end{cmhtcbraster}
	Upon running the following commands
	\begin{commandshell}
latexindent.pl aligned1.tex -l sba1.yaml
latexindent.pl aligned1.tex -l sba2.yaml
latexindent.pl aligned1.tex -l sba3.yaml
latexindent.pl aligned1.tex -l sba4.yaml
\end{commandshell}
	then we receive the (same) output given in \cref{lst:aligned1-mod1}; we note that there
	is \emph{one space} before each ampersand.

	\begin{cmhtcbraster}
		\cmhlistingsfromfile{demonstrations/aligned1-mod1.tex}{\texttt{aligned1-mod1.tex}}{lst:aligned1-mod1}
	\end{cmhtcbraster}

	We note in particular:
	\begin{itemize}
		\item \cref{lst:sba1} demonstrates the \emph{basic} form for
		      \texttt{lookForAlignDelims}; in this case,
		      the default values are specified as in \vref{lst:aligndelims:advanced};
		\item \cref{lst:sba2} demonstrates the \emph{advanced} form for
		      \texttt{lookForAlignDelims}
		      and specified \texttt{spacesBeforeAmpersand}. The default value is \texttt{1};
		\item \cref{lst:sba3} demonstrates the new \emph{advanced} way to specify
		      \texttt{spacesBeforeAmpersand}, and
		      for us to set the \texttt{default} value that sets the number of spaces before ampersands
		      which are \emph{not} in leading blank columns. The default value is \texttt{1}.

		      We note that \texttt{leadingBlankColumn} has not been specified in \cref{lst:sba3}, and
		      it will inherit the value from \texttt{default};
		\item \cref{lst:sba4} demonstrates spaces to be used before amperands for
		      \emph{leading blank columns}.
		      We note that \emph{default} has not been specified, and it will be set to \texttt{1} by
		      default.
	\end{itemize}
	We can customise the space before the ampersand in the \emph{leading blank column} of
	\cref{lst:aligned1-mod1} by using either of \cref{lst:sba5,lst:sba6}, which are
	equivalent.

	\begin{cmhtcbraster}
		\cmhlistingsfromfile{demonstrations/sba5.yaml}[yaml-TCB]{\texttt{sba5.yaml}}{lst:sba5}
		\cmhlistingsfromfile{demonstrations/sba6.yaml}[yaml-TCB]{\texttt{sba6.yaml}}{lst:sba6}
	\end{cmhtcbraster}

	Upon running
	\begin{commandshell}
latexindent.pl aligned1.tex -l sba5.yaml
latexindent.pl aligned1.tex -l sba6.yaml
\end{commandshell}
	then we receive the (same) output given in \cref{lst:aligned1-mod5}. We note that the
	space before the ampersand in the \emph{leading blank column} has been set to \texttt{0}
	by \cref{lst:sba6}.

	We can demonstrated this feature further using the settings in \cref{lst:sba7} which give
	the output in \cref{lst:aligned1-mod7}.

	\begin{cmhtcbraster}[raster columns=3,
			raster left skip=-3.75cm,
			raster right skip=-2cm,]
		\cmhlistingsfromfile{demonstrations/aligned1-mod5.tex}{\texttt{aligned1-mod5.tex}}{lst:aligned1-mod5}
		\cmhlistingsfromfile{demonstrations/aligned1-mod7.tex}{\texttt{aligned1.tex} using \cref{lst:sba7}}{lst:aligned1-mod7}
		\cmhlistingsfromfile{demonstrations/sba7.yaml}[yaml-TCB]{\texttt{sba7.yaml}}{lst:sba7}
	\end{cmhtcbraster}
\subsubsection{lookForAlignDelims: alignFinalDoubleBackSlash}
	We explore%
	\announce{2020-03-21}{alignFinalDoubleBackSlash demonstration} the
	\texttt{alignFinalDoubleBackSlash} feature by using the file in \cref{lst:tabular4}. Upon
	running the following commands
	\index{delimiters!double backslash demonstration}
	\index{switches!-y demonstration}
	\index{switches!-o demonstration}
	\begin{commandshell}
latexindent.pl tabular4.tex -o=+-default
latexindent.pl tabular4.tex -o=+-FDBS -y="lookForAlignDelims:tabular:alignFinalDoubleBackSlash:1"
\end{commandshell}
	then we receive the respective outputs given in \cref{lst:tabular4-default} and
	\cref{lst:tabular4-FDBS}.

	\begin{cmhtcbraster}[raster columns=3,
			raster left skip=-3.75cm,
			raster right skip=-2cm,]
		\cmhlistingsfromfile{demonstrations/tabular4.tex}{\texttt{tabular4.tex}}{lst:tabular4}
		\cmhlistingsfromfile{demonstrations/tabular4-default.tex}{\texttt{tabular4-default.tex}}{lst:tabular4-default}
		\cmhlistingsfromfile{demonstrations/tabular4-FDBS.tex}{\texttt{tabular4-FDBS.tex}}{lst:tabular4-FDBS}
	\end{cmhtcbraster}

	We note that in:
	\begin{itemize}
		\item \cref{lst:tabular4-default}, by default, the \emph{first} set of double back
		      slashes in the first row of the \texttt{tabular} environment have been used for
		      alignment;
		\item \cref{lst:tabular4-FDBS}, the \emph{final} set of double back slashes in the
		      first row have been used, because we specified \texttt{alignFinalDoubleBackSlash} as 1.
	\end{itemize}

	As of Version 3.0, the alignment routine works on mandatory and optional arguments within
	commands, and also within `special' code blocks (see \texttt{specialBeginEnd} on
	\cpageref{yaml:specialBeginEnd}); for example, assuming that you have a command called
	\lstinline!\matrix! and that it is populated within \texttt{lookForAlignDelims}
	(which it is, by default), and that
	you run the command
	\begin{commandshell}
latexindent.pl matrix1.tex 
\end{commandshell}
	then the before-and-after results shown in \cref{lst:matrixbefore,lst:matrixafter} are
	achievable by default.

	\begin{cmhtcbraster}
		\cmhlistingsfromfile{demonstrations/matrix1.tex}{\texttt{matrix1.tex}}{lst:matrixbefore}
		\cmhlistingsfromfile{demonstrations/matrix1-default.tex}{\texttt{matrix1.tex} default output}{lst:matrixafter}
	\end{cmhtcbraster}

	If you have blocks of code that you wish to align at the \&  character that are
	\emph{not} wrapped in, for example, \lstinline!\begin{tabular}! \ldots
	\lstinline!\end{tabular}!, then you can use the mark up illustrated in
	\cref{lst:alignmentmarkup}; the default output is shown in
	\cref{lst:alignmentmarkup-default}. Note
	that the \lstinline!%*! must be next to each other, but that there can be any number of
	spaces (possibly none) between the
	\lstinline!*! and \lstinline!\begin{tabular}!; note also that you may use any
	environment name that you have specified in \texttt{lookForAlignDelims}.

	\begin{cmhtcbraster}[raster left skip=-1.5cm,]
		\cmhlistingsfromfile{demonstrations/align-block.tex}{\texttt{align-block.tex}}{lst:alignmentmarkup}
		\cmhlistingsfromfile{demonstrations/align-block-default.tex}{\texttt{align-block.tex} default output}{lst:alignmentmarkup-default}
	\end{cmhtcbraster}

	With reference to \vref{tab:code-blocks} and the, yet undiscussed, fields of
	\texttt{noAdditionalIndent} and \texttt{indentRules} (see \vref{sec:noadd-indent-rules}),
	these comment-marked blocks are considered \texttt{environments}.

\subsubsection{lookForAlignDelims: the dontMeasure feature}\label{sec:dontMeasure}
	The%
	\announce{2020-03-21}{don't measure feature}
	\texttt{lookForAlignDelims} field can, optionally, receive the \texttt{dontMeasure}
	option which can be specified in a few different ways. We will explore this feature in
	relation to the code given in \cref{lst:tabular-DM}; the default output is shown in
	\cref{lst:tabular-DM-default}.
	\index{delimiters!dontMeasure feature}

	\begin{cmhtcbraster}[raster left skip=-1.5cm,]
		\cmhlistingsfromfile{demonstrations/tabular-DM.tex}{\texttt{tabular-DM.tex}}{lst:tabular-DM}
		\cmhlistingsfromfile{demonstrations/tabular-DM-default.tex}{\texttt{tabular-DM.tex} default output}{lst:tabular-DM-default}
	\end{cmhtcbraster}

	The \texttt{dontMeasure} field can be specified as \texttt{largest}, and in which case,
	the largest element will not be measured; with reference to the YAML file given in
	\cref{lst:dontMeasure1}, we can run the command
	\index{switches!-l demonstration}
	\begin{commandshell} 
latexindent.pl tabular-DM.tex -l=dontMeasure1.yaml
\end{commandshell}
	and receive the output given in \cref{lst:tabular-DM-mod1}.

	\begin{cmhtcbraster}
		\cmhlistingsfromfile{demonstrations/tabular-DM-mod1.tex}{\texttt{tabular-DM.tex} using \cref{lst:dontMeasure1}}{lst:tabular-DM-mod1}
		\cmhlistingsfromfile{demonstrations/dontMeasure1.yaml}[yaml-TCB]{\texttt{dontMeasure1.yaml}}{lst:dontMeasure1}
	\end{cmhtcbraster}

	We note that the \emph{largest} column entries have not contributed to the measuring
	routine.

	The \texttt{dontMeasure} field can also be specified in the form demonstrated in
	\cref{lst:dontMeasure2}. On running the following commands,
	\index{switches!-l demonstration}
	\begin{commandshell} 
latexindent.pl tabular-DM.tex -l=dontMeasure2.yaml
\end{commandshell}
	we receive the output in \cref{lst:tabular-DM-mod2}.
	\index{regular expressions!dontMeasure feature, cell}

	\begin{cmhtcbraster}
		\cmhlistingsfromfile{demonstrations/tabular-DM-mod2.tex}{\texttt{tabular-DM.tex} using \cref{lst:dontMeasure2} or \cref{lst:dontMeasure3}}{lst:tabular-DM-mod2}
		\cmhlistingsfromfile{demonstrations/dontMeasure2.yaml}[yaml-TCB]{\texttt{dontMeasure2.yaml}}{lst:dontMeasure2}
	\end{cmhtcbraster}

	We note that in \cref{lst:dontMeasure2} we have specified entries not to be measured, one
	entry per line.

	The \texttt{dontMeasure} field can also be specified in the forms demonstrated in
	\cref{lst:dontMeasure3} and \cref{lst:dontMeasure4}. Upon running the commands
	\index{switches!-l demonstration}
	\begin{commandshell} 
latexindent.pl tabular-DM.tex -l=dontMeasure3.yaml
latexindent.pl tabular-DM.tex -l=dontMeasure4.yaml
\end{commandshell}
	we receive the output given in \cref{lst:tabular-DM-mod3}
	\index{regular expressions!lowercase alph a-z}
	\begin{cmhtcbraster}[raster columns=3,
			raster left skip=-3.5cm,
			raster right skip=-2cm,
			raster column skip=.03\linewidth]
		\cmhlistingsfromfile{demonstrations/tabular-DM-mod3.tex}{\texttt{tabular-DM.tex} using \cref{lst:dontMeasure3} or \cref{lst:dontMeasure3}}{lst:tabular-DM-mod3}
		\cmhlistingsfromfile{demonstrations/dontMeasure3.yaml}[yaml-TCB]{\texttt{dontMeasure3.yaml}}{lst:dontMeasure3}
		\cmhlistingsfromfile{demonstrations/dontMeasure4.yaml}[yaml-TCB]{\texttt{dontMeasure4.yaml}}{lst:dontMeasure4}
	\end{cmhtcbraster}
	We note that in:
	\begin{itemize}
		\item \cref{lst:dontMeasure3} we have specified entries not to be measured, each one has a
		      \emph{string} in the \texttt{this}
		      field, together with an optional specification of \texttt{applyTo} as \texttt{cell};
		\item \cref{lst:dontMeasure4} we have specified entries not to be measured as a
		      \emph{regular expression} using
		      the \texttt{regex} field, together with an optional specification of \texttt{applyTo} as
		      \texttt{cell} field, together with an optional specification of \texttt{applyTo} as
		      \texttt{cell}.
	\end{itemize}
	In both cases, the default value of \texttt{applyTo} is \texttt{cell}, and does not need
	to be specified.

	We may also specify the \texttt{applyTo} field as \texttt{row}, a demonstration of which
	is given in \cref{lst:dontMeasure5}; upon running
	\index{switches!-l demonstration}
	\begin{commandshell} 
latexindent.pl tabular-DM.tex -l=dontMeasure5.yaml
\end{commandshell}
	we receive the output in \cref{lst:tabular-DM-mod5}.
	\begin{cmhtcbraster}
		\cmhlistingsfromfile{demonstrations/tabular-DM-mod5.tex}{\texttt{tabular-DM.tex} using \cref{lst:dontMeasure5}}{lst:tabular-DM-mod5}
		\cmhlistingsfromfile{demonstrations/dontMeasure5.yaml}[yaml-TCB]{\texttt{dontMeasure5.yaml}}{lst:dontMeasure5}
	\end{cmhtcbraster}

	Finally, the \texttt{applyTo} field can be specified as \texttt{row}, together with a
	\texttt{regex} expression. For example, for the settings given in
	\cref{lst:dontMeasure6}, upon running
	\index{switches!-l demonstration}
	\begin{commandshell} 
latexindent.pl tabular-DM.tex -l=dontMeasure6.yaml
\end{commandshell}
	we receive the output in \cref{lst:tabular-DM-mod6}.
	\index{regular expressions!dontMeasure feature, row}
	\index{regular expressions!lowercase alph a-z}

	\begin{cmhtcbraster}
		\cmhlistingsfromfile{demonstrations/tabular-DM-mod6.tex}{\texttt{tabular-DM.tex} using \cref{lst:dontMeasure6}}{lst:tabular-DM-mod6}
		\cmhlistingsfromfile{demonstrations/dontMeasure6.yaml}[yaml-TCB]{\texttt{dontMeasure6.yaml}}{lst:dontMeasure6}
	\end{cmhtcbraster}

\subsubsection{lookForAlignDelims: the delimiterRegEx and delimiterJustification feature}\label{sec:delimiter-reg-ex}

	The delimiter alignment%
	\announce{2020-03-21}{delimiterRegEx feature} will, by default, align code blocks at the
	ampersand character. The behaviour is controlled by the \texttt{delimiterRegEx} field
	within \texttt{lookForAlignDelims}; the default value is
	\lstinline3'(?<!\\)(&)'3, which can be read as: \emph{an ampersand, as long as it is not
		immediately preceeded by a backslash}.
	\index{warning!capturing parenthesis for lookForAlignDelims}
	\index{capturing parenthesis (regex)}
	\index{regular expressions!capturing parenthesis}
	\index{delimiters!delimiterRegEx}
	\index{delimiters!delimiter justification (left or right)}

	\begin{warning}
		Important: note the `capturing' parenthesis in the \lstinline!(&)! which are necessary; if you
		intend to customise this field, then be sure to include them appropriately.
	\end{warning}

	We demonstrate how to customise this with respect to the code given in
	\cref{lst:tabbing}; the default output from \lstinline!latexindent.pl! is given in
	\cref{lst:tabbing-default}.

	\begin{cmhtcbraster}
		\cmhlistingsfromfile{demonstrations/tabbing.tex}{\texttt{tabbing.tex}}{lst:tabbing}
		\cmhlistingsfromfile{demonstrations/tabbing-default.tex}{\texttt{tabbing.tex} default output}{lst:tabbing-default}
	\end{cmhtcbraster}

	Let's say that we wish to align the code at either the \lstinline!\=! or
	\lstinline!\>!. We employ the settings given in \cref{lst:delimiterRegEx1} and
	run the command
	\index{switches!-l demonstration}
	\begin{commandshell}
latexindent.pl tabbing.tex -l=delimiterRegEx1.yaml
\end{commandshell}
	to receive the output given in \cref{lst:tabbing-mod1}.
	\index{regular expressions!delimiter regex at \textbackslash= or \textbackslash>}

	\begin{cmhtcbraster}
		\cmhlistingsfromfile{demonstrations/tabbing-mod1.tex}{\texttt{tabbing.tex} using \cref{lst:delimiterRegEx1}}{lst:tabbing-mod1}
		\cmhlistingsfromfile{demonstrations/delimiterRegEx1.yaml}[yaml-TCB]{\texttt{delimiterRegEx1.yaml}}{lst:delimiterRegEx1}
	\end{cmhtcbraster}
	We note that:
	\begin{itemize}
		\item in \cref{lst:tabbing-mod1} the code has been aligned, as intended, at both the
		      \lstinline!\=! and \lstinline!\>!;
		\item in \cref{lst:delimiterRegEx1} we have heeded the warning and captured the expression
		      using grouping parenthesis, specified a backslash using \lstinline!\\! and said that it
		      must be followed by either \lstinline!=! or \lstinline!>!.
	\end{itemize}
	We can explore \texttt{delimiterRegEx} a little further using the settings in
	\cref{lst:delimiterRegEx2} and run the command
	\index{switches!-l demonstration}
	\begin{commandshell}
latexindent.pl tabbing.tex -l=delimiterRegEx2.yaml
\end{commandshell}
	to receive the output given in \cref{lst:tabbing-mod2}.
	\index{regular expressions!delimiter regex at only \textbackslash>}

	\begin{cmhtcbraster}
		\cmhlistingsfromfile{demonstrations/tabbing-mod2.tex}{\texttt{tabbing.tex} using \cref{lst:delimiterRegEx2}}{lst:tabbing-mod2}
		\cmhlistingsfromfile{demonstrations/delimiterRegEx2.yaml}[yaml-TCB]{\texttt{delimiterRegEx2.yaml}}{lst:delimiterRegEx2}
	\end{cmhtcbraster}
	We note that only the \lstinline!\>! have been aligned.

	Of course, the other lookForAlignDelims options can be used alongside the
	\texttt{delimiterRegEx}; regardless of the type of delimiter being used (ampersand or
	anything else), the fields from \vref{lst:aligndelims:advanced} remain the same; for
	example, using the settings in \cref{lst:delimiterRegEx3}, and running
	\index{switches!-l demonstration}
	\begin{commandshell}
latexindent.pl tabbing.tex -l=delimiterRegEx3.yaml
\end{commandshell}
	to receive the output given in \cref{lst:tabbing-mod3}.

	\begin{cmhtcbraster}
		\cmhlistingsfromfile{demonstrations/tabbing-mod3.tex}{\texttt{tabbing.tex} using \cref{lst:delimiterRegEx3}}{lst:tabbing-mod3}
		\cmhlistingsfromfile{demonstrations/delimiterRegEx3.yaml}[yaml-TCB]{\texttt{delimiterRegEx3.yaml}}{lst:delimiterRegEx3}
	\end{cmhtcbraster}

	It is possible that delimiters specified within \texttt{delimiterRegEx} can be of
	different lengths. Consider the file in \cref{lst:tabbing1}, and associated YAML in
	\cref{lst:delimiterRegEx4}. Note that the \cref{lst:delimiterRegEx4} specifies the option
	for the delimiter to be either
	\lstinline!#! or
	\lstinline!\>!, \emph{which are different lengths}. Upon running the command
	\index{switches!-l demonstration}
	\index{switches!-o demonstration}
	\begin{commandshell}
latexindent.pl tabbing1.tex -l=delimiterRegEx4.yaml -o=+-mod4
\end{commandshell}
	we receive the output in \cref{lst:tabbing1-mod4}.
	\index{regular expressions!delimiter regex at \#}

	\begin{cmhtcbraster}[raster columns=3,
			raster left skip=-3.5cm,
			raster right skip=-2cm,
			raster column skip=.03\linewidth]
		\cmhlistingsfromfile{demonstrations/tabbing1.tex}{\texttt{tabbing1.tex}}{lst:tabbing1}
		\cmhlistingsfromfile{demonstrations/tabbing1-mod4.tex}{\texttt{tabbing1-mod4.tex}}{lst:tabbing1-mod4}
		\cmhlistingsfromfile{demonstrations/delimiterRegEx4.yaml}[yaml-TCB]{\texttt{delimiterRegEx4.yaml}}{lst:delimiterRegEx4}
	\end{cmhtcbraster}

	You can set the \emph{delimiter} justification as either \texttt{left} (default) or
	\texttt{right}, which will only have effect when delimiters in the same column have
	different lengths. Using the settings in \cref{lst:delimiterRegEx5} and running the
	command
	\index{switches!-l demonstration}
	\index{switches!-o demonstration}
	\begin{commandshell}
latexindent.pl tabbing1.tex -l=delimiterRegEx5.yaml -o=+-mod5
\end{commandshell}
	gives the output in \cref{lst:tabbing1-mod5}.
	\index{regular expressions!delimiter regex at \# or \textbackslash>}

	\begin{cmhtcbraster}
		\cmhlistingsfromfile{demonstrations/tabbing1-mod5.tex}{\texttt{tabbing1-mod5.tex}}{lst:tabbing1-mod5}
		\cmhlistingsfromfile{demonstrations/delimiterRegEx5.yaml}[yaml-TCB]{\texttt{delimiterRegEx5.yaml}}{lst:delimiterRegEx5}
	\end{cmhtcbraster}

	Note that in \cref{lst:tabbing1-mod5} the second set of delimiters have been \emph{right
		aligned} -- it is quite subtle!

\subsection{Indent after items, specials and headings}
\yamltitle{indentAfterItems}*{fields}
	The environment names specified in \texttt{indentAfterItems} tell \texttt{latexindent.pl}
	to look for \lstinline!\item! commands; if these switches are set to \texttt{1} then
	indentation will be performed so as indent the code after each \texttt{item}. A
	demonstration is given in \cref{lst:itemsbefore,lst:itemsafter}

	\begin{cmhtcbraster}[raster columns=3,
			raster left skip=-3.5cm,
			raster right skip=-2cm,
			raster column skip=.03\linewidth]
		\cmhlistingsfromfile[style=indentAfterItems]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{indentAfterItems}}{lst:indentafteritems}
		\cmhlistingsfromfile{demonstrations/items1.tex}{\texttt{items1.tex}}{lst:itemsbefore}
		\cmhlistingsfromfile{demonstrations/items1-default.tex}{\texttt{items1.tex} default output}{lst:itemsafter}
	\end{cmhtcbraster}

\yamltitle{itemNames}*{fields}
	If you have your own \texttt{item} commands (perhaps you prefer to use \texttt{myitem},
	for example) then you can put populate them in \texttt{itemNames}. For example, users of
	the \texttt{exam} document class might like to add \texttt{parts} to
	\texttt{indentAfterItems} and \texttt{part} to \texttt{itemNames} to their user settings
	(see \vref{sec:indentconfig} for details of how to configure user settings, and
	\vref{lst:mysettings} \\ in particular \label{page:examsettings}.)

	\cmhlistingsfromfile[style=itemNames]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{itemNames}}{lst:itemNames}

\yamltitle{specialBeginEnd}*{fields}\label{yaml:specialBeginEnd}
	The fields specified
	\index{specialBeginEnd!introduction}%
	\announce{2017-08-21}*{specialBeginEnd} in \texttt{specialBeginEnd} are, in their default
	state, focused on math mode begin and end statements, but there is no requirement for
	this to be the case; \cref{lst:specialBeginEnd} shows the default settings of
	\texttt{specialBeginEnd}.
	\index{specialBeginEnd!default settings}

	\cmhlistingsfromfile[style=specialBeginEnd]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{specialBeginEnd}}{lst:specialBeginEnd}

	The field \texttt{displayMath} represents \lstinline!\[...\]!, \texttt{inlineMath}
	represents
	\lstinline!$...$! and \texttt{displayMathTex} represents \lstinline!$$...$$!.
	You can, of course, rename these in your own YAML files (see \vref{sec:localsettings});
	indeed, you might like to set up your own special begin and end statements.

	A demonstration of the before-and-after results are shown in
	\cref{lst:specialbefore,lst:specialafter}.

	\begin{cmhtcbraster}
		\cmhlistingsfromfile{demonstrations/special1.tex}{\texttt{special1.tex} before}{lst:specialbefore}
		\cmhlistingsfromfile{demonstrations/special1-default.tex}{\texttt{special1.tex} default output}{lst:specialafter}
	\end{cmhtcbraster}

	For each field, \texttt{lookForThis} is set to \texttt{1} by default, which means that
	\texttt{latexindent.pl} will look for this pattern; you can tell \texttt{latexindent.pl}
	not to look for the pattern, by setting \texttt{lookForThis} to \texttt{0}.

	There are%
	\announce{2017-08-21}{specialBeforeCommand}
	examples in which it is advantageous to search for \texttt{specialBeginEnd} fields
	\emph{before} searching for commands, and the \texttt{specialBeforeCommand} switch
	controls this behaviour. For example, consider the file shown in
	\cref{lst:specialLRbefore}.

	\cmhlistingsfromfile{demonstrations/specialLR.tex}{\texttt{specialLR.tex}}{lst:specialLRbefore}

	Now consider the YAML files shown in
	\cref{lst:specialsLeftRight-yaml,lst:specialBeforeCommand-yaml}
	\index{specialBeginEnd!searching for special before commands}

	\begin{cmhtcbraster}
		\cmhlistingsfromfile[]*{demonstrations/specialsLeftRight.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{specialsLeftRight.yaml}}{lst:specialsLeftRight-yaml}
		\cmhlistingsfromfile[]*{demonstrations/specialBeforeCommand.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{specialBeforeCommand.yaml}}{lst:specialBeforeCommand-yaml}
	\end{cmhtcbraster}

	Upon running the following commands
	\index{switches!-l demonstration}
	\begin{widepage}
		\begin{commandshell}
latexindent.pl specialLR.tex -l=specialsLeftRight.yaml      
latexindent.pl specialLR.tex -l=specialsLeftRight.yaml,specialBeforeCommand.yaml      
\end{commandshell}
	\end{widepage}
	we receive the respective outputs in
	\cref{lst:specialLR-comm-first-tex,lst:specialLR-special-first-tex}.

	\begin{minipage}{.49\linewidth}
		\cmhlistingsfromfile{demonstrations/specialLR-comm-first.tex}{\texttt{specialLR.tex} using \cref{lst:specialsLeftRight-yaml}}{lst:specialLR-comm-first-tex}
	\end{minipage}
	\hfill
	\begin{minipage}{.49\linewidth}
		\cmhlistingsfromfile{demonstrations/specialLR-special-first.tex}{\texttt{specialLR.tex} using \cref{lst:specialsLeftRight-yaml,lst:specialBeforeCommand-yaml}}{lst:specialLR-special-first-tex}
	\end{minipage}

	Notice that in:
	\begin{itemize}
		\item \cref{lst:specialLR-comm-first-tex} the \lstinline!\left! has been treated as a
		      \emph{command}, with one optional argument;
		\item \cref{lst:specialLR-special-first-tex} the \texttt{specialBeginEnd} pattern in
		      \cref{lst:specialsLeftRight-yaml}
		      has been obeyed because \cref{lst:specialBeforeCommand-yaml} specifies that the
		      \texttt{specialBeginEnd} should be sought \emph{before} commands.
	\end{itemize}

	You can,optionally, specify%
	\announce{2018-04-27}{update to specialBeginEnd} the \texttt{middle} field for anything that you specify in
	\texttt{specialBeginEnd}. For example, let's consider the \texttt{.tex} file in
	\cref{lst:special2}.
	\index{specialBeginEnd!middle}
	\index{specialBeginEnd!IfElsFi example}

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

	Upon saving the YAML settings in \cref{lst:middle-yaml,lst:middle1-yaml} and running the
	commands
	\index{switches!-l demonstration}
	\begin{commandshell}
latexindent.pl special2.tex -l=middle
latexindent.pl special2.tex -l=middle1
\end{commandshell}
	then we obtain the output given in \cref{lst:special2-mod1,lst:special2-mod2}.

	\begin{cmhtcbraster}
		\cmhlistingsfromfile{demonstrations/middle.yaml}[yaml-TCB]{\texttt{middle.yaml}}{lst:middle-yaml}
		\cmhlistingsfromfile{demonstrations/special2-mod1.tex}{\texttt{special2.tex} using \cref{lst:middle-yaml}}{lst:special2-mod1}
	\end{cmhtcbraster}

	\begin{cmhtcbraster}
		\cmhlistingsfromfile{demonstrations/middle1.yaml}[yaml-TCB]{\texttt{middle1.yaml}}{lst:middle1-yaml}
		\cmhlistingsfromfile{demonstrations/special2-mod2.tex}{\texttt{special2.tex} using \cref{lst:middle1-yaml}}{lst:special2-mod2}
	\end{cmhtcbraster}

	We note that:
	\begin{itemize}
		\item in \cref{lst:special2-mod1} the bodies of each of the \texttt{Elsif} statements have been
		      indented appropriately;
		\item the \texttt{Else} statement has \emph{not} been indented appropriately in
		      \cref{lst:special2-mod1} -- read on!
		\item we have specified multiple settings for the \texttt{middle} field using the syntax
		      demonstrated in \cref{lst:middle1-yaml} so that the body of the \texttt{Else} statement
		      has been indented appropriately in \cref{lst:special2-mod2}.
	\end{itemize}

	You may%
	\announce{2018-08-13}{specialBeginEnd verbatim}
	specify fields in \texttt{specialBeginEnd} to be treated as verbatim code blocks by
	changing \texttt{lookForThis} to be \texttt{verbatim}.
	\index{verbatim!specialBeginEnd}

	For example, beginning with the code in \cref{lst:special3-mod1} and the YAML in
	\cref{lst:special-verb1-yaml}, and running
	\index{switches!-l demonstration}
	\begin{commandshell}
latexindent.pl special3.tex -l=special-verb1
\end{commandshell}
	then the output in \cref{lst:special3-mod1} is unchanged.
	\index{specialBeginEnd!specifying as verbatim}

	\begin{cmhtcbraster}
		\cmhlistingsfromfile{demonstrations/special-verb1.yaml}[yaml-TCB]{\texttt{special-verb1.yaml}}{lst:special-verb1-yaml}
		\cmhlistingsfromfile{demonstrations/special3-mod1.tex}{\texttt{special3.tex} and output using \cref{lst:special-verb1-yaml}}{lst:special3-mod1}
	\end{cmhtcbraster}

	We can combine the \texttt{specialBeginEnd} with the \texttt{lookForAlignDelims} feature.
	We begin with the code in \cref{lst:special-align}.

	\cmhlistingsfromfile{demonstrations/special-align.tex}{\texttt{special-align.tex}}{lst:special-align}

	Let's assume that our goal is to align the code at the \texttt{edge} and \texttt{node}
	text; we employ the code given in \cref{lst:edge-node1} and run the command
	\index{switches!-l demonstration}
	\index{switches!-o demonstration}
	\begin{commandshell}
latexindent.pl special-align.tex -l edge-node1.yaml -o=+-mod1
\end{commandshell}
	to receive the output in \cref{lst:special-align-mod1}.
	\index{specialBeginEnd!combined with lookForAlignDelims}
	\index{specialBeginEnd!delimiterRegEx}
	\index{specialBeginEnd!alignment at delimiter}
	\index{specialBeginEnd!tikz example}
	\index{regular expressions!delimiter alignment for edge or node}
	\index{delimiters!within specialBeginEnd blocks}
	\index{regular expressions!numeric 0-9}

	\begin{cmhtcbraster}[ raster left skip=-3.5cm,]
		\cmhlistingsfromfile{demonstrations/edge-node1.yaml}[yaml-TCB]{\texttt{edge-node1.yaml}}{lst:edge-node1}
		\cmhlistingsfromfile{demonstrations/special-align-mod1.tex}{\texttt{special-align.tex} using \cref{lst:edge-node1}}{lst:special-align-mod1}
	\end{cmhtcbraster}

	The output in \cref{lst:special-align-mod1} is not quite ideal. We can tweak the settings
	within \cref{lst:edge-node1} in order to improve the output; in particular, we employ the
	code in \cref{lst:edge-node2} and run the command
	\index{switches!-l demonstration}
	\index{switches!-o demonstration}
	\index{regular expressions!uppercase alph A-Z}
	\begin{commandshell}
latexindent.pl special-align.tex -l edge-node2.yaml -o=+-mod2
\end{commandshell}
	to receive the output in \cref{lst:special-align-mod2}.
	\index{specialBeginEnd!delimiterRegEx tweaked}
	\index{regular expressions!at least one +}
	\index{regular expressions!horizontal space \textbackslash{h}}

	\begin{cmhtcbraster}[ raster left skip=-3.5cm,]
		\cmhlistingsfromfile{demonstrations/edge-node2.yaml}[yaml-TCB]{\texttt{edge-node2.yaml}}{lst:edge-node2}
		\cmhlistingsfromfile{demonstrations/special-align-mod2.tex}{\texttt{special-align.tex} using \cref{lst:edge-node2}}{lst:special-align-mod2}
	\end{cmhtcbraster}

	The \texttt{lookForThis} field can be considered
	optional;%
	\announce{2021-06-19}*{lookForThis optional for specialBeginEnd} by default, it is assumed to be 1, which is demonstrated in
	\cref{lst:edge-node2}.

\yamltitle{indentAfterHeadings}*{fields}
	This field enables the user to specify indentation rules that take effect after heading
	commands such as \lstinline!\part!, \lstinline!\chapter!,
	\lstinline!\section!, \lstinline!\subsection*!, or indeed any user-specified command
	written in this field.\footnote{There is a slight difference in interface for this field
		when comparing Version 2.2 to Version 3.0; see \vref{app:differences} for details.}

	\cmhlistingsfromfile[style=indentAfterHeadings]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{indentAfterHeadings}}{lst:indentAfterHeadings}

	The default settings do \emph{not} place indentation after a heading, but you can easily
	switch them on by changing \texttt{indentAfterThisHeading} from 0 to 1. The
	\texttt{level} field tells \texttt{latexindent.pl} the hierarchy of the heading structure
	in your document. You might, for example, like to have both \texttt{section} and
	\texttt{subsection} set with \texttt{level: 3} because you do not want the indentation to
	go too deep.

	You can add any of your own custom heading commands to this field, specifying the
	\texttt{level} as appropriate. You can also specify your own indentation in
	\texttt{indentRules} (see \vref{sec:noadd-indent-rules}); you will find the default
	\texttt{indentRules} contains
	\lstinline!chapter: " "! which tells \texttt{latexindent.pl} simply to use a space
	character after \texttt{\chapter} headings (once \texttt{indent} is set to \texttt{1} for
	\texttt{chapter}).

	For example, assuming that you have the code in \cref{lst:headings1yaml} saved into
	\texttt{headings1.yaml}, and that you have the text from \cref{lst:headings1} saved into
	\texttt{headings1.tex}.

	\begin{cmhtcbraster}
		\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/headings1.yaml}[yaml-TCB]{\texttt{headings1.yaml}}{lst:headings1yaml}
		\cmhlistingsfromfile{demonstrations/headings1.tex}{\texttt{headings1.tex}}{lst:headings1}
	\end{cmhtcbraster}

	If you run the command
	\index{switches!-l demonstration}
	\begin{commandshell}
latexindent.pl headings1.tex -l=headings1.yaml
\end{commandshell}
	then you should receive the output given in \cref{lst:headings1-mod1}.

	\begin{minipage}{.45\textwidth}
		\cmhlistingsfromfile[showtabs=true]{demonstrations/headings1-mod1.tex}{\texttt{headings1.tex} using \cref{lst:headings1yaml}}{lst:headings1-mod1}
	\end{minipage}%
	\hfill
	\begin{minipage}{.45\textwidth}
		\cmhlistingsfromfile[showtabs=true]{demonstrations/headings1-mod2.tex}{\texttt{headings1.tex} second modification}{lst:headings1-mod2}
	\end{minipage}

	Now say that you modify the \texttt{YAML} from \cref{lst:headings1yaml} so that the
	\texttt{paragraph} \texttt{level} is \texttt{1}; after running
	\index{switches!-l demonstration}
	\begin{commandshell}
latexindent.pl headings1.tex -l=headings1.yaml
\end{commandshell}
	you should receive the code given in \cref{lst:headings1-mod2}; notice that the
	\texttt{paragraph} and \texttt{subsection} are at the same indentation level.

	\index{indentation!maximum indetation}

\yamltitle{maximumIndentation}*{horizontal space}
	You can control the maximum indentation given to your file
	by%
	\announce{2017-08-21}{maximumIndentation} specifying
	the \texttt{maximumIndentation} field as horizontal space (but \emph{not} including
	tabs). This feature uses the \texttt{Text::Tabs} module \cite{texttabs}, and is
	\emph{off} by default.

	For example, consider the example shown in \cref{lst:mult-nested} together with the
	default output shown in \cref{lst:mult-nested-default}.

	\begin{cmhtcbraster}[raster column skip=.1\linewidth]
		\cmhlistingsfromfile{demonstrations/mult-nested.tex}{\texttt{mult-nested.tex}}{lst:mult-nested}
		\cmhlistingsfromfile[showtabs=true]{demonstrations/mult-nested-default.tex}{\texttt{mult-nested.tex} default output}{lst:mult-nested-default}
	\end{cmhtcbraster}

	Now say that, for example, you have the \texttt{max-indentation1.yaml} from
	\cref{lst:max-indentation1yaml} and that you run the following command:
	\index{switches!-l demonstration}
	\begin{commandshell}
latexindent.pl mult-nested.tex -l=max-indentation1
\end{commandshell}
	You should receive the output shown in \cref{lst:mult-nested-max-ind1}.

	\begin{cmhtcbraster}
		\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/max-indentation1.yaml}[yaml-TCB]{\texttt{max-indentation1.yaml}}{lst:max-indentation1yaml}
		\cmhlistingsfromfile[showspaces=true]{demonstrations/mult-nested-max-ind1.tex}{\texttt{mult-nested.tex} using \cref{lst:max-indentation1yaml}}{lst:mult-nested-max-ind1}
	\end{cmhtcbraster}

	Comparing the output in \cref{lst:mult-nested-default,lst:mult-nested-max-ind1} we notice
	that the (default) tabs of indentation have been replaced by a single space.

	In general, when using the \texttt{maximumIndentation} feature, any leading tabs will be
	replaced by equivalent spaces except, of course, those found in
	\texttt{verbatimEnvironments} (see \vref{lst:verbatimEnvironments}) or
	\texttt{noIndentBlock} (see \vref{lst:noIndentBlock}).

\subsection{The code blocks known latexindent.pl}\label{subsubsec:code-blocks}

	As of Version 3.0, \texttt{latexindent.pl} processes documents using code blocks; each of
	these are shown in \cref{tab:code-blocks}.
	\index{regular expressions!uppercase alph A-Z}
	\index{regular expressions!lowercase alph a-z}
	\index{regular expressions!numeric 0-9}
	\index{regular expressions!horizontal space \textbackslash{h}}

	\begin{table}[!htp]
		\begin{widepage}
			\centering
			\caption{Code blocks known to \texttt{latexindent.pl}}\label{tab:code-blocks}
			\begin{tabular}{m{.3\linewidth}@{\hspace{.25cm}}m{.4\linewidth}@{\hspace{.25cm}}m{.2\linewidth}}
				\toprule
				Code block                    & characters allowed in name                                                                  & example                                                                                                                                                               \\
				\midrule
				environments                  & \lstinline!a-zA-Z@\*0-9_\\!                                                                 &
				\begin{lstlisting}[,nolol=true,]
\begin{myenv}
body of myenv
\end{myenv}
  \end{lstlisting}
				\\\cmidrule{2-3}
				optionalArguments             & \emph{inherits} name from parent (e.g environment name)                                     &
				\begin{lstlisting}[,nolol=true,]
[
opt arg text
]
  \end{lstlisting}
				\\\cmidrule{2-3}
				mandatoryArguments            & \emph{inherits} name from parent (e.g environment name)                                     &
				\begin{lstlisting}[,nolol=true,]
{
mand arg text
}
  \end{lstlisting}
				\\\cmidrule{2-3}
				commands                      & \lstinline!+a-zA-Z@\*0-9_\:!                                                                & \lstinline!\mycommand!$\langle$\itshape{arguments}$\rangle$                                                                                                           \\\cmidrule{2-3}
				keyEqualsValuesBracesBrackets & \lstinline!a-zA-Z@\*0-9_\/.\h\{\}:\#-!                                                      & \lstinline!my key/.style=!$\langle$\itshape{arguments}$\rangle$                                                                                                       \\\cmidrule{2-3}
				namedGroupingBracesBrackets   & \lstinline!0-9\.a-zA-Z@\*><!                                                                & \lstinline!in!$\langle$\itshape{arguments}$\rangle$                                                                                                                   \\\cmidrule{2-3}
				UnNamedGroupingBracesBrackets & \centering\emph{No name!}                                                                   & \lstinline!{! or \lstinline![! or \lstinline!,! or \lstinline!&! or \lstinline!)! or \lstinline!(! or \lstinline!$! followed by $\langle$\itshape{arguments}$\rangle$ \\\cmidrule{2-3}
				ifElseFi                      & \lstinline!@a-zA-Z! but must begin with either \newline \lstinline!\if! of \lstinline!\@if! &
				\begin{lstlisting}[,nolol=true,]
\ifnum...
...
\else
...
\fi
  \end{lstlisting}                                                                                                                                                                                                                                                                     \\\cmidrule{2-3}
				items                         & User specified, see \vref{lst:indentafteritems,lst:itemNames}                               &
				\begin{lstlisting}[,nolol=true,]
\begin{enumerate}
  \item ...
\end{enumerate}
  \end{lstlisting}                                                                                                                                                                                                                                                                     \\\cmidrule{2-3}
				specialBeginEnd               & User specified, see \vref{lst:specialBeginEnd}                                              &
				\begin{lstlisting}[,nolol=true,]
\[
  ...
\]
  \end{lstlisting}                                                                                                                                                                                                                                                                     \\\cmidrule{2-3}
				afterHeading                  & User specified, see \vref{lst:indentAfterHeadings}                                          &
				\begin{lstlisting}[,morekeywords={chapter},nolol=true,]
\chapter{title}
  ...
\section{title}
  \end{lstlisting}                                                                                                                                                                                                                                              \\\cmidrule{2-3}
				filecontents                  & User specified, see \vref{lst:fileContentsEnvironments}                                     &
				\begin{lstlisting}[,nolol=true,]
\begin{filecontents}
...
\end{filecontents}
  \end{lstlisting}                                                                                                                                                                                                                                                                     \\
				\bottomrule
			\end{tabular}
		\end{widepage}
	\end{table}

	We will refer to these code blocks in what follows.%
	\announce{2019-07-13}{fine tuning of code blocks} Note that the fine tuning of the
	definition of the code blocks detailed in \cref{tab:code-blocks} is discussed in
	\vref{sec:finetuning}.