summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/support/latexindent/documentation/latexindent.tex
blob: c39b89e627e5cc177667fdb8aa87116b556215a1 (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
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
% arara: pdflatex
% arara: bibtex
% arara: pdflatex
% arara: pdflatex
% !arara: pdflatex
% !arara: indent: {overwrite: yes, trace: yes, localSettings: yes, silent: yes}
\documentclass[11pt]{article}
%   This program is free software: you can redistribute it and/or modify
%   it under the terms of the GNU General Public License as published by
%   the Free Software Foundation, either version 3 of the License, or
%   (at your option) any later version.
%
%   This program is distributed in the hope that it will be useful,
%   but WITHOUT ANY WARRANTY; without even the implied warranty of
%   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
%   GNU General Public License for more details.
%
%   See <http://www.gnu.org/licenses/>.
\usepackage[left=4.5cm,right=2.5cm,showframe=false,
top=2cm,bottom=1.5cm]{geometry}                      % page setup
\usepackage{parskip}                                 % paragraph skips
\usepackage{booktabs}                                % beautiful tables
\usepackage{listings}                                % nice verbatim environments
\usepackage{titlesec}                                % customize headings
\usepackage{changepage}                              % adjust width of page
\usepackage{fancyhdr}                                % headers & footers
\usepackage[sc,format=hang,font=small]{caption}      % captions
\usepackage[backend=bibtex]{biblatex}                % bibliography
\usepackage{tcolorbox}                                % framed environments
\usepackage[charter]{mathdesign}                     % changes font
\usepackage[expansion=false,kerning=true]{microtype} % better kerning
\usepackage{enumitem}                                % custom lists
% setup gitinfo2, as in the manual, details just above begin{document}
\usepackage[mark,grumpy]{gitinfo2}
\usepackage{examplep}
% tcolorbox libraries
\tcbuselibrary{breakable,skins,listings}
% tikz libraries
\usetikzlibrary{positioning}
\usetikzlibrary{decorations.pathmorphing}
\usetikzlibrary{decorations,shapes}
\usepackage{varioref}                                % clever referencing
\usepackage{hyperref}
\hypersetup{
   pdfauthor={Chris Hughes},
   pdftitle={latexindent.pl package},
   pdfkeywords={perl;beautify;indentation},
	bookmarksnumbered,
	bookmarksopen,
	linktocpage,
    colorlinks=true,
    linkcolor=blue,
    citecolor=black,
}
\usepackage{cleveref}

\addbibresource{latex-indent}
\addbibresource{contributors}


% http://tex.stackexchange.com/questions/122135/how-to-add-a-png-icon-on-the-right-side-of-a-tcolorbox-title
\newtcolorbox{warning}{parbox=false,breakable,enhanced,arc=0mm,colback=red!5,colframe=red,leftrule=12mm,%
	overlay={\node[anchor=north west,outer sep=2pt] at (frame.north west) {\includegraphics[width=8mm]{warning}}; }}

\makeatletter
\tcbset{
	addtolol/.style={list entry={\kvtcb@title},add to list={lol}{lstlisting}},
}

\newtcblisting[use counter=lstlisting]{cmhlistings}[3][]{%
	width=\linewidth,
	breakable,
	colback=blue!5!white,
	colframe=white!85!black,
	top=0cm,
	bottom=0cm,
	left=6mm,
	listing only,
	listing options={#1},
	center title,
	title={\color{black}{\scshape Listing \thetcbcounter}: ~#2},label={#3},
	addtolol,
}

\lstset{%
	basicstyle=\small\ttfamily,language={[LaTeX]TeX},
	%	numbers=left,
	numberstyle=\ttfamily%\small,
	breaklines=true,
	%   frame=single,framexleftmargin=8mm, xleftmargin=8mm,
	%	prebreak = \raisebox{0ex}[0ex][0ex]{\ensuremath{\hookrightarrow}},
	%	backgroundcolor=\color{green!5},frameround=fttt,
	%	rulecolor=\color{blue!70!black},
	keywordstyle=\color{blue},                    % keywords
	commentstyle=\color{purple},    % comments
	tabsize=3,
	%xleftmargin=1.5em,
}%
\lstdefinestyle{yaml}{%
	numbers=left,
	numberstyle=\color{black},}
\lstdefinestyle{demo}{
	numbers=none,
	linewidth=1.25\textwidth,
	columns=fullflexible,
}

% stars around contributors
\pgfdeclaredecoration{stars}{initial}{
	\state{initial}[width=15pt]
	{
		\pgfmathparse{round(rnd*100)}
		\pgfsetfillcolor{yellow!\pgfmathresult!orange}
		\pgfsetstrokecolor{yellow!\pgfmathresult!red}
		\pgfnode{star}{center}{}{}{\pgfusepath{stroke,fill}}
	}
	\state{final}
	{
		\pgfpathmoveto{\pgfpointdecoratedpathlast}
	}
}

\newtcolorbox{stars}{%
	enhanced jigsaw,
	breakable, % allow page breaks
	left=0cm,
	top=0cm,
	before skip=0.2cm,
	boxsep=0cm,
	frame style={draw=none,fill=none}, % hide the default frame
	colback=white,
	overlay={
		\draw[inner sep=0,minimum size=rnd*15pt+2pt]
		decorate[decoration={stars,segment length=2cm}] {
			decorate[decoration={zigzag,segment length=2cm,amplitude=0.3cm}] {
				([xshift=-.5cm,yshift=0.1cm]frame.south west) --  ([xshift=-.5cm,yshift=0.4cm]frame.north west)
		}};
		\draw[inner sep=0,minimum size=rnd*15pt+2pt]
		decorate[decoration={stars,segment length=2cm}] {
			decorate[decoration={zigzag,segment length=2cm,amplitude=0.3cm}] {
				([xshift=.75cm,yshift=0.1cm]frame.south east) --  ([xshift=.75cm,yshift=0.6cm]frame.north east)
		}};
	},
	% paragraph skips obeyed within tcolorbox
	parbox=false,
}

% copied from /usr/local/texlive/2013/texmf-dist/tex/latex/biblatex/bbx/numeric.bbx
% the only modification is the \stars and \endstars
\defbibenvironment{specialbib}
{\stars\list
	{\printtext[labelnumberwidth]{%
		\printfield{prefixnumber}%
		\printfield{labelnumber}}}
	{\setlength{\labelwidth}{\labelnumberwidth}%
		\setlength{\leftmargin}{\labelwidth}%
		\setlength{\labelsep}{\biblabelsep}%
		\addtolength{\leftmargin}{\labelsep}%
		\setlength{\itemsep}{\bibitemsep}%
		\setlength{\parsep}{\bibparsep}}%
	\renewcommand*{\makelabel}[1]{\hss##1}}
{\endlist\endstars}
{\item}

% see: http://tex.stackexchange.com/questions/2245/verbatim-description-list-item
\newcommand{\verbitem}[1]{\small\PVerb{#1}}
% stolen from arara.sty http://mirrors.med.harvard.edu/ctan/support/arara/doc/arara.sty
%\lstnewenvironment{yaml}[1][]{\lstset{%
%	basicstyle=\ttfamily,
%	numbers=left,
%	xleftmargin=1.5em,
%	breaklines=true,
%	numberstyle=\ttfamily\small,
%	columns=flexible,
%	mathescape=false,
%	#1,
%}}
%{}

\newcommand{\fixthis}[1]
{%
	\marginpar{\huge \color{red} \framebox{FIX}}%
	\typeout{FIXTHIS: p\thepage : #1^^J}%
}
% custom section
\titleformat{\section}
{\normalfont\Large\bfseries}
{\llap{\thesection\hskip.5cm}}
{0pt}
{}
% custom subsection
\titleformat{\subsection}
{\normalfont\bfseries}
{\llap{\thesubsection\hskip.5cm}}
{0pt}
{}
% custom subsubsection
\titleformat{\subsubsection}
{\normalfont\bfseries}
{\llap{\thesubsubsection\hskip.5cm}}
{0pt}
{}


\titlespacing\section{0pt}{12pt plus 4pt minus 2pt}{-5pt plus 2pt minus 2pt}
\titlespacing\subsection{0pt}{12pt plus 4pt minus 2pt}{-6pt plus 2pt minus 2pt}
\titlespacing\subsubsection{0pt}{12pt plus 4pt minus 2pt}{-6pt plus 2pt minus 2pt}


% cleveref settings
\crefname{table}{Table}{Tables}
\Crefname{table}{Table}{Tables}
\crefname{figure}{Figure}{Figures}
\Crefname{figure}{Figure}{Figures}
\crefname{section}{Section}{Sections}
\Crefname{section}{Section}{Sections}
\crefname{listing}{Listing}{Listings}
\Crefname{listing}{Listing}{Listings}

% headers and footers
\fancyhf{} % delete current header and footer
\fancyhead[R]{\bfseries\thepage}
\fancyheadoffset[L]{3cm}
\pagestyle{fancy}

% renew plain style
\fancypagestyle{plain}{%
\fancyhf{} % clear all header and footer fields
\renewcommand{\headrulewidth}{0pt}
\renewcommand{\footrulewidth}{0pt}}

% sidebyside environment
\newenvironment{sidebyside}{\begin{adjustwidth}{-3cm}{1cm}}{\end{adjustwidth}}

% gitinfo2 settings
\renewcommand{\gitMark}{\gitBranch\,@\,\gitAbbrevHash{}\,\textbullet{}\,\gitAuthorDate }

% setting up gitinfo2:
%   copy the file post-xxx-sample.txt from https://www.ctan.org/tex-archive/macros/latex/contrib/gitinfo2
%   and put it in .git/hooks/post-checkout
% then
%   cd .git/hooks
%   chmod g+x post-checkout
%   chmod +x post-checkout
%   cp post-checkout post-commit
%   cp post-checkout post-merge
%   cd ../..
%   git checkout master
%   git checkout develop
%   ls .git
% and you should see gitHeadInfo.gin
\begin{document}
% \begin{noindent}
	\title{\lstinline[basicstyle=\huge\ttfamily]!latexindent.pl!\\[1cm]
		Version 2.2}
% \end{noindent}
\author{Chris Hughes \footnote{and contributors! (See \vref{sec:contributors}.)}}
\maketitle
\begin{abstract}
	\lstinline!latexindent.pl! is a \lstinline!Perl! script that indents \lstinline!.tex! (and other)
	files according to an indentation scheme that the user can modify to suit their
	taste. Environments, including those with alignment delimiters (such as \lstinline!tabular!),
	and commands, including those that can split braces and brackets across lines,
	are \emph{usually} handled correctly by the script. Options for \lstinline!verbatim!-like
	environments and indentation after headings (such as \lstinline!\chapter!, \lstinline!\section!, etc)
	are also available.
\end{abstract}

\tableofcontents
\lstlistoflistings

\section{Before we begin}
\subsection{Thanks}
I first created \lstinline!latexindent.pl! to help me format chapter files
in a big project. After I blogged about it on the
\TeX{} stack exchange \cite{cmhblog} I received some positive feedback and
follow-up feature requests. A big thank you to Harish Kumar who has really
helped to drive the script forward and has put it through a number of challenging
tests--I look forward to more challenges in the future Harish!

The \lstinline!yaml!-based interface of \lstinline!latexindent.pl! was inspired
by the wonderful \lstinline!arara! tool; any similarities are deliberate, and
I hope that it is perceived as the compliment that it is. Thank you to Paulo Cereda and the
team for releasing this awesome tool; I initially worried that I was going to
have to make a GUI for \lstinline!latexindent.pl!, but the release of \lstinline!arara!
has meant there is no need. Thank you to Paulo for all of your advice and
encouragement.

There have been several contributors to the project so far (and hopefully more in
the future!); thank you very much to the people detailed in \vref{sec:contributors}
for their valued contributions.

\subsection{License}
\lstinline!latexindent.pl! is free and open source, and it always will be.
Before you start using it on any important files, bear in mind that \lstinline!latexindent.pl! has the option to overwrite your \lstinline!.tex! files.
It will always make at least one backup (you can choose how many it makes, see \cpageref{page:onlyonebackup})
but you should still be careful when using it. The script has been tested on many
files, but there are some known limitations (see \cref{sec:knownlimitations}).
You, the user, are responsible for ensuring that you maintain backups of your files
before running \lstinline!latexindent.pl! on them. I think it is important at this
stage to restate an important part of the license here:
\begin{quote}\itshape
	This program is distributed in the hope that it will be useful,
	but WITHOUT ANY WARRANTY; without even the implied warranty of
	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
	GNU General Public License for more details.
\end{quote}
There is certainly no malicious intent in releasing this script, and I do hope
that it works as you expect it to--if it does not, please first of all
make sure that you have the correct settings, and then feel free to let me know with a
complete minimum working example as I would like to improve the code as much as possible.

\begin{warning}
	Before you try the script on anything important (like your thesis), test it
	out on the sample files that come with it in the \lstinline!success! directory.
\end{warning}


\section{Demonstration: before and after}
Let's give a demonstration of some before and after code--after all, you probably
won't want to try the script if you don't much like the results. You might also
like to watch the video demonstration I made on youtube \cite{cmh:videodemo}

As you look at \crefrange{lst:filecontentsbefore}{lst:pstricksafter}, remember
that \lstinline!latexindent.pl! is just following its rules--there is nothing
particular about these code snippets. All of the rules can be modified
so that each user can personalize their indentation scheme.

In each of the samples given in \crefrange{lst:filecontentsbefore}{lst:pstricksafter}
the `before' case is a `worst case scenario' with no effort to make indentation. The `after'
result would be the same, regardless of the leading white space at the beginning of
each line which is stripped by \lstinline!latexindent.pl! (unless a \lstinline!verbatim!-like
environment or \lstinline!noIndentBlock! is specified--more on this in \cref{sec:defuseloc}).

  \begin{sidebyside}
	\noindent
	\begin{minipage}{.6\textwidth}
		\begin{cmhlistings}[style=demo]{\lstinline!filecontents! before}{lst:filecontentsbefore}
\begin{filecontents}{mybib.bib}
@online{strawberryperl,
title="Strawberry Perl",
url="http://strawberryperl.com/"}
@online{cmhblog,
title="A Perl script ...
url="...
\end{filecontents}
		\end{cmhlistings}
	\end{minipage}%
	\noindent
	\begin{minipage}{.6\textwidth}
		\begin{cmhlistings}[style=demo]{\lstinline!filecontents! after}{lst:filecontentsafter}
\begin{filecontents}{mybib.bib}
	@online{strawberryperl,
		title="Strawberry Perl",
		url="http://strawberryperl.com/"}
	@online{cmhblog,
		title="A Perl script for ...
		url="...
\end{filecontents}
		\end{cmhlistings}
	\end{minipage}
	\begin{minipage}{.6\textwidth}
		\begin{cmhlistings}[style=demo]{\lstinline!tikzset! before}{lst:tikzsetbefore}
\tikzset{
shrink inner sep/.code={
\pgfkeysgetvalue...
\pgfkeysgetvalue...
}
}
		\end{cmhlistings}
	\end{minipage}%
	\begin{minipage}{.6\textwidth}
		\begin{cmhlistings}[style=demo]{\lstinline!tikzset! after}{lst:tikzsetafter}
\tikzset{
	shrink inner sep/.code={
		\pgfkeysgetvalue...
		\pgfkeysgetvalue...
	}
}
		\end{cmhlistings}
	\end{minipage}
	\begin{minipage}{.6\textwidth}
		\begin{cmhlistings}[style=demo]{\lstinline!pstricks! before}{lst:pstricksbefore}
\def\Picture#1{%
\def\stripH{#1}%
\begin{pspicture}[showgrid...
\psforeach{\row}{%
{{3,2.8,2.7,3,3.1}},% <=== Only this
{2.8,1,1.2,2,3},%
...
}{%
\expandafter...
}
\end{pspicture}}
		\end{cmhlistings}
	\end{minipage}%
	\begin{minipage}{.6\textwidth}
		\begin{cmhlistings}[style=demo]{\lstinline!pstricks! after}{lst:pstricksafter}
\def\Picture#1{%
	\def\stripH{#1}%
	\begin{pspicture}[showgrid...
		\psforeach{\row}{%
			{{3,2.8,2.7,3,3.1}},% <===
			{2.8,1,1.2,2,3},%
            ...
			}{%
			\expandafter...
		}
	\end{pspicture}}
		\end{cmhlistings}
	\end{minipage}
  \end{sidebyside}

\section{How to use the script}
\lstinline!latexindent.pl! ships as part of the \TeX Live distribution for
Linux and Mac users; \lstinline!latexindent.exe! ships as part of the \TeX Live
and MiK\TeX distributions for Windows users. These files are also available
from github \cite{latexindent-home} should you wish to use them without
a \TeX{} distribution; in this case, you may like to read \vref{sec:updating-path}
which details how the \lstinline!path! variable can be updated.

In what follows, we will always refer to \lstinline!latexindent.pl!, but depending on
your operating system and preference, you might substitute \lstinline!latexindent.exe! or
simply \lstinline!latexindent!.

There are two ways to use \lstinline!latexindent.pl!: from the command line,
and using \lstinline!arara!; we discuss these in \cref{sec:commandline} and
\cref{sec:arara} respectively. We will discuss how to change the settings and 
behaviour of the script in \vref{sec:defuseloc}.

\lstinline!latexindent.pl! ships with \lstinline!latexindent.exe! for Windows
users, so that you can use the script with or without a Perl distribution.
If you plan to use \lstinline!latexindent.pl! (i.e, the original Perl script) then you will
need a few standard Perl modules--see \vref{sec:requiredmodules} for details.

\subsection{From the command line}\label{sec:commandline}
\lstinline!latexindent.pl! has a number of different switches/flags/options, which
can be combined in any way that you like, either in short or long form as detailed below. 
\lstinline!latexindent.pl!  produces a \lstinline!.log! file, \lstinline!indent.log! every time it
is run. There is a base of information that is written to \lstinline!indent.log!,
but other additional information will be written depending
on which of the following options are used.

\begin{itemize}[labelsep=.25cm]
	\item[] \lstinline!latexindent.pl!

	      This will output a welcome message to the terminal, including the version number
	      and available options.
	\item[\verbitem{-h, --help}] \lstinline!latexindent.pl -h!

	      As above this will output a welcome message to the terminal, including the version number
	      and available options.
	\item[] \lstinline!latexindent.pl myfile.tex!

	      This will operate on \lstinline!myfile.tex!, but will simply output to your terminal; \lstinline!myfile.tex! will	not be changed in any way using this command.
	\item[\verbitem{-w, --overwrite}] \lstinline!latexindent.pl -w myfile.tex!

	      This \emph{will} overwrite \lstinline!myfile.tex!, but it will
	      make a copy of \lstinline!myfile.tex! first. You can control the name of
	      the extension (default is \lstinline!.bak!), and how many different backups are made--
	      more on this in \cref{sec:defuseloc}; see \lstinline!backupExtension! and \lstinline!onlyOneBackUp!.

	      Note that if \lstinline!latexindent.pl! can not create the backup, then it
	      will exit without touching your original file; an error message will be given
	      asking you to check the permissions of the backup file.
	\item[\verbitem{-o,--outputfile}] \lstinline!latexindent.pl -o myfile.tex outputfile.tex!

	      This will indent \lstinline!myfile.tex! and output it to \lstinline!outputfile.tex!,
	      overwriting it (\lstinline!outputfile.tex!) if it already exists. Note that if \lstinline!latexindent.pl! is called with both
	      the \lstinline!-w! and \lstinline!-o! switches, then \lstinline!-w! will
	      be ignored and \lstinline!-o! will take priority (this seems safer than the
	      other way round).

	      Note that using \lstinline!-o! is equivalent to using \lstinline!latexindent.pl myfile.tex > outputfile.tex!
	\item[\verbitem{-s, --silent}] \lstinline!latexindent.pl -s myfile.tex!

	      Silent mode: no output will be given to the terminal.
	\item[\verbitem{-t, --trace}] \lstinline!latexindent.pl -t myfile.tex!

	      \label{page:traceswitch}
	      Tracing mode: verbose output will be given to \lstinline!indent.log!. This
	      is useful if \lstinline!latexindent.pl! has made a mistake and you're
	      trying to find out where and why. You might also be interested in learning
	      about \lstinline!latexindent.pl!'s thought process--if so, this
	      switch is for you.
	\item[\verbitem{-tt, --ttrace}] \lstinline!latexindent.pl -tt myfile.tex!

      \emph{More detailed} tracing mode: this option gives more details to \lstinline!indent.log!
      than the standard \lstinline!trace! option.
	\item[\verbitem{-l, --local[=myyaml.yaml]}] \lstinline!latexindent.pl -l myfile.tex!

\lstinline!latexindent.pl -l=myyaml.yaml myfile.tex!

\lstinline!latexindent.pl -l myyaml.yaml myfile.tex!


	      \label{page:localswitch}
	      Local settings: you might like to read \cref{sec:defuseloc} before
	      using this switch. \lstinline!latexindent.pl! will always load \lstinline!defaultSettings.yaml!
	      and if it is called with the \lstinline!-l! switch and it finds \lstinline!localSettings.yaml!
	      in the same directory as \lstinline!myfile.tex! then these settings will be
	      added to the indentation scheme. Information will be given in \lstinline!indent.log! on
	      the success or failure of loading \lstinline!localSettings.yaml!.

The \lstinline!-l! flag can take an \emph{optional} parameter which details the name of a \lstinline!yaml! file
that resides in the same directory as \lstinline!myfile.tex!; you can use this option if you would 
like to load a settings file in the current working directory that is \emph{not} called \lstinline!localSettings.yaml!.

	\item[\verbitem{-d, --onlydefault}] \lstinline!latexindent.pl -d myfile.tex!

	      Only \lstinline!defaultSettings.yaml!: you might like to read \cref{sec:defuseloc} before
	      using this switch. By default, \lstinline!latexindent.pl! will always search for
	      \lstinline!indentconfig.yaml! or \lstinline!.indentconfig.yaml!  in your home directory. If you would prefer it not to do so
	      then (instead of deleting or renaming \lstinline!indentconfig.yaml!/\lstinline!.indentconfig.yaml!) you can simply
	      call the script with the \lstinline!-d! switch; note that this will also tell
	      the script to ignore \lstinline!localSettings.yaml! even if it has been called with the
	      \lstinline!-l! switch.

	\item[\verbitem{-c, --cruft=<directory>}]\lstinline!latexindent.pl -c=/path/to/directory/ myfile.tex!

	      If you wish to have backup files and \lstinline!indent.log! written to a directory
	      other than the current working directory, then you can send these `cruft' files
	      to another directory.
	      % this switch was made as a result of http://tex.stackexchange.com/questions/142652/output-latexindent-auxiliary-files-to-a-different-directory
\end{itemize}

\lstinline!latexindent.pl! can also be called on a file without the file extension, for
example \lstinline[breaklines=true,breakatwhitespace=true,]!latexindent.pl myfile! and in which case, you can specify
the order in which extensions are searched for; see \vref{lst:fileExtensionPreference}
for full details.

\subsection{From \lstinline!arara!}\label{sec:arara}
Using \lstinline!latexindent.pl! from the command line is fine for some folks, but
others may find it easier to use from \lstinline!arara!. \lstinline!latexindent.pl!
ships with an \lstinline!arara! rule, \lstinline!indent.yaml!, which can be copied
to the directory of
your other \lstinline!arara! rules; otherwise  you can add the directory in which \lstinline!latexindent.pl!
resides to your \lstinline!araraconfig.yaml! file.

Once you have told \lstinline!arara! where to find your \lstinline!indent! rule,
you can use it any of the ways described in \cref{lst:arara} (or combinations thereof).
In fact, \lstinline!arara! allows yet greater flexibility--you can use \lstinline!yes/no!, \lstinline!true/false!, or \lstinline!on/off! to toggle the various options.

\begin{cmhlistings}[style=demo,escapeinside={(*@}{@*)}]{\lstinline!arara! sample usage}{lst:arara}
%(*@@*) arara: indent
%(*@@*) arara: indent: {overwrite: yes}
%(*@@*) arara: indent: {output: myfile.tex}
%(*@@*) arara: indent: {silent: yes}
%(*@@*) arara: indent: {trace: yes}
%(*@@*) arara: indent: {localSettings: yes}
%(*@@*) arara: indent: {onlyDefault: on}
%(*@@*) arara: indent: { cruft: /home/cmhughes/Desktop }
\documentclass{article}
...
\end{cmhlistings}

Hopefully the use of these rules is fairly self-explanatory, but for completeness
\cref{tab:orbsandswitches} shows the relationship between \lstinline!arara! directive arguments and the
switches given in \cref{sec:commandline}.

\begin{table}[!ht]
	\centering
	\caption{\lstinline!arara! directive arguments and corresponding switches}
	\label{tab:orbsandswitches}
	\begin{tabular}{lc}
		\toprule
		\lstinline!arara! directive argument & switch         \\
		\midrule
		\lstinline!overwrite!                & \lstinline!-w! \\
		\lstinline!output!                   & \lstinline!-o! \\
		\lstinline!silent!                   & \lstinline!-s! \\
		\lstinline!trace!                    & \lstinline!-t! \\
		\lstinline!localSettings!            & \lstinline!-l! \\
		\lstinline!onlyDefault!              & \lstinline!-d! \\
		\lstinline!cruft!                    & \lstinline!-c! \\
		\bottomrule
	\end{tabular}
\end{table}

The \lstinline!cruft! directive does not work well when used with
directories that contain spaces.

\section{default, user, and local settings}\label{sec:defuseloc}
\lstinline!latexindent.pl! loads its settings from \lstinline!defaultSettings.yaml!
(rhymes with camel). 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.

\subsection{\lstinline!defaultSettings.yaml!}
If you look in \lstinline!defaultSettings.yaml! you'll find the switches
that govern the behaviour of \lstinline!latexindent.pl!. If you're not sure where
\lstinline!defaultSettings.yaml! resides on your computer, don't worry as \lstinline!indent.log!
will tell you where to find it.
\lstinline!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.

You can certainly feel free to edit \lstinline!defaultSettings.yaml!, but
this is not ideal as it may be overwritten when you update your \TeX{} distribution --
all of your hard work tweaking the script would be undone! Don't worry,
there's a solution, feel free to peek ahead to \cref{sec:indentconfig} if you like.
\begin{itemize}
	\item[\verbitem{defaultIndent}] \lstinline!"\t"!

	      This is the default indentation (\lstinline!\t! means a tab) used in the absence of other details
	      for the command or environment we are working with--see \lstinline!indentRules!
	      for more details (\cpageref{page:indentRules}).

	      If you're interested in experimenting with \lstinline!latexindent.pl! then you
	      can \emph{remove} all indentation by setting \lstinline!defaultIndent: ""!
	\item[\verbitem{backupExtension}] \lstinline!.bak!

	      If you call \lstinline!latexindent.pl! with the \lstinline!-w! switch (to overwrite
	      \lstinline!myfile.tex!) then it will create a backup file before doing
	      any indentation: \lstinline!myfile.bak0!

	      By default, every time you call \lstinline!latexindent.pl! after this with
	      the \lstinline!-w! switch it will create \lstinline!myfile.bak1!, \lstinline!myfile.bak2!,
	      etc.
	\item[\verbitem{onlyOneBackUp}] \lstinline!0!

	      \label{page:onlyonebackup}
	      If you don't want a backup for every time that you call \lstinline!latexindent.pl! (so
	      you don't want \lstinline!myfile.bak1!, \lstinline!myfile.bak2!, etc) and you simply
	      want \lstinline!myfile.bak! (or whatever you chose \lstinline!backupExtension! to be)
	      then change \lstinline!onlyOneBackUp! to \lstinline!1!.

	\item[\verbitem{maxNumberOfBackUps}]\lstinline!0!

	      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 \lstinline!maxNumberOfBackUps! is $0$ which will \emph{not}
	      prevent backup files being made--in this case, the behaviour will be dictated
	      entirely by \lstinline!onlyOneBackUp!.
	      %\footnote{This was a feature request made on \href{https://github.com/cmhughes/latexindent.plx}{github}}
	\item[\verbitem{cycleThroughBackUps}]\lstinline!0!

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

	      \begin{cmhlistings}[language=Perl]{\lstinline!cycleThroughBackUps!}{lst:cycleThroughBackUps}
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{cmhlistings}

	\item[\verbitem{indentPreamble}] \lstinline!0!

	      The preamble of a document can sometimes contain some trickier code
	      for \lstinline!latexindent.pl! to work with. By default, \lstinline!latexindent.pl!
	      won't try to operate on the preamble, but if you'd like it to try then
	      change \lstinline!indentPreamble! to \lstinline!1!.
	\item[\verbitem{alwaysLookforSplitBraces}] \lstinline!1!

	      This switch tells \lstinline!latexindent.pl! to look for commands that
	      can split \emph{braces} across lines, such as \lstinline!parbox!, \lstinline!tikzset!, etc. In older
	      versions of \lstinline!latexindent.pl! you had to specify each one in \lstinline!checkunmatched!--this
	      clearly became tedious, hence the introduction of \lstinline!alwaysLookforSplitBraces!.

	      \emph{As long as you leave this switch on (set to 1) you don't need to specify which
	      	commands can split braces across lines--you can ignore the
	      	fields \lstinline!checkunmatched! and \lstinline!checkunmatchedELSE! described
	      	later on \cpageref{lst:checkunmatched}}.
	\item[\verbitem{alwaysLookforSplitBrackets}] \lstinline!1!

	      This switch tells \lstinline!latexindent.pl! to look for commands that
	      can split \emph{brackets} across lines, such as \lstinline!psSolid!, \lstinline!pgfplotstabletypeset!,
	      etc. In older versions of \lstinline!latexindent.pl! you had to specify each one in \lstinline!checkunmatchedbracket!--
	      this clearly became tedious, hence the introduction of \lstinline!alwaysLookforSplitBraces!.

	      \emph{As long as you leave this switch on (set to 1) you don't need to specify which
	      	commands can split brackets across lines--you can ignore \lstinline!checkunmatchedbracket! described later on
	      	\cpageref{lst:checkunmatched}}.

	\item[\verbitem{removeTrailingWhitespace}] \lstinline!0!

	      By default \lstinline!latexindent.pl! indents every line (including empty lines)
	      which creates `trailing white space' feared by most version control systems. If
	      this option is set to \lstinline!1!, trailing white space is removed from all
	      lines, also non-empty ones. In general this should not create any problems, but
	      by precaution this option is turned off by default. Thanks to \cite{vosskuhle} for
	      providing this feature.

	\item[\verbitem{lookForAlignDelims}] This is the first example of a field
	      in \lstinline!defaultSettings.yaml! that has more than one line; \cref{lst:aligndelims:basic}
	      shows more details. In fact, the fields in \verbitem{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.

	      \begin{cmhlistings}[style=yaml]{\lstinline!lookForAlignDelims! (basic)}{lst:aligndelims:basic}
lookForAlignDelims:
   tabular: 1
   tabularx: 1
   longtable: 1
   array: 1
   matrix: 1
   bmatrix: 1
   pmatrix: 1
   align: 1
   align*: 1
   alignat: 1
   alignat*: 1
   aligned: 1
   cases: 1
   dcases: 1
   pmatrix: 1
   listabla: 1
	\end{cmhlistings}

	The environments specified in this field will be operated on in a special way  by \lstinline!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}.

	\begin{minipage}{.5\textwidth}
		\begin{cmhlistings}[style=demo,columns=fixed]{\lstinline!tabular! before}{lst:tabularbefore:basic}
\begin{tabular}{cccc}
1&	2 &3       &4\\
5& &6       &\\
\end{tabular}
		\end{cmhlistings}
	\end{minipage}%
	\begin{minipage}{.5\textwidth}
		\begin{cmhlistings}[style=demo,columns=fixed]{\lstinline!tabular! after (basic)}{lst:tabularafter:basic}
\begin{tabular}{cccc}
 1 & 2 & 3 & 4 \\
 5 &   & 6 &   \\
\end{tabular}
		\end{cmhlistings}
	\end{minipage}

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

    If you wish to remove the alignment of the \lstinline!\\! within a delimiter-aligned block, then the
    advanced form of \lstinline!lookForAlignDelims! shown in \cref{lst:aligndelims:advanced} is for you. 
	      \begin{cmhlistings}[style=yaml]{\lstinline!lookForAlignDelims! (advanced)}{lst:aligndelims:advanced}
lookForAlignDelims:
   tabular: 
      delims: 1
      alignDoubleBackSlash: 0
      spacesBeforeDoubleBackSlash: 0
   tabularx:
      delims: 1
   longtable: 1
	\end{cmhlistings}

    Note that you can use a mixture of the basic and advanced form: in \cref{lst:aligndelims:advanced} \lstinline!tabular! and \lstinline!tabularx! 
    are advanced and \lstinline!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 up to 3 fields: 
    \begin{itemize}
      \item \lstinline!delims!: switch equivalent to simply specifying, for example, \lstinline!tabular: 1! in
        the basic version shown in \cref{lst:aligndelims:basic} (default: 1);
      \item \lstinline!alignDoubleBackSlash!: switch to determine if \lstinline!\\! should be aligned (default: 1);
      \item \lstinline!spacesBeforeDoubleBackSlash!: optionally, specifies the number of spaces to be inserted
        before (non-aligned) \lstinline!\\!. In order to use this field, \lstinline!alignDoubleBackSlash! needs
        to be set to 0 (default: 0).
    \end{itemize}
    
    With the settings shown in \cref{lst:aligndelims:advanced} we receive the before-and-after results shown in
    \cref{lst:tabularbefore:advanced,lst:tabularafter:advanced}; note that the ampersands have been aligned, but 
    the \lstinline!\\! have not (compare the alignment of \lstinline!\\! in \cref{lst:tabularafter:basic,lst:tabularafter:advanced}).

	\begin{minipage}{.5\textwidth}
		\begin{cmhlistings}[style=demo,columns=fixed]{\lstinline!tabular! before }{lst:tabularbefore:advanced}
\begin{tabular}{cccc}
1&	2 &3       &4\\
5& &6       &\\
\end{tabular}
		\end{cmhlistings}
	\end{minipage}%
	\begin{minipage}{.5\textwidth}
		\begin{cmhlistings}[style=demo,columns=fixed]{\lstinline!tabular! after (advanced)}{lst:tabularafter:advanced}
\begin{tabular}{cccc}
 1 & 2 & 3 & 4\\
 5 &   & 6 &\\
\end{tabular}
		\end{cmhlistings}
	\end{minipage}

    Using  \lstinline!spacesBeforeDoubleBackSlash: 3! gives \cref{lst:tabularbefore:spacing,lst:tabularafter:spacing}, 
    note the spacing before the \lstinline!\\! in \cref{lst:tabularafter:spacing}.

	\begin{minipage}{.5\textwidth}
		\begin{cmhlistings}[style=demo,columns=fixed]{\lstinline!tabular! before}{lst:tabularbefore:spacing}
\begin{tabular}{cccc}
1&	2 &3       &4\\
5& &6       &\\
\end{tabular}
		\end{cmhlistings}
	\end{minipage}%
	\begin{minipage}{.5\textwidth}
		\begin{cmhlistings}[style=demo,columns=fixed]{\lstinline!tabular! after (spacing)}{lst:tabularafter:spacing}
\begin{tabular}{cccc}
 1 & 2 & 3 & 4   \\
 5 &   & 6 &   \\
\end{tabular}
		\end{cmhlistings}
	\end{minipage}

	


	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}...\end{tabular}!, then you use the mark up
	      illustrated in \cref{lst:alignmentmarkup}. 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 \lstinline!lookForAlignDelims!.
	      \begin{cmhlistings}[style=demo,columns=fixed]{Mark up for aligning delimiters outside of environments}{lst:alignmentmarkup}
\matrix{%
%* \begin{tabular}
 1 & 2 & 3 & 4 \\
 5 &   & 6 &   \\
%* \end{tabular}
}
	\end{cmhlistings}

	\item[\verbitem{verbatimEnvironments}] A field that contains a list of environments
	      that you would like left completely alone--no indentation will be done
	      to environments that you have specified in this field--see \cref{lst:verbatimEnvironments}.


	      \begin{cmhlistings}[style=yaml]{\lstinline!verbatimEnvironments!}{lst:verbatimEnvironments}
verbatimEnvironments:
    verbatim: 1
    lstlisting: 1
	\end{cmhlistings}
	Note that if  you put an environment in \lstinline!verbatimEnvironments!
	and in other fields such as \lstinline!lookForAlignDelims! or \lstinline!noAdditionalIndent!
	then \lstinline!latexindent.pl! will \emph{always} prioritize \lstinline!verbatimEnvironments!.

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

	      \begin{cmhlistings}[style=yaml]{\lstinline!noIndentBlock!}{lst:noIndentBlock}
noIndentBlock:
    noindent: 1
    cmhtest: 1
	\end{cmhlistings}

	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={(*@}{@*)}]{\lstinline!noIndentBlock! demonstration}{lst:noIndentBlockdemo}
%(*@@*) \begin{noindent}
        this code
                won't
     be touched
                    by
             latexindent.pl!
%(*@@*)\end{noindent}
	\end{cmhlistings}

	\item[\verbitem{noAdditionalIndent}] If you would prefer some of your
	      environments or commands not to receive any additional indent, then
	      populate \lstinline!noAdditionalIndent!; see \cref{lst:noAdditionalIndent}.
	      Note that these environments will still receive the \emph{current} level
	      of indentation unless they belong to \lstinline!verbatimEnvironments!, or \lstinline!noIndentBlock!.

	      \begin{cmhlistings}[style=yaml]{\lstinline!noAdditionalIndent!}{lst:noAdditionalIndent}
noAdditionalIndent:
    document: 1
    myexample: 1
    mydefinition: 1
    problem: 1
    exercises: 1
    mysolution: 1
    foreach: 0
    widepage: 1
    comment: 1
    \[: 1
    \]: 1
    frame: 0
	\end{cmhlistings}
	Note in particular from \cref{lst:noAdditionalIndent} that if you wish content within
	\lstinline!\[!  and \lstinline!\]! to receive no additional indentation then
	you have to specify \emph{both} as \lstinline!1! (the default is \lstinline!0!).
	If you do not specify both as the same value you may get some interesting results!
	\item[\verbitem{indentRules}] If\label{page:indentRules} you would prefer to specify
	      individual rules for certain environments or commands, just
	      populate \lstinline!indentRules!; see \cref{lst:indentRules}

	      \begin{cmhlistings}[style=yaml]{\lstinline!indentRules!}{lst:indentRules}
indentRules:
   myenvironment: "\t\t"
   anotherenvironment: "\t\t\t\t"
   \[: "\t"
	\end{cmhlistings}      %%%%%\] just here to stop vim from colouring the rest of my code
	Note that in contrast to \lstinline!noAdditionalIndent! you do \emph{not}
	need to specify both \lstinline!\[! and \lstinline!\]! in this field.

	If you put an environment in both \lstinline!noAdditionalIndent! and in
	\lstinline!indentRules! then \lstinline!latexindent.pl! will resolve the conflict
	by ignoring \lstinline!indentRules! and prioritizing \lstinline!noAdditionalIndent!.
	You will get a warning message in \lstinline!indent.log!; note that you will only
	get one warning message per command or environment. Further discussion
	is given in \cref{sec:fieldhierachy}.

	\item[\verbitem{indentAfterHeadings}] 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*! etc. This field is slightly different from most
	      of the fields that we have considered previously, because each element is
	      itself a field which has two elements: \lstinline!indent! and \lstinline!level!. (Similar 
          in structure to the advanced form of  \lstinline!lookForAlignDelims! in \cref{lst:aligndelims:advanced}.)
	      \begin{cmhlistings}[style=yaml]{\lstinline!indentAfterHeadings!}{lst:indentAfterHeadings}
indentAfterHeadings:
    part:
       indent: 0
       level: 1
    chapter:
       indent: 0
       level: 2
    section:
       indent: 0
       level: 3
    ...
	\end{cmhlistings}
	The default settings do \emph{not} place indentation after a heading--you
	can easily switch them on by changing \lstinline!indent: 0! to \lstinline!indent: 1!.
	The \lstinline!level! field tells \lstinline!latexindent.pl! the hierarchy of the heading
	structure in your document. You might, for example, like to have both \lstinline!section!
	and \lstinline!subsection! set with \lstinline!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 \lstinline!level!
	as appropriate.  You can also specify your own indentation in \lstinline!indentRules!--
	you will find the default \lstinline!indentRules! contains \lstinline!chapter: " "! which
	tells \lstinline!latexindent.pl! simply to use a space character after \lstinline!\chapter! headings
	(once \lstinline!indent! is set to \lstinline!1! for \lstinline!chapter!).

	\item[\verbitem{indentAfterItems}] The environments specified in \lstinline!indentAfterItems!  tell
	      \lstinline!latexindent.pl! to look for \lstinline!\item! commands; if these switches are set to \lstinline!1!
	      then indentation will be performed so as indent the code after each \lstinline!item!.
	      \begin{cmhlistings}{\lstinline!indentAfterItems!}{lst:indentafteritems}
indentAfterItems:
    itemize: 1
    enumerate: 1
	\end{cmhlistings}
	A demonstration is given in \cref{lst:itemsbefore,lst:itemsafter}

	\begin{minipage}{.5\textwidth}
		\begin{cmhlistings}[style=demo,xleftmargin=-3mm,columns=fixed]{\lstinline!items! before}{lst:itemsbefore}
\begin{itemize}
\item some text here
some more text here
some more text here
\item another item
\end{itemize}
		\end{cmhlistings}
	\end{minipage}%
	\begin{minipage}{.5\textwidth}
		\begin{cmhlistings}[style=demo,xleftmargin=-3mm,columns=fixed]{\lstinline!items! after}{lst:itemsafter}
\begin{itemize}
	\item some text here
		   some more text here
		   some more text here
	\item another item
\end{itemize}
		\end{cmhlistings}
	\end{minipage}

	\item[\verbitem{itemNames}] If you have your own \lstinline!item! commands (perhaps you
	      prefer to use \lstinline!myitem!, for example)
	      then you can put populate them in \lstinline!itemNames!.
	      For example, users of the \lstinline!exam! document class might like to add
	      \lstinline!parts! to \lstinline!indentAfterItems! and \lstinline!part! to \lstinline!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}

	\item[\verbitem{constructIfElseFi}] The commands specified in this field
	      will tell \lstinline!latexindent.pl! to look for constructs that
	      have the form \lstinline!\if...! \lstinline!\else...! \lstinline!\fi!, such as,
	      for example, \lstinline!\ifnum!; see \cref{lst:iffibefore,lst:iffiafter} for
	      a before-and-after demonstration.

	      \begin{minipage}{.5\textwidth}
	      	\begin{cmhlistings}[style=demo,xleftmargin=-3mm,columns=fixed]{\lstinline!if-else-fi! construct before}{lst:iffibefore}
\ifnum\radius>5
\ifnum\radius<16
\draw[decorate,...
\fi
\fi
	      	\end{cmhlistings}
	      \end{minipage}%
	      \begin{minipage}{.5\textwidth}
	      	\begin{cmhlistings}[style=demo,xleftmargin=-3mm,columns=fixed]{\lstinline!if-else-fi! construct after}{lst:iffiafter}
\ifnum\radius>5
    \ifnum\radius<16
    	\draw[decorate,...
	\fi
\fi
	      	\end{cmhlistings}
	      \end{minipage}

	\item[\verbitem{fileExtensionPreference}] \lstinline!latexindent.pl! can be called to
	      act on a file without
	      specifying the file extension.  For example we can call \lstinline!latexindent.pl myfile!
	      in which case the script will look for \lstinline!myfile! with the extensions
	      specified in \lstinline!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.
	      \begin{cmhlistings}[style=yaml]{\lstinline!fileExtensionPreference!}{lst:fileExtensionPreference}
fileExtensionPreference:
    .tex: 1
    .sty: 2
    .cls: 3
    .bib: 4
	\end{cmhlistings}
	Calling \lstinline!latexindent.pl myfile! with the details specified in \cref{lst:fileExtensionPreference}
	means that the script will first look for \lstinline!myfile.tex!, then \lstinline!myfile.sty!, \lstinline!myfile.cls!, 
    and finally \lstinline!myfile.bib! in order.
\item[\verbitem{logFilePreferences}] 
  \lstinline!latexindent.pl! writes information to \lstinline!indent.log!, some 
  of which can be customised by changing \lstinline!logFilePreferences!; see \cref{lst:logFilePreferences}.
\begin{cmhlistings}[style=yaml]{\lstinline!logFilePreferences!}{lst:logFilePreferences}
logFilePreferences:
    showEveryYamlRead: 1
    showAlmagamatedSettings: 0
    endLogFileWith: '--------------' 
    traceModeIncreaseIndent: '>>'
    traceModeAddCurrentIndent: '||'
    traceModeDecreaseIndent: '<<'
    traceModeBetweenLines: "\n"
  \end{cmhlistings}
If you load your own user settings (see \vref{sec:indentconfig}) then \lstinline!latexindent.pl! will
detail them in \lstinline!indent.log!; you can choose not to have the details logged by switching
\lstinline!showEveryYamlRead! to \lstinline!0!. Once all of your settings have 
been loaded, you can see the amalgamated settings by switching \lstinline!showAlmagamatedSettings! 
to \lstinline!1!, if you wish. The log file will end with the characters 
given in \lstinline!endLogFileWith!.

When \lstinline!trace! mode is active (see \cpageref{page:traceswitch}) verbose information is written 
to \lstinline!indent.log!. The decoration of this information can be customised through the remaining
fields given in \cref{lst:logFilePreferences}; note, in particular, the use of \lstinline!"\n"! for 
escaped characters (using single quotes will not produce the same results).

\item[\verbitem{fileContentsEnvironments}] 
  \lstinline!latexindent.pl! determines when the main document begins by looking for \lstinline!\begin{document}!; 
  it will not do so when inside any of the environments specified in \lstinline!fileContentsEnvironments!, see
  \cref{lst:fileContentsEnvironments}.
\begin{cmhlistings}[style=yaml]{\lstinline!fileContentsEnvironments!}{lst:fileContentsEnvironments}
fileContentsEnvironments:
    filecontents: 1
    filecontents*: 1
  \end{cmhlistings}

	\begin{warning}
		\emph{The following fields are marked in red, as they are not necessary
			unless you wish to micro-manage your indentation scheme.
			Note that in each case, you should \emph{not} use the backslash.}
	\end{warning}

	% to anyone reading the source code- I know the next line isn't the
	% correct way to do it :)
	\item[\color{red}\verbitem{checkunmatched}] Assuming you keep \lstinline!alwaysLookforSplitBraces! set to \lstinline!1! (which
	      is the default) then you don't need to worry about \lstinline!checkunmatched!.

	      Should you wish to deactivate \lstinline!alwaysLookforSplitBraces! by setting it to \lstinline!0!, then
	      you can populate \lstinline!checkunmatched! with commands that can split braces across
	      lines--see \cref{lst:checkunmatched}.

	      \begin{cmhlistings}[style=yaml]{\lstinline!checkunmatched!}{lst:checkunmatched}
checkunmatched:
    parbox: 1
    vbox: 1
	\end{cmhlistings}
	\item[\color{red}\verbitem{checkunmatchedELSE}] Similarly, assuming you keep \lstinline!alwaysLookforSplitBraces! set to \lstinline!1! (which
	      is the default) then you don't need to worry about \lstinline!checkunmatchedELSE!.

	      As in \lstinline!checkunmatched!, should you wish to deactivate \lstinline!alwaysLookforSplitBraces! by setting it to \lstinline!0!, then
	      you can populate \lstinline!checkunmatchedELSE! with commands that can split braces across
	      lines \emph{and} have an `else' statement--see \cref{lst:checkunmatchedELSE}.

	      \begin{cmhlistings}[style=yaml]{\lstinline!checkunmatchedELSE!}{lst:checkunmatchedELSE}
checkunmatchedELSE:
    pgfkeysifdefined: 1
    DTLforeach: 1
    ifthenelse: 1
	\end{cmhlistings}
	\item[\color{red}\verbitem{checkunmatchedbracket}] Assuming you keep \lstinline!alwaysLookforSplitBrackets!
	      set to \lstinline!1! (which is the default) then you don't need to worry about \lstinline!checkunmatchedbracket!.

	      Should you wish to deactivate \lstinline!alwaysLookforSplitBrackets! by setting it
	      to \lstinline!0!, then you can populate \lstinline!checkunmatchedbracket! with commands that can
	      split \emph{brackets} across lines--see \cref{lst:checkunmatchedbracket}.

	      \begin{cmhlistings}[style=yaml]{\lstinline!checkunmatchedbracket!}{lst:checkunmatchedbracket}
checkunmatchedbracket:
    psSolid: 1
    pgfplotstablecreatecol: 1
    pgfplotstablesave: 1
    pgfplotstabletypeset: 1
    mycommand: 1
	\end{cmhlistings}
\end{itemize}

\subsubsection{Hierarchy of fields}\label{sec:fieldhierachy}
After reading the previous section, it should sound reasonable that
\lstinline!noAdditionalIndent!, \lstinline!indentRules!, and
\lstinline!verbatim! all serve mutually exclusive tasks. Naturally, you may
well wonder what happens if you choose to ask \lstinline!latexindent.pl! to
prioritize one above the other.

For example, let's say that (after reading \cref{sec:indentconfig}) you put the fields in \cref{lst:conflict} into
one of your settings files.
\begin{cmhlistings}[style=yaml]{Conflicting ideas}{lst:conflict}
indentRules:
   myenvironment: "\t\t"
noAdditionalIndent:
   myenvironment: 1
\end{cmhlistings}

Clearly these fields conflict: first of all
you are telling \lstinline!latexindent.pl! that \lstinline!myenvironment! should
receive two tabs of indentation, and then you are telling it
not to put any indentation in the environment. \lstinline!latexindent.pl!
will always make the decision to prioritize \lstinline!noAdditionalIndent! above
\lstinline!indentRules! regardless of the order that you load them in
your settings file. The first
time it encounters \lstinline!myenvironment! it will put a warning in \lstinline!indent.log!
and delete the offending key from \lstinline!indentRules! so that any future
conflicts will not have to be addressed.

Let's consider another conflicting example in \cref{lst:bigconflict}
\begin{cmhlistings}[style=yaml]{More conflicting ideas}{lst:bigconflict}
lookForAlignDelims:
   myenvironment: 1
verbatimEnvironments:
   myenvironment: 1
\end{cmhlistings}
This is quite a significant conflict--we are first of all telling \lstinline!latexindent.pl!
to look for alignment delimiters in \lstinline!myenvironment! and then
telling it that actually we would like \lstinline!myenvironment! to be considered
as a \lstinline!verbatim!-like environment. Regardless of the order that we
state \cref{lst:bigconflict} the \lstinline!verbatim! instruction will always win.
As in \cref{lst:conflict} you will only receive a warning in \lstinline!indent.log! the
first time \lstinline!latexindent.pl! encounters \lstinline!myenvironment! as the
offending key is deleted from \lstinline!lookForAlignDelims!.

To summarize, \lstinline!latexindent.pl! will prioritize the various fields in the
following order:
\begin{enumerate}
	\item \lstinline!verbatimEnvironments!
	\item \lstinline!noAdditionalIndent!
	\item \lstinline!indentRules!
\end{enumerate}
\subsection{\lstinline!indentconfig.yaml! and \lstinline!.indentconfig.yaml! (for user settings)}\label{sec:indentconfig}
Editing \lstinline!defaultSettings.yaml! is not ideal as it may be overwritten when
updating your distribution--a better way to customize the settings to your liking
is to set up your own settings file,
\lstinline!mysettings.yaml! (or any name you like, provided it ends with \lstinline!.yaml!).
The only thing you have to do is tell \lstinline!latexindent.pl! where to find it.

\lstinline!latexindent.pl! will always check your home directory for \lstinline!indentconfig.yaml!
and  \lstinline!.indentconfig.yaml! (unless
it is called with the \lstinline!-d! switch),
which is a plain text file you can create that contains the \emph{absolute}
paths for any settings files that you wish \lstinline!latexindent.pl! to load. There is no difference
between \lstinline!indentconfig.yaml! and \lstinline!.indentconfig.yaml!, other than the
fact that \lstinline!.indentconfig.yaml! is a `hidden' file; thank you to \cite{jacobo-diaz-hidden-config}
for providing this feature. In what follows, we will use \lstinline!indentconfig.yaml!, but it
is understood that this equally represents \lstinline!.indentconfig.yaml! as well. If you
have both files in existence,  \lstinline!indentconfig.yaml! takes priority.

For Mac and Linux users, their home directory is \lstinline!~/username! while
Windows (Vista onwards) is \lstinline!C:\Users\username! \footnote{If you're not sure
	where to put \lstinline!indentconfig.yaml!, don't
	worry \lstinline!latexindent.pl! will tell you in the log file exactly where to
put it assuming it doesn't exist already.}
\Cref{lst:indentconfig} shows a sample \lstinline!indentconfig.yaml! file.

\begin{cmhlistings}[style=yaml]{\lstinline!indentconfig.yaml! (sample)}{lst:indentconfig}
# Paths to user settings for latexindent.pl
#
# Note that the settings will be read in the order you
# specify here- each successive settings file will overwrite
# the variables that you specify

paths:
- /home/cmhughes/Documents/yamlfiles/mysettings.yaml
- /home/cmhughes/folder/othersettings.yaml
- /some/other/folder/anynameyouwant.yaml
- C:\Users\chughes\Documents\mysettings.yaml
- C:\Users\chughes\Desktop\test spaces\more spaces.yaml
\end{cmhlistings}

Note that the \lstinline!.yaml! files you specify in \lstinline!indentconfig.yaml!
will be loaded in the order that you write them in. Each file doesn't have
to have every switch from \lstinline!defaultSettings.yaml!; in fact, I recommend
that you only keep the switches that you want to \emph{change} in these
settings files.

To get started with your own settings file, you might like to save a copy of
\lstinline!defaultSettings.yaml! in another directory and call it, for
example, \lstinline!mysettings.yaml!. Once you have added the path to \lstinline!indentconfig.yaml!
feel free to start changing the switches and adding more environments to it
as you see fit--have a look at \cref{lst:mysettings} for an example
that uses four tabs for the default indent, adds the \lstinline!tabbing!
environment to the list of environments that contains alignment delimiters,
and adds the changes we described on \cpageref{page:examsettings}.

\begin{cmhlistings}[style=yaml]{\lstinline!mysettings.yaml! (example)}{lst:mysettings}
# Default value of indentation
defaultIndent: "\t\t\t\t"

# environments that have tab delimiters, add more
# as needed
lookForAlignDelims:
   tabbing: 1

# If you use the exam documentclass, you might 
# like the following settings
# environments that have \item commands
indentAfterItems:
    parts: 1

# commands to be treated like \item
itemNames:
    part: 1
\end{cmhlistings}

You can make sure that your settings are loaded by checking \lstinline!indent.log!
for details--if you have specified a path that \lstinline!latexindent.pl! doesn't
recognize then you'll get a warning, otherwise you'll get confirmation that
\lstinline!latexindent.pl! has read your settings file \footnote{Windows users
	may find that they have to end \lstinline!.yaml! files with a blank line}.

\begin{warning}
	When editing \lstinline!.yaml! files it is \emph{extremely} important
	to remember how sensitive they are to spaces. I highly recommend copying
	and pasting from \lstinline!defaultSettings.yaml! when you create your
	first \lstinline!whatevernameyoulike.yaml! file.

	If \lstinline!latexindent.pl! can not read your \lstinline!.yaml! file it
	will tell you so in \lstinline!indent.log!.
\end{warning}

\subsection{\lstinline!localSettings.yaml!}\label{sec:localsettings}
You may remember on \cpageref{page:localswitch} we discussed the \lstinline!-l! switch
that tells \lstinline!latexindent.pl! to look for \lstinline!localSettings.yaml! in the
\emph{same directory} as \lstinline!myfile.tex!. This settings file will
be read \emph{after} \lstinline!defaultSettings.yaml! and, assuming they exist,
user settings.

The \emph{local} settings file may be called \lstinline!localSettings.yaml!, and
it can contain any switches that you'd
like to change--a sample is shown in \cref{lst:localSettings}.

\begin{cmhlistings}[style=yaml]{\lstinline!localSettings.yaml! (example)}{lst:localSettings}
# Default value of indentation
defaultIndent: " "

# environments that have tab delimiters, add more
# as needed
lookForAlignDelims:
   tabbing: 0

#  verbatim environments- environments specified
#  in this hash table will not be changed at all!
verbatimEnvironments:
    cmhenvironment: 0
\end{cmhlistings}

You can make sure that your local settings are loaded by checking \lstinline!indent.log!
for details--if \lstinline!localSettings.yaml! can not be read then you will
get a warning, otherwise you'll get confirmation that
\lstinline!latexindent.pl! has read \lstinline!localSettings.yaml!.

If you'd prefer to name your \lstinline!localSettings.yaml! file something different, (say, \lstinline!myyaml.yaml!) then
you can call \lstinline!latexindent.pl! using, for example, \lstinline[breaklines=true]!latexindent.pl -l=myyaml.yaml myfile.tex!.

\subsection{Settings load order}\label{sec:loadorder}
\lstinline!latexindent.pl! loads the settings files in the following order:
\begin{enumerate}
	\item \lstinline!defaultSettings.yaml! is always loaded, and can not be renamed;
	\item \lstinline!anyUserSettings.yaml! and any other arbitrarily-named files specified in \lstinline!indentconfig.yaml!;
	\item \lstinline!localSettings.yaml! but only if found in the same directory as \lstinline!myfile.tex! and called
	      with \lstinline!-l! switch; this file can be renamed, provided that the call to \lstinline!latexindent.pl! is adjusted 
          accordingly (see \cref{sec:localsettings}).
\end{enumerate}
A visual representation of this is given in \cref{fig:loadorder}.

\begin{figure}
	\centering
	\begin{tikzpicture}[
			needed/.style={very thick, draw=blue,fill=blue!20,
				text centered, minimum height=2.5em,rounded corners=1ex},
			optional/.style={draw=black, very thick,scale=0.8,
				text centered, minimum height=2.5em,rounded corners=1ex},
			optionalfill/.style={fill=black!10},
			connections/.style={draw=black!30,dotted,line width=3pt,text=red},
		]
		% Draw diagram elements
		\node (latexindent) [needed,circle]  {\lstinline!latexindent.pl!};
		\node (default) [needed,above right=.5cm of latexindent]  {\lstinline!defaultSettings.yaml!};
		\node (indentconfig) [optional,right=of latexindent]  {\lstinline!indentconfig.yaml!};
		\node (any) [optional,optionalfill,above right=of indentconfig]  {\lstinline!any.yaml!};
		\node (name) [optional,optionalfill,right=of indentconfig]  {\lstinline!name.yaml!};
		\node (you) [optional,optionalfill,below right=of indentconfig]  {\lstinline!you.yaml!};
		\node (want) [optional,optionalfill,below=of indentconfig]  {\lstinline!want.yaml!};
		\node (local) [optional,below=of latexindent]  {\lstinline!localSettings.yaml!};
		% Draw arrows between elements
		\draw[connections,solid] (latexindent) to[in=-90]node[pos=0.5,anchor=north]{1} (default.south) ;
		\draw[connections,optional] (latexindent) -- node[pos=0.5,anchor=north]{2} (indentconfig) ;
		\draw[connections,optional] (indentconfig) to[in=-90] (any.south) ;
		\draw[connections,optional] (indentconfig) -- (name) ;
		\draw[connections,optional] (indentconfig) to[out=-45,in=90] (you) ;
		\draw[connections,optional] (indentconfig) -- (want) ;
		\draw[connections,optional] (latexindent) -- node[pos=0.5,anchor=west]{3} (local) ;
	\end{tikzpicture}
	\caption{Schematic of the load order described in \cref{sec:loadorder}; solid lines represent
		mandatory files, dotted lines represent optional files. \lstinline!indentconfig.yaml! can
		contain as many files as you like--the files will be loaded in order; if you specify
	settings for the same field in more than one file, the most recent takes priority. }
	\label{fig:loadorder}
\end{figure}

\subsection{An important example}
I was working on a document that had the text shown in \cref{lst:casestudy}.
\begin{cmhlistings}[style=demo,escapeinside={(*@}{@*)}]{When to set \lstinline!alwaysLookforSplitBrackets=0!}{lst:casestudy}
Hence determine how many zeros the function $h(x)=f(x)-g(x)$
has on the interval $[0,9)$.(*@\label{line:interval1}@*)
\begin{shortsolution}
	The function $h$ has $10$ zeros on the interval $[0,9)$.(*@\label{line:interval2}@*)
\end{shortsolution}
\end{cmhlistings}
I had allowed \lstinline!alwaysLookforSplitBrackets=1!, which is the default setting.
Unfortunately, this caused undesired results, as \lstinline!latexindent.pl! thought that the opening
\lstinline![!  in the interval notation (\cref{line:interval1,line:interval2})
was an opening brace that needed to be closed (with a corresponding \lstinline!]!). Clearly
this was inappropriate, but also expected since \lstinline!latexindent.pl! was simply
following its matching rules.

In this particular instance, I set up \lstinline!localSettings.yaml!
to contain \lstinline!alwaysLookforSplitBrackets: 0! and then specified the commands
that could split brackets across lines (such as \lstinline!begin{axis}!) individually
in \lstinline!checkunmatchedbracket!.  Another option would have been to wrap the
the line in an environment from \lstinline!noIndentBlock! which treats its contents
as a verbatim environment.


\section{Known limitations}\label{sec:knownlimitations}
There are a number of known limitations of the script, and almost certainly quite a
few that are \emph{unknown}!

The main limitation is to do with the alignment routine of environments that contain
delimiters--in other words, environments that are entered in \lstinline!lookForAlignDelims!.
Indeed, this is the only part of the script that can \emph{potentially} remove
lines from \lstinline!myfile.tex!. Note that \lstinline!indent.log! will always
finish with a comparison of line counts before and after.

The routine works well for `standard' blocks of code that have the same number of \lstinline!&!
per line, but it will not do anything for lines that do not--such examples
include \lstinline!tabular! environments that use \lstinline!\multicolumn! or
perhaps spread cell contents across multiple lines.  For each alignment block (\lstinline!tabular!,
\lstinline!align!, etc) \lstinline!latexindent.pl! first of all makes a record
of the maximum number of \lstinline!&!; if each row does not have that
number of \lstinline!&! then it will not try to format that row. Details
will be given in \lstinline!indent.log! assuming that \lstinline!trace! mode
is active.

If you have a \lstinline!verbatim!-like environment inside a \lstinline!tabular!-like
environment, the \lstinline!verbatim! environment \emph{will} be formatted, which
is probably not what you want. I hope to address this in future versions, but for the
moment wrap it in a \lstinline!noIndentBlock! (see \cpageref{lst:noIndentBlockdemo}).

You can run \lstinline!latexindent! on \lstinline!.sty!, \lstinline!.cls! and any filetypes
that you specify in \lstinline[breaklines=true]!fileExtensionPreference! (see \vref{lst:fileExtensionPreference}); 
if you find a case in which the script struggles, please feel free
to report it at \cite{latexindent-home}, and
in the meantime, consider using a \lstinline!noIndentBlock! (see \cpageref{lst:noIndentBlockdemo}).

I hope that this script is useful to some; if you find an example where the
script does not behave as you think it should, the best way to contact me is to
report an issue on \cite{latexindent-home}; otherwise, feel free to find me on 
the \url{http://tex.stackexchange.com} site; I'm often around
and in the chat room.

\nocite{*}
\section{References}
\printbibliography[heading=subbibnumbered,title={External links},notkeyword=contributor]
\printbibliography[env=specialbib,heading=subbibnumbered,title={Contributors\label{sec:contributors}},keyword=contributor]

\appendix
\section{Required \lstinline!Perl! modules}\label{sec:requiredmodules}
If you intend to use \lstinline!latexindent.pl! and \emph{not} one of the supplied standalone executable files, then you will need a few standard Perl modules--if you can run the
minimum code in \cref{lst:helloworld} (\lstinline!perl helloworld.pl!) then you will be able to run \lstinline!latexindent.pl!, otherwise you may
need to install the missing modules.

\begin{cmhlistings}[language=Perl]{\lstinline!helloworld.pl!}{lst:helloworld}
#!/usr/bin/perl

use strict;
use warnings;
use FindBin;
use YAML::Tiny;
use File::Copy;
use File::Basename;
use Getopt::Long;
use File::HomeDir;

print "hello world";
exit;
\end{cmhlistings}
My default installation on Ubuntu 12.04 did \emph{not} come
with all of these modules as standard, but Strawberry Perl for Windows \cite{strawberryperl}
did.

Installing the modules given in \cref{lst:helloworld} will vary depending on your
operating system and \lstinline!Perl! distribution. For example, Ubuntu users
might visit the software center, or else run
\begin{lstlisting}[numbers=none]
sudo perl -MCPAN -e 'install "File::HomeDir"'
\end{lstlisting}

Linux users may be interested in exploring Perlbrew \cite{perlbrew}; possible installation and setup 
options follow for Ubuntu (other distributions will need slightly different commands).
\begin{lstlisting}[numbers=none]
sudo apt-get install perlbrew
perlbrew install perl-5.20.1
perlbrew switch perl-5.20.1
sudo apt-get install curl
curl -L http://cpanmin.us | perl - App::cpanminus
cpanm YAML::Tiny
cpanm File::HomeDir
\end{lstlisting}

Strawberry Perl users on Windows might use
\lstinline!CPAN client!. All of the modules are readily available on CPAN \cite{cpan}.

As of Version 2.1,  \lstinline!indent.log! will contain details of the location
of the Perl modules on your system.  \lstinline!latexindent.exe! is a standalone
executable for Windows (and therefore does not require a Perl distribution) and caches copies of the Perl modules onto your system; if you
wish to see where they are cached, use the  \lstinline!trace! option, e.g  \lstinline!latexindent.exe -t myfile.tex!.

\section{The \lstinline!arara! rule}
The \lstinline!arara! rule (\lstinline!indent.yaml!) contains lines such as those
given in \cref{lst:arararule}. With this setup, the user \emph{always} has
to specify whether or not they want (in this example) to use the \lstinline!trace!
identifier.
\begin{cmhlistings}[style=yaml,numbers=none]{The \lstinline!arara! rule}{lst:arararule}
...
arguments:
- identifier: trace
  flag: <arara> @{ isTrue( parameters.trace, "-t" ) }
...
\end{cmhlistings}

If you would like to have the \lstinline!trace! option on by default every time you
call \lstinline!latexindent.pl! from \lstinline!arara! (without having to write \lstinline!% arara: indent: {trace: yes}!), then simply
amend \cref{lst:arararule} so that it looks like \cref{lst:arararulemod}.
\begin{cmhlistings}[style=yaml,numbers=none]{The \lstinline!arara! rule (modified)}{lst:arararulemod}
...
arguments:
- identifier: trace
  flag: <arara> @{ isTrue( parameters.trace, "-t" ) }
  default: "-t"
...
\end{cmhlistings}

With this modification in place, you now simply to write \lstinline!% arara: indent! and
\lstinline!trace! mode will be activated by default. If you wish to turn off \lstinline!trace!
mode then you can write \lstinline!% arara: indent: {trace: off}!.

Of course, you can apply these types of modifications to \emph{any} of the identifiers,
but proceed with caution if you intend to do this for \lstinline!overwrite!.

\section{Updating the \lstinline!path! variable}\label{sec:updating-path}
\lstinline!latexindent.pl! ships with a few scripts that can update the \lstinline!path! variables
\footnote{Thanks to \cite{jasjuang} for this feature!}. If you're
on a Linux or Mac machine, then you'll want \lstinline!CMakeLists.txt! from \cite{latexindent-home}.
\subsection{Add to path for Linux}
To add \lstinline!latexindent.pl! to the path for Linux, follow these steps:
\begin{enumerate}
	\item download  \lstinline!latexindent.pl!, \lstinline!defaultSettings.yaml!,  to your
      chosen directory from \cite{latexindent-home} ; 
    \item within your directory, create a directory called \lstinline!path-helper-files! and 
      download \lstinline!CMakeLists.txt! and \lstinline!cmake_uninstall.cmake.in!
	      from \cite{latexindent-home}/path-helper-files to this directory;
	\item run \lstinline!ls /usr/local/bin! to see what is \emph{currently} in there;
	\item run the commands given in \cref{linux-add-to-path};
	\item run \lstinline!ls /usr/local/bin! again to check that \lstinline!latexindent.pl! and \lstinline!defaultSettings.yaml!
	      have been added.
\end{enumerate}
\begin{cmhlistings}[style=yaml,numbers=none]{Add to path from a Linux terminal}{linux-add-to-path}
sudo apt-get install cmake
sudo apt-get update && sudo apt-get install build-essential
mkdir build && cd build
cmake ../path-helper-files
sudo make install
\end{cmhlistings}
To \emph{remove} the files, run \lstinline!sudo make uninstall!.
\subsection{Add to path for Windows}
To add \lstinline!latexindent.exe! to the path for Windows, follow these steps:
\begin{enumerate}
	\item download  \lstinline!latexindent.exe!, \lstinline!defaultSettings.yaml!,  \lstinline!add-to-path.bat!
	      from \cite{latexindent-home} to your chosen directory;
	\item open a command prompt and run \lstinline!echo %path%! to see what is \emph{currently} in your \lstinline!%path%! variable;
	\item right click on \lstinline!add-to-path.bat! and \emph{Run as administrator};
	\item log out, and log back in;
	\item open a command prompt and run \lstinline!echo %path%! to check that the appropriate directory has been added to your
	      \lstinline!%path%!.
\end{enumerate}
To \emph{remove} the directory from your \lstinline!%path%!, run \lstinline!remove-from-path.bat! as administrator.
\end{document}