latexindent (19jun21)

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

1 files changed, 197 insertions, 48 deletions

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 2e5afbcdae2..426c0c9b789 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
@@ -33,6 +33,7 @@ latexindent.pl myfile
 
 	\index{backup files!extension settings}
 
+\subsection{Backup and log file preferences}
 \yamltitle{backupExtension}*{extension name}
 
 	If you call \texttt{latexindent.pl} with the \texttt{-w} switch (to overwrite
@@ -89,7 +90,7 @@ copy myfile.bak4 to myfile.bak3
 	amalgamated settings in the log file by switching \texttt{showAmalgamatedSettings} to
 	\texttt{1}, if you wish.
 
-	\cmhlistingsfromfile[style=logFilePreferences,]*{../defaultSettings.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{logFilePreferences}}{lst:logFilePreferences}
+	\cmhlistingsfromfile*[style=logFilePreferences,]*{../defaultSettings.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{logFilePreferences}}{lst:logFilePreferences}
 
 	When%
 	\announce{2018-01-13}{showDecorationStartCodeBlockTrace feature for log file} either of the
@@ -105,8 +106,16 @@ copy myfile.bak4 to myfile.bak3
 
 	Note: \texttt{latexindent.pl} no longer uses the \texttt{log4perl} module to handle
 	the creation of the logfile.%
-	\announce*{2021-03-14}*{no longer using log4perl}
+	\announce{2021-03-14}*{no longer using log4perl}
 
+	Some of the options%
+	\announce*{2021-06-19}*{logFilePreferences updated to include Dumper options}for Perl's \texttt{Dumper} module can
+	be specified in \cref{lst:logFilePreferences}; see \cite{dumper} and
+	\cite{dumperdemo} for more information. These options will mostly be helpful for
+	those calling \texttt{latexindent.pl} with the \texttt{-tt} option described
+	in \cref{sec:commandline}.
+
+\subsection{Verbatim code blocks}
 \yamltitle{verbatimEnvironments}*{fields}
 
 	A field that contains a list of environments that you would like left completely alone --
@@ -142,41 +151,58 @@ copy myfile.bak4 to myfile.bak3
 	you use them with a comment symbol, \lstinline!%!, followed by as many spaces
 	(possibly none) as you like; see \cref{lst:noIndentBlockdemo} for example.
 
-	\begin{cmhlistings}[style=demo,escapeinside={(*@}{@*)}]{\texttt{noIndentBlock} demonstration}{lst:noIndentBlockdemo}
-%(*@@*) \begin{noindent}
-        this code
-                won't
-     be touched
-                    by
-             latexindent.pl!
-%(*@@*)\end{noindent}
-	\end{cmhlistings}
+	\cmhlistingsfromfile{demonstrations/noindentblock.tex}{\texttt{noIndentBlock.tex}}{lst:noIndentBlockdemo}
 
 	Important note: it is assumed that the \texttt{noindent} block statements appear on
 	their own line.
 
-\yamltitle{removeTrailingWhitespace}*{fields}\label{yaml:removeTrailingWhitespace}
+	The%
+	\announce*{2021-06-19}{noIndentBlock specified as regex} \texttt{noIndentBlock}
+	fields can also be specified in terms of \texttt{begin} and
+	\texttt{end} fields. We begin with the file given in \cref{lst:noIndentBlock1}
 
-	Trailing white space can be removed both \emph{before} and
-	\emph{after} processing the document, as detailed in \cref{lst:removeTrailingWhitespace};
-	each of the fields can take the values \texttt{0} or
-	\texttt{1}. See \vref{lst:removeTWS-before,lst:env-mlb5-modAll,lst:env-mlb5-modAll-remove-WS} for before and after results. Thanks
-	to \cite{vosskuhle} for providing this feature.
+	\cmhlistingsfromfile*{demonstrations/noindentblock1.tex}{\texttt{noIndentBlock1.tex}}{lst:noIndentBlock1}
 
-	\begin{minipage}{.4\textwidth}
-		\cmhlistingsfromfile[style=removeTrailingWhitespace]*{../defaultSettings.yaml}[before=\centering,yaml-TCB]{removeTrailingWhitespace}{lst:removeTrailingWhitespace}
-	\end{minipage}%
-	\hfill
-	\begin{minipage}{.5\textwidth}
-		\begin{yaml}[numbers=none]{removeTrailingWhitespace (alt)}[before=\centering]{lst:removeTrailingWhitespace-alt}
-removeTrailingWhitespace: 1
-\end{yaml}
-	\end{minipage}%
+	The settings given in \cref{lst:noindent1,lst:noindent2} are equivalent
 
-	You can specify \texttt{removeTrailingWhitespace} simply as \texttt{0} or
-	\texttt{1}, if you wish; in this case,%
-	\announce{2017-06-28}{removeTrailingWhitespace} \texttt{latexindent.pl} will set both \texttt{beforeProcessing} and
-	\texttt{afterProcessing} to the value you specify; see \cref{lst:removeTrailingWhitespace-alt}.
+	\begin{cmhtcbraster}[raster columns=3,
+			raster left skip=-3.5cm,
+			raster right skip=-2cm,
+			raster column skip=.03\linewidth]
+		\cmhlistingsfromfile*{demonstrations/noindent1.yaml}[yaml-TCB]{\texttt{noindent1.yaml}}{lst:noindent1}
+		\cmhlistingsfromfile*{demonstrations/noindent2.yaml}[yaml-TCB]{\texttt{noindent2.yaml}}{lst:noindent2}
+		\cmhlistingsfromfile*{demonstrations/noindent3.yaml}[yaml-TCB]{\texttt{noindent3.yaml}}{lst:noindent3}
+	\end{cmhtcbraster}
+
+	Upon running the commands
+	\begin{commandshell}
+latexindent.pl -l noindent1.yaml noindent1
+latexindent.pl -l noindent2.yaml noindent1
+\end{commandshell}
+	then we receive the output given in \cref{lst:noIndentBlock1-mod1}.
+
+	\cmhlistingsfromfile*{demonstrations/noindentblock1-mod1.tex}{\texttt{noIndentBlock1.tex} using \cref{lst:noindent1} or \cref{lst:noindent2}}{lst:noIndentBlock1-mod1}
+
+	The \texttt{begin}, \texttt{body} and \texttt{end} fields
+	for \texttt{noIndentBlock} are all \emph{regular expressions}. If the
+	\texttt{body} field is not specified, then it takes a default value of
+	\lstinline!.*?! which is written explicitly in \cref{lst:noindent1}.
+
+	The \texttt{lookForThis} field is optional, and can take the values 0 (off) or 1 (on);
+	by default, it is assumed to be 1 (on).
+
+	Using \cref{lst:noindent3} demonstrates setting \texttt{lookForThis} to 0 (off);
+	running the command
+	\begin{commandshell}
+latexindent.pl -l noindent3.yaml noindent1
+\end{commandshell}
+	gives the output in \cref{lst:noIndentBlock1-mod3}.
+
+	\cmhlistingsfromfile*{demonstrations/noindentblock1-mod3.tex}{\texttt{noIndentBlock1.tex} using \cref{lst:noindent3}}{lst:noIndentBlock1-mod3}
+
+	We will demonstrate this feature later in the documentation in \cref{lst:href3}.
+
+\subsection{filecontents and preamble}
 \yamltitle{fileContentsEnvironments}*{field}
 
 	Before \texttt{latexindent.pl} determines the difference between preamble (if any) and
@@ -221,18 +247,43 @@ postfoothook=\end{mdframed},
 
 	\index{indentation!defaultIndent description}
 
+\subsection{Indentation and horizontal space}
 \yamltitle{defaultIndent}*{horizontal space}
-	This is the default indentation (\lstinline!\t! means a tab, and is the default
-	value) used in the absence of other details for the command or environment we are working
-	with; see \texttt{indentRules} in \vref{sec:noadd-indent-rules} for more details.
+	This is the default indentation used in the absence of other details for the code block
+	with which we are working. The default value is \lstinline!\t! which means a tab;
+	we will explore customisation beyond \texttt{defaultIndent} in \vref{sec:noadd-indent-rules}.
 
 	If you're interested in experimenting with \texttt{latexindent.pl} then you can
 	\emph{remove} all indentation by setting \texttt{defaultIndent: ""}.
 
+\yamltitle{removeTrailingWhitespace}*{fields}\label{yaml:removeTrailingWhitespace}
+
+	Trailing white space can be removed both \emph{before} and
+	\emph{after} processing the document, as detailed in \cref{lst:removeTrailingWhitespace};
+	each of the fields can take the values \texttt{0} or
+	\texttt{1}. See \vref{lst:removeTWS-before,lst:env-mlb5-modAll,lst:env-mlb5-modAll-remove-WS} for before and after results. Thanks
+	to \cite{vosskuhle} for providing this feature.
+
+	\begin{minipage}{.4\textwidth}
+		\cmhlistingsfromfile[style=removeTrailingWhitespace]*{../defaultSettings.yaml}[before=\centering,yaml-TCB]{removeTrailingWhitespace}{lst:removeTrailingWhitespace}
+	\end{minipage}%
+	\hfill
+	\begin{minipage}{.5\textwidth}
+		\begin{yaml}[numbers=none]{removeTrailingWhitespace (alt)}[before=\centering]{lst:removeTrailingWhitespace-alt}
+removeTrailingWhitespace: 1
+\end{yaml}
+	\end{minipage}%
+
+	You can specify \texttt{removeTrailingWhitespace} simply as \texttt{0} or
+	\texttt{1}, if you wish; in this case,%
+	\announce{2017-06-28}{removeTrailingWhitespace} \texttt{latexindent.pl} will set both \texttt{beforeProcessing} and
+	\texttt{afterProcessing} to the value you specify; see \cref{lst:removeTrailingWhitespace-alt}.
+
+\subsection{Aligning at delimiters}
 \yamltitle{lookForAlignDelims}*{fields}
-	This contains a list of environments and/or commands that are operated upon in a special
-	way by \texttt{latexindent.pl} (see \cref{lst:aligndelims:basic}). In fact, the fields in \texttt{lookForAlignDelims} can
-	actually take two different forms: the \emph{basic} version is shown in
+	This contains a list of code blocks that are operated upon in a special way by
+	\texttt{latexindent.pl} (see \cref{lst:aligndelims:basic}). In fact, the fields in \texttt{lookForAlignDelims} can actually take
+	two different forms: the \emph{basic} version is shown in
 	\cref{lst:aligndelims:basic} and the \emph{advanced} version in
 	\cref{lst:aligndelims:advanced}; we will discuss each in turn.
 	\index{delimiters!advanced settings of lookForAlignDelims}
@@ -247,10 +298,9 @@ lookForAlignDelims:
    ...
 	\end{yaml}
 
-	The environments specified in this field will be operated on in a special way by
-	\texttt{latexindent.pl}. In particular, it will try and align each column by its
-	alignment tabs. It does have some limitations (discussed further in
-	\cref{sec:knownlimitations}), but in many cases it will produce results such as those in
+	Specifying code blocks in this field instructs \texttt{latexindent.pl} to try and align
+	each column by its alignment delimiters. It does have some limitations (discussed further
+	in \cref{sec:knownlimitations}), but in many cases it will produce results such as those in
 	\cref{lst:tabularbefore:basic,lst:tabularafter:basic}.
 
 	If you find that \texttt{latexindent.pl} does not perform satisfactorily on such
@@ -291,7 +341,8 @@ lookForAlignDelims:
 		      should be aligned (default: 1);
 		\item \texttt{spacesBeforeDoubleBackSlash}: optionally,%
 		      \announce{2018-01-13}*{update to spacesBeforeDoubleBackSlash in ampersand alignment} specifies the number (integer $\geq$ 0) of spaces
-		      to be inserted before \lstinline!\\! (default: 1). \footnote{Previously this only activated if \texttt{alignDoubleBackSlash} was set to \texttt{0}.}
+		      to be inserted before \lstinline!\\! (default: 1);
+		      %\footnote{Previously this only activated if \texttt{alignDoubleBackSlash} was set to \texttt{0}.}
 		\item \announce{2017-06-19}{multiColumnGrouping} \texttt{multiColumnGrouping}: binary switch (0 or 1) that details if
 		      \texttt{latexindent.pl} should group columns
 		      above and below a \lstinline!\multicolumn! command (default: 0);
@@ -407,12 +458,104 @@ latexindent.pl tabular2.tex -l tabular2.yaml,tabular8.yaml
 		      output is the same as \cref{lst:tabular2-mod2};
 		\item in \cref{lst:tabular2-mod7} the \lstinline!\\! \emph{have} been
 		      aligned, and because \texttt{spacesBeforeDoubleBackSlash} is set to \texttt{0}, there are
-		      no spaces ahead of them; the output is otherwise the same as \cref{lst:tabular2-mod2}.
+		      no spaces ahead of them; the output is otherwise the same as \cref{lst:tabular2-mod2};
 		\item in \cref{lst:tabular2-mod8} the cells have been \emph{right}-justified; note
 		      that cells above and below the \lstinline!\multicol! statements have still been group
 		      correctly, because of the settings in \cref{lst:tabular2YAML}.
 	\end{itemize}
 
+\subsubsection{lookForAlignDelims: spacesBeforeAmpersand}
+	The \texttt{spacesBeforeAmpersand}%
+	\announce*{2021-06-19}*{spacesBeforeAmpersand leading blank column upgrade} can be specified in a few different
+	ways. The \emph{basic} form is demonstrated in \cref{lst:tabular4YAML}, but we
+	can customise the behaviour further by specifying if we would like this value to change
+	if it encounters a \emph{leading blank column}; that is, when the first column contains only
+	zero-width entries. We refer to this as the \emph{advanced} form.
+
+	We demonstrate this feature in relation to \cref{lst:aligned1}; upon running the
+	following command
+	\begin{commandshell}
+latexindent.pl aligned1.tex -o=+-default
+\end{commandshell}
+	then we receive the default output given in \cref{lst:aligned1-default}.
+
+	\begin{cmhtcbraster}
+		\cmhlistingsfromfile*{demonstrations/aligned1.tex}{\texttt{aligned1.tex}}{lst:aligned1}
+		\cmhlistingsfromfile*{demonstrations/aligned1-default.tex}{\texttt{aligned1-default.tex}}{lst:aligned1-default}
+	\end{cmhtcbraster}
+
+	The settings in \crefrange{lst:sba1}{lst:sba4} are all equivlanent; we have used the not-yet
+	discussed \texttt{noAdditionalIndent} field (see \vref{sec:noadd-indent-rules}) which will assist
+	in the demonstration in what follows.
+	\begin{cmhtcbraster}[raster columns=2, ]
+		\cmhlistingsfromfile*{demonstrations/sba1.yaml}[yaml-TCB]{\texttt{sba1.yaml}}{lst:sba1}
+		\cmhlistingsfromfile*{demonstrations/sba2.yaml}[yaml-TCB]{\texttt{sba2.yaml}}{lst:sba2}
+		\cmhlistingsfromfile*{demonstrations/sba3.yaml}[yaml-TCB]{\texttt{sba3.yaml}}{lst:sba3}
+		\cmhlistingsfromfile*{demonstrations/sba4.yaml}[yaml-TCB]{\texttt{sba4.yaml}}{lst:sba4}
+	\end{cmhtcbraster}
+	Upon running the following commands
+	\begin{commandshell}
+latexindent.pl aligned1.tex -l sba1.yaml
+latexindent.pl aligned1.tex -l sba2.yaml
+latexindent.pl aligned1.tex -l sba3.yaml
+latexindent.pl aligned1.tex -l sba4.yaml
+\end{commandshell}
+	then we receive the (same) output given in \cref{lst:aligned1-mod1}; we note that there is
+	\emph{one space} before each ampersand.
+
+	\begin{cmhtcbraster}
+		\cmhlistingsfromfile*{demonstrations/aligned1-mod1.tex}{\texttt{aligned1-mod1.tex}}{lst:aligned1-mod1}
+	\end{cmhtcbraster}
+
+	We note in particular:
+	\begin{itemize}
+		\item \cref{lst:sba1} demonstrates the \emph{basic} form for
+		      \texttt{lookForAlignDelims}; in this case,
+		      the default values are specified as in \vref{lst:aligndelims:advanced};
+		\item \cref{lst:sba2} demonstrates the \emph{advanced} form for
+		      \texttt{lookForAlignDelims}
+		      and specified \texttt{spacesBeforeAmpersand}. The default value is \texttt{1};
+		\item \cref{lst:sba3} demonstrates the new \emph{advanced} way to specify
+		      \texttt{spacesBeforeAmpersand}, and
+		      for us to set the \texttt{default} value that sets the number of spaces before
+		      ampersands which are \emph{not} in leading blank columns.	      The default
+		      value is \texttt{1}.
+
+		      We note that \texttt{leadingBlankColumn} has not been specified in \cref{lst:sba3},
+		      and it will inherit the value from \texttt{default};
+		\item \cref{lst:sba4} demonstrates spaces to be used before amperands for
+		      \emph{leading blank columns}.
+		      We note that \emph{default} has not been specified, and it will be set to
+		      \texttt{1} by default.
+	\end{itemize}
+	We can customise the space before the ampersand in the \emph{leading blank column} of
+	\cref{lst:aligned1-mod1} by using either of \cref{lst:sba5,lst:sba6}, which are equivalent.
+
+	\begin{cmhtcbraster}
+		\cmhlistingsfromfile*{demonstrations/sba5.yaml}[yaml-TCB]{\texttt{sba5.yaml}}{lst:sba5}
+		\cmhlistingsfromfile*{demonstrations/sba6.yaml}[yaml-TCB]{\texttt{sba6.yaml}}{lst:sba6}
+	\end{cmhtcbraster}
+
+	Upon running
+	\begin{commandshell}
+latexindent.pl aligned1.tex -l sba5.yaml
+latexindent.pl aligned1.tex -l sba6.yaml
+\end{commandshell}
+	then we receive the (same) output given in \cref{lst:aligned1-mod5}. We note that the
+	space before the ampersand in the \emph{leading blank column} has been set to
+	\texttt{0} by \cref{lst:sba6}.
+
+	We can demonstrated this feature further using the settings in \cref{lst:sba7}
+	which give the output in \cref{lst:aligned1-mod7}.
+
+	\begin{cmhtcbraster}[raster columns=3,
+			raster left skip=-3.75cm,
+			raster right skip=-2cm,]
+		\cmhlistingsfromfile*{demonstrations/aligned1-mod5.tex}{\texttt{aligned1-mod5.tex}}{lst:aligned1-mod5}
+		\cmhlistingsfromfile*{demonstrations/aligned1-mod7.tex}{\texttt{aligned1.tex} using \cref{lst:sba7}}{lst:aligned1-mod7}
+		\cmhlistingsfromfile*{demonstrations/sba7.yaml}[yaml-TCB]{\texttt{sba7.yaml}}{lst:sba7}
+	\end{cmhtcbraster}
+\subsubsection{lookForAlignDelims: alignFinalDoubleBackSlash}
 	We explore%
 	\announce{2020-03-21}{alignFinalDoubleBackSlash demonstration} the
 	\texttt{alignFinalDoubleBackSlash} feature by using the file in \cref{lst:tabular4}. Upon
@@ -479,7 +622,7 @@ latexindent.pl matrix1.tex
 	(see \vref{sec:noadd-indent-rules}), these comment-marked blocks are
 	considered \texttt{environments}.
 
-\subsection{lookForAlignDelims: the dontMeasure feature}\label{sec:dontMeasure}
+\subsubsection{lookForAlignDelims: the dontMeasure feature}\label{sec:dontMeasure}
 	The%
 	\announce{2020-03-21}{don't measure feature} \texttt{lookForAlignDelims}
 	field can, optionally, receive the \texttt{dontMeasure} option which can be specified
@@ -586,7 +729,7 @@ latexindent.pl tabular-DM.tex -l=dontMeasure6.yaml
 		\cmhlistingsfromfile{demonstrations/dontMeasure6.yaml}[yaml-TCB]{\texttt{dontMeasure6.yaml}}{lst:dontMeasure6}
 	\end{cmhtcbraster}
 
-\subsection{lookForAlignDelims: the delimiterRegEx and delimiterJustification feature}\label{sec:delimiter-reg-ex}
+\subsubsection{lookForAlignDelims: the delimiterRegEx and delimiterJustification feature}\label{sec:delimiter-reg-ex}
 	The delimiter alignment%
 	\announce{2020-03-21}{delimiterRegEx feature} will, by
 	default, align code blocks at the ampersand character. The behaviour is controlled by the
@@ -707,6 +850,7 @@ latexindent.pl tabbing1.tex -l=delimiterRegEx5.yaml -o=+-mod5
 	Note that in \cref{lst:tabbing1-mod5} the second set of delimiters have been
 	\emph{right aligned} -- it is quite subtle!
 
+\subsection{Indent after items, specials and headings}
 \yamltitle{indentAfterItems}*{fields}
 	The environment names specified in \texttt{indentAfterItems} tell \texttt{latexindent.pl}
 	to look for \lstinline!\item! commands; if these switches are set to
@@ -906,10 +1050,15 @@ latexindent.pl special-align.tex -l edge-node2.yaml -o=+-mod2
 	\index{regular expressions!horizontal space \textbackslash{h}}
 
 	\begin{cmhtcbraster}[ raster left skip=-3.5cm,]
-		\cmhlistingsfromfile{demonstrations/edge-node2.yaml}[yaml-TCB]{\texttt{edge-node2.yaml}}{lst:edge-node2}
+		\cmhlistingsfromfile*{demonstrations/edge-node2.yaml}[yaml-TCB]{\texttt{edge-node2.yaml}}{lst:edge-node2}
 		\cmhlistingsfromfile{demonstrations/special-align-mod2.tex}{\texttt{special-align.tex} using \cref{lst:edge-node2}}{lst:special-align-mod2}
 	\end{cmhtcbraster}
 
+	The \texttt{lookForThis} field can be considered
+	optional;%
+	\announce*{2021-06-19}*{lookForThis optional for specialBeginEnd} by default, it is
+	assumed to be 1, which is demonstrated in \cref{lst:edge-node2}.
+
 \yamltitle{indentAfterHeadings}*{fields}
 	This field enables the user to specify indentation rules that take effect after heading
 	commands such as \lstinline!\part!, \lstinline!\chapter!,
@@ -1065,19 +1214,19 @@ mand arg text
 \[
   ...
 \]
-  \end{lstlisting}                                                                                                                                                                                                                                                                                                                                                                      \\\cmidrule{2-3}
+  \end{lstlisting}                                                                                                                                                                                                                                                                                                                                                                     \\\cmidrule{2-3}
 				afterHeading                  & User specified, see \vref{lst:indentAfterHeadings}                                                             &
 				\begin{lstlisting}[,morekeywords={chapter},nolol=true,]
 \chapter{title}
   ...
 \section{title}
-  \end{lstlisting}                                                                                                                                                                                                                                                                                                                                                                      \\\cmidrule{2-3}
+  \end{lstlisting}                                                                                                                                                                                                                                                                                                                                                                     \\\cmidrule{2-3}
 				filecontents                  & User specified, see \vref{lst:fileContentsEnvironments}                                                        &
 				\begin{lstlisting}[,nolol=true,]
 \begin{filecontents}
 ...
 \end{filecontents}
-  \end{lstlisting}                                                                                                                                                                                                                                                                                                                                                                      \\
+  \end{lstlisting}                                                                                                                                                                                                                                                                                                                                                                     \\
 				\bottomrule
 			\end{tabular}
 		\end{widepage}