summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/support
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2021-06-19 20:46:12 +0000
committerKarl Berry <karl@freefriends.org>2021-06-19 20:46:12 +0000
commit77b0010297bb9ba792ad97dfd34f19fe23feda9c (patch)
tree2e92817f7021deae668b426d6d35e2755ef8965e /Master/texmf-dist/doc/support
parentca78748eb54af0281da1e6c872138c7bc58b2246 (diff)
latexindent (19jun21)
git-svn-id: svn://tug.org/texlive/trunk@59645 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/support')
-rw-r--r--Master/texmf-dist/doc/support/latexindent/README2
-rw-r--r--Master/texmf-dist/doc/support/latexindent/appendices.tex33
-rw-r--r--Master/texmf-dist/doc/support/latexindent/latexindent.pdfbin898994 -> 942354 bytes
-rw-r--r--Master/texmf-dist/doc/support/latexindent/latexindent.tex58
-rw-r--r--Master/texmf-dist/doc/support/latexindent/sec-conclusions-know-limitations.tex2
-rw-r--r--Master/texmf-dist/doc/support/latexindent/sec-default-user-local.tex245
-rw-r--r--Master/texmf-dist/doc/support/latexindent/sec-fine-tuning.tex63
-rw-r--r--Master/texmf-dist/doc/support/latexindent/sec-how-to-use.tex4
-rw-r--r--Master/texmf-dist/doc/support/latexindent/sec-indent-config-and-settings.tex18
-rw-r--r--Master/texmf-dist/doc/support/latexindent/sec-the-m-switch.tex18
-rw-r--r--Master/texmf-dist/doc/support/latexindent/title.tex4
11 files changed, 349 insertions, 98 deletions
diff --git a/Master/texmf-dist/doc/support/latexindent/README b/Master/texmf-dist/doc/support/latexindent/README
index 225e4ba5f34..afe8bbbd844 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.9.3, 2021-05-07
+ latexindent.pl, version 3.10, 2021-06-19
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 c60445b1b70..b6f1e9615c0 100644
--- a/Master/texmf-dist/doc/support/latexindent/appendices.tex
+++ b/Master/texmf-dist/doc/support/latexindent/appendices.tex
@@ -23,6 +23,7 @@ use YAML::Tiny;
use File::Copy;
use File::Basename;
use File::HomeDir;
+use Encode;
use Getopt::Long;
use Data::Dumper;
use List::Util qw(max);
@@ -228,6 +229,38 @@ TRACE: Searching myenv for optional and mandatory arguments
Notice that the information given about \texttt{myenv} is `framed' using
\texttt{+++++} and \lstinline!-----! respectively.
+ \section{Encoding indentconfig.yaml}\label{app:encoding}
+ In relation to \vref{sec:indentconfig}, Windows users that encounter encoding issues with
+ \texttt{indentconfig.yaml}, may wish to run the following command in either
+ \texttt{cmd.exe} or \texttt{powershell.exe}:
+ \begin{dosprompt}
+chcp
+ \end{dosprompt}
+ They may receive the following result
+ \begin{dosprompt}
+Active code page: 936
+ \end{dosprompt}
+ and can then use the settings given in \cref{lst:indentconfig-encoding1} within their
+ \texttt{indentconfig.yaml}, where 936 is the result of the \texttt{chcp} command.
+
+ \cmhlistingsfromfile*{demonstrations/encoding1.yaml}[yaml-TCB]{\texttt{encoding} demonstration for \texttt{indentconfig.yaml}}{lst:indentconfig-encoding1}
+
+ \section{dos2unix linebreak adjustment}
+
+ \yamltitle{dos2unixlinebreaks}*{integer}
+ If you use \texttt{latexindent.pl} on a dos-based Windows file on Linux
+ \announce*{2021-06-19}{dos2unix linebreaks} then you may find that trailing horizontal space is not removed
+ as you hope.
+
+ In such a case, you may wish to try setting \texttt{dos2unixlinebreaks} to 1 and employing,
+ for example, the following command.
+
+ \begin{commandshell}
+latexindent.pl -y="dos2unixlinebreaks:1" myfile.tex
+\end{commandshell}
+
+ See \cite{bersbersbers} for further dertails.
+
\section{Differences from Version 2.2 to 3.0}\label{app:differences}
There are a few (small) changes to the interface when comparing Version 2.2 to Version
3.0. Explicitly, in previous versions you might have run, for example,
diff --git a/Master/texmf-dist/doc/support/latexindent/latexindent.pdf b/Master/texmf-dist/doc/support/latexindent/latexindent.pdf
index a6d1c74fa59..f57535e9c7e 100644
--- a/Master/texmf-dist/doc/support/latexindent/latexindent.pdf
+++ b/Master/texmf-dist/doc/support/latexindent/latexindent.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/support/latexindent/latexindent.tex b/Master/texmf-dist/doc/support/latexindent/latexindent.tex
index 22aecf1b78d..2691cfa9ec7 100644
--- a/Master/texmf-dist/doc/support/latexindent/latexindent.tex
+++ b/Master/texmf-dist/doc/support/latexindent/latexindent.tex
@@ -321,175 +321,175 @@
\lstdefinestyle{logFilePreferences}{
style=yaml-LST,
- firstnumber=85,linerange={85-91},
+ firstnumber=85,linerange={85-99},
numbers=left,
}
\lstdefinestyle{verbatimEnvironments}{
style=yaml-LST,
- firstnumber=95,linerange={95-98},
+ firstnumber=103,linerange={103-106},
numbers=left,
}
\lstdefinestyle{verbatimCommands}{
style=yaml-LST,
- firstnumber=101,linerange={101-103},
+ firstnumber=109,linerange={109-111},
numbers=left,
}
\lstdefinestyle{noIndentBlock}{
style=yaml-LST,
- firstnumber=108,linerange={108-110},
+ firstnumber=116,linerange={116-118},
numbers=left,
}
\lstdefinestyle{removeTrailingWhitespace}{
style=yaml-LST,
- firstnumber=113,linerange={113-115},
+ firstnumber=147,linerange={147-149},
numbers=left,
}
\lstdefinestyle{fileContentsEnvironments}{
style=yaml-LST,
- firstnumber=119,linerange={119-121},
+ firstnumber=122,linerange={122-124},
numbers=left,
}
\lstdefinestyle{lookForPreamble}{
style=yaml-LST,
- firstnumber=127,linerange={127-131},
+ firstnumber=130,linerange={130-134},
numbers=left,
}
\lstdefinestyle{lookForAlignDelims}{
style=yaml-LST,
- firstnumber=144,linerange={144-160},
+ firstnumber=152,linerange={152-168},
numbers=left,
}
\lstdefinestyle{indentAfterItems}{
style=yaml-LST,
- firstnumber=217,linerange={217-221},
+ firstnumber=225,linerange={225-229},
numbers=left,
}
\lstdefinestyle{itemNames}{
style=yaml-LST,
- firstnumber=227,linerange={227-229},
+ firstnumber=235,linerange={235-237},
numbers=left,
}
\lstdefinestyle{specialBeginEnd}{
style=yaml-LST,
- firstnumber=233,linerange={233-246},
+ firstnumber=241,linerange={241-254},
numbers=left,
}
\lstdefinestyle{indentAfterHeadings}{
style=yaml-LST,
- firstnumber=256,linerange={256-265},
+ firstnumber=264,linerange={264-273},
numbers=left,
}
\lstdefinestyle{noAdditionalIndentGlobalEnv}{
style=yaml-LST,
- firstnumber=314,linerange={314-315},
+ firstnumber=322,linerange={322-323},
numbers=left,
}
\lstdefinestyle{noAdditionalIndentGlobal}{
style=yaml-LST,
- firstnumber=314,linerange={314-326},
+ firstnumber=322,linerange={322-334},
numbers=left,
}
\lstdefinestyle{indentRulesGlobalEnv}{
style=yaml-LST,
- firstnumber=330,linerange={330-331},
+ firstnumber=338,linerange={338-339},
numbers=left,
}
\lstdefinestyle{indentRulesGlobal}{
style=yaml-LST,
- firstnumber=330,linerange={330-342},
+ firstnumber=338,linerange={338-350},
numbers=left,
}
\lstdefinestyle{commandCodeBlocks}{
style=yaml-LST,
- firstnumber=345,linerange={345-360},
+ firstnumber=353,linerange={353-368},
numbers=left,
}
\lstdefinestyle{modifylinebreaks}{
style=yaml-LST,
- firstnumber=472,linerange={472-474},
+ firstnumber=483,linerange={483-485},
numbers=left,
}
\lstdefinestyle{textWrapOptions}{
style=yaml-LST,
- firstnumber=499,linerange={499-500},
+ firstnumber=510,linerange={510-511},
numbers=left,
}
\lstdefinestyle{textWrapOptionsAll}{
style=yaml-LST,
- firstnumber=499,linerange={499-515},
+ firstnumber=510,linerange={510-527},
numbers=left,
}
\lstdefinestyle{removeParagraphLineBreaks}{
style=yaml-LST,
- firstnumber=516,linerange={516-530},
+ firstnumber=528,linerange={528-542},
numbers=left,
}
\lstdefinestyle{paragraphsStopAt}{
style=yaml-LST,
- firstnumber=531,linerange={531-540},
+ firstnumber=543,linerange={543-552},
numbers=left,
}
\lstdefinestyle{oneSentencePerLine}{
style=yaml-LST,
- firstnumber=475,linerange={475-498},
+ firstnumber=486,linerange={486-509},
numbers=left,
}
\lstdefinestyle{sentencesFollow}{
style=yaml-LST,
- firstnumber=480,linerange={480-488},
+ firstnumber=491,linerange={491-499},
numbers=left,
}
\lstdefinestyle{sentencesBeginWith}{
style=yaml-LST,
- firstnumber=489,linerange={489-492},
+ firstnumber=500,linerange={500-503},
numbers=left,
}
\lstdefinestyle{sentencesEndWith}{
style=yaml-LST,
- firstnumber=493,linerange={493-498},
+ firstnumber=504,linerange={504-509},
numbers=left,
}
\lstdefinestyle{modifylinebreaksEnv}{
style=yaml-LST,
- firstnumber=541,linerange={541-550},
+ firstnumber=553,linerange={553-562},
numbers=left,
}
\lstdefinestyle{replacements}{
style=yaml-LST,
- firstnumber=602,linerange={602-610},
+ firstnumber=614,linerange={614-622},
numbers=left,
}
\lstdefinestyle{fineTuning}{
style=yaml-LST,
- firstnumber=613,linerange={613-634},
+ firstnumber=625,linerange={625-648},
numbers=left,
}
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 a768d0ba6a8..5f20a13d17a 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
@@ -31,7 +31,7 @@
\announce{2019-07-13}*{ability to call latexindent on any file} if you don't specify an extension, then the extensions that you
specify in \lstinline[breaklines=true]!fileExtensionPreference! (see \vref{lst:fileExtensionPreference}) will be consulted. If you
find a case in which the script struggles, please feel free to report it at
- \cite{latexindent-home}, and in the meantime, consider using a \texttt{noIndentBlock} (see \cpageref{lst:noIndentBlockdemo}).
+ \cite{latexindent-home}, and in the meantime, consider using a \texttt{noIndentBlock} (see \cpageref{lst:noIndentBlock}).
I hope that this script is useful to some; if you find an example where the script does
not behave as you think it should, the best way to contact me is to report an issue on
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}
diff --git a/Master/texmf-dist/doc/support/latexindent/sec-fine-tuning.tex b/Master/texmf-dist/doc/support/latexindent/sec-fine-tuning.tex
index ccd04ffb47a..928b3a0909e 100644
--- a/Master/texmf-dist/doc/support/latexindent/sec-fine-tuning.tex
+++ b/Master/texmf-dist/doc/support/latexindent/sec-fine-tuning.tex
@@ -29,7 +29,7 @@
\end{warning}
\begin{widepage}
- \cmhlistingsfromfile[style=fineTuning]*{../defaultSettings.yaml}[width=0.95\linewidth,before=\centering,yaml-TCB]{\texttt{fineTuning}}{lst:fineTuning}
+ \cmhlistingsfromfile*[style=fineTuning]*{../defaultSettings.yaml}[width=.95\linewidth,before=\centering,yaml-TCB]{\texttt{fineTuning}}{lst:fineTuning}
\end{widepage}
The fields given in \cref{lst:fineTuning} are all \emph{regular expressions}. This manual
@@ -171,6 +171,63 @@ latexindent.pl -m -y='modifyLineBreaks:oneSentencePerLine:manipulateSentences: 1
\end{commandshell}
gives the output shown in \cref{lst:finetuning3-mod1}.
- \cmhlistingsfromfile*{demonstrations/finetuning3.tex}{\texttt{finetuning3.tex}}{lst:finetuning3}
- \cmhlistingsfromfile*{demonstrations/finetuning3-mod1.tex}{\texttt{finetuning3.tex} using -y switch}{lst:finetuning3-mod1}
+ \cmhlistingsfromfile{demonstrations/finetuning3.tex}{\texttt{finetuning3.tex}}{lst:finetuning3}
+ \cmhlistingsfromfile{demonstrations/finetuning3-mod1.tex}{\texttt{finetuning3.tex} using -y switch}{lst:finetuning3-mod1}
+ \end{example}
+
+ \begin{example}
+ We can tweak the \texttt{fineTuning} for how trailing comments are classified. For motivation, let's consider
+ the code given in \cref{lst:finetuning4}
+
+ \cmhlistingsfromfile*{demonstrations/finetuning4.tex}{\texttt{finetuning4.tex}}{lst:finetuning4}
+
+ We will compare the settings given in \cref{lst:href1,lst:href2}.
+
+ \begin{cmhtcbraster}[raster column skip=.01\linewidth,
+ raster left skip=0cm,
+ raster right skip=-0.5cm,]
+ \cmhlistingsfromfile*[style=yaml-LST]*{demonstrations/href1.yaml}[MLB-TCB]{\texttt{href1.yaml}}{lst:href1}
+ \cmhlistingsfromfile*[style=yaml-LST]*{demonstrations/href2.yaml}[MLB-TCB]{\texttt{href2.yaml}}{lst:href2}
+ \end{cmhtcbraster}
+
+ Upon running the following commands
+ \begin{commandshell}
+latexindent.pl -m finetuning4.tex -o=+-mod1 -l=href1
+latexindent.pl -m finetuning4.tex -o=+-mod2 -l=href2
+\end{commandshell}
+ we receive the respective output in \cref{lst:finetuning4-mod1,lst:finetuning4-mod2}.
+
+ \begin{widepage}
+ \cmhlistingsfromfile*{demonstrations/finetuning4-mod1.tex}{\texttt{finetuning4.tex} using \cref{lst:href1}}{lst:finetuning4-mod1}
+
+ \cmhlistingsfromfile*{demonstrations/finetuning4-mod2.tex}{\texttt{finetuning4.tex} using \cref{lst:href2}}{lst:finetuning4-mod2}
+ \end{widepage}
+
+ We note that in:
+ \begin{itemize}
+ \item \cref{lst:finetuning4-mod1} the trailing comments are assumed to be everything following the
+ first comment symbol, which has meant that everything following it has been moved to the
+ end of the line; this is undesirable, clearly!
+ \item \cref{lst:finetuning4-mod2} has fine-tuned the trailing comment matching, and says that
+ \lstinline!%! cannot
+ be immediately preceeded by the words `Handbook', `for' or `Spoken', which means that
+ none of the \lstinline!%! symbols have been treated as trailing comments, and
+ the output is desirable.
+ \end{itemize}
+
+ Another approach to this situation, which does not use \texttt{fineTuning}, is to use \texttt{noIndentBlock}
+ which we discussed in \vref{lst:noIndentBlock};
+ using the settings in \cref{lst:href3} and running the command
+ \begin{commandshell}
+latexindent.pl -m finetuning4.tex -o=+-mod3 -l=href3
+\end{commandshell}
+ then we receive the same output given in \cref{lst:finetuning4-mod2}; see also \texttt{paragraphsStopAt}
+ in \vref{lst:paragraphsStopAt}.
+
+ \cmhlistingsfromfile*[style=yaml-LST]*{demonstrations/href3.yaml}[MLB-TCB]{\texttt{href3.yaml}}{lst:href3}
+
+ With reference to the \texttt{body} field in \cref{lst:href3}, we note that \lstinline![^}]*?! can
+ be interpreted as: the fewest number of zero or more characters that are not right braces. This
+ is an example of character class.
+ \index{regular expressions!character class demonstration}
\end{example}
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 0760d467ef2..ba35a043280 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
@@ -206,7 +206,7 @@ latexindent.pl myfile.tex -l=first.yaml,second.yaml,third.yaml
and if it is called with the \texttt{-l} switch and it finds
\texttt{localSettings.yaml} in the same directory as \texttt{myfile.tex}, then, if not
found, it looks for \texttt{localSettings.yaml} (and friends, see \vref{sec:localsettings}) in the current working directory, then these
- \announce*{2021-03-14}*{-l switch: localSettings and friends} settings will be added to the indentation scheme. Information
+ \announce{2021-03-14}*{-l switch: localSettings and friends} settings will be added to the indentation scheme. Information
will be given in \texttt{indent.log} on the success or failure of loading
\texttt{localSettings.yaml}.
@@ -317,7 +317,7 @@ latexindent.pl myfile.tex -g other.log
if you wish to change the name of this file, simply call the script with your chosen name
after the \texttt{-g} switch as demonstrated above.
- \announce*{2021-05-07}{log file creation updated} If \texttt{latexindent.pl} can not open the log file that you
+ \announce{2021-05-07}{log file creation updated} If \texttt{latexindent.pl} can not open the log file that you
specify, then the script will operate, and no log file will be produced; this might be
helpful to users who wish to specify the following, for example
\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 40216948a77..ddce5c806bf 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
@@ -81,11 +81,23 @@ lookForAlignDelims:
will tell you so in \texttt{indent.log}.
\end{warning}
+ If you find that%
+ \announce*{2021-06-19}{encoding option for indentconfig.yaml}
+ \texttt{latexindent.pl} does not read your YAML file, then it might be as a result of the
+ default commandline encoding not being UTF-8; normally this will only occcur for Windows
+ users. In this case, you might like to explore the \texttt{encoding} option for
+ \texttt{indentconfig.yaml} as demonstrated in \cref{lst:indentconfig-encoding}.
+
+ \cmhlistingsfromfile*{demonstrations/encoding.yaml}[yaml-TCB]{The \texttt{encoding} option for \texttt{indentconfig.yaml}}{lst:indentconfig-encoding}
+
+ Thank you to \cite{qiancy98} for this contribution; please see
+ \vref{app:encoding} and details within \cite{encoding} for further information.
+
\subsection{localSettings.yaml and friends}\label{sec:localsettings}
The \texttt{-l} switch tells \texttt{latexindent.pl} to look for
\texttt{localSettings.yaml} and/or friends in the \emph{same directory} as
\texttt{myfile.tex}. For%
- \announce*{2021-03-14}*{-l switch: localSettings and friends}
+ \announce{2021-03-14}*{-l switch: localSettings and friends}
example, if you use the following command
\index{switches!-l demonstration}
\begin{commandshell}
@@ -138,8 +150,8 @@ verbatimEnvironments:
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:
+ specify the settings from \cref{lst:localSettings} using the \texttt{-y}
+ switch, then you could use the following command:
\index{verbatim!verbatimEnvironments demonstration (-y switch)}
\begin{commandshell}
latexindent.pl -y="verbatimEnvironments:cmhenvironment:0;myenv:1" myfile.tex
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 13ee49d1b48..c77ed24ec41 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
@@ -1901,17 +1901,17 @@ latexindent.pl -m pmatrix3.tex -l DBS3.yaml
\toprule
Code block & Sample & \multicolumn{2}{c}{Poly-switch mapping} \\
\midrule
- environment & \verb!before words!$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & BeginStartsOnOwnLine \\
- & \verb!\begin{myenv}!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & BodyStartsOnOwnLine \\
- & \verb!body of myenv!$\EndStartsOnOwnLine$ & $\EndStartsOnOwnLine$ & EndStartsOnOwnLine \\
- & \verb!\end{myenv}!$\EndFinishesWithLineBreak$ & $\EndFinishesWithLineBreak$ & EndFinishesWithLineBreak \\
- & \verb!after words! & & \\
+ environment & \verb!before words!$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & BeginStartsOnOwnLine \\
+ & \verb!\begin{myenv}!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & BodyStartsOnOwnLine \\
+ & \verb!body of myenv!$\EndStartsOnOwnLine$ & $\EndStartsOnOwnLine$ & EndStartsOnOwnLine \\
+ & \verb!\end{myenv}!$\EndFinishesWithLineBreak$ & $\EndFinishesWithLineBreak$ & EndFinishesWithLineBreak \\
+ & \verb!after words! & & \\
\cmidrule{2-4}
- ifelsefi & \verb!before words!$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & IfStartsOnOwnLine \\
- & \verb!\if...!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & BodyStartsOnOwnLine \\
- & \verb!body of if/or statement!$\OrStartsOnOwnLine$ & $\OrStartsOnOwnLine$ & OrStartsOnOwnLine %
+ ifelsefi & \verb!before words!$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & IfStartsOnOwnLine \\
+ & \verb!\if...!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & BodyStartsOnOwnLine \\
+ & \verb!body of if/or statement!$\OrStartsOnOwnLine$ & $\OrStartsOnOwnLine$ & OrStartsOnOwnLine %
\announce{2018-04-27}{new ifElseFi code block poly-switches} \\
- & \verb!\or!$\OrFinishesWithLineBreak$ & $\OrFinishesWithLineBreak$ & OrFinishesWithLineBreak \\
+ & \verb!\or!$\OrFinishesWithLineBreak$ & $\OrFinishesWithLineBreak$ & OrFinishesWithLineBreak \\
& \verb!body of if/or statement!$\ElseStartsOnOwnLine$ & $\ElseStartsOnOwnLine$ & ElseStartsOnOwnLine \\
& \verb!\else!$\ElseFinishesWithLineBreak$ & $\ElseFinishesWithLineBreak$ & ElseFinishesWithLineBreak \\
& \verb!body of else statement!$\EndStartsOnOwnLine$ & $\EndStartsOnOwnLine$ & FiStartsOnOwnLine \\
diff --git a/Master/texmf-dist/doc/support/latexindent/title.tex b/Master/texmf-dist/doc/support/latexindent/title.tex
index 7545c5d4934..06bbb12c359 100644
--- a/Master/texmf-dist/doc/support/latexindent/title.tex
+++ b/Master/texmf-dist/doc/support/latexindent/title.tex
@@ -8,14 +8,14 @@
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.9.3
+ \centering\ttfamily\bfseries latexindent.pl\\[1cm] Version 3.10
\end{tcolorbox}
}
\author{Chris Hughes \thanks{and contributors!
See \vref{sec:contributors}.
For
all communication, please visit \cite{latexindent-home}.}}
-\date{2021-05-07}
+\date{2021-06-19}
\maketitle
\begin{adjustwidth}{1cm}{1cm}
\small