latexindent (22aug17)

git-svn-id: svn://tug.org/texlive/trunk@45098 c570f23f-e606-0410-a88d-b1316a301751

34 files changed, 1261 insertions, 570 deletions

diff --git a/Master/texmf-dist/doc/support/latexindent/README b/Master/texmf-dist/doc/support/latexindent/README
index 6d1a3beb2dc..563595d2a5a 100644
--- a/Master/texmf-dist/doc/support/latexindent/README
+++ b/Master/texmf-dist/doc/support/latexindent/README
@@ -1,5 +1,5 @@
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-    latexindent.pl, version 3.2.2, 2017-06-28
+    latexindent.pl, version 3.3, 2017-08-21
 
     PERL script to indent code within environments, and align delimited 
     environments in .tex files.
diff --git a/Master/texmf-dist/doc/support/latexindent/appendices.tex b/Master/texmf-dist/doc/support/latexindent/appendices.tex
index 63a2b680394..1f6f1465e17 100644
--- a/Master/texmf-dist/doc/support/latexindent/appendices.tex
+++ b/Master/texmf-dist/doc/support/latexindent/appendices.tex
@@ -15,6 +15,7 @@ use PerlIO::encoding;
 use Unicode::GCString;
 use open ':std', ':encoding(UTF-8)';
 use Text::Wrap;
+use Text::Tabs;
 use FindBin;
 use YAML::Tiny;
 use File::Copy;
diff --git a/Master/texmf-dist/doc/support/latexindent/latexindent.pdf b/Master/texmf-dist/doc/support/latexindent/latexindent.pdf
index 3a475cd1f26..49539762cc9 100644
--- a/Master/texmf-dist/doc/support/latexindent/latexindent.pdf
+++ b/Master/texmf-dist/doc/support/latexindent/latexindent.pdf
diff --git a/Master/texmf-dist/doc/support/latexindent/latexindent.tex b/Master/texmf-dist/doc/support/latexindent/latexindent.tex
index 4adddf3007f..ae47b9fdeb4 100644
--- a/Master/texmf-dist/doc/support/latexindent/latexindent.tex
+++ b/Master/texmf-dist/doc/support/latexindent/latexindent.tex
@@ -38,6 +38,7 @@
 \usepackage{enumitem}                                % custom lists
 \usepackage{longtable}
 \usepackage{array}
+\usepackage{totalcount}
 % setup gitinfo2, as in the manual, details just above begin{document}
 \usepackage[mark,grumpy]{gitinfo2}
 % tikz, tcolorbox libraries
@@ -45,7 +46,7 @@
 \usetikzlibrary{decorations.pathmorphing}
 \usetikzlibrary{decorations,shapes}
 \usepackage{varioref}                                % the documentation library from tcolorbox loads hyperref
-\tcbuselibrary{breakable,minted,xparse,documentation}
+\tcbuselibrary{breakable,minted,xparse,documentation,hooks}
 \hypersetup{
 	pdfauthor={Chris Hughes},
 	pdftitle={latexindent.pl package},
@@ -59,17 +60,53 @@
 }
 \usepackage{cleveref}
 
+% create my own star style, for re-use at various points
+\tikzset{cmhstar/.style={star,star point ratio=2.25,fill=cmhgold,draw=orange,}}
+
+% shortcut command for displaying star in documentation
+\newcommand{\stardemo}[1][]{\begin{tikzpicture}
+	\node at (10:.1cm)[very thin,cmhstar,scale=0.25,rotate=20,#1]{};
+	\node at (120:.1cm)[very thin,cmhstar,scale=0.15,rotate=-10,#1]{};
+	\node at (235:.1cm)[very thin,cmhstar,scale=0.2,rotate=-20,#1]{};
+	\end{tikzpicture}}
+
+% totalcount
+\DeclareTotalCounter{lstlisting}
+
 % customise the \tcbdocnew command
 \tcbset{doclang/new={{\bfseries\color{green!50!black}N\normalfont\color{black}}}}
+\tcbset{doclang/updated={{\bfseries\color{green!50!black}U\normalfont\color{black}}}}
 \tcbset{doc marginnote={width=1.6cm}}
-%\newcommand{\announce}[1]{\tcbdocmarginnote{\tcbdocnew{#1}}}
-\NewDocumentCommand{\announce}{ s m }{%
-	\IfBooleanTF{#1}
+\NewDocumentCommand{\announce}{ s m s m }{%
+	\IfBooleanTF{#1}%
 	{% \announce*
-		\tcbdocmarginnote[overlay={\node[anchor=north east,text=cmhgold] at ([yshift=3mm,xshift=4mm]frame.north east) {$\bigstar$}; }]{\tcbdocnew{#2}}
-	}
+		\tcbdocmarginnote[overlay={\node at ([yshift=0mm,xshift=1mm]frame.north east) {\stardemo}; }]{%
+			\IfBooleanTF{#3}%
+			{% \announce*{date}*[text] means *updated* as of <date>
+				\tcbdocupdated{#2}%
+			}%
+			{% \announce*{date}[text] means *new* as of <date>
+				\tcbdocnew{#2}%
+			}%
+		}%
+		\IfBooleanTF{#3}%
+		{%
+			\addcontentsline{new}{cmhtitle}{#4 (U)}%
+		}%
+		{%
+			\addcontentsline{new}{cmhtitle}{#4 (N)}%
+		}%
+	}%
 	{% \announce
-		\tcbdocmarginnote{\tcbdocnew{#2}}
+		\tcbdocmarginnote{%
+			\IfBooleanTF{#3}%
+			{% \announce{date}*[text] means *updated* as of <date>
+				\tcbdocupdated{#2}%
+			}%
+			{% \announce{date}[text] means *new* as of <date>
+				\tcbdocnew{#2}%
+			}%
+		}%
 	}}
 
 \reversemarginpar
@@ -87,6 +124,7 @@
 \makeatletter
 \tcbset{
 	addtolol/.style={list entry={\kvtcb@title},add to list={lol}{lstlisting}},
+	addtololstar/.style={list entry={\kvtcb@title},add to list={lol}{lstlistingstar}},
 	cmhlistings/.style={
 			%	width=\linewidth,
 			%breakable,
@@ -100,7 +138,6 @@
 			listing engine=minted,
 			minted style=colorful,
 			minted options={obeytabs=true,showtabs=true,tabsize=4,showspaces=true},
-			addtolol,
 			boxrule=0pt,
 			toprule=1pt,bottomrule=1pt,
 			titlerule=1pt,
@@ -136,27 +173,56 @@
 			%bottomrule=1pt,
 			enhanced,
 			overlay={\node[anchor=north east,outer sep=2pt,draw=cmhgold,very thick,double,fill=harvestgold,font =\small] at ([yshift=-3mm]frame.north east) {\texttt{-m}}; }
-		}
+		},
+	new-to-this-version/.style={
+			enhanced,
+			overlay app={\node at ([yshift=0mm,xshift=0mm]frame.north east) {\stardemo[scale=1.2]}; },
+			addtololstar,
+		},
 }
 
 \newtcblisting[use counter=lstlisting]{cmhlistings}[3][]{%
 	cmhlistings,
+	addtolol,
 	center title,
 	title={\color{black}{\scshape Listing \thetcbcounter}: ~#2},label={#3},
 	listing engine=listings,
 	listing options={#1},
 }
 
-% \cmhlistingsfromfile uses listings library
-% \cmhlistingsfromfile* uses minted library
-\DeclareTCBInputListing[use counter=lstlisting]{\cmhlistingsfromfile}{s O{} m O{} m m}{%
+% \cmhlistingsfromfile
+%                   *    no star: not new, star: new
+%                   [ listing/minted options ]
+%                   *    no star: uses listings library star: uses minted library
+%                   {<name of listing file>}
+%                   [<options for tcolorbox>]
+%                   {<title>}
+%                   {<label>}
+%
+% for example,
+%   \cmhlistingsfromfile*[listing options]...  uses listings library and is NEW
+%   \cmhlistingsfromfile[listing options]...   uses listings library
+%   \cmhlistingsfromfile[listing options]*...  uses minted library
+%   \cmhlistingsfromfile*[listing options]*... uses minted library and is NEW
+\DeclareTCBInputListing[use counter=lstlisting]{\cmhlistingsfromfile}{s O{} s m O{} m m}{%
 	cmhlistings,
-	listing file={#3},
-	IfBooleanTF={#1}{minted options={obeytabs=true,showtabs=true,tabsize=4,showspaces=false,#2}}{listing options={#2}},
-	title={\color{black}{\scshape Listing \thetcbcounter}: ~#5},label={#6},
-	#4,
+	listing file={#4},
+	IfBooleanTF={#3}{minted options={obeytabs=true,showtabs=true,tabsize=4,showspaces=false,#2}}{listing options={#2}},
+	title={\color{black}{\scshape Listing \thetcbcounter}: ~#6},label={#7},
+	#5,
+	IfBooleanTF={#1}{new-to-this-version}{addtolol},
 }
 
+\makeatletter
+\@tempswafalse
+\def\@tempa{draft}
+\@for\next:=\@classoptionslist\do
+{\ifx\next\@tempa\@tempswatrue\fi}
+\if@tempswa % draft option is active
+	\RenewDocumentCommand{\cmhlistingsfromfile}{s O{} s m O{} m m}{\captionof{lstlisting}{#6}\label{#7}}
+	\renewcommand{\stardemo}[1][]{$\star$}
+\fi
+
 % command shell
 \newtcblisting{commandshell}{colback=black,colupper=white,colframe=yellow!75!black,
 	listing only,listing options={style=tcblatex,language=sh,
@@ -277,79 +343,79 @@
 
 \lstdefinestyle{specialBeginEnd}{
 	style=yaml-LST,
-	firstnumber=190,linerange={190-202},
+	firstnumber=190,linerange={190-203},
 	numbers=left,
 }
 
 \lstdefinestyle{indentAfterHeadings}{
 	style=yaml-LST,
-	firstnumber=212,linerange={212-221},
+	firstnumber=213,linerange={213-222},
 	numbers=left,
 }
 
 \lstdefinestyle{noAdditionalIndentGlobalEnv}{
 	style=yaml-LST,
-	firstnumber=267,linerange={267-268},
+	firstnumber=271,linerange={271-272},
 	numbers=left,
 }
 
 \lstdefinestyle{noAdditionalIndentGlobal}{
 	style=yaml-LST,
-	firstnumber=267,linerange={267-279},
+	firstnumber=271,linerange={271-283},
 	numbers=left,
 }
 
 \lstdefinestyle{indentRulesGlobalEnv}{
 	style=yaml-LST,
-	firstnumber=283,linerange={283-284},
+	firstnumber=287,linerange={287-288},
 	numbers=left,
 }
 
 \lstdefinestyle{indentRulesGlobal}{
 	style=yaml-LST,
-	firstnumber=283,linerange={283-295},
+	firstnumber=287,linerange={287-299},
 	numbers=left,
 }
 
 \lstdefinestyle{commandCodeBlocks}{
 	style=yaml-LST,
-	firstnumber=298,linerange={298-306},
+	firstnumber=302,linerange={302-312},
 	numbers=left,
 }
 
 \lstdefinestyle{modifylinebreaks}{
 	style=yaml-LST,
-	firstnumber=376,linerange={376-378},
+	firstnumber=382,linerange={382-384},
 	numbers=left,
 }
 
 \lstdefinestyle{textWrapOptions}{
 	style=yaml-LST,
-	firstnumber=379,linerange={379-380},
+	firstnumber=385,linerange={385-386},
 	numbers=left,
 }
 
 \lstdefinestyle{textWrapOptionsAll}{
 	style=yaml-LST,
-	firstnumber=379,linerange={379-381},
+	firstnumber=385,linerange={385-387},
 	numbers=left,
 }
 
 \lstdefinestyle{removeParagraphLineBreaks}{
 	style=yaml-LST,
-	firstnumber=382,linerange={382-394},
+	firstnumber=388,linerange={388-400},
 	numbers=left,
 }
 
 \lstdefinestyle{paragraphsStopAt}{
 	style=yaml-LST,
-	firstnumber=395,linerange={395-403},
+	firstnumber=401,linerange={401-409},
 	numbers=left,
 }
 
 \lstdefinestyle{modifylinebreaksEnv}{
 	style=yaml-LST,
-	firstnumber=404,linerange={404-413},
+	firstnumber=410,linerange={410-419},
 	numbers=left,
 }
 
@@ -464,10 +530,18 @@
 
 % list of listings
 \contentsuse{lstlisting}{lol}
-\titlecontents{lstlisting}[2em]
+\titleclass{\lstlistingstar}{straight}[\section]
+\titleformat{\lstlistingstar}{}{}{}{}
+\titlecontents{lstlistingstar}[2em]
   {\addvspace{0.25pc}}
-  {\textbf{Code \thecontentslabel} }
   {}
+  {\llap{\stardemo}\thecontentslabel}
+  {\titlerule*[0.5em]{$\cdot$}\contentspage}
+  []
+\titlecontents{lstlisting}[2em]
+  {\addvspace{0.25pc}}
+  {\thecontentslabel}
+  {\thecontentslabel}
   {\titlerule*[0.5em]{$\cdot$}\contentspage}
   []
 \AtBeginDocument{\addtocontents{lol}{\protect\begin{widepage}\protect\begin{multicols}{2}}}
@@ -514,7 +588,7 @@
 % table rules
 \setlength\heavyrulewidth{0.25ex}
 % gitinfo2 settings
-\renewcommand{\gitMark}{\gitBranch\,@\,\gitAbbrevHash{}\,\textbullet{}\,\gitAuthorDate\,\textbullet{}\faGithub}
+\renewcommand{\gitMark}{\gitBranch\,@\,\gitAbbrevHash{}\,\textbullet{}\,\gitAuthorDate\,\textbullet{}\faGithub\,\textbullet{}\gitRel}
 
 % setting up gitinfo2:
 %   copy the file post-xxx-sample.txt from http://mirror.ctan.org/macros/latex/contrib/gitinfo2
@@ -539,6 +613,22 @@
 % suitably define the command
 \DeclareTextCommand{\textasteriskcentered}{OT1}{\raisebox{-.7ex}[1ex][0pt]{*}}
 
+% new features list
+\newcommand{\listOfNewFeatures}{\setcounter{tocdepth}{4}\@starttoc{new}}
+\contentsuse{cmhtitle}{new}
+% toc settings
+\titleclass{\cmhtitle}{straight}[\subsection]
+\titleformat{\cmhtitle}{}{}{}{}
+\titlecontents*{cmhtitle}% <paragaph>
+[3cm]% <left>
+{\small\itshape}% <above-code>
+{}% <numbered-entry-format>; you could also use {\thecontentslabel. } to show the numbers
+{}% <numberless-entry-format>
+{\ \thecontentspage}% <filler-page-format>
+[,\ ]% <separator>
+[]% <end>
+
+\setcounter{secnumdepth}{5}
 \begin{document}
 \renewcommand*{\thefootnote}{\arabic{footnote}}
 \input{title.tex}
@@ -609,3 +699,11 @@ Ver­sion 3.2
 im­ple­ments a new fea­ture called 'mul­ti­Colum­nGroup­ing' which gives a new op­tion for the align­ment-at-am­per­sands rou­tine.
 More de­tails are given at
 https://github.com/cmhughes/la­texin­dent.pl/pull/67
+
+Version 3.2.1
+Upgrades to the -o and -l switches
+https://github.com/cmhughes/latexindent.pl/pull/71
+
+Version 3.2.2
+Users can specify removeTrailingWhitespace as a scalar, for example,  removeTrailingWhitespace: 0
+https://github.com/cmhughes/latexindent.pl/pull/72
diff --git a/Master/texmf-dist/doc/support/latexindent/sec-conclusions-know-limitations.tex b/Master/texmf-dist/doc/support/latexindent/sec-conclusions-know-limitations.tex
index 4f9053b9717..1b97f41128d 100644
--- a/Master/texmf-dist/doc/support/latexindent/sec-conclusions-know-limitations.tex
+++ b/Master/texmf-dist/doc/support/latexindent/sec-conclusions-know-limitations.tex
@@ -3,28 +3,11 @@
  There are a number of known limitations of the script, and almost certainly quite a
  few that are \emph{unknown}!
 
- For example, \texttt{latexindent.pl} will not indent the following code correctly,
- because of the unmatched \lstinline![!. I'm hopeful to be able to resolve this
- issue in a future version.
-
- \begin{lstlisting}[,nolol=true,]
-\parbox{
-\@ifnextchar[{\@assignmentwithcutoff}{\@assignmentnocutoff}
-}
-\end{lstlisting}
-
- The main other limitation is to do with the alignment routine of environments/commands that contain
- delimiters which are specified in \texttt{lookForAlignDelims}.
-
- 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 \texttt{tabular} environments that use \lstinline!\multicolumn! or
- perhaps spread cell contents across multiple lines.  For each alignment block (\texttt{tabular},
- \texttt{align}, etc) \texttt{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 \texttt{indent.log} assuming that \texttt{trace} mode
- is active.
+ The main limitation is to do with efficiency, particularly when the \texttt{-m}
+ switch is active, as this adds many checks and processes. The current implementation
+ relies upon finding and storing \emph{every} code block (see the discussion on \cpageref{page:phases});
+ it is hoped that, in a future version, only \emph{nested} code blocks will need
+ to be stored in the `packing' phase, and that this will improve the efficiency of the script.
 
  You can run \texttt{latexindent} on \texttt{.sty}, \texttt{.cls} and any file types
  that you specify in \lstinline[breaklines=true]!fileExtensionPreference! (see \vref{lst:fileExtensionPreference});
diff --git a/Master/texmf-dist/doc/support/latexindent/sec-default-user-local.tex b/Master/texmf-dist/doc/support/latexindent/sec-default-user-local.tex
index af43a9e56de..e1a3f0d09c7 100644
--- a/Master/texmf-dist/doc/support/latexindent/sec-default-user-local.tex
+++ b/Master/texmf-dist/doc/support/latexindent/sec-default-user-local.tex
@@ -100,6 +100,7 @@ copy myfile.bak4 to myfile.bak3
 	\begin{minipage}{.45\textwidth}
 		\cmhlistingsfromfile[style=verbatimEnvironments]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{verbatimEnvironments}}{lst:verbatimEnvironments}
 	\end{minipage}%
+	\hfill
 	\begin{minipage}{.45\textwidth}
 		\cmhlistingsfromfile[style=verbatimCommands]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{verbatimCommands}}{lst:verbatimCommands}
 	\end{minipage}%
@@ -154,7 +155,7 @@ removeTrailingWhitespace: 1
 	for before and after results.  Thanks to \cite{vosskuhle} for providing this feature.
 
 	You can specify \texttt{removeTrailingWhitespace} simply as \texttt{0} or \texttt{1}, if you wish; in this case,
-	\announce*{2017-06-28}
+	\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}
@@ -231,11 +232,11 @@ lookForAlignDelims:
 	instances of the environment, you could wrap them in something from \texttt{noIndentBlock} (see \vref{lst:noIndentBlock}).
 
 	\begin{minipage}{.45\textwidth}
-		\cmhlistingsfromfile*[showspaces=false,showtabs=false]{demonstrations/tabular1.tex}{\texttt{tabular1.tex}}{lst:tabularbefore:basic}
+		\cmhlistingsfromfile[showspaces=false,showtabs=false]*{demonstrations/tabular1.tex}{\texttt{tabular1.tex}}{lst:tabularbefore:basic}
 	\end{minipage}%
 	\hfill
 	\begin{minipage}{.45\textwidth}
-		\cmhlistingsfromfile*[showspaces=false,showtabs=false]{demonstrations/tabular1-default.tex}{\texttt{tabular1.tex} default output}{lst:tabularafter:basic}
+		\cmhlistingsfromfile[showspaces=false,showtabs=false]*{demonstrations/tabular1-default.tex}{\texttt{tabular1.tex} default output}{lst:tabularafter:basic}
 	\end{minipage}%
 
 	If you wish to remove the alignment of the \lstinline!\\! within a delimiter-aligned block, then the
@@ -253,9 +254,9 @@ lookForAlignDelims:
 		\item \texttt{spacesBeforeDoubleBackSlash}: optionally, specifies the number of spaces to be inserted
 		      before (non-aligned) \lstinline!\\!. In order to use this field, \texttt{alignDoubleBackSlash} needs
 		      to be set to 0 (default: 0).
-		\item \announce{2017-06-19} \texttt{multiColumnGrouping}: details if \texttt{latexindent.pl} should group columns
+		\item \announce{2017-06-19}{multiColumnGrouping} \texttt{multiColumnGrouping}: details if \texttt{latexindent.pl} should group columns
 		      underneath a \lstinline!\multicolumn! command (default: 0);
-		\item \announce{2017-06-19} \texttt{alignRowsWithoutMaxDelims}: details if rows that do not contain the
+		\item \announce{2017-06-19}{alignRowsWithoutMaxDelims} \texttt{alignRowsWithoutMaxDelims}: details if rows that do not contain the
 		      maximum number of delimeters should be formatted so as to have the ampersands aligned (default: 1).
 	\end{itemize}
 
@@ -269,11 +270,11 @@ latexindent.pl -l tabular.yaml tabular1.tex
 	the \lstinline!\\! have not (compare the alignment of \lstinline!\\! in \cref{lst:tabularafter:basic,lst:tabularafter:advanced}).
 
 	\begin{minipage}{.45\textwidth}
-		\cmhlistingsfromfile*[showspaces=false,showtabs=false]{demonstrations/tabular1.tex}{\texttt{tabular1.tex}}{lst:tabularbefore:advanced}
+		\cmhlistingsfromfile[showspaces=false,showtabs=false]*{demonstrations/tabular1.tex}{\texttt{tabular1.tex}}{lst:tabularbefore:advanced}
 	\end{minipage}%
 	\hfill
 	\begin{minipage}{.45\textwidth}
-		\cmhlistingsfromfile*[showspaces=false,showtabs=false]{demonstrations/tabular1-advanced.tex}{\texttt{tabular1.tex} using \cref{lst:aligndelims:advanced}}{lst:tabularafter:advanced}
+		\cmhlistingsfromfile[showspaces=false,showtabs=false]*{demonstrations/tabular1-advanced.tex}{\texttt{tabular1.tex} using \cref{lst:aligndelims:advanced}}{lst:tabularafter:advanced}
 	\end{minipage}%
 
 	Saving \cref{lst:aligndelims:advanced} into \texttt{tabular1.yaml} as in \cref{lst:tabular1YAML}, and running the command
@@ -283,7 +284,7 @@ latexindent.pl -l tabular1.yaml tabular1.tex
 	gives \cref{lst:tabularafter:spacing}; note the spacing before the \lstinline!\\!.
 
 	\begin{minipage}{.45\textwidth}
-		\cmhlistingsfromfile*[showspaces=false,showtabs=false]{demonstrations/tabular1-advanced-3spaces.tex}{\texttt{tabular1.tex} using \cref{lst:tabular1YAML}}{lst:tabularafter:spacing}
+		\cmhlistingsfromfile[showspaces=false,showtabs=false]*{demonstrations/tabular1-advanced-3spaces.tex}{\texttt{tabular1.tex} using \cref{lst:tabular1YAML}}{lst:tabularafter:spacing}
 	\end{minipage}%
 	\hfill
 	\begin{minipage}{.54\textwidth}
@@ -293,7 +294,7 @@ latexindent.pl -l tabular1.yaml tabular1.tex
 	Now consider the file \texttt{tabular2.tex} in \cref{lst:tabular2}, which contains a \lstinline!\multicolumn! command, and
 	the YAML files in \cref{lst:tabular2YAML,lst:tabular3YAML}.
 
-	\cmhlistingsfromfile*[showspaces=false,showtabs=false]{demonstrations/tabular2.tex}{\texttt{tabular2.tex}}{lst:tabular2}
+	\cmhlistingsfromfile[showspaces=false,showtabs=false]*{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}%
@@ -311,9 +312,9 @@ latexindent.pl -s tabular2.tex -l tabular3.yaml
 	we obtain the respective outputs given in \cref{lst:tabular2-default,lst:tabular2-mc,lst:tabular2-no-max}.
 
 	\begin{widepage}
-		\cmhlistingsfromfile*[showspaces=false,showtabs=false]{demonstrations/tabular2-default.tex}{\texttt{tabular2-default.tex}}{lst:tabular2-default}
-		\cmhlistingsfromfile*[showspaces=false,showtabs=false]{demonstrations/tabular2-mc.tex}{\texttt{tabular2-mc.tex}}{lst:tabular2-mc}
-		\cmhlistingsfromfile*[showspaces=false,showtabs=false]{demonstrations/tabular2-no-max.tex}{\texttt{tabular2-no-max.tex}}{lst:tabular2-no-max}
+		\cmhlistingsfromfile[showspaces=false,showtabs=false]*{demonstrations/tabular2-default.tex}{\texttt{tabular2-default.tex}}{lst:tabular2-default}
+		\cmhlistingsfromfile[showspaces=false,showtabs=false]*{demonstrations/tabular2-mc.tex}{\texttt{tabular2-mc.tex}}{lst:tabular2-mc}
+		\cmhlistingsfromfile[showspaces=false,showtabs=false]*{demonstrations/tabular2-no-max.tex}{\texttt{tabular2-no-max.tex}}{lst:tabular2-no-max}
 	\end{widepage}
 
 	Notice in particular:
@@ -394,11 +395,12 @@ latexindent.pl matrix1.tex
 	and \vref{lst:mysettings} \\ in particular \label{page:examsettings}.)
 
 \yamltitle{specialBeginEnd}*{fields}\label{yaml:specialBeginEnd}
-	The fields specified in \texttt{specialBeginEnd} are, in their default state, focused on math mode begin and end statements, but
+	The fields specified%
+	\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}.
 
-	\cmhlistingsfromfile[style=specialBeginEnd]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{specialBeginEnd}}{lst:specialBeginEnd}
+	\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,
@@ -419,6 +421,47 @@ latexindent.pl matrix1.tex
 	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}
+
+	\begin{minipage}{.49\linewidth}
+		\cmhlistingsfromfile*{demonstrations/specialsLeftRight.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{specialsLeftRight.yaml}}{lst:specialsLeftRight-yaml}
+	\end{minipage}
+	\hfill
+	\begin{minipage}{.49\linewidth}
+		\cmhlistingsfromfile*{demonstrations/specialBeforeCommand.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{specialBeforeCommand.yaml}}{lst:specialBeforeCommand-yaml}
+	\end{minipage}
+
+	Upon running the following commands
+	\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}
+
 \yamltitle{indentAfterHeadings}*{fields}
 	\begin{wrapfigure}[17]{r}[0pt]{8cm}
 		\cmhlistingsfromfile[style=indentAfterHeadings]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{indentAfterHeadings}}{lst:indentAfterHeadings}
@@ -473,73 +516,117 @@ latexindent.pl headings1.tex -l=headings1.yaml
 	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.
 
+\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{minipage}{.45\textwidth}
+		\cmhlistingsfromfile*{demonstrations/mult-nested.tex}{\texttt{mult-nested.tex}}{lst:mult-nested}
+	\end{minipage}%
+	\hfill
+	\begin{minipage}{.45\textwidth}
+		\cmhlistingsfromfile*{demonstrations/mult-nested-default.tex}{\texttt{mult-nested.tex} default output}{lst:mult-nested-default}
+	\end{minipage}
+
+	Now say that, for example, you have the \texttt{max-indentation1.yaml} from \cref{lst:max-indentation1yaml} and
+	that you run the following command:
+	\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{minipage}{.45\textwidth}
+		\cmhlistingsfromfile*[style=yaml-LST]{demonstrations/max-indentation1.yaml}[yaml-TCB]{\texttt{max-indentation1.yaml}}{lst:max-indentation1yaml}
+	\end{minipage}%
+	\hfill
+	\begin{minipage}{.45\textwidth}
+		\cmhlistingsfromfile*{demonstrations/mult-nested-max-ind1.tex}{\texttt{mult-nested.tex} using \cref{lst:max-indentation1yaml}}{lst:mult-nested-max-ind1}
+	\end{minipage}
+
+	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 \texttt{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}.
 
-	\begin{longtable}{m{.3\linewidth}@{\hspace{.25cm}}m{.4\linewidth}@{}m{.2\linewidth}}
-		\caption{Code blocks known to \texttt{latexindent.pl}}\label{tab:code-blocks}                                                                                                                                                                                                                                                                                                                \\
-		\toprule
-		Code block                    & characters allowed in name                                                                                     & example                                                                                                                                                                                                                                     \\
-		\midrule
-		environments                  & \lstinline!a-zA-Z@\*0-9_\\!                                                                                        &
-		\begin{lstlisting}[,nolol=true,]
+	\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,]
+				\\\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,]
+				\\\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!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,]
+				\\\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!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,]
+				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,]
+				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,]
+				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,]
+				filecontents                  & User specified, see \vref{lst:fileContentsEnvironments}                                                        &
+				\begin{lstlisting}[,nolol=true,]
 \begin{filecontents}
 ...
 \end{filecontents}
   \end{lstlisting}                                                                                                                                                                                                                                                                                                                                                                      \\
-		\bottomrule
-	\end{longtable}
+				\bottomrule
+			\end{tabular}
+		\end{widepage}
+	\end{table}
 
 	We will refer to these code blocks in what follows.
diff --git a/Master/texmf-dist/doc/support/latexindent/sec-how-to-use.tex b/Master/texmf-dist/doc/support/latexindent/sec-how-to-use.tex
index 993e63662d5..81364b18cf9 100644
--- a/Master/texmf-dist/doc/support/latexindent/sec-how-to-use.tex
+++ b/Master/texmf-dist/doc/support/latexindent/sec-how-to-use.tex
@@ -21,12 +21,6 @@
  If you plan to use \texttt{latexindent.pl} (i.e, the original Perl script) then you will
  need a few standard Perl modules -- see \vref{sec:requiredmodules} for details.
 
- As you read through this documentation, you'll occasionally see dates shown in the margin
- (for example, next to this paragraph!)
- \announce{2017-06-25} which detail the date of the version in which the feature was implemented;
- the `N' stands for `new as of the date shown'. If you see a $\color{cmhgold}\bigstar$, it
- means that the feature is new as of the release of the current version.
-
 \subsection{From the command line}\label{sec:commandline}
 	\texttt{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.
@@ -45,7 +39,7 @@ latexindent.pl
 	and available options.
 
 \flagbox{-v, --version}
-	\announce{2017-06-25}
+	\announce{2017-06-25}{version}
 	\begin{commandshell}
 latexindent.pl -v
       \end{commandshell}
@@ -103,7 +97,7 @@ latexindent.pl myfile.tex > output.tex
 \end{commandshell}
 
 	You can call the \texttt{-o} switch with the name of the output file \emph{without} an extension; in
-	\announce{2017-06-25}
+	\announce{2017-06-25}{upgrade to -o switch}
 	this case, \texttt{latexindent.pl} will use the extension from the original file. For example,
 	the following two calls to \texttt{latexindent.pl} are equivalent:
 	\begin{commandshell}
@@ -112,7 +106,7 @@ latexindent.pl myfile.tex -o=output.tex
 \end{commandshell}
 
 	You can call the \texttt{-o} switch using a \texttt{+} symbol at the beginning; this will
-	\announce{2017-06-25}
+	\announce{2017-06-25}{+ sign in o switch}
 	concatenate the name of the input file and the text given to the \texttt{-o} switch.
 	For example, the following two calls to \texttt{latexindent.pl} are equivalent:
 	\begin{commandshell}
@@ -121,7 +115,7 @@ latexindent.pl myfile.tex -o=myfilenew.tex
 \end{commandshell}
 
 	You can call the \texttt{-o} switch using a \texttt{++} symbol at the end of the name
-	\announce{2017-06-25}
+	\announce{2017-06-25}{++ in o switch}
 	of your output file; this tells \texttt{latexindent.pl} to search successively for
 	the name of your output file concatenated with $0, 1, \ldots$ while the name of the
 	output file exists.  For example,
@@ -205,12 +199,17 @@ latexindent.pl myfile.tex -l=first.yaml,second.yaml,third.yaml
 	The \texttt{-l} flag can take an \emph{optional} parameter which details the name (or names separated by commas) of a YAML file(s)
 	that resides in the same directory as \texttt{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 \texttt{localSettings.yaml}.
-	In fact, you can specify \emph{relative} path names to the current directory, but \emph{not}
-	absolute paths -- for absolute paths, see \vref{sec:indentconfig}.
-	Explicit demonstrations of how to use the \texttt{-l} switch are given throughout this documentation.
+	\announce*{2017-08-21}*{-l switch absolute paths} In fact, you can specify both \emph{relative} and \emph{absolute paths} for your YAML files;
+	for example
+	\begin{commandshell}
+latexindent.pl -l=../../myyaml.yaml myfile.tex
+latexindent.pl -l=/home/cmhughes/Desktop/myyaml.yaml myfile.tex
+latexindent.pl -l=C:\Users\cmhughes\Desktop\myyaml.yaml myfile.tex
+    \end{commandshell}
+	You will find a lot of other explicit demonstrations of how to use the \texttt{-l} switch throughout this documentation,
 
 	You can call the \texttt{-l} switch with a `+' symbol either before or after
-	\announce{2017-06-25}
+	\announce{2017-06-25}{+ sign with -l switch}
 	another YAML file; for example:
 	\begin{commandshell}
 latexindent.pl -l=+myyaml.yaml  myfile.tex
@@ -231,13 +230,29 @@ latexindent.pl -l+myyaml.yaml myfile.tex
 	\begin{commandshell}
 latexindent.pl -l + myyaml.yaml myfile.tex
     \end{commandshell}
-	will \emph{only} load \texttt{localSettings.yaml}, and \texttt{myyaml.yaml} will be ignored.
+	will \emph{only} load \texttt{localSettings.yaml}, and \texttt{myyaml.yaml} will be ignored. If you wish
+	to use spaces between any of the YAML settings, then you must wrap the entire list of YAML files in quotes, as demonstrated above.
 
 	You may also choose to omit the \texttt{yaml} extension, such as
-	\announce{2017-06-25}
+	\announce{2017-06-25}{no extension for -l switch}
 	\begin{commandshell}
 latexindent.pl -l=localSettings,myyaml myfile.tex
     \end{commandshell}
+\flagbox{-y, --yaml=yaml settings}
+	\begin{commandshell}
+latexindent.pl myfile.tex -y="defaultIndent: ' '"
+latexindent.pl myfile.tex -y="defaultIndent: ' ',maximumIndentation:' '"
+latexindent.pl myfile.tex -y="indentRules: one: '\t\t\t\t'"
+latexindent.pl myfile.tex -y='modifyLineBreaks:environments:EndStartsOnOwnLine:3' -m
+latexindent.pl myfile.tex -y='modifyLineBreaks:environments:one:EndStartsOnOwnLine:3' -m
+    \end{commandshell}
+	\label{page:yamlswitch}You%
+	\announce*{2017-08-21}{the -y switch} can specify YAML settings from the command line using the \texttt{-y} or \texttt{--yaml} switch;
+	sample demonstrations are given above.  Note, in particular, that multiple settings can be specified by separating them
+	via commas. There is a further option to use a \texttt{;} to separate fields, which is demonstrated in \vref{sec:yamlswitch}.
+
+	Any settings specified via this switch will be loaded \emph{after}
+	any specified using the \texttt{-l} switch. This is discussed further in \vref{sec:loadorder}.
 \flagbox{-d, --onlydefault}
 	\begin{commandshell}
 latexindent.pl -d myfile.tex
@@ -246,10 +261,12 @@ latexindent.pl -d myfile.tex
 	Only \texttt{defaultSettings.yaml}: you might like to read \cref{sec:defuseloc} before
 	using this switch. By default, \texttt{latexindent.pl} will always search for
 	\texttt{indentconfig.yaml} or \texttt{.indentconfig.yaml}  in your home directory. If you would prefer it not to do so
-	then (instead of deleting or renaming \texttt{indentconfig.yaml}/\texttt{.indentconfig.yaml}) you can simply
+	then (instead of deleting or renaming \texttt{indentconfig.yaml} or \texttt{.indentconfig.yaml}) you can simply
 	call the script with the \texttt{-d} switch; note that this will also tell
 	the script to ignore \texttt{localSettings.yaml} even if it has been called with the
-	\texttt{-l} switch.
+	\texttt{-l} switch; \texttt{latexindent.pl}%
+	\announce*{2017-08-21}*{updated -d switch} will also ignore any settings specified
+	from the \texttt{-y} switch.
 
 \flagbox{-c, --cruft=<directory>}
 	\begin{commandshell}
diff --git a/Master/texmf-dist/doc/support/latexindent/sec-indent-config-and-settings.tex b/Master/texmf-dist/doc/support/latexindent/sec-indent-config-and-settings.tex
index a3cffa0921a..988b3a68abd 100644
--- a/Master/texmf-dist/doc/support/latexindent/sec-indent-config-and-settings.tex
+++ b/Master/texmf-dist/doc/support/latexindent/sec-indent-config-and-settings.tex
@@ -1,60 +1,60 @@
 % arara: pdflatex: {shell: yes, files: [latexindent]}
-\section{User, local settings, \texttt{indentconfig.yaml} and \texttt{.indentconfig.yaml}}\label{sec:indentconfig}
- Editing \texttt{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,
- \texttt{mysettings.yaml} (or any name you like, provided it ends with \texttt{.yaml}).
- The only thing you have to do is tell \texttt{latexindent.pl} where to find it.
-
- \texttt{latexindent.pl} will always check your home directory for \texttt{indentconfig.yaml}
- and  \texttt{.indentconfig.yaml} (unless
- it is called with the \texttt{-d} switch),
- which is a plain text file you can create that contains the \emph{absolute}
- paths for any settings files that you wish \texttt{latexindent.pl} to load. There is no difference
- between \texttt{indentconfig.yaml} and \texttt{.indentconfig.yaml}, other than the
- fact that \texttt{.indentconfig.yaml} is a `hidden' file; thank you to \cite{jacobo-diaz-hidden-config}
- for providing this feature. In what follows, we will use \texttt{indentconfig.yaml}, but it
- is understood that this equally represents \texttt{.indentconfig.yaml} as well. If you
- have both files in existence,  \texttt{indentconfig.yaml} takes priority.
-
- For Mac and Linux users, their home directory is \texttt{~/username} while
- Windows (Vista onwards) is \lstinline!C:\Users\username!\footnote{If you're not sure
-	 where to put \texttt{indentconfig.yaml}, don't
-	 worry \texttt{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 \texttt{indentconfig.yaml} file.
-
- \begin{yaml}{\texttt{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
+\section{\texttt{indentconfig.yaml}, local settings and the \texttt{-y} switch }\label{sec:indentconfig}
+ The behaviour of \texttt{latexindent.pl} is controlled from the settings specified
+ in any of the YAML files that you tell it to load. By default, \texttt{latexindent.pl}
+ will only load \texttt{defaultSettings.yaml}, but there are a few ways that you can
+ tell it to load your own settings files.
+
+\subsection{\texttt{indentconfig.yaml} and \texttt{{.indentconfig.yaml}}}
+	\texttt{latexindent.pl} will always check your home directory for \texttt{indentconfig.yaml}
+	and  \texttt{.indentconfig.yaml} (unless
+	it is called with the \texttt{-d} switch),
+	which is a plain text file you can create that contains the \emph{absolute}
+	paths for any settings files that you wish \texttt{latexindent.pl} to load. There is no difference
+	between \texttt{indentconfig.yaml} and \texttt{.indentconfig.yaml}, other than the
+	fact that \texttt{.indentconfig.yaml} is a `hidden' file; thank you to \cite{jacobo-diaz-hidden-config}
+	for providing this feature. In what follows, we will use \texttt{indentconfig.yaml}, but it
+	is understood that this could equally represent \texttt{.indentconfig.yaml}. If you
+	have both files in existence then \texttt{indentconfig.yaml} takes priority.
+
+	For Mac and Linux users, their home directory is \texttt{~/username} while
+	Windows (Vista onwards) is \lstinline!C:\Users\username!\footnote{If you're not sure
+		where to put \texttt{indentconfig.yaml}, don't
+		worry \texttt{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 \texttt{indentconfig.yaml} file.
+
+	\begin{yaml}{\texttt{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{yaml}
 
- Note that the \texttt{.yaml} files you specify in \texttt{indentconfig.yaml}
- will be loaded in the order that you write them in. Each file doesn't have
- to have every switch from \texttt{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
- \texttt{defaultSettings.yaml} in another directory and call it, for
- example, \texttt{mysettings.yaml}. Once you have added the path to \texttt{indentconfig.yaml}
- you can change the switches and add more code-block names 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 \texttt{tabbing}
- environment/command to the list of environments that contains alignment delimiters; you might also like to
- refer to the many YAML files detailed throughout the rest of this documentation.
-
- \begin{yaml}{\texttt{mysettings.yaml} (example)}{lst:mysettings}
+	Note that the \texttt{.yaml} files you specify in \texttt{indentconfig.yaml}
+	will be loaded in the order in which you write them. Each file doesn't have
+	to have every switch from \texttt{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
+	\texttt{defaultSettings.yaml} in another directory and call it, for
+	example, \texttt{mysettings.yaml}. Once you have added the path to \texttt{indentconfig.yaml}
+	you can change the switches and add more code-block names 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 \texttt{tabbing}
+	environment/command to the list of environments that contains alignment delimiters; you might also like to
+	refer to the many YAML files detailed throughout the rest of this documentation.
+
+	\begin{yaml}{\texttt{mysettings.yaml} (example)}{lst:mysettings}
 # Default value of indentation
 defaultIndent: "\t\t\t\t"
 
@@ -64,48 +64,77 @@ lookForAlignDelims:
     tabbing: 1
 \end{yaml}
 
- You can make sure that your settings are loaded by checking \texttt{indent.log}
- for details -- if you have specified a path that \texttt{latexindent.pl} doesn't
- recognize then you'll get a warning, otherwise you'll get confirmation that
- \texttt{latexindent.pl} has read your settings file \footnote{Windows users
-	 may find that they have to end \texttt{.yaml} files with a blank line}.
+	You can make sure that your settings are loaded by checking \texttt{indent.log}
+	for details -- if you have specified a path that \texttt{latexindent.pl} doesn't
+	recognize then you'll get a warning, otherwise you'll get confirmation that
+	\texttt{latexindent.pl} has read your settings file \footnote{Windows users
+		may find that they have to end \texttt{.yaml} files with a blank line}.
 
- \begin{warning}
-	 When editing \texttt{.yaml} files it is \emph{extremely} important
-	 to remember how sensitive they are to spaces. I highly recommend copying
-	 and pasting from \texttt{defaultSettings.yaml} when you create your
-	 first \texttt{whatevernameyoulike.yaml} file.
+	\begin{warning}
+		When editing \texttt{.yaml} files it is \emph{extremely} important
+		to remember how sensitive they are to spaces. I highly recommend copying
+		and pasting from \texttt{defaultSettings.yaml} when you create your
+		first \texttt{whatevernameyoulike.yaml} file.
 
-	 If \texttt{latexindent.pl} can not read your \texttt{.yaml} file it
-	 will tell you so in \texttt{indent.log}.
- \end{warning}
+		If \texttt{latexindent.pl} can not read your \texttt{.yaml} file it
+		will tell you so in \texttt{indent.log}.
+	\end{warning}
 
 \subsection{\texttt{localSettings.yaml}}\label{sec:localsettings}
 	The \texttt{-l} switch tells \texttt{latexindent.pl} to look for \texttt{localSettings.yaml} in the
-	\emph{same directory} as \texttt{myfile.tex}.  If you'd prefer to name your \texttt{localSettings.yaml} file something
-	different, (say, \texttt{myyaml.yaml}) then
+	\emph{same directory} as \texttt{myfile.tex}.  For example, if you use the following command
+	\begin{commandshell}
+latexindent.pl -l myfile.tex
+\end{commandshell}
+	then \texttt{latexindent.pl} will (assuming it exists) load \texttt{localSettings.yaml} from the same directory
+	as \texttt{myfile.tex}.
+
+	If you'd prefer to name your \texttt{localSettings.yaml} file something
+	different, (say, \texttt{mysettings.yaml} as in \cref{lst:mysettings}) then
 	you can call \texttt{latexindent.pl} using, for example,
 	\begin{commandshell}
-latexindent.pl -l=myyaml.yaml myfile.tex
+latexindent.pl -l=mysettings.yaml myfile.tex
 \end{commandshell}
 
 	Any settings file(s) specified using the \texttt{-l} switch will be read \emph{after} \texttt{defaultSettings.yaml} and, assuming they exist,
-	user settings from \texttt{indentconfig.yaml}.
+	any user setting files specified in \texttt{indentconfig.yaml}.
 
 	Your settings file can contain any switches that you'd
 	like to change; a sample is shown in \cref{lst:localSettings}, and you'll find plenty of further examples throughout this manual.
 
 	\begin{yaml}{\texttt{localSettings.yaml} (example)}{lst:localSettings}
-#  verbatim environments- environments specified
-#  in this hash table will not be changed at all!
+#  verbatim environments - environments specified
+#  here will not be changed at all!
 verbatimEnvironments:
     cmhenvironment: 0
+    myenv: 1
 \end{yaml}
 
 	You can make sure that your settings file has been loaded by checking \texttt{indent.log}
 	for details; if it can not be read then you receive a warning, otherwise you'll get confirmation that
 	\texttt{latexindent.pl} has read your settings file.
 
+\subsection{The \texttt{-y|yaml} switch}\label{sec:yamlswitch}
+	You%
+	\announce*{2017-08-21}{demonstration of the -y switch} may use the \texttt{-y} switch to load
+	your settings;  for example, if you wished to specify the settings from \cref{lst:localSettings}
+	using the \texttt{-y} switch, then you could use the following command:
+	\begin{commandshell}
+latexindent.pl -y="verbatimEnvironments:cmhenvironment:0;myenv:1" myfile.tex
+    \end{commandshell}
+	Note the use of \texttt{;} to specify another field within \texttt{verbatimEnvironments}. This is
+	shorthand, and equivalent, to using the following command:
+	\begin{commandshell}
+latexindent.pl -y="verbatimEnvironments:cmhenvironment:0,verbatimEnvironments:myenv:1" myfile.tex
+    \end{commandshell}
+	You may, of course, specify settings using the \texttt{-y} switch as well as, for example,
+	settings loaded using the \texttt{-l} switch; for example,
+	\begin{commandshell}
+latexindent.pl -l=mysettings.yaml -y="verbatimEnvironments:cmhenvironment:0;myenv:1" myfile.tex
+    \end{commandshell}
+	Any settings specified using the \texttt{-y} switch will be loaded \emph{after} any specified
+	using \texttt{indentconfig.yaml} and the \texttt{-l} switch.
+
 \subsection{Settings load order}\label{sec:loadorder}
 	\texttt{latexindent.pl} loads the settings files in the following order:
 	\begin{enumerate}
@@ -113,12 +142,15 @@ verbatimEnvironments:
 		\item \texttt{anyUserSettings.yaml} and any other arbitrarily-named files specified in \texttt{indentconfig.yaml};
 		\item \texttt{localSettings.yaml} but only if found in the same directory as \texttt{myfile.tex} and called
 		      with \texttt{-l} switch; this file can be renamed, provided that the call to \texttt{latexindent.pl} is adjusted
-		      accordingly (see \cref{sec:localsettings}). You may specify relative  paths to other
-		      YAML files using the \texttt{-l} switch, separating multiple files using commas.
+		      accordingly (see \cref{sec:localsettings}). You may specify both relative and absolute%
+		      \announce*{2017-08-21}*{-l absolute paths} paths to other
+		      YAML files using the \texttt{-l} switch, separating multiple files using commas;
+		\item any settings%
+		      \announce*{2017-08-21}{-y switch load order}  specified in the \texttt{-y} switch.
 	\end{enumerate}
 	A visual representation of this is given in \cref{fig:loadorder}.
 
-	\begin{figure}
+	\begin{figure}[!htb]
 		\centering
 		\begin{tikzpicture}[
 				needed/.style={very thick, draw=blue,fill=blue!20,
@@ -137,6 +169,7 @@ verbatimEnvironments:
 			\node (you) [optional,optionalfill,below right=of indentconfig]  {\texttt{you.yaml}};
 			\node (want) [optional,optionalfill,below=of indentconfig]  {\texttt{want.yaml}};
 			\node (local) [optional,below=of latexindent]  {\texttt{localSettings.yaml}};
+			\node (yamlswitch) [optional,left=of latexindent]  {\texttt{-y switch}};
 			% 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) ;
@@ -145,6 +178,7 @@ verbatimEnvironments:
 			\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) ;
+			\draw[connections,optional] (latexindent) -- node[pos=0.5,anchor=north]{4} (yamlswitch) ;
 		\end{tikzpicture}
 		\caption{Schematic of the load order described in \cref{sec:loadorder}; solid lines represent
 			mandatory files, dotted lines represent optional files. \texttt{indentconfig.yaml} can
diff --git a/Master/texmf-dist/doc/support/latexindent/sec-introduction.tex b/Master/texmf-dist/doc/support/latexindent/sec-introduction.tex
index 67826d37c24..154ea633fe5 100644
--- a/Master/texmf-dist/doc/support/latexindent/sec-introduction.tex
+++ b/Master/texmf-dist/doc/support/latexindent/sec-introduction.tex
@@ -1,9 +1,10 @@
+% arara: pdflatex: {shell: yes, files: [latexindent]}
 \section{Introduction}
 \subsection{Thanks}
 	I first created \texttt{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
+	follow-up feature requests. A big thank you to Harish Kumar \cite{harish} who
 	helped to develop and test the initial versions of the script.
 
 	The \texttt{YAML}-based interface of \texttt{latexindent.pl} was inspired
@@ -47,3 +48,49 @@
 	\emph{If you have used any version 2.* of \texttt{latexindent.pl}, there
 		are a few changes to the interface; see \vref{app:differences} and the comments
 		throughout this document for details}.
+
+\subsection{About this documentation}
+	As you read through this documentation, you will see many listings; in this version of the documentation,
+	there are a total of \totallstlistings. This may seem a lot, but I deem it necessary in
+	presenting the various different options of \texttt{latexindent.pl} and the associated output that they are capable of
+	producing.
+
+	The different listings are presented using different styles:
+
+	\begin{minipage}{.4\textwidth}
+		\cmhlistingsfromfile*{demonstrations/demo-tex.tex}{\texttt{demo-tex.tex}}{lst:demo-tex}
+	\end{minipage}%
+	\hfill
+	\begin{minipage}{.4\textwidth}
+		This type of listing is a \texttt{.tex} file.
+	\end{minipage}%
+
+	\begin{minipage}{.4\textwidth}
+		\cmhlistingsfromfile*[style=fileExtensionPreference]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{fileExtensionPreference}}{lst:fileExtensionPreference-demo}
+	\end{minipage}%
+	\hfill
+	\begin{minipage}{.4\textwidth}
+		This type of listing is a \texttt{.yaml} file; when you see line numbers given (as here)
+		it means that the snippet is taken directly from \texttt{defaultSettings.yaml}, discussed in
+		detail in \vref{sec:defuseloc}.
+	\end{minipage}%
+
+	\begin{minipage}{.55\textwidth}
+		\cmhlistingsfromfile*[style=modifylinebreaks]{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{modifyLineBreaks}}{lst:modifylinebreaks-demo}
+	\end{minipage}%
+	\hfill
+	\begin{minipage}{.4\textwidth}
+		This type of listing is a \texttt{.yaml} file, but it will only
+		be relevant when the \texttt{-m} switch is active; see \vref{sec:modifylinebreaks}
+		for more details.
+	\end{minipage}%
+
+	You will occasionally see dates shown in the margin (for example, next to this paragraph!)
+	\announce{2017-06-25}{announce} which detail the date of the version in which the feature was implemented;
+	the `N' stands for `new as of the date shown' and `U' stands for `updated as of the date shown'.
+	If you see \stardemo, it
+	means that the feature is either new (N) or updated (U) as of the release of the current version; if you see \stardemo\,
+	attached to a listing, then it means that listing is new (N) or updated (U) as of the current version. If you have
+	not read this document before (and even if you have!), then you can ignore every occurrence of the \stardemo;
+	they are simply there to highlight new and updated features.
+	The new and updated features in this documentation (\gitRel) are on the following pages: \listOfNewFeatures
diff --git a/Master/texmf-dist/doc/support/latexindent/sec-the-m-switch.tex b/Master/texmf-dist/doc/support/latexindent/sec-the-m-switch.tex
index 8f645177c0b..278c1163b50 100644
--- a/Master/texmf-dist/doc/support/latexindent/sec-the-m-switch.tex
+++ b/Master/texmf-dist/doc/support/latexindent/sec-the-m-switch.tex
@@ -58,7 +58,7 @@ latexindent.pl myfile.tex -m
 
 \yamltitle{textWrapOptions}*{fields}
 	When the \texttt{-m} switch is active \texttt{latexindent.pl} has the ability to wrap text using the options
-	\announce{2017-05-27}
+	\announce{2017-05-27}{textWrapOptions}
 	specified in the \texttt{textWrapOptions} field, see \cref{lst:textWrapOptions}. The value of
 	\texttt{columns} specifies the column at which the text should be wrapped.
 	By default, the value of \texttt{columns} is \texttt{0}, so \texttt{latexindent.pl}
@@ -149,7 +149,7 @@ latexindent.pl -m textwrap4.tex -o textwrap4-mod2.tex -l textwrap2.yaml
 
 \yamltitle{removeParagraphLineBreaks}*{fields}
 	When the \texttt{-m} switch is active \texttt{latexindent.pl} has the ability to remove line breaks
-	\announce{2017-05-27}
+	\announce{2017-05-27}{removeParagraphLineBreaks}
 	from within paragraphs; the behaviour is controlled by the \texttt{removeParagraphLineBreaks} field, detailed in
 	\cref{lst:removeParagraphLineBreaks}. Thank you to \cite{jowens} for shaping and assisting with the testing of this feature.
 
@@ -279,7 +279,7 @@ latexindent.pl -m shortlines-md.tex -o shortlines-md4.tex -l remove-para4.yaml
 
 \yamltitle{paragraphsStopAt}*{fields}
 	The paragraph line break routine considers blank lines and the \lstinline|\par| command to be the end of a paragraph;
-	\announce{2017-05-27}
+	\announce{2017-05-27}{paragraphsStopAt}
 	you can fine tune the behaviour of the routine further by using the \texttt{paragraphsStopAt} fields, shown in \cref{lst:paragraphsStopAt}.
 
 	\cmhlistingsfromfile[style=paragraphsStopAt]{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{paragraphsStopAt}}{lst:paragraphsStopAt}
@@ -330,15 +330,21 @@ latexindent.pl -m sl-stop.tex -o sl-stop4-comment.tex -l=remove-para4.yaml,stop-
 
 \subsection{Poly-switches}
 	Every other field in the \texttt{modifyLineBreaks} field uses poly-switches, and can take
-	one of four integer values\footnote{You might like to associate one of the four circles in the logo with one of the four given values}:
+	one of \emph{five}%
+	\announce*{2017-08-21}*{blank line poly-switch} integer values:
 	\begin{itemize}[font=\bfseries]
 		\item[$-1$] \emph{remove mode}: line breaks before or after the \emph{<part of thing>} can be removed (assuming that \texttt{preserveBlankLines} is set to \texttt{0});
 		\item[0] \emph{off mode}: line breaks will not be modified for the \emph{<part of thing>} under consideration;
 		\item[1] \emph{add mode}: a line break will be added before or after the \emph{<part of thing>} under consideration, assuming that
 		      there is not already a line break before or after the \emph{<part of thing>};
 		\item[2] \emph{comment then add mode}: a comment symbol will be added, followed by a line break before or after the \emph{<part of thing>} under consideration, assuming that
-		      there is not already a comment and line break before or after the \emph{<part of thing>}.
+		      there is not already a comment and line break before or after the \emph{<part of thing>};
+		\item[3] \emph{add then blank line mode}%
+		      \announce*{2017-08-21}{blank line poly-switch}: a line break will be added before or after the \emph{<part of thing>} under consideration, assuming that
+		      there is not already a line break before or after the \emph{<part of thing>}, followed by a blank line.
 	\end{itemize}
+	In the above, \emph{<part of thing>} refers to either the \emph{begin statement}, \emph{body} or \emph{end statement} of the
+	code blocks detailed in \vref{tab:code-blocks}.
 	All poly-switches are \emph{off} by default; \texttt{latexindent.pl} searches first of all for per-name settings, and then followed by global per-thing settings.
 
 \subsection{modifyLineBreaks for environments}\label{sec:modifylinebreaks-environments}
@@ -348,7 +354,6 @@ latexindent.pl -m sl-stop.tex -o sl-stop4-comment.tex -l=remove-para4.yaml,stop-
 
 	\cmhlistingsfromfile[style=modifylinebreaksEnv]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,MLB-TCB]{\texttt{environments}}{lst:environments-mlb}
 
-\subsubsection{Adding line breaks (poly-switches set to $1$ or $2$)}
 	Let's begin with the simple example given in \cref{lst:env-mlb1-tex}; note that we have annotated key parts of the file using $\BeginStartsOnOwnLine$,
 	$\BodyStartsOnOwnLine$, $\EndStartsOnOwnLine$ and $\EndFinishesWithLineBreak$, these will be related to fields specified in \cref{lst:environments-mlb}.
 
@@ -356,6 +361,7 @@ latexindent.pl -m sl-stop.tex -o sl-stop4-comment.tex -l=remove-para4.yaml,stop-
 before words(*@$\BeginStartsOnOwnLine$@*) \begin{myenv}(*@$\BodyStartsOnOwnLine$@*)body of myenv(*@$\EndStartsOnOwnLine$@*)\end{myenv}(*@$\EndFinishesWithLineBreak$@*) after words
 \end{cmhlistings}
 
+\subsubsection{Adding line breaks using \texttt{BeginStartsOnOwnLine} and \texttt{BodyStartsOnOwnLine}}
 	Let's explore \texttt{BeginStartsOnOwnLine} and \texttt{BodyStartsOnOwnLine} in \cref{lst:env-mlb1,lst:env-mlb2}, and in particular,
 	let's allow each of them in turn to take a value of $1$.
 
@@ -375,11 +381,11 @@ latexindent.pl -m env-mlb.tex -l env-mlb2.yaml
 	the output is as in \cref{lst:env-mlb-mod1,lst:env-mlb-mod2} respectively.
 
 	\begin{widepage}
-		\begin{minipage}{.57\linewidth}
+		\begin{minipage}{.56\linewidth}
 			\cmhlistingsfromfile{demonstrations/env-mlb-mod1.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb1}}{lst:env-mlb-mod1}
 		\end{minipage}
 		\hfill
-		\begin{minipage}{.42\linewidth}
+		\begin{minipage}{.43\linewidth}
 			\cmhlistingsfromfile{demonstrations/env-mlb-mod2.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb2}}{lst:env-mlb-mod2}
 		\end{minipage}
 	\end{widepage}
@@ -406,11 +412,11 @@ latexindent.pl -m env-mlb.tex -l env-mlb2.yaml
 	Upon running  commands analogous to the above, we obtain \cref{lst:env-mlb-mod3,lst:env-mlb-mod4}.
 
 	\begin{widepage}
-		\begin{minipage}{.57\linewidth}
+		\begin{minipage}{.56\linewidth}
 			\cmhlistingsfromfile{demonstrations/env-mlb-mod3.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb3}}{lst:env-mlb-mod3}
 		\end{minipage}
 		\hfill
-		\begin{minipage}{.42\linewidth}
+		\begin{minipage}{.43\linewidth}
 			\cmhlistingsfromfile{demonstrations/env-mlb-mod4.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb4}}{lst:env-mlb-mod4}
 		\end{minipage}
 	\end{widepage}
@@ -419,68 +425,124 @@ latexindent.pl -m env-mlb.tex -l env-mlb2.yaml
 	has been added before adding the line break; in both cases, trailing horizontal
 	space has been stripped before doing so.
 
-	Let's explore \texttt{EndStartsOnOwnLine} and \texttt{EndFinishesWithLineBreak} in \cref{lst:env-mlb5,lst:env-mlb6},
+	Let's%
+	\announce*{2017-08-21}{demonstration of blank line poly-switch (3)}  now change each of the \texttt{1} values in \cref{lst:env-mlb1,lst:env-mlb2} so that they are $3$ and
+	save them into \texttt{env-mlb5.yaml} and \texttt{env-mlb6.yaml} respectively (see \cref{lst:env-mlb5,lst:env-mlb6}).
+
+	\begin{minipage}{.45\textwidth}
+		\cmhlistingsfromfile*[style=yaml-LST]{demonstrations/env-mlb5.yaml}[MLB-TCB]{\texttt{env-mlb5.yaml}}{lst:env-mlb5}
+	\end{minipage}
+	\hfill
+	\begin{minipage}{.45\textwidth}
+		\cmhlistingsfromfile*[style=yaml-LST]{demonstrations/env-mlb6.yaml}[MLB-TCB]{\texttt{env-mlb6.yaml}}{lst:env-mlb6}
+	\end{minipage}
+
+	Upon running  commands analogous to the above, we obtain \cref{lst:env-mlb-mod5,lst:env-mlb-mod6}.
+
+	\begin{widepage}
+		\begin{minipage}{.56\linewidth}
+			\cmhlistingsfromfile*{demonstrations/env-mlb-mod5.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb5}}{lst:env-mlb-mod5}
+		\end{minipage}
+		\hfill
+		\begin{minipage}{.43\linewidth}
+			\cmhlistingsfromfile*{demonstrations/env-mlb-mod6.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb6}}{lst:env-mlb-mod6}
+		\end{minipage}
+	\end{widepage}
+
+	Note that line breaks have been added as in \cref{lst:env-mlb-mod1,lst:env-mlb-mod2}, but this time a \emph{blank line}
+	has been added after adding the line break.
+
+\subsubsection{Adding line breaks using \texttt{EndStartsOnOwnLine} and \texttt{EndFinishesWithLineBreak}}
+	Let's explore \texttt{EndStartsOnOwnLine} and \texttt{EndFinishesWithLineBreak} in \cref{lst:env-mlb7,lst:env-mlb8},
 	and in particular, let's allow each of them in turn to take a value of $1$.
 
 	\begin{minipage}{.49\textwidth}
-		\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb5.yaml}[MLB-TCB]{\texttt{env-mlb5.yaml}}{lst:env-mlb5}
+		\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb7.yaml}[MLB-TCB]{\texttt{env-mlb7.yaml}}{lst:env-mlb7}
 	\end{minipage}
 	\hfill
 	\begin{minipage}{.49\textwidth}
-		\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb6.yaml}[MLB-TCB]{\texttt{env-mlb6.yaml}}{lst:env-mlb6}
+		\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb8.yaml}[MLB-TCB]{\texttt{env-mlb8.yaml}}{lst:env-mlb8}
 	\end{minipage}
 
 	After running the following commands,
 	\begin{commandshell}
-latexindent.pl -m env-mlb.tex -l env-mlb5.yaml
-latexindent.pl -m env-mlb.tex -l env-mlb6.yaml
+latexindent.pl -m env-mlb.tex -l env-mlb7.yaml
+latexindent.pl -m env-mlb.tex -l env-mlb8.yaml
 \end{commandshell}
-	the output is as in \cref{lst:env-mlb-mod5,lst:env-mlb-mod6}.
+	the output is as in \cref{lst:env-mlb-mod7,lst:env-mlb-mod8}.
 
 	\begin{widepage}
 		\begin{minipage}{.42\linewidth}
-			\cmhlistingsfromfile{demonstrations/env-mlb-mod5.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb5}}{lst:env-mlb-mod5}
+			\cmhlistingsfromfile{demonstrations/env-mlb-mod7.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb7}}{lst:env-mlb-mod7}
 		\end{minipage}
 		\hfill
 		\begin{minipage}{.57\linewidth}
-			\cmhlistingsfromfile{demonstrations/env-mlb-mod6.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb6}}{lst:env-mlb-mod6}
+			\cmhlistingsfromfile{demonstrations/env-mlb-mod8.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb8}}{lst:env-mlb-mod8}
 		\end{minipage}
 	\end{widepage}
 
 	There are a couple of points to note:
 	\begin{itemize}
-		\item in \cref{lst:env-mlb-mod5} a line break has been added at the point denoted by $\EndStartsOnOwnLine$ in \vref{lst:env-mlb1-tex}; no
+		\item in \cref{lst:env-mlb-mod7} a line break has been added at the point denoted by $\EndStartsOnOwnLine$ in \vref{lst:env-mlb1-tex}; no
 		      other line breaks have been changed and the \lstinline!\end{myenv}! statement has \emph{not} received indentation (as intended);
-		\item in \cref{lst:env-mlb-mod6} a line break has been added at the point denoted by $\EndFinishesWithLineBreak$ in \vref{lst:env-mlb1-tex}.
+		\item in \cref{lst:env-mlb-mod8} a line break has been added at the point denoted by $\EndFinishesWithLineBreak$ in \vref{lst:env-mlb1-tex}.
 	\end{itemize}
 
-	Let's now change each of the \texttt{1} values in \cref{lst:env-mlb5,lst:env-mlb6} so that they are $2$ and
-	save them into \texttt{env-mlb7.yaml} and \texttt{env-mlb8.yaml} respectively (see \cref{lst:env-mlb7,lst:env-mlb8}).
+	Let's now change each of the \texttt{1} values in \cref{lst:env-mlb7,lst:env-mlb8} so that they are $2$ and
+	save them into \texttt{env-mlb9.yaml} and \texttt{env-mlb10.yaml} respectively (see \cref{lst:env-mlb9,lst:env-mlb10}).
 
 	\begin{minipage}{.49\textwidth}
-		\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb7.yaml}[MLB-TCB]{\texttt{env-mlb7.yaml}}{lst:env-mlb7}
+		\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb9.yaml}[MLB-TCB]{\texttt{env-mlb9.yaml}}{lst:env-mlb9}
 	\end{minipage}
 	\hfill
 	\begin{minipage}{.49\textwidth}
-		\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb8.yaml}[MLB-TCB]{\texttt{env-mlb8.yaml}}{lst:env-mlb8}
+		\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb10.yaml}[MLB-TCB]{\texttt{env-mlb10.yaml}}{lst:env-mlb10}
 	\end{minipage}
 
-	Upon running  commands analogous to the above, we obtain \cref{lst:env-mlb-mod7,lst:env-mlb-mod8}.
+	Upon running  commands analogous to the above, we obtain \cref{lst:env-mlb-mod9,lst:env-mlb-mod10}.
 
 	\begin{widepage}
-		\begin{minipage}{.42\linewidth}
-			\cmhlistingsfromfile{demonstrations/env-mlb-mod7.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb7}}{lst:env-mlb-mod7}
+		\begin{minipage}{.43\linewidth}
+			\cmhlistingsfromfile{demonstrations/env-mlb-mod9.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb9}}{lst:env-mlb-mod9}
 		\end{minipage}
 		\hfill
-		\begin{minipage}{.57\linewidth}
-			\cmhlistingsfromfile{demonstrations/env-mlb-mod8.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb8}}{lst:env-mlb-mod8}
+		\begin{minipage}{.56\linewidth}
+			\cmhlistingsfromfile{demonstrations/env-mlb-mod10.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb10}}{lst:env-mlb-mod10}
 		\end{minipage}
 	\end{widepage}
 
-	Note that line breaks have been added as in \cref{lst:env-mlb-mod5,lst:env-mlb-mod6}, but this time a comment symbol
+	Note that line breaks have been added as in \cref{lst:env-mlb-mod7,lst:env-mlb-mod8}, but this time a comment symbol
 	has been added before adding the line break; in both cases, trailing horizontal
 	space has been stripped before doing so.
 
+	Let's%
+	\announce*{2017-08-21}{demonstration of blank line poly-switch (3)} now change each of the \texttt{1} values in \cref{lst:env-mlb7,lst:env-mlb8} so that they are $3$ and
+	save them into \texttt{env-mlb11.yaml} and \texttt{env-mlb12.yaml} respectively (see \cref{lst:env-mlb11,lst:env-mlb12}).
+
+	\begin{minipage}{.49\textwidth}
+		\cmhlistingsfromfile*[style=yaml-LST]{demonstrations/env-mlb11.yaml}[MLB-TCB]{\texttt{env-mlb11.yaml}}{lst:env-mlb11}
+	\end{minipage}
+	\hfill
+	\begin{minipage}{.49\textwidth}
+		\cmhlistingsfromfile*[style=yaml-LST]{demonstrations/env-mlb12.yaml}[MLB-TCB]{\texttt{env-mlb12.yaml}}{lst:env-mlb12}
+	\end{minipage}
+
+	Upon running  commands analogous to the above, we obtain \cref{lst:env-mlb-mod11,lst:env-mlb-mod12}.
+
+	\begin{widepage}
+		\begin{minipage}{.42\linewidth}
+			\cmhlistingsfromfile*{demonstrations/env-mlb-mod11.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb11}}{lst:env-mlb-mod11}
+		\end{minipage}
+		\hfill
+		\begin{minipage}{.57\linewidth}
+			\cmhlistingsfromfile*{demonstrations/env-mlb-mod12.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb12}}{lst:env-mlb-mod12}
+		\end{minipage}
+	\end{widepage}
+
+	Note that line breaks have been added as in \cref{lst:env-mlb-mod7,lst:env-mlb-mod8}, and that a \emph{blank line}
+	has been added after the line break.
+
+\subsubsection{poly-switches only add line breaks when necessary}
 	If you ask \texttt{latexindent.pl} to add a line break (possibly with a comment) using a poly-switch value of $1$ (or $2$),
 	it will only do so if necessary. For example, if you process the file in \vref{lst:mlb2} using any of the YAML
 	files presented so far in this section, it will be left unchanged.
@@ -517,7 +579,7 @@ latexindent.pl -m env-mlb.tex -l env-mlb6.yaml
 	Setting poly-switches to $-1$ tells \texttt{latexindent.pl} to remove line breaks of the \emph{<part of the thing>}, if necessary. We will consider the
 	example code given in \cref{lst:mlb4}, noting in particular the positions of
 	the line break highlighters, $\BeginStartsOnOwnLine$, $\BodyStartsOnOwnLine$, $\EndStartsOnOwnLine$
-	and $\EndFinishesWithLineBreak$, together with the associated YAML files in \crefrange{lst:env-mlb9}{lst:env-mlb12}.
+	and $\EndFinishesWithLineBreak$, together with the associated YAML files in \crefrange{lst:env-mlb13}{lst:env-mlb16}.
 
 	\begin{minipage}{.45\linewidth}
 		\begin{cmhlistings}[escapeinside={(*@}{@*)}]{\texttt{env-mlb4.tex}}{lst:mlb4}
@@ -530,100 +592,100 @@ after words
 	\end{minipage}%
 	\hfill
 	\begin{minipage}{.51\textwidth}
-		\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb9.yaml}[MLB-TCB]{\texttt{env-mlb9.yaml}}{lst:env-mlb9}
+		\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb13.yaml}[MLB-TCB]{\texttt{env-mlb13.yaml}}{lst:env-mlb13}
 
-		\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb10.yaml}[MLB-TCB]{\texttt{env-mlb10.yaml}}{lst:env-mlb10}
+		\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb14.yaml}[MLB-TCB]{\texttt{env-mlb14.yaml}}{lst:env-mlb14}
 
-		\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb11.yaml}[MLB-TCB]{\texttt{env-mlb11.yaml}}{lst:env-mlb11}
+		\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb15.yaml}[MLB-TCB]{\texttt{env-mlb15.yaml}}{lst:env-mlb15}
 
-		\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb12.yaml}[MLB-TCB]{\texttt{env-mlb12.yaml}}{lst:env-mlb12}
+		\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb16.yaml}[MLB-TCB]{\texttt{env-mlb16.yaml}}{lst:env-mlb16}
 	\end{minipage}
 
 	After running the commands
 	\begin{commandshell}
-latexindent.pl -m env-mlb4.tex -l env-mlb9.yaml
-latexindent.pl -m env-mlb4.tex -l env-mlb10.yaml
-latexindent.pl -m env-mlb4.tex -l env-mlb11.yaml
-latexindent.pl -m env-mlb4.tex -l env-mlb12.yaml
+latexindent.pl -m env-mlb4.tex -l env-mlb13.yaml
+latexindent.pl -m env-mlb4.tex -l env-mlb14.yaml
+latexindent.pl -m env-mlb4.tex -l env-mlb15.yaml
+latexindent.pl -m env-mlb4.tex -l env-mlb16.yaml
 \end{commandshell}
 
-	we obtain the respective output in \crefrange{lst:env-mlb4-mod9}{lst:env-mlb4-mod12}.
+	we obtain the respective output in \crefrange{lst:env-mlb4-mod13}{lst:env-mlb4-mod16}.
 
 	\begin{minipage}{.45\linewidth}
-		\cmhlistingsfromfile{demonstrations/env-mlb4-mod9.tex}{\texttt{env-mlb4.tex} using \cref{lst:env-mlb9}}{lst:env-mlb4-mod9}
+		\cmhlistingsfromfile{demonstrations/env-mlb4-mod13.tex}{\texttt{env-mlb4.tex} using \cref{lst:env-mlb13}}{lst:env-mlb4-mod13}
 	\end{minipage}
 	\hfill
 	\begin{minipage}{.45\linewidth}
-		\cmhlistingsfromfile{demonstrations/env-mlb4-mod10.tex}{\texttt{env-mlb4.tex} using \cref{lst:env-mlb10}}{lst:env-mlb4-mod10}
+		\cmhlistingsfromfile{demonstrations/env-mlb4-mod14.tex}{\texttt{env-mlb4.tex} using \cref{lst:env-mlb14}}{lst:env-mlb4-mod14}
 	\end{minipage}
 
 	\begin{minipage}{.45\linewidth}
-		\cmhlistingsfromfile{demonstrations/env-mlb4-mod11.tex}{\texttt{env-mlb4.tex} using \cref{lst:env-mlb11}}{lst:env-mlb4-mod11}
+		\cmhlistingsfromfile{demonstrations/env-mlb4-mod15.tex}{\texttt{env-mlb4.tex} using \cref{lst:env-mlb15}}{lst:env-mlb4-mod15}
 	\end{minipage}
 	\hfill
 	\begin{minipage}{.45\linewidth}
-		\cmhlistingsfromfile{demonstrations/env-mlb4-mod12.tex}{\texttt{env-mlb4.tex} using \cref{lst:env-mlb12}}{lst:env-mlb4-mod12}
+		\cmhlistingsfromfile{demonstrations/env-mlb4-mod16.tex}{\texttt{env-mlb4.tex} using \cref{lst:env-mlb16}}{lst:env-mlb4-mod16}
 	\end{minipage}
 
-	Notice that in
+	Notice that in:
 	\begin{itemize}
-		\item \cref{lst:env-mlb4-mod9} the line break denoted by $\BeginStartsOnOwnLine$ in \cref{lst:mlb4} has been removed;
-		\item \cref{lst:env-mlb4-mod10} the line break denoted by $\BodyStartsOnOwnLine$ in \cref{lst:mlb4} has been removed;
-		\item \cref{lst:env-mlb4-mod11} the line break denoted by $\EndStartsOnOwnLine$ in \cref{lst:mlb4} has been removed;
-		\item \cref{lst:env-mlb4-mod12} the line break denoted by $\EndFinishesWithLineBreak$ in \cref{lst:mlb4} has been removed.
+		\item \cref{lst:env-mlb4-mod13} the line break denoted by $\BeginStartsOnOwnLine$ in \cref{lst:mlb4} has been removed;
+		\item \cref{lst:env-mlb4-mod14} the line break denoted by $\BodyStartsOnOwnLine$ in \cref{lst:mlb4} has been removed;
+		\item \cref{lst:env-mlb4-mod15} the line break denoted by $\EndStartsOnOwnLine$ in \cref{lst:mlb4} has been removed;
+		\item \cref{lst:env-mlb4-mod16} the line break denoted by $\EndFinishesWithLineBreak$ in \cref{lst:mlb4} has been removed.
 	\end{itemize}
 	We examined each of these cases separately for clarity of explanation, but you can combine all of the YAML
-	settings in \crefrange{lst:env-mlb9}{lst:env-mlb12} into one file; alternatively, you could tell \texttt{latexindent.pl}
+	settings in \crefrange{lst:env-mlb13}{lst:env-mlb16} into one file; alternatively, you could tell \texttt{latexindent.pl}
 	to load them all by using the following command, for example
 	\begin{widepage}
 		\begin{commandshell}
-latexindent.pl -m env-mlb4.tex -l env-mlb9.yaml,env-mlb10.yaml,env-mlb11.yaml,env-mlb12.yaml
+latexindent.pl -m env-mlb4.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,env-mlb16.yaml
 \end{commandshell}
 	\end{widepage}
 	which gives the output in \vref{lst:env-mlb1-tex}.
 
-	\paragraph{About trailing horizontal space}
-		Recall that on \cpageref{yaml:removeTrailingWhitespace} we discussed the YAML field \texttt{removeTrailingWhitespace},
-		and that it has two (binary) switches to determine if horizontal space should be removed \texttt{beforeProcessing} and \texttt{afterProcessing}.
-		The \texttt{beforeProcessing} is particularly relevant when considering the \texttt{-m} switch; let's consider the
-		file shown in \cref{lst:mlb5}, which highlights trailing spaces.
+\subsubsection{About trailing horizontal space}
+	Recall that on \cpageref{yaml:removeTrailingWhitespace} we discussed the YAML field \texttt{removeTrailingWhitespace},
+	and that it has two (binary) switches to determine if horizontal space should be removed \texttt{beforeProcessing} and \texttt{afterProcessing}.
+	The \texttt{beforeProcessing} is particularly relevant when considering the \texttt{-m} switch; let's consider the
+	file shown in \cref{lst:mlb5}, which highlights trailing spaces.
 
-		\begin{minipage}{.45\linewidth}
-			\begin{cmhlistings}[showspaces=true,escapeinside={(*@}{@*)}]{\texttt{env-mlb5.tex}}{lst:mlb5}
+	\begin{minipage}{.45\linewidth}
+		\begin{cmhlistings}[showspaces=true,escapeinside={(*@}{@*)}]{\texttt{env-mlb5.tex}}{lst:mlb5}
 before words   (*@$\BeginStartsOnOwnLine$@*) 
 \begin{myenv}           (*@$\BodyStartsOnOwnLine$@*)
 body of myenv      (*@$\EndStartsOnOwnLine$@*) 
 \end{myenv}     (*@$\EndFinishesWithLineBreak$@*)
 after words
 \end{cmhlistings}
-		\end{minipage}
-		\hfill
-		\begin{minipage}{.45\linewidth}
-			\cmhlistingsfromfile[style=yaml-LST]{demonstrations/removeTWS-before.yaml}[yaml-TCB]{\texttt{removeTWS-before.yaml}}{lst:removeTWS-before}
-		\end{minipage}
+	\end{minipage}
+	\hfill
+	\begin{minipage}{.45\linewidth}
+		\cmhlistingsfromfile[style=yaml-LST]{demonstrations/removeTWS-before.yaml}[yaml-TCB]{\texttt{removeTWS-before.yaml}}{lst:removeTWS-before}
+	\end{minipage}
 
-		The output from the following commands
-		\begin{widepage}
-			\begin{commandshell}
-latexindent.pl -m env-mlb5.tex -l env-mlb9.yaml,env-mlb10.yaml,env-mlb11.yaml,env-mlb12.yaml
-latexindent.pl -m env-mlb5.tex -l env-mlb9.yaml,env-mlb10.yaml,env-mlb11.yaml,env-mlb12.yaml,removeTWS-before.yaml
+	The output from the following commands
+	\begin{widepage}
+		\begin{commandshell}
+latexindent.pl -m env-mlb5.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,env-mlb16.yaml
+latexindent.pl -m env-mlb5.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,env-mlb16.yaml,removeTWS-before.yaml
 \end{commandshell}
-		\end{widepage}
-		is shown, respectively, in \cref{lst:env-mlb5-modAll,lst:env-mlb5-modAll-remove-WS}; note that
-		the trailing horizontal white space has been preserved (by default) in \cref{lst:env-mlb5-modAll}, while
-		in \cref{lst:env-mlb5-modAll-remove-WS}, it has been removed using the switch specified in \cref{lst:removeTWS-before}.
+	\end{widepage}
+	is shown, respectively, in \cref{lst:env-mlb5-modAll,lst:env-mlb5-modAll-remove-WS}; note that
+	the trailing horizontal white space has been preserved (by default) in \cref{lst:env-mlb5-modAll}, while
+	in \cref{lst:env-mlb5-modAll-remove-WS}, it has been removed using the switch specified in \cref{lst:removeTWS-before}.
 
-		\begin{widepage}
-			\cmhlistingsfromfile{demonstrations/env-mlb5-modAll.tex}{\texttt{env-mlb5.tex} using \crefrange{lst:env-mlb4-mod9}{lst:env-mlb4-mod12}}{lst:env-mlb5-modAll}
+	\begin{widepage}
+		\cmhlistingsfromfile{demonstrations/env-mlb5-modAll.tex}{\texttt{env-mlb5.tex} using \crefrange{lst:env-mlb4-mod13}{lst:env-mlb4-mod16}}{lst:env-mlb5-modAll}
 
-			\cmhlistingsfromfile{demonstrations/env-mlb5-modAll-remove-WS.tex}{\texttt{env-mlb5.tex} using \crefrange{lst:env-mlb4-mod9}{lst:env-mlb4-mod12} \emph{and} \cref{lst:removeTWS-before}}{lst:env-mlb5-modAll-remove-WS}
-		\end{widepage}
+		\cmhlistingsfromfile{demonstrations/env-mlb5-modAll-remove-WS.tex}{\texttt{env-mlb5.tex} using \crefrange{lst:env-mlb4-mod13}{lst:env-mlb4-mod16} \emph{and} \cref{lst:removeTWS-before}}{lst:env-mlb5-modAll-remove-WS}
+	\end{widepage}
 
-	\paragraph{Blank lines}
-		Now let's consider the file in \cref{lst:mlb6}, which contains blank lines.
+\subsubsection{poly-switch line break removal and blank lines}
+	Now let's consider the file in \cref{lst:mlb6}, which contains blank lines.
 
-		\begin{minipage}{.45\linewidth}
-			\begin{cmhlistings}[escapeinside={(*@}{@*)}]{\texttt{env-mlb6.tex}}{lst:mlb6}
+	\begin{minipage}{.45\linewidth}
+		\begin{cmhlistings}[escapeinside={(*@}{@*)}]{\texttt{env-mlb6.tex}}{lst:mlb6}
 before words(*@$\BeginStartsOnOwnLine$@*)
 
 
@@ -637,34 +699,58 @@ body of myenv(*@$\EndStartsOnOwnLine$@*)
 
 after words
 \end{cmhlistings}
-		\end{minipage}%
+	\end{minipage}%
+	\hfill
+	\begin{minipage}{.45\linewidth}
+		\cmhlistingsfromfile[style=yaml-LST]{demonstrations/UnpreserveBlankLines.yaml}[MLB-TCB]{\texttt{UnpreserveBlankLines.yaml}}{lst:UnpreserveBlankLines}
+	\end{minipage}
+
+	Upon running the following commands
+	\begin{widepage}
+		\begin{commandshell}
+latexindent.pl -m env-mlb6.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,env-mlb16.yaml
+latexindent.pl -m env-mlb6.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,env-mlb16.yaml,UnpreserveBlankLines.yaml
+\end{commandshell}
+	\end{widepage}
+	we receive the respective outputs in \cref{lst:env-mlb6-modAll,lst:env-mlb6-modAll-un-Preserve-Blank-Lines}. In
+	\cref{lst:env-mlb6-modAll} we see that the multiple blank lines have each been condensed into one blank line,
+	but that blank lines have \emph{not} been removed by the poly-switches -- this is because, by default, \texttt{preserveBlankLines}
+	is set to \texttt{1}. By contrast, in \cref{lst:env-mlb6-modAll-un-Preserve-Blank-Lines}, we have allowed
+	the poly-switches to remove blank lines because, in \cref{lst:UnpreserveBlankLines}, we have set \texttt{preserveBlankLines} to \texttt{0}.
+
+	\begin{widepage}
+		\begin{minipage}{.30\linewidth}
+			\cmhlistingsfromfile{demonstrations/env-mlb6-modAll.tex}{\texttt{env-mlb6.tex} using \crefrange{lst:env-mlb4-mod13}{lst:env-mlb4-mod16}}{lst:env-mlb6-modAll}
+		\end{minipage}
 		\hfill
-		\begin{minipage}{.45\linewidth}
-			\cmhlistingsfromfile[style=yaml-LST]{demonstrations/UnpreserveBlankLines.yaml}[MLB-TCB]{\texttt{UnpreserveBlankLines.yaml}}{lst:UnpreserveBlankLines}
+		\begin{minipage}{.65\linewidth}
+			\cmhlistingsfromfile{demonstrations/env-mlb6-modAll-un-Preserve-Blank-Lines.tex}{\texttt{env-mlb6.tex} using \crefrange{lst:env-mlb4-mod13}{lst:env-mlb4-mod16} \emph{and} \cref{lst:UnpreserveBlankLines}}{lst:env-mlb6-modAll-un-Preserve-Blank-Lines}
 		\end{minipage}
+	\end{widepage}
 
-		Upon running the following commands
-		\begin{widepage}
-			\begin{commandshell}
-latexindent.pl -m env-mlb6.tex -l env-mlb9.yaml,env-mlb10.yaml,env-mlb11.yaml,env-mlb12.yaml
-latexindent.pl -m env-mlb6.tex -l env-mlb9.yaml,env-mlb10.yaml,env-mlb11.yaml,env-mlb12.yaml,UnpreserveBlankLines.yaml
-\end{commandshell}
-		\end{widepage}
-		we receive the respective outputs in \cref{lst:env-mlb6-modAll,lst:env-mlb6-modAll-un-Preserve-Blank-Lines}. In
-		\cref{lst:env-mlb6-modAll} we see that the multiple blank lines have each been condensed into one blank line,
-		but that blank lines have \emph{not} been removed by the poly-switches -- this is because, by default, \texttt{preserveBlankLines}
-		is set to \texttt{1}. By contrast, in \cref{lst:env-mlb6-modAll-un-Preserve-Blank-Lines}, we have allowed
-		the poly-switches to remove blank lines because, in \cref{lst:UnpreserveBlankLines}, we have set \texttt{preserveBlankLines} to \texttt{0}.
-
-		\begin{widepage}
-			\begin{minipage}{.30\linewidth}
-				\cmhlistingsfromfile{demonstrations/env-mlb6-modAll.tex}{\texttt{env-mlb6.tex} using \crefrange{lst:env-mlb4-mod9}{lst:env-mlb4-mod12}}{lst:env-mlb6-modAll}
-			\end{minipage}
-			\hfill
-			\begin{minipage}{.65\linewidth}
-				\cmhlistingsfromfile{demonstrations/env-mlb6-modAll-un-Preserve-Blank-Lines.tex}{\texttt{env-mlb6.tex} using \crefrange{lst:env-mlb4-mod9}{lst:env-mlb4-mod12} \emph{and} \cref{lst:UnpreserveBlankLines}}{lst:env-mlb6-modAll-un-Preserve-Blank-Lines}
-			\end{minipage}
-		\end{widepage}
+	We can explore this further using the blank-line poly-switch value of $3$; let's use the file given
+	in \cref{lst:env-mlb7-tex}.
+
+	\cmhlistingsfromfile*{demonstrations/env-mlb7.tex}{\texttt{env-mlb7.tex}}{lst:env-mlb7-tex}
+
+	Upon running the following commands
+	\begin{commandshell}
+latexindent.pl -m env-mlb7.tex -l env-mlb12.yaml,env-mlb13.yaml
+latexindent.pl -m env-mlb7.tex -l env-mlb13.yaml,env-mlb14.yaml,UnpreserveBlankLines.yaml
+            \end{commandshell}
+	we receive the outputs given in \cref{lst:env-mlb7-preserve,lst:env-mlb7-no-preserve}.
+
+	\cmhlistingsfromfile*{demonstrations/env-mlb7-preserve.tex}{\texttt{env-mlb7-preserve.tex}}{lst:env-mlb7-preserve}
+	\cmhlistingsfromfile*{demonstrations/env-mlb7-no-preserve.tex}{\texttt{env-mlb7-no-preserve.tex}}{lst:env-mlb7-no-preserve}
+
+	Notice that in:
+	\begin{itemize}
+		\item \cref{lst:env-mlb7-preserve} that \lstinline!\end{one}! has added a blank line, because of the value of
+		      \texttt{EndFinishesWithLineBreak} in \vref{lst:env-mlb12}, and even though the line break ahead of \lstinline!\begin{two}! should have been removed
+		      (because of \texttt{BeginStartsOnOwnLine} in \vref{lst:env-mlb13}), the blank line has been preserved by default;
+		\item \cref{lst:env-mlb7-no-preserve}, by contrast, has had the additional line-break removed, because of
+		      the settings in \cref{lst:UnpreserveBlankLines}.
+	\end{itemize}
 
 \subsection{Poly-switches for other code blocks}
 	Rather than repeat the examples shown for the environment code blocks (in \vref{sec:modifylinebreaks-environments}), we choose to detail the poly-switches for
diff --git a/Master/texmf-dist/doc/support/latexindent/subsec-commands-and-their-options.tex b/Master/texmf-dist/doc/support/latexindent/subsec-commands-and-their-options.tex
index be953d1c5db..600339217e5 100644
--- a/Master/texmf-dist/doc/support/latexindent/subsec-commands-and-their-options.tex
+++ b/Master/texmf-dist/doc/support/latexindent/subsec-commands-and-their-options.tex
@@ -7,9 +7,10 @@
 
 \yamltitle{commandCodeBlocks}*{fields}
 
-	The \texttt{commandCodeBlocks} field contains a few switches detailed in \cref{lst:commandCodeBlocks}.
+	The \texttt{commandCodeBlocks} field%
+	\announce*{2017-08-21}*{commandCodeBlocks} contains a few switches detailed in \cref{lst:commandCodeBlocks}.
 
-	\cmhlistingsfromfile[style=commandCodeBlocks]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{commandCodeBlocks}}{lst:commandCodeBlocks}
+	\cmhlistingsfromfile*[style=commandCodeBlocks]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{commandCodeBlocks}}{lst:commandCodeBlocks}
 
 \yamltitle{roundParenthesesAllowed}{0|1}
 
@@ -137,3 +138,37 @@ latexindent.pl tikz-node1.tex -l no-to.yaml
 		\item it finds a \texttt{namedGroupingBracesBrackets} called \texttt{to} (see \vref{tab:code-blocks}) \emph{with} argument \lstinline![in=110,out=-90]!
 		\item it finds another \texttt{namedGroupingBracesBrackets} but this time called \texttt{node} with argument \lstinline![below,align=left,scale=0.5]!
 	\end{itemize}
+
+\yamltitle{commandNameSpecial}*{fields}
+	There are some special command names%
+	\announce*{2017-08-21}{commandNameSpecial} that do not fit within the names recognized by \texttt{latexindent.pl},
+	the first one of which is \lstinline!\@ifnextchar[!. From the perspective of \texttt{latexindent.pl}, the whole of the
+	text \lstinline!\@ifnextchar[! is is a command, because it is
+	immediately followed by sets of mandatory arguments. However, without the \texttt{commandNameSpecial} field, \texttt{latexindent.pl}
+	would not be able to label it as such, because the \lstinline![! is, necessarily, not matched by a closing \lstinline!]!.
+
+	For example, consider the sample file in \cref{lst:ifnextchar}, which has default output in \cref{lst:ifnextchar-default}.
+
+	\begin{minipage}{.45\textwidth}
+		\cmhlistingsfromfile*{demonstrations/ifnextchar.tex}{\texttt{ifnextchar.tex}}{lst:ifnextchar}
+	\end{minipage}
+	\hfill
+	\begin{minipage}{.45\textwidth}
+		\cmhlistingsfromfile*{demonstrations/ifnextchar-default.tex}{\texttt{ifnextchar.tex} default output}{lst:ifnextchar-default}
+	\end{minipage}
+
+	Notice that in \cref{lst:ifnextchar-default} the \texttt{parbox} command has been able to indent its body, because \texttt{latexindent.pl}
+	has successfully found the command \lstinline!\@ifnextchar! first; the pattern-matching of \texttt{latexindent.pl} starts from
+	\emph{the inner most <thing> and works outwards}, discussed in more detail on \cpageref{page:phases}.  For demonstration, we can compare
+	this output with that given in \cref{lst:ifnextchar-off} in which
+	the settings from \cref{lst:no-ifnextchar} have dictated that \lstinline!\@ifnextchar[! command should not be searched for specially;
+	as such, the \texttt{parbox} command has been \emph{unable} to indent its body successfully, because the \lstinline!\@ifnextchar[!
+	command has not been found.
+
+	\begin{minipage}{.45\textwidth}
+		\cmhlistingsfromfile*{demonstrations/ifnextchar-off.tex}{\texttt{ifnextchar.tex} using \cref{lst:no-ifnextchar}}{lst:ifnextchar-off}
+	\end{minipage}
+	\hfill
+	\begin{minipage}{.45\textwidth}
+		\cmhlistingsfromfile*[style=yaml-LST]{demonstrations/no-ifnextchar.yaml}[yaml-TCB]{\texttt{no-ifnextchar.yaml}}{lst:no-ifnextchar}
+	\end{minipage}
diff --git a/Master/texmf-dist/doc/support/latexindent/subsec-conflicting-poly-switches.tex b/Master/texmf-dist/doc/support/latexindent/subsec-conflicting-poly-switches.tex
index e7a66901f18..b08cb45623a 100644
--- a/Master/texmf-dist/doc/support/latexindent/subsec-conflicting-poly-switches.tex
+++ b/Master/texmf-dist/doc/support/latexindent/subsec-conflicting-poly-switches.tex
@@ -69,7 +69,7 @@ latexindent.pl -m -l=nested-env-mlb1.yaml nested-env.tex
 	gives the output in \cref{lst:nested-env-mlb1}.
 
 	\begin{minipage}{.45\linewidth}
-		\cmhlistingsfromfile{demonstrations/nested-env-mlb1.tex}{\texttt{nested-env.tex} using \cref{lst:nested-env-mlb1}}{lst:nested-env-mlb1}
+		\cmhlistingsfromfile{demonstrations/nested-env-mlb1.tex}{\texttt{nested-env.tex} using \cref{lst:nested-env-mlb1-yaml}}{lst:nested-env-mlb1}
 	\end{minipage}
 	\hfill
 	\begin{minipage}{.55\linewidth}
@@ -79,7 +79,7 @@ latexindent.pl -m -l=nested-env-mlb1.yaml nested-env.tex
 	In \cref{lst:nested-env-mlb1}, let's first of all note that both environments have received the appropriate (default) indentation; secondly,
 	note that the poly-switch \texttt{EndStartsOnOwnLine} appears to have won the conflict, as \lstinline!\end{one}! has had its leading line break removed.
 
-	To understand it, let's talk about the three basic phases of \texttt{latexindent.pl}:
+	To understand it, let's talk about the three basic phases \label{page:phases}of \texttt{latexindent.pl}:
 	\begin{enumerate}
 		\item Phase 1: packing, in which code blocks are replaced with unique ids, working from \emph{the inside to the outside}, and then sequentially -- for example, in
 		      \cref{lst:nested-env}, the \texttt{two} environment is found \emph{before} the \texttt{one} environment; if the -m switch is active, then during this phase:
diff --git a/Master/texmf-dist/doc/support/latexindent/title.tex b/Master/texmf-dist/doc/support/latexindent/title.tex
index 78845b84c5b..74450037999 100644
--- a/Master/texmf-dist/doc/support/latexindent/title.tex
+++ b/Master/texmf-dist/doc/support/latexindent/title.tex
@@ -8,7 +8,7 @@
 			sharp corners,
 			enhanced,
 			overlay={\node[anchor=north east,outer sep=2pt] at ([xshift=3cm,yshift=4mm]frame.north east) {\includegraphics[width=3cm]{logo}}; }]
-		\centering\ttfamily\bfseries latexindent.pl\\[1cm] Version 3.2.2
+		\centering\ttfamily\bfseries latexindent.pl\\[1cm] Version 3.3
 	\end{tcolorbox}
 }
 \author{Chris Hughes \thanks{and contributors! See \vref{sec:contributors}. For
diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/Arguments.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/Arguments.pm
index 569cead9584..9643bf11375 100644
--- a/Master/texmf-dist/scripts/latexindent/LatexIndent/Arguments.pm
+++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/Arguments.pm
@@ -142,19 +142,23 @@ sub find_opt_mand_arguments{
                 my $BodyValue = (defined ${$self}{BodyStartsOnOwnLine}) ? ${$self}{BodyStartsOnOwnLine} : "0";
                 $self->logger("$BodyStringLogFile = $BodyValue (in ${$self}{name}), but first argument *should* begin on its own line (see $BeginStringLogFile)") if $is_t_switch_active;
 
-                # possibly add a comment at the end of the begin statement
-                my $trailingCommentToken = q();
+                # possibly add a comment or a blank line, depending on if BeginStartsOnOwnLine == 2 or 3 respectively 
+                # at the end of the begin statement
+                my $trailingCharacterToken = q();
                 if(${${${$arguments}{children}}[0]}{BeginStartsOnOwnLine}==1){
                     $self->logger("Adding line breaks at the end of ${$self}{begin} (first argument, see $BeginStringLogFile == ${${${$arguments}{children}}[0]}{BeginStartsOnOwnLine})") if $is_t_switch_active;
                 } elsif(${${${$arguments}{children}}[0]}{BeginStartsOnOwnLine}==2){
                     $self->logger("Adding a % at the end of begin, ${$self}{begin} followed by a linebreak ($BeginStringLogFile == 2)") if $is_t_switch_active;
-                    $trailingCommentToken = "%".$self->add_comment_symbol;
+                    $trailingCharacterToken = "%".$self->add_comment_symbol;
                     $self->logger("Removing trailing space on ${$self}{begin}") if $is_t_switch_active;
                     ${$self}{begin} =~ s/\h*$//s;
+                } elsif (${${${$arguments}{children}}[0]}{BeginStartsOnOwnLine}==3) {
+                  $self->logger("Adding a blank line immediately ${$self}{begin} ($BeginStringLogFile==3)") if $is_t_switch_active;
+                  $trailingCharacterToken = "\n".(${$masterSettings{modifyLineBreaks}}{preserveBlankLines}?$tokens{blanklines}:q());
                 }
 
                 # modification
-                ${$self}{begin} .= "$trailingCommentToken\n";
+                ${$self}{begin} .= "$trailingCharacterToken\n";
                 ${$self}{linebreaksAtEnd}{begin} = 1;
             }
         }
diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/BlankLines.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/BlankLines.pm
index f4572dd6797..7f5c5b63cca 100644
--- a/Master/texmf-dist/scripts/latexindent/LatexIndent/BlankLines.pm
+++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/BlankLines.pm
@@ -87,19 +87,18 @@ sub unprotect_blank_lines{
     my $blankLineToken = $tokens{blanklines};
 
     # loop through the body, looking for the blank line token
-    while(${$self}{body} =~ m/$blankLineToken/m){
+    while(${$self}{body} =~ m/$blankLineToken/s){
         # when the blank line token occupies the whole line
-        if(${$self}{body} =~ m/^\h*$blankLineToken$/m){
-            $self->logger("Replacing purely blank lines",'heading') if $is_tt_switch_active;
-            ${$self}{body} =~ s/^\h*$blankLineToken$//mg;
-            $self->logger("body now looks like:\n${$self}{body}",'ttrace') if($is_tt_switch_active);
-        }
-        # otherwise the blank line has been deleted, so we compensate with an extra
-        if(${$self}{body} =~ m/(^\h*)?$blankLineToken/m){
-            $self->logger("Replacing blank line token that doesn't take up whole line",'heading') if $is_tt_switch_active;
-            ${$self}{body} =~ s/(^\h*)?$blankLineToken/$1?"\n".$1:"\n"/me;
-            $self->logger("body now looks like:\n${$self}{body}",'ttrace') if($is_tt_switch_active);
-        }
+        ${$self}{body} =~ s/^\h*$blankLineToken$//mg;
+
+        # when there's stuff *after* the blank line token
+        ${$self}{body} =~ s/(^\h*)$blankLineToken/"\n".$1/meg;
+
+        # when there is stuff before and after the blank line token
+        ${$self}{body} =~ s/^(.*?)$blankLineToken\h*(.*?)\h*$/$1."\n".($2?"\n".$2:$2)/meg;
+
+        # when there is only stuff *after* the blank line token
+        ${$self}{body} =~ s/^$blankLineToken\h*(.*?)$/$1."\n"/emg;
     }
     $self->logger("Finished unprotecting lines (see preserveBlankLines)",'heading') if $is_t_switch_active;
     $self->logger("body now looks like ${$self}{body}",'ttrace') if($is_tt_switch_active);
diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/Command.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/Command.pm
index 70712a03626..db876c4c8c5 100755
--- a/Master/texmf-dist/scripts/latexindent/LatexIndent/Command.pm
+++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/Command.pm
@@ -43,11 +43,28 @@ sub construct_command_regexp{
                                                                     mode=>"lineBreaksAtEnd",
                                                                     stringBetweenArguments=>1);
 
+    # put together a list of the special command names (this was mostly motivated by the \@ifnextchar[ issue)
+    my %commandNameSpecial = %{${$masterSettings{commandCodeBlocks}}{commandNameSpecial}};
+
+    my $commandNameSpecialRegExp = q();
+    while( my ($commandName,$yesNo)= each %commandNameSpecial){
+        # change + and - to escaped characters
+        $commandName =~ s/\+/\\+/g;
+        $commandName =~ s/\-/\\-/g;
+        $commandName =~ s/\[/\\[/g;
+
+        # form the regexp
+        $commandNameSpecialRegExp .= ($commandNameSpecialRegExp eq '' ? q() : "|").$commandName if $yesNo; 
+    }
+
+    # details to log file
+    $self->logger("The special command names regexp is: $commandNameSpecialRegExp (see commandNameSpecial)",'heading') if $is_t_switch_active;
+
     # construct the command regexp
     $commandRegExp = qr/
-              (\\|@)   
+              (\\|\\@|@)   
               (
-               [+a-zA-Z@\*0-9_\:]+? # lowercase|uppercase letters, @, *, numbers
+               [+a-zA-Z@\*0-9_\:]+?|$commandNameSpecialRegExp      # lowercase|uppercase letters, @, *, numbers
               )                
               (\h*)
               (\R*)?
@@ -104,6 +121,13 @@ sub tasks_particular_to_each_object{
         ${${$self}{linebreaksAtEnd}}{end} = ${${${${${$self}{children}}[0]}{children}[-1]}{linebreaksAtEnd}}{end};
         ${$self}{replacementText} .= "\n";
 
+        # if the last argument has EndFinishesWithLineBreak == 3
+        if (${${${${$self}{children}}[0]}{children}[-1]}{EndFinishesWithLineBreak} == 3 ){
+              my $EndStringLogFile = ${${${${$self}{children}}[0]}{children}[-1]}{aliases}{EndFinishesWithLineBreak}||"EndFinishesWithLineBreak";
+              $self->logger("Adding another blank line to replacement text for ${$self}{name} as last argument has $EndStringLogFile == 3 ") if $is_t_switch_active;
+              ${$self}{replacementText} .= (${$masterSettings{modifyLineBreaks}}{preserveBlankLines}?$tokens{blanklines}:"\n")."\n";
+        }
+
         # update the argument object
         $self->logger("Adjusting argument object in command, ${$self}{name}") if $is_t_switch_active;
         ${${${${$self}{children}}[0]}{linebreaksAtEnd}}{body} = 0;
diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/Document.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/Document.pm
index 93d8c404928..8697c20e86c 100644
--- a/Master/texmf-dist/scripts/latexindent/LatexIndent/Document.pm
+++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/Document.pm
@@ -30,7 +30,7 @@ use LatexIndent::BlankLines qw/protect_blank_lines unprotect_blank_lines condens
 use LatexIndent::ModifyLineBreaks qw/modify_line_breaks_body modify_line_breaks_end remove_line_breaks_begin adjust_line_breaks_end_parent max_char_per_line paragraphs_on_one_line construct_paragraph_reg_exp/;
 use LatexIndent::TrailingComments qw/remove_trailing_comments put_trailing_comments_back_in add_comment_symbol construct_trailing_comment_regexp/;
 use LatexIndent::HorizontalWhiteSpace qw/remove_trailing_whitespace remove_leading_space/;
-use LatexIndent::Indent qw/indent wrap_up_statement determine_total_indentation indent_begin indent_body indent_end_statement final_indentation_check  get_surrounding_indentation indent_children_recursively check_for_blank_lines_at_beginning put_blank_lines_back_in_at_beginning add_surrounding_indentation_to_begin_statement/;
+use LatexIndent::Indent qw/indent wrap_up_statement determine_total_indentation indent_begin indent_body indent_end_statement final_indentation_check  get_surrounding_indentation indent_children_recursively check_for_blank_lines_at_beginning put_blank_lines_back_in_at_beginning add_surrounding_indentation_to_begin_statement post_indentation_check/;
 use LatexIndent::Tokens qw/token_check %tokens/;
 use LatexIndent::HiddenChildren qw/find_surrounding_indentation_for_children update_family_tree get_family_tree check_for_hidden_children/;
 use LatexIndent::AlignmentAtAmpersand qw/align_at_ampersand find_aligned_block/;
@@ -39,7 +39,8 @@ use LatexIndent::DoubleBackSlash qw/dodge_double_backslash un_dodge_double_backs
 # code blocks
 use LatexIndent::Verbatim qw/put_verbatim_back_in find_verbatim_environments find_noindent_block find_verbatim_commands  put_verbatim_commands_back_in/;
 use LatexIndent::Environment qw/find_environments/;
-use LatexIndent::IfElseFi qw/find_ifelsefi/;
+use LatexIndent::IfElseFi qw/find_ifelsefi construct_ifelsefi_regexp/;
+use LatexIndent::Else qw/check_for_else_statement/;
 use LatexIndent::Arguments qw/get_arguments_regexp find_opt_mand_arguments get_numbered_arg_regexp construct_arguments_regexp/;
 use LatexIndent::OptionalArgument qw/find_optional_arguments/;
 use LatexIndent::MandatoryArgument qw/find_mandatory_arguments get_mand_arg_reg_exp/;
@@ -109,6 +110,7 @@ sub operate_on_file{
 sub construct_regular_expressions{
     my $self = shift;
     $self->construct_trailing_comment_regexp;
+    $self->construct_ifelsefi_regexp;
     $self->construct_list_of_items;
     $self->construct_special_begin;
     $self->construct_headings_levels;
@@ -171,25 +173,20 @@ sub find_objects{
     my $self = shift;
 
     # search for environments
-    $self->logger('looking for ENVIRONMENTS');
+    $self->logger('looking for ENVIRONMENTS') if $is_t_switch_active;
     $self->find_environments;
 
     # search for ifElseFi blocks
-    $self->logger('looking for IFELSEFI');
+    $self->logger('looking for IFELSEFI') if $is_t_switch_active;
     $self->find_ifelsefi;
 
     # search for headings (part, chapter, section, setc)
-    $self->logger('looking for HEADINGS (chapter, section, part, etc)');
+    $self->logger('looking for HEADINGS (chapter, section, part, etc)') if $is_t_switch_active;
     $self->find_heading;
-    
-    # search for commands with arguments
-    $self->logger('looking for COMMANDS and key = {value}');
-    $self->find_commands_or_key_equals_values_braces;
-
-    # search for special begin/end
-    $self->logger('looking for SPECIAL begin/end');
-    $self->find_special;
 
+    # the ordering of finding commands and special code blocks can change
+    $self->find_commands_or_key_equals_values_braces_and_special;
+    
     # documents without preamble need a manual call to the paragraph_one_line routine
     if ($is_m_switch_active and !${$self}{preamblePresent}){
         ${$self}{removeParagraphLineBreaks} = ${$masterSettings{modifyLineBreaks}{removeParagraphLineBreaks}}{all}||${$masterSettings{modifyLineBreaks}{removeParagraphLineBreaks}}{masterDocument}||0;
@@ -198,7 +195,7 @@ sub find_objects{
 
     # if there are no children, return
     if(${$self}{children}){
-        $self->logger("Objects have been found.",'heading');
+        $self->logger("Objects have been found.",'heading') if $is_t_switch_active;
     } else {
         $self->logger("No objects found.");
         return;
@@ -206,10 +203,34 @@ sub find_objects{
 
     # logfile information
     $self->logger(Dumper(\%{$self}),'ttrace') if($is_tt_switch_active);
-    $self->logger("Operating on: ${$self}{name}",'heading');
-    $self->logger("Number of children:",'heading');
-    $self->logger(scalar (@{${$self}{children}}));
+    $self->logger("Operating on: ${$self}{name}",'heading')if $is_t_switch_active;
+    $self->logger("Number of children: ".scalar (@{${$self}{children}})) if $is_t_switch_active;
+
+    return;
+}
 
+sub find_commands_or_key_equals_values_braces_and_special{
+    my $self = shift;
+
+    # the order in which we search for specialBeginEnd and commands/key/braces
+    # can change depending upon specialBeforeCommand
+    if(${$masterSettings{specialBeginEnd}}{specialBeforeCommand}){
+        # search for special begin/end
+        $self->logger('looking for SPECIAL begin/end *before* looking for commands (see specialBeforeCommand)') if $is_t_switch_active;
+        $self->find_special;
+
+        # search for commands with arguments
+        $self->logger('looking for COMMANDS and key = {value}') if $is_t_switch_active;
+        $self->find_commands_or_key_equals_values_braces;
+    } else {
+        # search for commands with arguments
+        $self->logger('looking for COMMANDS and key = {value}') if $is_t_switch_active;
+        $self->find_commands_or_key_equals_values_braces;
+
+        # search for special begin/end
+        $self->logger('looking for SPECIAL begin/end') if $is_t_switch_active;
+        $self->find_special;
+    }
     return;
 }
 
diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/Else.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/Else.pm
new file mode 100644
index 00000000000..878a68dc1cb
--- /dev/null
+++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/Else.pm
@@ -0,0 +1,109 @@
+package LatexIndent::Else;
+#	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/.
+#
+#	Chris Hughes, 2017
+#
+#	For all communication, please visit: https://github.com/cmhughes/latexindent.pl
+use strict;
+use warnings;
+use LatexIndent::Tokens qw/%tokens/;
+use LatexIndent::TrailingComments qw/$trailingCommentRegExp/;
+use LatexIndent::Switches qw/$is_m_switch_active $is_t_switch_active $is_tt_switch_active/;
+use Data::Dumper;
+use Exporter qw/import/;
+our @ISA = "LatexIndent::Document"; # class inheritance, Programming Perl, pg 321
+our @EXPORT_OK = qw/check_for_else_statement/;
+our $elseCounter;
+
+# store the regular expresssion for matching and replacing the \else statements
+our $elseRegExp = qr/
+                  (
+                    \\else  
+                    \h*     # possible horizontal space
+                    (\R*)   # possible line breaks after \else statement
+                  )
+                  (.*?)$
+            /sx;
+
+sub check_for_else_statement{
+    my $self = shift;
+    $self->logger("Looking for \\else statement (${$self}{name})",'heading') if $is_t_switch_active;
+
+    ${$self}{body} =~ s/$elseRegExp(\h*)($trailingCommentRegExp)?
+                       /   # log file output
+                      $self->logger("else found: ${$self}{name}",'heading')if $is_t_switch_active;
+         
+                      # create a new IfElseFi object
+                      my $else = LatexIndent::Else->new(begin=>$1,
+                                                              name=>${$self}{name},
+                                                              storageNameAppend=>"else",
+                                                              body=>$3,
+                                                              end=>q(),
+                                                              linebreaksAtEnd=>{
+                                                                begin=>$2?1:0,
+                                                                body=>0,
+                                                                end=>0,
+                                                              },
+                                                              aliases=>{
+                                                                # begin statements
+                                                                BeginStartsOnOwnLine=>"ElseStartsOnOwnLine",
+                                                                # end statements
+                                                                BodyStartsOnOwnLine=>"ElseFinishesWithLineBreak",
+                                                              },
+                                                              modifyLineBreaksYamlName=>"ifElseFi",
+                                                              endImmediatelyFollowedByComment=>0,
+                                                              horizontalTrailingSpace=>q(),
+                                                            );
+                      # the settings and storage of most objects has a lot in common
+                      $self->get_settings_and_store_new_object($else);
+                      ${@{${$self}{children}}[-1]}{replacementText};
+                      /xse;
+        return;
+}
+
+sub remove_line_breaks_begin{
+    # the \else command can need a trailing white space if the line breaks have been removed after it and
+    # there is no white space
+    my $self = shift;
+    my $BodyStringLogFile = ${$self}{aliases}{BodyStartsOnOwnLine}||"BodyStartsOnOwnLine";
+    $self->logger("Removing linebreak at the end of begin (see $BodyStringLogFile)");
+    ${$self}{begin} =~ s/\R*$//sx;
+    ${$self}{begin} .= " " unless(${$self}{begin} =~ m/\h$/s or ${$self}{body} =~ m/^\h/s or ${$self}{body} =~ m/^\R/s );
+    ${$self}{linebreaksAtEnd}{begin} = 0;
+}
+
+sub tasks_particular_to_each_object{
+    my $self = shift;
+
+    # search for headings (important to do this before looking for commands!)
+    $self->find_heading;
+
+    # search for commands and special code blocks
+    $self->find_commands_or_key_equals_values_braces_and_special;
+    return;
+}
+
+sub get_indentation_information{
+    return q();
+}
+
+sub create_unique_id{
+    my $self = shift;
+
+    $elseCounter++;
+
+    ${$self}{id} = "$tokens{else}$elseCounter";
+    return;
+}
+
+1;
diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/Environment.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/Environment.pm
index 2f6afe07e4b..0dd2fa80174 100755
--- a/Master/texmf-dist/scripts/latexindent/LatexIndent/Environment.pm
+++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/Environment.pm
@@ -103,8 +103,8 @@ sub tasks_particular_to_each_object{
     # search for headings (important to do this before looking for commands!)
     $self->find_heading;
 
-    # search for commands, keys, named grouping braces
-    $self->find_commands_or_key_equals_values_braces;
+    # search for commands and special code blocks
+    $self->find_commands_or_key_equals_values_braces_and_special;
 
     # search for arguments
     $self->find_opt_mand_arguments;
@@ -112,8 +112,6 @@ sub tasks_particular_to_each_object{
     # search for ifElseFi blocks
     $self->find_ifelsefi;
 
-    # search for special begin/end
-    $self->find_special;
 }
 
 sub create_unique_id{
diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/FileContents.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/FileContents.pm
index d4d13507a13..802b2a1ef9d 100644
--- a/Master/texmf-dist/scripts/latexindent/LatexIndent/FileContents.pm
+++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/FileContents.pm
@@ -34,11 +34,11 @@ sub find_file_contents_environments_and_preamble{
     my @fileContentsStorageArray; 
 
     # fileContents environments
-    $self->logger('looking for FILE CONTENTS environments (see fileContentsEnvironments)','heading');
+    $self->logger('looking for FILE CONTENTS environments (see fileContentsEnvironments)','heading') if $is_t_switch_active;
     $self->logger(Dumper(\%{$masterSettings{fileContentsEnvironments}})) if($is_t_switch_active);
     while( my ($fileContentsEnv,$yesno)= each %{$masterSettings{fileContentsEnvironments}}){
         if($yesno){
-            $self->logger("looking for $fileContentsEnv:$yesno environments");
+            $self->logger("looking for $fileContentsEnv:$yesno environments") if $is_t_switch_active;
 
             # the trailing * needs some care
             if($fileContentsEnv =~ m/\*$/){
@@ -119,7 +119,7 @@ sub find_file_contents_environments_and_preamble{
     # try and find the preamble
     if( ${$self}{body} =~ m/$preambleRegExp/sx and ${$masterSettings{lookForPreamble}}{${$self}{fileExtension}}){
 
-        $self->logger("\\begin{document} found in body (after searching for filecontents)-- assuming that a preamble exists");
+        $self->logger("\\begin{document} found in body (after searching for filecontents)-- assuming that a preamble exists",'heading') if $is_t_switch_active ;
 
         # create a preamble object
         $preamble = LatexIndent::Preamble->new( begin=>q(),
@@ -142,19 +142,19 @@ sub find_file_contents_environments_and_preamble{
         $preamble->get_replacement_text;
 
         # log file output
-        $self->logger("preamble found: $preamble");
+        $self->logger("preamble found: $preamble") if $is_t_switch_active;
 
         # remove the environment block, and replace with unique ID
         ${$self}{body} =~ s/$preambleRegExp/${$preamble}{replacementText}/sx;
 
-        $self->logger("replaced with ID: ${$preamble}{replacementText}");
+        $self->logger("replaced with ID: ${$preamble}{replacementText}") if $is_t_switch_active;
         # indentPreamble set to 1
         if($masterSettings{indentPreamble}){
             $self->logger("storing ${$preamble}{id} for indentation (see indentPreamble)");
             $needToStorePreamble = 1;
         } else {
             # indentPreamble set to 0
-            $self->logger("NOT storing ${$preamble}{id} for indentation -- will store as VERBATIM object (see indentPreamble)");
+            $self->logger("NOT storing ${$preamble}{id} for indentation -- will store as VERBATIM object (see indentPreamble)") if $is_t_switch_active;
             $preamble->unprotect_blank_lines;
             ${$self}{verbatim}{${$preamble}{id}} = $preamble;
         }
@@ -220,13 +220,8 @@ sub tasks_particular_to_each_object{
     # search for headings (part, chapter, section, setc)
     $self->find_heading;
     
-    # search for commands with arguments
-    $self->find_commands_or_key_equals_values_braces;
-
-    # search for special begin/end
-    $self->find_special;
-
-
+    # search for commands and special code blocks
+    $self->find_commands_or_key_equals_values_braces_and_special;
 }
 
 1;
diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/GetYamlSettings.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/GetYamlSettings.pm
index 0d51d5837db..bb0e47f2576 100644
--- a/Master/texmf-dist/scripts/latexindent/LatexIndent/GetYamlSettings.pm
+++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/GetYamlSettings.pm
@@ -36,7 +36,7 @@ sub readSettings{
   my $self = shift;
   
   $defaultSettings = YAML::Tiny->read( "$FindBin::RealBin/defaultSettings.yaml" );
-  $self->logger("YAML settings read",'heading');
+  $self->logger("YAML settings read: defaultSettings.yaml",'heading');
   $self->logger("Reading defaultSettings.yaml from $FindBin::RealBin/defaultSettings.yaml");
   
   # if latexindent.exe is invoked from TeXLive, then defaultSettings.yaml won't be in 
@@ -60,6 +60,7 @@ sub readSettings{
   
   # we'll need the home directory a lot in what follows
   my $homeDir = File::HomeDir->my_home; 
+  $self->logger("YAML settings read: indentconfig.yaml or .indentconfig.yaml",'heading');
   
   # get information about user settings- first check if indentconfig.yaml exists
   my $indentconfig = "$homeDir/indentconfig.yaml";
@@ -91,7 +92,9 @@ sub readSettings{
      if($switches{onlyDefault}) {
         $self->logger("Only default settings requested, not reading USER settings from $indentconfig");
         $self->logger("Ignoring $switches{readLocalSettings} (you used the -d switch)") if($switches{readLocalSettings});
+        $self->logger("Ignoring the -y switch: $switches{yaml} (you used the -d switch)") if($switches{yaml});
         $switches{readLocalSettings}=0;
+        $switches{yaml}=0;
      } else {
        # give the user instructions on where to put indentconfig.yaml or .indentconfig.yaml
        $self->logger("Home directory is $homeDir (didn't find either indentconfig.yaml or .indentconfig.yaml)");
@@ -100,11 +103,6 @@ sub readSettings{
      }
   }
 
-  # get information about LOCAL settings, assuming that $readLocalSettings exists
-  my $directoryName = dirname (${$self}{fileName});
-  
-  my @localSettings;
-
   # local settings can be called with a + symbol, for example
   #     -l=+myfile.yaml
   #     -l "+ myfile.yaml"
@@ -117,6 +115,14 @@ sub readSettings{
   # and
   #     -l + myfile.yaml
   # will *only* load localSettings.yaml, and myfile.yaml will be ignored
+  my @localSettings;
+
+  $self->logger("YAML settings read: -l switch",'heading') if $switches{readLocalSettings};
+
+  # remove leading, trailing, and intermediate space
+  $switches{readLocalSettings} =~ s/^\h*//g;
+  $switches{readLocalSettings} =~ s/\h*$//g;
+  $switches{readLocalSettings} =~ s/\h*,\h*/,/g;
   if($switches{readLocalSettings} =~ m/\+/){
         $self->logger("+ found in call for -l switch: will add localSettings.yaml");
 
@@ -132,7 +138,7 @@ sub readSettings{
   #     -l = myyaml1.yaml,myyaml2.yaml
   # and in which case, we need to read them all
   if($switches{readLocalSettings} =~ m/,/){
-        $self->logger("Multiple localSettings found, separated by commas:",'heading');
+        $self->logger("Multiple localSettings found, separated by commas:");
         @localSettings = split(/,/,$switches{readLocalSettings});
   } else {
     push(@localSettings,$switches{readLocalSettings}) if($switches{readLocalSettings});
@@ -141,21 +147,30 @@ sub readSettings{
   # add local settings to the paths, if appropriate
   foreach (@localSettings) {
     # check for an extension (.yaml)
-    my ($dir, $name, $ext) = fileparse($_, "yaml");
+    my ($name, $dir , $ext) = fileparse($_, "yaml");
 
     # if no extension is found, append the current localSetting with .yaml
     $_ = $_.($_=~m/\.\z/ ? q() : ".")."yaml" if(!$ext);
 
+    # if the -l switch is called on its own, or else with +
+    # and latexindent.pl is called from a different directory, then
+    # we need to account for this
+    if($_ eq "localSettings.yaml"){
+        $_ = dirname (${$self}{fileName})."/".$_;
+    }
+
     # check for existence and non-emptiness
-    if ( (-e "$directoryName/$_") and !(-z "$directoryName/$_")) {
-        $self->logger("Adding $directoryName/$_ to YAML read paths");
-        push(@absPaths,"$directoryName/$_");
-    } elsif ( !(-e "$directoryName/$_") ) {
-          $self->logger("WARNING yaml file not found: $directoryName/$_ not found");
-          $self->logger("Proceeding without it.");
+    if ( (-e $_) and !(-z $_)) {
+        $self->logger("Adding $_ to YAML read paths");
+        push(@absPaths,"$_");
+    } elsif ( !(-e $_) ) {
+          $self->logger("WARNING yaml file not found: $_ not found. Proceeding without it.");
     }
   }
 
+  # heading for the log file
+  $self->logger("YAML settings, reading from the following files:",'heading') if @absPaths;
+
   # read in the settings from each file
   foreach my $settings (@absPaths) {
     # check that the settings file exists and that it isn't empty
@@ -221,6 +236,145 @@ sub readSettings{
     }
   }
 
+  # read settings from -y|--yaml switch
+  if($switches{yaml}){
+        # report to log file
+        $self->logger("YAML settings read: -y switch",'heading');
+
+        # remove any horizontal space before or after , OR : OR ; or at the beginning or end of the switch value
+        $switches{yaml} =~ s/\h*(,|:|;)\h*/$1/g;
+        $switches{yaml} =~ s/^\h*//g;
+
+        # store settings, possibly multiple ones split by commas
+        my @yamlSettings;
+        if($switches{yaml} =~ m/,/){
+            @yamlSettings = split(/,/,$switches{yaml});
+        } else {
+            push(@yamlSettings,$switches{yaml});
+        }
+
+        # it is possible to specify, for example,
+        #
+        #   -y=indentAfterHeadings:paragraph:indentAfterThisHeading:1;level:1
+        #   -y=specialBeginEnd:displayMath:begin:'\\\[';end: '\\\]';lookForThis: 1
+        #
+        # which should be translated into
+        #
+        #   indentAfterHeadings:
+        #       paragraph:
+        #           indentAfterThisHeading:1
+        #           level:1
+        #
+        # so we need to loop through the comma separated list and search 
+        # for semi-colons
+        my $settingsCounter=0;
+        my @originalYamlSettings = @yamlSettings;
+        foreach(@originalYamlSettings){
+            # increment the counter
+            $settingsCounter++;
+
+            # check for a match of the ;
+            if($_ =~ m/;/){
+                my (@subfield) = split(/;/,$_);
+
+                # the content up to the first ; is called the 'root'
+                my $root = shift @subfield;
+
+                # split the root at :
+                my (@keysValues) = split(/:/,$root);
+
+                # get rid of the last *two* elements, which will be 
+                #   key: value
+                # for example, in
+                #   -y=indentAfterHeadings:paragraph:indentAfterThisHeading:1;level:1
+                # then @keysValues holds
+                #   indentAfterHeadings:paragraph:indentAfterThisHeading:1
+                # so we need to get rid of both
+                #    1
+                #    indentAfterThisHeading
+                # so that we are in a position to concatenate
+                #   indentAfterHeadings:paragraph
+                # with 
+                #   level:1
+                # to form
+                #   indentAfterHeadings:paragraph:level:1
+                pop(@keysValues);
+                pop(@keysValues);
+
+                # update the appropriate piece of the -y switch, for example:
+                #   -y=indentAfterHeadings:paragraph:indentAfterThisHeading:1;level:1
+                # needs to be changed to
+                #   -y=indentAfterHeadings:paragraph:indentAfterThisHeading:1
+                # the 
+                #   indentAfterHeadings:paragraph:level:1
+                # will be added in the next part
+                $yamlSettings[$settingsCounter-1] = $root;
+
+                # reform the root
+                $root = join(":",@keysValues);
+                $self->logger("Sub-field detected (; present) and the root is: $root") if $is_t_switch_active;
+
+                # now we need to attach the $root back together with any subfields
+                foreach(@subfield){
+                   # splice the new field into @yamlSettings (reference: https://perlmaven.com/splice-to-slice-and-dice-arrays-in-perl)
+                   splice @yamlSettings,$settingsCounter,0,$root.":".$_; 
+                   
+                   # increment the counter
+                   $settingsCounter++;
+                }
+                $self->logger("-y switch value interpreted as: ".join(',',@yamlSettings));
+            }
+        }
+
+        # loop through each of the settings specified in the -y switch
+        foreach(@yamlSettings){
+            # split each value at semi-colon
+            my (@keysValues) = split(/:/,$_);
+
+            # $value will always be the last element
+            my $value = $keysValues[-1];
+
+            # horizontal space needs special treatment
+            if($value =~ m/^(?:"|')(\h*)(?:"|')$/){
+                # pure horizontal space
+                $value = $1;
+            } elsif($value =~ m/^(?:"|')((?:\\t)*)(?:"|')$/){
+                # tabs
+                $value =~ s/^(?:"|')//;
+                $value =~ s/(?:"|')$//;
+                $value =~ s/\\t/\t/g;
+            }
+
+            if(scalar(@keysValues) == 2){
+                # for example, -y="defaultIndent: ' '"
+                my $key = $keysValues[0];
+                $self->logger("Updating masterSettings with $key: $value");
+                $masterSettings{$key} = $value;
+            } elsif(scalar(@keysValues) == 3){
+                # for example, -y="indentRules: one: '\t\t\t\t'"
+                my $parent = $keysValues[0];
+                my $child = $keysValues[1];
+                $self->logger("Updating masterSettings with $parent: $child: $value");
+                $masterSettings{$parent}{$child} = $value;
+            } elsif(scalar(@keysValues) == 4){
+                # for example, -y='modifyLineBreaks  :  environments: EndStartsOnOwnLine:3' -m
+                my $parent = $keysValues[0];
+                my $child = $keysValues[1];
+                my $grandchild = $keysValues[2];
+                $self->logger("Updating masterSettings with $parent: $child: $grandchild: $value");
+                $masterSettings{$parent}{$child}{$grandchild} = $value;
+            } elsif(scalar(@keysValues) == 5){
+                # for example, -y='modifyLineBreaks  :  environments: one: EndStartsOnOwnLine:3' -m
+                my $parent = $keysValues[0];
+                my $child = $keysValues[1];
+                my $grandchild = $keysValues[2];
+                my $greatgrandchild = $keysValues[3];
+                $self->logger("Updating masterSettings with $parent: $child: $grandchild: $greatgrandchild: $value");
+                $masterSettings{$parent}{$child}{$grandchild}{$greatgrandchild} = $value;
+            }
+          }
+  }
+
   # some users may wish to see showAmalgamatedSettings
   # which details the overall state of the settings modified
   # from the default in various user files
@@ -236,7 +390,7 @@ sub get_indentation_settings_for_this_object{
     my $self = shift;
 
     # create a name for previously found settings
-    my $storageName = ${$self}{name}.${$self}{modifyLineBreaksYamlName};
+    my $storageName = ${$self}{name}.${$self}{modifyLineBreaksYamlName}.(defined ${$self}{storageNameAppend}?${$self}{storageNameAppend}:q());
 
     # check for storage of repeated objects
     if ($previouslyFoundSettings{$storageName}){
@@ -371,8 +525,10 @@ sub modify_line_breaks_settings{
         $self->logger("$YamlName specified with fields in removeParagraphLineBreaks, looking for $name") if $is_t_switch_active;
         ${$self}{removeParagraphLineBreaks} = ${${$masterSettings{modifyLineBreaks}{removeParagraphLineBreaks}}{$YamlName}}{$name}||0;
     } else {
-        $self->logger("$YamlName specified with just a number in removeParagraphLineBreaks ${$masterSettings{modifyLineBreaks}{removeParagraphLineBreaks}}{$YamlName}") if $is_t_switch_active;
-        ${$self}{removeParagraphLineBreaks} = ${$masterSettings{modifyLineBreaks}{removeParagraphLineBreaks}}{$YamlName};
+        if(defined ${$masterSettings{modifyLineBreaks}{removeParagraphLineBreaks}}{$YamlName}){
+            $self->logger("$YamlName specified with just a number in removeParagraphLineBreaks ${$masterSettings{modifyLineBreaks}{removeParagraphLineBreaks}}{$YamlName}") if $is_t_switch_active;
+            ${$self}{removeParagraphLineBreaks} = ${$masterSettings{modifyLineBreaks}{removeParagraphLineBreaks}}{$YamlName};
+        }
     }
     return;
 }
diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/Heading.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/Heading.pm
index 6cca3c26695..9a2f7187531 100644
--- a/Master/texmf-dist/scripts/latexindent/LatexIndent/Heading.pm
+++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/Heading.pm
@@ -86,7 +86,7 @@ sub construct_headings_levels{
             # make the stars escaped correctly
             $headingsAtThisLevel =~ s/\*/\\\*/g;
             push(@headingsRegexpArray,$headingsAtThisLevel);
-            $self->logger("Heading level regexp for level $i will contain: $headingsAtThisLevel");
+            $self->logger("Heading level regexp for level $i will contain: $headingsAtThisLevel") if $is_t_switch_active;
         }
     }
   }
@@ -99,7 +99,7 @@ sub find_heading{
     my $self = shift;
 
     # otherwise loop through the headings regexp
-    $self->logger("Searching for special begin/end (see specialBeginEnd)");
+    $self->logger("Searching for headings ") if $is_t_switch_active;
 
     # loop through each headings match; note that we need to 
     # do it in *reverse* so as to ensure that the lower level headings get matched first of all
diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/IfElseFi.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/IfElseFi.pm
index 04753f81a87..5e4040d5cef 100755
--- a/Master/texmf-dist/scripts/latexindent/LatexIndent/IfElseFi.pm
+++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/IfElseFi.pm
@@ -22,13 +22,15 @@ use LatexIndent::Switches qw/$is_m_switch_active $is_t_switch_active $is_tt_swit
 use Data::Dumper;
 use Exporter qw/import/;
 our @ISA = "LatexIndent::Document"; # class inheritance, Programming Perl, pg 321
-our @EXPORT_OK = qw/find_ifelsefi/;
-our %previouslyFoundSettings;
+our @EXPORT_OK = qw/find_ifelsefi construct_ifelsefi_regexp/;
 our $ifElseFiCounter;
+our $ifElseFiRegExp;
 
 # store the regular expresssion for matching and replacing the \if...\else...\fi statements
 # note: we search for \else separately in an attempt to keep this regexp a little more managable
-our $ifElseFiRegExp = qr/
+
+sub construct_ifelsefi_regexp{
+    $ifElseFiRegExp = qr/
                 (
                     \\
                         (@?if[a-zA-Z@]*?)
@@ -36,7 +38,7 @@ our $ifElseFiRegExp = qr/
                     (\R*)
                 )                           # begin statement, e.g \ifnum, \ifodd
                 (
-                    \\(?!if)|[0-9]|\R|\h|\#|!-!   # up until a \\, linebreak # or !-!, which is 
+                    \\(?!if)|[0-9]|\R|\h|\#|!-!|$trailingCommentRegExp   # up until a \\, linebreak # or !-!, which is 
                 )                           # part of the tokens used for latexindent
                 (
                     (?: 
@@ -50,63 +52,6 @@ our $ifElseFiRegExp = qr/
                 (\h*)                       # 0 or more horizontal spaces
                 (\R)?                       # linebreaks after \fi
 /sx;
-
-
-sub indent{
-    my $self = shift;
-
-    # determine the surrounding and current indentation
-    $self->determine_total_indentation;
-
-    # line break checks after \if statement, can get messy if we 
-    # have, for example
-    #       \ifnum
-    #               something
-    # which might be changed into
-    #       \ifnumsomething
-    # which is undeserible
-    if (defined ${$self}{BodyStartsOnOwnLine}
-        and ${$self}{BodyStartsOnOwnLine}==-1 
-        and ${$self}{body} !~ m/^(\h|\\|(?:!-!))/s
-    ){
-        ${$self}{begin} .= " ";
-    }
-
-    # indent the body
-    $self->indent_body;
-
-    # calculate and grab the surrounding indentation for the \else statement adjustment
-    $self->get_surrounding_indentation;
-    my $surroundingIndentation = ${$self}{surroundingIndentation}?${$self}{surroundingIndentation}:q();
-
-    if(${$self}{elsePresent} and ${$self}{linebreaksAtEnd}{ifbody}){
-            $self->logger("Adding surrounding indentation to \\else statement ('$surroundingIndentation')")if $is_t_switch_active;
-            ${$self}{body} =~ s/\h*\\else/$surroundingIndentation\\else/; 
-            $self->logger("Body (${$self}{name}) after \\else adjustment:\n${$self}{body}") if $is_t_switch_active;
-    }
-
-    # indent the end statement
-    $self->indent_end_statement;
-
-    # wrap-up statement
-    $self->wrap_up_statement;
-
-    # line break checks *after* \end{statement}
-    if (defined ${$self}{EndFinishesWithLineBreak}
-        and ${$self}{EndFinishesWithLineBreak}==-1 
-        ) {
-        # add a single horizontal space after the child id, otherwise we can end up 
-        # with things like
-        #       before: 
-        #               \fi
-        #                   text
-        #       after:
-        #               \fitext
-        $self->logger("Adding a single space after \\fi statement (otherwise \\fi can be comined with next line of text in an unwanted way)",'heading') if $is_t_switch_active;
-        ${$self}{end} =${$self}{end}." ";
-    }
-
-    return $self;
 }
 
 sub find_ifelsefi{
@@ -139,9 +84,7 @@ sub find_ifelsefi{
                                                                   # after end statements
                                                                   EndFinishesWithLineBreak=>"FiFinishesWithLineBreak",
                                                                 },
-                                                                elsePresent=>0,
                                                                 modifyLineBreaksYamlName=>"ifElseFi",
-                                                                additionalAssignments=>["ElseStartsOnOwnLine","ElseFinishesWithLineBreak"],
                                                                 endImmediatelyFollowedByComment=>$9?0:($11?1:0),
                                                                 horizontalTrailingSpace=>$8?$8:q(),
                                                               );
@@ -154,6 +97,19 @@ sub find_ifelsefi{
     return;
 }
 
+sub post_indentation_check{
+    # needed to remove leading horizontal space before \else
+    my $self = shift;
+    if(${$self}{body} =~ m/^\h*\\else/sm
+                and
+       !(${$self}{body} =~ m/^\h*\\else/s and ${$self}{linebreaksAtEnd}{begin}==0)
+            ){
+        $self->logger("Adding surrounding indentation to \\else statement ('${$self}{surroundingIndentation}')") if $is_t_switch_active;
+        ${$self}{body} =~ s/^\h*\\else/${$self}{surroundingIndentation}\\else/sm;
+    }
+    return;
+}
+
 sub tasks_particular_to_each_object{
     my $self = shift;
 
@@ -163,20 +119,50 @@ sub tasks_particular_to_each_object{
     # search for headings (important to do this before looking for commands!)
     $self->find_heading;
 
-    # search for commands, keys, named grouping braces
-    $self->find_commands_or_key_equals_values_braces;
+    # search for commands and special code blocks
+    $self->find_commands_or_key_equals_values_braces_and_special;
 
-    # search for arguments
-    $self->find_opt_mand_arguments;
+}
 
-    # search for ifElseFi blocks
-    $self->find_ifelsefi;
+sub indent_begin{
+    my $self = shift;
+    # line break checks after \if statement, can get messy if we 
+    # have, for example
+    #       \ifnum
+    #               something
+    # which might be changed into
+    #       \ifnumsomething
+    # which is undeserible
+    if (defined ${$self}{BodyStartsOnOwnLine}
+        and ${$self}{BodyStartsOnOwnLine}==-1 
+        and ${$self}{body} !~ m/^(\h|\\|(?:!-!))/s
+    ){
+        ${$self}{begin} .= " ";
+    }
+}
 
-    # search for special begin/end
-    $self->find_special;
+sub wrap_up_statement{
+    my $self = shift;
 
+    # line break checks *after* \end{statement}
+    if (defined ${$self}{EndFinishesWithLineBreak}
+        and ${$self}{EndFinishesWithLineBreak}==-1 
+        ) {
+        # add a single horizontal space after the child id, otherwise we can end up 
+        # with things like
+        #       before: 
+        #               \fi
+        #                   text
+        #       after:
+        #               \fitext
+        $self->logger("Adding a single space after \\fi statement (otherwise \\fi can be comined with next line of text in an unwanted way)",'heading') if $is_t_switch_active;
+        ${$self}{end} =${$self}{end}." ";
+    }
+    $self->logger("Finished indenting ${$self}{name}",'heading') if $is_t_switch_active;
+    return $self;
 }
 
+
 sub create_unique_id{
     my $self = shift;
 
@@ -186,91 +172,5 @@ sub create_unique_id{
     return;
 }
 
-sub check_for_else_statement{
-    my $self = shift;
-    $self->logger("Looking for \\else statement (${$self}{name})",'heading') if $is_t_switch_active;
-    if(${$self}{body} =~ m/
-                            (\R*)   # possible line breaks before \else statement
-                            \\else  
-                            \h*     # possible horizontal space
-                            (\R*)   # possible line breaks after \else statement
-                            /x){
-      $self->logger("found \\else statement, storing line break information:") if($is_t_switch_active);
-
-      # linebreaks *before* \else statement
-      ${$self}{linebreaksAtEnd}{ifbody} = $1?1:0;
-      $self->logger("linebreaksAtEnd of ifbody: ${$self}{linebreaksAtEnd}{ifbody}") if($is_t_switch_active);
-
-      # linebreaks *after* \else statement
-      ${$self}{linebreaksAtEnd}{else} = $2?1:0;
-      $self->logger("linebreaksAtEnd of else: ${$self}{linebreaksAtEnd}{else}") if($is_t_switch_active);
-      ${$self}{elsePresent}=1;
-
-      # check that \else isn't the first thing in body
-      if(${$self}{body} =~ m/^\\else/s and ${$self}{linebreaksAtEnd}{begin}){
-        ${$self}{linebreaksAtEnd}{ifbody} = 1;
-        $self->logger("\\else *begins* the ifbody, linebreaksAtEnd of ifbody: ${$self}{linebreaksAtEnd}{ifbody}") if($is_t_switch_active);
-      }
-
-      # check if -m switch is active
-      return unless $is_m_switch_active;
-
-      # possibly modify line break *before* \else statement
-      if(defined ${$self}{ElseStartsOnOwnLine}){
-          if(${$self}{ElseStartsOnOwnLine}>=1 and !${$self}{linebreaksAtEnd}{ifbody}){
-              # by default, assume that no trailing comment token is needed
-              my $trailingCommentToken = q();
-              if(${$self}{ElseStartsOnOwnLine}==2){
-                $self->logger("Adding a % immediately before else statement of ${$self}{name} (ElseStartsOnOwnLine==2)") if $is_t_switch_active;
-                $trailingCommentToken = "%".$self->add_comment_symbol;
-              }
-
-              # add a line break after ifbody, if appropriate
-              $self->logger("Adding a linebreak before the \\else statement (see ElseStartsOnOwnLine)");
-              ${$self}{body} =~ s/\\else/$trailingCommentToken\n\\else/s;
-              ${$self}{linebreaksAtEnd}{ifbody} = 1;
-          } elsif (${$self}{ElseStartsOnOwnLine}==-1 and ${$self}{linebreaksAtEnd}{ifbody}){
-              # remove line break *after* ifbody, if appropriate
-              $self->logger("Removing linebreak before \\else statement (see ElseStartsOnOwnLine)");
-              ${$self}{body} =~ s/\R*(\h*)\\else/$1\\else/sx;
-              ${$self}{linebreaksAtEnd}{ifbody} = 0;
-          }
-      }
-
-      # possibly modify line break *before* \else statement
-      if(defined ${$self}{ElseFinishesWithLineBreak}){
-          if(${$self}{ElseFinishesWithLineBreak}>=1 and !${$self}{linebreaksAtEnd}{else}){
-              # by default, assume that no trailing comment token is needed
-              my $trailingCommentToken = q();
-              if(${$self}{ElseFinishesWithLineBreak}==2){
-                return if(${$self}{body} =~ m/\\else\h*$trailingCommentRegExp/s);
-                $self->logger("Adding a % immediately after else statement of ${$self}{name} (ElseFinishesWithLineBreak==2)") if $is_t_switch_active;
-                $trailingCommentToken = "%".$self->add_comment_symbol;
-              }
-
-              # add a line break after else, if appropriate
-              $self->logger("Adding a linebreak after the \\else statement (see ElseFinishesWithLineBreak)")if $is_t_switch_active;
-              ${$self}{body} =~ s/\\else\h*/\\else$trailingCommentToken\n/s;
-              ${$self}{linebreaksAtEnd}{else} = 1;
-          } elsif (${$self}{ElseFinishesWithLineBreak}==-1 and ${$self}{linebreaksAtEnd}{else}){
-              # remove line break *after* else, if appropriate, 
-              # note the space so that, for example,
-              #     \else
-              #             some text
-              # becomes
-              #     \else some text
-              # and not
-              #     \elsesome text
-              $self->logger("Removing linebreak after \\else statement (see ElseFinishesWithLineBreak)")if $is_t_switch_active;
-              ${$self}{body} =~ s/\\else\h*\R*/\\else /sx;
-              ${$self}{linebreaksAtEnd}{else} = 0;
-          }
-      }
-
-      return;
-    } else {
-      $self->logger("\\else statement not found") if($is_t_switch_active);
-    }
-}
 
 1;
diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/Indent.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/Indent.pm
index f0cf33aa23f..c9d05269d92 100644
--- a/Master/texmf-dist/scripts/latexindent/LatexIndent/Indent.pm
+++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/Indent.pm
@@ -19,9 +19,11 @@ use warnings;
 use LatexIndent::Tokens qw/%tokens/;
 use LatexIndent::Switches qw/$is_m_switch_active $is_t_switch_active $is_tt_switch_active/;
 use LatexIndent::HiddenChildren qw/%familyTree/;
+use LatexIndent::GetYamlSettings qw/%masterSettings/;
+use Text::Tabs;
 use Data::Dumper;
 use Exporter qw/import/;
-our @EXPORT_OK = qw/indent wrap_up_statement determine_total_indentation indent_begin indent_body indent_end_statement final_indentation_check push_family_tree_to_indent get_surrounding_indentation indent_children_recursively check_for_blank_lines_at_beginning put_blank_lines_back_in_at_beginning add_surrounding_indentation_to_begin_statement/;
+our @EXPORT_OK = qw/indent wrap_up_statement determine_total_indentation indent_begin indent_body indent_end_statement final_indentation_check push_family_tree_to_indent get_surrounding_indentation indent_children_recursively check_for_blank_lines_at_beginning put_blank_lines_back_in_at_beginning add_surrounding_indentation_to_begin_statement post_indentation_check/;
 our %familyTree;
 
 sub indent{
@@ -152,13 +154,15 @@ sub indent_body{
         }
     }
 
+    # some objects need a post-indentation check, e.g ifElseFi
+    $self->post_indentation_check;
     # if the routine check_for_blank_lines_at_beginning has been called, then the following routine
     # puts blank line tokens back in 
     $self->put_blank_lines_back_in_at_beginning if $is_m_switch_active; 
 
     # the final linebreak can be modified by a child object; see test-cases/commands/figureValign-mod5.tex, for example
-    if($is_m_switch_active and defined ${$self}{linebreaksAtEnd}{body} and ${$self}{linebreaksAtEnd}{body}==1 and ${$self}{body} !~ m/\R$/){
-        $self->logger("Updating body for ${$self}{name} to contain a linebreak at the end (linebreaksAtEnd is 1, but there isn't currently a linebreak)") if($is_t_switch_active);
+    if($is_m_switch_active and defined ${$self}{linebreaksAtEnd}{body} and ${$self}{linebreaksAtEnd}{body}==1 and ${$self}{body} !~ m/\R$/ and ${$self}{body} ne ''){
+        $self->logger("Adding a linebreak at end of body for ${$self}{name} to contain a linebreak at the end (linebreaksAtEnd is 1, but there isn't currently a linebreak)") if($is_t_switch_active);
         ${$self}{body} .= "\n";
     }
 
@@ -167,6 +171,10 @@ sub indent_body{
     return $self;
 }
 
+sub post_indentation_check{
+    return;
+}
+
 sub check_for_blank_lines_at_beginning{
     # some objects need this routine
     return;
@@ -221,9 +229,26 @@ sub final_indentation_check{
                         $after = "TAB"x$numberOfTABS.$after;
                         $self->logger("Indentation after: '$after'") if($is_t_switch_active);
                         ($indentation = $after) =~s|TAB|\t|g;
+
                         $indentation;
                        /xsmeg;
 
+    return unless($masterSettings{maximumIndentation} =~ m/^\h+$/);
+
+    # maximum indentation check
+    $self->logger("Maximum indentation check",'heading') if($is_t_switch_active);
+
+    # replace any leading tabs with spaces, and update the body
+    my @expanded_lines = expand(${$self}{body});
+    ${$self}{body} = join("",@expanded_lines);
+
+    # grab the maximum indentation
+    my $maximumIndentation = $masterSettings{maximumIndentation};
+    my $maximumIndentationLength = length($maximumIndentation)+1;
+
+    # replace any leading space that is greater than the 
+    # specified maximum indentation with the maximum indentation
+    ${$self}{body} =~ s/^\h{$maximumIndentationLength,}/$maximumIndentation/smg;
 }
 
 sub indent_children_recursively{
@@ -297,25 +322,32 @@ sub indent_children_recursively{
                 # line break checks before <begin statement>
                 if(defined ${$child}{BeginStartsOnOwnLine}){
                     my $BeginStringLogFile = ${$child}{aliases}{BeginStartsOnOwnLine}||"BeginStartsOnOwnLine";
+
+                    # if the child ID is not the first character and BeginStartsOnOwnLine>=1 
+                    # then we will need to add a line break (==1), a comment (==2) or another blank line (==3)
                     if(${$child}{BeginStartsOnOwnLine}>=1 and !$IDFirstNonWhiteSpaceCharacter){
                         # by default, assume that no trailing comment token is needed
-                        my $trailingCommentToken = q();
+                        my $trailingCharacterToken = q();
                         if(${$child}{BeginStartsOnOwnLine}==2){
                             $self->logger("Removing space immediately before ${$child}{id}, in preparation for adding % ($BeginStringLogFile == 2)") if $is_t_switch_active;
                             ${$self}{body} =~ s/\h*${$child}{id}/${$child}{id}/s;
                             $self->logger("Adding a % at the end of the line that ${$child}{begin} is on, then a linebreak ($BeginStringLogFile == 2)") if $is_t_switch_active;
-                            $trailingCommentToken = "%".$self->add_comment_symbol;
+                            $trailingCharacterToken = "%".$self->add_comment_symbol;
+                        } elsif (${$child}{BeginStartsOnOwnLine}==3){
+                            $self->logger("Adding a blank line at the end of the line that ${$child}{begin} is on, then a linebreak ($BeginStringLogFile == 3)") if $is_t_switch_active;
+                            $trailingCharacterToken = "\n".(${$masterSettings{modifyLineBreaks}}{preserveBlankLines}?$tokens{blanklines}:q());
                         } else {
                             $self->logger("Adding a linebreak at the beginning of ${$child}{begin} (see $BeginStringLogFile)") if $is_t_switch_active;
                         }
 
                         # the trailing comment/linebreak magic
-                        ${$child}{begin} = "$trailingCommentToken\n".${$child}{begin};
+                        ${$child}{begin} = "$trailingCharacterToken\n".${$child}{begin};
                         $child->add_surrounding_indentation_to_begin_statement;
 
                         # remove surrounding indentation ahead of %
                         ${$child}{begin} =~ s/^(\h*)%/%/ if(${$child}{BeginStartsOnOwnLine}==2);
                     } elsif (${$child}{BeginStartsOnOwnLine}==-1 and $IDFirstNonWhiteSpaceCharacter){
+                        # finally, if BeginStartsOnOwnLine == -1 then we might need to *remove* a blank line(s)
                         # important to check we don't move the begin statement next to a blank-line-token
                         my $blankLineToken = $tokens{blanklines};
                         if(${$self}{body} !~ m/$blankLineToken\R*\h*${$child}{id}/s){
diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/Item.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/Item.pm
index 1166282895d..4861cb9f82c 100644
--- a/Master/texmf-dist/scripts/latexindent/LatexIndent/Item.pm
+++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/Item.pm
@@ -37,7 +37,7 @@ sub construct_list_of_items{
     }
 
     # detail items in the log
-    $self->logger("List of items: $listOfItems (see itemNames)",'heading');
+    $self->logger("List of items: $listOfItems (see itemNames)",'heading') if $is_t_switch_active;
 
     $itemRegExp = qr/
                           (
@@ -127,11 +127,8 @@ sub tasks_particular_to_each_object{
     # search for headings (part, chapter, section, setc)
     $self->find_heading;
     
-    # search for commands with arguments
-    $self->find_commands_or_key_equals_values_braces;
-
-    # search for special begin/end
-    $self->find_special;
+    # search for commands and special code blocks
+    $self->find_commands_or_key_equals_values_braces_and_special;
 
 }
 
diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/LogFile.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/LogFile.pm
index fb7cb37ed00..128034a2881 100644
--- a/Master/texmf-dist/scripts/latexindent/LatexIndent/LogFile.pm
+++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/LogFile.pm
@@ -63,7 +63,7 @@ usage: latexindent.pl [options] [file][.tex|.sty|.cls|.bib|...]
           displays the version number and date of release
       -h, --help
           help (see the documentation for detailed instructions and examples)
-      -o, --outputfile
+      -o, --outputfile=<name-of-output-file>
           output to another file; sample usage:
                 latexindent.pl -o outputfile.tex myfile.tex 
                 latexindent.pl -o=outputfile.tex myfile.tex 
@@ -79,6 +79,10 @@ usage: latexindent.pl [options] [file][.tex|.sty|.cls|.bib|...]
                 latexindent.pl -l some.yaml myfile.tex 
                 latexindent.pl -l=another.yaml myfile.tex 
                 latexindent.pl -l=some.yaml,another.yaml myfile.tex 
+      -y, --yaml=<yaml settings>
+          specify YAML settings; sample usage:
+                latexindent.pl -y="defaultIndent:' '" myfile.tex
+                latexindent.pl -y="defaultIndent:' ',maximumIndentation:' '" myfile.tex
       -d, --onlydefault
           ONLY use defaultSettings.yaml, ignore ALL (yaml) user files
       -g, --logfile=<name of log file>
@@ -87,7 +91,7 @@ usage: latexindent.pl [options] [file][.tex|.sty|.cls|.bib|...]
           used to specify the location of backup files and indent.log
       -m, --modifylinebreaks
           modify linebreaks before, during, and at the end of code blocks; 
-          trailing comments can also be added using this feature
+          trailing comments and blank lines can also be added using this feature
 ENDQUOTE
     ;
     exit(2);
@@ -106,6 +110,7 @@ ENDQUOTE
     $self->logger('-d|--onlydefault: Only defaultSettings.yaml will be used (you have used either -d or --onlydefault)') if($switches{onlyDefault});
     $self->logger("-w|--overwrite: Overwrite mode active, will make a back up of ${$self}{fileName} first") if($switches{overwrite});
     $self->logger("-l|--localSettings: Read localSettings YAML file") if($switches{readLocalSettings});
+    $self->logger("-y|--yaml: YAML settings specified via command line") if($switches{yaml});
     $self->logger("-o|--outputfile: output to file") if($switches{outputToFile});
     $self->logger("-m|--modifylinebreaks: modify line breaks") if($switches{modifyLineBreaks});
     $self->logger("-g|--logfile: logfile name") if($switches{logFileName});
diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/ModifyLineBreaks.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/ModifyLineBreaks.pm
index 3f0148d4670..d527f5d7986 100644
--- a/Master/texmf-dist/scripts/latexindent/LatexIndent/ModifyLineBreaks.pm
+++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/ModifyLineBreaks.pm
@@ -35,6 +35,11 @@ sub modify_line_breaks_body{
     if(defined ${$self}{BodyStartsOnOwnLine}){
       my $BodyStringLogFile = ${$self}{aliases}{BodyStartsOnOwnLine}||"BodyStartsOnOwnLine";
       if(${$self}{BodyStartsOnOwnLine}>=1 and !${$self}{linebreaksAtEnd}{begin}){
+          # if the <begin> statement doesn't finish with a line break, 
+          # then we have different actions based upon the value of BodyStartsOnOwnLine:
+          #     BodyStartsOnOwnLine == 1 just add a new line
+          #     BodyStartsOnOwnLine == 2 add a comment, and then new line
+          #     BodyStartsOnOwnLine == 3 add a blank line, and then new line
           if(${$self}{BodyStartsOnOwnLine}==1){
             # modify the begin statement
             $self->logger("Adding a linebreak at the end of begin, ${$self}{begin} (see $BodyStringLogFile)") if $is_t_switch_active;
@@ -47,7 +52,7 @@ sub modify_line_breaks_body{
             my $trailingCommentToken = q();
             if(${$self}{body} !~ m/^\h*$trailingCommentRegExp/s){
                 # modify the begin statement
-                $self->logger("Adding a % at the end of begin, ${$self}{begin}, followed by a linebreak ($BodyStringLogFile == 2)") if $is_t_switch_active;
+                $self->logger("Adding a % at the end of begin ${$self}{begin} followed by a linebreak ($BodyStringLogFile == 2)") if $is_t_switch_active;
                 $trailingCommentToken = "%".$self->add_comment_symbol;
                 ${$self}{begin} =~ s/\h*$//;       
                 ${$self}{begin} .= "$trailingCommentToken\n";       
@@ -57,6 +62,14 @@ sub modify_line_breaks_body{
             } else {
                 $self->logger("Even though $BodyStringLogFile == 2, ${$self}{begin} already finishes with a %, so not adding another.") if $is_t_switch_active;
             }
+          } elsif (${$self}{BodyStartsOnOwnLine}==3){
+            my $trailingCharacterToken = q();
+            $self->logger("Adding a blank line at the end of begin ${$self}{begin} followed by a linebreak ($BodyStringLogFile == 3)") if $is_t_switch_active;
+            ${$self}{begin} =~ s/\h*$//;       
+            ${$self}{begin} .= (${$masterSettings{modifyLineBreaks}}{preserveBlankLines}?$tokens{blanklines}:"\n")."\n";       
+            ${$self}{linebreaksAtEnd}{begin} = 1;
+            $self->logger("Removing leading space from body of ${$self}{name} (see $BodyStringLogFile)") if $is_t_switch_active;
+            ${$self}{body} =~ s/^\h*//;       
           } 
        } elsif (${$self}{BodyStartsOnOwnLine}==-1 and ${$self}{linebreaksAtEnd}{begin}){
           # remove line break *after* begin, if appropriate
@@ -80,14 +93,22 @@ sub modify_line_breaks_end{
     if(defined ${$self}{EndStartsOnOwnLine}){
           my $EndStringLogFile = ${$self}{aliases}{EndStartsOnOwnLine}||"EndStartsOnOwnLine";
           if(${$self}{EndStartsOnOwnLine}>=1 and !${$self}{linebreaksAtEnd}{body}){
-              # add a line break after body, if appropriate
+              # if the <body> statement doesn't finish with a line break, 
+              # then we have different actions based upon the value of EndStartsOnOwnLine:
+              #     EndStartsOnOwnLine == 1 just add a new line
+              #     EndStartsOnOwnLine == 2 add a comment, and then new line
+              #     EndStartsOnOwnLine == 3 add a blank line, and then new line
               $self->logger("Adding a linebreak at the end of body (see $EndStringLogFile)") if $is_t_switch_active;
 
-              # by default, assume that no trailing comment token is needed
-              my $trailingCommentToken = q();
+              # by default, assume that no trailing character token is needed
+              my $trailingCharacterToken = q();
               if(${$self}{EndStartsOnOwnLine}==2){
                 $self->logger("Adding a % immediately after body of ${$self}{name} ($EndStringLogFile==2)") if $is_t_switch_active;
-                $trailingCommentToken = "%".$self->add_comment_symbol;
+                $trailingCharacterToken = "%".$self->add_comment_symbol;
+                ${$self}{body} =~ s/\h*$//s;
+              } elsif (${$self}{EndStartsOnOwnLine}==3) {
+                $self->logger("Adding a blank line immediately after body of ${$self}{name} ($EndStringLogFile==3)") if $is_t_switch_active;
+                $trailingCharacterToken = "\n".(${$masterSettings{modifyLineBreaks}}{preserveBlankLines}?$tokens{blanklines}:q());
                 ${$self}{body} =~ s/\h*$//s;
               }
               
@@ -95,7 +116,7 @@ sub modify_line_breaks_end{
               if(${$self}{body} =~ m/^\h*$/s and ${$self}{BodyStartsOnOwnLine} >=1 ){
                 ${$self}{linebreaksAtEnd}{body} = 0;
               } else {
-                ${$self}{body} .= "$trailingCommentToken\n";
+                ${$self}{body} .= "$trailingCharacterToken\n";
                 ${$self}{linebreaksAtEnd}{body} = 1;
               }
           } elsif (${$self}{EndStartsOnOwnLine}==-1 and ${$self}{linebreaksAtEnd}{body}){
@@ -117,9 +138,14 @@ sub modify_line_breaks_end{
     if(defined ${$self}{EndFinishesWithLineBreak}
        and ${$self}{EndFinishesWithLineBreak}>=1 
        and !${$self}{linebreaksAtEnd}{end}){
+              # if the <end> statement doesn't finish with a line break, 
+              # then we have different actions based upon the value of EndFinishesWithLineBreak:
+              #     EndFinishesWithLineBreak == 1 just add a new line
+              #     EndFinishesWithLineBreak == 2 add a comment, and then new line
+              #     EndFinishesWithLineBreak == 3 add a blank line, and then new line
               my $EndStringLogFile = ${$self}{aliases}{EndFinishesWithLineBreak}||"EndFinishesWithLineBreak";
               if(${$self}{EndFinishesWithLineBreak}==1){
-                $self->logger("Adding a linebreak at the end of ${$self}{end} (see $EndStringLogFile)") if $is_t_switch_active;
+                $self->logger("Adding a linebreak at the end of ${$self}{end} ($EndStringLogFile==1)") if $is_t_switch_active;
                 ${$self}{linebreaksAtEnd}{end} = 1;
 
                 # modified end statement
@@ -136,7 +162,13 @@ sub modify_line_breaks_end{
                   ${$self}{replacementText} .= "$trailingCommentToken\n";
                   ${$self}{linebreaksAtEnd}{end} = 1;
                 }
-              }
+              } elsif(${$self}{EndFinishesWithLineBreak}==3){
+                $self->logger("Adding a blank line at the end of ${$self}{end} ($EndStringLogFile==3)") if $is_t_switch_active;
+                ${$self}{linebreaksAtEnd}{end} = 1;
+
+                # modified end statement
+                ${$self}{replacementText} .= (${$masterSettings{modifyLineBreaks}}{preserveBlankLines}?$tokens{blanklines}:"\n")."\n";
+              } 
     }
 
 }
@@ -211,7 +243,7 @@ sub construct_paragraph_reg_exp{
                 $stopAtRegExp .= "|(?:".($paragraphStopAt eq "trailingComment" ? "%" : q() ).$tokens{$paragraphStopAt}."\\d+)";
             }
         } else {
-            $self->logger("The paragraph-stop regexp won't include $tokens{$paragraphStopAt} (see paragraphsStopAt)",'heading') if $is_t_switch_active ;
+            $self->logger("The paragraph-stop regexp won't include $tokens{$paragraphStopAt} (see paragraphsStopAt)",'heading') if ($tokens{$paragraphStopAt} and $is_t_switch_active);
         }
     }
 
diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/Preamble.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/Preamble.pm
index a3a62dd3f56..178bfe4ff7b 100644
--- a/Master/texmf-dist/scripts/latexindent/LatexIndent/Preamble.pm
+++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/Preamble.pm
@@ -17,6 +17,7 @@ package LatexIndent::Preamble;
 use strict;
 use warnings;
 use LatexIndent::Tokens qw/%tokens/;
+use LatexIndent::Switches qw/$is_t_switch_active/;
 use LatexIndent::GetYamlSettings qw/%masterSettings/;
 our @ISA = "LatexIndent::Document"; # class inheritance, Programming Perl, pg 321
 our $preambleCounter;
@@ -33,7 +34,7 @@ sub get_replacement_text{
     my $self = shift;
 
     # the replacement text for preamble needs to put the \\begin{document} back in
-    $self->logger("Custom replacement text routine for preamble ${$self}{name}");
+    $self->logger("Custom replacement text routine for preamble ${$self}{name}") if $is_t_switch_active;
     ${$self}{replacementText} = ${$self}{id}.${$self}{afterbit};
     delete ${$self}{afterbit};
 }
@@ -52,12 +53,19 @@ sub tasks_particular_to_each_object{
     # search for ifElseFi blocks
     $self->find_ifelsefi;
 
-    # search for commands with arguments
-    $self->find_commands_or_key_equals_values_braces if(!$masterSettings{preambleCommandsBeforeEnvironments});
+    if(${$masterSettings{specialBeginEnd}}{specialBeforeCommand}){
+        # search for special begin/end
+        $self->find_special;
 
-    # search for special begin/end
-    $self->find_special;
+        # search for commands with arguments
+        $self->find_commands_or_key_equals_values_braces if(!$masterSettings{preambleCommandsBeforeEnvironments});
+    } else {
+        # search for commands with arguments
+        $self->find_commands_or_key_equals_values_braces if(!$masterSettings{preambleCommandsBeforeEnvironments});
 
+        # search for special begin/end
+        $self->find_special;
+      }
 
 }
 
diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/Special.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/Special.pm
index d278d80e75c..d5a751f9e0e 100644
--- a/Master/texmf-dist/scripts/latexindent/LatexIndent/Special.pm
+++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/Special.pm
@@ -34,15 +34,17 @@ sub construct_special_begin{
 
     # put together a list of the begin terms in special
     while( my ($specialName,$BeginEnd)= each %{$masterSettings{specialBeginEnd}}){
-      # only append the regexps if lookForThis is 1
-      $specialBegins .= ($specialBegins eq ""?q():"|").${$BeginEnd}{begin} if(${$BeginEnd}{lookForThis});
+      if(ref($BeginEnd) eq "HASH"){
+        # only append the regexps if lookForThis is 1
+        $specialBegins .= ($specialBegins eq ""?q():"|").${$BeginEnd}{begin} if(${$BeginEnd}{lookForThis});
+      }
     }
 
     # put together a list of the begin terms in special
     while( my ($specialName,$BeginEnd)= each %{$masterSettings{specialBeginEnd}}){
 
       # only append the regexps if lookForThis is 1
-      if(${$BeginEnd}{lookForThis}){
+      if( (ref($BeginEnd) eq "HASH") and ${$BeginEnd}{lookForThis}){
         # the beginning parts
         $specialBegins .= ($specialBegins eq ""?q():"|").${$BeginEnd}{begin};
 
@@ -116,10 +118,10 @@ sub find_special{
         while( my ($specialName,$BeginEnd)= each %{$masterSettings{specialBeginEnd}}){
 
             # log file
-            if(${$BeginEnd}{lookForThis}){
+            if((ref($BeginEnd) eq "HASH") and ${$BeginEnd}{lookForThis}){
                 $self->logger("Looking for $specialName",'heading') if $is_t_switch_active ;
             } else {
-                $self->logger("Not looking for $specialName (see lookForThis)",'heading') if $is_t_switch_active ;
+                $self->logger("Not looking for $specialName (see lookForThis)",'heading') if ($is_t_switch_active and (ref($BeginEnd) eq "HASH"));
                 next;
             }
 
@@ -171,6 +173,19 @@ sub find_special{
      }
 }
 
+sub tasks_particular_to_each_object{
+    my $self = shift;
+
+    return unless(${$masterSettings{specialBeginEnd}}{specialBeforeCommand});
+
+    # search for commands with arguments
+    $self->find_commands_or_key_equals_values_braces;
+
+    # search for ifElseFi blocks
+    $self->find_ifelsefi;
+
+}
+
 
 sub create_unique_id{
     my $self = shift;
diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/Tokens.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/Tokens.pm
index e50c66d25d0..a106a09dcb1 100644
--- a/Master/texmf-dist/scripts/latexindent/LatexIndent/Tokens.pm
+++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/Tokens.pm
@@ -32,6 +32,7 @@ our %tokens = (
                 optionalArguments=>$beginningToken."OPTIONAL-ARGUMENT",
                 mandatoryArguments=>$beginningToken."MANDATORY-ARGUMENT",
                 ifElseFi=>$ifelsefiSpecial.$beginningToken."IFELSEFI", 
+                else=>$beginningToken."ELSE",
                 items=>$beginningToken."ITEMS",
                 keyEqualsValuesBracesBrackets=>$beginningToken."KEY-VALUE-BRACES",
                 namedGroupingBracesBrackets=>$beginningToken."GROUPING-BRACES",
diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/Verbatim.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/Verbatim.pm
index ba6b698175e..909b33cfc1b 100644
--- a/Master/texmf-dist/scripts/latexindent/LatexIndent/Verbatim.pm
+++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/Verbatim.pm
@@ -146,7 +146,7 @@ sub find_verbatim_commands{
     # would need to be found *before* trailing comments have been removed. Similarly, 
     # verbatim commands need to be put back in *after* trailing comments have been put 
     # back in
-    $self->logger('looking for VERBATIM commands (see verbatimCommands)','heading');
+    $self->logger('looking for VERBATIM commands (see verbatimCommands)','heading') if $is_t_switch_active;
     $self->logger(Dumper(\%{$masterSettings{verbatimCommands}})) if($is_tt_switch_active);
     while( my ($verbCommand,$yesno)= each %{$masterSettings{verbatimCommands}}){
         if($yesno){
diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/Version.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/Version.pm
index ec7202cf3eb..260f1f124a4 100644
--- a/Master/texmf-dist/scripts/latexindent/LatexIndent/Version.pm
+++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/Version.pm
@@ -19,6 +19,6 @@ use warnings;
 use Exporter qw/import/;
 our @EXPORT_OK = qw/$versionNumber $versionDate/;
 
-our $versionNumber = '3.2.2';
-our $versionDate = '2017-06-28';
+our $versionNumber = '3.3';
+our $versionDate = '2017-08-21';
 1
diff --git a/Master/texmf-dist/scripts/latexindent/defaultSettings.yaml b/Master/texmf-dist/scripts/latexindent/defaultSettings.yaml
index d91ee50010e..97c63d7e4f2 100755
--- a/Master/texmf-dist/scripts/latexindent/defaultSettings.yaml
+++ b/Master/texmf-dist/scripts/latexindent/defaultSettings.yaml
@@ -1,4 +1,4 @@
-# defaultSettings.yaml for latexindent.pl, version 3.2.2, 2017-06-28
+# defaultSettings.yaml for latexindent.pl, version 3.3, 2017-08-21
 #                      a script that aims to
 #                      beautify .tex, .sty, .cls files
 #
@@ -200,6 +200,7 @@ specialBeginEnd:
         begin: '\$\$'
         end: '\$\$'
         lookForThis: 1
+    specialBeforeCommand: 0
 
 # if you want to add indentation after
 # a heading, such as \part, \chapter, etc
@@ -235,6 +236,9 @@ indentAfterHeadings:
        indentAfterThisHeading: 0
        level: 7
 
+# maximum indentation, off by default
+maximumIndentation: -1
+
 # if you don't want to have additional indentation 
 # in an environment put it in this hash table; note that
 # environments in this hash table will inherit 
@@ -304,6 +308,8 @@ commandCodeBlocks:
         decoration: 1
         ++: 1
         --: 1
+    commandNameSpecial:
+        @ifnextchar[: 1
 
 # modifyLineBreaks will only be searched if the -m 
 # switch is active
diff --git a/Master/texmf-dist/scripts/latexindent/latexindent.pl b/Master/texmf-dist/scripts/latexindent/latexindent.pl
index bafa1790e46..b2d9da3a032 100755
--- a/Master/texmf-dist/scripts/latexindent/latexindent.pl
+++ b/Master/texmf-dist/scripts/latexindent/latexindent.pl
@@ -1,5 +1,5 @@
 #!/usr/bin/env perl
-#   latexindent.pl, version 3.2.2, 2017-06-28
+#   latexindent.pl, version 3.3, 2017-08-21
 #
 #	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
@@ -35,6 +35,7 @@ GetOptions (
     "trace|t"=>\$switches{trace},
     "ttrace|tt"=>\$switches{ttrace},
     "local|l:s"=>\$switches{readLocalSettings},
+    "yaml|y=s"=>\$switches{yaml},
     "onlydefault|d"=>\$switches{onlyDefault},
     "overwrite|w"=>\$switches{overwrite},
     "outputfile|o=s"=>\$switches{outputToFile},