summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/support/latexindent/sec-default-user-local.tex
blob: 2e5afbcdae2d760df2d1d2489de46cc15a04ef74 (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
% 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.

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

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

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

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

	\begin{cmhlistings}[style=demo,escapeinside={(*@}{@*)}]{\texttt{noIndentBlock} demonstration}{lst:noIndentBlockdemo}
%(*@@*) \begin{noindent}
        this code
                won't
     be touched
                    by
             latexindent.pl!
%(*@@*)\end{noindent}
	\end{cmhlistings}

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

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

\yamltitle{defaultIndent}*{horizontal space}
	This is the default indentation (\lstinline!\t! means a tab, and is the default
	value) used in the absence of other details for the command or environment we are working
	with; see \texttt{indentRules} in \vref{sec:noadd-indent-rules} for more details.

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

\yamltitle{lookForAlignDelims}*{fields}
	This contains a list of environments and/or commands 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}

	The environments specified in this field will be operated on in a special way by
	\texttt{latexindent.pl}. In particular, it will try and align each column by its
	alignment tabs. 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}

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

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

\subsection{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!

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

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