diff options
Diffstat (limited to 'Master/texmf-dist/doc')
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 Binary files differindex a6d1c74fa59..f57535e9c7e 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 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 |