latexindent (22aug17)

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

13 files changed, 692 insertions, 304 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