From f6d37096894bec4b24ac8deb2bc07b7c068e9c63 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Sun, 14 Mar 2021 22:59:48 +0000 Subject: latexindent (14mar21) git-svn-id: svn://tug.org/texlive/trunk@58361 c570f23f-e606-0410-a88d-b1316a301751 --- Master/bin/win32/latexindent.exe | Bin 11472350 -> 6371118 bytes Master/texmf-dist/doc/support/latexindent/README | 2 +- .../doc/support/latexindent/appendices.tex | 19 +- .../doc/support/latexindent/cmhlistings.tex | 5 + .../doc/support/latexindent/figure-schematic.png | Bin 0 -> 7161 bytes .../latexindent/latexindent-module-installer.pl | 2 +- .../doc/support/latexindent/latexindent.pdf | Bin 888691 -> 893716 bytes .../doc/support/latexindent/latexindent.tex | 65 ++--- Master/texmf-dist/doc/support/latexindent/logo.png | Bin 0 -> 44096 bytes .../sec-conclusions-know-limitations.tex | 4 +- .../support/latexindent/sec-default-user-local.tex | 189 ++++++++++----- .../doc/support/latexindent/sec-fine-tuning.tex | 43 +++- .../doc/support/latexindent/sec-how-to-use.tex | 28 ++- .../latexindent/sec-indent-config-and-settings.tex | 39 ++- .../doc/support/latexindent/sec-introduction.tex | 3 + .../doc/support/latexindent/sec-replacements.tex | 38 +++ .../doc/support/latexindent/sec-the-m-switch.tex | 267 +++++++++++++++++---- .../subsec-commands-and-their-options.tex | 7 + .../subsec-conflicting-poly-switches.tex | 10 + .../subsec-noAdditionalIndent-indentRules.tex | 5 + .../subsec-partnering-poly-switches.tex | 3 + .../subsubsec-commands-with-arguments.tex | 3 + .../subsubsec-environments-and-their-arguments.tex | 11 + .../subsubsec-environments-with-items.tex | 2 + .../doc/support/latexindent/subsubsec-headings.tex | 2 + .../doc/support/latexindent/subsubsec-ifelsefi.tex | 2 + .../subsubsec-no-add-remaining-code-blocks.tex | 3 + .../doc/support/latexindent/subsubsec-special.tex | 4 + .../texmf-dist/doc/support/latexindent/title.tex | 2 +- .../scripts/latexindent/LatexIndent/Document.pm | 15 +- .../latexindent/LatexIndent/FileExtension.pm | 5 +- .../latexindent/LatexIndent/GetYamlSettings.pm | 107 ++++++--- .../scripts/latexindent/LatexIndent/IfElseFi.pm | 2 +- .../scripts/latexindent/LatexIndent/Item.pm | 4 +- .../scripts/latexindent/LatexIndent/LogFile.pm | 95 +------- .../scripts/latexindent/LatexIndent/Logger.pm | 64 +++++ .../scripts/latexindent/LatexIndent/Version.pm | 4 +- .../scripts/latexindent/defaultSettings.yaml | 9 +- .../texmf-dist/scripts/latexindent/latexindent.pl | 11 +- 39 files changed, 767 insertions(+), 307 deletions(-) create mode 100644 Master/texmf-dist/doc/support/latexindent/figure-schematic.png create mode 100644 Master/texmf-dist/doc/support/latexindent/logo.png create mode 100644 Master/texmf-dist/scripts/latexindent/LatexIndent/Logger.pm (limited to 'Master') diff --git a/Master/bin/win32/latexindent.exe b/Master/bin/win32/latexindent.exe index c90fcfac4ff..28406dfc3b1 100755 Binary files a/Master/bin/win32/latexindent.exe and b/Master/bin/win32/latexindent.exe differ diff --git a/Master/texmf-dist/doc/support/latexindent/README b/Master/texmf-dist/doc/support/latexindent/README index 05a58a37fa5..08dd864b2e0 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.8.3, 2020-11-06 + latexindent.pl, version 3.9, 2021-03-14 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 e756fb9533f..4036579e53a 100644 --- a/Master/texmf-dist/doc/support/latexindent/appendices.tex +++ b/Master/texmf-dist/doc/support/latexindent/appendices.tex @@ -26,7 +26,6 @@ use File::HomeDir; use Getopt::Long; use Data::Dumper; use List::Util qw(max); -use Log::Log4perl qw(get_logger :levels); print "hello world"; exit; @@ -62,12 +61,19 @@ curl -L http://cpanmin.us | perl - App::cpanminus cpanm YAML::Tiny cpanm File::HomeDir cpanm Unicode::GCString -cpanm Log::Log4perl cpanm Log::Dispatch \end{commandshell} - For other distributions, the Ubuntu/Debian approach may work by visiting the software - center, or else by running, for example, + For other distributions, the Ubuntu/Debian approach may work as follows + \begin{commandshell} +sudo apt install perl +sudo cpan -i App::cpanminus +sudo cpanm YAML::Tiny +sudo cpanm File::HomeDir +sudo cpanm Unicode::GCString +sudo cpanm Log::Dispatch::File +\end{commandshell} + or else by running, for example, \begin{commandshell} sudo perl -MCPAN -e'install "File::HomeDir"' \end{commandshell} @@ -83,7 +89,6 @@ apk --no-cache add miniperl perl-utils # Installing incompatible latexindent perl dependencies via apk apk --no-cache add \ - perl-log-log4perl \ perl-log-dispatch \ perl-namespace-autoclean \ perl-specio \ @@ -113,7 +118,6 @@ brew install cpanm cpanm YAML::Tiny cpanm File::HomeDir cpanm Unicode::GCString -cpanm Log::Log4perl cpanm Log::Dispatch \end{commandshell} @@ -230,10 +234,12 @@ TRACE: Searching myenv for optional and mandatory arguments \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, + \index{switches!-o demonstration} \begin{commandshell} latexindent.pl -o myfile.tex outputfile.tex \end{commandshell} whereas in Version 3.0 you would run any of the following, for example, + \index{switches!-o demonstration} \begin{commandshell} latexindent.pl -o=outputfile.tex myfile.tex latexindent.pl -o outputfile.tex myfile.tex @@ -264,6 +270,7 @@ latexindent.pl myfile.tex -outputfile outputfile.tex would write YAML as in \cref{lst:noAdditionalIndentOld}; as of Version 3.0, you would write YAML as in \cref{lst:indentAfterThisHeadingNew1} or, if you're using \texttt{-m} switch, \cref{lst:indentAfterThisHeadingNew2}. + \index{specialBeginEnd!update to displaymath V3.0} \begin{minipage}{.45\textwidth} \cmhlistingsfromfile{demonstrations/noAddtionalIndentOld.yaml}[yaml-TCB]{\texttt{noAdditionalIndent} in Version 2.2}{lst:noAdditionalIndentOld} diff --git a/Master/texmf-dist/doc/support/latexindent/cmhlistings.tex b/Master/texmf-dist/doc/support/latexindent/cmhlistings.tex index 1f058616d6d..5d44a598039 100644 --- a/Master/texmf-dist/doc/support/latexindent/cmhlistings.tex +++ b/Master/texmf-dist/doc/support/latexindent/cmhlistings.tex @@ -26,3 +26,8 @@ #1^^J .. endproof:example::^^J } +\newcommand{\cmhindex}[1]{ + +:index:@#1@ + +} diff --git a/Master/texmf-dist/doc/support/latexindent/figure-schematic.png b/Master/texmf-dist/doc/support/latexindent/figure-schematic.png new file mode 100644 index 00000000000..f56aa562c24 Binary files /dev/null and b/Master/texmf-dist/doc/support/latexindent/figure-schematic.png differ diff --git a/Master/texmf-dist/doc/support/latexindent/latexindent-module-installer.pl b/Master/texmf-dist/doc/support/latexindent/latexindent-module-installer.pl index e45fdcbe73d..786c37b6419 100755 --- a/Master/texmf-dist/doc/support/latexindent/latexindent-module-installer.pl +++ b/Master/texmf-dist/doc/support/latexindent/latexindent-module-installer.pl @@ -20,7 +20,7 @@ use warnings; print ("============\nlatexindent.pl module installer\n============\n"); print ("Would you like to run the following commands?\n"); -my @modulesToInstall = ("cpanm YAML::Tiny","cpanm File::HomeDir","cpanm Unicode::GCString","cpanm Log::Log4perl","cpanm Log::Dispatch"); +my @modulesToInstall = ("cpanm YAML::Tiny","cpanm File::HomeDir","cpanm Unicode::GCString"); foreach (@modulesToInstall) { print $_,"\n"; } diff --git a/Master/texmf-dist/doc/support/latexindent/latexindent.pdf b/Master/texmf-dist/doc/support/latexindent/latexindent.pdf index ec8fbfd2696..c7e3178cc6b 100644 Binary files a/Master/texmf-dist/doc/support/latexindent/latexindent.pdf and b/Master/texmf-dist/doc/support/latexindent/latexindent.pdf differ diff --git a/Master/texmf-dist/doc/support/latexindent/latexindent.tex b/Master/texmf-dist/doc/support/latexindent/latexindent.tex index 81a00604835..22aecf1b78d 100644 --- a/Master/texmf-dist/doc/support/latexindent/latexindent.tex +++ b/Master/texmf-dist/doc/support/latexindent/latexindent.tex @@ -1,6 +1,7 @@ % arara: pdflatex: {shell: yes} +% arara: makeindex: {style: latexindent.ist} % arara: bibtex -% arara: pdflatex: {shell: yes} if changed (toFile('latexindent.aux')) +% arara: pdflatex: {shell: yes} if changed (toFile('latexindent.aux')) || changed (toFile('latexindent.ind')) % arara: pdflatex: {shell: yes} if changed (toFile('latexindent.aux')) % arara: pdflatex: {shell: yes} if changed (toFile('latexindent.aux')) \documentclass[10pt]{article} @@ -320,175 +321,175 @@ \lstdefinestyle{logFilePreferences}{ style=yaml-LST, - firstnumber=85,linerange={85-95}, + firstnumber=85,linerange={85-91}, numbers=left, } \lstdefinestyle{verbatimEnvironments}{ style=yaml-LST, - firstnumber=99,linerange={99-102}, + firstnumber=95,linerange={95-98}, numbers=left, } \lstdefinestyle{verbatimCommands}{ style=yaml-LST, - firstnumber=105,linerange={105-107}, + firstnumber=101,linerange={101-103}, numbers=left, } \lstdefinestyle{noIndentBlock}{ style=yaml-LST, - firstnumber=112,linerange={112-114}, + firstnumber=108,linerange={108-110}, numbers=left, } \lstdefinestyle{removeTrailingWhitespace}{ style=yaml-LST, - firstnumber=117,linerange={117-119}, + firstnumber=113,linerange={113-115}, numbers=left, } \lstdefinestyle{fileContentsEnvironments}{ style=yaml-LST, - firstnumber=123,linerange={123-125}, + firstnumber=119,linerange={119-121}, numbers=left, } \lstdefinestyle{lookForPreamble}{ style=yaml-LST, - firstnumber=131,linerange={131-135}, + firstnumber=127,linerange={127-131}, numbers=left, } \lstdefinestyle{lookForAlignDelims}{ style=yaml-LST, - firstnumber=148,linerange={148-164}, + firstnumber=144,linerange={144-160}, numbers=left, } \lstdefinestyle{indentAfterItems}{ style=yaml-LST, - firstnumber=221,linerange={221-225}, + firstnumber=217,linerange={217-221}, numbers=left, } \lstdefinestyle{itemNames}{ style=yaml-LST, - firstnumber=231,linerange={231-233}, + firstnumber=227,linerange={227-229}, numbers=left, } \lstdefinestyle{specialBeginEnd}{ style=yaml-LST, - firstnumber=237,linerange={237-250}, + firstnumber=233,linerange={233-246}, numbers=left, } \lstdefinestyle{indentAfterHeadings}{ style=yaml-LST, - firstnumber=260,linerange={260-269}, + firstnumber=256,linerange={256-265}, numbers=left, } \lstdefinestyle{noAdditionalIndentGlobalEnv}{ style=yaml-LST, - firstnumber=318,linerange={318-319}, + firstnumber=314,linerange={314-315}, numbers=left, } \lstdefinestyle{noAdditionalIndentGlobal}{ style=yaml-LST, - firstnumber=318,linerange={318-330}, + firstnumber=314,linerange={314-326}, numbers=left, } \lstdefinestyle{indentRulesGlobalEnv}{ style=yaml-LST, - firstnumber=334,linerange={334-335}, + firstnumber=330,linerange={330-331}, numbers=left, } \lstdefinestyle{indentRulesGlobal}{ style=yaml-LST, - firstnumber=334,linerange={334-346}, + firstnumber=330,linerange={330-342}, numbers=left, } \lstdefinestyle{commandCodeBlocks}{ style=yaml-LST, - firstnumber=349,linerange={349-363}, + firstnumber=345,linerange={345-360}, numbers=left, } \lstdefinestyle{modifylinebreaks}{ style=yaml-LST, - firstnumber=475,linerange={475-477}, + firstnumber=472,linerange={472-474}, numbers=left, } \lstdefinestyle{textWrapOptions}{ style=yaml-LST, - firstnumber=502,linerange={502-503}, + firstnumber=499,linerange={499-500}, numbers=left, } \lstdefinestyle{textWrapOptionsAll}{ style=yaml-LST, - firstnumber=502,linerange={502-518}, + firstnumber=499,linerange={499-515}, numbers=left, } \lstdefinestyle{removeParagraphLineBreaks}{ style=yaml-LST, - firstnumber=519,linerange={519-533}, + firstnumber=516,linerange={516-530}, numbers=left, } \lstdefinestyle{paragraphsStopAt}{ style=yaml-LST, - firstnumber=534,linerange={534-543}, + firstnumber=531,linerange={531-540}, numbers=left, } \lstdefinestyle{oneSentencePerLine}{ style=yaml-LST, - firstnumber=478,linerange={478-501}, + firstnumber=475,linerange={475-498}, numbers=left, } \lstdefinestyle{sentencesFollow}{ style=yaml-LST, - firstnumber=483,linerange={483-491}, + firstnumber=480,linerange={480-488}, numbers=left, } \lstdefinestyle{sentencesBeginWith}{ style=yaml-LST, - firstnumber=492,linerange={492-495}, + firstnumber=489,linerange={489-492}, numbers=left, } \lstdefinestyle{sentencesEndWith}{ style=yaml-LST, - firstnumber=496,linerange={496-501}, + firstnumber=493,linerange={493-498}, numbers=left, } \lstdefinestyle{modifylinebreaksEnv}{ style=yaml-LST, - firstnumber=544,linerange={544-553}, + firstnumber=541,linerange={541-550}, numbers=left, } \lstdefinestyle{replacements}{ style=yaml-LST, - firstnumber=605,linerange={605-613}, + firstnumber=602,linerange={602-610}, numbers=left, } \lstdefinestyle{fineTuning}{ style=yaml-LST, - firstnumber=616,linerange={616-637}, + firstnumber=613,linerange={613-634}, numbers=left, } @@ -661,7 +662,6 @@ {\titlerule*[0.5em]{$\cdot$}\contentspage} [] \AtBeginDocument{\addtocontents{lol}{\protect\begin{widepage}\protect\begin{multicols}{2}}} -\AtEndDocument{\addtocontents{lol}{\protect\end{multicols}\protect\end{widepage}}} % cleveref settings \crefname{table}{Table}{Tables} @@ -749,6 +749,7 @@ {\titlerule*[0.5em]{$\cdot$}\contentspage} \setcounter{secnumdepth}{5} +\makeindex \begin{document} \renewcommand*{\thefootnote}{\arabic{footnote}} \input{title.tex} @@ -780,4 +781,6 @@ \input{sec-conclusions-know-limitations} \input{references} \input{appendices} + \addtocontents{lol}{\protect\end{multicols}\protect\end{widepage}} + \printindex \end{document} diff --git a/Master/texmf-dist/doc/support/latexindent/logo.png b/Master/texmf-dist/doc/support/latexindent/logo.png new file mode 100644 index 00000000000..1aa80cc43db Binary files /dev/null and b/Master/texmf-dist/doc/support/latexindent/logo.png differ 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 ddd4e6c8ad0..a768d0ba6a8 100644 --- a/Master/texmf-dist/doc/support/latexindent/sec-conclusions-know-limitations.tex +++ b/Master/texmf-dist/doc/support/latexindent/sec-conclusions-know-limitations.tex @@ -3,8 +3,8 @@ There are a number of known limitations of the script, and almost certainly quite a few that are \emph{unknown}! - The main limitation is to do with the alignment routine discussed on - \cpageref{yaml:lookforaligndelims}; for example, consider the file given in \cref{lst:matrix2}. + The main limitation is to do with the alignment routine discussed in + \cpageref{lst:aligndelims:advanced}; for example, consider the file given in \cref{lst:matrix2}. \cmhlistingsfromfile{demonstrations/matrix2.tex}{\texttt{matrix2.tex}}{lst:matrix2} 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 2d0498749e9..411461e3e57 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 @@ -31,6 +31,8 @@ latexindent.pl myfile finally \texttt{myfile.bib} in order\footnote{Throughout this manual, listings shown with line numbers represent code taken directly from \texttt{defaultSettings.yaml}.}. + \index{backup files!extension settings} + \yamltitle{backupExtension}*{extension name} If you call \texttt{latexindent.pl} with the \texttt{-w} switch (to overwrite @@ -45,11 +47,14 @@ latexindent.pl myfile \yamltitle{onlyOneBackUp}*{integer} \label{page:onlyonebackup} + \index{backup files!number of backup files} If you don't want a backup for every time that you call \texttt{latexindent.pl} (so you don't want \texttt{myfile.bak1}, \texttt{myfile.bak2}, etc) and you simply want \texttt{myfile.bak} (or whatever you chose \texttt{backupExtension} to be) then change \texttt{onlyOneBackUp} to \texttt{1}; the default value of \texttt{onlyOneBackUp} is \texttt{0}. + \index{backup files!maximum number of backup files} + \index{backup files!number of backup files} \yamltitle{maxNumberOfBackUps}*{integer} Some users may only want a finite number of backup files, say at most @@ -60,6 +65,7 @@ latexindent.pl myfile \texttt{0}. \yamltitle{cycleThroughBackUps}*{integer} + \index{backup files!cycle through} Some users may wish to cycle through backup files, by deleting the oldest backup file and keeping only the most recent; for example, with \texttt{maxNumberOfBackUps: 4}, and \texttt{cycleThroughBackUps} set to \texttt{1} then the \texttt{copy} @@ -97,17 +103,17 @@ copy myfile.bak4 to myfile.bak3 report the \texttt{GitHub} address of \texttt{latexindent.pl} to the log file if \texttt{showGitHubInfoFooter} is set to \texttt{1}. - \texttt{latexindent.pl}% - \announce{2018-01-13}{log file pattern layout for log file} uses the \texttt{log4perl} module \cite{log4perl} - to handle the creation of the logfile. You can specify the layout of the information - given in the logfile using any of the \texttt{Log Layouts} detailed at - \cite{log4perl}. + 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} \yamltitle{verbatimEnvironments}*{fields} A field that contains a list of environments that you would like left completely alone -- no indentation will be performed on environments that you have specified in this field, see \cref{lst:verbatimEnvironments}. + \index{verbatim!environments} + \index{verbatim!commands} \begin{cmhtcbraster}[raster column skip=.1\linewidth] \cmhlistingsfromfile[style=verbatimEnvironments]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{verbatimEnvironments}}{lst:verbatimEnvironments} @@ -125,11 +131,10 @@ copy myfile.bak4 to myfile.bak3 \vref{sec:modifylinebreaks}). \yamltitle{noIndentBlock}*{fields} - If you have a block of code that you don't want \texttt{latexindent.pl} to touch (even if - it is \emph{not} a verbatim-like environment) then you can wrap it in an - environment from \texttt{noIndentBlock}; you can use any name you like for this, - provided you populate it as demonstrate in \cref{lst:noIndentBlock}. + \index{verbatim!noIndentBlock} it is \emph{not} a verbatim-like environment) then + you can wrap it in an environment from \texttt{noIndentBlock}; you can use any name you + like for this, provided you populate it as demonstrate in \cref{lst:noIndentBlock}. \cmhlistingsfromfile[style=noIndentBlock]*{../defaultSettings.yaml}[width=.4\linewidth,before=\centering,yaml-TCB]{\texttt{noIndentBlock}}{lst:noIndentBlock} @@ -211,6 +216,8 @@ postfoothook=\end{mdframed}, ... \end{cmhlistings} + \index{indentation!defaultIndent description} + \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 @@ -219,12 +226,13 @@ postfoothook=\end{mdframed}, If you're interested in experimenting with \texttt{latexindent.pl} then you can \emph{remove} all indentation by setting \texttt{defaultIndent: ""}. -\yamltitle{lookForAlignDelims}*{fields}\label{yaml:lookforaligndelims} +\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 \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} \begin{yaml}[numbers=none]{\texttt{lookForAlignDelims} (basic)}[width=.8\linewidth,before=\centering]{lst:aligndelims:basic} lookForAlignDelims: @@ -256,8 +264,14 @@ lookForAlignDelims: If, for example, you wish to remove the alignment of the \lstinline!\\! within a delimiter-aligned block, then the advanced form of \texttt{lookForAlignDelims} shown in \cref{lst:aligndelims:advanced} is for you. + \index{regular expressions!delimiterRegEx} + \index{regular expressions!ampersand alignment} + \index{delimiters!default settings of lookForAlignDelims} + \index{delimiters!ampersand \&} + \index{delimiters!advanced settings} + \index{delimiters!lookForAlignDelims} - \cmhlistingsfromfile*[style=lookForAlignDelims]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{lookForAlignDelims} (advanced)}{lst:aligndelims:advanced} + \cmhlistingsfromfile[style=lookForAlignDelims]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{lookForAlignDelims} (advanced)}{lst:aligndelims:advanced} Note that you can use a mixture of the basic and advanced form: in \cref{lst:aligndelims:advanced} \texttt{tabular} and \texttt{tabularx} are advanced @@ -289,14 +303,14 @@ lookForAlignDelims: spaces to be placed \emph{After} ampersands (default: 1); \item \announce{2018-01-13}{justification of cells in ampersand alignment}\texttt{justification}: optionally specifies the justification of each cell as either \emph{left} or \emph{right} (default: left); - \item \announce*{2020-03-21}{align final double back slash}{alignFinalDoubleBackSlash} optionally specifies if the + \item \announce{2020-03-21}{align final double back slash}{alignFinalDoubleBackSlash} optionally specifies if the \emph{final} double back slash should be used for alignment (default: 0); - \item \announce*{2020-03-21}{don't measure feature}{dontMeasure} optionally specifies if + \item \announce{2020-03-21}{don't measure feature}{dontMeasure} optionally specifies if user-specified cells, rows or the largest entries should \emph{not} be measured (default: 0); - \item \announce*{2020-03-21}{delimiter RegEx feature}{delimiterRegEx} optionally specifies the pattern + \item \announce{2020-03-21}{delimiter RegEx feature}{delimiterRegEx} optionally specifies the pattern matching to be used for the alignment delimeter (default: \lstinline3 '(?!. We employ the settings given in \cref{lst:delimiterRegEx1} and run the command + \index{switches!-l demonstration} \begin{commandshell} latexindent.pl tabbing.tex -l=delimiterRegEx1.yaml \end{commandshell} to receive the output given in \cref{lst:tabbing-mod1}. + \index{regular expressions!delimiter regex at \textbackslash= or \textbackslash>} \begin{cmhtcbraster} - \cmhlistingsfromfile*{demonstrations/tabbing-mod1.tex}{\texttt{tabbing.tex} using \cref{lst:delimiterRegEx1}}{lst:tabbing-mod1} - \cmhlistingsfromfile*{demonstrations/delimiterRegEx1.yaml}[yaml-TCB]{\texttt{delimiterRegEx1.yaml}}{lst:delimiterRegEx1} + \cmhlistingsfromfile{demonstrations/tabbing-mod1.tex}{\texttt{tabbing.tex} using \cref{lst:delimiterRegEx1}}{lst:tabbing-mod1} + \cmhlistingsfromfile{demonstrations/delimiterRegEx1.yaml}[yaml-TCB]{\texttt{delimiterRegEx1.yaml}}{lst:delimiterRegEx1} \end{cmhtcbraster} We note that: \begin{itemize} @@ -597,14 +633,16 @@ latexindent.pl tabbing.tex -l=delimiterRegEx1.yaml \end{itemize} We can explore \texttt{delimiterRegEx} a little further using the settings in \cref{lst:delimiterRegEx2} and run the command + \index{switches!-l demonstration} \begin{commandshell} latexindent.pl tabbing.tex -l=delimiterRegEx2.yaml \end{commandshell} to receive the output given in \cref{lst:tabbing-mod2}. + \index{regular expressions!delimiter regex at only \textbackslash>} \begin{cmhtcbraster} - \cmhlistingsfromfile*{demonstrations/tabbing-mod2.tex}{\texttt{tabbing.tex} using \cref{lst:delimiterRegEx2}}{lst:tabbing-mod2} - \cmhlistingsfromfile*{demonstrations/delimiterRegEx2.yaml}[yaml-TCB]{\texttt{delimiterRegEx2.yaml}}{lst:delimiterRegEx2} + \cmhlistingsfromfile{demonstrations/tabbing-mod2.tex}{\texttt{tabbing.tex} using \cref{lst:delimiterRegEx2}}{lst:tabbing-mod2} + \cmhlistingsfromfile{demonstrations/delimiterRegEx2.yaml}[yaml-TCB]{\texttt{delimiterRegEx2.yaml}}{lst:delimiterRegEx2} \end{cmhtcbraster} We note that only the \lstinline!\>! have been aligned. @@ -612,14 +650,15 @@ latexindent.pl tabbing.tex -l=delimiterRegEx2.yaml \texttt{delimiterRegEx}; regardless of the type of delimiter being used (ampersand or anything else), the fields from \vref{lst:aligndelims:advanced} remain the same; for example, using the settings in \cref{lst:delimiterRegEx3}, and running + \index{switches!-l demonstration} \begin{commandshell} latexindent.pl tabbing.tex -l=delimiterRegEx3.yaml \end{commandshell} to receive the output given in \cref{lst:tabbing-mod3}. \begin{cmhtcbraster} - \cmhlistingsfromfile*{demonstrations/tabbing-mod3.tex}{\texttt{tabbing.tex} using \cref{lst:delimiterRegEx3}}{lst:tabbing-mod3} - \cmhlistingsfromfile*{demonstrations/delimiterRegEx3.yaml}[yaml-TCB]{\texttt{delimiterRegEx3.yaml}}{lst:delimiterRegEx3} + \cmhlistingsfromfile{demonstrations/tabbing-mod3.tex}{\texttt{tabbing.tex} using \cref{lst:delimiterRegEx3}}{lst:tabbing-mod3} + \cmhlistingsfromfile{demonstrations/delimiterRegEx3.yaml}[yaml-TCB]{\texttt{delimiterRegEx3.yaml}}{lst:delimiterRegEx3} \end{cmhtcbraster} It is possible that delimiters specified within \texttt{delimiterRegEx} can be of @@ -628,32 +667,38 @@ latexindent.pl tabbing.tex -l=delimiterRegEx3.yaml the delimiter to be either \lstinline!#! or \lstinline!\>!, \emph{which are different lengths}. Upon running the command + \index{switches!-l demonstration} + \index{switches!-o demonstration} \begin{commandshell} latexindent.pl tabbing1.tex -l=delimiterRegEx4.yaml -o=+-mod4 \end{commandshell} we receive the output in \cref{lst:tabbing1-mod4}. + \index{regular expressions!delimiter regex at \#} \begin{cmhtcbraster}[raster columns=3, raster left skip=-3.5cm, raster right skip=-2cm, raster column skip=.03\linewidth] - \cmhlistingsfromfile*{demonstrations/tabbing1.tex}{\texttt{tabbing1.tex}}{lst:tabbing1} - \cmhlistingsfromfile*{demonstrations/tabbing1-mod4.tex}{\texttt{tabbing1-mod4.tex}}{lst:tabbing1-mod4} - \cmhlistingsfromfile*{demonstrations/delimiterRegEx4.yaml}[yaml-TCB]{\texttt{delimiterRegEx4.yaml}}{lst:delimiterRegEx4} + \cmhlistingsfromfile{demonstrations/tabbing1.tex}{\texttt{tabbing1.tex}}{lst:tabbing1} + \cmhlistingsfromfile{demonstrations/tabbing1-mod4.tex}{\texttt{tabbing1-mod4.tex}}{lst:tabbing1-mod4} + \cmhlistingsfromfile{demonstrations/delimiterRegEx4.yaml}[yaml-TCB]{\texttt{delimiterRegEx4.yaml}}{lst:delimiterRegEx4} \end{cmhtcbraster} You can set the \emph{delimiter} justification as either \texttt{left} (default) or \texttt{right}, which will only have effect when delimiters in the same column have different lengths. Using the settings in \cref{lst:delimiterRegEx5} and running the command + \index{switches!-l demonstration} + \index{switches!-o demonstration} \begin{commandshell} latexindent.pl tabbing1.tex -l=delimiterRegEx5.yaml -o=+-mod5 \end{commandshell} gives the output in \cref{lst:tabbing1-mod5}. + \index{regular expressions!delimiter regex at \# or \textbackslash>} \begin{cmhtcbraster} - \cmhlistingsfromfile*{demonstrations/tabbing1-mod5.tex}{\texttt{tabbing1-mod5.tex}}{lst:tabbing1-mod5} - \cmhlistingsfromfile*{demonstrations/delimiterRegEx5.yaml}[yaml-TCB]{\texttt{delimiterRegEx5.yaml}}{lst:delimiterRegEx5} + \cmhlistingsfromfile{demonstrations/tabbing1-mod5.tex}{\texttt{tabbing1-mod5.tex}}{lst:tabbing1-mod5} + \cmhlistingsfromfile{demonstrations/delimiterRegEx5.yaml}[yaml-TCB]{\texttt{delimiterRegEx5.yaml}}{lst:delimiterRegEx5} \end{cmhtcbraster} Note that in \cref{lst:tabbing1-mod5} the second set of delimiters have been @@ -686,11 +731,13 @@ latexindent.pl tabbing1.tex -l=delimiterRegEx5.yaml -o=+-mod5 \cmhlistingsfromfile[style=itemNames]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{itemNames}}{lst:itemNames} \yamltitle{specialBeginEnd}*{fields}\label{yaml:specialBeginEnd} - The fields specified% + The fields specified + \index{specialBeginEnd!introduction}% \announce{2017-08-21}*{specialBeginEnd} in \texttt{specialBeginEnd} are, in their default state, focused on math mode begin and end statements, but there is no requirement for this to be the case; \cref{lst:specialBeginEnd} shows the default settings of \texttt{specialBeginEnd}. + \index{specialBeginEnd!default settings} \cmhlistingsfromfile[style=specialBeginEnd]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{specialBeginEnd}}{lst:specialBeginEnd} @@ -721,6 +768,7 @@ latexindent.pl tabbing1.tex -l=delimiterRegEx5.yaml -o=+-mod5 \cmhlistingsfromfile{demonstrations/specialLR.tex}{\texttt{specialLR.tex}}{lst:specialLRbefore} Now consider the YAML files shown in \cref{lst:specialsLeftRight-yaml,lst:specialBeforeCommand-yaml} + \index{specialBeginEnd!searching for special before commands} \begin{cmhtcbraster} \cmhlistingsfromfile[]*{demonstrations/specialsLeftRight.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{specialsLeftRight.yaml}}{lst:specialsLeftRight-yaml} @@ -728,6 +776,7 @@ latexindent.pl tabbing1.tex -l=delimiterRegEx5.yaml -o=+-mod5 \end{cmhtcbraster} Upon running the following commands + \index{switches!-l demonstration} \begin{widepage} \begin{commandshell} latexindent.pl specialLR.tex -l=specialsLeftRight.yaml @@ -757,10 +806,13 @@ latexindent.pl specialLR.tex -l=specialsLeftRight.yaml,specialBeforeCommand.yaml \announce{2018-04-27}{update to specialBeginEnd} the \texttt{middle} field for anything that you specify in \texttt{specialBeginEnd}. For example, let's consider the \texttt{.tex} file in \cref{lst:special2}. + \index{specialBeginEnd!middle} + \index{specialBeginEnd!IfElsFi example} \cmhlistingsfromfile{demonstrations/special2.tex}{\texttt{special2.tex}}{lst:special2} Upon saving the YAML settings in \cref{lst:middle-yaml,lst:middle1-yaml} and running the commands + \index{switches!-l demonstration} \begin{commandshell} latexindent.pl special2.tex -l=middle latexindent.pl special2.tex -l=middle1 @@ -793,13 +845,16 @@ latexindent.pl special2.tex -l=middle1 \announce{2018-08-13}{specialBeginEnd verbatim} specify fields in \texttt{specialBeginEnd} to be treated as verbatim code blocks by changing \texttt{lookForThis} to be \texttt{verbatim}. + \index{verbatim!specialBeginEnd} For example, beginning with the code in \cref{lst:special3-mod1} and the YAML in \cref{lst:special-verb1-yaml}, and running + \index{switches!-l demonstration} \begin{commandshell} latexindent.pl special3.tex -l=special-verb1 \end{commandshell} then the output in \cref{lst:special3-mod1} is unchanged. + \index{specialBeginEnd!specifying as verbatim} \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/special-verb1.yaml}[yaml-TCB]{\texttt{special-verb1.yaml}}{lst:special-verb1-yaml} @@ -809,32 +864,47 @@ latexindent.pl special3.tex -l=special-verb1 We can combine the \texttt{specialBeginEnd} with the \texttt{lookForAlignDelims} feature. We begin with the code in \cref{lst:special-align}. - \cmhlistingsfromfile*{demonstrations/special-align.tex}{\texttt{special-align.tex}}{lst:special-align} + \cmhlistingsfromfile{demonstrations/special-align.tex}{\texttt{special-align.tex}}{lst:special-align} Let's assume that our goal is to align the code at the \texttt{edge} and \texttt{node} text; we employ the code given in \cref{lst:edge-node1} and run the command + \index{switches!-l demonstration} + \index{switches!-o demonstration} \begin{commandshell} latexindent.pl special-align.tex -l edge-node1.yaml -o=+-mod1 \end{commandshell} to receive the output in \cref{lst:special-align-mod1}. + \index{specialBeginEnd!combined with lookForAlignDelims} + \index{specialBeginEnd!delimiterRegEx} + \index{specialBeginEnd!alignment at delimiter} + \index{specialBeginEnd!tikz example} + \index{regular expressions!delimiter alignment for edge or node} + \index{delimiters!within specialBeginEnd blocks} + \index{regular expressions!numeric 0-9} \begin{cmhtcbraster}[ raster left skip=-3.5cm,] - \cmhlistingsfromfile*{demonstrations/edge-node1.yaml}[yaml-TCB]{\texttt{edge-node1.yaml}}{lst:edge-node1} - \cmhlistingsfromfile*{demonstrations/special-align-mod1.tex}{\texttt{special-align.tex} using \cref{lst:edge-node1}}{lst:special-align-mod1} + \cmhlistingsfromfile{demonstrations/edge-node1.yaml}[yaml-TCB]{\texttt{edge-node1.yaml}}{lst:edge-node1} + \cmhlistingsfromfile{demonstrations/special-align-mod1.tex}{\texttt{special-align.tex} using \cref{lst:edge-node1}}{lst:special-align-mod1} \end{cmhtcbraster} The output in \cref{lst:special-align-mod1} is not quite ideal. We can tweak the settings within \cref{lst:edge-node1} in order to improve the output; in particular, we employ the code in \cref{lst:edge-node2} and run the command + \index{switches!-l demonstration} + \index{switches!-o demonstration} + \index{regular expressions!uppercase alph A-Z} \begin{commandshell} latexindent.pl special-align.tex -l edge-node2.yaml -o=+-mod2 \end{commandshell} to receive the output in \cref{lst:special-align-mod2}. + \index{specialBeginEnd!delimiterRegEx tweaked} + \index{regular expressions!at least one +} + \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/special-align-mod2.tex}{\texttt{special-align.tex} using \cref{lst:edge-node2}}{lst:special-align-mod2} + \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} \yamltitle{indentAfterHeadings}*{fields} @@ -870,6 +940,7 @@ latexindent.pl special-align.tex -l edge-node2.yaml -o=+-mod2 \end{cmhtcbraster} If you run the command + \index{switches!-l demonstration} \begin{commandshell} latexindent.pl headings1.tex -l=headings1.yaml \end{commandshell} @@ -886,12 +957,15 @@ latexindent.pl headings1.tex -l=headings1.yaml Now say that you modify the \texttt{YAML} from \cref{lst:headings1yaml} so that the \texttt{paragraph} \texttt{level} is \texttt{1}; after running + \index{switches!-l demonstration} \begin{commandshell} latexindent.pl headings1.tex -l=headings1.yaml \end{commandshell} you should receive the code given in \cref{lst:headings1-mod2}; notice that the \texttt{paragraph} and \texttt{subsection} are at the same indentation level. + \index{indentation!maximum indetation} + \yamltitle{maximumIndentation}*{horizontal space} You can control the maximum indentation given to your file by% @@ -910,6 +984,7 @@ latexindent.pl headings1.tex -l=headings1.yaml Now say that, for example, you have the \texttt{max-indentation1.yaml} from \cref{lst:max-indentation1yaml} and that you run the following command: + \index{switches!-l demonstration} \begin{commandshell} latexindent.pl mult-nested.tex -l=max-indentation1 \end{commandshell} @@ -930,6 +1005,10 @@ latexindent.pl mult-nested.tex -l=max-indentation1 \subsection{The code blocks known latexindent.pl}\label{subsubsec:code-blocks} As of Version 3.0, \texttt{latexindent.pl} processes documents using code blocks; each of these are shown in \cref{tab:code-blocks}. + \index{regular expressions!uppercase alph A-Z} + \index{regular expressions!lowercase alph a-z} + \index{regular expressions!numeric 0-9} + \index{regular expressions!horizontal space \textbackslash{h}} \begin{table}[!htp] \begin{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 f026a176231..ccd04ffb47a 100644 --- a/Master/texmf-dist/doc/support/latexindent/sec-fine-tuning.tex +++ b/Master/texmf-dist/doc/support/latexindent/sec-fine-tuning.tex @@ -7,6 +7,21 @@ This field is for those that would like to peek under the bonnet/hood and make some fine tuning to \texttt{latexindent.pl}'s operating. + \index{warning!fine tuning} + \index{regular expressions!fine tuning} + \index{regular expressions!environments} + \index{regular expressions!ifElseFi} + \index{regular expressions!commands} + \index{regular expressions!keyEqualsValuesBracesBrackets} + \index{regular expressions!NamedGroupingBracesBrackets} + \index{regular expressions!UnNamedGroupingBracesBrackets} + \index{regular expressions!arguments} + \index{regular expressions!modifyLineBreaks} + \index{regular expressions!lowercase alph a-z} + \index{regular expressions!uppercase alph A-Z} + \index{regular expressions!numeric 0-9} + \index{regular expressions!at least one +} + \index{regular expressions!horizontal space \textbackslash{h}} \begin{warning} Making changes to the fine tuning may have significant consequences for your indentation scheme, @@ -17,8 +32,8 @@ \cmhlistingsfromfile[style=fineTuning]*{../defaultSettings.yaml}[width=0.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 is - not intended to be a tutorial on regular expressions; you might like to read, for + The fields given in \cref{lst:fineTuning} are all \emph{regular expressions}. This manual + is not intended to be a tutorial on regular expressions; you might like to read, for example, \cite{masteringregexp} for a detailed covering of the topic. We make the following comments with reference to \cref{lst:fineTuning}: @@ -34,6 +49,7 @@ \item \lstinline!_! underscores \item \lstinline!\! backslashes \end{enumerate} + \index{regular expressions!at least one +} The \texttt{+} at the end means \emph{at least one} of the above characters. \item the \texttt{ifElseFi:name} field: @@ -99,10 +115,12 @@ latexindent.pl finetuning1.tex It's clear from \cref{lst:finetuning1-default} that the indentation scheme has not worked as expected. We can \emph{fine tune} the indentation scheme by employing the settings given in \cref{lst:fine-tuning1} and running the command + \index{switches!-l demonstration} \begin{commandshell} latexindent.pl finetuning1.tex -l=fine-tuning1.yaml \end{commandshell} and the associated (desired) output is given in \cref{lst:finetuning1-mod1}. + \index{regular expressions!at least one +} \begin{cmhtcbraster}[raster column skip=.01\linewidth] \cmhlistingsfromfile{demonstrations/finetuning1-mod1.tex}{\texttt{finetuning1.tex} using \cref{lst:fine-tuning1}}{lst:finetuning1-mod1} @@ -121,13 +139,14 @@ latexindent.pl finetuning2.tex \begin{cmhtcbraster}[raster column skip=.01\linewidth, raster left skip=-3.75cm, raster right skip=0cm,] - \cmhlistingsfromfile*{demonstrations/finetuning2.tex}{\texttt{finetuning2.tex}}{lst:finetuning2} - \cmhlistingsfromfile*{demonstrations/finetuning2-default.tex}{\texttt{finetuning2.tex} default}{lst:finetuning2-default} + \cmhlistingsfromfile{demonstrations/finetuning2.tex}{\texttt{finetuning2.tex}}{lst:finetuning2} + \cmhlistingsfromfile{demonstrations/finetuning2-default.tex}{\texttt{finetuning2.tex} default}{lst:finetuning2-default} \end{cmhtcbraster} It's clear from \cref{lst:finetuning2-default} that the indentation scheme has not worked as expected. We can \emph{fine tune} the indentation scheme by employing the settings given in \cref{lst:fine-tuning2} and running the command + \index{switches!-l demonstration} \begin{commandshell} latexindent.pl finetuning2.tex -l=fine-tuning2.yaml \end{commandshell} @@ -136,10 +155,22 @@ latexindent.pl finetuning2.tex -l=fine-tuning2.yaml \begin{cmhtcbraster}[raster column skip=.01\linewidth, raster left skip=-3.75cm, raster right skip=0cm,] - \cmhlistingsfromfile*{demonstrations/finetuning2-mod1.tex}{\texttt{finetuning2.tex} using \cref{lst:fine-tuning2}}{lst:finetuning2-mod1} - \cmhlistingsfromfile*[style=yaml-LST]*{demonstrations/fine-tuning2.yaml}[yaml-TCB]{\texttt{finetuning2.yaml}}{lst:fine-tuning2} + \cmhlistingsfromfile{demonstrations/finetuning2-mod1.tex}{\texttt{finetuning2.tex} using \cref{lst:fine-tuning2}}{lst:finetuning2-mod1} + \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/fine-tuning2.yaml}[yaml-TCB]{\texttt{finetuning2.yaml}}{lst:fine-tuning2} \end{cmhtcbraster} In particular, note that the settings in \cref{lst:fine-tuning2} specify that \texttt{NamedGroupingBracesBrackets} and \texttt{UnNamedGroupingBracesBrackets} can follow \texttt{"} and that we allow \lstinline!---! between arguments. \end{example} + + \begin{example} + You can tweak the \texttt{fineTuning} using the \texttt{-y} switch, but to be sure to use quotes appropriately. + For example, starting with the code in \cref{lst:finetuning3} and running the following command + \begin{commandshell} +latexindent.pl -m -y='modifyLineBreaks:oneSentencePerLine:manipulateSentences: 1, modifyLineBreaks:oneSentencePerLine:sentencesBeginWith:a-z: 1, fineTuning:modifyLineBreaks:betterFullStop: "(?:\.|;|:(?![a-z]))|(?:(?} + \index{switches!-c, --cruft definition and details} \begin{commandshell} latexindent.pl -c=/path/to/directory/ myfile.tex \end{commandshell} @@ -290,6 +305,7 @@ latexindent.pl -c=/path/to/directory/ myfile.tex directory. Note the use of a trailing forward slash. % this switch was made as a result of http://tex.stackexchange.com/questions/142652/output-latexindent-auxiliary-files-to-a-different-directory \flagbox{-g, --logfile=} + \index{switches!-g, --logfile definition and details} \begin{commandshell} latexindent.pl -g=other.log myfile.tex latexindent.pl -g other.log myfile.tex @@ -302,6 +318,7 @@ latexindent.pl myfile.tex -g other.log after the \texttt{-g} switch as demonstrated above. \flagbox{-sl, --screenlog} + \index{switches!-sl, --screenlog definition and details} \begin{commandshell} latexindent.pl -sl myfile.tex latexindent.pl -screenlog myfile.tex @@ -312,6 +329,7 @@ latexindent.pl -screenlog myfile.tex log file. \flagbox{-m, --modifylinebreaks} + \index{switches!-m, --modifylinebreaks definition and details} \begin{commandshell} latexindent.pl -m myfile.tex latexindent.pl -modifylinebreaks myfile.tex @@ -361,6 +379,7 @@ latexindent.pl to signify that your input has finished. Thanks to \cite{xu-cheng} for an update to this feature. \flagbox{-r, --replacement} + \index{switches!-r, --replacement definition and details} \begin{commandshell} latexindent.pl -r myfile.tex latexindent.pl -replacement myfile.tex @@ -370,8 +389,10 @@ latexindent.pl -replacement myfile.tex \texttt{latexindent.pl} with the \texttt{-r} switch to instruct it to perform replacements/substitutions on your file; full details and examples are given in \vref{sec:replacements}. + \index{verbatim!rv, replacementrespectverb switch} \flagbox{-rv, --replacementrespectverb} + \index{switches!-rv, --replacementrespectverb definition and details} \begin{commandshell} latexindent.pl -rv myfile.tex latexindent.pl -replacementrespectverb myfile.tex @@ -383,6 +404,7 @@ latexindent.pl -replacementrespectverb myfile.tex examples are given in \vref{sec:replacements}. \flagbox{-rr, --onlyreplacement} + \index{switches!-rr, --onlyreplacement definition and details} \begin{commandshell} latexindent.pl -rr myfile.tex latexindent.pl -onlyreplacement myfile.tex 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 cb551194c0e..40216948a77 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 @@ -52,6 +52,7 @@ paths: the \texttt{tabbing} environment/command to the list of environments that contains alignment delimiters; you might also like to refer to the many YAML files detailed throughout the rest of this documentation. + \index{indentation!defaultIndent using YAML file} \begin{yaml}{\texttt{mysettings.yaml} (example)}{lst:mysettings} # Default value of indentation @@ -68,6 +69,7 @@ lookForAlignDelims: then you'll get a warning, otherwise you'll get confirmation that \texttt{latexindent.pl} has read your settings file \footnote{Windows users may find that they have to end \texttt{.yaml} files with a blank line}. + \index{warning!editing YAML files} \begin{warning} When editing \texttt{.yaml} files it is \emph{extremely} important @@ -79,15 +81,29 @@ lookForAlignDelims: will tell you so in \texttt{indent.log}. \end{warning} -\subsection{localSettings.yaml}\label{sec:localsettings} +\subsection{localSettings.yaml and friends}\label{sec:localsettings} The \texttt{-l} switch tells \texttt{latexindent.pl} to look for - \texttt{localSettings.yaml} in the \emph{same directory} as \texttt{myfile.tex}. 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} example, if you use the following command + \index{switches!-l demonstration} \begin{commandshell} latexindent.pl -l myfile.tex \end{commandshell} - then \texttt{latexindent.pl} will (assuming it exists) load \texttt{localSettings.yaml} from - the same directory as \texttt{myfile.tex}. + then \texttt{latexindent.pl} will search for and then, assuming they exist, load each of + the following files in the following order: + \begin{enumerate} + \item localSettings.yaml + \item latexindent.yaml + \item .localSettings.yaml + \item .latexindent.yaml + \end{enumerate} + These files will be assumed to be in the same directory as \texttt{myfile.tex}, or + otherwise in the current working directory. You do not need to have all of the above + files, usually just one will be sufficient. In what follows, whenever we refer to + \texttt{localSettings.yaml} it is assumed that it can mean any of the four named options + listed above. If you'd prefer to name your \texttt{localSettings.yaml} file something different, (say, \texttt{mysettings.yaml} as in \cref{lst:mysettings}) then you can call @@ -103,6 +119,7 @@ latexindent.pl -l=mysettings.yaml myfile.tex Your settings file can contain any switches that you'd like to change; a sample is shown in \cref{lst:localSettings}, and you'll find plenty of further examples throughout this manual. + \index{verbatim!verbatimEnvironments demonstration (-l switch)} \begin{yaml}{\texttt{localSettings.yaml} (example)}{lst:localSettings} # verbatim environments - environments specified @@ -123,17 +140,21 @@ verbatimEnvironments: \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: + \index{verbatim!verbatimEnvironments demonstration (-y switch)} \begin{commandshell} latexindent.pl -y="verbatimEnvironments:cmhenvironment:0;myenv:1" myfile.tex \end{commandshell} Note the use of \texttt{;} to specify another field within \texttt{verbatimEnvironments}. This is shorthand, and equivalent, to using the following command: + \index{switches!-y demonstration} \begin{commandshell} latexindent.pl -y="verbatimEnvironments:cmhenvironment:0,verbatimEnvironments:myenv:1" myfile.tex \end{commandshell} You may, of course, specify settings using the \texttt{-y} switch as well as, for example, settings loaded using the \texttt{-l} switch; for example, + \index{switches!-l demonstration} + \index{switches!-y demonstration} \begin{commandshell} latexindent.pl -l=mysettings.yaml -y="verbatimEnvironments:cmhenvironment:0;myenv:1" myfile.tex \end{commandshell} @@ -142,16 +163,18 @@ latexindent.pl -l=mysettings.yaml -y="verbatimEnvironments:cmhenvironment:0;myen \texttt{-l} switch. If you wish to specify any regex-based settings using the \texttt{-y} switch, - it is important not to use quotes surrounding the regex; for example, with reference to - the `one sentence per line' feature (\vref{sec:onesentenceperline}) and the listings within - \vref{lst:sentencesEndWith}, the following settings give the option to have sentences end - with a semicolon + \index{regular expressions!using -y switch} it is important not to use quotes surrounding the regex; for + example, with reference to the `one sentence per line' feature (\vref{sec:onesentenceperline}) + and the listings within \vref{lst:sentencesEndWith}, the following settings give the option + to have sentences end with a semicolon + \index{switches!-y demonstration} \begin{commandshell} latexindent.pl -m --yaml='modifyLineBreaks:oneSentencePerLine:sentencesEndWith:other:\;' \end{commandshell} \subsection{Settings load order}\label{sec:loadorder} \texttt{latexindent.pl} loads the settings files in the following order: + \index{switches!-l in relation to other settings} \begin{enumerate} \item \texttt{defaultSettings.yaml} is always loaded, and can not be renamed; \item \texttt{anyUserSettings.yaml} and any other arbitrarily-named files specified in diff --git a/Master/texmf-dist/doc/support/latexindent/sec-introduction.tex b/Master/texmf-dist/doc/support/latexindent/sec-introduction.tex index a6a2627309f..887a0968876 100644 --- a/Master/texmf-dist/doc/support/latexindent/sec-introduction.tex +++ b/Master/texmf-dist/doc/support/latexindent/sec-introduction.tex @@ -41,9 +41,11 @@ works as you expect it to; if it does not, please first of all make sure that you have the correct settings, and then feel free to let me know at \cite{latexindent-home} with a complete minimum working example as I would like to improve the code as much as possible. + \begin{warning} Before you try the script on anything important (like your thesis), test it out on the sample files in the \texttt{test-case} directory \cite{latexindent-home}. + \index{warning!be sure to test before use} \end{warning} \emph{If you have used any version 2.* of \texttt{latexindent.pl}, there @@ -130,6 +132,7 @@ perl latexindent-module-installer.pl \vref{sec:requiredmodules}. \subsection{A word about regular expressions} + \index{regular expressions!a word about} As you read this documentation, you may encounter the term \emph{regular expressions}. I've tried to write this documentation in such a way so as to allow you to engage with them or not, as you prefer. This documentation is not designed to be a guide to regular diff --git a/Master/texmf-dist/doc/support/latexindent/sec-replacements.tex b/Master/texmf-dist/doc/support/latexindent/sec-replacements.tex index aa575f269fc..4362f347203 100644 --- a/Master/texmf-dist/doc/support/latexindent/sec-replacements.tex +++ b/Master/texmf-dist/doc/support/latexindent/sec-replacements.tex @@ -8,6 +8,7 @@ You can instruct \texttt{latexindent.pl} to perform replacements/substitutions on your \announce{2019-07-13}{replacement mode switches} file by using any of the \texttt{-r}, \texttt{-rv} or \texttt{-rr} switches: + \index{verbatim!rv, replacementrespectverb switch} \begin{itemize} \item the \texttt{-r} switch will perform indentation and replacements, not respecting verbatim code blocks; @@ -58,6 +59,7 @@ replace every instance of the text \texttt{latexindent.pl} with \texttt{pl.latexindent}. Beginning with the code in \cref{lst:replace1} and running the command + \index{switches!-r demonstration} \begin{commandshell} latexindent.pl -r replace1.tex \end{commandshell} @@ -71,6 +73,8 @@ latexindent.pl -r replace1.tex If we don't wish to perform this replacement, then we can tweak the default settings of \vref{lst:replacements} by changing \texttt{lookForThis} to 0; we perform this action in \cref{lst:replace1-yaml}, and run the command + \index{switches!-l demonstration} + \index{switches!-r demonstration} \begin{commandshell} latexindent.pl -r replace1.tex -l=replace1.yaml \end{commandshell} @@ -94,6 +98,7 @@ latexindent.pl -r replace1.tex -l=replace1.yaml \emph{this} with the string in \emph{that}. If you specify \texttt{this} and you do not specify \texttt{that}, then the \texttt{that} field will be assumed to be empty. + \index{regular expressions!replacement switch, -r} \item \emph{regex}-based replacements, which use the \texttt{substitution} field. \end{enumerate} We will demonstrate both in the examples that follow. @@ -113,6 +118,8 @@ latexindent.pl -r replace1.tex -l=replace1.yaml a few different ways. Using the YAML in \cref{lst:colsep-yaml}, and running the command + \index{switches!-l demonstration} + \index{switches!-r demonstration} \begin{commandshell} latexindent.pl -r colsep.tex -l=colsep.yaml \end{commandshell} @@ -127,10 +134,14 @@ latexindent.pl -r colsep.tex -l=colsep.yaml We can make the YAML in \cref{lst:colsep-yaml} more concise by exploring the \texttt{substitution} field. Using the settings in \cref{lst:colsep1} and running the command + \index{switches!-l demonstration} + \index{switches!-r demonstration} \begin{commandshell} latexindent.pl -r colsep.tex -l=colsep1.yaml \end{commandshell} then we achieve the output in \cref{lst:colsep-mod1}. + \index{regular expressions!substitution field, arraycolsep} + \index{regular expressions!at least one +} \begin{cmhtcbraster}[raster column skip=.01\linewidth, raster force size=false, raster column 1/.style={add to width=-.1\textwidth}] @@ -162,6 +173,8 @@ latexindent.pl -r colsep.tex -l=colsep1.yaml We'll keep working with the file in \vref{lst:colsep} for this example. Using the YAML in \cref{lst:multi-line}, and running the command + \index{switches!-l demonstration} + \index{switches!-r demonstration} \begin{commandshell} latexindent.pl -r colsep.tex -l=multi-line.yaml \end{commandshell} @@ -179,6 +192,8 @@ latexindent.pl -r colsep.tex -l=multi-line.yaml The default value is \texttt{before}. Using the YAML in \cref{lst:multi-line1}, and running the command + \index{switches!-l demonstration} + \index{switches!-r demonstration} \begin{commandshell} latexindent.pl -r colsep.tex -l=multi-line1.yaml \end{commandshell} @@ -192,6 +207,8 @@ latexindent.pl -r colsep.tex -l=multi-line1.yaml indentation, the string as written in \cref{lst:multi-line1} is no longer part of the file, and has therefore not been replaced. As a final note on this example, if you use the \texttt{-rr} switch, as follows, + \index{switches!-l demonstration} + \index{switches!-rr demonstration} \begin{commandshell} latexindent.pl -rr colsep.tex -l=multi-line1.yaml \end{commandshell} @@ -208,10 +225,13 @@ latexindent.pl -rr colsep.tex -l=multi-line1.yaml \cmhlistingsfromfile{demonstrations/displaymath.tex}{\texttt{displaymath.tex}}{lst:displaymath} We use the settings in \cref{lst:displaymath1} and run the command + \index{switches!-l demonstration} + \index{switches!-r demonstration} \begin{commandshell} latexindent.pl -r displaymath.tex -l=displaymath1.yaml \end{commandshell} to receive the output given in \cref{lst:displaymath-mod1}. + \index{regular expressions!substitution field, equation} \begin{cmhtcbraster}[raster left skip=-3.75cm, raster right skip=-2cm,] @@ -233,6 +253,9 @@ latexindent.pl -r displaymath.tex -l=displaymath1.yaml The features of the replacement switches can, of course, be combined with others from the toolkit of \texttt{latexindent.pl}. For example, we can combine the poly-switches of \vref{sec:poly-switches}, which we do in \cref{lst:equation}; upon running the command + \index{switches!-l demonstration} + \index{switches!-m demonstration} + \index{switches!-r demonstration} \begin{commandshell} latexindent.pl -r -m displaymath.tex -l=displaymath1.yaml,equation.yaml \end{commandshell} @@ -255,10 +278,14 @@ latexindent.pl -r -m displaymath.tex -l=displaymath1.yaml,equation.yaml Our goal is to make the spacing uniform between the phrases. To achieve this, we employ the settings in \cref{lst:hspace}, and run the command + \index{switches!-l demonstration} + \index{switches!-r demonstration} \begin{commandshell} latexindent.pl -r phrase.tex -l=hspace.yaml \end{commandshell} which gives the output in \cref{lst:phrase-mod1}. + \index{regular expressions!at least one +} + \index{regular expressions!horizontal space \textbackslash{h}} \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/phrase-mod1.tex}{\texttt{phrase.tex} using \cref{lst:hspace}}{lst:phrase-mod1} @@ -275,10 +302,13 @@ latexindent.pl -r phrase.tex -l=hspace.yaml Our goal is to change each reference so that both the text and the reference are contained within one hyperlink. We achieve this by employing \cref{lst:reference} and running the command + \index{switches!-l demonstration} + \index{switches!-r demonstration} \begin{commandshell} latexindent.pl -r references.tex -l=reference.yaml \end{commandshell} which gives the output in \cref{lst:references-mod1}. + \index{regular expressions!horizontal space \textbackslash{h}} \cmhlistingsfromfile{demonstrations/references-mod1.tex}{\texttt{references.tex} using \cref{lst:reference}}{lst:references-mod1} @@ -298,6 +328,12 @@ latexindent.pl -r references.tex -l=reference.yaml \end{cmhtcbraster} Upon running the following commands, + \index{verbatim!comparison with -r and -rr switches} + \index{switches!-l demonstration} + \index{switches!-o demonstration} + \index{switches!-r demonstration} + \index{switches!-rv demonstration} + \index{switches!-rr demonstration} \begin{commandshell} latexindent.pl -r verb1.tex -l=verbatim1.yaml -o=+mod1 latexindent.pl -rv verb1.tex -l=verbatim1.yaml -o=+-rv-mod1 @@ -344,6 +380,8 @@ latexindent.pl -rr verb1.tex -l=verbatim1.yaml -o=+-rr-mod1 \end{cmhtcbraster} Upon running the following commands, + \index{switches!-l demonstration} + \index{switches!-r demonstration} \begin{commandshell} latexindent.pl -r amalg1.tex -l=amalg1-yaml latexindent.pl -r amalg1.tex -l=amalg1-yaml,amalg2-yaml 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 03e09db2598..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 @@ -27,6 +27,7 @@ Having read the previous paragraph, it should sound reasonable that, if you call \texttt{latexindent.pl} using the \texttt{-m} switch, then you give it permission to modify line breaks in your file, but let's be clear: + \index{warning!the m switch} \begin{warning} If you call \texttt{latexindent.pl} with the \texttt{-m} switch, then you @@ -47,6 +48,7 @@ \texttt{0}, \texttt{latexindent.pl} will condense multiple blank lines into the number of blank lines illustrated by this switch. As an example, \cref{lst:mlb-bl} shows a sample file with blank lines; upon running + \index{switches!-m demonstration} \begin{commandshell} latexindent.pl myfile.tex -m \end{commandshell} @@ -72,6 +74,7 @@ latexindent.pl myfile.tex -m \texttt{latexindent.pl} will \emph{not} wrap text; if you change it to a value of \texttt{2} or more, then text will be wrapped after the character in the specified column. + \index{modifying linebreaks! by text wrapping, globally} \cmhlistingsfromfile[style=textWrapOptions]*{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{textWrapOptions}}{lst:textWrapOptions} @@ -83,6 +86,9 @@ latexindent.pl myfile.tex -m Using the file \texttt{textwrap1.yaml} in \cref{lst:textwrap1-yaml}, and running the command + \index{switches!-l demonstration} + \index{switches!-m demonstration} + \index{switches!-o demonstration} \begin{commandshell} latexindent.pl -m textwrap1.tex -o textwrap1-mod1.tex -l textwrap1.yaml \end{commandshell} @@ -94,13 +100,17 @@ latexindent.pl -m textwrap1.tex -o textwrap1-mod1.tex -l textwrap1.yaml \end{cmhtcbraster} The text wrapping routine is performed \emph{after} verbatim environments - have been stored, so verbatim environments and verbatim commands are exempt from the - routine. For example, using the file in \cref{lst:textwrap2}, + \index{verbatim!in relation to textWrapOptions} have been stored, so verbatim environments and verbatim + commands are exempt from the routine. For example, using the file in + \cref{lst:textwrap2}, \begin{widepage} \cmhlistingsfromfile{demonstrations/textwrap2.tex}{\texttt{textwrap2.tex}}{lst:textwrap2} \end{widepage} and running the following command and continuing to use \texttt{textwrap1.yaml} from \cref{lst:textwrap1-yaml}, + \index{switches!-l demonstration} + \index{switches!-m demonstration} + \index{switches!-o demonstration} \begin{commandshell} latexindent.pl -m textwrap2.tex -o textwrap2-mod1.tex -l textwrap1.yaml \end{commandshell} @@ -116,6 +126,9 @@ latexindent.pl -m textwrap2.tex -o textwrap2-mod1.tex -l textwrap1.yaml \end{widepage} and running the following command and continuing to use \texttt{textwrap1.yaml} from \cref{lst:textwrap1-yaml}, + \index{switches!-l demonstration} + \index{switches!-m demonstration} + \index{switches!-o demonstration} \begin{commandshell} latexindent.pl -m textwrap3.tex -o textwrap3-mod1.tex -l textwrap1.yaml \end{commandshell} @@ -134,6 +147,9 @@ latexindent.pl -m textwrap3.tex -o textwrap3-mod1.tex -l textwrap1.yaml \cmhlistingsfromfile{demonstrations/textwrap4.tex}{\texttt{textwrap4.tex}}{lst:textwrap4} and using \texttt{textwrap2.yaml} from \cref{lst:textwrap2-yaml} with the following command + \index{switches!-l demonstration} + \index{switches!-m demonstration} + \index{switches!-o demonstration} \begin{commandshell} latexindent.pl -m textwrap4.tex -o textwrap4-mod2.tex -l textwrap2.yaml \end{commandshell} @@ -149,6 +165,9 @@ latexindent.pl -m textwrap4.tex -o textwrap4-mod2.tex -l textwrap2.yaml \announce{2019-09-07}{huge option for text wrap module}. This can be helpful if you would like to forbid the \texttt{Text::Wrap} routine from breaking words. For example, using the settings in \cref{lst:textwrap2A-yaml,lst:textwrap2B-yaml} and running the commands + \index{switches!-l demonstration} + \index{switches!-m demonstration} + \index{switches!-o demonstration} \begin{commandshell} latexindent.pl -m textwrap4.tex -o=+-mod2A -l textwrap2A.yaml latexindent.pl -m textwrap4.tex -o=+-mod2B -l textwrap2B.yaml @@ -163,12 +182,15 @@ latexindent.pl -m textwrap4.tex -o=+-mod2B -l textwrap2B.yaml \cmhlistingsfromfile{demonstrations/textwrap2B.yaml}[MLB-TCB]{\texttt{textwrap2B.yaml}}{lst:textwrap2B-yaml} \end{cmhtcbraster} - You can also specify the \texttt{tabstop} field% - \announce*{2020-11-06}{tabstop option for text wrap module} as - an integer value, which is passed to the text wrap module; see - \cite{textwrap} for details. Starting with the code in - \cref{lst:textwrap-ts} with settings in \cref{lst:tabstop}, and running the - command + You can also specify the \texttt{tabstop} + field% + \announce{2020-11-06}{tabstop option for text wrap module} as an integer + value, which is passed to the text wrap module; see \cite{textwrap} for + details. Starting with the code in \cref{lst:textwrap-ts} with settings in + \cref{lst:tabstop}, and running the command + \index{switches!-l demonstration} + \index{switches!-m demonstration} + \index{switches!-o demonstration} \begin{commandshell} latexindent.pl -m textwrap-ts.tex -o=+-mod1 -l tabstop.yaml \end{commandshell} @@ -177,9 +199,9 @@ latexindent.pl -m textwrap-ts.tex -o=+-mod1 -l tabstop.yaml raster left skip=-3.5cm, raster right skip=-2cm, raster column skip=.03\linewidth] - \cmhlistingsfromfile*[showtabs=true]*{demonstrations/textwrap-ts.tex}{\texttt{textwrap-ts.tex}}{lst:textwrap-ts} - \cmhlistingsfromfile*{demonstrations/tabstop.yaml}[MLB-TCB]{\texttt{tabstop.yaml}}{lst:tabstop} - \cmhlistingsfromfile*[showtabs=true]*{demonstrations/textwrap-ts-mod1.tex}{\texttt{textwrap-ts-mod1.tex}}{lst:textwrap-ts-mod1} + \cmhlistingsfromfile[showtabs=true]*{demonstrations/textwrap-ts.tex}{\texttt{textwrap-ts.tex}}{lst:textwrap-ts} + \cmhlistingsfromfile{demonstrations/tabstop.yaml}[MLB-TCB]{\texttt{tabstop.yaml}}{lst:tabstop} + \cmhlistingsfromfile[showtabs=true]*{demonstrations/textwrap-ts-mod1.tex}{\texttt{textwrap-ts-mod1.tex}}{lst:textwrap-ts-mod1} \end{cmhtcbraster} You can specify \texttt{break} and \texttt{unexpand} options in @@ -195,9 +217,11 @@ latexindent.pl -m textwrap-ts.tex -o=+-mod1 -l tabstop.yaml instruct \texttt{latexindent.pl} to apply \texttt{textWrap} on a per-code-block basis. Thanks to \cite{zoehneto} for their help in testing and shaping this feature. + \index{modifying linebreaks! by text wrapping, per-code-block} The full details of \texttt{textWrapOptions} are shown in \cref{lst:textWrapOptionsAll}. In particular, note the field \texttt{perCodeBlockBasis: 0}. + \index{specialBeginEnd!textWrapOptions} \cmhlistingsfromfile[style=textWrapOptionsAll]*{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{textWrapOptions}}{lst:textWrapOptionsAll} @@ -245,6 +269,8 @@ latexindent.pl -m textwrap-ts.tex -o=+-mod1 -l tabstop.yaml \end{itemize} Upon running the following commands + \index{switches!-l demonstration} + \index{switches!-m demonstration} \begin{commandshell} latexindent.pl -s textwrap5.tex -l=textwrap3.yaml -m latexindent.pl -s textwrap5.tex -l=textwrap4.yaml -m @@ -262,6 +288,8 @@ latexindent.pl -s textwrap5.tex -l=textwrap5.yaml -m \end{widepage} In particular, upon running + \index{switches!-l demonstration} + \index{switches!-m demonstration} \begin{commandshell} latexindent.pl -s textwrap6.tex -l=textwrap5.yaml -m \end{commandshell} @@ -292,6 +320,8 @@ latexindent.pl -s textwrap6.tex -l=textwrap5.yaml -m \end{adjustwidth} Upon running the commands + \index{switches!-l demonstration} + \index{switches!-m demonstration} \begin{commandshell} latexindent.pl -s textwrap6.tex -l=textwrap6.yaml -m latexindent.pl -s textwrap6.tex -l=textwrap7.yaml -m @@ -334,6 +364,8 @@ latexindent.pl -s textwrap6.tex -l=textwrap8.yaml -m \Cref{lst:textwrap9-yaml} and \cref{lst:textwrap10-yaml} are equivalent. Upon running the commands + \index{switches!-l demonstration} + \index{switches!-m demonstration} \begin{commandshell} latexindent.pl -s textwrap6.tex -l=textwrap9.yaml -m latexindent.pl -s textwrap6.tex -l=textwrap11.yaml -m @@ -372,6 +404,7 @@ latexindent.pl -s textwrap6.tex -l=textwrap11.yaml -m \subsubsection{Summary of text wrapping} It is important to note the following: + \index{verbatim!within summary of text wrapping} \begin{itemize} \item Verbatim environments (\vref{lst:verbatimEnvironments}) and verbatim commands (\vref{lst:verbatimCommands}) will \emph{not} be affected by the text @@ -394,6 +427,11 @@ latexindent.pl -s textwrap6.tex -l=textwrap11.yaml -m it puts one sentence per line. Thank you to \cite{mlep} for helping to shape and test this feature. The behaviour of this part of the script is controlled by the switches detailed in \cref{lst:oneSentencePerLine}, all of which we discuss next. + \index{modifying linebreaks! by using one sentence per line} + \index{sentences!oneSentencePerLine} + \index{sentences!one sentence per line} + \index{regular expressions!lowercase alph a-z} + \index{regular expressions!uppercase alph A-Z} \cmhlistingsfromfile[style=oneSentencePerLine]*{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{oneSentencePerLine}}{lst:oneSentencePerLine} @@ -408,12 +446,15 @@ latexindent.pl -s textwrap6.tex -l=textwrap11.yaml -m internal line breaks as \texttt{removeSentenceLineBreaks} is set to \texttt{1}. Setting this switch to \texttt{0} instructs \texttt{latexindent.pl} not to do so. + \index{sentences!removing sentence line breaks} For example, consider \texttt{multiple-sentences.tex} shown in \cref{lst:multiple-sentences}. \cmhlistingsfromfile{demonstrations/multiple-sentences.tex}{\texttt{multiple-sentences.tex}}{lst:multiple-sentences} If we use the YAML files in \cref{lst:manipulate-sentences-yaml,lst:keep-sen-line-breaks-yaml}, and run the commands + \index{switches!-l demonstration} + \index{switches!-m demonstration} \begin{widepage} \begin{commandshell} latexindent.pl multiple-sentences -m -l=manipulate-sentences.yaml @@ -439,6 +480,9 @@ latexindent.pl multiple-sentences -m -l=keep-sen-line-breaks.yaml The remainder of the settings displayed in \vref{lst:oneSentencePerLine} instruct \texttt{latexindent.pl} on how to define a sentence. From the perspective of \texttt{latexindent.pl} a sentence must: + \index{sentences!follow} + \index{sentences!begin with} + \index{sentences!end with} \begin{itemize} \item \emph{follow} a certain character or set of characters (see \cref{lst:sentencesFollow}); by default, this is either \lstinline!\par!, a @@ -452,6 +496,8 @@ latexindent.pl multiple-sentences -m -l=keep-sen-line-breaks.yaml In each case, you can specify the \texttt{other} field to include any pattern that you would like; you can specify anything in this field using the language of regular expressions. + \index{regular expressions!lowercase alph a-z} + \index{regular expressions!uppercase alph A-Z} \begin{cmhtcbraster}[raster columns=3, raster left skip=-3.5cm, @@ -466,6 +512,9 @@ latexindent.pl multiple-sentences -m -l=keep-sen-line-breaks.yaml Let's explore a few of the switches in \texttt{sentencesFollow}; let's start with \vref{lst:multiple-sentences}, and use the YAML settings given in \cref{lst:sentences-follow1-yaml}. Using the command + \index{sentences!follow} + \index{switches!-l demonstration} + \index{switches!-m demonstration} \begin{commandshell} latexindent.pl multiple-sentences -m -l=sentences-follow1.yaml \end{commandshell} @@ -486,6 +535,8 @@ latexindent.pl multiple-sentences -m -l=sentences-follow1.yaml \cmhlistingsfromfile{demonstrations/multiple-sentences1.tex}{\texttt{multiple-sentences1.tex}}{lst:multiple-sentences1} Upon running the following commands + \index{switches!-l demonstration} + \index{switches!-m demonstration} \begin{widepage} \begin{commandshell} latexindent.pl multiple-sentences1 -m -l=manipulate-sentences.yaml @@ -514,10 +565,13 @@ latexindent.pl multiple-sentences1 -m -l=manipulate-sentences.yaml,sentences-fol sentences to begin with lower case letters (see \cref{lst:sentencesBeginWith}), and we can use the \texttt{other} field to define sentences to begin with other characters. + \index{sentences!begin with} \cmhlistingsfromfile{demonstrations/multiple-sentences2.tex}{\texttt{multiple-sentences2.tex}}{lst:multiple-sentences2} Upon running the following commands + \index{switches!-l demonstration} + \index{switches!-m demonstration} \begin{widepage} \begin{commandshell} latexindent.pl multiple-sentences2 -m -l=manipulate-sentences.yaml @@ -526,6 +580,7 @@ latexindent.pl multiple-sentences2 -m -l=manipulate-sentences.yaml,sentences-beg \end{widepage} then we obtain the respective output given in \cref{lst:multiple-sentences2-mod1,lst:multiple-sentences2-mod2}. \cmhlistingsfromfile{demonstrations/multiple-sentences2-mod1.tex}{\texttt{multiple-sentences2.tex} using \vref{lst:manipulate-sentences-yaml}}{lst:multiple-sentences2-mod1} + \index{regular expressions!numeric 0-9} \begin{cmhtcbraster}[ raster force size=false, @@ -547,11 +602,15 @@ latexindent.pl multiple-sentences2 -m -l=manipulate-sentences.yaml,sentences-beg \vref{lst:multiple-sentences-mod1}. We can populate the \texttt{other} field with any character that we wish; for example, using the YAML specified in \cref{lst:sentences-end1-yaml} and the command + \index{sentences!end with} + \index{switches!-l demonstration} + \index{switches!-m demonstration} \begin{commandshell} latexindent.pl multiple-sentences -m -l=sentences-end1.yaml latexindent.pl multiple-sentences -m -l=sentences-end2.yaml \end{commandshell} then we obtain the output in \cref{lst:multiple-sentences-mod4}. + \index{regular expressions!lowercase alph a-z} \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/multiple-sentences-mod4.tex}{\texttt{multiple-sentences.tex} using \cref{lst:sentences-end1-yaml}}{lst:multiple-sentences-mod4} @@ -579,6 +638,8 @@ latexindent.pl multiple-sentences -m -l=sentences-end2.yaml \cmhlistingsfromfile{demonstrations/url.tex}{\texttt{url.tex}}{lst:url} Upon running the following commands + \index{switches!-l demonstration} + \index{switches!-m demonstration} \begin{commandshell} latexindent.pl url -m -l=manipulate-sentences.yaml \end{commandshell} @@ -605,6 +666,8 @@ latexindent.pl url -m -l=manipulate-sentences.yaml The \texttt{basicFullStop} routine should probably be avoided in most situations, as it does not accommodate the specifications above. For example, using the following command + \index{switches!-l demonstration} + \index{switches!-m demonstration} \begin{commandshell} latexindent.pl url -m -l=alt-full-stop1.yaml \end{commandshell} @@ -625,12 +688,14 @@ latexindent.pl url -m -l=alt-full-stop1.yaml \subsubsection{Features of the oneSentencePerLine routine} The sentence manipulation routine takes place \emph{after} verbatim - environments, preamble and trailing comments have been accounted for; this means that any - characters within these types of code blocks will not be part of the sentence - manipulation routine. + \index{verbatim!in relation to oneSentencePerLine} environments, preamble and trailing comments have been + accounted for; this means that any characters within these types of code blocks will not + be part of the sentence manipulation routine. For example, if we begin with the \texttt{.tex} file in \cref{lst:multiple-sentences3}, and run the command + \index{switches!-l demonstration} + \index{switches!-m demonstration} \begin{commandshell} latexindent.pl multiple-sentences3 -m -l=manipulate-sentences.yaml \end{commandshell} @@ -640,6 +705,8 @@ latexindent.pl multiple-sentences3 -m -l=manipulate-sentences.yaml Furthermore, if sentences run across environments then, by default, the line breaks internal to the sentence will be removed. For example, if we use the \texttt{.tex} file in \cref{lst:multiple-sentences4} and run the commands + \index{switches!-l demonstration} + \index{switches!-m demonstration} \begin{commandshell} latexindent.pl multiple-sentences4 -m -l=manipulate-sentences.yaml latexindent.pl multiple-sentences4 -m -l=keep-sen-line-breaks.yaml @@ -652,6 +719,8 @@ latexindent.pl multiple-sentences4 -m -l=keep-sen-line-breaks.yaml Once you've read \cref{sec:poly-switches}, you will know that you can accommodate the removal of internal sentence line breaks by using the YAML in \cref{lst:item-rules2-yaml} and the command + \index{switches!-l demonstration} + \index{switches!-m demonstration} \begin{commandshell} latexindent.pl multiple-sentences4 -m -l=item-rules2.yaml \end{commandshell} @@ -666,12 +735,16 @@ latexindent.pl multiple-sentences4 -m -l=item-rules2.yaml The \texttt{oneSentencePerLine}% \announce{2018-08-13}{oneSentencePerline text wrap and indent} can be instructed to perform text wrapping and indentation upon sentences. + \index{sentences!text wrapping} + \index{sentences!indenting} Let's use the code in \cref{lst:multiple-sentences5}. \cmhlistingsfromfile{demonstrations/multiple-sentences5.tex}{\texttt{multiple-sentences5.tex}}{lst:multiple-sentences5} Referencing \cref{lst:sentence-wrap1-yaml}, and running the following command + \index{switches!-l demonstration} + \index{switches!-m demonstration} \begin{commandshell} latexindent.pl multiple-sentences5 -m -l=sentence-wrap1.yaml \end{commandshell} @@ -704,6 +777,9 @@ latexindent.pl multiple-sentences5 -m -l=sentence-wrap1.yaml By default, \texttt{latexindent.pl} will find the full-stop within the first \texttt{item}, which means that, upon running the following commands + \index{switches!-l demonstration} + \index{switches!-m demonstration} + \index{switches!-y demonstration} \begin{commandshell} latexindent.pl multiple-sentences6 -m -l=sentence-wrap1.yaml latexindent.pl multiple-sentences6 -m -l=sentence-wrap1.yaml -y="modifyLineBreaks:oneSentencePerLine:sentenceIndent:''" @@ -724,10 +800,16 @@ latexindent.pl multiple-sentences6 -m -l=sentence-wrap1.yaml -y="modifyLineBreak not followed by \texttt{item} commands, and that the end of sentences contains \lstinline!\end{itemize}! as in \cref{lst:itemize-yaml} (if you intend to use this, ensure that you remove the line breaks from the \texttt{other} field). + \index{regular expressions!lowercase alph a-z} + \index{regular expressions!uppercase alph A-Z} + \index{regular expressions!numeric 0-9} + \index{regular expressions!horizontal space \textbackslash{h}} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/itemized.yaml}[MLB-TCB]{\texttt{itemize.yaml}}{lst:itemize-yaml} Upon running + \index{switches!-l demonstration} + \index{switches!-m demonstration} \begin{commandshell} latexindent.pl multiple-sentences6 -m -l=sentence-wrap1.yaml,itemize.yaml \end{commandshell} @@ -747,6 +829,7 @@ latexindent.pl multiple-sentences6 -m -l=sentence-wrap1.yaml,itemize.yaml \yamltitle{removeParagraphLineBreaks}*{fields} This feature is considered complimentary to the \texttt{oneSentencePerLine} feature described in \vref{sec:onesentenceperline}. + \index{specialBeginEnd!removeParagraphLineBreaks} \cmhlistingsfromfile[style=removeParagraphLineBreaks]*{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{removeParagraphLineBreaks}}{lst:removeParagraphLineBreaks} @@ -775,6 +858,9 @@ latexindent.pl multiple-sentences6 -m -l=sentence-wrap1.yaml,itemize.yaml \end{cmhtcbraster} Upon running the command + \index{switches!-l demonstration} + \index{switches!-m demonstration} + \index{switches!-o demonstration} \begin{commandshell} latexindent.pl -m shortlines.tex -o shortlines1.tex -l remove-para1.yaml \end{commandshell} @@ -786,6 +872,9 @@ latexindent.pl -m shortlines.tex -o shortlines1.tex -l remove-para1.yaml \cref{lst:shortlines} which has crept in to the output in \cref{lst:shortlines1}. This can be fixed using the YAML file in \vref{lst:removeTWS-before} and running, for example, + \index{switches!-l demonstration} + \index{switches!-m demonstration} + \index{switches!-o demonstration} \begin{commandshell} latexindent.pl -m shortlines.tex -o shortlines1-tws.tex -l remove-para1.yaml,removeTWS-before.yaml \end{commandshell} @@ -804,6 +893,9 @@ latexindent.pl -m shortlines.tex -o shortlines1-tws.tex -l remove-para1.yaml,rem \end{cmhtcbraster} Upon running the commands + \index{switches!-l demonstration} + \index{switches!-m demonstration} + \index{switches!-o demonstration} \begin{widepage} \begin{commandshell} latexindent.pl -m shortlines-mand.tex -o shortlines-mand1.tex -l remove-para1.yaml @@ -837,6 +929,9 @@ latexindent.pl -m shortlines-opt.tex -o shortlines-opt1.tex -l remove-para1.yaml \end{minipage} Upon running the commands + \index{switches!-l demonstration} + \index{switches!-m demonstration} + \index{switches!-o demonstration} \begin{widepage} \begin{commandshell} latexindent.pl -m shortlines-envs.tex -o shortlines-envs2.tex -l remove-para2.yaml @@ -864,6 +959,9 @@ latexindent.pl -m shortlines-envs.tex -o shortlines-envs3.tex -l remove-para3.ya \end{cmhtcbraster} Upon running the following command + \index{switches!-l demonstration} + \index{switches!-m demonstration} + \index{switches!-o demonstration} \begin{widepage} \begin{commandshell} latexindent.pl -m shortlines-md.tex -o shortlines-md4.tex -l remove-para4.yaml @@ -881,16 +979,18 @@ latexindent.pl -m shortlines-md.tex -o shortlines-md4.tex -l remove-para4.yaml \lstinline|\par| command to be the end of a paragraph; \announce{2017-05-27}{paragraphsStopAt} you can fine tune the behaviour of the routine further by using the \texttt{paragraphsStopAt} fields, shown in \cref{lst:paragraphsStopAt}. + \index{specialBeginEnd!paragraphsStopAt} + \index{verbatim!in relation to paragraphsStopAt} \cmhlistingsfromfile[style=paragraphsStopAt]*{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{paragraphsStopAt}}{lst:paragraphsStopAt} The fields specified in \texttt{paragraphsStopAt} tell \texttt{latexindent.pl} to stop the current paragraph when it reaches a line that \emph{begins} with any of the code-block types specified as \texttt{1} in - \cref{lst:paragraphsStopAt}. By default, you'll see that the paragraph line break routine - will stop when it reaches an environment or verbatim code block at the beginning of a - line. It is \emph{not} possible to specify these fields on a per-name - basis. + \cref{lst:paragraphsStopAt}. By default, you'll see that the paragraph line break + routine will stop when it reaches an environment or verbatim code block at the beginning + of a line. It is \emph{not} possible to specify these fields on a + per-name basis. Let's use the \texttt{.tex} file in \cref{lst:sl-stop}; we will, in turn, consider the settings in \cref{lst:stop-command-yaml,lst:stop-comment-yaml}. @@ -906,6 +1006,9 @@ latexindent.pl -m shortlines-md.tex -o shortlines-md4.tex -l remove-para4.yaml \end{minipage} Upon using the settings from \vref{lst:remove-para4-yaml} and running the commands + \index{switches!-l demonstration} + \index{switches!-m demonstration} + \index{switches!-o demonstration} \begin{widepage} \begin{commandshell} latexindent.pl -m sl-stop.tex -o sl-stop4.tex -l remove-para4.yaml @@ -959,6 +1062,9 @@ latexindent.pl -m sl-stop.tex -o sl-stop4-comment.tex -l=remove-para4.yaml,stop- switch. Explicitly, using the settings in \cref{lst:textwrap12-yaml} and running the command + \index{switches!-l demonstration} + \index{switches!-m demonstration} + \index{switches!-o demonstration} \begin{commandshell} latexindent.pl -m textwrap7.tex -l=textwrap12.yaml -o=+-mod12 \end{commandshell} @@ -978,42 +1084,50 @@ latexindent.pl -m textwrap7.tex -l=textwrap12.yaml -o=+-mod12 Every other field in the \texttt{modifyLineBreaks} field uses poly-switches, and can take one of the following% \announce{2017-08-21}*{blank line poly-switch} integer values: + \index{modifying linebreaks! using poly-switches} + \index{poly-switches!definition} + \index{poly-switches!values} + \index{poly-switches!off by default: set to 0} \begin{description} \item[$-1$] \emph{remove mode}: line breaks before or after the - \emph{} can be removed (assuming that \texttt{preserveBlankLines} is - set to \texttt{0}); + \emph{} can be removed (assuming that \texttt{preserveBlankLines} is + set to \texttt{0}); \item[0] \emph{off mode}: line breaks will not be modified for the - \emph{} under consideration; + \emph{} under consideration; \item[1] \emph{add mode}: a line break will be added before or after the - \emph{} under consideration, assuming that - there is not already a line break before or after the \emph{}; + \emph{} under consideration, assuming that + there is not already a line break before or after the \emph{}; \item[2] \emph{comment then add mode}: a comment symbol will be added, followed by a line break - before or after the \emph{} under consideration, assuming that there - is not already a comment and line break before or after the \emph{}; + before or after the \emph{} under consideration, assuming that there + is not already a comment and line break before or after the \emph{}; \item[3] \emph{add then blank line mode}% - \announce{2017-08-21}{blank line poly-switch}: a line break will be added before or after the - \emph{} under consideration, assuming that - there is not already a line break before or after the \emph{}, - followed by a blank line; + \announce{2017-08-21}{blank line poly-switch}: a line break will be added before or after the + \emph{} under consideration, assuming that + there is not already a line break before or after the \emph{}, + followed by a blank line; \item[4] \emph{add blank line mode}% - \announce{2019-07-13}{blank line poly-switch}; a blank line will - be added before or after the \emph{} under consideration, even if the - \emph{} is already on its own line. + \announce{2019-07-13}{blank line poly-switch}; a blank line will + be added before or after the \emph{} under consideration, even if the + \emph{} is already on its own line. \end{description} In the above, \emph{} refers to either the - \emph{begin statement}, \emph{body} or \emph{end statement} - of the code blocks detailed in \vref{tab:code-blocks}. All poly-switches are - \emph{off} by default; \texttt{latexindent.pl} searches first of all - for per-name settings, and then followed by global per-thing settings. + \emph{begin statement}, \emph{body} or + \emph{end statement} of the code blocks detailed in \vref{tab:code-blocks}. + All poly-switches are \emph{off} by default; + \texttt{latexindent.pl} searches first of all for per-name settings, and then + followed by global per-thing settings. \subsection{modifyLineBreaks for environments}\label{sec:modifylinebreaks-environments} We start by viewing a snippet of \texttt{defaultSettings.yaml} in \cref{lst:environments-mlb}; note that it contains \emph{global} settings (immediately after the \texttt{environments} field) and that \emph{per-name} settings are also allowed -- in the case of - \cref{lst:environments-mlb}, settings for \texttt{equation*} have been specified - for demonstration. Note that all poly-switches are \emph{off} (set to 0) by - default. + \cref{lst:environments-mlb}, settings for \texttt{equation*} have been + specified for demonstration. Note that all poly-switches are \emph{off} (set to 0) + by default. + \index{poly-switches!default values} + \index{poly-switches!environment global example} + \index{poly-switches!environment per-code block example} \cmhlistingsfromfile[style=modifylinebreaksEnv]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,MLB-TCB]{\texttt{environments}}{lst:environments-mlb} @@ -1021,6 +1135,7 @@ latexindent.pl -m textwrap7.tex -l=textwrap12.yaml -o=+-mod12 have annotated key parts of the file using $\BeginStartsOnOwnLine$, $\BodyStartsOnOwnLine$, $\EndStartsOnOwnLine$ and $\EndFinishesWithLineBreak$, these will be related to fields specified in \cref{lst:environments-mlb}. + \index{poly-switches!visualisation: $\BeginStartsOnOwnLine$, $\BodyStartsOnOwnLine$, $\EndStartsOnOwnLine$, $\EndFinishesWithLineBreak$} \begin{cmhlistings}[style=tcblatex,escapeinside={(*@}{@*)}]{\texttt{env-mlb1.tex}}{lst:env-mlb1-tex} before words(*@$\BeginStartsOnOwnLine$@*) \begin{myenv}(*@$\BodyStartsOnOwnLine$@*)body of myenv(*@$\EndStartsOnOwnLine$@*)\end{myenv}(*@$\EndFinishesWithLineBreak$@*) after words @@ -1030,6 +1145,8 @@ before words(*@$\BeginStartsOnOwnLine$@*) \begin{myenv}(*@$\BodyStartsOnOwnLine$ Let's explore \texttt{BeginStartsOnOwnLine} and \texttt{BodyStartsOnOwnLine} in \cref{lst:env-mlb1,lst:env-mlb2}, and in particular, let's allow each of them in turn to take a value of $1$. + \index{modifying linebreaks! at the \emph{beginning} of a code block} + \index{poly-switches!adding line breaks: set to 1} \begin{minipage}{.45\textwidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/env-mlb1.yaml}[MLB-TCB]{\texttt{env-mlb1.yaml}}{lst:env-mlb1} @@ -1040,6 +1157,8 @@ before words(*@$\BeginStartsOnOwnLine$@*) \begin{myenv}(*@$\BodyStartsOnOwnLine$ \end{minipage} After running the following commands, + \index{switches!-l demonstration} + \index{switches!-m demonstration} \begin{commandshell} latexindent.pl -m env-mlb.tex -l env-mlb1.yaml latexindent.pl -m env-mlb.tex -l env-mlb2.yaml @@ -1071,6 +1190,7 @@ latexindent.pl -m env-mlb.tex -l env-mlb2.yaml \cref{lst:env-mlb1,lst:env-mlb2} so that they are $2$ and save them into \texttt{env-mlb3.yaml} and \texttt{env-mlb4.yaml} respectively (see \cref{lst:env-mlb3,lst:env-mlb4}). + \index{poly-switches!adding comments and then line breaks: set to 2} \begin{minipage}{.45\textwidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/env-mlb3.yaml}[MLB-TCB]{\texttt{env-mlb3.yaml}}{lst:env-mlb3} @@ -1097,10 +1217,11 @@ latexindent.pl -m env-mlb.tex -l env-mlb2.yaml horizontal space has been stripped before doing so. Let's% - \announce{2017-08-21}{demonstration of blank line poly-switch (3)} now change each of - the \texttt{1} values in \cref{lst:env-mlb1,lst:env-mlb2} so that they are - $3$ and save them into \texttt{env-mlb5.yaml} and + \announce{2017-08-21}{demonstration of blank line poly-switch (3)} now change each + of the \texttt{1} values in \cref{lst:env-mlb1,lst:env-mlb2} so that they + are $3$ and save them into \texttt{env-mlb5.yaml} and \texttt{env-mlb6.yaml} respectively (see \cref{lst:env-mlb5,lst:env-mlb6}). + \index{poly-switches!adding blank lines: set to 3} \begin{minipage}{.45\textwidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/env-mlb5.yaml}[MLB-TCB]{\texttt{env-mlb5.yaml}}{lst:env-mlb5} @@ -1130,6 +1251,7 @@ latexindent.pl -m env-mlb.tex -l env-mlb2.yaml of the \texttt{1} values in \cref{lst:env-mlb5,lst:env-mlb6} so that they are $4$ and save them into \texttt{env-beg4.yaml} and \texttt{env-body4.yaml} respectively (see \cref{lst:env-beg4,lst:env-body4}). + \index{poly-switches!adding blank lines (again"!): set to 4} \begin{minipage}{.45\textwidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/env-beg4.yaml}[MLB-TCB]{\texttt{env-beg4.yaml}}{lst:env-beg4} @@ -1145,6 +1267,8 @@ latexindent.pl -m env-mlb.tex -l env-mlb2.yaml \cmhlistingsfromfile{demonstrations/env-mlb1.tex}{\texttt{env-mlb1.tex}}{lst:env-mlb1-text} Upon running the commands + \index{switches!-l demonstration} + \index{switches!-m demonstration} \begin{commandshell} latexindent.pl -m env-mlb1.tex -l env-beg4.yaml latexindent.pl -m env-mlb.1tex -l env-body4.yaml @@ -1170,6 +1294,8 @@ latexindent.pl -m env-mlb.1tex -l env-body4.yaml Let's explore \texttt{EndStartsOnOwnLine} and \texttt{EndFinishesWithLineBreak} in \cref{lst:env-mlb7,lst:env-mlb8}, and in particular, let's allow each of them in turn to take a value of $1$. + \index{modifying linebreaks! at the \emph{end} of a code block} + \index{poly-switches!adding line breaks: set to 1} \begin{minipage}{.49\textwidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/env-mlb7.yaml}[MLB-TCB]{\texttt{env-mlb7.yaml}}{lst:env-mlb7} @@ -1180,6 +1306,8 @@ latexindent.pl -m env-mlb.1tex -l env-body4.yaml \end{minipage} After running the following commands, + \index{switches!-l demonstration} + \index{switches!-m demonstration} \begin{commandshell} latexindent.pl -m env-mlb.tex -l env-mlb7.yaml latexindent.pl -m env-mlb.tex -l env-mlb8.yaml @@ -1210,6 +1338,7 @@ latexindent.pl -m env-mlb.tex -l env-mlb8.yaml \cref{lst:env-mlb7,lst:env-mlb8} so that they are $2$ and save them into \texttt{env-mlb9.yaml} and \texttt{env-mlb10.yaml} respectively (see \cref{lst:env-mlb9,lst:env-mlb10}). + \index{poly-switches!adding comments and then line breaks: set to 2} \begin{minipage}{.49\textwidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/env-mlb9.yaml}[MLB-TCB]{\texttt{env-mlb9.yaml}}{lst:env-mlb9} @@ -1240,6 +1369,7 @@ latexindent.pl -m env-mlb.tex -l env-mlb8.yaml of the \texttt{1} values in \cref{lst:env-mlb7,lst:env-mlb8} so that they are $3$ and save them into \texttt{env-mlb11.yaml} and \texttt{env-mlb12.yaml} respectively (see \cref{lst:env-mlb11,lst:env-mlb12}). + \index{poly-switches!adding blank lines: set to 3} \begin{minipage}{.49\textwidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/env-mlb11.yaml}[MLB-TCB]{\texttt{env-mlb11.yaml}}{lst:env-mlb11} @@ -1269,6 +1399,7 @@ latexindent.pl -m env-mlb.tex -l env-mlb8.yaml of the \texttt{1} values in \cref{lst:env-mlb11,lst:env-mlb12} so that they are $4$ and save them into \texttt{env-end4.yaml} and \texttt{env-end-f4.yaml} respectively (see \cref{lst:env-end4,lst:env-end-f4}). + \index{poly-switches!adding blank lines (again"!): set to 4} \begin{minipage}{.45\textwidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/env-end4.yaml}[MLB-TCB]{\texttt{env-end4.yaml}}{lst:env-end4} @@ -1282,6 +1413,8 @@ latexindent.pl -m env-mlb.tex -l env-mlb8.yaml \vref{lst:env-mlb1-text}. Upon running the commands + \index{switches!-l demonstration} + \index{switches!-m demonstration} \begin{commandshell} latexindent.pl -m env-mlb1.tex -l env-end4.yaml latexindent.pl -m env-mlb.1tex -l env-end-f4.yaml @@ -1351,6 +1484,7 @@ latexindent.pl -m env-mlb.1tex -l env-end-f4.yaml positions of the line break highlighters, $\BeginStartsOnOwnLine$, $\BodyStartsOnOwnLine$, $\EndStartsOnOwnLine$ and $\EndFinishesWithLineBreak$, together with the associated YAML files in \crefrange{lst:env-mlb13}{lst:env-mlb16}. + \index{poly-switches!removing line breaks: set to -1} \begin{minipage}{.45\linewidth} \begin{cmhlistings}[style=tcblatex,escapeinside={(*@}{@*)}]{\texttt{env-mlb4.tex}}{lst:mlb4} @@ -1373,6 +1507,8 @@ after words \end{minipage} After running the commands + \index{switches!-l demonstration} + \index{switches!-m demonstration} \begin{commandshell} latexindent.pl -m env-mlb4.tex -l env-mlb13.yaml latexindent.pl -m env-mlb4.tex -l env-mlb14.yaml @@ -1413,6 +1549,8 @@ latexindent.pl -m env-mlb4.tex -l env-mlb16.yaml combine all of the YAML settings in \crefrange{lst:env-mlb13}{lst:env-mlb16} into one file; alternatively, you could tell \texttt{latexindent.pl} to load them all by using the following command, for example + \index{switches!-l demonstration} + \index{switches!-m demonstration} \begin{widepage} \begin{commandshell} latexindent.pl -m env-mlb4.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,env-mlb16.yaml @@ -1440,6 +1578,8 @@ after words \end{cmhtcbraster} The output from the following commands + \index{switches!-l demonstration} + \index{switches!-m demonstration} \begin{widepage} \begin{commandshell} latexindent.pl -m env-mlb5.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,env-mlb16.yaml @@ -1459,6 +1599,7 @@ latexindent.pl -m env-mlb5.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,e \subsubsection{poly-switch line break removal and blank lines} Now let's consider the file in \cref{lst:mlb6}, which contains blank lines. + \index{poly-switches!blank lines} \begin{cmhtcbraster} \begin{cmhlistings}[style=tcblatex,escapeinside={(*@}{@*)}]{\texttt{env-mlb6.tex}}{lst:mlb6} @@ -1479,6 +1620,8 @@ after words \end{cmhtcbraster} Upon running the following commands + \index{switches!-l demonstration} + \index{switches!-m demonstration} \begin{widepage} \begin{commandshell} latexindent.pl -m env-mlb6.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,env-mlb16.yaml @@ -1510,6 +1653,8 @@ latexindent.pl -m env-mlb6.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,e \cmhlistingsfromfile{demonstrations/env-mlb7.tex}{\texttt{env-mlb7.tex}}{lst:env-mlb7-tex} Upon running the following commands + \index{switches!-l demonstration} + \index{switches!-m demonstration} \begin{commandshell} latexindent.pl -m env-mlb7.tex -l env-mlb12.yaml,env-mlb13.yaml latexindent.pl -m env-mlb7.tex -l env-mlb13.yaml,env-mlb14.yaml,UnpreserveBlankLines.yaml @@ -1538,6 +1683,9 @@ latexindent.pl -m env-mlb7.tex -l env-mlb13.yaml,env-mlb14.yaml,UnpreserveBlankL special code blocks (\vref{lst:specialafter}). Note that for these poly-switches to take effect, the name of the code block must necessarily be specified within \texttt{lookForAlignDelims} (\vref{lst:aligndelims:basic}); we will demonstrate this in what follows. + \index{delimiters!poly-switches for double back slash} + \index{modifying linebreaks! surrounding double back slash} + \index{poly-switches!for double back slash (delimiters)} Consider the code given in \cref{lst:dbs-demo}. \begin{cmhlistings}[style=tcblatex,escapeinside={(*@}{@*)}]{\texttt{tabular3.tex}}{lst:dbs-demo} @@ -1561,6 +1709,8 @@ latexindent.pl -m env-mlb7.tex -l env-mlb13.yaml,env-mlb14.yaml,UnpreserveBlankL \cref{lst:dbs-demo}, together with the YAML files given in \cref{lst:DBS1} and \cref{lst:DBS2} and running the following commands + \index{switches!-l demonstration} + \index{switches!-m demonstration} \begin{commandshell} latexindent.pl -m tabular3.tex -l DBS1.yaml latexindent.pl -m tabular3.tex -l DBS2.yaml @@ -1582,11 +1732,11 @@ latexindent.pl -m tabular3.tex -l DBS2.yaml \begin{itemize} \item \cref{lst:DBS1} specifies \texttt{DBSStartsOnOwnLine} for \emph{every} environment (that is within \texttt{lookForAlignDelims}, - \vref{yaml:lookforaligndelims}); + \vref{lst:aligndelims:advanced}); the double back slashes from \cref{lst:dbs-demo} have been moved to their own line in \cref{lst:tabular3-DBS1}; \item \cref{lst:DBS2} specifies \texttt{DBSStartsOnOwnLine} on a - \emph{per-name} basis for \texttt{tabular} (that is within \texttt{lookForAlignDelims}, \vref{yaml:lookforaligndelims}); + \emph{per-name} basis for \texttt{tabular} (that is within \texttt{lookForAlignDelims}, \vref{lst:aligndelims:advanced}); the double back slashes from \cref{lst:dbs-demo} have been moved to their own line in \cref{lst:tabular3-DBS2}, having added comment symbols before moving them. \end{itemize} @@ -1596,6 +1746,9 @@ latexindent.pl -m tabular3.tex -l DBS2.yaml \cref{lst:dbs-demo}, together with the YAML files given in \cref{lst:DBS3} and \cref{lst:DBS4} and running the following commands + \index{poly-switches!for double back slash (delimiters)} + \index{switches!-l demonstration} + \index{switches!-m demonstration} \begin{commandshell} latexindent.pl -m tabular3.tex -l DBS3.yaml latexindent.pl -m tabular3.tex -l DBS4.yaml @@ -1617,29 +1770,38 @@ latexindent.pl -m tabular3.tex -l DBS4.yaml \begin{itemize} \item \cref{lst:DBS3} specifies \texttt{DBSFinishesWithLineBreak} for \emph{every} environment (that is within \texttt{lookForAlignDelims}, - \vref{yaml:lookforaligndelims}); + \vref{lst:aligndelims:advanced}); the code following the double back slashes from \cref{lst:dbs-demo} has been moved to their own line in \cref{lst:tabular3-DBS3}; \item \cref{lst:DBS4} specifies \texttt{DBSFinishesWithLineBreak} on a - \emph{per-name} basis for \texttt{tabular} (that is within \texttt{lookForAlignDelims}, \vref{yaml:lookforaligndelims}); + \emph{per-name} basis for \texttt{tabular} (that is within \texttt{lookForAlignDelims}, \vref{lst:aligndelims:advanced}); the first double back slashes from \cref{lst:dbs-demo} have moved code following them to their own line in \cref{lst:tabular3-DBS4}, having added comment symbols before moving them; the final double back slashes have \emph{not} added a line break as they are at the end of the body within the code block. \end{itemize} -\subsubsection{Double back slash poly switches for specialBeginEnd} +\subsubsection{Double back slash poly-switches for specialBeginEnd} Let's explore the double back slash poly-switches for code blocks within \texttt{specialBeginEnd} code blocks (\vref{lst:specialBeginEnd}); we begin with the code within \cref{lst:special4}. + \index{specialBeginEnd!double backslash poly-switch demonstration} + \index{poly-switches!double backslash} + \index{poly-switches!for double back slash (delimiters)} + \index{specialBeginEnd!lookForAlignDelims} + \index{delimiters} + \index{linebreaks!summary of poly-switches} \cmhlistingsfromfile{demonstrations/special4.tex}{\texttt{special4.tex}}{lst:special4} Upon using the YAML settings in \cref{lst:DBS5}, and running the command + \index{switches!-l demonstration} + \index{switches!-m demonstration} \begin{commandshell} latexindent.pl -m special4.tex -l DBS5.yaml \end{commandshell} then we receive the output given in \cref{lst:special4-DBS5}. + \index{delimiters!with specialBeginEnd and the -m switch} \begin{cmhtcbraster}[ raster force size=false, @@ -1660,14 +1822,17 @@ latexindent.pl -m special4.tex -l DBS5.yaml symbol, followed by a line break, as it is set to a value of 2. \end{itemize} -\subsubsection{Double back slash poly switches for optional and mandatory arguments} +\subsubsection{Double back slash poly-switches for optional and mandatory arguments} For clarity, we provide a demonstration of controlling the double back slash poly-switches for optional and mandatory arguments. We begin with the code in \cref{lst:mycommand2}. + \index{poly-switches!for double back slash (delimiters)} \cmhlistingsfromfile{demonstrations/mycommand2.tex}{\texttt{mycommand2.tex}}{lst:mycommand2} Upon using the YAML settings in \cref{lst:DBS6,lst:DBS7}, and running the command + \index{switches!-l demonstration} + \index{switches!-m demonstration} \begin{commandshell} latexindent.pl -m mycommand2.tex -l DBS6.yaml latexindent.pl -m mycommand2.tex -l DBS7.yaml @@ -1694,12 +1859,15 @@ latexindent.pl -m mycommand2.tex -l DBS7.yaml The pattern matching for the double back slash will also, optionally, allow trailing square brackets that contain a measurement of vertical spacing, for example \lstinline!\\[3pt]!. + \index{poly-switches!for double back slash (delimiters)} For example, beginning with the code in \cref{lst:pmatrix3} \cmhlistingsfromfile{demonstrations/pmatrix3.tex}{\texttt{pmatrix3.tex}}{lst:pmatrix3} and running the following command, using \cref{lst:DBS3}, + \index{switches!-l demonstration} + \index{switches!-m demonstration} \begin{commandshell} latexindent.pl -m pmatrix3.tex -l DBS3.yaml \end{commandshell} @@ -1723,6 +1891,9 @@ latexindent.pl -m pmatrix3.tex -l DBS3.yaml \announce{2019-05-05}*{verbatim poly-switch} However, there are two poly-switches available for \texttt{verbatim} code blocks: environments (\vref{lst:verbatimEnvironments}), commands (\vref{lst:verbatimCommands}) and \texttt{specialBeginEnd} (\vref{lst:special-verb1-yaml}). + \index{specialBeginEnd!poly-switch summary} + \index{verbatim!poly-switch summary} + \index{poly-switches!summary of all poly-switches} \clearpage \begin{longtable}{llll} diff --git a/Master/texmf-dist/doc/support/latexindent/subsec-commands-and-their-options.tex b/Master/texmf-dist/doc/support/latexindent/subsec-commands-and-their-options.tex index a1184bf3a59..d38d4e3f549 100644 --- a/Master/texmf-dist/doc/support/latexindent/subsec-commands-and-their-options.tex +++ b/Master/texmf-dist/doc/support/latexindent/subsec-commands-and-their-options.tex @@ -41,6 +41,7 @@ \texttt{noAdditionalIndentGlobal} as discussed on \cpageref{page:command:noAddGlobal}. Upon using the YAML settings in \cref{lst:noRoundParentheses}, and running the command + \index{switches!-l demonstration} \begin{commandshell} latexindent.pl pstricks1.tex -l noRoundParentheses.yaml \end{commandshell} @@ -60,6 +61,7 @@ latexindent.pl pstricks1.tex -l noRoundParentheses.yaml \cref{lst:pstricks1-nrp}. Let's explore this using the YAML given in \cref{lst:defFunction} and run the command + \index{switches!-l demonstration} \begin{commandshell} latexindent.pl pstricks1.tex -l defFunction.yaml \end{commandshell} @@ -110,6 +112,7 @@ latexindent.pl pstricks1.tex -l defFunction.yaml We can explore this further, for example using \cref{lst:draw} and running the command + \index{switches!-l demonstration} \begin{commandshell} latexindent.pl tikz-node1.tex -l draw.yaml \end{commandshell} @@ -126,6 +129,7 @@ latexindent.pl tikz-node1.tex -l draw.yaml Let's compare this with the output from using the YAML settings in \cref{lst:no-strings}, and running the command + \index{switches!-l demonstration} \begin{commandshell} latexindent.pl tikz-node1.tex -l no-strings.yaml \end{commandshell} @@ -183,6 +187,7 @@ latexindent.pl tikz-node1.tex -l no-strings.yaml Let's compare this with the output from using the YAML settings in \cref{lst:foreach}, and running the command + \index{switches!-l demonstration} \begin{commandshell} latexindent.pl for-each.tex -l foreach.yaml \end{commandshell} @@ -239,6 +244,8 @@ latexindent.pl for-each.tex -l foreach.yaml The \texttt{amalgamate} field can be used for \texttt{commandNameSpecial}, just as for \texttt{stringsAllowedBetweenArguments}. The same condition holds as stated previously, which we state again here: + \index{warning!amalgamate field} + \begin{warning} It is important to note that the \texttt{amalgamate} field, if used, in either \texttt{commandNameSpecial} or \texttt{stringsAllowedBetweenArguments} must be in the first field, and specified using the syntax given in \cref{lst:amalgamate-demo1,lst:amalgamate-demo2,lst:amalgamate-demo3}. diff --git a/Master/texmf-dist/doc/support/latexindent/subsec-conflicting-poly-switches.tex b/Master/texmf-dist/doc/support/latexindent/subsec-conflicting-poly-switches.tex index 25ebe3efaa2..a4b98981d2c 100644 --- a/Master/texmf-dist/doc/support/latexindent/subsec-conflicting-poly-switches.tex +++ b/Master/texmf-dist/doc/support/latexindent/subsec-conflicting-poly-switches.tex @@ -3,6 +3,9 @@ It is very easy to have conflicting poly-switches; if we use the example from \vref{lst:mycommand1}, and consider the YAML settings given in \cref{lst:mycom-mlb4}. The output from running + \index{poly-switches!conflicting switches} + \index{switches!-l demonstration} + \index{switches!-m demonstration} \begin{commandshell} latexindent.pl -m -l=mycom-mlb4.yaml mycommand1.tex \end{commandshell} @@ -27,6 +30,8 @@ latexindent.pl -m -l=mycom-mlb4.yaml mycommand1.tex We can explore this further by considering the YAML settings in \cref{lst:mycom-mlb5}; upon running the command + \index{switches!-l demonstration} + \index{switches!-m demonstration} \begin{commandshell} latexindent.pl -m -l=mycom-mlb5.yaml mycommand1.tex \end{commandshell} @@ -62,11 +67,14 @@ latexindent.pl -m -l=mycom-mlb5.yaml mycommand1.tex Now let's consider an example when nested code blocks have conflicting poly-switches; we'll use the code in \cref{lst:nested-env}, noting that it contains nested environments. + \index{poly-switches!conflicting switches} \cmhlistingsfromfile{demonstrations/nested-env.tex}{\texttt{nested-env.tex}}{lst:nested-env} Let's use the YAML settings given in \cref{lst:nested-env-mlb1-yaml}, which upon running the command + \index{switches!-l demonstration} + \index{switches!-m demonstration} \begin{commandshell} latexindent.pl -m -l=nested-env-mlb1.yaml nested-env.tex \end{commandshell} @@ -132,6 +140,8 @@ latexindent.pl -m -l=nested-env-mlb1.yaml nested-env.tex We can explore this further using the poly-switches in \cref{lst:nested-env-mlb2}; upon running the command + \index{switches!-l demonstration} + \index{switches!-m demonstration} \begin{commandshell} latexindent.pl -m -l=nested-env-mlb2.yaml nested-env.tex \end{commandshell} diff --git a/Master/texmf-dist/doc/support/latexindent/subsec-noAdditionalIndent-indentRules.tex b/Master/texmf-dist/doc/support/latexindent/subsec-noAdditionalIndent-indentRules.tex index 53fd835392f..4bb5d127e50 100644 --- a/Master/texmf-dist/doc/support/latexindent/subsec-noAdditionalIndent-indentRules.tex +++ b/Master/texmf-dist/doc/support/latexindent/subsec-noAdditionalIndent-indentRules.tex @@ -1,5 +1,10 @@ % arara: pdflatex: {shell: yes, files: [latexindent]} % arara: pdflatex: {shell: yes, files: [latexindent]} +\index{indentation!no additional indent} +\index{indentation!removing indentation per-code block} +\index{indentation!customising indentation per-code block} +\index{indentation!customising per-name} +\index{indentation!no additional indent global} \subsection{noAdditionalIndent and indentRules}\label{sec:noadd-indent-rules} \texttt{latexindent.pl} operates on files by looking for code blocks, as detailed in \vref{subsubsec:code-blocks}; diff --git a/Master/texmf-dist/doc/support/latexindent/subsec-partnering-poly-switches.tex b/Master/texmf-dist/doc/support/latexindent/subsec-partnering-poly-switches.tex index 03337669efb..4c0b7a8f051 100644 --- a/Master/texmf-dist/doc/support/latexindent/subsec-partnering-poly-switches.tex +++ b/Master/texmf-dist/doc/support/latexindent/subsec-partnering-poly-switches.tex @@ -4,6 +4,7 @@ involving the \emph{first} argument of a code block need to be accounted for using both \texttt{BodyStartsOnOwnLine} (or its equivalent, see \vref{tab:poly-switch-mapping}) and \texttt{LCuBStartsOnOwnLine} for mandatory arguments, and \texttt{LSqBStartsOnOwnLine} for optional arguments. + \index{poly-switches!conflicting partnering} Let's begin with the code in \cref{lst:mycommand1} and the YAML settings in \cref{lst:mycom-mlb1}; with reference to \vref{tab:poly-switch-mapping}, the key @@ -12,6 +13,8 @@ \cmhlistingsfromfile{demonstrations/mycommand1.tex}{\texttt{mycommand1.tex}}{lst:mycommand1} Upon running the command + \index{switches!-l demonstration} + \index{switches!-m demonstration} \begin{commandshell} latexindent.pl -m -l=mycom-mlb1.yaml mycommand1.tex \end{commandshell} diff --git a/Master/texmf-dist/doc/support/latexindent/subsubsec-commands-with-arguments.tex b/Master/texmf-dist/doc/support/latexindent/subsubsec-commands-with-arguments.tex index 84bff810a1e..5531e7eace6 100644 --- a/Master/texmf-dist/doc/support/latexindent/subsubsec-commands-with-arguments.tex +++ b/Master/texmf-dist/doc/support/latexindent/subsubsec-commands-with-arguments.tex @@ -23,6 +23,7 @@ \end{minipage} After running the following commands, + \index{switches!-l demonstration} \begin{commandshell} latexindent.pl mycommand.tex -l mycommand-noAdd1.yaml latexindent.pl mycommand.tex -l mycommand-noAdd2.yaml @@ -55,6 +56,7 @@ latexindent.pl mycommand.tex -l mycommand-noAdd2.yaml \end{minipage} After running the following commands, + \index{switches!-l demonstration} \begin{commandshell} latexindent.pl mycommand.tex -l mycommand-noAdd3.yaml latexindent.pl mycommand.tex -l mycommand-noAdd4.yaml @@ -85,6 +87,7 @@ latexindent.pl mycommand.tex -l mycommand-noAdd4.yaml \end{minipage} After running the following commands, + \index{switches!-l demonstration} \begin{commandshell} latexindent.pl mycommand.tex -l mycommand-noAdd5.yaml latexindent.pl mycommand.tex -l mycommand-noAdd6.yaml diff --git a/Master/texmf-dist/doc/support/latexindent/subsubsec-environments-and-their-arguments.tex b/Master/texmf-dist/doc/support/latexindent/subsubsec-environments-and-their-arguments.tex index a37e3eb0edb..b151d2d7676 100644 --- a/Master/texmf-dist/doc/support/latexindent/subsubsec-environments-and-their-arguments.tex +++ b/Master/texmf-dist/doc/support/latexindent/subsubsec-environments-and-their-arguments.tex @@ -18,6 +18,7 @@ \end{minipage} On applying either of the following commands, + \index{switches!-l demonstration} \begin{commandshell} latexindent.pl myenv.tex -l myenv-noAdd1.yaml latexindent.pl myenv.tex -l myenv-noAdd2.yaml @@ -30,6 +31,7 @@ latexindent.pl myenv.tex -l myenv-noAdd2.yaml \cmhlistingsfromfile{demonstrations/myenvironment-simple-noAdd-body1.tex}{\texttt{myenv.tex} output (using either \cref{lst:myenv-noAdd1} or \cref{lst:myenv-noAdd2})}{lst:myenv-output} Upon changing the YAML files to those shown in \cref{lst:myenv-noAdd3,lst:myenv-noAdd4}, and running either + \index{switches!-l demonstration} \begin{commandshell} latexindent.pl myenv.tex -l myenv-noAdd3.yaml latexindent.pl myenv.tex -l myenv-noAdd4.yaml @@ -52,6 +54,7 @@ latexindent.pl myenv.tex -l myenv-noAdd4.yaml \cmhlistingsfromfile{demonstrations/myenvironment-args.tex}{\texttt{myenv-args.tex}}{lst:myenv-args} Upon running + \index{switches!-l demonstration} \begin{commandshell} latexindent.pl -l=myenv-noAdd1.yaml myenv-args.tex \end{commandshell} @@ -74,6 +77,7 @@ latexindent.pl -l=myenv-noAdd1.yaml myenv-args.tex \end{minipage} Upon running + \index{switches!-l demonstration} \begin{commandshell} latexindent.pl myenv.tex -l myenv-noAdd5.yaml latexindent.pl myenv.tex -l myenv-noAdd6.yaml @@ -102,6 +106,7 @@ latexindent.pl myenv.tex -l myenv-noAdd6.yaml \end{cmhtcbraster} On applying either of the following commands, + \index{switches!-l demonstration} \begin{commandshell} latexindent.pl myenv.tex -l myenv-rules1.yaml latexindent.pl myenv.tex -l myenv-rules2.yaml @@ -118,6 +123,7 @@ latexindent.pl myenv.tex -l myenv-rules2.yaml Returning to the example in \cref{lst:myenv-args} that contains optional and mandatory arguments. Upon using \cref{lst:myenv-rules1} as in + \index{switches!-l demonstration} \begin{commandshell} latexindent.pl myenv-args.tex -l=myenv-rules1.yaml \end{commandshell} @@ -137,6 +143,7 @@ latexindent.pl myenv-args.tex -l=myenv-rules1.yaml \end{minipage} After running + \index{switches!-l demonstration} \begin{commandshell} latexindent.pl myenv-args.tex -l myenv-rules3.yaml latexindent.pl myenv-args.tex -l myenv-rules4.yaml @@ -170,6 +177,7 @@ latexindent.pl myenv-args.tex -l myenv-rules4.yaml \texttt{noAdditionalIndentGlobal}, and in particular \emph{for the environments} key (see \cref{lst:noAdditionalIndentGlobal:environments}). Let's say that you change the value of \texttt{environments} to \texttt{1} in \cref{lst:noAdditionalIndentGlobal:environments}, and that you run + \index{switches!-l demonstration} \begin{widepage} \begin{commandshell} @@ -206,6 +214,7 @@ latexindent.pl myenv-args.tex -l myenv-rules1.yaml,env-noAdditionalGlobal.yaml \end{minipage} we may run the commands + \index{switches!-l demonstration} \begin{commandshell} latexindent.pl myenv-args.tex -local opt-args-no-add-glob.yaml latexindent.pl myenv-args.tex -local mand-args-no-add-glob.yaml @@ -231,6 +240,7 @@ latexindent.pl myenv-args.tex -local mand-args-no-add-glob.yaml \texttt{indentRulesGlobal} as detailed in \cref{lst:indentRulesGlobal:environments}; if you change the \texttt{environments} field to anything involving horizontal space, say \lstinline!" "!, and then run the following commands + \index{switches!-l demonstration} \begin{commandshell} latexindent.pl myenv-args.tex -l env-indentRules.yaml @@ -263,6 +273,7 @@ latexindent.pl myenv-args.tex -l myenv-rules1.yaml,env-indentRules.yaml \end{minipage} Upon running the following commands + \index{switches!-l demonstration} \begin{commandshell} latexindent.pl myenv-args.tex -local opt-args-indent-rules-glob.yaml latexindent.pl myenv-args.tex -local mand-args-indent-rules-glob.yaml diff --git a/Master/texmf-dist/doc/support/latexindent/subsubsec-environments-with-items.tex b/Master/texmf-dist/doc/support/latexindent/subsubsec-environments-with-items.tex index 4cc53e654f3..c615be110df 100644 --- a/Master/texmf-dist/doc/support/latexindent/subsubsec-environments-with-items.tex +++ b/Master/texmf-dist/doc/support/latexindent/subsubsec-environments-with-items.tex @@ -17,6 +17,7 @@ \end{cmhtcbraster} Upon running the following commands + \index{switches!-l demonstration} \begin{commandshell} latexindent.pl items1.tex -local item-noAdd1.yaml latexindent.pl items1.tex -local item-rules1.yaml @@ -51,6 +52,7 @@ latexindent.pl items1.tex -local item-rules1.yaml \end{minipage} Upon running the following commands, + \index{switches!-l demonstration} \begin{commandshell} latexindent.pl items1.tex -local items-noAdditionalGlobal.yaml latexindent.pl items1.tex -local items-indentRulesGlobal.yaml diff --git a/Master/texmf-dist/doc/support/latexindent/subsubsec-headings.tex b/Master/texmf-dist/doc/support/latexindent/subsubsec-headings.tex index 088ece973dd..3cbe5996ea9 100644 --- a/Master/texmf-dist/doc/support/latexindent/subsubsec-headings.tex +++ b/Master/texmf-dist/doc/support/latexindent/subsubsec-headings.tex @@ -7,6 +7,7 @@ \cmhlistingsfromfile{demonstrations/headings2.tex}{\texttt{headings2.tex}}{lst:headings2} On using the YAML file in \cref{lst:headings3yaml} by running the command + \index{switches!-l demonstration} \begin{commandshell} latexindent.pl headings2.tex -l headings3.yaml \end{commandshell} @@ -20,6 +21,7 @@ latexindent.pl headings2.tex -l headings3.yaml \end{cmhtcbraster} If we specify \texttt{noAdditionalIndent} as in \cref{lst:headings4yaml} and run the command + \index{switches!-l demonstration} \begin{commandshell} latexindent.pl headings2.tex -l headings4.yaml \end{commandshell} diff --git a/Master/texmf-dist/doc/support/latexindent/subsubsec-ifelsefi.tex b/Master/texmf-dist/doc/support/latexindent/subsubsec-ifelsefi.tex index c7171bc7525..419fc0d53f9 100644 --- a/Master/texmf-dist/doc/support/latexindent/subsubsec-ifelsefi.tex +++ b/Master/texmf-dist/doc/support/latexindent/subsubsec-ifelsefi.tex @@ -27,6 +27,7 @@ \end{minipage} After running the following commands, + \index{switches!-l demonstration} \begin{commandshell} latexindent.pl ifelsefi1.tex -local ifnum-noAdd.yaml latexindent.pl ifelsefi1.tex -l ifnum-indent-rules.yaml @@ -56,6 +57,7 @@ latexindent.pl ifelsefi1.tex -l ifnum-indent-rules.yaml \end{minipage} Upon running the following commands + \index{switches!-l demonstration} \begin{commandshell} latexindent.pl ifelsefi1.tex -local ifelsefi-noAdd-glob.yaml latexindent.pl ifelsefi1.tex -l ifelsefi-indent-rules-global.yaml diff --git a/Master/texmf-dist/doc/support/latexindent/subsubsec-no-add-remaining-code-blocks.tex b/Master/texmf-dist/doc/support/latexindent/subsubsec-no-add-remaining-code-blocks.tex index 7068c5a873b..f72ac43d395 100644 --- a/Master/texmf-dist/doc/support/latexindent/subsubsec-no-add-remaining-code-blocks.tex +++ b/Master/texmf-dist/doc/support/latexindent/subsubsec-no-add-remaining-code-blocks.tex @@ -121,8 +121,11 @@ neither arguments nor items are sought. \subsubsection{Summary} + \index{indentation!summary} Having considered all of the different types of code blocks, the functions of the fields given in \cref{lst:noAdditionalIndentGlobal,lst:indentRulesGlobal} should now make sense. + \index{specialBeginEnd!noAdditionalIndentGlobal} + \index{specialBeginEnd!indentRulesGlobal} \begin{widepage} \begin{minipage}{.47\linewidth} diff --git a/Master/texmf-dist/doc/support/latexindent/subsubsec-special.tex b/Master/texmf-dist/doc/support/latexindent/subsubsec-special.tex index 378c4d1413b..7a974461652 100644 --- a/Master/texmf-dist/doc/support/latexindent/subsubsec-special.tex +++ b/Master/texmf-dist/doc/support/latexindent/subsubsec-special.tex @@ -7,6 +7,8 @@ `scalar' form for these type of code blocks, although the `field' form would work, assuming that \texttt{body} was specified. Examples are shown in \cref{lst:displayMath-noAdd,lst:displayMath-indent-rules}. + \index{specialBeginEnd!noAdditionalIndent} + \index{specialBeginEnd!indentRules example} \begin{minipage}{.49\textwidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/displayMath-noAdd.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{displayMath-noAdd.yaml}}{lst:displayMath-noAdd} @@ -17,6 +19,7 @@ \end{minipage} After running the following commands, + \index{switches!-l demonstration} \begin{commandshell} latexindent.pl special1.tex -local displayMath-noAdd.yaml latexindent.pl special1.tex -l displayMath-indent-rules.yaml @@ -46,6 +49,7 @@ latexindent.pl special1.tex -l displayMath-indent-rules.yaml \end{minipage} Upon running the following commands + \index{switches!-l demonstration} \begin{commandshell} latexindent.pl special1.tex -local special-noAdd-glob.yaml latexindent.pl special1.tex -l special-indent-rules-global.yaml diff --git a/Master/texmf-dist/doc/support/latexindent/title.tex b/Master/texmf-dist/doc/support/latexindent/title.tex index 444213847f9..724ebd1d208 100644 --- a/Master/texmf-dist/doc/support/latexindent/title.tex +++ b/Master/texmf-dist/doc/support/latexindent/title.tex @@ -8,7 +8,7 @@ sharp corners, enhanced, overlay={\node[anchor=north east,outer sep=2pt] at ([xshift=3cm,yshift=4mm]frame.north east) {\includegraphics[width=3cm]{logo}}; }] - \centering\ttfamily\bfseries latexindent.pl\\[1cm] Version 3.8.3 + \centering\ttfamily\bfseries latexindent.pl\\[1cm] Version 3.9 \end{tcolorbox} } \author{Chris Hughes \thanks{and contributors! diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/Document.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/Document.pm index 027597b9ef4..0b3ea9b254a 100644 --- a/Master/texmf-dist/scripts/latexindent/LatexIndent/Document.pm +++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/Document.pm @@ -23,6 +23,7 @@ use open ':std', ':encoding(UTF-8)'; # gain access to subroutines in the following modules use LatexIndent::Switches qw/storeSwitches %switches $is_m_switch_active $is_t_switch_active $is_tt_switch_active $is_r_switch_active $is_rr_switch_active $is_rv_switch_active/; use LatexIndent::LogFile qw/processSwitches $logger/; +use LatexIndent::Logger qw/@logFileLines/; use LatexIndent::Replacement qw/make_replacements/; use LatexIndent::GetYamlSettings qw/yaml_read_settings yaml_modify_line_breaks_settings yaml_get_indentation_settings_for_this_object yaml_poly_switch_get_every_or_custom_value yaml_get_indentation_information yaml_get_object_attribute_for_indentation_settings yaml_alignment_at_ampersand_settings yaml_get_textwrap_removeparagraphline_breaks %masterSettings yaml_get_columns/; use LatexIndent::FileExtension qw/file_extension_check/; @@ -151,12 +152,24 @@ sub output_indented_text{ } else { $logger->info("Not outputting to file; see -w and -o switches for more options."); } - + # put the final line in the logfile $logger->info("${$masterSettings{logFilePreferences}}{endLogFileWith}") if ${$masterSettings{logFilePreferences}}{endLogFileWith}; # github info line $logger->info("*Please direct all communication/issues to:\nhttps://github.com/cmhughes/latexindent.pl") if ${$masterSettings{logFilePreferences}}{showGitHubInfoFooter}; + + # open log file + my $logfileName = $switches{logFileName}||"indent.log"; + my $logfile; + open($logfile,">","${$self}{cruftDirectory}/$logfileName") or die "Can't open $logfileName"; + + foreach my $line (@{LatexIndent::Logger::logFileLines}){ + print $logfile $line,"\n"; + } + + # close log file + close($logfile); # output to screen, unless silent mode print ${$self}{body} unless $switches{silentMode}; diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/FileExtension.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/FileExtension.pm index 716598de777..499ca9f65a4 100644 --- a/Master/texmf-dist/scripts/latexindent/LatexIndent/FileExtension.pm +++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/FileExtension.pm @@ -21,17 +21,14 @@ use PerlIO::encoding; use open ':std', ':encoding(UTF-8)'; use File::Basename; # to get the filename and directory path use Exporter qw/import/; -use Log::Log4perl qw(get_logger :levels); use LatexIndent::GetYamlSettings qw/%masterSettings/; use LatexIndent::Switches qw/%switches/; +use LatexIndent::LogFile qw/$logger/; our @EXPORT_OK = qw/file_extension_check/; sub file_extension_check{ my $self = shift; - # grab the logger object - my $logger = get_logger("Document"); - # grab the filename my $fileName = ${$self}{fileName}; diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/GetYamlSettings.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/GetYamlSettings.pm index e46eccf3809..4be1d3a97bf 100644 --- a/Master/texmf-dist/scripts/latexindent/LatexIndent/GetYamlSettings.pm +++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/GetYamlSettings.pm @@ -21,8 +21,8 @@ use YAML::Tiny; # interpret defaultSettings.yaml and other potent use File::Basename; # to get the filename and directory path use File::HomeDir; use Cwd; -use Log::Log4perl qw(get_logger :levels); use Exporter qw/import/; +use LatexIndent::LogFile qw/$logger/; our @EXPORT_OK = qw/yaml_read_settings yaml_modify_line_breaks_settings yaml_get_indentation_settings_for_this_object yaml_poly_switch_get_every_or_custom_value yaml_get_indentation_information yaml_get_object_attribute_for_indentation_settings yaml_alignment_at_ampersand_settings yaml_get_textwrap_removeparagraphline_breaks %masterSettings yaml_get_columns/; # Read in defaultSettings.YAML file @@ -56,7 +56,6 @@ sub yaml_read_settings{ $defaultSettings = YAML::Tiny->read( "$FindBin::RealBin/defaultSettings.yaml" ) if ( -e "$FindBin::RealBin/defaultSettings.yaml" ); # grab the logger object - my $logger = get_logger("Document"); $logger->info("*YAML settings read: defaultSettings.yaml\nReading defaultSettings.yaml from $FindBin::RealBin/defaultSettings.yaml"); # if latexindent.exe is invoked from TeXLive, then defaultSettings.yaml won't be in @@ -87,7 +86,7 @@ sub yaml_read_settings{ # if indentconfig.yaml doesn't exist, check for the hidden file, .indentconfig.yaml $indentconfig = "$homeDir/.indentconfig.yaml" if(! -e $indentconfig); - + # messages for indentconfig.yaml and/or .indentconfig.yaml if ( -e $indentconfig and !$switches{onlyDefault}) { # read the absolute paths from indentconfig.yaml @@ -126,7 +125,17 @@ sub yaml_read_settings{ $logger->info("Home directory is $homeDir (didn't find either indentconfig.yaml or .indentconfig.yaml)\nTo specify user settings you would put indentconfig.yaml here: $homeDir/indentconfig.yaml\nAlternatively, you can use the hidden file .indentconfig.yaml as: $homeDir/.indentconfig.yaml"); } } - + + # default value of readLocalSettings + # + # latexindent -l myfile.tex + # + # means that we wish to use localSettings.yaml + if(defined($switches{readLocalSettings}) and ($switches{readLocalSettings} eq '')){ + $logger->info('*-l switch used without filename, will search for the following files in turn:'); + $logger->info('localSettings.yaml,latexindent.yaml,.localSettings.yaml,.latexindent.yaml'); + $switches{readLocalSettings} = 'localSettings.yaml,latexindent.yaml,.localSettings.yaml,.latexindent.yaml'; + } # local settings can be called with a + symbol, for example # -l=+myfile.yaml @@ -149,12 +158,14 @@ sub yaml_read_settings{ $switches{readLocalSettings} =~ s/\h*$//g; $switches{readLocalSettings} =~ s/\h*,\h*/,/g; if($switches{readLocalSettings} =~ m/\+/){ - $logger->info("+ found in call for -l switch: will add localSettings.yaml"); + $logger->info("+ found in call for -l switch: will add localSettings.yaml,latexindent.yaml,.localSettings.yaml,.latexindent.yaml"); # + can be either at the beginning or the end, which determines if where the comma should go my $commaAtBeginning = ($switches{readLocalSettings} =~ m/^\h*\+/ ? q() : ","); my $commaAtEnd = ($switches{readLocalSettings} =~ m/^\h*\+/ ? "," : q()); - $switches{readLocalSettings} =~ s/\h*\+\h*/$commaAtBeginning."localSettings.yaml".$commaAtEnd/e; + $switches{readLocalSettings} =~ s/\h*\+\h*/$commaAtBeginning + ."localSettings.yaml,latexindent.yaml,.localSettings.yaml,.latexindent.yaml" + .$commaAtEnd/ex; $logger->info("New value of -l switch: $switches{readLocalSettings}"); } @@ -197,7 +208,15 @@ sub yaml_read_settings{ $logger->info("Adding $_ to YAML read paths"); push(@absPaths,"$_"); } elsif ( !(-e $_) ) { - $logger->warn("*yaml file not found: $_ not found. Proceeding without it."); + if ( ($_ =~ m/localSettings|latexindent/s + and !(-e 'localSettings.yaml') + and !(-e '.localSettings.yaml') + and !(-e 'latexindent.yaml') + and !(-e '.latexindent.yaml')) + or $_ !~ m/localSettings|latexindent/s + ){ + $logger->warn("*yaml file not found: $_ not found. Proceeding without it."); + } } } @@ -328,6 +347,10 @@ sub yaml_read_settings{ push(@yamlSettings,$switches{yaml}); } + foreach (@yamlSettings){ + $logger->info("YAML setting: ".$_); + } + # it is possible to specify, for example, # # -y=indentAfterHeadings:paragraph:indentAfterThisHeading:1;level:1 @@ -348,8 +371,18 @@ sub yaml_read_settings{ # increment the counter $settingsCounter++; + # need to be careful in splitting at ';' + # + # motivation as detailed in https://github.com/cmhughes/latexindent.pl/issues/243 + # + # latexindent.pl -m -y='modifyLineBreaks:oneSentencePerLine:manipulateSentences: 1, + # modifyLineBreaks:oneSentencePerLine:sentencesBeginWith:a-z: 1, + # fineTuning:modifyLineBreaks:betterFullStop: "(?:\.|;|:(?![a-z]))|(?:(?info("quote found in -y switch"); + $logger->info("key: ".$splitAtQuote[0]); + + # definition check + $splitAtQuote[1] = '' if not defined $splitAtQuote[1]; + + # then log the value + $logger->info("value: ".$splitAtQuote[1]); + + # split at : + (@keysValues) = split(/(?trace("*Using stored settings for $storageName") if($is_t_switch_active); @@ -573,9 +638,6 @@ sub yaml_alignment_at_ampersand_settings{ sub yaml_modify_line_breaks_settings{ my $self = shift; - # grab the logging object - my $logger = get_logger("Document"); - # details to the log file $logger->trace("*-m modifylinebreaks switch active") if $is_t_switch_active; $logger->trace("looking for polyswitch, textWrapOptions, removeParagraphLineBreaks, oneSentencePerLine settings for ${$self}{name} ") if $is_t_switch_active; @@ -601,9 +663,6 @@ sub yaml_modify_line_breaks_settings{ sub yaml_get_textwrap_removeparagraphline_breaks{ my $self = shift; - # grab the logging object - my $logger = get_logger("Document"); - # textWrap and removeParagraphLineBreaks settings foreach ("textWrapOptions","removeParagraphLineBreaks"){ @@ -789,9 +848,6 @@ sub yaml_poly_switch_get_every_or_custom_value{ my $toBeAssignedTo = $input{toBeAssignedTo}; my $toBeAssignedToAlias = $input{toBeAssignedToAlias}; - # grab the logging object - my $logger = get_logger("Document"); - # alias if(${$self}{aliases}{$toBeAssignedTo}){ $logger->trace("aliased $toBeAssignedTo using ${$self}{aliases}{$toBeAssignedTo}") if($is_t_switch_active); @@ -871,9 +927,6 @@ sub yaml_get_indentation_information{ # if the YamlName is not optionalArguments, mandatoryArguments, heading (possibly others) then assume we're looking for 'body' my $YamlName = $self->yaml_get_object_attribute_for_indentation_settings; - # grab the logging object - my $logger = get_logger("Document"); - my $indentationInformation; foreach my $indentationAbout ("noAdditionalIndent","indentRules"){ # check that the 'thing' is defined @@ -912,8 +965,8 @@ sub yaml_get_indentation_information{ if(${$masterSettings{$globalInformation}}{$YamlName}=~m/^\h*$/){ $logger->trace("$globalInformation specified for $YamlName (see $globalInformation)") if $is_t_switch_active; return ${$masterSettings{$globalInformation}}{$YamlName}; - } else { - $logger->trace("$globalInformation specified (${$masterSettings{$globalInformation}}{$YamlName}) for $YamlName, but it needs to only contain horizontal space -- I'm ignoring this one") if $is_t_switch_active; + } elsif (${$masterSettings{$globalInformation}}{$YamlName} ne '0') { + $logger->warn("$globalInformation specified (${$masterSettings{$globalInformation}}{$YamlName}) for $YamlName, but it needs to only contain horizontal space -- I'm ignoring this one"); } } } diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/IfElseFi.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/IfElseFi.pm index 056b36d8c3e..e7e363b04c6 100755 --- a/Master/texmf-dist/scripts/latexindent/LatexIndent/IfElseFi.pm +++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/IfElseFi.pm @@ -47,7 +47,7 @@ sub construct_ifelsefi_regexp{ ) # part of the tokens used for latexindent ( (?: - (?!\\if). + (?!\\$ifElseFiNameRegExp). )*? # body, which can't include another \if ) (\R*) # linebreaks after body diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/Item.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/Item.pm index f9fbf8dd4b6..16c6bd8b8da 100644 --- a/Master/texmf-dist/scripts/latexindent/LatexIndent/Item.pm +++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/Item.pm @@ -45,14 +45,14 @@ sub construct_list_of_items{ $itemRegExp = qr/ ( - \\($listOfItems) + \\((?:$listOfItems)(?:\[[^]]*?\])?(?!\S)) \h* (\R*)? ) ( (?: # cluster-only (), don't capture (?! - (?:\\(?:$listOfItems)) # cluster-only (), don't capture + (?:\\(?:(?:$listOfItems)(?:\[[^]]*?\])?(?!\S))) # cluster-only (), don't capture ). # any character, but not \\$item )* ) diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/LogFile.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/LogFile.pm index 205d72031e3..8a35c3c2a27 100644 --- a/Master/texmf-dist/scripts/latexindent/LatexIndent/LogFile.pm +++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/LogFile.pm @@ -19,20 +19,10 @@ use warnings; use FindBin; use File::Basename; # to get the filename and directory path use Exporter qw/import/; -use Log::Log4perl qw(get_logger :levels); -use Log::Log4perl::Appender::Screen; -use Log::Dispatch::File; -use LatexIndent::GetYamlSettings qw/%masterSettings/; use LatexIndent::Switches qw/%switches/; use LatexIndent::Version qw/$versionNumber $versionDate/; our @EXPORT_OK = qw/processSwitches $logger/; -our @logFileNotes; -our $logger = get_logger("Document"); - -# log file methods, using log4perl; references -# pattern layout: http://search.cpan.org/~mschilli/Log-Log4perl-1.32/lib/Log/Log4perl/Layout/PatternLayout.pm -# multiple appenders: https://stackoverflow.com/questions/8620347/perl-log4perl-printing-and-logging-at-the-same-time-in-a-line?rq=1 -# getting started: https://www.perl.com/pub/2002/09/11/log4perl.html +our $logger; sub processSwitches{ # -v switch is just to show the version number @@ -98,7 +88,7 @@ ENDQUOTE # if we've made it this far, the processing of switches and logging begins my $self = shift; - ($switches{trace}||$switches{ttrace}) ? $logger->level($TRACE): $logger->level($INFO); + $logger = LatexIndent::Logger->new(); # cruft directory ${$self}{cruftDirectory} = $switches{cruftDirectory}||(dirname ${$self}{fileName}); @@ -106,58 +96,6 @@ ENDQUOTE my $logfileName = ($switches{cruftDirectory} ? ${$self}{cruftDirectory}."/" : '').($switches{logFileName}||"indent.log"); - # layout of the logfile information, for example - # - # 2017/09/16 11:59:09 INFO: message - # 2017/09/16 12:23:53 INFO: LogFile.pm:156 LatexIndent::LogFile::processSwitches - message - # reference: https://stackoverflow.com/questions/46262844/log4perl-grouping-messages/46309392#46309392 - Log::Log4perl::Layout::PatternLayout::add_global_cspec( - 'A', sub { - if($_[1] =~ /^\*/){ - $_[1]=~s/^\*//; - if($_[1]=~m/\R/s){ - my $indentation = ' '.(' ' x length $_[3]); - $_[1] =~ s/\R/\n$indentation/gs; - } - return "$_[3]: ".$_[1]; - } else { - my $indentation = ' '.(' ' x length $_[3]); - $_[1] =~ s/\R/\n$indentation/gs if($_[1]=~m/\R/s); - return $indentation.$_[1]; - } - }); - - my $layout = Log::Log4perl::Layout::PatternLayout->new("%A%n"); - - # details for the Log4perl logging - my $appender = Log::Log4perl::Appender->new( - "Log::Dispatch::File", - filename => $logfileName, - mode => "write", - utf8 => 1, - ); - - # add the layout - $appender->layout($layout); - - # adjust the logger object - $logger->add_appender($appender); - - # appender object for output to screen - my $appender_screen = q(); - - # output to screen, if appropriate - if($switches{screenlog}){ - $appender_screen = Log::Log4perl::Appender->new( - "Log::Log4perl::Appender::Screen", - stderr => 1, - utf8 => 1, - ); - - $appender_screen->layout($layout); - $logger->add_appender($appender_screen); - } - # details of the script to log file $logger->info("*$FindBin::Script version $versionNumber, $versionDate, a script to indent .tex files"); $logger->info("$FindBin::Script lives here: $FindBin::RealBin/"); @@ -207,7 +145,7 @@ ENDQUOTE # output location of modules if($FindBin::Script eq 'latexindent.pl' or ($FindBin::Script eq 'latexindent.exe' and $switches{trace} )) { - my @listOfModules = ('FindBin', 'YAML::Tiny', 'File::Copy', 'File::Basename', 'Getopt::Long','File::HomeDir','Unicode::GCString','Log::Log4perl'); + my @listOfModules = ('FindBin', 'YAML::Tiny', 'File::Copy', 'File::Basename', 'Getopt::Long','File::HomeDir','Unicode::GCString'); $logger->info("*Perl modules are being loaded from the following directories:"); foreach my $moduleName (@listOfModules) { (my $file = $moduleName) =~ s|::|/|g; @@ -221,33 +159,6 @@ ENDQUOTE # read the YAML settings $self->yaml_read_settings; - # the user may have specified their own settings for the rest of the log file, - # for example: - # - # logFilePreferences: - # PatternLayout: - # default: "%p: %m{indent}%n" - # trace: "%p: %m{indent}%n" - # ttrace: "%d %p: %F{1}:%L %M - %m{indent}%n" - # - # e.g, default mode: - # 2017/09/16 11:59:09 INFO: message - # or trace mode: - # 2017/09/16 11:59:09 INFO: message - # or in trace mode: - # 2017/09/16 12:23:53 INFO: LogFile.pm:156 LatexIndent::LogFile::processSwitches - message - my $pattern = q(); - if($switches{ttrace}){ - $pattern = ${${$masterSettings{logFilePreferences}}{PatternLayout}}{ttrace}; - } elsif($switches{trace}){ - $pattern = ${${$masterSettings{logFilePreferences}}{PatternLayout}}{trace}; - } else { - $pattern = ${${$masterSettings{logFilePreferences}}{PatternLayout}}{default}; - } - $layout = Log::Log4perl::Layout::PatternLayout->new($pattern); - $appender->layout($layout); - - $appender_screen->layout($layout) if $switches{screenlog}; return; } diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/Logger.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/Logger.pm new file mode 100644 index 00000000000..02bcd23dd77 --- /dev/null +++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/Logger.pm @@ -0,0 +1,64 @@ +package LatexIndent::Logger; +# This program is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# See http://www.gnu.org/licenses/. +# +# Chris Hughes, 2017 +# +# For all communication, please visit: https://github.com/cmhughes/latexindent.pl + +use strict; +use warnings; +use Exporter; +use LatexIndent::Switches qw/%switches/; +our @ISA = "LatexIndent::Document"; # class inheritance, Programming Perl, pg 321 +our @EXPORT_OK = qw/@logFileLines/; +our @logFileLines; + +sub info{ + my $self = shift; + my $logfileline = shift; + if ($logfileline =~ m/^\*/s){ + $logfileline =~ s/^\*/INFO: /s; + $logfileline =~ s/^/ /mg; + $logfileline =~ s/^\h+INFO/INFO/s; + } else { + $logfileline =~ s/^/ /mg; + } + push(@logFileLines,$logfileline); + print $logfileline,"\n" if $switches{screenlog}; +} + +sub warn{ + my $self = shift; + my $logfileline = shift; + if ($logfileline =~ m/^\*/s){ + $logfileline =~ s/^\*/WARN: /s + } else { + $logfileline =~ s/^/ /mg; + } + push(@logFileLines,$logfileline); + print $logfileline,"\n" if $switches{screenlog}; +} + +sub trace{ + my $self = shift; + my $logfileline = shift; + if ($logfileline =~ m/^\*/s){ + $logfileline =~ s/^\*/TRACE: /s + } else { + $logfileline =~ s/^/ /mg; + } + push(@logFileLines,$logfileline); + print $logfileline,"\n" if $switches{screenlog}; +} + +1; diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/Version.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/Version.pm index a5dd88c0277..17c5ddd1fcf 100644 --- a/Master/texmf-dist/scripts/latexindent/LatexIndent/Version.pm +++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/Version.pm @@ -19,6 +19,6 @@ use warnings; use Exporter qw/import/; our @EXPORT_OK = qw/$versionNumber $versionDate/; -our $versionNumber = '3.8.3'; -our $versionDate = '2020-11-06'; +our $versionNumber = '3.9'; +our $versionDate = '2021-03-14'; 1 diff --git a/Master/texmf-dist/scripts/latexindent/defaultSettings.yaml b/Master/texmf-dist/scripts/latexindent/defaultSettings.yaml index d4ed8f0c805..f12e0030a95 100755 --- a/Master/texmf-dist/scripts/latexindent/defaultSettings.yaml +++ b/Master/texmf-dist/scripts/latexindent/defaultSettings.yaml @@ -1,4 +1,4 @@ -# defaultSettings.yaml for latexindent.pl, version 3.8.3, 2020-11-06 +# defaultSettings.yaml for latexindent.pl, version 3.9, 2021-03-14 # a script that aims to # beautify .tex, .sty, .cls files # @@ -89,10 +89,6 @@ logFilePreferences: showDecorationFinishCodeBlockTrace: 0 endLogFileWith: '--------------' showGitHubInfoFooter: 1 - PatternLayout: - default: "%A%n" - trace: "%A%n" - ttrace: "%A%n" # verbatim environments specified # in this field will not be changed at all! @@ -357,6 +353,7 @@ commandCodeBlocks: - 'decoration' - '\+\+' - '\-\-' + - '\#\#\d' commandNameSpecial: - amalgamate: 1 @@ -617,7 +614,7 @@ fineTuning: environments: name: '[a-zA-Z@\*0-9_\\]+' ifElseFi: - name: '@?if[a-zA-Z@]*?' + name: '(?!@?if[a-zA-Z@]*?\{)@?if[a-zA-Z@]*?' commands: name: '[+a-zA-Z@\*0-9_\:]+?' keyEqualsValuesBracesBrackets: diff --git a/Master/texmf-dist/scripts/latexindent/latexindent.pl b/Master/texmf-dist/scripts/latexindent/latexindent.pl index f38d6c3fb53..77ae1fb829f 100755 --- a/Master/texmf-dist/scripts/latexindent/latexindent.pl +++ b/Master/texmf-dist/scripts/latexindent/latexindent.pl @@ -1,5 +1,5 @@ #!/usr/bin/env perl -# latexindent.pl, version 3.8.3, 2020-11-06 +# latexindent.pl, version 3.9, 2021-03-14 # # This program is free software: you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by @@ -64,15 +64,6 @@ if($switches{readLocalSettings} and scalar(@ARGV) < 1) { $switches{readLocalSettings} = ''; } -# default value of readLocalSettings -# -# latexindent -l myfile.tex -# -# means that we wish to use localSettings.yaml -if(defined($switches{readLocalSettings}) and ($switches{readLocalSettings} eq '')){ - $switches{readLocalSettings} = 'localSettings.yaml'; -} - # allow STDIN as input, if a filename is not present unshift( @ARGV, '-' ) unless @ARGV; -- cgit v1.2.3