From a54d196b0fc4715e3d2dbcfe62cfccea6aae57fe Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Tue, 14 Aug 2018 22:01:47 +0000 Subject: latexindent (15aug18) git-svn-id: svn://tug.org/texlive/trunk@48402 c570f23f-e606-0410-a88d-b1316a301751 --- .../linked_scripts/latexindent/latexindent.pl | 4 +- Master/bin/win32/latexindent.exe | Bin 11456282 -> 11459600 bytes Master/texmf-dist/doc/support/latexindent/README | 2 +- .../doc/support/latexindent/appendices.tex | 100 ++- .../latexindent/latexindent-module-installer.pl | 2 - .../doc/support/latexindent/latexindent.pdf | Bin 690838 -> 733304 bytes .../doc/support/latexindent/latexindent.tex | 100 +-- .../sec-conclusions-know-limitations.tex | 52 +- .../support/latexindent/sec-default-user-local.tex | 556 +++++++------ .../doc/support/latexindent/sec-demonstration.tex | 21 +- .../doc/support/latexindent/sec-how-to-use.tex | 288 ++++--- .../latexindent/sec-indent-config-and-settings.tex | 139 ++-- .../doc/support/latexindent/sec-introduction.tex | 90 +- .../doc/support/latexindent/sec-the-m-switch.tex | 914 +++++++++++++++------ .../subsec-commands-and-their-options.tex | 180 ++-- .../subsec-conflicting-poly-switches.tex | 136 +-- .../subsec-noAdditionalIndent-indentRules.tex | 25 +- .../subsec-partnering-poly-switches.tex | 26 +- .../subsubsec-commands-with-arguments.tex | 35 +- .../subsubsec-environments-and-their-arguments.tex | 129 +-- .../subsubsec-environments-with-items.tex | 39 +- .../doc/support/latexindent/subsubsec-headings.tex | 48 +- .../doc/support/latexindent/subsubsec-ifelsefi.tex | 42 +- .../subsubsec-no-add-remaining-code-blocks.tex | 91 +- .../doc/support/latexindent/subsubsec-special.tex | 21 +- .../texmf-dist/doc/support/latexindent/title.tex | 2 +- .../LatexIndent/AlignmentAtAmpersand.pm | 2 +- .../scripts/latexindent/LatexIndent/Arguments.pm | 14 + .../scripts/latexindent/LatexIndent/BlankLines.pm | 20 +- .../scripts/latexindent/LatexIndent/Document.pm | 36 +- .../scripts/latexindent/LatexIndent/Else.pm | 2 +- .../scripts/latexindent/LatexIndent/Environment.pm | 4 +- .../latexindent/LatexIndent/FileContents.pm | 34 +- .../latexindent/LatexIndent/GetYamlSettings.pm | 233 +++++- .../scripts/latexindent/LatexIndent/Heading.pm | 2 +- .../latexindent/LatexIndent/HiddenChildren.pm | 17 +- .../scripts/latexindent/LatexIndent/Indent.pm | 20 +- .../scripts/latexindent/LatexIndent/LogFile.pm | 6 +- .../latexindent/LatexIndent/MandatoryArgument.pm | 2 +- .../latexindent/LatexIndent/ModifyLineBreaks.pm | 78 +- .../latexindent/LatexIndent/OptionalArgument.pm | 2 +- .../scripts/latexindent/LatexIndent/Preamble.pm | 18 +- .../latexindent/LatexIndent/RoundBrackets.pm | 2 +- .../scripts/latexindent/LatexIndent/Special.pm | 8 +- .../latexindent/LatexIndent/TrailingComments.pm | 2 +- .../scripts/latexindent/LatexIndent/Verbatim.pm | 53 +- .../scripts/latexindent/LatexIndent/Version.pm | 4 +- .../scripts/latexindent/defaultSettings.yaml | 27 +- .../texmf-dist/scripts/latexindent/latexindent.pl | 4 +- 49 files changed, 2280 insertions(+), 1352 deletions(-) diff --git a/Build/source/texk/texlive/linked_scripts/latexindent/latexindent.pl b/Build/source/texk/texlive/linked_scripts/latexindent/latexindent.pl index c9835ccbe37..0945273d857 100755 --- a/Build/source/texk/texlive/linked_scripts/latexindent/latexindent.pl +++ b/Build/source/texk/texlive/linked_scripts/latexindent/latexindent.pl @@ -1,5 +1,5 @@ #!/usr/bin/env perl -# latexindent.pl, version 3.4.3, 2018-06-08 +# latexindent.pl, version 3.5, 2018-08-13 # # 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 @@ -73,6 +73,6 @@ if(defined($switches{readLocalSettings}) and ($switches{readLocalSettings} eq '' # allow STDIN as input, if a filename is not present unshift( @ARGV, '-' ) unless @ARGV; -my $document = bless ({name=>"masterDocument",fileName=>$ARGV[0],switches=>\%switches},"LatexIndent::Document"); +my $document = bless ({name=>"masterDocument",modifyLineBreaksYamlName=>"masterDocument",fileName=>$ARGV[0],switches=>\%switches},"LatexIndent::Document"); $document->latexindent; exit(0); diff --git a/Master/bin/win32/latexindent.exe b/Master/bin/win32/latexindent.exe index f35c0e80f37..f72957ab12e 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 0ffb2810068..0e4600ed256 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.4.3, 2018-06-08 + latexindent.pl, version 3.5, 2018-08-13 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 3a54a950389..bc04c6c1a0b 100644 --- a/Master/texmf-dist/doc/support/latexindent/appendices.tex +++ b/Master/texmf-dist/doc/support/latexindent/appendices.tex @@ -1,9 +1,11 @@ % arara: pdflatex: {shell: yes, files: [latexindent]} \appendix \section{Required Perl modules}\label{sec:requiredmodules} - If you intend to use \texttt{latexindent.pl} and \emph{not} one of the supplied standalone executable files, then you will need a few standard Perl modules -- if you can run the - minimum code in \cref{lst:helloworld} (\texttt{perl helloworld.pl}) then you will be able to run \texttt{latexindent.pl}, otherwise you may - need to install the missing modules -- see \cref{sec:module-installer,sec:manual-module-instal}. + If you intend to use \texttt{latexindent.pl} and \emph{not} one of the + supplied standalone executable files, then you will need a few standard Perl modules -- + if you can run the minimum code in \cref{lst:helloworld} (\texttt{perl helloworld.pl}) then you will be able to run + \texttt{latexindent.pl}, otherwise you may need to install the missing modules -- see + \cref{sec:module-installer,sec:manual-module-instal}. \begin{cmhlistings}[style=tcblatex,language=Perl]{\texttt{helloworld.pl}}{lst:helloworld} #!/usr/bin/perl @@ -31,8 +33,8 @@ exit; \end{cmhlistings} \subsection{Module installer script}\label{sec:module-installer} - \announce{2018-01-13}{perl module helper script} \texttt{latexindent.pl} ships with a helper script that will install any missing \texttt{perl} modules - on your system; if you run + \announce{2018-01-13}{perl module helper script} \texttt{latexindent.pl} ships with a helper script that will + install any missing \texttt{perl} modules on your system; if you run \begin{commandshell} perl latexindent-module-installer.pl \end{commandshell} @@ -40,18 +42,20 @@ perl latexindent-module-installer.pl \begin{dosprompt} perl latexindent-module-installer.pl \end{dosprompt} - then, once you have answered \texttt{Y}, the appropriate modules will be installed onto your distribution. + then, once you have answered \texttt{Y}, the appropriate modules will be + installed onto your distribution. \subsection{Manually installed modules}\label{sec:manual-module-instal} - Manually installing the modules given in \cref{lst:helloworld} will vary depending on your - operating system and \texttt{Perl} distribution. For example, Ubuntu users + Manually installing the modules given in \cref{lst:helloworld} will vary depending on + your operating system and \texttt{Perl} distribution. For example, Ubuntu users might visit the software center, or else run \begin{commandshell} sudo perl -MCPAN -e 'install "File::HomeDir"' \end{commandshell} - Linux users may be interested in exploring Perlbrew \cite{perlbrew}; possible installation and setup - options follow for Ubuntu (other distributions will need slightly different commands). + Linux users may be interested in exploring Perlbrew \cite{perlbrew}; possible + installation and setup options follow for Ubuntu (other distributions will need slightly + different commands). \begin{commandshell} sudo apt-get install perlbrew perlbrew install perl-5.22.1 @@ -65,29 +69,31 @@ cpanm Log::Log4perl cpanm Log::Dispatch \end{commandshell} - Strawberry Perl users on Windows might use - \texttt{CPAN client}. All of the modules are readily available on CPAN \cite{cpan}. + Strawberry Perl users on Windows might use \texttt{CPAN client}. All of the modules are + readily available on CPAN \cite{cpan}. \texttt{indent.log} will contain details of the location - of the Perl modules on your system. \texttt{latexindent.exe} is a standalone - executable for Windows (and therefore does not require a Perl distribution) and caches copies of the Perl modules onto your system; if you - wish to see where they are cached, use the \texttt{trace} option, e.g + of the Perl modules on your system. \texttt{latexindent.exe} is a standalone executable + for Windows (and therefore does not require a Perl distribution) and caches copies of the + Perl modules onto your system; if you wish to see where they are cached, use the + \texttt{trace} option, e.g \begin{dosprompt} latexindent.exe -t myfile.tex \end{dosprompt} \section{Updating the path variable}\label{sec:updating-path} - \texttt{latexindent.pl} has a few scripts (available at \cite{latexindent-home}) that can update the \texttt{path} variables. - Thank you to \cite{jasjuang} for this feature. If you're - on a Linux or Mac machine, then you'll want \texttt{CMakeLists.txt} from \cite{latexindent-home}. + \texttt{latexindent.pl} has a few scripts (available at \cite{latexindent-home}) that can + update the \texttt{path} variables. Thank you to \cite{jasjuang} for this + feature. If you're on a Linux or Mac machine, then you'll want \texttt{CMakeLists.txt} + from \cite{latexindent-home}. \subsection{Add to path for Linux} To add \texttt{latexindent.pl} to the path for Linux, follow these steps: \begin{enumerate} - \item download \texttt{latexindent.pl} and its associated modules, \texttt{defaultSettings.yaml}, - to your chosen directory from \cite{latexindent-home} ; - \item within your directory, create a directory called \texttt{path-helper-files} and - download \texttt{CMakeLists.txt} and \lstinline!cmake_uninstall.cmake.in! - from \cite{latexindent-home}/path-helper-files to this directory; + \item download \texttt{latexindent.pl} and its associated modules, \texttt{defaultSettings.yaml}, to + your chosen directory from \cite{latexindent-home} ; + \item within your directory, create a directory called \texttt{path-helper-files} and download + \texttt{CMakeLists.txt} and \lstinline!cmake_uninstall.cmake.in! from + \cite{latexindent-home}/path-helper-files to this directory; \item run \begin{commandshell} ls /usr/local/bin @@ -105,7 +111,8 @@ sudo make install \begin{commandshell} ls /usr/local/bin \end{commandshell} - again to check that \texttt{latexindent.pl}, its modules and \texttt{defaultSettings.yaml} have been added. + again to check that \texttt{latexindent.pl}, its modules and \texttt{defaultSettings.yaml} have + been added. \end{enumerate} To \emph{remove} the files, run \begin{commandshell} @@ -114,9 +121,10 @@ sudo make uninstall \subsection{Add to path for Windows} To add \texttt{latexindent.exe} to the path for Windows, follow these steps: \begin{enumerate} - \item download \texttt{latexindent.exe}, \texttt{defaultSettings.yaml}, \texttt{add-to-path.bat} - from \cite{latexindent-home} to your chosen directory; - \item open a command prompt and run the following command to see what is \emph{currently} in your \lstinline!%path%! variable; + \item download \texttt{latexindent.exe}, \texttt{defaultSettings.yaml}, \texttt{add-to-path.bat} from + \cite{latexindent-home} to your chosen directory; + \item open a command prompt and run the following command to see what is \emph{currently} + in your \lstinline!%path%! variable; \begin{dosprompt} echo %path% \end{dosprompt} @@ -128,12 +136,14 @@ echo %path% \end{dosprompt} to check that the appropriate directory has been added to your \lstinline!%path%!. \end{enumerate} - To \emph{remove} the directory from your \lstinline!%path%!, run \texttt{remove-from-path.bat} as administrator. + To \emph{remove} the directory from your \lstinline!%path%!, run + \texttt{remove-from-path.bat} as administrator. \section{logFilePreferences}\label{app:logfile-demo} \Vref{lst:logFilePreferences} describes the options for customising the information given - to the log file, and we provide a few demonstrations here. Let's say that we start with the code - given in \cref{lst:simple}, and the settings specified in \cref{lst:logfile-prefs1-yaml}. + to the log file, and we provide a few demonstrations here. Let's say that we start with + the code given in \cref{lst:simple}, and the settings specified in + \cref{lst:logfile-prefs1-yaml}. \begin{minipage}{.35\linewidth} \cmhlistingsfromfile{demonstrations/simple.tex}{\texttt{simple.tex}}{lst:simple} @@ -147,7 +157,8 @@ echo %path% \begin{commandshell} latexindent.pl -t -l=logfile-prefs1.yaml simple.tex \end{commandshell} - then on inspection of \texttt{indent.log} we will find the snippet given in \cref{lst:indentlog}. + then on inspection of \texttt{indent.log} we will find the snippet given in + \cref{lst:indentlog}. \begin{cmhlistings}[style=tcblatex,morekeywords={TRACE}]{\texttt{indent.log}}{lst:indentlog} +++++ TRACE: environment found: myenv @@ -164,11 +175,12 @@ TRACE: Searching myenv for optional and mandatory arguments ... no arguments found ----- \end{cmhlistings} - Notice that the information given about \texttt{myenv} is `framed' using \texttt{+++++} and \lstinline!-----! respectively. + Notice that the information given about \texttt{myenv} is `framed' using + \texttt{+++++} and \lstinline!-----! respectively. \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, + 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, \begin{commandshell} latexindent.pl -o myfile.tex outputfile.tex \end{commandshell} @@ -181,14 +193,15 @@ latexindent.pl myfile.tex -o=outputfile.tex latexindent.pl myfile.tex -outputfile=outputfile.tex latexindent.pl myfile.tex -outputfile outputfile.tex \end{commandshell} - noting that the \emph{output} file is given \emph{next to} the \texttt{-o} switch. + noting that the \emph{output} file is given \emph{next to} the + \texttt{-o} switch. The fields given in \cref{lst:obsoleteYaml} are \emph{obsolete} from Version 3.0 - onwards. - \cmhlistingsfromfile{demonstrations/obsolete.yaml}[yaml-obsolete]{Obsolete YAML fields from Version 3.0}{lst:obsoleteYaml} + onwards. \cmhlistingsfromfile{demonstrations/obsolete.yaml}[yaml-obsolete]{Obsolete YAML fields from Version 3.0}{lst:obsoleteYaml} - There is a slight difference when specifying indentation after headings; specifically, - we now write \texttt{indentAfterThisHeading} instead of \texttt{indent}. See \cref{lst:indentAfterThisHeadingOld,lst:indentAfterThisHeadingNew} + There is a slight difference when specifying indentation after headings; specifically, we + now write \texttt{indentAfterThisHeading} instead of \texttt{indent}. See + \cref{lst:indentAfterThisHeadingOld,lst:indentAfterThisHeadingNew} \begin{minipage}{.45\textwidth} \cmhlistingsfromfile{demonstrations/indentAfterThisHeadingOld.yaml}[yaml-TCB]{\texttt{indentAfterThisHeading} in Version 2.2}{lst:indentAfterThisHeadingOld} @@ -198,9 +211,10 @@ latexindent.pl myfile.tex -outputfile outputfile.tex \cmhlistingsfromfile{demonstrations/indentAfterThisHeadingNew.yaml}[yaml-TCB]{\texttt{indentAfterThisHeading} in Version 3.0}{lst:indentAfterThisHeadingNew} \end{minipage}% - To specify \texttt{noAdditionalIndent} for display-math environments in Version 2.2, you 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}. + To specify \texttt{noAdditionalIndent} for display-math environments in Version 2.2, you 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}. \begin{minipage}{.45\textwidth} \cmhlistingsfromfile{demonstrations/noAddtionalIndentOld.yaml}[yaml-TCB]{\texttt{noAdditionalIndent} in Version 2.2}{lst:noAdditionalIndentOld} @@ -212,7 +226,7 @@ latexindent.pl myfile.tex -outputfile outputfile.tex \cmhlistingsfromfile{demonstrations/noAddtionalIndentNew1.yaml}[yaml-TCB]{\texttt{noAdditionalIndent} for \texttt{displayMath} in Version 3.0}{lst:indentAfterThisHeadingNew2} \end{minipage}% - \mbox{}\hfill \begin{minipage}{.25\textwidth} + \mbox{}\hfill \begin{minipage}{.25\textwidth} \hrule \hfill\itshape End\\\mbox{}\hfill\mbox{}\rlap{\hfill\includegraphics{logo}} 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 660b81d2399..e45fdcbe73d 100755 --- a/Master/texmf-dist/doc/support/latexindent/latexindent-module-installer.pl +++ b/Master/texmf-dist/doc/support/latexindent/latexindent-module-installer.pl @@ -1,6 +1,4 @@ #!/usr/bin/env perl -# latexindent.pl, version 3.3, 2017-08-21 -# # 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 diff --git a/Master/texmf-dist/doc/support/latexindent/latexindent.pdf b/Master/texmf-dist/doc/support/latexindent/latexindent.pdf index be0c9f8d6fa..d93a76ea06b 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 eb089d0418f..71ebc1d3ce4 100644 --- a/Master/texmf-dist/doc/support/latexindent/latexindent.tex +++ b/Master/texmf-dist/doc/support/latexindent/latexindent.tex @@ -406,55 +406,55 @@ \lstdefinestyle{textWrapOptions}{ style=yaml-LST, - firstnumber=397,linerange={397-398}, + firstnumber=421,linerange={421-422}, numbers=left, } \lstdefinestyle{textWrapOptionsAll}{ style=yaml-LST, - firstnumber=397,linerange={397-399}, + firstnumber=421,linerange={421-437}, numbers=left, } \lstdefinestyle{removeParagraphLineBreaks}{ style=yaml-LST, - firstnumber=422,linerange={422-434}, + firstnumber=438,linerange={438-452}, numbers=left, } \lstdefinestyle{paragraphsStopAt}{ style=yaml-LST, - firstnumber=435,linerange={435-443}, + firstnumber=453,linerange={453-462}, numbers=left, } \lstdefinestyle{oneSentencePerLine}{ style=yaml-LST, - firstnumber=400,linerange={400-421}, + firstnumber=397,linerange={397-420}, numbers=left, } \lstdefinestyle{sentencesFollow}{ style=yaml-LST, - firstnumber=403,linerange={403-411}, + firstnumber=402,linerange={402-410}, numbers=left, } \lstdefinestyle{sentencesBeginWith}{ style=yaml-LST, - firstnumber=412,linerange={412-415}, + firstnumber=411,linerange={411-414}, numbers=left, } \lstdefinestyle{sentencesEndWith}{ style=yaml-LST, - firstnumber=416,linerange={416-421}, + firstnumber=415,linerange={415-420}, numbers=left, } \lstdefinestyle{modifylinebreaksEnv}{ style=yaml-LST, - firstnumber=444,linerange={444-453}, + firstnumber=463,linerange={463-472}, numbers=left, } @@ -700,85 +700,3 @@ \input{references} \input{appendices} \end{document} - -version history: - -1.0: first release -https://www.ctan.org/ctan-ann/id/mailman.278.1369470527.5851.ctan-ann@dante.de - -1.1R -Changed Bin to RealBin so that I hope the script can get bun­dled into TeXLive 2013. Some other up­dates, too, detailed in the documentation. -https://www.ctan.org/ctan-ann/id/mailman.3048.1384345731.2385.ctan-ann@dante.de - -1.11R -This release updates the script to use $FindBin::RealBin which should help in the TeXLive implementation. - -Version 2.0R -Ver­sion 2.0R of la­texin­dent.pl adds a num­ber of new fea­tures, in­clud­ing: - in­den­ta­tion af­ter \item com­mands - align­ment of de­lim­itered en­vi­ron­ments in com­mands, such as \ma­trix - in­den­ta­tion of \if...\else...\fi state­ments - max­i­mum num­ber of back­ups can cy­cle through back­ups - bet­ter sup­port for .cls and .sty files - and a few other bug fixes -https://www.ctan.org/ctan-ann/id/mailman.3090.1417864461.4370.ctan-ann@dante.de - -Version 2.1R -in­dent­con­fig.yaml can now be a 'hid­den' file, .in­dent­con­fig.yaml The Win­dows ex­e­cutable file, la­texin­dent.exe, should now work much bet­ter with Win­dows TeXLive. -https://www.ctan.org/ctan-ann/id/mailman.343.1429509943.4405.ctan-ann@dante.de - -Version 2.2 -v2.2 addresses a reg­exp issue, and adds a few enhancements; full details are here: https://github.com/cmhughes/latexindent.pl/pull/49 -https://www.ctan.org/ctan-ann/id/mailman.198.1477655196.4574.ctan-ann@ctan.org - -Version 3.0 -latexindent.pl version 3.0: this represents a complete re-build of the script; full details are given here: -https://github.com/cmhughes/la­texin­dent.pl/pull/56 - -V3.0.1 -pro­vides sup­port for the align­ment at am­per­sands rou­tine for code that con­tains uni­code char­ac­ters; see -https://github.com/cmhughes/la­texin­dent.pl/pull/61 - -V3.0.2 -A mi­nor re­lease to fix a small bug re­lated to in­den­tPream­ble; de­tails given here: -https://github.com/cmhughes/la­texin­dent.pl/pull/62 - -Ver­sion 3.1 of la­texin­dent.pl, -in­clud­ing op­tions for text wrap­ping and para­graph line break re­moval. Full de­tails here: -https://github.com/cmhughes/la­texin­dent.pl/pull/64 - -Ver­sion 3.2 -im­ple­ments a new fea­ture called 'mul­ti­Colum­nGroup­ing' which gives a new op­tion for the align­ment-at-am­per­sands rou­tine. -More de­tails are given at -https://github.com/cmhughes/la­texin­dent.pl/pull/67 - -Version 3.2.1 -Upgrades to the -o and -l switches -https://github.com/cmhughes/latexindent.pl/pull/71 - -Version 3.2.2 -Users can specify removeTrailingWhitespace as a scalar, for example, removeTrailingWhitespace: 0 -https://github.com/cmhughes/latexindent.pl/pull/72 - -Version 3.3 -- maximum indentation: https://github.com/cmhughes/latexindent.pl/issues/50 -- blank line poly-switch: https://github.com/cmhughes/latexindent.pl/issues/57 -- ifnextchar issue: https://github.com/cmhughes/latexindent.pl/issues/73 -- the -y/yaml switch: https://github.com/cmhughes/latexindent.pl/issues/79 -- absolute paths for the -l switch: https://github.com/cmhughes/latexindent.pl/issues/82 -bug fixes: -- an ifelsefi bug: https://github.com/cmhughes/latexindent.pl/issues/76 -- empty environment bug: https://github.com/cmhughes/latexindent.pl/issues/78 -- a command/special bug: https://github.com/cmhughes/latexindent.pl/issues/80 -https://github.com/cmhughes/latexindent.pl/releases/tag/V3.3 - -Version 3.4 -- enhancements to alignment at ampersand routine: https://github.com/cmhughes/latexindent.pl/issues/74 -- log4Perl module: https://github.com/cmhughes/latexindent.pl/issues/75 -- one sentence per line: https://github.com/cmhughes/latexindent.pl/issues/81 -- STDIN allowed: https://github.com/cmhughes/latexindent.pl/issues/88 -- textwrap bug fix: https://github.com/cmhughes/latexindent.pl/issues/90 -- polyswitch bug fix: https://github.com/cmhughes/latexindent.pl/issues/94 - -Version 3.4.1 -- the reading of defaultSettings.yaml needed addressing -- https://github.com/cmhughes/latexindent.pl/releases/tag/V3.4.1 - -Version 3.4.2 -- enhancements to specialBeginEnd: https://github.com/cmhughes/latexindent.pl/issues/100 -- enhancements to commandCodeBlocks: https://github.com/cmhughes/latexindent.pl/issues/105 -- better support for forrest syntax: https://github.com/cmhughes/latexindent.pl/issues/107 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 db7cfc7059f..0128adb8a38 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 @@ -1,37 +1,37 @@ % arara: pdflatex: {shell: yes, files: [latexindent]} \section{Conclusions and known limitations}\label{sec:knownlimitations} - There are a number of known limitations of the script, and almost certainly quite a - few that are \emph{unknown}! + 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 on + \cpageref{yaml:lookforaligndelims}; for example, consider the file given in \cref{lst:matrix2}. \cmhlistingsfromfile{demonstrations/matrix2.tex}{\texttt{matrix2.tex}}{lst:matrix2} - The default output is given in \cref{lst:matrix2-default}, and it is clear that the alignment routine - has not worked as hoped, but it is \emph{expected}. - \cmhlistingsfromfile{demonstrations/matrix2-default.tex}{\texttt{matrix2.tex} default output}{lst:matrix2-default} + The default output is given in \cref{lst:matrix2-default}, and it is clear that the alignment + routine has not worked as hoped, but it is \emph{expected}. \cmhlistingsfromfile{demonstrations/matrix2-default.tex}{\texttt{matrix2.tex} default output}{lst:matrix2-default} - The reason for the problem is that when \texttt{latexindent.pl} stores its code blocks (see \vref{tab:code-blocks}) - it uses replacement tokens. The alignment routine is using the \emph{length of the replacement token} in its measuring -- I hope - to be able to address this in the future. + The reason for the problem is that when \texttt{latexindent.pl} stores its code blocks + (see \vref{tab:code-blocks}) it uses replacement tokens. The alignment routine is using + the \emph{length of the replacement token} in its measuring -- I hope to be able to address this in the + future. - There are other limitations to do with the multicolumn alignment routine (see \vref{lst:tabular2-mod2}); in particular, - when working with codeblocks in which multicolumn commands overlap, the algorithm can fail. + There are other limitations to do with the multicolumn alignment routine (see + \vref{lst:tabular2-mod2}); in particular, when working with codeblocks in which multicolumn + commands overlap, the algorithm can fail. Another limitation is to do with efficiency, particularly when the \texttt{-m} switch is active, as this adds many checks and processes. The current implementation - relies upon finding and storing \emph{every} code block (see the discussion on \cpageref{page:phases}); - it is hoped that, in a future version, only \emph{nested} code blocks will need - to be stored in the `packing' phase, and that this will improve the efficiency of the script. - - You can run \texttt{latexindent} on \texttt{.sty}, \texttt{.cls} and any file types - that you specify in \lstinline[breaklines=true]!fileExtensionPreference! (see \vref{lst:fileExtensionPreference}); - if you find a case in which the script struggles, please feel free - to report it at \cite{latexindent-home}, and - in the meantime, consider using a \texttt{noIndentBlock} (see \cpageref{lst:noIndentBlockdemo}). - - I hope that this script is useful to some; if you find an example where the - script does not behave as you think it should, the best way to contact me is to - report an issue on \cite{latexindent-home}; otherwise, feel free to find me on - the \url{http://tex.stackexchange.com/users/6621/cmhughes}. + relies upon finding and storing \emph{every} code block (see the discussion on + \cpageref{page:phases}); it is hoped that, in a future version, only + \emph{nested} code blocks will need to be stored in the `packing' phase, and + that this will improve the efficiency of the script. + + You can run \texttt{latexindent} on \texttt{.sty}, \texttt{.cls} and + any file types that you specify in \lstinline[breaklines=true]!fileExtensionPreference! (see \vref{lst:fileExtensionPreference}); + if you find a case in which the script struggles, please feel free to report it at + \cite{latexindent-home}, and in the meantime, consider using a \texttt{noIndentBlock} (see \cpageref{lst:noIndentBlockdemo}). + + I hope that this script is useful to some; if you find an example where the script does + not behave as you think it should, the best way to contact me is to report an issue on + \cite{latexindent-home}; otherwise, feel free to find me on the \url{http://tex.stackexchange.com/users/6621/cmhughes}. 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 0f6045189ac..6f3c355107f 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 @@ -1,23 +1,20 @@ % arara: pdflatex: {shell: yes, files: [latexindent]} \section{defaultSettings.yaml}\label{sec:defuseloc} - \texttt{latexindent.pl} loads its settings from \texttt{defaultSettings.yaml}. The idea is to separate the behaviour of the script - from the internal working -- this is very similar to the way that we separate content - from form when writing our documents in \LaTeX. - - If you look in \texttt{defaultSettings.yaml} you'll find the switches - that govern the behaviour of \texttt{latexindent.pl}. If you're not sure where - \texttt{defaultSettings.yaml} resides on your computer, don't worry as \texttt{indent.log} - will tell you where to find it. - \texttt{defaultSettings.yaml} is commented, - but here is a description of what each switch is designed to do. The default - value is given in each case; whenever you see \emph{integer} in \emph{this} - section, assume that it must be greater than or equal to \texttt{0} unless - otherwise stated. + \texttt{latexindent.pl} loads its settings from \texttt{defaultSettings.yaml}. The idea is to + separate the behaviour of the script from the internal working -- this is very similar to + the way that we separate content from form when writing our documents in \LaTeX. + + If you look in \texttt{defaultSettings.yaml} you'll find the switches that govern the behaviour + of \texttt{latexindent.pl}. If you're not sure where \texttt{defaultSettings.yaml} resides on + your computer, don't worry as \texttt{indent.log} will tell you where to find it. + \texttt{defaultSettings.yaml} is commented, but here is a description of what each switch is + designed to do. The default value is given in each case; whenever you see + \emph{integer} in \emph{this} section, assume that it must be + greater than or equal to \texttt{0} unless otherwise stated. \yamltitle{fileExtensionPreference}*{fields} \texttt{latexindent.pl} can be called to - act on a file without - specifying the file extension. For example we can call + act on a file without specifying the file extension. For example we can call \begin{commandshell} latexindent.pl myfile \end{commandshell} @@ -26,48 +23,49 @@ latexindent.pl myfile \end{wrapfigure} in which case the script will look for \texttt{myfile} with the extensions - specified in \texttt{fileExtensionPreference} in their numeric order. If - no match is found, the script will exit. As with all of the fields, you should - change and/or add to this as necessary. - - Calling \texttt{latexindent.pl myfile} with the (default) settings specified in \cref{lst:fileExtensionPreference} - means that the script will first look for \texttt{myfile.tex}, then \texttt{myfile.sty}, \texttt{myfile.cls}, - and finally \texttt{myfile.bib} in order\footnote{Throughout this manual, listings shown with line numbers represent code + specified in \texttt{fileExtensionPreference} in their numeric order. If no match is found, the + script will exit. As with all of the fields, you should change and/or add to this as + necessary. + + Calling \texttt{latexindent.pl myfile} with the (default) settings specified in + \cref{lst:fileExtensionPreference} means that the script will first look for + \texttt{myfile.tex}, then \texttt{myfile.sty}, \texttt{myfile.cls}, and + finally \texttt{myfile.bib} in order\footnote{Throughout this manual, listings shown with line numbers represent code taken directly from \texttt{defaultSettings.yaml}.}. \yamltitle{backupExtension}*{extension name} If you call \texttt{latexindent.pl} with the \texttt{-w} switch (to overwrite - \texttt{myfile.tex}) then it will create a backup file before doing - any indentation; the default extension is \texttt{.bak}, so, for example, \texttt{myfile.bak0} - would be created when calling \texttt{latexindent.pl myfile.tex} for the first time. + \texttt{myfile.tex}) then it will create a backup file before doing any indentation; + the default extension is \texttt{.bak}, so, for example, + \texttt{myfile.bak0} would be created when calling \texttt{latexindent.pl myfile.tex} for the + first time. - By default, every time you subsequently call \texttt{latexindent.pl} with - the \texttt{-w} to act upon \texttt{myfile.tex}, it will create successive back up files: \texttt{myfile.bak1}, \texttt{myfile.bak2}, - etc. + By default, every time you subsequently call \texttt{latexindent.pl} with the + \texttt{-w} to act upon \texttt{myfile.tex}, it will create successive + back up files: \texttt{myfile.bak1}, \texttt{myfile.bak2}, etc. \yamltitle{onlyOneBackUp}*{integer} \label{page:onlyonebackup} 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}. + 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}. \yamltitle{maxNumberOfBackUps}*{integer} - Some users may only want a finite number of backup files, - say at most $3$, in which case, they can change this switch. - The smallest value of \texttt{maxNumberOfBackUps} is $0$ which will \emph{not} - prevent backup files being made; in this case, the behaviour will be dictated - entirely by \texttt{onlyOneBackUp}. The default value of \texttt{maxNumberOfBackUps} - is \texttt{0}. + Some users may only want a finite number of backup files, say at most + $3$, in which case, they can change this switch. The smallest value of + \texttt{maxNumberOfBackUps} is $0$ which will \emph{not} + prevent backup files being made; in this case, the behaviour will be dictated entirely by + \texttt{onlyOneBackUp}. The default value of \texttt{maxNumberOfBackUps} is + \texttt{0}. \yamltitle{cycleThroughBackUps}*{integer} - 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} procedure given below - would be obeyed. + 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} procedure given below would be obeyed. \begin{commandshell} copy myfile.bak1 to myfile.bak0 @@ -79,35 +77,39 @@ copy myfile.bak4 to myfile.bak3 \yamltitle{logFilePreferences}*{fields} \texttt{latexindent.pl} writes information to \texttt{indent.log}, some - of which can be customized by changing \texttt{logFilePreferences}; see \cref{lst:logFilePreferences}. - If you load your own user settings (see \vref{sec:indentconfig}) then \texttt{latexindent.pl} will - detail them in \texttt{indent.log}; you can choose not to have the details logged by switching - \texttt{showEveryYamlRead} to \texttt{0}. Once all of your settings have - been loaded, you can see the amalgamated settings in the log file by switching \texttt{showAmalgamatedSettings} - to \texttt{1}, if you wish. + of which can be customized by changing \texttt{logFilePreferences}; see + \cref{lst:logFilePreferences}. If you load your own user settings (see \vref{sec:indentconfig}) + then \texttt{latexindent.pl} will detail them in \texttt{indent.log}; you can choose + not to have the details logged by switching \texttt{showEveryYamlRead} to + \texttt{0}. Once all of your settings have been loaded, you can see the + amalgamated settings in the log file by switching \texttt{showAmalgamatedSettings} to + \texttt{1}, if you wish. \cmhlistingsfromfile[style=logFilePreferences,]*{../defaultSettings.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{logFilePreferences}}{lst:logFilePreferences} - When% - \announce{2018-01-13}{showDecorationStartCodeBlockTrace feature for log file} either of the \texttt{trace} modes (see \cpageref{page:traceswitch}) - are active, you will receive detailed information in \texttt{indent.log}. You can specify character strings - to appear before and after the notification of a found code block using, respectively, \texttt{showDecorationStartCodeBlockTrace} - and \texttt{showDecorationFinishCodeBlockTrace}. A demonstration is given in \vref{app:logfile-demo}. + When%%%% + \announce{2018-01-13}{showDecorationStartCodeBlockTrace feature for log file} either of the + \texttt{trace} modes (see \cpageref{page:traceswitch}) are active, you will receive + detailed information in \texttt{indent.log}. You can specify character strings to + appear before and after the notification of a found code block using, respectively, + \texttt{showDecorationStartCodeBlockTrace} and \texttt{showDecorationFinishCodeBlockTrace}. A demonstration is given in + \vref{app:logfile-demo}. - The log file will end with the characters - given in \texttt{endLogFileWith}, and will report the \texttt{GitHub} address - of \texttt{latexindent.pl} to the log file if \texttt{showGitHubInfoFooter} is set to \texttt{1}. + The log file will end with the characters given in \texttt{endLogFileWith}, and will + 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}. + 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}. \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}. + 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}. \begin{minipage}{.45\textwidth} \cmhlistingsfromfile[style=verbatimEnvironments]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{verbatimEnvironments}}{lst:verbatimEnvironments} @@ -117,29 +119,29 @@ copy myfile.bak4 to myfile.bak3 \cmhlistingsfromfile[style=verbatimCommands]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{verbatimCommands}}{lst:verbatimCommands} \end{minipage}% - Note that if you put an environment in \texttt{verbatimEnvironments} - and in other fields such as \texttt{lookForAlignDelims} or \texttt{noAdditionalIndent} - then \texttt{latexindent.pl} will \emph{always} prioritize \texttt{verbatimEnvironments}. + Note that if you put an environment in \texttt{verbatimEnvironments} and in other fields such + as \texttt{lookForAlignDelims} or \texttt{noAdditionalIndent} then \texttt{latexindent.pl} will + \emph{always} prioritize \texttt{verbatimEnvironments}. \yamltitle{verbatimCommands}*{fields} A field that contains a list of commands that are verbatim commands, for example - \lstinline|\lstinline|; any commands populated in this field are protected from line breaking - routines (only relevant if the \texttt{-m} is active, see \vref{sec:modifylinebreaks}). + \lstinline|\lstinline|; any commands populated in this field are protected from line + breaking routines (only relevant if the \texttt{-m} is active, see + \vref{sec:modifylinebreaks}). \yamltitle{noIndentBlock}*{fields} \begin{wrapfigure}[8]{r}[0pt]{6cm} \cmhlistingsfromfile[style=noIndentBlock]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{noIndentBlock}}{lst:noIndentBlock} \end{wrapfigure} - 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}. + 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}. - Of course, you don't want to have to specify these as null environments - in your code, so you use them with a comment symbol, \lstinline!%!, followed - by as many spaces (possibly none) as you like; see \cref{lst:noIndentBlockdemo} for - example. + Of course, you don't want to have to specify these as null environments in your code, so + you use them with a comment symbol, \lstinline!%!, followed by as many spaces + (possibly none) as you like; see \cref{lst:noIndentBlockdemo} for example. \begin{cmhlistings}[style=demo,escapeinside={(*@}{@*)}]{\texttt{noIndentBlock} demonstration}{lst:noIndentBlockdemo} %(*@@*) \begin{noindent} @@ -161,46 +163,52 @@ copy myfile.bak4 to myfile.bak3 removeTrailingWhitespace: 1 \end{yaml} \end{wrapfigure} - Trailing white space can be removed both \emph{before} and \emph{after} processing - the document, as detailed in \cref{lst:removeTrailingWhitespace}; each of the fields - can take the values \texttt{0} or \texttt{1}. See \vref{lst:removeTWS-before,lst:env-mlb5-modAll,lst:env-mlb5-modAll-remove-WS} - for before and after results. Thanks to \cite{vosskuhle} for providing this feature. - - You can specify \texttt{removeTrailingWhitespace} simply as \texttt{0} or \texttt{1}, if you wish; in this case, - \announce{2017-06-28}{removeTrailingWhitespace} - \texttt{latexindent.pl} will set both \texttt{beforeProcessing} and \texttt{afterProcessing} to the value you specify; - see \cref{lst:removeTrailingWhitespace-alt}. + Trailing white space can be removed both \emph{before} and + \emph{after} processing the document, as detailed in \cref{lst:removeTrailingWhitespace}; + each of the fields can take the values \texttt{0} or + \texttt{1}. See \vref{lst:removeTWS-before,lst:env-mlb5-modAll,lst:env-mlb5-modAll-remove-WS} for before and after results. Thanks + to \cite{vosskuhle} for providing this feature. + + You can specify \texttt{removeTrailingWhitespace} simply as \texttt{0} or + \texttt{1}, if you wish; in this case,% + \announce{2017-06-28}{removeTrailingWhitespace} \texttt{latexindent.pl} will set both \texttt{beforeProcessing} and + \texttt{afterProcessing} to the value you specify; see \cref{lst:removeTrailingWhitespace-alt}. \yamltitle{fileContentsEnvironments}*{field} \begin{wrapfigure}[6]{r}[0pt]{6cm} \cmhlistingsfromfile[style=fileContentsEnvironments]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{fileContentsEnvironments}}{lst:fileContentsEnvironments} \end{wrapfigure} - Before \texttt{latexindent.pl} determines the difference between preamble (if any) and the main document, - it first searches for any of the environments specified in \texttt{fileContentsEnvironments}, see - \cref{lst:fileContentsEnvironments}. - The behaviour of \texttt{latexindent.pl} on these environments is determined by their location (preamble or not), and - the value \texttt{indentPreamble}, discussed next. + Before \texttt{latexindent.pl} determines the difference between preamble (if any) and + the main document, it first searches for any of the environments specified in + \texttt{fileContentsEnvironments}, see \cref{lst:fileContentsEnvironments}. The behaviour of + \texttt{latexindent.pl} on these environments is determined by their location (preamble + or not), and the value \texttt{indentPreamble}, discussed next. \yamltitle{indentPreamble}{0|1} - The preamble of a document can sometimes contain some trickier code - for \texttt{latexindent.pl} to operate upon. By default, \texttt{latexindent.pl} - won't try to operate on the preamble (as \texttt{indentPreamble} is set to \texttt{0}, - by default), but if you'd like \texttt{latexindent.pl} to try then change \texttt{indentPreamble} to \texttt{1}. + The preamble of a document can sometimes contain some trickier code for + \texttt{latexindent.pl} to operate upon. By default, \texttt{latexindent.pl} won't try to + operate on the preamble (as \texttt{indentPreamble} is set to \texttt{0}, by + default), but if you'd like \texttt{latexindent.pl} to try then change + \texttt{indentPreamble} to \texttt{1}. \yamltitle{lookForPreamble}*{fields} \begin{wrapfigure}[8]{r}[0pt]{5cm} \cmhlistingsfromfile[style=lookForPreamble]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{lookForPreamble}{lst:lookForPreamble} \end{wrapfigure} - Not all files contain preamble; for example, \texttt{sty}, \texttt{cls} and \texttt{bib} files typically do \emph{not}. Referencing - \cref{lst:lookForPreamble}, if you set, for example, \texttt{.tex} to \texttt{0}, then regardless of the setting of the value of \texttt{indentPreamble}, preamble - will not be assumed when operating upon \texttt{.tex} files. + Not all files contain preamble; for example, \texttt{sty}, + \texttt{cls} and \texttt{bib} files typically do + \emph{not}. Referencing \cref{lst:lookForPreamble}, if you set, for example, + \texttt{.tex} to \texttt{0}, then regardless of the setting of the + value of \texttt{indentPreamble}, preamble will not be assumed when operating upon + \texttt{.tex} files. \yamltitle{preambleCommandsBeforeEnvironments}{0|1} - Assuming that \texttt{latexindent.pl} is asked to operate upon the preamble of a document, - when this switch is set to \texttt{0} then environment code blocks will be sought first, - and then command code blocks. When this switch is set to \texttt{1}, commands - will be sought first. The example that first motivated this switch contained the code given in \cref{lst:motivatepreambleCommandsBeforeEnvironments}. + Assuming that \texttt{latexindent.pl} is asked to operate upon the preamble of a + document, when this switch is set to \texttt{0} then environment code blocks + will be sought first, and then command code blocks. When this switch is set to + \texttt{1}, commands will be sought first. The example that first motivated + this switch contained the code given in \cref{lst:motivatepreambleCommandsBeforeEnvironments}. \begin{cmhlistings}{Motivating \texttt{preambleCommandsBeforeEnvironments}}{lst:motivatepreambleCommandsBeforeEnvironments} ... @@ -210,12 +218,12 @@ postfoothook=\end{mdframed}, \end{cmhlistings} \yamltitle{defaultIndent}*{horizontal space} - This is the default indentation (\lstinline!\t! means a tab, and is the default value) used in the absence of other details - for the command or environment we are working with; see \texttt{indentRules} in \vref{sec:noadd-indent-rules} - for more details. + This is the default indentation (\lstinline!\t! means a tab, and is the default + value) used in the absence of other details for the command or environment we are working + with; see \texttt{indentRules} in \vref{sec:noadd-indent-rules} for more details. - If you're interested in experimenting with \texttt{latexindent.pl} then you - can \emph{remove} all indentation by setting \texttt{defaultIndent: ""}. + 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} \begin{wrapfigure}[12]{r}[0pt]{5cm} @@ -229,19 +237,23 @@ lookForAlignDelims: ... \end{yaml} \end{wrapfigure} - 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. - - The environments specified in this field will be operated on in a special way by \texttt{latexindent.pl}. In particular, it will try and align each column by its alignment - tabs. It does have some limitations (discussed further in \cref{sec:knownlimitations}), - but in many cases it will produce results such as those in \cref{lst:tabularbefore:basic,lst:tabularafter:basic}. + 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. + + The environments specified in this field will be operated on in a special way by + \texttt{latexindent.pl}. In particular, it will try and align each column by its + alignment tabs. It does have some limitations (discussed further in + \cref{sec:knownlimitations}), but in many cases it will produce results such as those in + \cref{lst:tabularbefore:basic,lst:tabularafter:basic}. If you find that \texttt{latexindent.pl} does not perform satisfactorily on such - environments then you can set the relevant key to \texttt{0}, for example \texttt{tabular: 0}; alternatively, if you just want to ignore \emph{specific} - instances of the environment, you could wrap them in something from \texttt{noIndentBlock} (see \vref{lst:noIndentBlock}). + environments then you can set the relevant key to \texttt{0}, for example + \texttt{tabular: 0}; alternatively, if you just want to ignore + \emph{specific} instances of the environment, you could wrap them in something + from \texttt{noIndentBlock} (see \vref{lst:noIndentBlock}). \begin{minipage}{.45\textwidth} \cmhlistingsfromfile{demonstrations/tabular1.tex}{\texttt{tabular1.tex}}{lst:tabularbefore:basic} @@ -251,36 +263,46 @@ lookForAlignDelims: \cmhlistingsfromfile{demonstrations/tabular1-default.tex}{\texttt{tabular1.tex} default output}{lst:tabularafter:basic} \end{minipage}% - 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. + 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. \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/tabular.yaml}[yaml-TCB]{\texttt{tabular.yaml}}{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 and \texttt{longtable} is basic. When using the advanced form, each field should receive at least 1 sub-field, and \emph{can} - (but does not have to) receive any of the following fields: + 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 + and \texttt{longtable} is basic. When using the advanced form, each field should + receive at least 1 sub-field, and \emph{can} + (but does not have to) receive any of the following + fields: \begin{itemize} - \item \texttt{delims}: binary switch (0 or 1) equivalent to simply specifying, for example, \texttt{tabular: 1} in - the basic version shown in \cref{lst:aligndelims:basic}. If \texttt{delims} is set to \texttt{0} then the align at ampersand routine - will not be called for this code block (default: 1); - \item \texttt{alignDoubleBackSlash}: binary switch (0 or 1) to determine if \lstinline!\\! should be aligned (default: 1); + \item \texttt{delims}: binary switch (0 or 1) equivalent to simply specifying, for + example, \texttt{tabular: 1} in the basic version shown in \cref{lst:aligndelims:basic}. If + \texttt{delims} is set to \texttt{0} then the align at ampersand + routine will not be called for this code block (default: 1); + \item \texttt{alignDoubleBackSlash}: binary switch (0 or 1) to determine if \lstinline!\\! + should be aligned (default: 1); \item \texttt{spacesBeforeDoubleBackSlash}: optionally,% - \announce{2018-01-13}*{update to spacesBeforeDoubleBackSlash in ampersand alignment} specifies the number (integer $\geq$ 0) of spaces to be inserted - before \lstinline!\\! (default: 1). \footnote{Previously this only activated if \texttt{alignDoubleBackSlash} was set to \texttt{0}.} - \item \announce{2017-06-19}{multiColumnGrouping} \texttt{multiColumnGrouping}: binary switch (0 or 1) that details if \texttt{latexindent.pl} should group columns + \announce{2018-01-13}*{update to spacesBeforeDoubleBackSlash in ampersand alignment} specifies the number (integer $\geq$ 0) of spaces + to be inserted before \lstinline!\\! (default: 1). \footnote{Previously this only activated if \texttt{alignDoubleBackSlash} was set to \texttt{0}.} + \item \announce{2017-06-19}{multiColumnGrouping} \texttt{multiColumnGrouping}: binary switch (0 or 1) that details if + \texttt{latexindent.pl} should group columns above and below a \lstinline!\multicolumn! command (default: 0); - \item \announce{2017-06-19}{alignRowsWithoutMaxDelims} \texttt{alignRowsWithoutMaxDelims}: binary switch (0 or 1) that details if rows that do not contain the - maximum number of delimeters should be formatted so as to have the ampersands aligned (default: 1); - \item \announce{2018-01-13}{spacesBeforeAmpersand in ampersand alignment}\texttt{spacesBeforeAmpersand}: optionally specifies the number (integer $\geq$ 0) of + \item \announce{2017-06-19}{alignRowsWithoutMaxDelims} \texttt{alignRowsWithoutMaxDelims}: binary switch (0 or 1) that details if + rows that do not contain the maximum number of delimeters should be formatted so as to + have the ampersands aligned (default: 1); + \item \announce{2018-01-13}{spacesBeforeAmpersand in ampersand alignment}\texttt{spacesBeforeAmpersand}: optionally specifies the number (integer + $\geq$ 0) of spaces to be placed \emph{before} ampersands (default: 1); - \item \announce{2018-01-13}{spacesAfterAmpersand in ampersand alignment}\texttt{spacesAfterAmpersand}: optionally specifies the number (integer $\geq$ 0) of + \item \announce{2018-01-13}{spacesAfterAmpersand in ampersand alignment}\texttt{spacesAfterAmpersand}: optionally specifies the number (integer + $\geq$ 0) of 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{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). \end{itemize} - We will explore each of these features using the file \texttt{tabular2.tex} in \cref{lst:tabular2} (which contains a \lstinline!\multicolumn! command), - and the YAML files in \crefrange{lst:tabular2YAML}{lst:tabular8YAML}. + We will explore each of these features using the file \texttt{tabular2.tex} in + \cref{lst:tabular2} (which contains a \lstinline!\multicolumn! command), and the YAML files in \crefrange{lst:tabular2YAML}{lst:tabular8YAML}. \cmhlistingsfromfile{demonstrations/tabular2.tex}{\texttt{tabular2.tex}}{lst:tabular2} \begin{minipage}{.45\textwidth} @@ -337,37 +359,47 @@ latexindent.pl tabular2.tex -l tabular2.yaml,tabular8.yaml Notice in particular: \begin{itemize} - \item in both \cref{lst:tabular2-default,lst:tabular2-mod2} all rows have been aligned at the ampersand, even - those that do not contain the maximum number of ampersands (3 ampersands, in this case); + \item in both \cref{lst:tabular2-default,lst:tabular2-mod2} all rows have been aligned at the ampersand, even those + that do not contain the maximum number of ampersands (3 ampersands, in this case); \item in \cref{lst:tabular2-default} the columns have been aligned at the ampersand; - \item in \cref{lst:tabular2-mod2} the \lstinline!\multicolumn! command has grouped the $2$ columns beneath \emph{and} above it, - because \texttt{multiColumnGrouping} is set to $1$ in \cref{lst:tabular2YAML}; - \item in \cref{lst:tabular2-mod3} rows~3 and~6 have \emph{not} been aligned at the ampersand, because - \texttt{alignRowsWithoutMaxDelims} has been to set to $0$ in \cref{lst:tabular3YAML}; however, - the \lstinline!\\! \emph{have} still been aligned; - \item in \cref{lst:tabular2-mod4} the columns beneath and above the \lstinline!\multicolumn! commands have been - grouped (because \texttt{multiColumnGrouping} is set to $1$), and there are at least $4$ spaces \emph{before} - each aligned ampersand because \texttt{spacesBeforeAmpersand} is set to $4$; - \item in \cref{lst:tabular2-mod5} the columns beneath and above the \lstinline!\multicolumn! commands have been - grouped (because \texttt{multiColumnGrouping} is set to $1$), and there are at least $4$ spaces \emph{after} - each aligned ampersand because \texttt{spacesAfterAmpersand} is set to $4$; - \item in \cref{lst:tabular2-mod6} the \lstinline!\\! have \emph{not} been aligned, because \texttt{alignDoubleBackSlash} - is set to \texttt{0}, otherwise the output is the same as \cref{lst:tabular2-mod2}; - \item in \cref{lst:tabular2-mod7} the \lstinline!\\! \emph{have} been aligned, and because \texttt{spacesBeforeDoubleBackSlash} - is set to \texttt{0}, there are no spaces ahead of them; the output is otherwise the same as \cref{lst:tabular2-mod2}. - \item in \cref{lst:tabular2-mod8} the cells have been \emph{right}-justified; note that cells above and below the \lstinline!\multicol! - statements have still been group correctly, because of the settings in \cref{lst:tabular2YAML}. + \item in \cref{lst:tabular2-mod2} the \lstinline!\multicolumn! command has grouped the + $2$ columns beneath \emph{and} above it, because + \texttt{multiColumnGrouping} is set to $1$ in \cref{lst:tabular2YAML}; + \item in \cref{lst:tabular2-mod3} rows~3 and~6 have \emph{not} been aligned at the + ampersand, because \texttt{alignRowsWithoutMaxDelims} has been to set to $0$ in + \cref{lst:tabular3YAML}; however, the \lstinline!\\! \emph{have} still + been aligned; + \item in \cref{lst:tabular2-mod4} the columns beneath and above the \lstinline!\multicolumn! + commands have been grouped (because \texttt{multiColumnGrouping} is set to + $1$), and there are at least $4$ spaces + \emph{before} each aligned ampersand because \texttt{spacesBeforeAmpersand} is set to + $4$; + \item in \cref{lst:tabular2-mod5} the columns beneath and above the \lstinline!\multicolumn! + commands have been grouped (because \texttt{multiColumnGrouping} is set to + $1$), and there are at least $4$ spaces + \emph{after} each aligned ampersand because \texttt{spacesAfterAmpersand} is set to + $4$; + \item in \cref{lst:tabular2-mod6} the \lstinline!\\! have \emph{not} been + aligned, because \texttt{alignDoubleBackSlash} is set to \texttt{0}, otherwise the + output is the same as \cref{lst:tabular2-mod2}; + \item in \cref{lst:tabular2-mod7} the \lstinline!\\! \emph{have} been + aligned, and because \texttt{spacesBeforeDoubleBackSlash} is set to \texttt{0}, there are + no spaces ahead of them; the output is otherwise the same as \cref{lst:tabular2-mod2}. + \item in \cref{lst:tabular2-mod8} the cells have been \emph{right}-justified; note + that cells above and below the \lstinline!\multicol! statements have still been group + correctly, because of the settings in \cref{lst:tabular2YAML}. \end{itemize} - As of Version 3.0, the alignment routine works on mandatory and optional arguments within commands, and also within `special' code blocks - (see \texttt{specialBeginEnd} on \cpageref{yaml:specialBeginEnd}); for example, assuming that you have a command called \lstinline!\matrix! - and that it is populated within \texttt{lookForAlignDelims} (which it is, by default), and that you - run the command + As of Version 3.0, the alignment routine works on mandatory and optional arguments within + commands, and also within `special' code blocks (see \texttt{specialBeginEnd} on + \cpageref{yaml:specialBeginEnd}); for example, assuming that you have a command called + \lstinline!\matrix! and that it is populated within \texttt{lookForAlignDelims} (which it is, by default), and that + you run the command \begin{commandshell} latexindent.pl matrix1.tex \end{commandshell} - then the before-and-after results - shown in \cref{lst:matrixbefore,lst:matrixafter} are achievable by default. + then the before-and-after results shown in \cref{lst:matrixbefore,lst:matrixafter} are achievable by + default. \begin{minipage}{.45\textwidth} \cmhlistingsfromfile{demonstrations/matrix1.tex}{\texttt{matrix1.tex}}{lst:matrixbefore} @@ -377,10 +409,12 @@ latexindent.pl matrix1.tex \cmhlistingsfromfile{demonstrations/matrix1-default.tex}{\texttt{matrix1.tex} default output}{lst:matrixafter} \end{minipage}% - If you have blocks of code that you wish to align at the \& character that - are \emph{not} wrapped in, for example, \lstinline!\begin{tabular}! \ldots \lstinline!\end{tabular}!, then you can use the mark up - illustrated in \cref{lst:alignmentmarkup}; the default output is shown in \cref{lst:alignmentmarkup-default}. Note that the \lstinline!%*! must be next to - each other, but that there can be any number of spaces (possibly none) between the + If you have blocks of code that you wish to align at the \& character that are + \emph{not} wrapped in, for example, \lstinline!\begin{tabular}! \ldots + \lstinline!\end{tabular}!, then you can use the mark up illustrated in + \cref{lst:alignmentmarkup}; the default output is shown in \cref{lst:alignmentmarkup-default}. Note + that the \lstinline!%*! must be next to each other, but that there can be any + number of spaces (possibly none) between the \lstinline!*! and \lstinline!\begin{tabular}!; note also that you may use any environment name that you have specified in \texttt{lookForAlignDelims}. @@ -392,17 +426,19 @@ latexindent.pl matrix1.tex \cmhlistingsfromfile{demonstrations/align-block-default.tex}{\texttt{align-block.tex} default output}{lst:alignmentmarkup-default} \end{minipage}% - With reference to \vref{tab:code-blocks} and the, yet undiscussed, fields of \texttt{noAdditionalIndent} and \texttt{indentRules} - (see \vref{sec:noadd-indent-rules}), these comment-marked blocks are considered \texttt{environments}. + With reference to \vref{tab:code-blocks} and the, yet undiscussed, fields of + \texttt{noAdditionalIndent} and \texttt{indentRules} + (see \vref{sec:noadd-indent-rules}), these comment-marked blocks are + considered \texttt{environments}. \yamltitle{indentAfterItems}*{fields} \begin{wrapfigure}[5]{r}[0pt]{7cm} \cmhlistingsfromfile[style=indentAfterItems]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{indentAfterItems}}{lst:indentafteritems} \end{wrapfigure} - The environment names specified in \texttt{indentAfterItems} tell - \texttt{latexindent.pl} to look for \lstinline!\item! commands; if these switches are set to \texttt{1} - then indentation will be performed so as indent the code after each \texttt{item}. - A demonstration is given in \cref{lst:itemsbefore,lst:itemsafter} + The environment names specified in \texttt{indentAfterItems} tell \texttt{latexindent.pl} + to look for \lstinline!\item! commands; if these switches are set to + \texttt{1} then indentation will be performed so as indent the code after + each \texttt{item}. A demonstration is given in \cref{lst:itemsbefore,lst:itemsafter} \begin{minipage}{.45\textwidth} \cmhlistingsfromfile{demonstrations/items1.tex}{\texttt{items1.tex}}{lst:itemsbefore} @@ -416,26 +452,28 @@ latexindent.pl matrix1.tex \begin{wrapfigure}[5]{r}[0pt]{5cm} \cmhlistingsfromfile[style=itemNames]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{itemNames}}{lst:itemNames} \end{wrapfigure} - If you have your own \texttt{item} commands (perhaps you - prefer to use \texttt{myitem}, for example) - then you can put populate them in \texttt{itemNames}. - For example, users of the \texttt{exam} document class might like to add - \texttt{parts} to \texttt{indentAfterItems} and \texttt{part} to \texttt{itemNames} - to their user settings (see \vref{sec:indentconfig} for details of how to configure user settings, - and \vref{lst:mysettings} \\ in particular \label{page:examsettings}.) + If you have your own \texttt{item} commands (perhaps you prefer to use + \texttt{myitem}, for example) then you can put populate them in + \texttt{itemNames}. For example, users of the \texttt{exam} document class + might like to add \texttt{parts} to \texttt{indentAfterItems} and + \texttt{part} to \texttt{itemNames} to their user settings (see + \vref{sec:indentconfig} for details of how to configure user settings, and + \vref{lst:mysettings} \\ in particular \label{page:examsettings}.) \yamltitle{specialBeginEnd}*{fields}\label{yaml:specialBeginEnd} - The fields specified% - \announce{2017-08-21}*{specialBeginEnd} in \texttt{specialBeginEnd} are, in their default state, focused on math mode begin and end statements, but - there is no requirement for this to be the case; \cref{lst:specialBeginEnd} shows the - default settings of \texttt{specialBeginEnd}. + The fields specified%%%% + \announce{2017-08-21}*{specialBeginEnd} in + \texttt{specialBeginEnd} are, in their default state, focused on math mode begin and end + statements, but there is no requirement for this to be the case; \cref{lst:specialBeginEnd} + shows the default settings of \texttt{specialBeginEnd}. \cmhlistingsfromfile[style=specialBeginEnd]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{specialBeginEnd}}{lst:specialBeginEnd} - The field \texttt{displayMath} represents \lstinline!\[...\]!, \texttt{inlineMath} represents - \lstinline!$...$! and \texttt{displayMathTex} represents \lstinline!$$...$$!. You can, of course, - rename these in your own YAML files (see \vref{sec:localsettings}); indeed, you - might like to set up your own special begin and end statements. + The field \texttt{displayMath} represents \lstinline!\[...\]!, + \texttt{inlineMath} represents + \lstinline!$...$! and \texttt{displayMathTex} represents \lstinline!$$...$$!. + You can, of course, rename these in your own YAML files (see \vref{sec:localsettings}); + indeed, you might like to set up your own special begin and end statements. A demonstration of the before-and-after results are shown in \cref{lst:specialbefore,lst:specialafter}. @@ -447,14 +485,16 @@ latexindent.pl matrix1.tex \cmhlistingsfromfile{demonstrations/special1-default.tex}{\texttt{special1.tex} default output}{lst:specialafter} \end{minipage} - For each field, \texttt{lookForThis} is set to \texttt{1} by default, which means that \texttt{latexindent.pl} - will look for this pattern; you can tell \texttt{latexindent.pl} not to look for the pattern, by setting - \texttt{lookForThis} to \texttt{0}. + For each field, \texttt{lookForThis} is set to \texttt{1} by default, + which means that \texttt{latexindent.pl} will look for this pattern; you can tell + \texttt{latexindent.pl} not to look for the pattern, by setting \texttt{lookForThis} + to \texttt{0}. - There are% - \announce{2017-08-21}{specialBeforeCommand} examples in which it is advantageous to search for \texttt{specialBeginEnd} fields \emph{before} - searching for commands, and the \texttt{specialBeforeCommand} switch controls this behaviour. For example, consider - the file shown in \cref{lst:specialLRbefore}. + There are%%%% + \announce{2017-08-21}{specialBeforeCommand} examples in which it + is advantageous to search for \texttt{specialBeginEnd} fields \emph{before} + searching for commands, and the \texttt{specialBeforeCommand} switch controls this behaviour. + For example, consider the file shown in \cref{lst:specialLRbefore}. \cmhlistingsfromfile{demonstrations/specialLR.tex}{\texttt{specialLR.tex}}{lst:specialLRbefore} @@ -487,16 +527,19 @@ latexindent.pl specialLR.tex -l=specialsLeftRight.yaml,specialBeforeCommand.yaml Notice that in: \begin{itemize} - \item \cref{lst:specialLR-comm-first-tex} the \lstinline!\left! has been treated as a \emph{command}, with one optional argument; - \item \cref{lst:specialLR-special-first-tex} the \texttt{specialBeginEnd} pattern in \cref{lst:specialsLeftRight-yaml} has been obeyed - because \cref{lst:specialBeforeCommand-yaml} specifies that the \texttt{specialBeginEnd} should be sought \emph{before} commands. + \item \cref{lst:specialLR-comm-first-tex} the \lstinline!\left! has been treated as a + \emph{command}, with one optional argument; + \item \cref{lst:specialLR-special-first-tex} the \texttt{specialBeginEnd} pattern in \cref{lst:specialsLeftRight-yaml} + has been obeyed because \cref{lst:specialBeforeCommand-yaml} specifies that the + \texttt{specialBeginEnd} should be sought \emph{before} commands. \end{itemize} - You can,optionally, specify% - \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}. + You can,optionally, specify%%%% + \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}. - \cmhlistingsfromfile*{demonstrations/special2.tex}{\texttt{special2.tex}}{lst:special2} + \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 \begin{commandshell} @@ -506,52 +549,80 @@ latexindent.pl special2.tex -l=middle1 then we obtain the output given in \cref{lst:special2-mod1,lst:special2-mod2}. \begin{minipage}{.4\linewidth} - \cmhlistingsfromfile*{demonstrations/middle.yaml}[yaml-TCB]{\texttt{middle.yaml}}{lst:middle-yaml} + \cmhlistingsfromfile{demonstrations/middle.yaml}[yaml-TCB]{\texttt{middle.yaml}}{lst:middle-yaml} \end{minipage} \hfill \begin{minipage}{.5\linewidth} - \cmhlistingsfromfile*{demonstrations/special2-mod1.tex}{\texttt{special2.tex} using \cref{lst:middle-yaml}}{lst:special2-mod1} + \cmhlistingsfromfile{demonstrations/special2-mod1.tex}{\texttt{special2.tex} using \cref{lst:middle-yaml}}{lst:special2-mod1} \end{minipage} \begin{minipage}{.4\linewidth} - \cmhlistingsfromfile*{demonstrations/middle1.yaml}[yaml-TCB]{\texttt{middle1.yaml}}{lst:middle1-yaml} + \cmhlistingsfromfile{demonstrations/middle1.yaml}[yaml-TCB]{\texttt{middle1.yaml}}{lst:middle1-yaml} \end{minipage} \hfill \begin{minipage}{.5\linewidth} - \cmhlistingsfromfile*{demonstrations/special2-mod2.tex}{\texttt{special2.tex} using \cref{lst:middle1-yaml}}{lst:special2-mod2} + \cmhlistingsfromfile{demonstrations/special2-mod2.tex}{\texttt{special2.tex} using \cref{lst:middle1-yaml}}{lst:special2-mod2} \end{minipage} We note that: \begin{itemize} - \item in \cref{lst:special2-mod1} the bodies of each of the \texttt{Elsif} statements have been indented appropriately; - \item the \texttt{Else} statement has \emph{not} been indented appropriately in \cref{lst:special2-mod1} -- read on! - \item we have specified multiple settings for the \texttt{middle} field using the syntax demonstrated in - \cref{lst:middle1-yaml} so that the body of the \texttt{Else} statement has been indented appropriately in \cref{lst:special2-mod2}. + \item in \cref{lst:special2-mod1} the bodies of each of the \texttt{Elsif} statements + have been indented appropriately; + \item the \texttt{Else} statement has \emph{not} been indented + appropriately in \cref{lst:special2-mod1} -- read on! + \item we have specified multiple settings for the \texttt{middle} field using the + syntax demonstrated in \cref{lst:middle1-yaml} so that the body of the + \texttt{Else} statement has been indented appropriately in + \cref{lst:special2-mod2}. \end{itemize} + You may%% + \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}. + + For example, beginning with the code in \cref{lst:special3-mod1} and the YAML in + \cref{lst:special-verb1-yaml}, and running + \begin{commandshell} +latexindent.pl special3.tex -l=special-verb1 + \end{commandshell} + then the output in \cref{lst:special3-mod1} is unchanged. + + \begin{minipage}{.4\linewidth} + \cmhlistingsfromfile*{demonstrations/special-verb1.yaml}[yaml-TCB]{\texttt{special-verb1.yaml}}{lst:special-verb1-yaml} + \end{minipage} + \hfill + \begin{minipage}{.5\linewidth} + \cmhlistingsfromfile*{demonstrations/special3-mod1.tex}{\texttt{special3.tex} and output using \cref{lst:special-verb1-yaml}}{lst:special3-mod1} + \end{minipage} + \yamltitle{indentAfterHeadings}*{fields} \begin{wrapfigure}[17]{r}[0pt]{8cm} \cmhlistingsfromfile[style=indentAfterHeadings]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{indentAfterHeadings}}{lst:indentAfterHeadings} \end{wrapfigure} - This field enables the user to specify - indentation rules that take effect after heading commands such as \lstinline!\part!, \lstinline!\chapter!, - \lstinline!\section!, \lstinline!\subsection*!, or indeed any user-specified command written in this field.\footnote{There is a slight + This field enables the user to specify indentation rules that take effect after heading + commands such as \lstinline!\part!, \lstinline!\chapter!, + \lstinline!\section!, \lstinline!\subsection*!, or indeed any user-specified command + written in this field.\footnote{There is a slight difference in interface for this field when comparing Version 2.2 to Version 3.0; see \vref{app:differences} for details.} - The default settings do \emph{not} place indentation after a heading, but you - can easily switch them on by changing \\ \texttt{indentAfterThisHeading: 0} to \\ \texttt{indentAfterThisHeading: 1}. - The \texttt{level} field tells \texttt{latexindent.pl} the hierarchy of the heading - structure in your document. You might, for example, like to have both \texttt{section} - and \texttt{subsection} set with \texttt{level: 3} because you do not want the indentation to go too deep. + The default settings do \emph{not} place indentation after a heading, but + you can easily switch them on by changing \\ \texttt{indentAfterThisHeading: 0} to \\ + \texttt{indentAfterThisHeading: 1}. The \texttt{level} field tells \texttt{latexindent.pl} + the hierarchy of the heading structure in your document. You might, for example, like to + have both \texttt{section} and \texttt{subsection} set with + \texttt{level: 3} because you do not want the indentation to go too deep. - You can add any of your own custom heading commands to this field, specifying the \texttt{level} - as appropriate. You can also specify your own indentation in \texttt{indentRules} (see \vref{sec:noadd-indent-rules}); - you will find the default \texttt{indentRules} contains \lstinline!chapter: " "! which - tells \texttt{latexindent.pl} simply to use a space character after \texttt{\chapter} headings - (once \texttt{indent} is set to \texttt{1} for \texttt{chapter}). + You can add any of your own custom heading commands to this field, specifying the + \texttt{level} as appropriate. You can also specify your own indentation in + \texttt{indentRules} (see \vref{sec:noadd-indent-rules}); you will find the default \texttt{indentRules} contains + \lstinline!chapter: " "! which tells \texttt{latexindent.pl} simply to use a space + character after \texttt{\chapter} headings (once \texttt{indent} is set to + \texttt{1} for \texttt{chapter}). - For example, assuming that you have the code in \cref{lst:headings1yaml} saved into \texttt{headings1.yaml}, - and that you have the text from \cref{lst:headings1} saved into \texttt{headings1.tex}. + For example, assuming that you have the code in \cref{lst:headings1yaml} saved into + \texttt{headings1.yaml}, and that you have the text from \cref{lst:headings1} saved + into \texttt{headings1.tex}. \begin{minipage}{.45\textwidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/headings1.yaml}[yaml-TCB]{\texttt{headings1.yaml}}{lst:headings1yaml} @@ -575,23 +646,25 @@ latexindent.pl headings1.tex -l=headings1.yaml \cmhlistingsfromfile[showtabs=true]{demonstrations/headings1-mod2.tex}{\texttt{headings1.tex} second modification}{lst:headings1-mod2} \end{minipage} - Now say that you modify the \texttt{YAML} from \cref{lst:headings1yaml} so that the \texttt{paragraph} \texttt{level} is \texttt{1}; after + Now say that you modify the \texttt{YAML} from \cref{lst:headings1yaml} so that + the \texttt{paragraph} \texttt{level} is \texttt{1}; after running \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. + you should receive the code given in \cref{lst:headings1-mod2}; notice that the + \texttt{paragraph} and \texttt{subsection} are at the same indentation level. \yamltitle{maximumIndentation}*{horizontal space} - You can control the maximum indentation given to your file by% - \announce{2017-08-21}{maximumIndentation} - specifying the \texttt{maximumIndentation} field as horizontal space (but \emph{not} including tabs). - This feature uses the \texttt{Text::Tabs} module \cite{texttabs}, and is \emph{off} - by default. + You can control the maximum indentation given to your file + by%%%% + \announce{2017-08-21}{maximumIndentation} specifying the + \texttt{maximumIndentation} field as horizontal space (but \emph{not} including + tabs). This feature uses the \texttt{Text::Tabs} module \cite{texttabs}, and + is \emph{off} by default. - For example, consider the example shown in \cref{lst:mult-nested} together with the default output - shown in \cref{lst:mult-nested-default}. + For example, consider the example shown in \cref{lst:mult-nested} together with the + default output shown in \cref{lst:mult-nested-default}. \begin{minipage}{.45\textwidth} \cmhlistingsfromfile{demonstrations/mult-nested.tex}{\texttt{mult-nested.tex}}{lst:mult-nested} @@ -601,8 +674,8 @@ latexindent.pl headings1.tex -l=headings1.yaml \cmhlistingsfromfile[showtabs=true]{demonstrations/mult-nested-default.tex}{\texttt{mult-nested.tex} default output}{lst:mult-nested-default} \end{minipage} - Now say that, for example, you have the \texttt{max-indentation1.yaml} from \cref{lst:max-indentation1yaml} and - that you run the following command: + Now say that, for example, you have the \texttt{max-indentation1.yaml} from + \cref{lst:max-indentation1yaml} and that you run the following command: \begin{commandshell} latexindent.pl mult-nested.tex -l=max-indentation1 \end{commandshell} @@ -616,15 +689,16 @@ latexindent.pl mult-nested.tex -l=max-indentation1 \cmhlistingsfromfile[showspaces=true]{demonstrations/mult-nested-max-ind1.tex}{\texttt{mult-nested.tex} using \cref{lst:max-indentation1yaml}}{lst:mult-nested-max-ind1} \end{minipage} - Comparing the output in \cref{lst:mult-nested-default,lst:mult-nested-max-ind1} we notice that the (default) tabs - of indentation have been replaced by a single space. + Comparing the output in \cref{lst:mult-nested-default,lst:mult-nested-max-ind1} we notice that the (default) tabs of + indentation have been replaced by a single space. - In general, when using the \texttt{maximumIndentation} feature, any leading tabs will be replaced by equivalent - spaces except, of course, those found in \texttt{verbatimEnvironments} (see \vref{lst:verbatimEnvironments}) or \texttt{noIndentBlock} (see \vref{lst:noIndentBlock}). + In general, when using the \texttt{maximumIndentation} feature, any leading tabs will be + replaced by equivalent spaces except, of course, those found in \texttt{verbatimEnvironments} (see \vref{lst:verbatimEnvironments}) + or \texttt{noIndentBlock} (see \vref{lst:noIndentBlock}). \subsection{The code blocks known 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}. + As of Version 3.0, \texttt{latexindent.pl} processes documents using code blocks; each of + these are shown in \cref{tab:code-blocks}. \begin{table}[!htp] \begin{widepage} diff --git a/Master/texmf-dist/doc/support/latexindent/sec-demonstration.tex b/Master/texmf-dist/doc/support/latexindent/sec-demonstration.tex index 71eb207c6e3..9049a5dfd8e 100644 --- a/Master/texmf-dist/doc/support/latexindent/sec-demonstration.tex +++ b/Master/texmf-dist/doc/support/latexindent/sec-demonstration.tex @@ -1,18 +1,17 @@ % arara: pdflatex: {shell: yes, files: [latexindent]} \section{Demonstration: before and after} - Let's give a demonstration of some before and after code -- after all, you probably - won't want to try the script if you don't much like the results. You might also - like to watch the video demonstration I made on youtube \cite{cmh:videodemo} + Let's give a demonstration of some before and after code -- after all, you probably won't + want to try the script if you don't much like the results. You might also like to watch + the video demonstration I made on youtube \cite{cmh:videodemo} - As you look at \crefrange{lst:filecontentsbefore}{lst:pstricksafter}, remember - that \texttt{latexindent.pl} is just following its rules, and there is nothing - particular about these code snippets. All of the rules can be modified - so that you can personalize your indentation scheme. + As you look at \crefrange{lst:filecontentsbefore}{lst:pstricksafter}, remember that \texttt{latexindent.pl} is just + following its rules, and there is nothing particular about these code snippets. All of + the rules can be modified so that you can personalize your indentation scheme. - In each of the samples given in \crefrange{lst:filecontentsbefore}{lst:pstricksafter} - the `before' case is a `worst case scenario' with no effort to make indentation. The `after' - result would be the same, regardless of the leading white space at the beginning of - each line which is stripped by \texttt{latexindent.pl} (unless a \texttt{verbatim}-like + In each of the samples given in \crefrange{lst:filecontentsbefore}{lst:pstricksafter} the `before' case is a `worst case + scenario' with no effort to make indentation. The `after' result would be the same, + regardless of the leading white space at the beginning of each line which is stripped by + \texttt{latexindent.pl} (unless a \texttt{verbatim}-like environment or \texttt{noIndentBlock} is specified -- more on this in \cref{sec:defuseloc}). \begin{widepage} diff --git a/Master/texmf-dist/doc/support/latexindent/sec-how-to-use.tex b/Master/texmf-dist/doc/support/latexindent/sec-how-to-use.tex index 165cccf4724..6a5aa290ca0 100644 --- a/Master/texmf-dist/doc/support/latexindent/sec-how-to-use.tex +++ b/Master/texmf-dist/doc/support/latexindent/sec-how-to-use.tex @@ -1,37 +1,38 @@ % arara: pdflatex: {shell: yes, files: [latexindent]} \section{How to use the script} \texttt{latexindent.pl} ships as part of the \TeX Live distribution for - Linux and Mac users; \texttt{latexindent.exe} ships as part of the \TeX Live - and MiK\TeX{} distributions for Windows users. These files are also available - from github \cite{latexindent-home} should you wish to use them without - a \TeX{} distribution; in this case, you may like to read \vref{sec:updating-path} - which details how the \texttt{path} variable can be updated. - - In what follows, we will always refer to \texttt{latexindent.pl}, but depending on - your operating system and preference, you might substitute \texttt{latexindent.exe} or - simply \texttt{latexindent}. - - There are two ways to use \texttt{latexindent.pl}: from the command line, - and using \texttt{arara}; we discuss these in \cref{sec:commandline} and + Linux and Mac users; \texttt{latexindent.exe} ships as part of the \TeX Live and + MiK\TeX{} distributions for Windows users. These files are also available + from github \cite{latexindent-home} should you wish to use them without a + \TeX{} distribution; in this case, you may like to read + \vref{sec:updating-path} which details how the \texttt{path} variable can be + updated. + + In what follows, we will always refer to \texttt{latexindent.pl}, but depending on your + operating system and preference, you might substitute \texttt{latexindent.exe} or simply + \texttt{latexindent}. + + There are two ways to use \texttt{latexindent.pl}: from the command line, and using + \texttt{arara}; we discuss these in \cref{sec:commandline} and \cref{sec:arara} respectively. We will discuss how to change the settings and behaviour of the script in \vref{sec:defuseloc}. \texttt{latexindent.pl} ships with \texttt{latexindent.exe} for Windows - users, so that you can use the script with or without a Perl distribution. - If you plan to use \texttt{latexindent.pl} (i.e, the original Perl script) then you will - need a few standard Perl modules -- see \vref{sec:requiredmodules} for details; - \announce{2018-01-13}{perl module installer helper script} in particular, note - that a module installer helper script is shipped with \texttt{latexindent.pl}. + users, so that you can use the script with or without a Perl distribution. If you plan to + use \texttt{latexindent.pl} (i.e, the original Perl script) then you will need a few standard Perl modules -- see + \vref{sec:requiredmodules} for details;% + \announce{2018-01-13}{perl module installer helper script} in particular, note that a module installer helper script is + shipped with \texttt{latexindent.pl}. \subsection{From the command line}\label{sec:commandline} \texttt{latexindent.pl} has a number of different switches/flags/options, which can be combined in any way that you like, either in short or long form as detailed below. - \texttt{latexindent.pl} produces a \texttt{.log} file, \texttt{indent.log}, every time it - is run; the name of the log file can be customized, but we will - refer to the log file as \texttt{indent.log} throughout this document. - There is a base of information that is written to \texttt{indent.log}, - but other additional information will be written depending - on which of the following options are used. + \texttt{latexindent.pl} produces a \texttt{.log} file, + \texttt{indent.log}, every time it is run; the name of the log file can be customized, + but we will refer to the log file as \texttt{indent.log} throughout this document. + There is a base of information that is written to \texttt{indent.log}, but other + additional information will be written depending on which of the following options are + used. \flagbox{-v, --version} \announce{2017-06-25}{version} @@ -52,8 +53,9 @@ latexindent.pl -h latexindent.pl myfile.tex \end{commandshell} - This will operate on \texttt{myfile.tex}, but will simply output to your terminal; \texttt{myfile.tex} will not be changed - by \texttt{latexindent.pl} in any way using this command. + This will operate on \texttt{myfile.tex}, but will simply output to your terminal; + \texttt{myfile.tex} will not be changed by \texttt{latexindent.pl} in any way + using this command. \flagbox{-w, --overwrite} \begin{commandshell} @@ -62,14 +64,15 @@ latexindent.pl --overwrite myfile.tex latexindent.pl myfile.tex --overwrite \end{commandshell} - This \emph{will} overwrite \texttt{myfile.tex}, but it will - make a copy of \texttt{myfile.tex} first. You can control the name of - the extension (default is \texttt{.bak}), and how many different backups are made -- - more on this in \cref{sec:defuseloc}, and in particular see \texttt{backupExtension} and \texttt{onlyOneBackUp}. + This \emph{will} overwrite \texttt{myfile.tex}, but it will make a copy of + \texttt{myfile.tex} first. You can control the name of the extension (default is + \texttt{.bak}), and how many different backups are made -- more on this in + \cref{sec:defuseloc}, and in particular see \texttt{backupExtension} and + \texttt{onlyOneBackUp}. - Note that if \texttt{latexindent.pl} can not create the backup, then it - will exit without touching your original file; an error message will be given - asking you to check the permissions of the backup file. + Note that if \texttt{latexindent.pl} can not create the backup, then it will exit without + touching your original file; an error message will be given asking you to check the + permissions of the backup file. \flagbox{-o=output.tex,--outputfile=output.tex} \begin{commandshell} @@ -81,39 +84,42 @@ latexindent.pl --outputfile output.tex myfile.tex This will indent \texttt{myfile.tex} and output it to \texttt{output.tex}, overwriting it (\texttt{output.tex}) if it already exists\footnote{Users of version 2.* should - note the subtle change in syntax}. Note that if \texttt{latexindent.pl} is called with both - the \texttt{-w} and \texttt{-o} switches, then \texttt{-w} will - be ignored and \texttt{-o} will take priority (this seems safer than the - other way round). + note the subtle change in syntax}. Note + that if \texttt{latexindent.pl} is called with both the \texttt{-w} and + \texttt{-o} switches, then \texttt{-w} will be ignored and + \texttt{-o} will take priority (this seems safer than the other way round). Note that using \texttt{-o} as above is equivalent to using \begin{commandshell} latexindent.pl myfile.tex > output.tex \end{commandshell} - You can call the \texttt{-o} switch with the name of the output file \emph{without} an extension; in - \announce{2017-06-25}{upgrade to -o switch} - this case, \texttt{latexindent.pl} will use the extension from the original file. For example, - the following two calls to \texttt{latexindent.pl} are equivalent: + You can call the \texttt{-o} switch with the name of the output file + \emph{without} an extension; in% + \announce{2017-06-25}{upgrade to -o switch} this case, \texttt{latexindent.pl} will use the extension from the + original file. For example, the following two calls to \texttt{latexindent.pl} are + equivalent: \begin{commandshell} latexindent.pl myfile.tex -o=output latexindent.pl myfile.tex -o=output.tex \end{commandshell} - You can call the \texttt{-o} switch using a \texttt{+} symbol at the beginning; this will + You can call the \texttt{-o} switch using a \texttt{+} symbol at + the beginning; this will%%% \announce{2017-06-25}{+ sign in o switch} - concatenate the name of the input file and the text given to the \texttt{-o} switch. - For example, the following two calls to \texttt{latexindent.pl} are equivalent: + concatenate the name of the input file and the text given to the \texttt{-o} + switch. For example, the following two calls to \texttt{latexindent.pl} are equivalent: \begin{commandshell} latexindent.pl myfile.tex -o=+new latexindent.pl myfile.tex -o=myfilenew.tex \end{commandshell} - You can call the \texttt{-o} switch using a \texttt{++} symbol at the end of the name - \announce{2017-06-25}{++ in o switch} - of your output file; this tells \texttt{latexindent.pl} to search successively for - the name of your output file concatenated with $0, 1, \ldots$ while the name of the - output file exists. For example, + You can call the \texttt{-o} switch using a \texttt{++} symbol at + the end of the name%%% + \announce{2017-06-25}{++ in o switch} of your output + file; this tells \texttt{latexindent.pl} to search successively for the name of your + output file concatenated with $0, 1, \ldots$ while the name of the output file + exists. For example, \begin{commandshell} latexindent.pl myfile.tex -o=output++ \end{commandshell} @@ -124,24 +130,26 @@ latexindent.pl myfile.tex -o=output++ \begin{commandshell} latexindent.pl myfile.tex -o=++ \end{commandshell} - tells it to output to \texttt{myfile0.tex}, but if it exists then output to \texttt{myfile1.tex} - and so on. + tells it to output to \texttt{myfile0.tex}, but if it exists then output to + \texttt{myfile1.tex} and so on. - The \texttt{+} and \texttt{++} feature of the \texttt{-o} switch can be combined; for example, calling + The \texttt{+} and \texttt{++} feature of the + \texttt{-o} switch can be combined; for example, calling \begin{commandshell} latexindent.pl myfile.tex -o=+out++ \end{commandshell} tells \texttt{latexindent.pl} to output to \texttt{myfileout0.tex}, but if it exists, then try \texttt{myfileout1.tex}, and so on. - There is no need to specify a file extension when using the \texttt{++} feature, but if you wish to, - then you should include it \emph{after} the \texttt{++} symbols, for example + There is no need to specify a file extension when using the \texttt{++} + feature, but if you wish to, then you should include it \emph{after} the + \texttt{++} symbols, for example \begin{commandshell} latexindent.pl myfile.tex -o=+out++.tex \end{commandshell} - See \vref{app:differences} for details of how the interface has changed - from Version 2.2 to Version 3.0 for this flag. + See \vref{app:differences} for details of how the interface has changed from Version 2.2 + to Version 3.0 for this flag. \flagbox{-s, --silent} \begin{commandshell} latexindent.pl -s myfile.tex @@ -157,12 +165,11 @@ latexindent.pl myfile.tex -t \end{commandshell} \label{page:traceswitch} - Tracing mode: verbose output will be given to \texttt{indent.log}. This - is useful if \texttt{latexindent.pl} has made a mistake and you're - trying to find out where and why. You might also be interested in learning - about \texttt{latexindent.pl}'s thought process -- if so, this - switch is for you, although it should be noted that, especially for large files, this does affect - performance of the script. + Tracing mode: verbose output will be given to \texttt{indent.log}. This is useful if + \texttt{latexindent.pl} has made a mistake and you're trying to find out where and why. + You might also be interested in learning about \texttt{latexindent.pl}'s thought process + -- if so, this switch is for you, although it should be noted that, especially for large + files, this does affect performance of the script. \flagbox{-tt, --ttrace} \begin{commandshell} @@ -170,9 +177,11 @@ latexindent.pl -tt myfile.tex latexindent.pl myfile.tex -tt \end{commandshell} - \emph{More detailed} tracing mode: this option gives more details to \texttt{indent.log} - than the standard \texttt{trace} option (note that, even more so than with \texttt{-t}, - especially for large files, performance of the script will be affected). + \emph{More detailed} tracing mode: this option gives more details to + \texttt{indent.log} + than the standard \texttt{trace} option (note that, even more so than with + \texttt{-t}, especially for large files, performance of the script will be + affected). \flagbox{-l, --local[=myyaml.yaml,other.yaml,...]} \begin{commandshell} @@ -186,26 +195,29 @@ latexindent.pl myfile.tex -l=first.yaml,second.yaml,third.yaml \label{page:localswitch} \texttt{latexindent.pl} will always load \texttt{defaultSettings.yaml} (rhymes with camel) - and if it is called with the \texttt{-l} switch and it finds \texttt{localSettings.yaml} - in the same directory as \texttt{myfile.tex} then these settings will be - added to the indentation scheme. Information will be given in \texttt{indent.log} on - the success or failure of loading \texttt{localSettings.yaml}. - - The \texttt{-l} flag can take an \emph{optional} parameter which details the name (or names separated by commas) of a YAML file(s) - that resides in the same directory as \texttt{myfile.tex}; you can use this option if you would - like to load a settings file in the current working directory that is \emph{not} called \texttt{localSettings.yaml}. - \announce{2017-08-21}*{-l switch absolute paths} In fact, you can specify both \emph{relative} and \emph{absolute paths} for your YAML files; - for example + and if it is called with the \texttt{-l} switch and it finds + \texttt{localSettings.yaml} in the same directory as \texttt{myfile.tex} then these + settings will be added to the indentation scheme. Information will be given in + \texttt{indent.log} on the success or failure of loading \texttt{localSettings.yaml}. + + The \texttt{-l} flag can take an \emph{optional} parameter which + details the name (or names separated by commas) of a YAML file(s) that resides in the + same directory as \texttt{myfile.tex}; you can use this option if you would like to + load a settings file in the current working directory that is \emph{not} + called \texttt{localSettings.yaml}.%%% + \announce{2017-08-21}*{-l switch absolute paths} + In fact, you can specify both \emph{relative} and \emph{absolute paths} for + your YAML files; for example \begin{commandshell} latexindent.pl -l=../../myyaml.yaml myfile.tex latexindent.pl -l=/home/cmhughes/Desktop/myyaml.yaml myfile.tex latexindent.pl -l=C:\Users\cmhughes\Desktop\myyaml.yaml myfile.tex \end{commandshell} - You will find a lot of other explicit demonstrations of how to use the \texttt{-l} switch throughout this documentation, + You will find a lot of other explicit demonstrations of how to use the + \texttt{-l} switch throughout this documentation, You can call the \texttt{-l} switch with a `+' symbol either before or after - \announce{2017-06-25}{+ sign with -l switch} - another YAML file; for example: + \announce{2017-06-25}{+ sign with -l switch} another YAML file; for example: \begin{commandshell} latexindent.pl -l=+myyaml.yaml myfile.tex latexindent.pl -l "+ myyaml.yaml" myfile.tex @@ -225,8 +237,9 @@ latexindent.pl -l+myyaml.yaml myfile.tex \begin{commandshell} latexindent.pl -l + myyaml.yaml myfile.tex \end{commandshell} - will \emph{only} load \texttt{localSettings.yaml}, and \texttt{myyaml.yaml} will be ignored. If you wish - to use spaces between any of the YAML settings, then you must wrap the entire list of YAML files in quotes, as demonstrated above. + will \emph{only} load \texttt{localSettings.yaml}, and \texttt{myyaml.yaml} + will be ignored. If you wish to use spaces between any of the YAML settings, then you + must wrap the entire list of YAML files in quotes, as demonstrated above. You may also choose to omit the \texttt{yaml} extension, such as \announce{2017-06-25}{no extension for -l switch} @@ -242,36 +255,39 @@ latexindent.pl myfile.tex -y='modifyLineBreaks:environments:EndStartsOnOwnLine:3 latexindent.pl myfile.tex -y='modifyLineBreaks:environments:one:EndStartsOnOwnLine:3' -m \end{commandshell} \label{page:yamlswitch}You% - \announce{2017-08-21}{the -y switch} can specify YAML settings from the command line using the \texttt{-y} or \texttt{--yaml} switch; - sample demonstrations are given above. Note, in particular, that multiple settings can be specified by separating them - via commas. There is a further option to use a \texttt{;} to separate fields, which is demonstrated in \vref{sec:yamlswitch}. - - Any settings specified via this switch will be loaded \emph{after} - any specified using the \texttt{-l} switch. This is discussed further in \vref{sec:loadorder}. + \announce{2017-08-21}{the -y switch} can specify YAML settings from the command line using the + \texttt{-y} or \texttt{--yaml} switch; + sample demonstrations are given above. Note, in particular, that multiple settings can + be specified by separating them via commas. There is a further option to use a + \texttt{;} to separate fields, which is demonstrated in + \vref{sec:yamlswitch}. + + Any settings specified via this switch will be loaded \emph{after} any + specified using the \texttt{-l} switch. This is discussed further in + \vref{sec:loadorder}. \flagbox{-d, --onlydefault} \begin{commandshell} latexindent.pl -d myfile.tex \end{commandshell} - Only \texttt{defaultSettings.yaml}: you might like to read \cref{sec:defuseloc} before - using this switch. By default, \texttt{latexindent.pl} will always search for - \texttt{indentconfig.yaml} or \texttt{.indentconfig.yaml} in your home directory. If you would prefer it not to do so - then (instead of deleting or renaming \texttt{indentconfig.yaml} or \texttt{.indentconfig.yaml}) you can simply - call the script with the \texttt{-d} switch; note that this will also tell - the script to ignore \texttt{localSettings.yaml} even if it has been called with the - \texttt{-l} switch; \texttt{latexindent.pl}% - \announce{2017-08-21}*{updated -d switch} will also ignore any settings specified - from the \texttt{-y} switch. + Only \texttt{defaultSettings.yaml}: you might like to read \cref{sec:defuseloc} before using + this switch. By default, \texttt{latexindent.pl} will always search for + \texttt{indentconfig.yaml} or \texttt{.indentconfig.yaml} in your home directory. If you would + prefer it not to do so then (instead of deleting or renaming \texttt{indentconfig.yaml} or + \texttt{.indentconfig.yaml}) you can simply call the script with the \texttt{-d} + switch; note that this will also tell the script to ignore \texttt{localSettings.yaml} even + if it has been called with the \texttt{-l} switch; \texttt{latexindent.pl}% + \announce{2017-08-21}*{updated -d switch} will also ignore any settings specified from the + \texttt{-y} switch. \flagbox{-c, --cruft=} \begin{commandshell} latexindent.pl -c=/path/to/directory/ myfile.tex \end{commandshell} - If you wish to have backup files and \texttt{indent.log} written to a directory - other than the current working directory, then you can send these `cruft' files - to another directory. - % this switch was made as a result of http://tex.stackexchange.com/questions/142652/output-latexindent-auxiliary-files-to-a-different-directory + If you wish to have backup files and \texttt{indent.log} written to a directory other + than the current working directory, then you can send these `cruft' files to another + directory. % 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=} \begin{commandshell} @@ -281,17 +297,19 @@ latexindent.pl --logfile other.log myfile.tex latexindent.pl myfile.tex -g other.log \end{commandshell} - By default, \texttt{latexindent.pl} reports information to \texttt{indent.log}, but if you wish to change the - name of this file, simply call the script with your chosen name after the \texttt{-g} switch as demonstrated above. + By default, \texttt{latexindent.pl} reports information to \texttt{indent.log}, but + if you wish to change the name of this file, simply call the script with your chosen name + after the \texttt{-g} switch as demonstrated above. \flagbox{-sl, --screenlog} \begin{commandshell} latexindent.pl -sl myfile.tex latexindent.pl -screenlog myfile.tex \end{commandshell} - Using this% - \announce{2018-01-13}{screenlog switch created} option tells \texttt{latexindent.pl} to output the log file to the screen, as well - as to your chosen log file. + Using this%%%% + \announce{2018-01-13}{screenlog switch created} option tells + \texttt{latexindent.pl} to output the log file to the screen, as well as to your chosen + log file. \flagbox{-m, --modifylinebreaks} \begin{commandshell} @@ -299,29 +317,30 @@ latexindent.pl -m myfile.tex latexindent.pl -modifylinebreaks myfile.tex \end{commandshell} - One of the most exciting developments in Version~3.0 is the ability to modify line breaks; for full details - see \vref{sec:modifylinebreaks} + One of the most exciting developments in Version~3.0 is the ability to modify line + breaks; for full details see \vref{sec:modifylinebreaks} \texttt{latexindent.pl} can also be called on a file without the file extension, for example \begin{commandshell} latexindent.pl myfile \end{commandshell} - and in which case, you can specify - the order in which extensions are searched for; see \vref{lst:fileExtensionPreference} - for full details. + and in which case, you can specify the order in which extensions are searched for; see + \vref{lst:fileExtensionPreference} for full details. \flagbox{STDIN} \begin{commandshell} cat myfile.tex | latexindent.pl \end{commandshell} \texttt{latexindent.pl} will% \announce{2018-01-13}{STDIN allowed} allow input from STDIN, which means that you can pipe output from - other commands directly into the script. For example assuming that you have content in \texttt{myfile.tex}, then the above - command will output the results of operating upon \texttt{myfile.tex} - - Similarly, if you% - \announce{2018-01-13}*{no options/filename updated} simply type \texttt{latexindent.pl} - at the command line, then it will expect (STDIN) input from the command line. + other commands directly into the script. For example assuming that you have content in + \texttt{myfile.tex}, then the above command will output the results of operating upon + \texttt{myfile.tex} + + Similarly, if you%%%% + \announce{2018-01-13}*{no options/filename updated} simply type + \texttt{latexindent.pl} at the command line, then it will expect (STDIN) input from the + command line. \begin{commandshell} latexindent.pl \end{commandshell} @@ -331,41 +350,10 @@ latexindent.pl \item \texttt{CTRL+D} on Linux \item \texttt{CTRL+Z} followed by \texttt{ENTER} on Windows \end{itemize} - to signify that your input has finished. + to signify that your input has finished. Thanks to \cite{xu-cheng} for an update + to this feature. \subsection{From arara}\label{sec:arara} - Using \texttt{latexindent.pl} from the command line is fine for some folks, but - others may find it easier to use from \texttt{arara}; you can find the arara rule at \cite{paulo}. - - You can use the rule in any of the ways described in \cref{lst:arara} (or combinations thereof). - In fact, \texttt{arara} allows yet greater flexibility -- you can use \texttt{yes/no}, \texttt{true/false}, or \texttt{on/off} to toggle the various options. - - \cmhlistingsfromfile{demonstrations/arara-demo.tex}{\texttt{arara} sample usage}{lst:arara} - - Hopefully the use of these rules is fairly self-explanatory, but for completeness - \cref{tab:orbsandswitches} shows the relationship between \texttt{arara} directive arguments and the - switches given in \cref{sec:commandline}. - - \begin{table}[!ht] - \centering - \caption{\texttt{arara} directive arguments and corresponding switches} - \label{tab:orbsandswitches} - \begin{tabular}{lc} - \toprule - \texttt{arara} directive argument & switch \\ - \midrule - \texttt{overwrite} & \texttt{-w} \\ - \texttt{output} & \texttt{-o} \\ - \texttt{silent} & \texttt{-s} \\ - \texttt{trace} & \texttt{-t} \\ - \texttt{localSettings} & \texttt{-l} \\ - \texttt{onlyDefault} & \texttt{-d} \\ - \texttt{cruft} & \texttt{-c} \\ - %\texttt{modifylinebreaks} & \texttt{-m} \\ - \bottomrule - \end{tabular} - \end{table} - - The \texttt{cruft} directive does not work well when used with - directories that contain spaces. - + Using \texttt{latexindent.pl} from the command line is fine for some folks, but others + may find it easier to use from \texttt{arara}; you can find the arara rule for + \texttt{latexindent.pl} and its associated documentation at \cite{paulo}. 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 db5f61621ee..f69fda83dee 100644 --- a/Master/texmf-dist/doc/support/latexindent/sec-indent-config-and-settings.tex +++ b/Master/texmf-dist/doc/support/latexindent/sec-indent-config-and-settings.tex @@ -1,28 +1,28 @@ % arara: pdflatex: {shell: yes, files: [latexindent]} \section{indentconfig.yaml, local settings and the -y switch }\label{sec:indentconfig} - The behaviour of \texttt{latexindent.pl} is controlled from the settings specified - in any of the YAML files that you tell it to load. By default, \texttt{latexindent.pl} - will only load \texttt{defaultSettings.yaml}, but there are a few ways that you can - tell it to load your own settings files. + The behaviour of \texttt{latexindent.pl} is controlled from the settings specified in any + of the YAML files that you tell it to load. By default, \texttt{latexindent.pl} will only + load \texttt{defaultSettings.yaml}, but there are a few ways that you can tell it to load your + own settings files. \subsection{indentconfig.yaml and .indentconfig.yaml} \texttt{latexindent.pl} will always check your home directory for \texttt{indentconfig.yaml} and \texttt{.indentconfig.yaml} (unless - it is called with the \texttt{-d} switch), - which is a plain text file you can create that contains the \emph{absolute} - paths for any settings files that you wish \texttt{latexindent.pl} to load. There is no difference - between \texttt{indentconfig.yaml} and \texttt{.indentconfig.yaml}, other than the - fact that \texttt{.indentconfig.yaml} is a `hidden' file; thank you to \cite{jacobo-diaz-hidden-config} - for providing this feature. In what follows, we will use \texttt{indentconfig.yaml}, but it - is understood that this could equally represent \texttt{.indentconfig.yaml}. If you - have both files in existence then \texttt{indentconfig.yaml} takes priority. - - For Mac and Linux users, their home directory is \texttt{~/username} while - Windows (Vista onwards) is \lstinline!C:\Users\username!\footnote{If you're not sure + it is called with the \texttt{-d} switch), which is a plain text file you can create that contains the + \emph{absolute} paths for any settings files that you wish \texttt{latexindent.pl} + to load. There is no difference between \texttt{indentconfig.yaml} and + \texttt{.indentconfig.yaml}, other than the fact that \texttt{.indentconfig.yaml} is a `hidden' + file; thank you to \cite{jacobo-diaz-hidden-config} for providing this feature. In what follows, we + will use \texttt{indentconfig.yaml}, but it is understood that this could equally represent + \texttt{.indentconfig.yaml}. If you have both files in existence then \texttt{indentconfig.yaml} + takes priority. + + For Mac and Linux users, their home directory is \texttt{~/username} while Windows + (Vista onwards) is \lstinline!C:\Users\username!\footnote{If you're not sure where to put \texttt{indentconfig.yaml}, don't worry \texttt{latexindent.pl} will tell you in the log file exactly where to - put it assuming it doesn't exist already.} - \Cref{lst:indentconfig} shows a sample \texttt{indentconfig.yaml} file. + put it assuming it doesn't exist already.} \Cref{lst:indentconfig} + shows a sample \texttt{indentconfig.yaml} file. \begin{yaml}{\texttt{indentconfig.yaml} (sample)}{lst:indentconfig} # Paths to user settings for latexindent.pl @@ -39,20 +39,19 @@ paths: - C:\Users\chughes\Desktop\test spaces\more spaces.yaml \end{yaml} - Note that the \texttt{.yaml} files you specify in \texttt{indentconfig.yaml} - will be loaded in the order in which you write them. Each file doesn't have - to have every switch from \texttt{defaultSettings.yaml}; in fact, I recommend - that you only keep the switches that you want to \emph{change} in these - settings files. + Note that the \texttt{.yaml} files you specify in \texttt{indentconfig.yaml} will be + loaded in the order in which you write them. Each file doesn't have to have every switch + from \texttt{defaultSettings.yaml}; in fact, I recommend that you only keep the switches that + you want to \emph{change} in these settings files. To get started with your own settings file, you might like to save a copy of - \texttt{defaultSettings.yaml} in another directory and call it, for - example, \texttt{mysettings.yaml}. Once you have added the path to \texttt{indentconfig.yaml} - you can change the switches and add more code-block names to it - as you see fit -- have a look at \cref{lst:mysettings} for an example - that uses four tabs for the default indent, adds the \texttt{tabbing} - environment/command to the list of environments that contains alignment delimiters; you might also like to - refer to the many YAML files detailed throughout the rest of this documentation. + \texttt{defaultSettings.yaml} in another directory and call it, for example, + \texttt{mysettings.yaml}. Once you have added the path to \texttt{indentconfig.yaml} you can + change the switches and add more code-block names to it as you see fit -- have a look at + \cref{lst:mysettings} for an example that uses four tabs for the default indent, adds + the \texttt{tabbing} environment/command to the list of environments that contains + alignment delimiters; you might also like to refer to the many YAML files detailed + throughout the rest of this documentation. \begin{yaml}{\texttt{mysettings.yaml} (example)}{lst:mysettings} # Default value of indentation @@ -64,10 +63,10 @@ lookForAlignDelims: tabbing: 1 \end{yaml} - You can make sure that your settings are loaded by checking \texttt{indent.log} - for details -- if you have specified a path that \texttt{latexindent.pl} doesn't - recognize then you'll get a warning, otherwise you'll get confirmation that - \texttt{latexindent.pl} has read your settings file \footnote{Windows users + You can make sure that your settings are loaded by checking \texttt{indent.log} for + details -- if you have specified a path that \texttt{latexindent.pl} doesn't recognize + then you'll get a warning, otherwise you'll get confirmation that \texttt{latexindent.pl} + has read your settings file \footnote{Windows users may find that they have to end \texttt{.yaml} files with a blank line}. \begin{warning} @@ -81,26 +80,29 @@ lookForAlignDelims: \end{warning} \subsection{localSettings.yaml}\label{sec:localsettings} - The \texttt{-l} switch tells \texttt{latexindent.pl} to look for \texttt{localSettings.yaml} in the - \emph{same directory} as \texttt{myfile.tex}. For example, if you use the following command + The \texttt{-l} switch tells \texttt{latexindent.pl} to look for + \texttt{localSettings.yaml} in the \emph{same directory} as \texttt{myfile.tex}. For + example, if you use the following command \begin{commandshell} latexindent.pl -l myfile.tex \end{commandshell} - then \texttt{latexindent.pl} will (assuming it exists) load \texttt{localSettings.yaml} from the same directory - as \texttt{myfile.tex}. + then \texttt{latexindent.pl} will (assuming it exists) load \texttt{localSettings.yaml} from + the same directory as \texttt{myfile.tex}. - If you'd prefer to name your \texttt{localSettings.yaml} file something - different, (say, \texttt{mysettings.yaml} as in \cref{lst:mysettings}) then - you can call \texttt{latexindent.pl} using, for example, + If you'd prefer to name your \texttt{localSettings.yaml} file something different, (say, + \texttt{mysettings.yaml} as in \cref{lst:mysettings}) then you can call + \texttt{latexindent.pl} using, for example, \begin{commandshell} latexindent.pl -l=mysettings.yaml myfile.tex \end{commandshell} - Any settings file(s) specified using the \texttt{-l} switch will be read \emph{after} \texttt{defaultSettings.yaml} and, assuming they exist, - any user setting files specified in \texttt{indentconfig.yaml}. + Any settings file(s) specified using the \texttt{-l} switch will be read + \emph{after} \texttt{defaultSettings.yaml} and, assuming they exist, any user setting + files specified in \texttt{indentconfig.yaml}. - Your settings file can contain any switches that you'd - like to change; a sample is shown in \cref{lst:localSettings}, and you'll find plenty of further examples throughout this manual. + Your settings file can contain any switches that you'd like to change; a sample is shown + in \cref{lst:localSettings}, and you'll find plenty of further examples throughout this + manual. \begin{yaml}{\texttt{localSettings.yaml} (example)}{lst:localSettings} # verbatim environments - environments specified @@ -110,43 +112,50 @@ verbatimEnvironments: myenv: 1 \end{yaml} - You can make sure that your settings file has been loaded by checking \texttt{indent.log} - for details; if it can not be read then you receive a warning, otherwise you'll get confirmation that - \texttt{latexindent.pl} has read your settings file. + You can make sure that your settings file has been loaded by checking + \texttt{indent.log} for details; if it can not be read then you receive a warning, + otherwise you'll get confirmation that \texttt{latexindent.pl} has read your settings + file. \subsection{The -y|yaml switch}\label{sec:yamlswitch} - You% - \announce{2017-08-21}{demonstration of the -y switch} may use the \texttt{-y} switch to load - your settings; for example, if you wished to specify the settings from \cref{lst:localSettings} - using the \texttt{-y} switch, then you could use the following command: + You%%%% + \announce{2017-08-21}{demonstration of the -y switch} may use the + \texttt{-y} switch to load your settings; for example, if you wished to + specify the settings from \cref{lst:localSettings} using the \texttt{-y} switch, + then you could use the following command: \begin{commandshell} latexindent.pl -y="verbatimEnvironments:cmhenvironment:0;myenv:1" myfile.tex \end{commandshell} - Note the use of \texttt{;} to specify another field within \texttt{verbatimEnvironments}. This is - shorthand, and equivalent, to using the following command: + Note the use of \texttt{;} to specify another field within + \texttt{verbatimEnvironments}. This is shorthand, and equivalent, to using the following + command: \begin{commandshell} latexindent.pl -y="verbatimEnvironments:cmhenvironment:0,verbatimEnvironments:myenv:1" myfile.tex \end{commandshell} - You may, of course, specify settings using the \texttt{-y} switch as well as, for example, - settings loaded using the \texttt{-l} switch; for example, + You may, of course, specify settings using the \texttt{-y} switch as well as, + for example, settings loaded using the \texttt{-l} switch; for example, \begin{commandshell} latexindent.pl -l=mysettings.yaml -y="verbatimEnvironments:cmhenvironment:0;myenv:1" myfile.tex \end{commandshell} - Any settings specified using the \texttt{-y} switch will be loaded \emph{after} any specified - using \texttt{indentconfig.yaml} and the \texttt{-l} switch. + Any settings specified using the \texttt{-y} switch will be loaded + \emph{after} any specified using \texttt{indentconfig.yaml} and the + \texttt{-l} switch. \subsection{Settings load order}\label{sec:loadorder} \texttt{latexindent.pl} loads the settings files in the following order: \begin{enumerate} \item \texttt{defaultSettings.yaml} is always loaded, and can not be renamed; - \item \texttt{anyUserSettings.yaml} and any other arbitrarily-named files specified in \texttt{indentconfig.yaml}; - \item \texttt{localSettings.yaml} but only if found in the same directory as \texttt{myfile.tex} and called - with \texttt{-l} switch; this file can be renamed, provided that the call to \texttt{latexindent.pl} is adjusted - accordingly (see \cref{sec:localsettings}). You may specify both relative and absolute% - \announce{2017-08-21}*{-l absolute paths} paths to other - YAML files using the \texttt{-l} switch, separating multiple files using commas; - \item any settings% - \announce{2017-08-21}{-y switch load order} specified in the \texttt{-y} switch. + \item \texttt{anyUserSettings.yaml} and any other arbitrarily-named files specified in + \texttt{indentconfig.yaml}; + \item \texttt{localSettings.yaml} but only if found in the same directory as \texttt{myfile.tex} + and called with \texttt{-l} switch; this file can be renamed, provided that + the call to \texttt{latexindent.pl} is adjusted accordingly (see \cref{sec:localsettings}). + You may specify both relative and absolute%% + \announce{2017-08-21}*{-l absolute paths} paths to other YAML files using the \texttt{-l} switch, + separating multiple files using commas; + \item any settings%%%% + \announce{2017-08-21}{-y switch load order} specified in the + \texttt{-y} switch. \end{enumerate} A visual representation of this is given in \cref{fig:loadorder}. diff --git a/Master/texmf-dist/doc/support/latexindent/sec-introduction.tex b/Master/texmf-dist/doc/support/latexindent/sec-introduction.tex index 453851d7383..c869b84596e 100644 --- a/Master/texmf-dist/doc/support/latexindent/sec-introduction.tex +++ b/Master/texmf-dist/doc/support/latexindent/sec-introduction.tex @@ -1,44 +1,45 @@ % arara: pdflatex: {shell: yes, files: [latexindent]} \section{Introduction} \subsection{Thanks} - I first created \texttt{latexindent.pl} to help me format chapter files - in a big project. After I blogged about it on the - \TeX{} stack exchange \cite{cmhblog} I received some positive feedback and - follow-up feature requests. A big thank you to Harish Kumar \cite{harish} who - helped to develop and test the initial versions of the script. + I first created \texttt{latexindent.pl} to help me format chapter files in a big project. + After I blogged about it on the \TeX{} stack exchange + \cite{cmhblog} I received some positive feedback and follow-up feature requests. + A big thank you to Harish Kumar \cite{harish} who helped to develop and test the + initial versions of the script. - The \texttt{YAML}-based interface of \texttt{latexindent.pl} was inspired - by the wonderful \texttt{arara} tool; any similarities are deliberate, and - I hope that it is perceived as the compliment that it is. Thank you to Paulo Cereda and the - team for releasing this awesome tool; I initially worried that I was going to - have to make a GUI for \texttt{latexindent.pl}, but the release of \texttt{arara} - has meant there is no need. + The \texttt{YAML}-based interface of \texttt{latexindent.pl} was inspired by the + wonderful \texttt{arara} tool; any similarities are deliberate, and I hope that + it is perceived as the compliment that it is. Thank you to Paulo Cereda and the team for + releasing this awesome tool; I initially worried that I was going to have to make a GUI + for \texttt{latexindent.pl}, but the release of \texttt{arara} has meant there is + no need. - There have been several contributors to the project so far (and hopefully more in - the future!); thank you very much to the people detailed in \vref{sec:contributors} - for their valued contributions, and thank you to those who report bugs and request features - at \cite{latexindent-home}. + There have been several contributors to the project so far (and hopefully more in the + future!); thank you very much to the people detailed in \vref{sec:contributors} for their + valued contributions, and thank you to those who report bugs and request features at + \cite{latexindent-home}. \subsection{License} \texttt{latexindent.pl} is free and open source, and it always will be; it is released under the GNU General Public License v3.0. - Before you start using it on any important files, bear in mind that \texttt{latexindent.pl} has the option to overwrite your \texttt{.tex} files. - It will always make at least one backup (you can choose how many it makes, see \cpageref{page:onlyonebackup}) - but you should still be careful when using it. The script has been tested on many - files, but there are some known limitations (see \cref{sec:knownlimitations}). - You, the user, are responsible for ensuring that you maintain backups of your files - before running \texttt{latexindent.pl} on them. I think it is important at this - stage to restate an important part of the license here: + Before you start using it on any important files, bear in mind that + \texttt{latexindent.pl} has the option to overwrite your \texttt{.tex} files. It + will always make at least one backup (you can choose how many it makes, see + \cpageref{page:onlyonebackup}) but you should still be careful when using it. The script has + been tested on many files, but there are some known limitations (see + \cref{sec:knownlimitations}). You, the user, are responsible for ensuring that you maintain + backups of your files before running \texttt{latexindent.pl} on them. I think it is + important at this stage to restate an important part of the license here: \begin{quote}\itshape 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. \end{quote} - There is certainly no malicious intent in releasing this script, and I do hope - that it 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 + There is certainly no malicious intent in releasing this script, and I do hope that it + 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 @@ -50,10 +51,10 @@ throughout this document for details}. \subsection{About this documentation} - As you read through this documentation, you will see many listings; in this version of the documentation, - there are a total of \totallstlistings. This may seem a lot, but I deem it necessary in - presenting the various different options of \texttt{latexindent.pl} and the associated output that they are capable of - producing. + As you read through this documentation, you will see many listings; in this version of + the documentation, there are a total of \totallstlistings. This may seem a lot, but I + deem it necessary in presenting the various different options of \texttt{latexindent.pl} + and the associated output that they are capable of producing. The different listings are presented using different styles: @@ -86,15 +87,17 @@ \end{minipage}% % \begin{latexonly} - You will occasionally see dates shown in the margin (for example, next to this paragraph!) - \announce{2017-06-25}{announce} which detail the date of the version in which the feature was implemented; - the `N' stands for `new as of the date shown' and `U' stands for `updated as of the date shown'. - If you see \stardemo, it - means that the feature is either new (N) or updated (U) as of the release of the current version; if you see \stardemo\, - attached to a listing, then it means that listing is new (N) or updated (U) as of the current version. If you have - not read this document before (and even if you have!), then you can ignore every occurrence of the \stardemo; - they are simply there to highlight new and updated features. - The new and updated features in this documentation (\gitRel) are on the following pages: \listOfNewFeatures + You will occasionally see dates shown in the margin (for example, next to this + paragraph!)%%% + \announce{2017-06-25}{announce} which detail the date + of the version in which the feature was implemented; the `N' stands for `new as of the + date shown' and `U' stands for `updated as of the date shown'. If you see \stardemo, it + means that the feature is either new (N) or updated (U) as of the release of the current + version; if you see \stardemo\, attached to a listing, then it means that listing is new + (N) or updated (U) as of the current version. If you have not read this document before + (and even if you have!), then you can ignore every occurrence of the \stardemo; they are + simply there to highlight new and updated features. The new and updated features in this + documentation (\gitRel) are on the following pages: \listOfNewFeatures % \end{latexonly} \subsection{Quick start}\label{sec:quickstart} @@ -102,15 +105,16 @@ \begin{commandshell} latexindent.pl myfile.tex \end{commandshell} - from the command line. If you receive an error message such as that given in \cref{lst:poss-errors}, - then you need to install the missing perl modules. + from the command line. If you receive an error message such as that given in + \cref{lst:poss-errors}, then you need to install the missing perl modules. \begin{cmhlistings}[style=tcblatex,language=Perl]{Possible error messages}{lst:poss-errors} Can't locate File/HomeDir.pm in @INC (@INC contains: /Library/Perl/5.12/darwin-thread-multi-2level /Library/Perl/5.12 /Network/Library/Perl/5.12/darwin-thread-multi-2level /Network/Library/Perl/5.12 /Library/Perl/Updates/5.12.4/darwin-thread-multi-2level /Library/Perl/Updates/5.12.4 /System/Library/Perl/5.12/darwin-thread-multi-2level /System/Library/Perl/5.12 /System/Library/Perl/Extras/5.12/darwin-thread-multi-2level /System/Library/Perl/Extras/5.12 .) at helloworld.pl line 10. BEGIN failed--compilation aborted at helloworld.pl line 10. \end{cmhlistings} - \texttt{latexindent.pl} ships with a script to help with this process; if you run the following script, you should be prompted - to install the appropriate modules. + \texttt{latexindent.pl} ships with a script to help with this process; if you run the + following script, you should be prompted to install the appropriate modules. \begin{commandshell} perl latexindent-module-installer.pl \end{commandshell} - You might also like to see \href{https://stackoverflow.com/questions/19590042/error-cant-locate-file-homedir-pm-in-inc}{https://stackoverflow.com/questions/19590042/error-cant-locate-file-homedir-pm-in-inc}, for example, as well as \vref{sec:requiredmodules}. + You might also like to see \href{https://stackoverflow.com/questions/19590042/error-cant-locate-file-homedir-pm-in-inc}{https://stackoverflow.com/questions/19590042/error-cant-locate-file-homedir-pm-in-inc}, for example, as well as + \vref{sec:requiredmodules}. 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 caed7644c67..3677af3f169 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 @@ -4,8 +4,8 @@ \node at (1,0){\includegraphics{logo}}; }} \section{The -m (modifylinebreaks) switch}\label{sec:modifylinebreaks} - All features described in this section will only be relevant if the \texttt{-m} switch - is used. + All features described in this section will only be relevant if the + \texttt{-m} switch is used. \startcontents[the-m-switch] \printcontents[the-m-switch]{}{0}{} @@ -17,15 +17,15 @@ \makebox[0pt][r]{% \raisebox{-\totalheight}[0pt][0pt]{% \tikz\node[opacity=1] at (0,0) {\includegraphics[width=4cm]{logo}};}}% - As of Version 3.0, \texttt{latexindent.pl} has the \texttt{-m} switch, which - permits \texttt{latexindent.pl} to modify line breaks, according to the + As of Version 3.0, \texttt{latexindent.pl} has the \texttt{-m} + switch, which permits \texttt{latexindent.pl} to modify line breaks, according to the specifications in the \texttt{modifyLineBreaks} field. \emph{The settings - in this field will only be considered if the \texttt{-m} switch has been used}. - A snippet of the default settings of this field is shown in \cref{lst:modifylinebreaks}. + in this field will only be considered if the \texttt{-m} switch has been used}. A + snippet of the default settings of this field is shown in \cref{lst:modifylinebreaks}. - 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: + 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: \begin{warning} If you call \texttt{latexindent.pl} with the \texttt{-m} switch, then you @@ -35,21 +35,23 @@ \end{warning} \yamltitle{preserveBlankLines}{0|1} - This field is directly related to \emph{poly-switches}, discussed below. - By default, it is set to \texttt{1}, which means that blank lines will - be protected from removal; however, regardless of this setting, multiple - blank lines can be condensed if \texttt{condenseMultipleBlankLinesInto} is - greater than \texttt{0}, discussed next. + This field is directly related to \emph{poly-switches}, discussed below. By + default, it is set to \texttt{1}, which means that blank lines will be + protected from removal; however, regardless of this setting, multiple blank lines can be + condensed if \texttt{condenseMultipleBlankLinesInto} is greater than \texttt{0}, + discussed next. \yamltitle{condenseMultipleBlankLinesInto}*{positive integer} - Assuming that this switch takes an integer value greater than \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 + Assuming that this switch takes an integer value greater than + \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 \begin{commandshell} latexindent.pl myfile.tex -m \end{commandshell} - the output is shown in \cref{lst:mlb-bl-out}; note that the multiple blank lines have been - condensed into one blank line, and note also that we have used the \texttt{-m} switch! + the output is shown in \cref{lst:mlb-bl-out}; note that the multiple blank lines + have been condensed into one blank line, and note also that we have used the + \texttt{-m} switch! \begin{minipage}{.45\textwidth} \cmhlistingsfromfile{demonstrations/mlb1.tex}{\texttt{mlb1.tex}}{lst:mlb-bl} @@ -59,14 +61,16 @@ latexindent.pl myfile.tex -m \cmhlistingsfromfile{demonstrations/mlb1-out.tex}{\texttt{mlb1.tex} out output}{lst:mlb-bl-out} \end{minipage} -\yamltitle{textWrapOptions}*{fields} - When the \texttt{-m} switch is active \texttt{latexindent.pl} has the ability to wrap text using the options - \announce{2017-05-27}{textWrapOptions} - specified in the \texttt{textWrapOptions} field, see \cref{lst:textWrapOptions}. The value of - \texttt{columns} specifies the column at which the text should be wrapped. - By default, the value of \texttt{columns} is \texttt{0}, so \texttt{latexindent.pl} - 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. +\subsection{textWrapOptions: modifying line breaks by text wrapping}\label{subsec:textwrapping} + When the \texttt{-m} switch is active \texttt{latexindent.pl} has the + ability to wrap text using the options% + \announce{2017-05-27}{textWrapOptions} specified in the \texttt{textWrapOptions} field, see + \cref{lst:textWrapOptions}. The value of \texttt{columns} specifies the + column at which the text should be wrapped. By default, the value of + \texttt{columns} is \texttt{0}, so + \texttt{latexindent.pl} 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. \cmhlistingsfromfile[style=textWrapOptions]*{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{textWrapOptions}}{lst:textWrapOptions} @@ -76,7 +80,8 @@ latexindent.pl myfile.tex -m \cmhlistingsfromfile{demonstrations/textwrap1.tex}{\texttt{textwrap1.tex}}{lst:textwrap1} \end{widepage} - Using the file \texttt{textwrap1.yaml} in \cref{lst:textwrap1-yaml}, and running the command + Using the file \texttt{textwrap1.yaml} in \cref{lst:textwrap1-yaml}, and running + the command \begin{commandshell} latexindent.pl -m textwrap1.tex -o textwrap1-mod1.tex -l textwrap1.yaml \end{commandshell} @@ -90,13 +95,14 @@ latexindent.pl -m textwrap1.tex -o textwrap1-mod1.tex -l textwrap1.yaml \cmhlistingsfromfile{demonstrations/textwrap1.yaml}[MLB-TCB]{\texttt{textwrap1.yaml}}{lst:textwrap1-yaml} \end{minipage} - 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}, + 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}, \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}, + and running the following command and continuing to use \texttt{textwrap1.yaml} from + \cref{lst:textwrap1-yaml}, \begin{commandshell} latexindent.pl -m textwrap2.tex -o textwrap2-mod1.tex -l textwrap1.yaml \end{commandshell} @@ -105,11 +111,13 @@ latexindent.pl -m textwrap2.tex -o textwrap2-mod1.tex -l textwrap1.yaml \cmhlistingsfromfile{demonstrations/textwrap2-mod1.tex}{\texttt{textwrap2-mod1.tex}}{lst:textwrap2-mod1} \end{widepage} Furthermore, the text wrapping routine is performed after the trailing comments have been - stored, and they are also exempt from text wrapping. For example, using the file in \cref{lst:textwrap3} + stored, and they are also exempt from text wrapping. For example, using the file in + \cref{lst:textwrap3} \begin{widepage} \cmhlistingsfromfile{demonstrations/textwrap3.tex}{\texttt{textwrap3.tex}}{lst:textwrap3} \end{widepage} - and running the following command and continuing to use \texttt{textwrap1.yaml} from \cref{lst:textwrap1-yaml}, + and running the following command and continuing to use \texttt{textwrap1.yaml} from + \cref{lst:textwrap1-yaml}, \begin{commandshell} latexindent.pl -m textwrap3.tex -o textwrap3-mod1.tex -l textwrap1.yaml \end{commandshell} @@ -117,17 +125,17 @@ latexindent.pl -m textwrap3.tex -o textwrap3-mod1.tex -l textwrap1.yaml \cmhlistingsfromfile{demonstrations/textwrap3-mod1.tex}{\texttt{textwrap3-mod1.tex}}{lst:textwrap3-mod1} - \begin{wrapfigure}[6]{r}[0pt]{8cm} - \cmhlistingsfromfile[style=textWrapOptionsAll]*{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{textWrapOptions}}{lst:textWrapOptionsAll} - \end{wrapfigure} - The text wrapping routine of \texttt{latexindent.pl} is performed by the \texttt{Text::Wrap} module, which provides a - \texttt{separator} feature to separate lines with characters other than a new line (see \cite{textwrap}). By default, - the separator is empty (see \cref{lst:textWrapOptionsAll}) which means that a new line token will be used, but you can change it as you see fit. + The text wrapping routine of \texttt{latexindent.pl} is performed by the + \texttt{Text::Wrap} module, which provides a \texttt{separator} feature + to separate lines with characters other than a new line (see + \cite{textwrap}). By default, the separator is empty which means that a new + line token will be used, but you can change it as you see fit. For example starting with the file in \cref{lst:textwrap4} \cmhlistingsfromfile{demonstrations/textwrap4.tex}{\texttt{textwrap4.tex}}{lst:textwrap4} - and using \texttt{textwrap2.yaml} from \cref{lst:textwrap2-yaml} with the following command + and using \texttt{textwrap2.yaml} from \cref{lst:textwrap2-yaml} with the following + command \begin{commandshell} latexindent.pl -m textwrap4.tex -o textwrap4-mod2.tex -l textwrap2.yaml \end{commandshell} @@ -141,31 +149,233 @@ latexindent.pl -m textwrap4.tex -o textwrap4-mod2.tex -l textwrap2.yaml \cmhlistingsfromfile{demonstrations/textwrap2.yaml}[MLB-TCB]{\texttt{textwrap2.yaml}}{lst:textwrap2-yaml} \end{minipage} - \textbf{Summary of text wrapping} +\subsubsection{text wrapping on a per-code-block basis} + By default, if the value of \texttt{columns} is greater than 0 and the + \texttt{-m} switch is active, then% + \announce*{2018-08-13}*{updates to textWrapOptions} the text wrapping routine will operate before the code blocks + have been searched for. This behaviour is customisable; in particular, you can instead + 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. + + The full details of \texttt{textWrapOptions} are shown in \cref{lst:textWrapOptionsAll}. + In particular, note the field \texttt{perCodeBlockBasis: 0}. + + \cmhlistingsfromfile*[style=textWrapOptionsAll]*{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{textWrapOptions}}{lst:textWrapOptionsAll} + + The code blocks detailed in \cref{lst:textWrapOptionsAll} are with direct reference to + those detailed in \vref{tab:code-blocks}. The only special case is the + \texttt{masterDocument} field; this is designed for `chapter'-type files that may + contain paragraphs that are not within any other code-blocks. The same notation is used + between this feature and the \texttt{removeParagraphLineBreaks} described in + \vref{lst:removeParagraphLineBreaks}; in fact, the two features can even be combined (this is + detailed in \vref{subsec:removeparagraphlinebreaks:and:textwrap}). + + Let's explore these switches with reference to the code given in + \cref{lst:textwrap5}; the text outside of the environment is considered part of + the \texttt{masterDocument}. + + \begin{widepage} + \cmhlistingsfromfile*{demonstrations/textwrap5.tex}{\texttt{textwrap5.tex}}{lst:textwrap5} + \end{widepage} + + With reference to this codeblock, the settings given in \cref{lst:textwrap3-yaml,lst:textwrap4-yaml,lst:textwrap5-yaml} each + give the same output. + + \begin{adjustwidth}{-3.5cm}{-2.5cm} + \begin{minipage}{.33\linewidth} + \cmhlistingsfromfile*{demonstrations/textwrap3.yaml}[MLB-TCB]{\texttt{textwrap3.yaml}}{lst:textwrap3-yaml} + \end{minipage}% + \begin{minipage}{.33\linewidth} + \cmhlistingsfromfile*{demonstrations/textwrap4.yaml}[MLB-TCB]{\texttt{textwrap4.yaml}}{lst:textwrap4-yaml} + \end{minipage}% + \begin{minipage}{.33\linewidth} + \cmhlistingsfromfile*{demonstrations/textwrap5.yaml}[MLB-TCB]{\texttt{textwrap5.yaml}}{lst:textwrap5-yaml} + \end{minipage} + \end{adjustwidth} + + Let's explore the similarities and differences in the equivalent (with respect to + \cref{lst:textwrap5}) syntax specified in \cref{lst:textwrap3-yaml,lst:textwrap4-yaml,lst:textwrap5-yaml}: + \begin{itemize} + \item in each of \cref{lst:textwrap3-yaml,lst:textwrap4-yaml,lst:textwrap5-yaml} notice that \texttt{columns: 30}; + \item in each of \cref{lst:textwrap3-yaml,lst:textwrap4-yaml,lst:textwrap5-yaml} notice that \texttt{perCodeBlockBasis: 1}; + \item in \cref{lst:textwrap3-yaml} we have specified \texttt{all: 1} so that the + text wrapping will operate upon \emph{all} code blocks; + \item in \cref{lst:textwrap4-yaml} we have \emph{not} specified + \texttt{all}, and instead, have specified that text wrapping should be + applied to each of \texttt{environments} and \texttt{masterDocument}; + \item in \cref{lst:textwrap5-yaml} we have specified text wrapping for + \texttt{masterDocument} and on a \emph{per-name} basis for + \texttt{environments} code blocks. + \end{itemize} + + Upon running the following commands + \begin{commandshell} +latexindent.pl -s textwrap5.tex -l=textwrap3.yaml -m +latexindent.pl -s textwrap5.tex -l=textwrap4.yaml -m +latexindent.pl -s textwrap5.tex -l=textwrap5.yaml -m + \end{commandshell} + we obtain the output shown in \cref{lst:textwrap5-mod3}. + + \cmhlistingsfromfile*{demonstrations/textwrap5-mod3.tex}{\texttt{textwrap5-mod3.tex}}{lst:textwrap5-mod3} + + We can explore the idea of per-name text wrapping given in \cref{lst:textwrap5-yaml} by + using \cref{lst:textwrap6}. + + \begin{widepage} + \cmhlistingsfromfile*{demonstrations/textwrap6.tex}{\texttt{textwrap6.tex}}{lst:textwrap6} + \end{widepage} + + In particular, upon running + \begin{commandshell} +latexindent.pl -s textwrap6.tex -l=textwrap5.yaml -m + \end{commandshell} + we obtain the output given in \cref{lst:textwrap6-mod5}. + + \begin{widepage} + \cmhlistingsfromfile*{demonstrations/textwrap6-mod5.tex}{\texttt{textwrap6.tex} using \cref{lst:textwrap5-yaml}}{lst:textwrap6-mod5} + \end{widepage} + + Notice that, because \texttt{environments} has been specified only for + \texttt{myenv} (in \cref{lst:textwrap5-yaml}) that the environment named \texttt{another} has + \emph{not} had text wrapping applied to it. + + The {all} field can be specified with exceptions which can either + be done on a per-code-block or per-name basis; we explore this in relation to + \cref{lst:textwrap6} in the settings given in \crefrange{lst:textwrap6-yaml}{lst:textwrap8-yaml}. + + \begin{adjustwidth}{-3.5cm}{-2.5cm} + \begin{minipage}{.33\linewidth} + \cmhlistingsfromfile*{demonstrations/textwrap6.yaml}[MLB-TCB]{\texttt{textwrap6.yaml}}{lst:textwrap6-yaml} + \end{minipage}% + \begin{minipage}{.33\linewidth} + \cmhlistingsfromfile*{demonstrations/textwrap7.yaml}[MLB-TCB]{\texttt{textwrap7.yaml}}{lst:textwrap7-yaml} + \end{minipage}% + \begin{minipage}{.33\linewidth} + \cmhlistingsfromfile*{demonstrations/textwrap8.yaml}[MLB-TCB]{\texttt{textwrap8.yaml}}{lst:textwrap8-yaml} + \end{minipage} + \end{adjustwidth} + + Upon running the commands + \begin{commandshell} +latexindent.pl -s textwrap6.tex -l=textwrap6.yaml -m +latexindent.pl -s textwrap6.tex -l=textwrap7.yaml -m +latexindent.pl -s textwrap6.tex -l=textwrap8.yaml -m + \end{commandshell} + we receive the respective output given in \crefrange{lst:textwrap6-mod6}{lst:textwrap6-mod8}. + \begin{widepage} + \cmhlistingsfromfile*{demonstrations/textwrap6-mod6.tex}{\texttt{textwrap6.tex} using \cref{lst:textwrap6-yaml}}{lst:textwrap6-mod6} + + \cmhlistingsfromfile*{demonstrations/textwrap6-mod7.tex}{\texttt{textwrap6.tex} using \cref{lst:textwrap7-yaml}}{lst:textwrap6-mod7} + + \cmhlistingsfromfile*{demonstrations/textwrap6-mod8.tex}{\texttt{textwrap6.tex} using \cref{lst:textwrap8-yaml}}{lst:textwrap6-mod8} + \end{widepage} + + Notice that: + \begin{itemize} + \item in \cref{lst:textwrap6-mod6} the text wrapping routine has not been applied to any + \texttt{environments} because it has been switched off (per-code-block) in + \cref{lst:textwrap6-yaml}; + \item in \cref{lst:textwrap6-mod7} the text wrapping routine has not been applied to + \texttt{myenv} because it has been switched off (per-name) in + \cref{lst:textwrap7-yaml}; + \item in \cref{lst:textwrap6-mod8} the text wrapping routine has not been applied to + \texttt{masterDocument} because of the settings in \cref{lst:textwrap8-yaml}. + \end{itemize} + + The \texttt{columns} field has a variety of different ways that it can be + specified; we've seen two basic ways already: the default (set to + \texttt{0}) and a positive integer (see \vref{lst:textwrap6}, for + example). We explore further options in \crefrange{lst:textwrap9-yaml}{lst:textwrap11-yaml}. + + \begin{adjustwidth}{-3.5cm}{-2.5cm} + \begin{minipage}{.33\linewidth} + \cmhlistingsfromfile*{demonstrations/textwrap9.yaml}[MLB-TCB]{\texttt{textwrap9.yaml}}{lst:textwrap9-yaml} + \end{minipage}% + \begin{minipage}{.33\linewidth} + \cmhlistingsfromfile*{demonstrations/textwrap10.yaml}[MLB-TCB]{\texttt{textwrap10.yaml}}{lst:textwrap10-yaml} + \end{minipage}% + \begin{minipage}{.33\linewidth} + \cmhlistingsfromfile*{demonstrations/textwrap11.yaml}[MLB-TCB]{\texttt{textwrap11.yaml}}{lst:textwrap11-yaml} + \end{minipage} + \end{adjustwidth} + + \Cref{lst:textwrap9-yaml} and \cref{lst:textwrap10-yaml} are equivalent. Upon running + the commands + \begin{commandshell} +latexindent.pl -s textwrap6.tex -l=textwrap9.yaml -m +latexindent.pl -s textwrap6.tex -l=textwrap11.yaml -m + \end{commandshell} + we receive the respective output given in \cref{lst:textwrap6-mod9,lst:textwrap6-mod11}. + + \begin{widepage} + \cmhlistingsfromfile*{demonstrations/textwrap6-mod9.tex}{\texttt{textwrap6.tex} using \cref{lst:textwrap9-yaml}}{lst:textwrap6-mod9} + + \cmhlistingsfromfile*{demonstrations/textwrap6-mod11.tex}{\texttt{textwrap6.tex} using \cref{lst:textwrap11-yaml}}{lst:textwrap6-mod11} + \end{widepage} + + Notice that: + \begin{itemize} + \item in \cref{lst:textwrap6-mod9} the text for the \texttt{masterDocument} has been + wrapped using \texttt{30} columns, while \texttt{environments} has + been wrapped using \texttt{50} columns; + \item in \cref{lst:textwrap6-mod11} the text for \texttt{myenv} has been wrapped + using \texttt{50} columns, the text for \texttt{another} has + been wrapped using \texttt{15} columns, and \texttt{masterDocument} + has been wrapped using \texttt{30} columns. + \end{itemize} + If you don't specify a \texttt{default} value on per-code-block basis, then + the \texttt{default} value from \texttt{columns} will be inherited; + if you don't specify a default value for \texttt{columns} then + \texttt{80} will be used. + + \texttt{alignAtAmpersandTakesPriority} is set to \texttt{1} by default; assuming + that text wrapping is occuring on a per-code-block basis, and the current + environment/code block is specified within \vref{lst:aligndelims:basic} then text wrapping + will be disabled for this code block. + + If you wish to specify \texttt{afterHeading} commands (see + \vref{lst:indentAfterHeadings}) on a per-name basis, then you need to append the name with + \texttt{:heading}, for example, you might use \texttt{section:heading}. + +\subsubsection{Summary of text wrapping} It is important to note the following: \begin{itemize} - \item Verbatim environments (\vref{lst:verbatimEnvironments}) and verbatim commands (\vref{lst:verbatimCommands}) will \emph{not} be affected by the text wrapping routine (see \vref{lst:textwrap2-mod1}); - \item comments will \emph{not} be affected by the text wrapping routine (see \vref{lst:textwrap3-mod1}); - \item indentation is performed \emph{after} the text wrapping routine; as such, indented code - will likely exceed any maximum value set in the \texttt{columns} field. + \item Verbatim environments (\vref{lst:verbatimEnvironments}) and verbatim commands + (\vref{lst:verbatimCommands}) will \emph{not} be affected by the text + wrapping routine (see \vref{lst:textwrap2-mod1}); + \item comments will \emph{not} be affected by the text wrapping routine (see + \vref{lst:textwrap3-mod1}); + \item it is possible to wrap text on a per-code-block and a per-name basis; + \announce*{2018-08-13}*{updates to textWrapOptions} + \item the text wrapping routine sets \texttt{preserveBlankLines} as + \texttt{1}; + \item indentation is performed \emph{after} the text wrapping routine; as such, + indented code will likely exceed any maximum value set in the \texttt{columns} + field. \end{itemize} \subsection{oneSentencePerLine: modifying line breaks for sentences}\label{sec:onesentenceperline} - You can instruct \texttt{latexindent.pl} to format% - \announce{2018-01-13}{one sentence per line} your file so that 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. + You can instruct \texttt{latexindent.pl} to + format%%%%% + \announce{2018-01-13}{one sentence per line} your file so that + 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. - \cmhlistingsfromfile[style=oneSentencePerLine]*{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{oneSentencePerLine}}{lst:oneSentencePerLine} + \cmhlistingsfromfile*[style=oneSentencePerLine]*{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{oneSentencePerLine}}{lst:oneSentencePerLine} \yamltitle{manipulateSentences}{0|1} - This is a binary switch that details if \texttt{latexindent.pl} should perform the sentence manipulation routine; it - is \emph{off} (set to \texttt{0}) by default, and you will need to turn it on (by setting it to \texttt{1}) if you want the script + This is a binary switch that details if \texttt{latexindent.pl} should perform the + sentence manipulation routine; it is \emph{off} (set to \texttt{0}) by default, and you will + need to turn it on (by setting it to \texttt{1}) if you want the script to modify line breaks surrounding and within sentences. \yamltitle{removeSentenceLineBreaks}{0|1} - When operating upon sentences \texttt{latexindent.pl} will, by default, remove internal linebreaks as \texttt{removeSentenceLineBreaks} - is set to \texttt{1}. Setting this switch to \texttt{0} instructs \texttt{latexindent.pl} not to do so. + When operating upon sentences \texttt{latexindent.pl} will, by default, remove + internal linebreaks as \texttt{removeSentenceLineBreaks} is set to \texttt{1}. + Setting this switch to \texttt{0} instructs \texttt{latexindent.pl} + not to do so. For example, consider \texttt{multiple-sentences.tex} shown in \cref{lst:multiple-sentences}. @@ -196,21 +406,26 @@ latexindent.pl multiple-sentences -m -l=keep-sen-line-breaks.yaml \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/keep-sen-line-breaks.yaml}[MLB-TCB]{\texttt{keep-sen-line-breaks.yaml}}{lst:keep-sen-line-breaks-yaml} \end{minipage} - Notice, in particular, that the `internal' sentence line breaks in \cref{lst:multiple-sentences} have - been removed in \cref{lst:multiple-sentences-mod1}, but have not been removed in \cref{lst:multiple-sentences-mod2}. + Notice, in particular, that the `internal' sentence line breaks in + \cref{lst:multiple-sentences} have been removed in \cref{lst:multiple-sentences-mod1}, but have + not been removed in \cref{lst:multiple-sentences-mod2}. - The remainder of the settings displayed in \vref{lst:oneSentencePerLine} instruct \texttt{latexindent.pl} on how to define - a sentence. From the perpesctive of \texttt{latexindent.pl} a sentence must: + The remainder of the settings displayed in \vref{lst:oneSentencePerLine} instruct + \texttt{latexindent.pl} on how to define a sentence. From the perpesctive of + \texttt{latexindent.pl} a sentence must: \begin{itemize} - \item \emph{follow} a certain character or set of characters (see \cref{lst:sentencesFollow}); by default, this is either \lstinline!\par!, a blank line, - a full stop/period (.), exclamation mark (!), question mark (?) right brace (\}) or a comment - on the previous line; - \item \emph{begin} with a character type (see \cref{lst:sentencesBeginWith}); by default, this is only capital letters; - \item \emph{end} with a character (see \cref{lst:sentencesEndWith}); by default, these are - full stop/period (.), exclamation mark (!) and question mark (?). + \item \emph{follow} a certain character or set of characters (see + \cref{lst:sentencesFollow}); by default, this is either \lstinline!\par!, a + blank line, a full stop/period (.), exclamation mark (!), question mark (?) right brace + (\}) or a comment on the previous line; + \item \emph{begin} with a character type (see \cref{lst:sentencesBeginWith}); by + default, this is only capital letters; + \item \emph{end} with a character (see \cref{lst:sentencesEndWith}); by + default, these are full stop/period (.), exclamation mark (!) and question mark (?). \end{itemize} - 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. + 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. \begin{adjustwidth}{-3.5cm}{-2.5cm} \begin{minipage}{.36\linewidth} @@ -227,8 +442,9 @@ latexindent.pl multiple-sentences -m -l=keep-sen-line-breaks.yaml \end{adjustwidth} \subsubsection{sentencesFollow} - 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 + 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 \begin{commandshell} latexindent.pl multiple-sentences -m -l=sentences-follow1.yaml \end{commandshell} @@ -242,10 +458,12 @@ latexindent.pl multiple-sentences -m -l=sentences-follow1.yaml \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/sentences-follow1.yaml}[MLB-TCB]{\texttt{sentences-follow1.yaml}}{lst:sentences-follow1-yaml} \end{minipage} - Notice that, because \texttt{blankLine} is set to \texttt{0}, \texttt{latexindent.pl} will not seek sentences following a blank line, - and so the fourth sentence has not been accounted for. + Notice that, because \texttt{blankLine} is set to \texttt{0}, + \texttt{latexindent.pl} will not seek sentences following a blank line, and so the + fourth sentence has not been accounted for. - We can explore the \texttt{other} field in \cref{lst:sentencesFollow} with the \texttt{.tex} file detailed in \cref{lst:multiple-sentences1}. + We can explore the \texttt{other} field in \cref{lst:sentencesFollow} with + the \texttt{.tex} file detailed in \cref{lst:multiple-sentences1}. \cmhlistingsfromfile{demonstrations/multiple-sentences1.tex}{\texttt{multiple-sentences1.tex}}{lst:multiple-sentences1} @@ -267,14 +485,17 @@ latexindent.pl multiple-sentences1 -m -l=manipulate-sentences.yaml,sentences-fol \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/sentences-follow2.yaml}[MLB-TCB]{\texttt{sentences-follow2.yaml}}{lst:sentences-follow2-yaml} \end{minipage} - Notice that in \cref{lst:multiple-sentences1-mod1} the first sentence after the \texttt{)} has not been accounted for, but that - following the inclusion of \cref{lst:sentences-follow2-yaml}, the output given in \cref{lst:multiple-sentences1-mod2} demonstrates that - the sentence \emph{has} been accounted for correctly. + Notice that in \cref{lst:multiple-sentences1-mod1} the first sentence after the + \texttt{)} has not been accounted for, but that following the inclusion + of \cref{lst:sentences-follow2-yaml}, the output given in \cref{lst:multiple-sentences1-mod2} + demonstrates that the sentence \emph{has} been accounted for correctly. \subsubsection{sentencesBeginWith} - By default, \texttt{latexindent.pl} will only assume that sentences begin with the upper case letters \texttt{A-Z}; you can instruct the - script to define 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. + By default, \texttt{latexindent.pl} will only assume that sentences begin with the + upper case letters \texttt{A-Z}; you can instruct the script to define + 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. \cmhlistingsfromfile{demonstrations/multiple-sentences2.tex}{\texttt{multiple-sentences2.tex}}{lst:multiple-sentences2} @@ -295,14 +516,19 @@ latexindent.pl multiple-sentences2 -m -l=manipulate-sentences.yaml,sentences-beg \begin{minipage}{.45\linewidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/sentences-begin1.yaml}[MLB-TCB]{\texttt{sentences-begin1.yaml}}{lst:sentences-begin1-yaml} \end{minipage} - Notice that in \cref{lst:multiple-sentences2-mod1}, the first sentence has been accounted for but that the subsequent sentences - have not. In \cref{lst:multiple-sentences2-mod2}, all of the sentences have been accounted for, because the \texttt{other} field - in \cref{lst:sentences-begin1-yaml} has defined sentences to begin with either \lstinline!$! or any numeric digit, \texttt{0} to \texttt{9}. + Notice that in \cref{lst:multiple-sentences2-mod1}, the first sentence has been accounted for but + that the subsequent sentences have not. In \cref{lst:multiple-sentences2-mod2}, all of the + sentences have been accounted for, because the \texttt{other} field in + \cref{lst:sentences-begin1-yaml} has defined sentences to begin with either + \lstinline!$! or any numeric digit, \texttt{0} to + \texttt{9}. \subsubsection{sentencesEndWith} - Let's return to \vref{lst:multiple-sentences}; we have already seen the default way in which \texttt{latexindent.pl} will operate on the - sentences in this file in \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 + Let's return to \vref{lst:multiple-sentences}; we have already seen the default way in + which \texttt{latexindent.pl} will operate on the sentences in this file in + \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 \begin{commandshell} latexindent.pl multiple-sentences -m -l=sentences-end1.yaml latexindent.pl multiple-sentences -m -l=sentences-end2.yaml @@ -325,13 +551,16 @@ latexindent.pl multiple-sentences -m -l=sentences-end2.yaml \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/sentences-end2.yaml}[MLB-TCB]{\texttt{sentences-end2.yaml}}{lst:sentences-end2-yaml} \end{minipage} - There is a subtle difference between the output in \cref{lst:multiple-sentences-mod4,lst:multiple-sentences-mod5}; in particular, - in \cref{lst:multiple-sentences-mod4} the word \texttt{sentence} has not been defined as a sentence, because we have not instructed - \texttt{latexindent.pl} to begin sentences with lower case letters. We have changed this by using the settings in \cref{lst:sentences-end2-yaml}, - and the associated output in \cref{lst:multiple-sentences-mod5} reflects this. + There is a subtle difference between the output in \cref{lst:multiple-sentences-mod4,lst:multiple-sentences-mod5}; in + particular, in \cref{lst:multiple-sentences-mod4} the word \texttt{sentence} has not + been defined as a sentence, because we have not instructed \texttt{latexindent.pl} to + begin sentences with lower case letters. We have changed this by using the settings in + \cref{lst:sentences-end2-yaml}, and the associated output in \cref{lst:multiple-sentences-mod5} + reflects this. - Referencing \vref{lst:sentencesEndWith}, you'll notice that there is a field called \texttt{basicFullStop}, which - is set to \texttt{0}, and that the \texttt{betterFullStop} is set to \texttt{1} by default. + Referencing \vref{lst:sentencesEndWith}, you'll notice that there is a field called + \texttt{basicFullStop}, which is set to \texttt{0}, and that the + \texttt{betterFullStop} is set to \texttt{1} by default. Let's consider the file shown in \cref{lst:url}. @@ -345,22 +574,25 @@ latexindent.pl url -m -l=manipulate-sentences.yaml \cmhlistingsfromfile{demonstrations/url-mod1.tex}{\texttt{url.tex} using \vref{lst:manipulate-sentences-yaml}}{lst:url-mod1} - Notice that the full stop within the url has been interpreted correctly. This is because, within the \texttt{betterFullStop}, - full stops at the end of sentences have the following properties: + Notice that the full stop within the url has been interpreted correctly. This is because, + within the \texttt{betterFullStop}, full stops at the end of sentences have the + following properties: \begin{itemize} \item they are ignored within \texttt{e.g.} and \texttt{i.e.}; \item they can not be immediately followed by a lower case or upper case letter; \item they can not be immediately followed by a hyphen, comma, or number. \end{itemize} - If you find that the \texttt{betterFullStop} does not work for your purposes, then you can switch it off by setting - it to \texttt{0}, and you can experiment with the \texttt{other} field. + If you find that the \texttt{betterFullStop} does not work for your purposes, then + you can switch it off by setting it to \texttt{0}, and you can + experiment with the \texttt{other} field. - The \texttt{basicFullStop} routine should probably be avoided in most situations, as it does not accomodate the specifications - above. For example, using the following command + The \texttt{basicFullStop} routine should probably be avoided in most situations, as + it does not accomodate the specifications above. For example, using the following command \begin{commandshell} latexindent.pl url -m -l=alt-full-stop1.yaml \end{commandshell} - and the YAML in \cref{lst:alt-full-stop1-yaml} gives the output in \cref{lst:url-mod2}. + and the YAML in \cref{lst:alt-full-stop1-yaml} gives the output in + \cref{lst:url-mod2}. \begin{adjustwidth}{-3.5cm}{-1.5cm} \begin{minipage}{.6\linewidth} @@ -372,35 +604,38 @@ latexindent.pl url -m -l=alt-full-stop1.yaml \end{minipage} \end{adjustwidth} - Notice that the full stop within the URL has not been accomodated correctly because of the non-default settings in \cref{lst:alt-full-stop1-yaml}. + Notice that the full stop within the URL has not been accomodated correctly because of + the non-default settings in \cref{lst: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. + 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. - For example, if we begin with the \texttt{.tex} file in \cref{lst:multiple-sentences3}, and run the command + For example, if we begin with the \texttt{.tex} file in + \cref{lst:multiple-sentences3}, and run the command \begin{commandshell} latexindent.pl multiple-sentences3 -m -l=manipulate-sentences.yaml \end{commandshell} - then we obtain the output in \cref{lst:multiple-sentences3-mod1}. - \cmhlistingsfromfile{demonstrations/multiple-sentences3.tex}{\texttt{multiple-sentences3.tex}}{lst:multiple-sentences3} + then we obtain the output in \cref{lst:multiple-sentences3-mod1}. \cmhlistingsfromfile{demonstrations/multiple-sentences3.tex}{\texttt{multiple-sentences3.tex}}{lst:multiple-sentences3} \cmhlistingsfromfile{demonstrations/multiple-sentences3-mod1.tex}{\texttt{multiple-sentences3.tex} using \vref{lst:manipulate-sentences-yaml}}{lst:multiple-sentences3-mod1} - 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 + 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 \begin{commandshell} latexindent.pl multiple-sentences4 -m -l=manipulate-sentences.yaml latexindent.pl multiple-sentences4 -m -l=keep-sen-line-breaks.yaml \end{commandshell} - then we obtain the output in \cref{lst:multiple-sentences4-mod1,lst:multiple-sentences4-mod2}. - \cmhlistingsfromfile{demonstrations/multiple-sentences4.tex}{\texttt{multiple-sentences4.tex}}{lst:multiple-sentences4} + then we obtain the output in \cref{lst:multiple-sentences4-mod1,lst:multiple-sentences4-mod2}. \cmhlistingsfromfile{demonstrations/multiple-sentences4.tex}{\texttt{multiple-sentences4.tex}}{lst:multiple-sentences4} \begin{widepage} \cmhlistingsfromfile{demonstrations/multiple-sentences4-mod1.tex}{\texttt{multiple-sentences4.tex} using \vref{lst:manipulate-sentences-yaml}}{lst:multiple-sentences4-mod1} \end{widepage} \cmhlistingsfromfile{demonstrations/multiple-sentences4-mod2.tex}{\texttt{multiple-sentences4.tex} using \vref{lst:keep-sen-line-breaks-yaml}}{lst:multiple-sentences4-mod2} - Once you've read \cref{sec:poly-switches}, you will know that you can accomodate the removal of internal sentence line breaks - by using the YAML in \cref{lst:item-rules2-yaml} and the command + Once you've read \cref{sec:poly-switches}, you will know that you can accomodate the + removal of internal sentence line breaks by using the YAML in \cref{lst:item-rules2-yaml} + and the command \begin{commandshell} latexindent.pl multiple-sentences4 -m -l=item-rules2.yaml \end{commandshell} @@ -414,31 +649,66 @@ latexindent.pl multiple-sentences4 -m -l=item-rules2.yaml \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/item-rules2.yaml}[MLB-TCB]{\texttt{item-rules2.yaml}}{lst:item-rules2-yaml} \end{minipage} -\subsection{removeParagraphLineBreaks: modifying line breaks for paragraphs} - When the \texttt{-m} switch is active \texttt{latexindent.pl} has the ability to remove line breaks - \announce{2017-05-27}{removeParagraphLineBreaks} - from within paragraphs; the behaviour is controlled by the \texttt{removeParagraphLineBreaks} field, detailed in - \cref{lst:removeParagraphLineBreaks}. Thank you to \cite{jowens} for shaping and assisting with the testing of this feature. -\yamltitle{removeParagraphLineBreaks}*{fields} - This feature is considered complimentary to the \texttt{oneSentencePerLine} feature described in \vref{sec:onesentenceperline}. +\subsubsection{text wrapping and indenting sentences} + The \texttt{oneSentencePerLine}%% + \announce*{2018-08-13}{oneSentencePerline text wrap and indent} can be instructed to perform + text wrapping and indentation upon sentences. + + Let's use the code in \cref{lst:multiple-sentences5}. + + \cmhlistingsfromfile*{demonstrations/multiple-sentences5.tex}{\texttt{multiple-sentences5.tex}}{lst:multiple-sentences5} - \cmhlistingsfromfile[style=removeParagraphLineBreaks]*{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{removeParagraphLineBreaks}}{lst:removeParagraphLineBreaks} + Referencing \cref{lst:sentence-wrap1-yaml}, and running the following command + \begin{commandshell} +latexindent.pl multiple-sentences5 -m -l=sentence-wrap1.yaml +\end{commandshell} + we receive the output given in \cref{lst:multiple-sentences5-mod1}. - This routine can be turned on \emph{globally} for \emph{every} code block type known to \texttt{latexindent.pl} - (see \vref{tab:code-blocks}) by using the \texttt{all} switch; by default, this switch is \emph{off}. Assuming - that the \texttt{all} switch is off, then the routine can be controlled on a per-code-block-type basis, and - within that, on a per-name basis. We will consider examples of each of these in turn, but - before we do, let's specify what \texttt{latexindent.pl} considers as a paragraph: + \begin{widepage} + \begin{minipage}{.55\linewidth} + \cmhlistingsfromfile*{demonstrations/multiple-sentences5-mod1.tex}{\texttt{multiple-sentences5.tex} using \cref{lst:sentence-wrap1-yaml}}{lst:multiple-sentences5-mod1} + \end{minipage}% + \hfill + \begin{minipage}{.45\linewidth} + \cmhlistingsfromfile*[style=yaml-LST]*{demonstrations/sentence-wrap1.yaml}[MLB-TCB]{\texttt{sentence-wrap1.yaml}}{lst:sentence-wrap1-yaml} + \end{minipage} + \end{widepage} + + If you wish to specify the \texttt{columns} field on a per-code-block basis + for sentences, then you would use \texttt{sentence}; explicitly, starting with + \vref{lst:textwrap9-yaml}, for example, you would replace/append + \texttt{environments} with, for example, \texttt{sentence: 50}. + +\subsection{removeParagraphLineBreaks: modifying line breaks for paragraphs}\label{subsec:removeparagraphlinebreaks} + When the \texttt{-m} switch is active \texttt{latexindent.pl} has the + ability to remove line breaks% + \announce{2017-05-27}{removeParagraphLineBreaks} from within paragraphs; the behaviour is controlled by the + \texttt{removeParagraphLineBreaks} field, detailed in \cref{lst:removeParagraphLineBreaks}. Thank you to + \cite{jowens} for shaping and assisting with the testing of this feature. +\yamltitle{removeParagraphLineBreaks}*{fields} + This feature is considered complimentary to the \texttt{oneSentencePerLine} feature + described in \vref{sec:onesentenceperline}. + + \cmhlistingsfromfile*[style=removeParagraphLineBreaks]*{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{removeParagraphLineBreaks}}{lst:removeParagraphLineBreaks} + + This routine can be turned on \emph{globally} for \emph{every} + code block type known to \texttt{latexindent.pl} + (see \vref{tab:code-blocks}) by using the + \texttt{all} switch; by default, this switch is + \emph{off}. Assuming that the \texttt{all} switch is off, + then the routine can be controlled on a per-code-block-type basis, and within that, on a + per-name basis. We will consider examples of each of these in turn, but before we do, + let's specify what \texttt{latexindent.pl} considers as a paragraph: \begin{itemize} - \item it must begin on its own line with either an alphabetic or numeric character, and not with any of the - code-block types detailed in \vref{tab:code-blocks}; - \item it can include line breaks, but finishes when it meets either a blank line, a \lstinline!\par! - command, or any of the user-specified settings in the \texttt{paragraphsStopAt} field, - detailed in \vref{lst:paragraphsStopAt}. + \item it must begin on its own line with either an alphabetic or numeric character, and not + with any of the code-block types detailed in \vref{tab:code-blocks}; + \item it can include line breaks, but finishes when it meets either a blank line, a + \lstinline!\par! command, or any of the user-specified settings in the + \texttt{paragraphsStopAt} field, detailed in \vref{lst:paragraphsStopAt}. \end{itemize} - Let's start with the \texttt{.tex} file in \cref{lst:shortlines}, together with the YAML settings in - \cref{lst:remove-para1-yaml}. + Let's start with the \texttt{.tex} file in \cref{lst:shortlines}, + together with the YAML settings in \cref{lst:remove-para1-yaml}. \begin{minipage}{.45\linewidth} \cmhlistingsfromfile[showspaces=true]{demonstrations/shortlines.tex}{\texttt{shortlines.tex}}{lst:shortlines} @@ -456,19 +726,21 @@ latexindent.pl -m shortlines.tex -o shortlines1.tex -l remove-para1.yaml \cmhlistingsfromfile[showspaces=true]{demonstrations/shortlines1.tex}{\texttt{shortlines1.tex}}{lst:shortlines1} - Keen readers may notice that some trailing white space must be present in the file in \cref{lst:shortlines} which - has crept in to the output in \cref{lst:shortlines1}. This can be fixed using the YAML file in + Keen readers may notice that some trailing white space must be present in the file in + \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, \begin{commandshell} latexindent.pl -m shortlines.tex -o shortlines1-tws.tex -l remove-para1.yaml,removeTWS-before.yaml \end{commandshell} - in which case the output is as in \cref{lst:shortlines1-tws}; notice that the double spaces present in \cref{lst:shortlines1} - have been addressed. + in which case the output is as in \cref{lst:shortlines1-tws}; notice that the double + spaces present in \cref{lst:shortlines1} have been addressed. \cmhlistingsfromfile[showspaces=true]{demonstrations/shortlines1-tws.tex}{\texttt{shortlines1-tws.tex}}{lst:shortlines1-tws} - Keeping with the settings in \cref{lst:remove-para1-yaml}, we note that the \texttt{all} switch applies - to \emph{all} code block types. So, for example, let's consider the files in \cref{lst:shortlines-mand,lst:shortlines-opt} + Keeping with the settings in \cref{lst:remove-para1-yaml}, we note that the + \texttt{all} switch applies to \emph{all} code block + types. So, for example, let's consider the files in \cref{lst:shortlines-mand,lst:shortlines-opt} \begin{minipage}{.45\linewidth} \cmhlistingsfromfile{demonstrations/shortlines-mand.tex}{\texttt{shortlines-mand.tex}}{lst:shortlines-mand} @@ -491,13 +763,15 @@ latexindent.pl -m shortlines-opt.tex -o shortlines-opt1.tex -l remove-para1.yaml \cmhlistingsfromfile{demonstrations/shortlines-mand1.tex}{\texttt{shortlines-mand1.tex}}{lst:shortlines-mand1} \cmhlistingsfromfile{demonstrations/shortlines-opt1.tex}{\texttt{shortlines-opt1.tex}}{lst:shortlines-opt1} - Assuming that we turn \emph{off} the \texttt{all} switch (by setting it to \texttt{0}), then - we can control the behaviour of \texttt{removeParagraphLineBreaks} either on a per-code-block-type basis, - or on a per-name basis. + Assuming that we turn \emph{off} the \texttt{all} switch + (by setting it to \texttt{0}), then we can control the behaviour of + \texttt{removeParagraphLineBreaks} either on a per-code-block-type basis, or on a per-name + basis. - For example, let's use the code in \cref{lst:shortlines-envs}, and consider the settings in \cref{lst:remove-para2-yaml,lst:remove-para3-yaml}; - note that in \cref{lst:remove-para2-yaml} we specify that \emph{every} environment should receive - treatment from the routine, while in \cref{lst:remove-para3-yaml} we specify that \emph{only} the + For example, let's use the code in \cref{lst:shortlines-envs}, and consider the settings + in \cref{lst:remove-para2-yaml,lst:remove-para3-yaml}; note that in \cref{lst:remove-para2-yaml} we specify that + \emph{every} environment should receive treatment from the routine, while + in \cref{lst:remove-para3-yaml} we specify that \emph{only} the \texttt{one} environment should receive the treatment. \begin{minipage}{.45\linewidth} @@ -521,13 +795,15 @@ latexindent.pl -m shortlines-envs.tex -o shortlines-envs3.tex -l remove-para3.ya \cmhlistingsfromfile{demonstrations/shortlines-envs2.tex}{\texttt{shortlines-envs2.tex}}{lst:shortlines-envs2} \cmhlistingsfromfile{demonstrations/shortlines-envs3.tex}{\texttt{shortlines-envs3.tex}}{lst:shortlines-envs3} - The remaining code-block types can be customized in analogous ways, although note that \texttt{commands}, - \texttt{keyEqualsValuesBracesBrackets}, \texttt{namedGroupingBracesBrackets}, \texttt{UnNamedGroupingBracesBrackets} - are controlled by the \texttt{optionalArguments} and the \texttt{mandatoryArguments}. + The remaining code-block types can be customized in analogous ways, although note that + \texttt{commands}, \texttt{keyEqualsValuesBracesBrackets}, \texttt{namedGroupingBracesBrackets}, + \texttt{UnNamedGroupingBracesBrackets} are controlled by the \texttt{optionalArguments} and the + \texttt{mandatoryArguments}. - The only special case is the \texttt{masterDocument} field; this is designed for `chapter'-type files that - may contain paragraphs that are not within any other code-blocks. For example, consider the file in - \cref{lst:shortlines-md}, with the YAML settings in \cref{lst:remove-para4-yaml}. + The only special case is the \texttt{masterDocument} field; this is designed for + `chapter'-type files that may contain paragraphs that are not within any other + code-blocks. For example, consider the file in \cref{lst:shortlines-md}, with the YAML + settings in \cref{lst:remove-para4-yaml}. \begin{minipage}{.45\linewidth} \cmhlistingsfromfile{demonstrations/shortlines-md.tex}{\texttt{shortlines-md.tex}}{lst:shortlines-md} @@ -543,23 +819,31 @@ latexindent.pl -m shortlines-envs.tex -o shortlines-envs3.tex -l remove-para3.ya latexindent.pl -m shortlines-md.tex -o shortlines-md4.tex -l remove-para4.yaml \end{commandshell} \end{widepage} - then we obtain the output in \cref{lst:shortlines-md4}. - \cmhlistingsfromfile{demonstrations/shortlines-md4.tex}{\texttt{shortlines-md4.tex}}{lst:shortlines-md4} + then we obtain the output in \cref{lst:shortlines-md4}. \cmhlistingsfromfile{demonstrations/shortlines-md4.tex}{\texttt{shortlines-md4.tex}}{lst:shortlines-md4} + + Note%%%% + \announce*{2018-08-13}*{updates to all in removeParagraphLineBreaks} that the + \texttt{all} field can take the same exceptions detailed in + \cref{lst:textwrap6-yaml}{lst:textwrap8-yaml}. \yamltitle{paragraphsStopAt}*{fields} - The paragraph line break routine considers blank lines and the \lstinline|\par| command to be the end of a paragraph; - \announce{2017-05-27}{paragraphsStopAt} - you can fine tune the behaviour of the routine further by using the \texttt{paragraphsStopAt} fields, shown in \cref{lst:paragraphsStopAt}. + The paragraph line break routine considers blank lines and the + \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}. - \cmhlistingsfromfile[style=paragraphsStopAt]*{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{paragraphsStopAt}}{lst: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 at the - beginning of a line. It is \emph{not} possible to specify these fields on a per-name basis. + 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. - 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}. + 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}. \begin{minipage}{.45\linewidth} \cmhlistingsfromfile{demonstrations/sl-stop.tex}{\texttt{sl-stop.tex}}{lst:sl-stop} @@ -579,60 +863,121 @@ latexindent.pl -m sl-stop.tex -o sl-stop4-command.tex -l=remove-para4.yaml,stop- latexindent.pl -m sl-stop.tex -o sl-stop4-comment.tex -l=remove-para4.yaml,stop-comment.yaml \end{commandshell} \end{widepage} - we obtain the respective outputs in \crefrange{lst:sl-stop4}{lst:sl-stop4-comment}; notice in particular that: + we obtain the respective outputs in \crefrange{lst:sl-stop4}{lst:sl-stop4-comment}; notice in particular + that: \begin{itemize} - \item in \cref{lst:sl-stop4} the paragraph line break routine has included commands and comments; - \item in \cref{lst:sl-stop4-command} the paragraph line break routine has \emph{stopped} at the - \texttt{emph} command, because in \cref{lst:stop-command-yaml} we have specified \texttt{commands} - to be \texttt{1}, and \texttt{emph} is at the beginning of a line; - \item in \cref{lst:sl-stop4-comment} the paragraph line break routine has \emph{stopped} - at the comments, because in \cref{lst:stop-comment-yaml} we have specified \texttt{comments} - to be \texttt{1}, and the comment is at the beginning of a line. + \item in \cref{lst:sl-stop4} the paragraph line break routine has included commands and + comments; + \item in \cref{lst:sl-stop4-command} the paragraph line break routine has + \emph{stopped} at the \texttt{emph} command, because in + \cref{lst:stop-command-yaml} we have specified \texttt{commands} to be + \texttt{1}, and \texttt{emph} is at the beginning of a + line; + \item in \cref{lst:sl-stop4-comment} the paragraph line break routine has + \emph{stopped} at the comments, because in \cref{lst:stop-comment-yaml} we + have specified \texttt{comments} to be \texttt{1}, and the + comment is at the beginning of a line. \end{itemize} In all outputs in \crefrange{lst:sl-stop4}{lst:sl-stop4-comment} we notice that the paragraph line break - routine has stopped at \lstinline!\begin{myenv}! because, by default, \texttt{environments} - is set to \texttt{1} in \vref{lst:paragraphsStopAt}. + routine has stopped at \lstinline!\begin{myenv}! because, by default, + \texttt{environments} is set to \texttt{1} in + \vref{lst:paragraphsStopAt}. \cmhlistingsfromfile{demonstrations/sl-stop4.tex}{\texttt{sl-stop4.tex}}{lst:sl-stop4} \cmhlistingsfromfile{demonstrations/sl-stop4-command.tex}{\texttt{sl-stop4-command.tex}}{lst:sl-stop4-command} \cmhlistingsfromfile{demonstrations/sl-stop4-comment.tex}{\texttt{sl-stop4-comment.tex}}{lst:sl-stop4-comment} +\subsection{Combining removeParagraphLineBreaks and textWrapOptions}\label{subsec:removeparagraphlinebreaks:and:textwrap} + + The%%%% + \announce*{2018-08-13}{combine text wrap and remove paragraph line breaks} text wrapping + routine (\vref{subsec:textwrapping}) and remove paragraph line breaks routine + (\vref{subsec:removeparagraphlinebreaks}) can be combined. + + We motivate this feature with the code given in \cref{lst:textwrap7}. + + \cmhlistingsfromfile*{demonstrations/textwrap7.tex}{\texttt{textwrap7.tex}}{lst:textwrap7} + + Applying the text wrap routine from \vref{subsec:textwrapping} with, for example, + \vref{lst:textwrap3-yaml} gives the output in \cref{lst:textwrap7-mod3}. + + \cmhlistingsfromfile*{demonstrations/textwrap7-mod3.tex}{\texttt{textwrap7.tex} using \cref{lst:textwrap3-yaml}}{lst:textwrap7-mod3} + + The text wrapping routine has behaved as expected, but it may be desired to remove + paragraph line breaks \emph{before} performing the text wrapping routine. + The desired behaviour can be achieved by employing the \texttt{beforeTextWrap} + switch. + + Explicitly, using the settings in \cref{lst:textwrap12-yaml} and running the command + \begin{commandshell} +latexindent.pl -m textwrap7.tex -l=textwrap12.yaml -o=+-mod12 + \end{commandshell} + we obtain the output in \cref{lst:textwrap7-mod12}. + + \begin{minipage}{.45\linewidth} + \cmhlistingsfromfile*{demonstrations/textwrap7-mod12.tex}{\texttt{textwrap7-mod12.tex}}{lst:textwrap7-mod12} + \end{minipage} + \hfill + \begin{minipage}{.49\linewidth} + \cmhlistingsfromfile*{demonstrations/textwrap12.yaml}[MLB-TCB]{\texttt{textwrap12.yaml}}{lst:textwrap12-yaml} + \end{minipage} + + In \cref{lst:textwrap7-mod12} the paragraph linebreaks have first been removed from + \cref{lst:textwrap7}, and then the text wrapping routine has been applied. It is + envisaged that variants of \cref{lst:textwrap12-yaml} will be among the most useful + settings for these two features. + \subsection{Poly-switches}\label{sec:poly-switches} - Every other field in the \texttt{modifyLineBreaks} field uses poly-switches, and can take - one of \emph{five}% + Every other field in the \texttt{modifyLineBreaks} field uses poly-switches, and can + take one of \emph{five}%%%%% \announce{2017-08-21}*{blank line poly-switch} integer values: \begin{itemize}[font=\bfseries] - \item[$-1$] \emph{remove mode}: line breaks before or after the \emph{} 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; - \item[1] \emph{add mode}: a line break will be added before or after the \emph{} under consideration, assuming that + \item[$-1$] \emph{remove mode}: line breaks before or after the + \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; + \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{}; - \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{}; + \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{}; \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. \end{itemize} - 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. + 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. \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. Note that all poly-switches are \emph{off} by default. + 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. Note that all poly-switches are \emph{off} by default. \cmhlistingsfromfile[style=modifylinebreaksEnv]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,MLB-TCB]{\texttt{environments}}{lst:environments-mlb} - Let's begin with the simple example given in \cref{lst:env-mlb1-tex}; note that we have annotated key parts of the file using $\BeginStartsOnOwnLine$, - $\BodyStartsOnOwnLine$, $\EndStartsOnOwnLine$ and $\EndFinishesWithLineBreak$, these will be related to fields specified in \cref{lst:environments-mlb}. + Let's begin with the simple example given in \cref{lst:env-mlb1-tex}; note that we + have annotated key parts of the file using $\BeginStartsOnOwnLine$, + $\BodyStartsOnOwnLine$, $\EndStartsOnOwnLine$ and $\EndFinishesWithLineBreak$, + these will be related to fields specified in \cref{lst:environments-mlb}. \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 \end{cmhlistings} \subsubsection{Adding line breaks: BeginStartsOnOwnLine and 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$. + 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$. \begin{minipage}{.45\textwidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/env-mlb1.yaml}[MLB-TCB]{\texttt{env-mlb1.yaml}}{lst:env-mlb1} @@ -661,14 +1006,19 @@ latexindent.pl -m env-mlb.tex -l env-mlb2.yaml There are a couple of points to note: \begin{itemize} - \item in \cref{lst:env-mlb-mod1} a line break has been added at the point denoted by $\BeginStartsOnOwnLine$ in \cref{lst:env-mlb1-tex}; no - other line breaks have been changed; - \item in \cref{lst:env-mlb-mod2} a line break has been added at the point denoted by $\BodyStartsOnOwnLine$ in \cref{lst:env-mlb1-tex}; - furthermore, note that the \emph{body} of \texttt{myenv} has received the appropriate (default) indentation. + \item in \cref{lst:env-mlb-mod1} a line break has been added at the point denoted by + $\BeginStartsOnOwnLine$ in \cref{lst:env-mlb1-tex}; no other line breaks have been + changed; + \item in \cref{lst:env-mlb-mod2} a line break has been added at the point denoted by + $\BodyStartsOnOwnLine$ in \cref{lst:env-mlb1-tex}; furthermore, note that the + \emph{body} of \texttt{myenv} has received the appropriate + (default) indentation. \end{itemize} - Let's now change each of the \texttt{1} values in \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}). + Let's now change each of the \texttt{1} values in + \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}). \begin{minipage}{.45\textwidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/env-mlb3.yaml}[MLB-TCB]{\texttt{env-mlb3.yaml}}{lst:env-mlb3} @@ -690,13 +1040,15 @@ latexindent.pl -m env-mlb.tex -l env-mlb2.yaml \end{minipage} \end{widepage} - Note that line breaks have been added as in \cref{lst:env-mlb-mod1,lst:env-mlb-mod2}, but this time a comment symbol - has been added before adding the line break; in both cases, trailing horizontal - space has been stripped before doing so. + Note that line breaks have been added as in \cref{lst:env-mlb-mod1,lst:env-mlb-mod2}, but this time a + comment symbol has been added before adding the line break; in both cases, trailing + horizontal space has been stripped before doing so. - Let's% - \announce{2017-08-21}{demonstration of blank line poly-switch (3)} now change each of the \texttt{1} values in \cref{lst:env-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}). + Let's%%%%% + \announce{2017-08-21}{demonstration of blank line poly-switch (3)} now change each + of the \texttt{1} values in \cref{lst:env-mlb1,lst:env-mlb2} so that they are + $3$ and save them into \texttt{env-mlb5.yaml} and + \texttt{env-mlb6.yaml} respectively (see \cref{lst:env-mlb5,lst:env-mlb6}). \begin{minipage}{.45\textwidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/env-mlb5.yaml}[MLB-TCB]{\texttt{env-mlb5.yaml}}{lst:env-mlb5} @@ -718,12 +1070,13 @@ latexindent.pl -m env-mlb.tex -l env-mlb2.yaml \end{minipage} \end{widepage} - Note that line breaks have been added as in \cref{lst:env-mlb-mod1,lst:env-mlb-mod2}, but this time a \emph{blank line} - has been added after adding the line break. + Note that line breaks have been added as in \cref{lst:env-mlb-mod1,lst:env-mlb-mod2}, but this time a + \emph{blank line} has been added after adding the line break. \subsubsection{Adding line breaks using EndStartsOnOwnLine and EndFinishesWithLineBreak} - Let's explore \texttt{EndStartsOnOwnLine} and \texttt{EndFinishesWithLineBreak} in \cref{lst:env-mlb7,lst:env-mlb8}, - and in particular, let's allow each of them in turn to take a value of $1$. + Let's explore \texttt{EndStartsOnOwnLine} and \texttt{EndFinishesWithLineBreak} in + \cref{lst:env-mlb7,lst:env-mlb8}, and in particular, let's allow each of them in turn to take + a value of $1$. \begin{minipage}{.49\textwidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/env-mlb7.yaml}[MLB-TCB]{\texttt{env-mlb7.yaml}}{lst:env-mlb7} @@ -752,13 +1105,18 @@ latexindent.pl -m env-mlb.tex -l env-mlb8.yaml There are a couple of points to note: \begin{itemize} - \item in \cref{lst:env-mlb-mod7} a line break has been added at the point denoted by $\EndStartsOnOwnLine$ in \vref{lst:env-mlb1-tex}; no - other line breaks have been changed and the \lstinline!\end{myenv}! statement has \emph{not} received indentation (as intended); - \item in \cref{lst:env-mlb-mod8} a line break has been added at the point denoted by $\EndFinishesWithLineBreak$ in \vref{lst:env-mlb1-tex}. + \item in \cref{lst:env-mlb-mod7} a line break has been added at the point denoted by + $\EndStartsOnOwnLine$ in \vref{lst:env-mlb1-tex}; no other line breaks have been + changed and the \lstinline!\end{myenv}! statement has \emph{not} + received indentation (as intended); + \item in \cref{lst:env-mlb-mod8} a line break has been added at the point denoted by + $\EndFinishesWithLineBreak$ in \vref{lst:env-mlb1-tex}. \end{itemize} - Let's now change each of the \texttt{1} values in \cref{lst:env-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}). + Let's now change each of the \texttt{1} values in + \cref{lst:env-mlb7,lst:env-mlb8} so that they are $2$ and save them + into \texttt{env-mlb9.yaml} and \texttt{env-mlb10.yaml} respectively (see + \cref{lst:env-mlb9,lst:env-mlb10}). \begin{minipage}{.49\textwidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/env-mlb9.yaml}[MLB-TCB]{\texttt{env-mlb9.yaml}}{lst:env-mlb9} @@ -780,13 +1138,15 @@ latexindent.pl -m env-mlb.tex -l env-mlb8.yaml \end{minipage} \end{widepage} - Note that line breaks have been added as in \cref{lst:env-mlb-mod7,lst:env-mlb-mod8}, but this time a comment symbol - has been added before adding the line break; in both cases, trailing horizontal - space has been stripped before doing so. + Note that line breaks have been added as in \cref{lst:env-mlb-mod7,lst:env-mlb-mod8}, but this time a + comment symbol has been added before adding the line break; in both cases, trailing + horizontal space has been stripped before doing so. - Let's% - \announce{2017-08-21}{demonstration of blank line poly-switch (3)} now change each of the \texttt{1} values in \cref{lst:env-mlb7,lst:env-mlb8} so that they are $3$ and - save them into \texttt{env-mlb11.yaml} and \texttt{env-mlb12.yaml} respectively (see \cref{lst:env-mlb11,lst:env-mlb12}). + Let's%%%%% + \announce{2017-08-21}{demonstration of blank line poly-switch (3)} now change each of + the \texttt{1} values in \cref{lst:env-mlb7,lst:env-mlb8} so that they are + $3$ and save them into \texttt{env-mlb11.yaml} and + \texttt{env-mlb12.yaml} respectively (see \cref{lst:env-mlb11,lst:env-mlb12}). \begin{minipage}{.49\textwidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/env-mlb11.yaml}[MLB-TCB]{\texttt{env-mlb11.yaml}}{lst:env-mlb11} @@ -808,13 +1168,15 @@ latexindent.pl -m env-mlb.tex -l env-mlb8.yaml \end{minipage} \end{widepage} - Note that line breaks have been added as in \cref{lst:env-mlb-mod7,lst:env-mlb-mod8}, and that a \emph{blank line} - has been added after the line break. + Note that line breaks have been added as in \cref{lst:env-mlb-mod7,lst:env-mlb-mod8}, and that a + \emph{blank line} has been added after the line break. \subsubsection{poly-switches only add line breaks when necessary} - If you ask \texttt{latexindent.pl} to add a line break (possibly with a comment) using a poly-switch value of $1$ (or $2$), - it will only do so if necessary. For example, if you process the file in \vref{lst:mlb2} using any of the YAML - files presented so far in this section, it will be left unchanged. + If you ask \texttt{latexindent.pl} to add a line break (possibly with a comment) + using a poly-switch value of $1$ (or $2$), + it will only do so if necessary. For example, if you process the file in + \vref{lst:mlb2} using any of the YAML files presented so far in this section, + it will be left unchanged. \begin{minipage}{.45\linewidth} \cmhlistingsfromfile{demonstrations/env-mlb2.tex}{\texttt{env-mlb2.tex}}{lst:mlb2} @@ -824,13 +1186,15 @@ latexindent.pl -m env-mlb.tex -l env-mlb8.yaml \cmhlistingsfromfile{demonstrations/env-mlb3.tex}{\texttt{env-mlb3.tex}}{lst:mlb3} \end{minipage} - In contrast, the output from processing the file in \cref{lst:mlb3} will vary depending - on the poly-switches used; in \cref{lst:env-mlb3-mod2} you'll see that the comment symbol after - the \lstinline!\begin{myenv}! has been moved to the next line, as \texttt{BodyStartsOnOwnLine} - is set to \texttt{1}. In \cref{lst:env-mlb3-mod4} you'll see that the comment has been accounted - for correctly because \texttt{BodyStartsOnOwnLine} has been set to \texttt{2}, - and the comment symbol has \emph{not} been moved to its own line. You're encouraged to experiment - with \cref{lst:mlb3} and by setting the other poly-switches considered so far to \texttt{2} in turn. + In contrast, the output from processing the file in \cref{lst:mlb3} will vary + depending on the poly-switches used; in \cref{lst:env-mlb3-mod2} you'll see that the + comment symbol after the \lstinline!\begin{myenv}! has been moved to the next line, as + \texttt{BodyStartsOnOwnLine} is set to \texttt{1}. In + \cref{lst:env-mlb3-mod4} you'll see that the comment has been accounted for correctly + because \texttt{BodyStartsOnOwnLine} has been set to \texttt{2}, and the + comment symbol has \emph{not} been moved to its own line. You're + encouraged to experiment with \cref{lst:mlb3} and by setting the other + poly-switches considered so far to \texttt{2} in turn. \begin{minipage}{.45\linewidth} \cmhlistingsfromfile{demonstrations/env-mlb3-mod2.tex}{\texttt{env-mlb3.tex} using \vref{lst:env-mlb2}}{lst:env-mlb3-mod2} @@ -840,15 +1204,19 @@ latexindent.pl -m env-mlb.tex -l env-mlb8.yaml \cmhlistingsfromfile{demonstrations/env-mlb3-mod4.tex}{\texttt{env-mlb3.tex} using \vref{lst:env-mlb4}}{lst:env-mlb3-mod4} \end{minipage} - The details of the discussion in this section have concerned \emph{global} poly-switches in the \texttt{environments} field; - each switch can also be specified on a \emph{per-name} basis, which would take priority over the global values; with - reference to \vref{lst:environments-mlb}, an example is shown for the \texttt{equation*} environment. + The details of the discussion in this section have concerned \emph{global} + poly-switches in the \texttt{environments} field; each switch can also be specified + on a \emph{per-name} basis, which would take priority over the global values; + with reference to \vref{lst:environments-mlb}, an example is shown for the + \texttt{equation*} environment. \subsubsection{Removing line breaks (poly-switches set to $-1$)} - Setting poly-switches to $-1$ tells \texttt{latexindent.pl} to remove line breaks of the \emph{}, if necessary. We will consider the + Setting poly-switches to $-1$ tells \texttt{latexindent.pl} to + remove line breaks of the \emph{}, if necessary. We will consider the example code given in \cref{lst:mlb4}, noting in particular the positions of - the line break highlighters, $\BeginStartsOnOwnLine$, $\BodyStartsOnOwnLine$, $\EndStartsOnOwnLine$ - and $\EndFinishesWithLineBreak$, together with the associated YAML files in \crefrange{lst:env-mlb13}{lst:env-mlb16}. + the line break highlighters, $\BeginStartsOnOwnLine$, $\BodyStartsOnOwnLine$, + $\EndStartsOnOwnLine$ and $\EndFinishesWithLineBreak$, together with the associated + YAML files in \crefrange{lst:env-mlb13}{lst:env-mlb16}. \begin{minipage}{.45\linewidth} \begin{cmhlistings}[style=tcblatex,escapeinside={(*@}{@*)}]{\texttt{env-mlb4.tex}}{lst:mlb4} @@ -898,14 +1266,19 @@ latexindent.pl -m env-mlb4.tex -l env-mlb16.yaml Notice that in: \begin{itemize} - \item \cref{lst:env-mlb4-mod13} the line break denoted by $\BeginStartsOnOwnLine$ in \cref{lst:mlb4} has been removed; - \item \cref{lst:env-mlb4-mod14} the line break denoted by $\BodyStartsOnOwnLine$ in \cref{lst:mlb4} has been removed; - \item \cref{lst:env-mlb4-mod15} the line break denoted by $\EndStartsOnOwnLine$ in \cref{lst:mlb4} has been removed; - \item \cref{lst:env-mlb4-mod16} the line break denoted by $\EndFinishesWithLineBreak$ in \cref{lst:mlb4} has been removed. + \item \cref{lst:env-mlb4-mod13} the line break denoted by $\BeginStartsOnOwnLine$ in + \cref{lst:mlb4} has been removed; + \item \cref{lst:env-mlb4-mod14} the line break denoted by $\BodyStartsOnOwnLine$ in + \cref{lst:mlb4} has been removed; + \item \cref{lst:env-mlb4-mod15} the line break denoted by $\EndStartsOnOwnLine$ in + \cref{lst:mlb4} has been removed; + \item \cref{lst:env-mlb4-mod16} the line break denoted by $\EndFinishesWithLineBreak$ in + \cref{lst:mlb4} has been removed. \end{itemize} - We examined each of these cases separately for clarity of explanation, but you can combine all of the YAML - settings in \crefrange{lst:env-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 + We examined each of these cases separately for clarity of explanation, but you can + 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 \begin{widepage} \begin{commandshell} latexindent.pl -m env-mlb4.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,env-mlb16.yaml @@ -914,10 +1287,12 @@ latexindent.pl -m env-mlb4.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,e which gives the output in \vref{lst:env-mlb1-tex}. \subsubsection{About trailing horizontal space} - Recall that on \cpageref{yaml:removeTrailingWhitespace} we discussed the YAML field \texttt{removeTrailingWhitespace}, - and that it has two (binary) switches to determine if horizontal space should be removed \texttt{beforeProcessing} and \texttt{afterProcessing}. - The \texttt{beforeProcessing} is particularly relevant when considering the \texttt{-m} switch; let's consider the - file shown in \cref{lst:mlb5}, which highlights trailing spaces. + Recall that on \cpageref{yaml:removeTrailingWhitespace} we discussed the YAML field + \texttt{removeTrailingWhitespace}, and that it has two (binary) switches to determine if + horizontal space should be removed \texttt{beforeProcessing} and + \texttt{afterProcessing}. The \texttt{beforeProcessing} is particularly relevant + when considering the \texttt{-m} switch; let's consider the file shown in + \cref{lst:mlb5}, which highlights trailing spaces. \begin{minipage}{.45\linewidth} \begin{cmhlistings}[style=tcblatex,showspaces=true,escapeinside={(*@}{@*)}]{\texttt{env-mlb5.tex}}{lst:mlb5} @@ -940,9 +1315,10 @@ latexindent.pl -m env-mlb5.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,e latexindent.pl -m env-mlb5.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,env-mlb16.yaml,removeTWS-before.yaml \end{commandshell} \end{widepage} - is shown, respectively, in \cref{lst:env-mlb5-modAll,lst:env-mlb5-modAll-remove-WS}; note that - the trailing horizontal white space has been preserved (by default) in \cref{lst:env-mlb5-modAll}, while - in \cref{lst:env-mlb5-modAll-remove-WS}, it has been removed using the switch specified in \cref{lst:removeTWS-before}. + is shown, respectively, in \cref{lst:env-mlb5-modAll,lst:env-mlb5-modAll-remove-WS}; note that the trailing horizontal + white space has been preserved (by default) in \cref{lst:env-mlb5-modAll}, while in + \cref{lst:env-mlb5-modAll-remove-WS}, it has been removed using the switch specified in + \cref{lst:removeTWS-before}. \begin{widepage} \cmhlistingsfromfile[showspaces=true]{demonstrations/env-mlb5-modAll.tex}{\texttt{env-mlb5.tex} using \crefrange{lst:env-mlb4-mod13}{lst:env-mlb4-mod16}}{lst:env-mlb5-modAll} @@ -982,10 +1358,12 @@ latexindent.pl -m env-mlb6.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,e \end{commandshell} \end{widepage} we receive the respective outputs in \cref{lst:env-mlb6-modAll,lst:env-mlb6-modAll-un-Preserve-Blank-Lines}. In - \cref{lst:env-mlb6-modAll} we see that the multiple blank lines have each been condensed into one blank line, - but that blank lines have \emph{not} been removed by the poly-switches -- this is because, by default, \texttt{preserveBlankLines} - is set to \texttt{1}. By contrast, in \cref{lst:env-mlb6-modAll-un-Preserve-Blank-Lines}, we have allowed - the poly-switches to remove blank lines because, in \cref{lst:UnpreserveBlankLines}, we have set \texttt{preserveBlankLines} to \texttt{0}. + \cref{lst:env-mlb6-modAll} we see that the multiple blank lines have each been condensed + into one blank line, but that blank lines have \emph{not} been removed + by the poly-switches -- this is because, by default, \texttt{preserveBlankLines} is set + to \texttt{1}. By contrast, in \cref{lst:env-mlb6-modAll-un-Preserve-Blank-Lines}, we have + allowed the poly-switches to remove blank lines because, in \cref{lst:UnpreserveBlankLines}, + we have set \texttt{preserveBlankLines} to \texttt{0}. \begin{widepage} \begin{minipage}{.30\linewidth} @@ -997,8 +1375,8 @@ latexindent.pl -m env-mlb6.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,e \end{minipage} \end{widepage} - We can explore this further using the blank-line poly-switch value of $3$; let's use the file given - in \cref{lst:env-mlb7-tex}. + We can explore this further using the blank-line poly-switch value of + $3$; let's use the file given in \cref{lst:env-mlb7-tex}. \cmhlistingsfromfile{demonstrations/env-mlb7.tex}{\texttt{env-mlb7.tex}}{lst:env-mlb7-tex} @@ -1014,18 +1392,24 @@ latexindent.pl -m env-mlb7.tex -l env-mlb13.yaml,env-mlb14.yaml,UnpreserveBlankL Notice that in: \begin{itemize} - \item \cref{lst:env-mlb7-preserve} that \lstinline!\end{one}! has added a blank line, because of the value of - \texttt{EndFinishesWithLineBreak} in \vref{lst:env-mlb12}, and even though the line break ahead of \lstinline!\begin{two}! should have been removed - (because of \texttt{BeginStartsOnOwnLine} in \vref{lst:env-mlb13}), the blank line has been preserved by default; - \item \cref{lst:env-mlb7-no-preserve}, by contrast, has had the additional line-break removed, because of - the settings in \cref{lst:UnpreserveBlankLines}. + \item \cref{lst:env-mlb7-preserve} that \lstinline!\end{one}! has added a blank line, + because of the value of \texttt{EndFinishesWithLineBreak} in \vref{lst:env-mlb12}, and + even though the line break ahead of \lstinline!\begin{two}! should have been removed + (because of \texttt{BeginStartsOnOwnLine} in \vref{lst:env-mlb13}), the blank line + has been preserved by default; + \item \cref{lst:env-mlb7-no-preserve}, by contrast, has had the additional line-break removed, + because of the settings in \cref{lst:UnpreserveBlankLines}. \end{itemize} \subsection{Poly-switches for other code blocks} - Rather than repeat the examples shown for the environment code blocks (in \vref{sec:modifylinebreaks-environments}), we choose to detail the poly-switches for - all other code blocks in \cref{tab:poly-switch-mapping}; note that each and every one of these poly-switches is \emph{off by default}, i.e, set to \texttt{0}. Note also that, - by design, line breaks involving \texttt{verbatim}, \texttt{filecontents} and `comment-marked' code blocks (\vref{lst:alignmentmarkup}) can \emph{not} be - modified using \texttt{latexindent.pl}. + Rather than repeat the examples shown for the environment code blocks (in + \vref{sec:modifylinebreaks-environments}), we choose to detail the poly-switches for all other code + blocks in \cref{tab:poly-switch-mapping}; note that each and every one of these + poly-switches is \emph{off by default}, i.e, set to \texttt{0}. + Note also that, by design, line breaks involving \texttt{verbatim}, + \texttt{filecontents} and `comment-marked' code blocks + (\vref{lst:alignmentmarkup}) can \emph{not} be modified using + \texttt{latexindent.pl}. \begin{longtable}{llll} \caption{Poly-switch mappings for all code-block types}\label{tab:poly-switch-mapping} \\ @@ -1041,7 +1425,7 @@ latexindent.pl -m env-mlb7.tex -l env-mlb13.yaml,env-mlb14.yaml,UnpreserveBlankL ifelsefi & \verb!before words!$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & IfStartsOnOwnLine \\ & \verb!\if...!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & BodyStartsOnOwnLine \\ & \verb!body of if/or statement!$\OrStartsOnOwnLine$ & $\OrStartsOnOwnLine$ & OrStartsOnOwnLine % - \announce*{2018-04-27}{new ifElseFi code block polyswitches} \\ + \announce{2018-04-27}{new ifElseFi code block polyswitches} \\ & \verb!\or!$\OrFinishesWithLineBreak$ & $\OrFinishesWithLineBreak$ & OrFinishesWithLineBreak \\ & \verb!body of if/or statement!$\ElseStartsOnOwnLine$ & $\ElseStartsOnOwnLine$ & ElseStartsOnOwnLine \\ & \verb!\else!$\ElseFinishesWithLineBreak$ & $\ElseFinishesWithLineBreak$ & ElseFinishesWithLineBreak \\ @@ -1080,7 +1464,7 @@ latexindent.pl -m env-mlb7.tex -l env-mlb13.yaml,env-mlb14.yaml,UnpreserveBlankL specialBeginEnd & before words$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & SpecialBeginStartsOnOwnLine \\ & \verb!\[!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & SpecialBodyStartsOnOwnLine \\ & \verb!body of special/middle!$\ElseStartsOnOwnLine$ & $\ElseStartsOnOwnLine$ & SpecialMiddleStartsOnOwnLine % - \announce*{2018-04-27}{new special code block polyswitches} \\ + \announce{2018-04-27}{new special code block polyswitches} \\ & \verb!\middle!$\ElseFinishesWithLineBreak$ & $\ElseFinishesWithLineBreak$ & SpecialMiddleFinishesWithLineBreak \\ & body of special/middle $\EndStartsOnOwnLine$ & $\EndStartsOnOwnLine$ & SpecialEndStartsOnOwnLine \\ & \verb!\]!$\EndFinishesWithLineBreak$ & $\EndFinishesWithLineBreak$ & SpecialEndFinishesWithLineBreak \\ 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 2f4412faffd..a6caa007060 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 @@ -1,21 +1,23 @@ % arara: pdflatex: {shell: yes, files: [latexindent]} \subsection{Commands and the strings between their arguments}\label{subsec:commands-string-between} - The \texttt{command} code blocks will always look for optional (square bracketed) and - mandatory (curly braced) arguments which can contain comments, line breaks and - `beamer' commands \lstinline!<.*?>! between them. There are switches that can allow them to contain - other strings, which we discuss next. + The \texttt{command} code blocks will always look for optional (square bracketed) + and mandatory (curly braced) arguments which can contain comments, line breaks and + `beamer' commands \lstinline!<.*?>! between them. There are switches that can allow + them to contain other strings, which we discuss next. \yamltitle{commandCodeBlocks}*{fields} - The \texttt{commandCodeBlocks} field% - \announce*{2018-04-27}*{commandCodeBlocks} contains a few switches detailed in \cref{lst:commandCodeBlocks}. + The \texttt{commandCodeBlocks} field%%%% + \announce{2018-04-27}*{commandCodeBlocks} + contains a few switches detailed in \cref{lst:commandCodeBlocks}. - \cmhlistingsfromfile*[style=commandCodeBlocks]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{commandCodeBlocks}}{lst:commandCodeBlocks} + \cmhlistingsfromfile[style=commandCodeBlocks]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{commandCodeBlocks}}{lst:commandCodeBlocks} \yamltitle{roundParenthesesAllowed}{0|1} - The need for this field was mostly motivated by commands found in code used to generate images in \texttt{PSTricks} and \texttt{tikz}; for example, - let's consider the code given in \cref{lst:pstricks1}. + The need for this field was mostly motivated by commands found in code used to generate + images in \texttt{PSTricks} and \texttt{tikz}; for example, let's consider + the code given in \cref{lst:pstricks1}. \begin{minipage}{.45\textwidth} \cmhlistingsfromfile{demonstrations/pstricks1.tex}{\texttt{pstricks1.tex}}{lst:pstricks1} @@ -28,12 +30,15 @@ Notice that the \lstinline!\defFunction! command has an optional argument, followed by a mandatory argument, followed by a round-parenthesis argument, $(u,v)$. - By default, because \texttt{roundParenthesesAllowed} is set to $1$ in \cref{lst:commandCodeBlocks}, then \texttt{latexindent.pl} - will allow round parenthesis between optional and mandatory arguments. In the case of the code in \cref{lst:pstricks1}, - \texttt{latexindent.pl} finds \emph{all} the arguments of \lstinline!defFunction!, both before and after \lstinline!(u,v)!. + By default, because \texttt{roundParenthesesAllowed} is set to $1$ in + \cref{lst:commandCodeBlocks}, then \texttt{latexindent.pl} will allow round parenthesis between + optional and mandatory arguments. In the case of the code in \cref{lst:pstricks1}, + \texttt{latexindent.pl} finds \emph{all} the arguments of + \lstinline!defFunction!, both before and after \lstinline!(u,v)!. - The default output from running \texttt{latexindent.pl} on \cref{lst:pstricks1} actually leaves it unchanged (see \cref{lst:pstricks1-default}); - note in particular, this is because of \texttt{noAdditionalIndentGlobal} as discussed on \cpageref{page:command:noAddGlobal}. + The default output from running \texttt{latexindent.pl} on \cref{lst:pstricks1} actually + leaves it unchanged (see \cref{lst:pstricks1-default}); note in particular, this is because of + \texttt{noAdditionalIndentGlobal} as discussed on \cpageref{page:command:noAddGlobal}. Upon using the YAML settings in \cref{lst:noRoundParentheses}, and running the command \begin{commandshell} @@ -49,10 +54,13 @@ latexindent.pl pstricks1.tex -l noRoundParentheses.yaml \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/noRoundParentheses.yaml}[yaml-TCB]{\texttt{noRoundParentheses.yaml}}{lst:noRoundParentheses} \end{minipage} - Notice the difference between \cref{lst:pstricks1-default} and \cref{lst:pstricks1-nrp}; in particular, in \cref{lst:pstricks1-nrp}, because - round parentheses are \emph{not} allowed, \texttt{latexindent.pl} finds that the \lstinline!\defFunction! command finishes at the first opening - round parenthesis. As such, the remaining braced, mandatory, arguments are found to be \texttt{UnNamedGroupingBracesBrackets} (see \vref{tab:code-blocks}) - which, by default, assume indentation for their body, and hence the tabbed indentation in \cref{lst:pstricks1-nrp}. + Notice the difference between \cref{lst:pstricks1-default} and \cref{lst:pstricks1-nrp}; in + particular, in \cref{lst:pstricks1-nrp}, because round parentheses are + \emph{not} allowed, \texttt{latexindent.pl} finds that the + \lstinline!\defFunction! command finishes at the first opening round parenthesis. As such, + the remaining braced, mandatory, arguments are found to be \texttt{UnNamedGroupingBracesBrackets} (see \vref{tab:code-blocks}) which, + by default, assume indentation for their body, and hence the tabbed indentation in + \cref{lst:pstricks1-nrp}. Let's explore this using the YAML given in \cref{lst:defFunction} and run the command \begin{commandshell} @@ -68,11 +76,14 @@ latexindent.pl pstricks1.tex -l defFunction.yaml \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/defFunction.yaml}[yaml-TCB]{\texttt{defFunction.yaml}}{lst:defFunction} \end{minipage} - Notice in \cref{lst:pstricks1-indent-rules} that the \emph{body} of the \lstinline!defFunction! command i.e, the subsequent lines - containing arguments after the command name, have received the single space of indentation specified by \cref{lst:defFunction}. + Notice in \cref{lst:pstricks1-indent-rules} that the \emph{body} of the + \lstinline!defFunction! command i.e, the subsequent lines containing arguments after the + command name, have received the single space of indentation specified by + \cref{lst:defFunction}. \yamltitle{stringsAllowedBetweenArguments}*{fields} - \texttt{tikz} users may well specify code such as that given in \cref{lst:tikz-node1}; processing this code using + \texttt{tikz} users may well specify code such as that given in + \cref{lst:tikz-node1}; processing this code using \texttt{latexindent.pl} gives the default output in \cref{lst:tikz-node1-default}. \begin{minipage}{.45\textwidth} @@ -87,21 +98,24 @@ latexindent.pl pstricks1.tex -l defFunction.yaml \begin{quote} to, node, ++ \end{quote} - are all allowed to appear between arguments; importantly, you are encouraged to add further names - to this field as necessary. This means that when \texttt{latexindent.pl} + are all allowed to appear between arguments; importantly, you are encouraged to add + further names to this field as necessary. This means that when \texttt{latexindent.pl} processes \cref{lst:tikz-node1}, it consumes: \begin{itemize} \item the optional argument \lstinline![thin]! - \item the round-bracketed argument \lstinline!(c)! because \texttt{roundParenthesesAllowed} is $1$ by default + \item the round-bracketed argument \lstinline!(c)! because \texttt{roundParenthesesAllowed} is + $1$ by default \item the string \lstinline!to! (specified in \texttt{stringsAllowedBetweenArguments}) \item the optional argument \lstinline![in=110,out=-90]! \item the string \lstinline!++! (specified in \texttt{stringsAllowedBetweenArguments}) - \item the round-bracketed argument \lstinline!(0,-0.5cm)! because \texttt{roundParenthesesAllowed} is $1$ by default + \item the round-bracketed argument \lstinline!(0,-0.5cm)! because \texttt{roundParenthesesAllowed} is + $1$ by default \item the string \lstinline!node! (specified in \texttt{stringsAllowedBetweenArguments}) \item the optional argument \lstinline![below,align=left,scale=0.5]! \end{itemize} - We can explore this further, for example using \cref{lst:draw} and running the command + We can explore this further, for example using \cref{lst:draw} and running the + command \begin{commandshell} latexindent.pl tikz-node1.tex -l draw.yaml \end{commandshell} @@ -115,10 +129,12 @@ latexindent.pl tikz-node1.tex -l draw.yaml \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/draw.yaml}[yaml-TCB]{\texttt{draw.yaml}}{lst:draw} \end{minipage} - Notice that each line after the \lstinline!\draw! command (its `body') in \cref{lst:tikz-node1-draw} has been given the - appropriate two-spaces worth of indentation specified in \cref{lst:draw}. + Notice that each line after the \lstinline!\draw! command (its `body') in + \cref{lst:tikz-node1-draw} has been given the appropriate two-spaces worth of indentation + specified in \cref{lst:draw}. - Let's compare this with the output from using the YAML settings in \cref{lst:no-strings}, and running the command + Let's compare this with the output from using the YAML settings in + \cref{lst:no-strings}, and running the command \begin{commandshell} latexindent.pl tikz-node1.tex -l no-strings.yaml \end{commandshell} @@ -129,83 +145,96 @@ latexindent.pl tikz-node1.tex -l no-strings.yaml \end{minipage} \hfill \begin{minipage}{.49\textwidth} - \cmhlistingsfromfile*[style=yaml-LST]*{demonstrations/no-strings.yaml}[yaml-TCB]{\texttt{no-strings.yaml}}{lst:no-strings} + \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/no-strings.yaml}[yaml-TCB]{\texttt{no-strings.yaml}}{lst:no-strings} \end{minipage} In this case, \texttt{latexindent.pl} sees that: \begin{itemize} - \item the \lstinline!\draw! command finishes after the \lstinline!(c)!, as \texttt{stringsAllowedBetweenArguments} has been set to $0$ - so there are no strings allowed between arguments; - \item it finds a \texttt{namedGroupingBracesBrackets} called \texttt{to} (see \vref{tab:code-blocks}) \emph{with} argument \lstinline![in=110,out=-90]! - \item it finds another \texttt{namedGroupingBracesBrackets} but this time called \texttt{node} with argument \lstinline![below,align=left,scale=0.5]! + \item the \lstinline!\draw! command finishes after the \lstinline!(c)!, as + \texttt{stringsAllowedBetweenArguments} has been set to $0$ so there are no strings + allowed between arguments; + \item it finds a \texttt{namedGroupingBracesBrackets} called \texttt{to} (see \vref{tab:code-blocks}) \emph{with} + argument \lstinline![in=110,out=-90]! + \item it finds another \texttt{namedGroupingBracesBrackets} but this time called \texttt{node} with + argument \lstinline![below,align=left,scale=0.5]! \end{itemize} Referencing \vref{lst:commandCodeBlocks},% - \announce*{2018-04-27}*{amalgamate feature in commandCodeBlocks}, we see that the first field in - the \texttt{stringsAllowedBetweenArguments} is \texttt{amalgamate} and is set to \texttt{1} by default. This is for users who wish to - specify their settings in multiple YAML files. For example, by using the settings in either \cref{lst:amalgamate-demo} or\cref{lst:amalgamate-demo1} - is equivalent to using the settings in \cref{lst:amalgamate-demo2}. + \announce{2018-04-27}*{amalgamate feature in commandCodeBlocks}, we see that the first field in the \texttt{stringsAllowedBetweenArguments} is + \texttt{amalgamate} and is set to \texttt{1} by default. This is for + users who wish to specify their settings in multiple YAML files. For example, by using + the settings in either \cref{lst:amalgamate-demo} or\cref{lst:amalgamate-demo1} is equivalent to + using the settings in \cref{lst:amalgamate-demo2}. \begin{adjustwidth}{-3.5cm}{-1.5cm} \begin{minipage}{.32\linewidth} - \cmhlistingsfromfile*[style=yaml-LST]*{demonstrations/amalgamate-demo.yaml}[yaml-TCB]{\texttt{amalgamate-demo.yaml}}{lst:amalgamate-demo} + \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/amalgamate-demo.yaml}[yaml-TCB]{\texttt{amalgamate-demo.yaml}}{lst:amalgamate-demo} \end{minipage}% \hfill \begin{minipage}{.32\linewidth} - \cmhlistingsfromfile*[style=yaml-LST]*{demonstrations/amalgamate-demo1.yaml}[yaml-TCB]{\texttt{amalgamate-demo1.yaml}}{lst:amalgamate-demo1} + \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/amalgamate-demo1.yaml}[yaml-TCB]{\texttt{amalgamate-demo1.yaml}}{lst:amalgamate-demo1} \end{minipage}% \hfill \begin{minipage}{.32\linewidth} - \cmhlistingsfromfile*[style=yaml-LST]*{demonstrations/amalgamate-demo2.yaml}[yaml-TCB]{\texttt{amalgamate-demo2.yaml}}{lst:amalgamate-demo2} + \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/amalgamate-demo2.yaml}[yaml-TCB]{\texttt{amalgamate-demo2.yaml}}{lst:amalgamate-demo2} \end{minipage} \end{adjustwidth} - We specify \texttt{amalgamate} to be set to \texttt{0} and in which case any settings loaded prior - to those specified, including the default, will be overwritten. For example, using the settings - in \cref{lst:amalgamate-demo3} means that only the strings specified in that field will be used. + We specify \texttt{amalgamate} to be set to \texttt{0} and in which case + any settings loaded prior to those specified, including the default, will be overwritten. + For example, using the settings in \cref{lst:amalgamate-demo3} means that only the strings + specified in that field will be used. - \cmhlistingsfromfile*[style=yaml-LST]*{demonstrations/amalgamate-demo3.yaml}[yaml-TCB]{\texttt{amalgamate-demo3.yaml}}{lst:amalgamate-demo3} + \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/amalgamate-demo3.yaml}[yaml-TCB]{\texttt{amalgamate-demo3.yaml}}{lst:amalgamate-demo3} - It is important to note that the \texttt{amalgamate} field, if used, must be in the first field, - and specified using the syntax given in \cref{lst:amalgamate-demo1,lst:amalgamate-demo2,lst:amalgamate-demo3}. + It is important to note that the \texttt{amalgamate} field, if used, must be in the + first field, and specified using the syntax given in \cref{lst:amalgamate-demo1,lst:amalgamate-demo2,lst:amalgamate-demo3}. - We may explore this feature further with the code in \cref{lst:for-each}, whose default output is given in \cref{lst:for-each-default}. + We may explore this feature further with the code in \cref{lst:for-each}, whose + default output is given in \cref{lst:for-each-default}. \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile*{demonstrations/for-each.tex}{\texttt{for-each.tex}}{lst:for-each} + \cmhlistingsfromfile{demonstrations/for-each.tex}{\texttt{for-each.tex}}{lst:for-each} \end{minipage} \hfill \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile*{demonstrations/for-each-default.tex}{\texttt{for-each} default output}{lst:for-each-default} + \cmhlistingsfromfile{demonstrations/for-each-default.tex}{\texttt{for-each} default output}{lst:for-each-default} \end{minipage} - Let's compare this with the output from using the YAML settings in \cref{lst:foreach}, and running the command + Let's compare this with the output from using the YAML settings in + \cref{lst:foreach}, and running the command \begin{commandshell} latexindent.pl for-each.tex -l foreach.yaml \end{commandshell} given in \cref{lst:for-each-mod1}. \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile*{demonstrations/for-each-mod1.tex}{\texttt{for-each.tex} using \cref{lst:foreach}}{lst:for-each-mod1} + \cmhlistingsfromfile{demonstrations/for-each-mod1.tex}{\texttt{for-each.tex} using \cref{lst:foreach}}{lst:for-each-mod1} \end{minipage} \hfill \begin{minipage}{.49\textwidth} - \cmhlistingsfromfile*[style=yaml-LST]*{demonstrations/foreach.yaml}[yaml-TCB]{\texttt{foreach.yaml}}{lst:foreach} + \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/foreach.yaml}[yaml-TCB]{\texttt{foreach.yaml}}{lst:foreach} \end{minipage} - You might like to compare the output given in \cref{lst:for-each-default} and \cref{lst:for-each-mod1}. Note,in particular, in - \cref{lst:for-each-default} that the \texttt{foreach} command has not included any of the subsequent strings, and that the braces - have been treated as a \texttt{namedGroupingBracesBrackets}. In \cref{lst:for-each-mod1} the \texttt{foreach} command has been allowed to have \lstinline!\x/\y! and \texttt{in} between - arguments because of the settings given in \cref{lst:foreach}. + You might like to compare the output given in \cref{lst:for-each-default} and + \cref{lst:for-each-mod1}. Note,in particular, in \cref{lst:for-each-default} that the + \texttt{foreach} command has not included any of the subsequent strings, and that + the braces have been treated as a \texttt{namedGroupingBracesBrackets}. In \cref{lst:for-each-mod1} the + \texttt{foreach} command has been allowed to have \lstinline!\x/\y! and + \texttt{in} between arguments because of the settings given in + \cref{lst:foreach}. \yamltitle{commandNameSpecial}*{fields} There are some special command names% - \announce*{2018-04-27}*{commandNameSpecial} that do not fit within the names recognized by \texttt{latexindent.pl}, - the first one of which is \lstinline!\@ifnextchar[!. From the perspective of \texttt{latexindent.pl}, the whole of the - text \lstinline!\@ifnextchar[! is a command, because it is - immediately followed by sets of mandatory arguments. However, without the \texttt{commandNameSpecial} field, \texttt{latexindent.pl} - would not be able to label it as such, because the \lstinline![! is, necessarily, not matched by a closing \lstinline!]!. + \announce{2018-04-27}*{commandNameSpecial} that do not fit within the names recognized by + \texttt{latexindent.pl}, the first one of which is \lstinline!\@ifnextchar[!. From the + perspective of \texttt{latexindent.pl}, the whole of the text \lstinline!\@ifnextchar[! is + a command, because it is immediately followed by sets of mandatory arguments. However, + without the \texttt{commandNameSpecial} field, \texttt{latexindent.pl} would not be able to + label it as such, because the \lstinline![! is, necessarily, not matched by a + closing \lstinline!]!. - For example, consider the sample file in \cref{lst:ifnextchar}, which has default output in \cref{lst:ifnextchar-default}. + For example, consider the sample file in \cref{lst:ifnextchar}, which has default + output in \cref{lst:ifnextchar-default}. \begin{minipage}{.45\textwidth} \cmhlistingsfromfile{demonstrations/ifnextchar.tex}{\texttt{ifnextchar.tex}}{lst:ifnextchar} @@ -215,26 +244,29 @@ latexindent.pl for-each.tex -l foreach.yaml \cmhlistingsfromfile{demonstrations/ifnextchar-default.tex}{\texttt{ifnextchar.tex} default output}{lst:ifnextchar-default} \end{minipage} - Notice that in \cref{lst:ifnextchar-default} the \texttt{parbox} command has been able to indent its body, because \texttt{latexindent.pl} - has successfully found the command \lstinline!\@ifnextchar! first; the pattern-matching of \texttt{latexindent.pl} starts from - \emph{the inner most and works outwards}, discussed in more detail on \cpageref{page:phases}. + Notice that in \cref{lst:ifnextchar-default} the \texttt{parbox} command has been able + to indent its body, because \texttt{latexindent.pl} has successfully found the command + \lstinline!\@ifnextchar! first; the pattern-matching of \texttt{latexindent.pl} starts + from \emph{the inner most and works outwards}, discussed in more detail on \cpageref{page:phases}. - For demonstration, we can compare - this output with that given in \cref{lst:ifnextchar-off} in which - the settings from \cref{lst:no-ifnextchar} have dictated that no special command names, including the \lstinline!\@ifnextchar[! command, should not be searched for specially; - as such, the \texttt{parbox} command has been \emph{unable} to indent its body successfully, because the \lstinline!\@ifnextchar[! - command has not been found. + For demonstration, we can compare this output with that given in \cref{lst:ifnextchar-off} + in which the settings from \cref{lst:no-ifnextchar} have dictated that no special command + names, including the \lstinline!\@ifnextchar[! command, should not be searched for + specially; as such, the \texttt{parbox} command has been \emph{unable} + to indent its body successfully, because the \lstinline!\@ifnextchar[! command has not been + found. \begin{minipage}{.45\textwidth} \cmhlistingsfromfile{demonstrations/ifnextchar-off.tex}{\texttt{ifnextchar.tex} using \cref{lst:no-ifnextchar}}{lst:ifnextchar-off} \end{minipage} \hfill \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile*[style=yaml-LST]*{demonstrations/no-ifnextchar.yaml}[yaml-TCB]{\texttt{no-ifnextchar.yaml}}{lst:no-ifnextchar} + \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/no-ifnextchar.yaml}[yaml-TCB]{\texttt{no-ifnextchar.yaml}}{lst:no-ifnextchar} \end{minipage} - 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: + 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: \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 d6c158a3206..2a5d0bcd340 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 @@ -1,7 +1,8 @@ % arara: pdflatex: {shell: yes, files: [latexindent]} \subsection{Conflicting poly-switches: sequential code blocks} - 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 + 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 \begin{commandshell} latexindent.pl -m -l=mycom-mlb4.yaml mycommand1.tex \end{commandshell} @@ -15,16 +16,20 @@ latexindent.pl -m -l=mycom-mlb4.yaml mycommand1.tex \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/mycom-mlb4.yaml}[MLB-TCB,width=\linewidth]{\texttt{mycom-mlb4.yaml}}{lst:mycom-mlb4} \end{minipage} - Studying \cref{lst:mycom-mlb4}, we see that the two poly-switches are at opposition with one another: + Studying \cref{lst:mycom-mlb4}, we see that the two poly-switches are at opposition with + one another: \begin{itemize} - \item on the one hand, \texttt{LCuBStartsOnOwnLine} should \emph{not} start on its own line (as poly-switch is set to $-1$); + \item on the one hand, \texttt{LCuBStartsOnOwnLine} should \emph{not} start on its own line + (as poly-switch is set to $-1$); \item on the other hand, \texttt{RCuBFinishesWithLineBreak} \emph{should} finish with a line break. \end{itemize} - So, which should win the conflict? As demonstrated in \cref{lst:mycommand1-mlb4}, it is clear that \texttt{LCuBStartsOnOwnLine} won - this conflict, and the reason is that \emph{the second argument was processed after the first} -- in general, the most recently-processed - code block and associated poly-switch takes priority. + So, which should win the conflict? As demonstrated in \cref{lst:mycommand1-mlb4}, it is clear + that \texttt{LCuBStartsOnOwnLine} won this conflict, and the reason is that + \emph{the second argument was processed after the first} -- in general, the most recently-processed code block and + associated poly-switch takes priority. - We can explore this further by considering the YAML settings in \cref{lst:mycom-mlb5}; upon running the command + We can explore this further by considering the YAML settings in \cref{lst:mycom-mlb5}; + upon running the command \begin{commandshell} latexindent.pl -m -l=mycom-mlb5.yaml mycommand1.tex \end{commandshell} @@ -38,8 +43,10 @@ latexindent.pl -m -l=mycom-mlb5.yaml mycommand1.tex \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/mycom-mlb5.yaml}[MLB-TCB,width=\linewidth]{\texttt{mycom-mlb5.yaml}}{lst:mycom-mlb5} \end{minipage} - As previously, the most-recently-processed code block takes priority -- as before, the second (i.e, \emph{last}) argument. Exploring this - further, we consider the YAML settings in \cref{lst:mycom-mlb6}, which give associated output in \cref{lst:mycommand1-mlb6}. + As previously, the most-recently-processed code block takes priority -- as before, the + second (i.e, \emph{last}) argument. Exploring this further, we consider the + YAML settings in \cref{lst:mycom-mlb6}, which give associated output in + \cref{lst:mycommand1-mlb6}. \begin{minipage}{.4\linewidth} \cmhlistingsfromfile{demonstrations/mycommand1-mlb6.tex}{\texttt{mycommand1.tex} using \cref{lst:mycom-mlb6}}{lst:mycommand1-mlb6} @@ -49,20 +56,26 @@ latexindent.pl -m -l=mycom-mlb5.yaml mycommand1.tex \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/mycom-mlb6.yaml}[MLB-TCB,width=\linewidth]{\texttt{mycom-mlb6.yaml}}{lst:mycom-mlb6} \end{minipage} - Note that a \lstinline!%! \emph{has} been added to the trailing first \lstinline!}!; this is because: + Note that a \lstinline!%! \emph{has} been added to the trailing + first \lstinline!}!; this is because: \begin{itemize} - \item while processing the \emph{first} argument, the trailing line break has been removed (\texttt{RCuBFinishesWithLineBreak} set to $-1$); - \item while processing the \emph{second} argument, \texttt{latexindent.pl} finds that it does \emph{not} begin on its own line, and so - because \texttt{LCuBStartsOnOwnLine} is set to $2$, it adds a comment, followed by a line break. + \item while processing the \emph{first} argument, the trailing line break has been + removed (\texttt{RCuBFinishesWithLineBreak} set to $-1$); + \item while processing the \emph{second} argument, \texttt{latexindent.pl} finds that + it does \emph{not} begin on its own line, and so because + \texttt{LCuBStartsOnOwnLine} is set to $2$, it adds a comment, followed by a + line break. \end{itemize} \subsection{Conflicting poly-switches: nested code blocks} - 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. + 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. \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 + Let's use the YAML settings given in \cref{lst:nested-env-mlb1-yaml}, which upon running the + command \begin{commandshell} latexindent.pl -m -l=nested-env-mlb1.yaml nested-env.tex \end{commandshell} @@ -76,41 +89,61 @@ latexindent.pl -m -l=nested-env-mlb1.yaml nested-env.tex \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/nested-env-mlb1.yaml}[MLB-TCB,width=\linewidth]{\texttt{nested-env-mlb1.yaml}}{lst:nested-env-mlb1-yaml} \end{minipage} - In \cref{lst:nested-env-mlb1}, let's first of all note that both environments have received the appropriate (default) indentation; secondly, - note that the poly-switch \texttt{EndStartsOnOwnLine} appears to have won the conflict, as \lstinline!\end{one}! has had its leading line break removed. + In \cref{lst:nested-env-mlb1}, let's first of all note that both environments have received + the appropriate (default) indentation; secondly, note that the poly-switch + \texttt{EndStartsOnOwnLine} appears to have won the conflict, as \lstinline!\end{one}! has + had its leading line break removed. - To understand it, let's talk about the three basic phases \label{page:phases}of \texttt{latexindent.pl}: + To understand it, let's talk about the three basic phases \label{page:phases}of + \texttt{latexindent.pl}: \begin{enumerate} - \item Phase 1: packing, in which code blocks are replaced with unique ids, working from \emph{the inside to the outside}, and then sequentially -- for example, in - \cref{lst:nested-env}, the \texttt{two} environment is found \emph{before} the \texttt{one} environment; if the -m switch is active, then during this phase: + \item Phase 1: packing, in which code blocks are replaced with unique ids, working from + \emph{the inside to the outside}, and then sequentially -- for example, in \cref{lst:nested-env}, + the \texttt{two} environment is found \emph{before} the + \texttt{one} environment; if the -m switch is active, then during this phase: \begin{itemize} - \item line breaks at the beginning of the \texttt{body} can be added (if \texttt{BodyStartsOnOwnLine} is $1$ or $2$) or removed (if \texttt{BodyStartsOnOwnLine} is $-1$); - \item line breaks at the end of the body can be added (if \texttt{EndStartsOnOwnLine} is $1$ or $2$) or removed (if \texttt{EndStartsOnOwnLine} is $-1$); - \item line breaks after the end statement can be added (if \texttt{EndFinishesWithLineBreak} is $1$ or $2$). + \item line breaks at the beginning of the \texttt{body} can be added (if + \texttt{BodyStartsOnOwnLine} is $1$ or $2$) or removed (if + \texttt{BodyStartsOnOwnLine} is $-1$); + \item line breaks at the end of the body can be added (if \texttt{EndStartsOnOwnLine} is + $1$ or $2$) or removed (if \texttt{EndStartsOnOwnLine} is + $-1$); + \item line breaks after the end statement can be added (if \texttt{EndFinishesWithLineBreak} is + $1$ or $2$). \end{itemize} - \item Phase 2: indentation, in which white space is added to the begin, body, and end statements; - \item Phase 3: unpacking, in which unique ids are replaced by their \emph{indented} code blocks; if the -m switch is active, then during this phase, + \item Phase 2: indentation, in which white space is added to the begin, body, and end + statements; + \item Phase 3: unpacking, in which unique ids are replaced by their \emph{indented} code + blocks; if the -m switch is active, then during this phase, \begin{itemize} - \item line breaks before \texttt{begin} statements can be added or removed (depending upon \texttt{BeginStartsOnOwnLine}); - \item line breaks after \emph{end} statements can be removed but \emph{NOT} added (see \texttt{EndFinishesWithLineBreak}). + \item line breaks before \texttt{begin} statements can be added or removed (depending + upon \texttt{BeginStartsOnOwnLine}); + \item line breaks after \emph{end} statements can be removed but + \emph{NOT} added (see \texttt{EndFinishesWithLineBreak}). \end{itemize} \end{enumerate} With reference to \cref{lst:nested-env-mlb1}, this means that during Phase 1: \begin{itemize} - \item the \texttt{two} environment is found first, and - the line break ahead of the \lstinline!\end{two}! statement is removed because \texttt{EndStartsOnOwnLine} is set to $-1$. Importantly, - because, \emph{at this stage}, \lstinline!\end{two}! \emph{does} finish with a line break, \texttt{EndFinishesWithLineBreak} causes - no action. - \item next, the \texttt{one} environment is found; the line break ahead of \lstinline!\end{one}! is removed because \texttt{EndStartsOnOwnLine} - is set to $-1$. + \item the \texttt{two} environment is found first, and the line break ahead of the + \lstinline!\end{two}! statement is removed because \texttt{EndStartsOnOwnLine} is set to + $-1$. Importantly, because, \emph{at this stage}, + \lstinline!\end{two}! \emph{does} finish with a line break, + \texttt{EndFinishesWithLineBreak} causes no action. + \item next, the \texttt{one} environment is found; the line break ahead of + \lstinline!\end{one}! is removed because \texttt{EndStartsOnOwnLine} is set to + $-1$. \end{itemize} - The indentation is done in Phase 2; in Phase 3 \emph{there is no option to add a line break after the \lstinline!end! statements}. - We can justify this by remembering that during Phase 3, the \texttt{one} environment will be found and processed first, followed - by the \texttt{two} environment. If the \texttt{two} environment were to add a line break after the \lstinline!\end{two}! statement, then - \texttt{latexindent.pl} would have no way of knowing how much indentation to add to the subsequent text (in this case, \lstinline!\end{one}!). - - We can explore this further using the poly-switches in \cref{lst:nested-env-mlb2}; upon running the command + The indentation is done in Phase 2; in Phase 3 \emph{there is no option to add a line break after the \lstinline!end! statements}. We can justify + this by remembering that during Phase 3, the \texttt{one} environment will be + found and processed first, followed by the \texttt{two} environment. If the + \texttt{two} environment were to add a line break after the + \lstinline!\end{two}! statement, then \texttt{latexindent.pl} would have no way of + knowing how much indentation to add to the subsequent text (in this case, + \lstinline!\end{one}!). + + We can explore this further using the poly-switches in \cref{lst:nested-env-mlb2}; upon + running the command \begin{commandshell} latexindent.pl -m -l=nested-env-mlb2.yaml nested-env.tex \end{commandshell} @@ -126,12 +159,17 @@ latexindent.pl -m -l=nested-env-mlb2.yaml nested-env.tex During Phase 1: \begin{itemize} - \item the \texttt{two} environment is found first, and - the line break ahead of the \lstinline!\end{two}! statement is not changed because \texttt{EndStartsOnOwnLine} is set to $1$. - Importantly, because, \emph{at this stage}, \lstinline!\end{two}! \emph{does} finish with a line break, \texttt{EndFinishesWithLineBreak} causes - no action. - \item next, the \texttt{one} environment is found; the line break ahead of \lstinline!\end{one}! is already present, and no action is needed. + \item the \texttt{two} environment is found first, and the line break ahead of the + \lstinline!\end{two}! statement is not changed because \texttt{EndStartsOnOwnLine} is set to + $1$. Importantly, because, \emph{at this stage}, + \lstinline!\end{two}! \emph{does} finish with a line break, + \texttt{EndFinishesWithLineBreak} causes no action. + \item next, the \texttt{one} environment is found; the line break ahead of + \lstinline!\end{one}! is already present, and no action is needed. \end{itemize} - The indentation is done in Phase 2, and then in Phase 3, the \texttt{one} environment is found and processed first, followed by - the \texttt{two} environment. \emph{At this stage}, the \texttt{two} environment finds \texttt{EndFinishesWithLineBreak} is $-1$, so it removes - the trailing line break; remember, at this point, \texttt{latexindent.pl} has completely finished with the \texttt{one} environment. + The indentation is done in Phase 2, and then in Phase 3, the \texttt{one} + environment is found and processed first, followed by the \texttt{two} + environment. \emph{At this stage}, the \texttt{two} environment finds + \texttt{EndFinishesWithLineBreak} is $-1$, so it removes the trailing line break; + remember, at this point, \texttt{latexindent.pl} has completely finished with the + \texttt{one} environment. 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 b715abfae17..8f0a737a353 100644 --- a/Master/texmf-dist/doc/support/latexindent/subsec-noAdditionalIndent-indentRules.tex +++ b/Master/texmf-dist/doc/support/latexindent/subsec-noAdditionalIndent-indentRules.tex @@ -1,24 +1,27 @@ % arara: pdflatex: {shell: yes, files: [latexindent]} % arara: pdflatex: {shell: yes, files: [latexindent]} \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}; - for each type of code block in \vref{tab:code-blocks} (which we will call a \emph{$\langle$thing$\rangle$} in what follows) - it searches YAML fields for information in the following order: + \texttt{latexindent.pl} operates on files by looking for code blocks, as detailed in + \vref{subsubsec:code-blocks}; + for each type of code block in \vref{tab:code-blocks} (which we will call a \emph{$\langle$thing$\rangle$} in what follows) it searches YAML fields for + information in the following order: \begin{enumerate} \item \texttt{noAdditionalIndent} for the \emph{name} of the current \emph{$\langle$thing$\rangle$}; \item \texttt{indentRules} for the \emph{name} of the current \emph{$\langle$thing$\rangle$}; \item \texttt{noAdditionalIndentGlobal} for the \emph{type} of the current \emph{$\langle$thing$\rangle$}; - \item \texttt{indentRulesGlobal} for the \emph{type} of the current \emph{$\langle$thing$\rangle$}. + \item \texttt{indentRulesGlobal} for the \emph{type} of the current + \emph{$\langle$thing$\rangle$}. \end{enumerate} - Using the above list, the first piece of information to be found will be used; failing that, - the value of \texttt{defaultIndent} is used. - If information is found in multiple fields, the first one according to the list above will be used; for example, - if information is present in both \texttt{indentRules} and in \texttt{noAdditionalIndentGlobal}, then the information from \texttt{indentRules} - takes priority. + Using the above list, the first piece of information to be found will be used; failing + that, the value of \texttt{defaultIndent} is used. If information is found in multiple + fields, the first one according to the list above will be used; for example, if + information is present in both \texttt{indentRules} and in \texttt{noAdditionalIndentGlobal}, then + the information from \texttt{indentRules} takes priority. - We now present details for the different type of code blocks known to \texttt{latexindent.pl}, as detailed in \vref{tab:code-blocks}; for - reference, there follows a list of the code blocks covered. + We now present details for the different type of code blocks known to + \texttt{latexindent.pl}, as detailed in \vref{tab:code-blocks}; for reference, there + follows a list of the code blocks covered. \startcontents[noAdditionalIndent] \printcontents[noAdditionalIndent]{}{0}{} 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 2741dbcac12..05734f54bea 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 @@ -1,11 +1,13 @@ % arara: pdflatex: {shell: yes, files: [latexindent]} \subsection{Partnering BodyStartsOnOwnLine with argument-based poly-switches} - Some poly-switches need to be partnered together; in particular, when line breaks 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. + Some poly-switches need to be partnered together; in particular, when line breaks + 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. - 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 \texttt{CommandNameFinishesWithLineBreak} is an alias for \texttt{BodyStartsOnOwnLine}. + 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 + \texttt{CommandNameFinishesWithLineBreak} is an alias for \texttt{BodyStartsOnOwnLine}. \cmhlistingsfromfile{demonstrations/mycommand1.tex}{\texttt{mycommand1.tex}}{lst:mycommand1} @@ -13,8 +15,9 @@ \begin{commandshell} latexindent.pl -m -l=mycom-mlb1.yaml mycommand1.tex \end{commandshell} - we obtain \cref{lst:mycommand1-mlb1}; note that the \emph{second} mandatory argument beginning brace \lstinline!{! has had - its leading line break removed, but that the \emph{first} brace has not. + we obtain \cref{lst:mycommand1-mlb1}; note that the \emph{second} mandatory argument + beginning brace \lstinline!{! has had its leading line break removed, but that + the \emph{first} brace has not. \begin{minipage}{.4\linewidth} \cmhlistingsfromfile{demonstrations/mycommand1-mlb1.tex}{\texttt{mycommand1.tex} using \cref{lst:mycom-mlb1}}{lst:mycommand1-mlb1} @@ -24,8 +27,9 @@ latexindent.pl -m -l=mycom-mlb1.yaml mycommand1.tex \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/mycom-mlb1.yaml}[MLB-TCB,width=\linewidth]{\texttt{mycom-mlb1.yaml}}{lst:mycom-mlb1} \end{minipage} - Now let's change the YAML file so that it is as in \cref{lst:mycom-mlb2}; upon running the analogous command to that given above, - we obtain \cref{lst:mycommand1-mlb2}; both beginning braces \lstinline!{! have had their leading line breaks removed. + Now let's change the YAML file so that it is as in \cref{lst:mycom-mlb2}; upon running + the analogous command to that given above, we obtain \cref{lst:mycommand1-mlb2}; both + beginning braces \lstinline!{! have had their leading line breaks removed. \begin{minipage}{.4\linewidth} \cmhlistingsfromfile{demonstrations/mycommand1-mlb2.tex}{\texttt{mycommand1.tex} using \cref{lst:mycom-mlb2}}{lst:mycommand1-mlb2} @@ -35,8 +39,8 @@ latexindent.pl -m -l=mycom-mlb1.yaml mycommand1.tex \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/mycom-mlb2.yaml}[MLB-TCB,width=\linewidth]{\texttt{mycom-mlb2.yaml}}{lst:mycom-mlb2} \end{minipage} - Now let's change the YAML file so that it is as in \cref{lst:mycom-mlb3}; upon running the analogous command to that given above, - we obtain \cref{lst:mycommand1-mlb3}. + Now let's change the YAML file so that it is as in \cref{lst:mycom-mlb3}; upon running + the analogous command to that given above, we obtain \cref{lst:mycommand1-mlb3}. \begin{minipage}{.4\linewidth} \cmhlistingsfromfile{demonstrations/mycommand1-mlb3.tex}{\texttt{mycommand1.tex} using \cref{lst:mycom-mlb3}}{lst:mycommand1-mlb3} 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 633d74e700c..6e6b0074c1e 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 @@ -1,7 +1,8 @@ % arara: pdflatex: {shell: yes, files: [latexindent]} \subsubsection{Commands with arguments}\label{subsubsec:commands-arguments} - Let's begin with the simple example in \cref{lst:mycommand}; when \texttt{latexindent.pl} operates - on this file, the default output is shown in \cref{lst:mycommand-default}. \footnote{The command code blocks + Let's begin with the simple example in \cref{lst:mycommand}; when + \texttt{latexindent.pl} operates on this file, the default output is shown in + \cref{lst:mycommand-default}. \footnote{The command code blocks have quite a few subtleties, described in \vref{subsec:commands-string-between}.} \begin{minipage}{.45\textwidth} @@ -12,8 +13,9 @@ \cmhlistingsfromfile{demonstrations/mycommand-default.tex}{\texttt{mycommand.tex} default output}{lst:mycommand-default} \end{minipage} - As in the environment-based case (see \vref{lst:myenv-noAdd1,lst:myenv-noAdd2}) we may specify \texttt{noAdditionalIndent} - either in `scalar' form, or in `field' form, as shown in \cref{lst:mycommand-noAdd1,lst:mycommand-noAdd2} + As in the environment-based case (see \vref{lst:myenv-noAdd1,lst:myenv-noAdd2}) we may specify + \texttt{noAdditionalIndent} either in `scalar' form, or in `field' form, as shown in + \cref{lst:mycommand-noAdd1,lst:mycommand-noAdd2} \begin{minipage}{.45\textwidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/mycommand-noAdd1.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{mycommand-noAdd1.yaml}}{lst:mycommand-noAdd1} @@ -38,12 +40,14 @@ latexindent.pl mycommand.tex -l mycommand-noAdd2.yaml \cmhlistingsfromfile{demonstrations/mycommand-noAdd2.tex}{\texttt{mycommand.tex} using \cref{lst:mycommand-noAdd2}}{lst:mycommand-output-noAdd2} \end{minipage} - Note that in \cref{lst:mycommand-output-noAdd1} that the `body', optional argument \emph{and} mandatory argument have \emph{all} received - no additional indentation, while in \cref{lst:mycommand-output-noAdd2}, only the `body' has not received any additional indentation. We define - the `body' of a command as any lines following the command name that include its optional or mandatory arguments. + Note that in \cref{lst:mycommand-output-noAdd1} that the `body', optional argument + \emph{and} mandatory argument have \emph{all} received no + additional indentation, while in \cref{lst:mycommand-output-noAdd2}, only the `body' has not received + any additional indentation. We define the `body' of a command as any lines following the + command name that include its optional or mandatory arguments. - We may further customise \texttt{noAdditionalIndent} for \texttt{mycommand} as we did in \vref{lst:myenv-noAdd5,lst:myenv-noAdd6}; explicit examples - are given in \cref{lst:mycommand-noAdd3,lst:mycommand-noAdd4}. + We may further customise \texttt{noAdditionalIndent} for \texttt{mycommand} as we did in + \vref{lst:myenv-noAdd5,lst:myenv-noAdd6}; explicit examples are given in \cref{lst:mycommand-noAdd3,lst:mycommand-noAdd4}. \begin{minipage}{.45\textwidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/mycommand-noAdd3.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{mycommand-noAdd3.yaml}}{lst:mycommand-noAdd3} @@ -68,9 +72,11 @@ latexindent.pl mycommand.tex -l mycommand-noAdd4.yaml \cmhlistingsfromfile{demonstrations/mycommand-noAdd4.tex}{\texttt{mycommand.tex} using \cref{lst:mycommand-noAdd4}}{lst:mycommand-output-noAdd4} \end{minipage} - Attentive readers will note that the body of \texttt{mycommand} in both \cref{lst:mycommand-output-noAdd3,lst:mycommand-output-noAdd4} - has received no additional indent, even though \texttt{body} is explicitly set to \texttt{0} in both \cref{lst:mycommand-noAdd3,lst:mycommand-noAdd4}. - This is because, by default, \texttt{noAdditionalIndentGlobal} for \texttt{commands} is set to \texttt{1} by default; this can be easily + Attentive readers will note that the body of \texttt{mycommand} in both + \cref{lst:mycommand-output-noAdd3,lst:mycommand-output-noAdd4} has received no additional indent, even though + \texttt{body} is explicitly set to \texttt{0} in both + \cref{lst:mycommand-noAdd3,lst:mycommand-noAdd4}. This is because, by default, \texttt{noAdditionalIndentGlobal} for + \texttt{commands} is set to \texttt{1} by default; this can be easily fixed as in \cref{lst:mycommand-noAdd5,lst:mycommand-noAdd6}.\label{page:command:noAddGlobal} \begin{minipage}{.45\textwidth} @@ -96,5 +102,6 @@ latexindent.pl mycommand.tex -l mycommand-noAdd6.yaml \cmhlistingsfromfile{demonstrations/mycommand-noAdd6.tex}{\texttt{mycommand.tex} using \cref{lst:mycommand-noAdd6}}{lst:mycommand-output-noAdd6} \end{minipage} - Both \texttt{indentRules} and \texttt{indentRulesGlobal} can be adjusted as they were for \emph{environment} code blocks, as in - \vref{lst:myenv-rules3,lst:myenv-rules4} and \vref{lst:indentRulesGlobal:environments,lst:opt-args-indent-rules-glob,lst:mand-args-indent-rules-glob}. + Both \texttt{indentRules} and \texttt{indentRulesGlobal} can be adjusted as they were for + \emph{environment} code blocks, as in \vref{lst:myenv-rules3,lst:myenv-rules4} and + \vref{lst:indentRulesGlobal:environments,lst:opt-args-indent-rules-glob,lst:mand-args-indent-rules-glob}. 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 09b08ed1fdf..9a137aa622f 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 @@ -1,13 +1,13 @@ % arara: pdflatex: {shell: yes, files: [latexindent]} \subsubsection{Environments and their arguments}\label{subsubsec:env-and-their-args} - There are a few different YAML switches governing the indentation of environments; let's start - with the code shown in \cref{lst:myenvtex}. + There are a few different YAML switches governing the indentation of environments; let's + start with the code shown in \cref{lst:myenvtex}. \cmhlistingsfromfile{demonstrations/myenvironment-simple.tex}{\texttt{myenv.tex}}{lst:myenvtex} \yamltitle{noAdditionalIndent}*{fields} - If we do not wish \texttt{myenv} to receive any additional indentation, we have a few choices available to us, - as demonstrated in \cref{lst:myenv-noAdd1,lst:myenv-noAdd2}. + If we do not wish \texttt{myenv} to receive any additional indentation, we have a + few choices available to us, as demonstrated in \cref{lst:myenv-noAdd1,lst:myenv-noAdd2}. \begin{minipage}{.45\textwidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/myenv-noAdd1.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-noAdd1.yaml}}{lst:myenv-noAdd1} @@ -22,8 +22,9 @@ latexindent.pl myenv.tex -l myenv-noAdd1.yaml latexindent.pl myenv.tex -l myenv-noAdd2.yaml \end{commandshell} - we obtain the output given in \cref{lst:myenv-output}; note in particular that the environment \texttt{myenv} - has not received any \emph{additional} indentation, but that the \texttt{outer} environment \emph{has} still + we obtain the output given in \cref{lst:myenv-output}; note in particular that the + environment \texttt{myenv} has not received any \emph{additional} + indentation, but that the \texttt{outer} environment \emph{has} still received indentation. \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} @@ -45,18 +46,20 @@ latexindent.pl myenv.tex -l myenv-noAdd4.yaml \cmhlistingsfromfile{demonstrations/myenvironment-simple-noAdd-body4.tex}{\texttt{myenv.tex output} (using either \cref{lst:myenv-noAdd3} or \cref{lst:myenv-noAdd4})}{lst:myenv-output-4} - Let's now allow \texttt{myenv} to have some optional and mandatory arguments, as in \cref{lst:myenv-args}. - \cmhlistingsfromfile{demonstrations/myenvironment-args.tex}{\texttt{myenv-args.tex}}{lst:myenv-args} - Upon running + Let's now allow \texttt{myenv} to have some optional and mandatory arguments, as + in \cref{lst:myenv-args}. \cmhlistingsfromfile{demonstrations/myenvironment-args.tex}{\texttt{myenv-args.tex}}{lst:myenv-args} Upon running \begin{commandshell} latexindent.pl -l=myenv-noAdd1.yaml myenv-args.tex \end{commandshell} - we obtain the output shown in \cref{lst:myenv-args-noAdd1}; note that the optional argument, mandatory argument and body \emph{all} - have received no additional indent. This is because, when \texttt{noAdditionalIndent} is specified in `scalar' form (as in \cref{lst:myenv-noAdd1}), - then \emph{all} parts of the environment (body, optional and mandatory arguments) are assumed to want no additional indent. + we obtain the output shown in \cref{lst:myenv-args-noAdd1}; note that the optional argument, + mandatory argument and body \emph{all} have received no additional indent. + This is because, when \texttt{noAdditionalIndent} is specified in `scalar' form (as in + \cref{lst:myenv-noAdd1}), then \emph{all} parts of the environment (body, + optional and mandatory arguments) are assumed to want no additional indent. \cmhlistingsfromfile{demonstrations/myenvironment-args-noAdd-body1.tex}{\texttt{myenv-args.tex} using \cref{lst:myenv-noAdd1}}{lst:myenv-args-noAdd1} - We may customise \texttt{noAdditionalIndent} for optional and mandatory arguments of the \texttt{myenv} environment, as shown in, for example, \cref{lst:myenv-noAdd5,lst:myenv-noAdd6}. + We may customise \texttt{noAdditionalIndent} for optional and mandatory arguments of the + \texttt{myenv} environment, as shown in, for example, \cref{lst:myenv-noAdd5,lst:myenv-noAdd6}. \begin{minipage}{.49\textwidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/myenv-noAdd5.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-noAdd5.yaml}}{lst:myenv-noAdd5} @@ -71,9 +74,11 @@ latexindent.pl -l=myenv-noAdd1.yaml myenv-args.tex latexindent.pl myenv.tex -l myenv-noAdd5.yaml latexindent.pl myenv.tex -l myenv-noAdd6.yaml \end{commandshell} - we obtain the respective outputs given in \cref{lst:myenv-args-noAdd5,lst:myenv-args-noAdd6}. Note that in \cref{lst:myenv-args-noAdd5} - the text for the \emph{optional} argument has not received any additional indentation, and that in \cref{lst:myenv-args-noAdd6} the - \emph{mandatory} argument has not received any additional indentation; in both cases, the \emph{body} has not received any additional indentation. + we obtain the respective outputs given in \cref{lst:myenv-args-noAdd5,lst:myenv-args-noAdd6}. Note that in + \cref{lst:myenv-args-noAdd5} the text for the \emph{optional} argument has not + received any additional indentation, and that in \cref{lst:myenv-args-noAdd6} the + \emph{mandatory} argument has not received any additional indentation; in both + cases, the \emph{body} has not received any additional indentation. \begin{minipage}{.45\textwidth} \cmhlistingsfromfile{demonstrations/myenvironment-args-noAdd5.tex}{\texttt{myenv-args.tex} using \cref{lst:myenv-noAdd5}}{lst:myenv-args-noAdd5} @@ -84,8 +89,8 @@ latexindent.pl myenv.tex -l myenv-noAdd6.yaml \end{minipage} \yamltitle{indentRules}*{fields} - We may also specify indentation rules for environment code blocks using the \texttt{indentRules} field; see, for example, - \cref{lst:myenv-rules1,lst:myenv-rules2}. + We may also specify indentation rules for environment code blocks using the + \texttt{indentRules} field; see, for example, \cref{lst:myenv-rules1,lst:myenv-rules2}. \begin{minipage}{.45\textwidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/myenv-rules1.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-rules1.yaml}}{lst:myenv-rules1} @@ -100,22 +105,27 @@ latexindent.pl myenv.tex -l myenv-noAdd6.yaml latexindent.pl myenv.tex -l myenv-rules1.yaml latexindent.pl myenv.tex -l myenv-rules2.yaml \end{commandshell} - we obtain the output given in \cref{lst:myenv-rules-output}; note in particular that the environment \texttt{myenv} - has received one tab (from the \texttt{outer} environment) plus three spaces from \cref{lst:myenv-rules1} or \ref{lst:myenv-rules2}. + we obtain the output given in \cref{lst:myenv-rules-output}; note in particular that the + environment \texttt{myenv} has received one tab (from the + \texttt{outer} environment) plus three spaces from \cref{lst:myenv-rules1} or + \ref{lst:myenv-rules2}. \cmhlistingsfromfile[showtabs=true,showspaces=true]{demonstrations/myenv-rules1.tex}{\texttt{myenv.tex} output (using either \cref{lst:myenv-rules1} or \cref{lst:myenv-rules2})}{lst:myenv-rules-output} - If you specify a field in \texttt{indentRules} using anything other than horizontal space, it will be ignored. + If you specify a field in \texttt{indentRules} using anything other than horizontal + space, it will be ignored. - Returning to the example in \cref{lst:myenv-args} that contains optional and mandatory arguments. Upon using \cref{lst:myenv-rules1} as in + Returning to the example in \cref{lst:myenv-args} that contains optional and mandatory + arguments. Upon using \cref{lst:myenv-rules1} as in \begin{commandshell} latexindent.pl myenv-args.tex -l=myenv-rules1.yaml \end{commandshell} - we obtain the output in \cref{lst:myenv-args-rules1}; note that the body, optional argument and mandatory argument of \texttt{myenv} - have \emph{all} received the same customised indentation. - \cmhlistingsfromfile[showtabs=true,showspaces=true]{demonstrations/myenvironment-args-rules1.tex}{\texttt{myenv-args.tex} using \cref{lst:myenv-rules1}}{lst:myenv-args-rules1} + we obtain the output in \cref{lst:myenv-args-rules1}; note that the body, optional argument + and mandatory argument of \texttt{myenv} have \emph{all} received + the same customised indentation. \cmhlistingsfromfile[showtabs=true,showspaces=true]{demonstrations/myenvironment-args-rules1.tex}{\texttt{myenv-args.tex} using \cref{lst:myenv-rules1}}{lst:myenv-args-rules1} - You can specify different indentation rules for the different features using, for example, \cref{lst:myenv-rules3,lst:myenv-rules4} + You can specify different indentation rules for the different features using, for + example, \cref{lst:myenv-rules3,lst:myenv-rules4} \begin{minipage}{.49\textwidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/myenv-rules3.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-rules3.yaml}}{lst:myenv-rules3} @@ -142,20 +152,23 @@ latexindent.pl myenv-args.tex -l myenv-rules4.yaml \end{minipage} \end{widepage} - Note that in \cref{lst:myenv-args-rules3}, the optional argument has only received a single space of indentation, while the mandatory argument - has received the default (tab) indentation; the environment body has received three spaces of indentation. + Note that in \cref{lst:myenv-args-rules3}, the optional argument has only received a single + space of indentation, while the mandatory argument has received the default (tab) + indentation; the environment body has received three spaces of indentation. - In \cref{lst:myenv-args-rules4}, the optional argument has received the default (tab) indentation, the mandatory argument has received two tabs - of indentation, and the body has received three spaces of indentation. + In \cref{lst:myenv-args-rules4}, the optional argument has received the default (tab) + indentation, the mandatory argument has received two tabs of indentation, and the body + has received three spaces of indentation. \yamltitle{noAdditionalIndentGlobal}*{fields} \begin{wrapfigure}[6]{r}[0pt]{7cm} \cmhlistingsfromfile[style=noAdditionalIndentGlobalEnv]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{noAdditionalIndentGlobal}}{lst:noAdditionalIndentGlobal:environments} \end{wrapfigure} - Assuming that your environment name is not found within neither \texttt{noAdditionalIndent} nor \texttt{indentRules}, the next - place that \texttt{latexindent.pl} will look is \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 + Assuming that your environment name is not found within neither \texttt{noAdditionalIndent} + nor \texttt{indentRules}, the next place that \texttt{latexindent.pl} will look is + \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 \begin{widepage} \begin{commandshell} @@ -164,10 +177,13 @@ latexindent.pl myenv-args.tex -l myenv-rules1.yaml,env-noAdditionalGlobal.yaml \end{commandshell} \end{widepage} - The respective output from these two commands are in \cref{lst:myenv-args-no-add-global1,lst:myenv-args-no-add-global2}; in \cref{lst:myenv-args-no-add-global1} notice that \emph{both} - environments receive no additional indentation but that the arguments of \texttt{myenv} still \emph{do} receive indentation. In \cref{lst:myenv-args-no-add-global2} - notice that the \emph{outer} environment does not receive additional indentation, but because of the settings from \texttt{myenv-rules1.yaml} (in \vref{lst:myenv-rules1}), the \texttt{myenv} - environment still \emph{does} receive indentation. + The respective output from these two commands are in \cref{lst:myenv-args-no-add-global1,lst:myenv-args-no-add-global2}; in + \cref{lst:myenv-args-no-add-global1} notice that \emph{both} environments receive no + additional indentation but that the arguments of \texttt{myenv} still + \emph{do} receive indentation. In \cref{lst:myenv-args-no-add-global2} notice that the + \emph{outer} environment does not receive additional indentation, but because + of the settings from \texttt{myenv-rules1.yaml} (in \vref{lst:myenv-rules1}), the \texttt{myenv} environment + still \emph{does} receive indentation. \begin{minipage}{.45\textwidth} \cmhlistingsfromfile{demonstrations/myenvironment-args-rules1-noAddGlobal1.tex}{\texttt{myenv-args.tex} using \cref{lst:noAdditionalIndentGlobal:environments}}{lst:myenv-args-no-add-global1} @@ -177,8 +193,8 @@ latexindent.pl myenv-args.tex -l myenv-rules1.yaml,env-noAdditionalGlobal.yaml \cmhlistingsfromfile{demonstrations/myenvironment-args-rules1-noAddGlobal2.tex}{\texttt{myenv-args.tex} using \cref{lst:noAdditionalIndentGlobal:environments,lst:myenv-rules1}}{lst:myenv-args-no-add-global2} \end{minipage} - In fact, \texttt{noAdditionalIndentGlobal} also contains keys that control the indentation of optional and mandatory - arguments; on referencing \cref{lst:opt-args-no-add-glob,lst:mand-args-no-add-glob} + In fact, \texttt{noAdditionalIndentGlobal} also contains keys that control the indentation of + optional and mandatory arguments; on referencing \cref{lst:opt-args-no-add-glob,lst:mand-args-no-add-glob} \begin{minipage}{.49\textwidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/opt-args-no-add-glob.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{opt-args-no-add-glob.yaml}}{lst:opt-args-no-add-glob} @@ -193,9 +209,10 @@ latexindent.pl myenv-args.tex -l myenv-rules1.yaml,env-noAdditionalGlobal.yaml latexindent.pl myenv-args.tex -local opt-args-no-add-glob.yaml latexindent.pl myenv-args.tex -local mand-args-no-add-glob.yaml \end{commandshell} - which produces the respective outputs given in \cref{lst:myenv-args-no-add-opt,lst:myenv-args-no-add-mand}. Notice that in \cref{lst:myenv-args-no-add-opt} - the \emph{optional} argument has not received any additional indentation, and in \cref{lst:myenv-args-no-add-mand} the \emph{mandatory} argument - has not received any additional indentation. + which produces the respective outputs given in \cref{lst:myenv-args-no-add-opt,lst:myenv-args-no-add-mand}. Notice that in + \cref{lst:myenv-args-no-add-opt} the \emph{optional} argument has not received any + additional indentation, and in \cref{lst:myenv-args-no-add-mand} the \emph{mandatory} + argument has not received any additional indentation. \begin{minipage}{.45\textwidth} \cmhlistingsfromfile{demonstrations/myenvironment-args-rules1-noAddGlobal3.tex}{\texttt{myenv-args.tex} using \cref{lst:opt-args-no-add-glob}}{lst:myenv-args-no-add-opt} @@ -209,17 +226,21 @@ latexindent.pl myenv-args.tex -local mand-args-no-add-glob.yaml \begin{wrapfigure}[4]{r}[0pt]{7cm} \cmhlistingsfromfile[style=indentRulesGlobalEnv]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{indentRulesGlobal}}{lst:indentRulesGlobal:environments} \end{wrapfigure} - The final check that \texttt{latexindent.pl} will make is to look for \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 + The final check that \texttt{latexindent.pl} will make is to look for + \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 \begin{commandshell} latexindent.pl myenv-args.tex -l env-indentRules.yaml latexindent.pl myenv-args.tex -l myenv-rules1.yaml,env-indentRules.yaml \end{commandshell} - then the respective output is shown in \cref{lst:myenv-args-indent-rules-global1,lst:myenv-args-indent-rules-global2}. Note that - in \cref{lst:myenv-args-indent-rules-global1}, both the environment blocks have received a single-space indentation, whereas in - \cref{lst:myenv-args-indent-rules-global2} the \texttt{outer} environment has received single-space indentation (specified by \texttt{indentRulesGlobal}), - but \texttt{myenv} has received \lstinline!" "!, as specified by the particular \texttt{indentRules} for \texttt{myenv} \vref{lst:myenv-rules1}. + then the respective output is shown in \cref{lst:myenv-args-indent-rules-global1,lst:myenv-args-indent-rules-global2}. Note that in + \cref{lst:myenv-args-indent-rules-global1}, both the environment blocks have received a single-space + indentation, whereas in \cref{lst:myenv-args-indent-rules-global2} the \texttt{outer} environment + has received single-space indentation (specified by \texttt{indentRulesGlobal}), but + \texttt{myenv} has received \lstinline!" "!, as specified by the + particular \texttt{indentRules} for \texttt{myenv} \vref{lst:myenv-rules1}. \begin{minipage}{.45\textwidth} \cmhlistingsfromfile[showspaces=true]{demonstrations/myenvironment-args-global-rules1.tex}{\texttt{myenv-args.tex} using \cref{lst:indentRulesGlobal:environments}}{lst:myenv-args-indent-rules-global1} @@ -229,7 +250,8 @@ latexindent.pl myenv-args.tex -l myenv-rules1.yaml,env-indentRules.yaml \cmhlistingsfromfile[showspaces=true]{demonstrations/myenvironment-args-global-rules2.tex}{\texttt{myenv-args.tex} using \cref{lst:myenv-rules1,lst:indentRulesGlobal:environments}}{lst:myenv-args-indent-rules-global2} \end{minipage} - You can specify \texttt{indentRulesGlobal} for both optional and mandatory arguments, as detailed in \cref{lst:opt-args-indent-rules-glob,lst:mand-args-indent-rules-glob} + You can specify \texttt{indentRulesGlobal} for both optional and mandatory arguments, as + detailed in \cref{lst:opt-args-indent-rules-glob,lst:mand-args-indent-rules-glob} \begin{minipage}{.49\textwidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/opt-args-indent-rules-glob.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{opt-args-indent-rules-glob.yaml}}{lst:opt-args-indent-rules-glob} @@ -244,9 +266,10 @@ latexindent.pl myenv-args.tex -l myenv-rules1.yaml,env-indentRules.yaml latexindent.pl myenv-args.tex -local opt-args-indent-rules-glob.yaml latexindent.pl myenv-args.tex -local mand-args-indent-rules-glob.yaml \end{commandshell} - we obtain the respective outputs in \cref{lst:myenv-args-indent-rules-global3,lst:myenv-args-indent-rules-global4}. Note that the \emph{optional} - argument in \cref{lst:myenv-args-indent-rules-global3} has received two tabs worth of indentation, while the \emph{mandatory} argument has - done so in \cref{lst:myenv-args-indent-rules-global4}. + we obtain the respective outputs in \cref{lst:myenv-args-indent-rules-global3,lst:myenv-args-indent-rules-global4}. Note that the + \emph{optional} argument in \cref{lst:myenv-args-indent-rules-global3} has received two tabs worth + of indentation, while the \emph{mandatory} argument has done so in + \cref{lst:myenv-args-indent-rules-global4}. \begin{widepage} \begin{minipage}{.55\textwidth} 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 6cdcf48e613..c5b71a71e38 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 @@ -1,15 +1,15 @@ % arara: pdflatex: {shell: yes, files: [latexindent]} \subsubsection{Environments with items} - With reference to \vref{lst:indentafteritems,lst:itemNames}, some commands - may contain \texttt{item} commands; for the purposes of this discussion, - we will use the code from \vref{lst:itemsbefore}. + With reference to \vref{lst:indentafteritems,lst:itemNames}, some commands may contain + \texttt{item} commands; for the purposes of this discussion, we will use the + code from \vref{lst:itemsbefore}. Assuming that you've populated \texttt{itemNames} with the name of your - \texttt{item}, you can put the item name into \texttt{noAdditionalIndent} - as in \cref{lst:item-noAdd1}, although a more efficient approach may be - to change the relevant field in \texttt{itemNames} to \texttt{0}. Similarly, - you can customise the indentation that your \texttt{item} receives using - \texttt{indentRules}, as in \cref{lst:item-rules1} + \texttt{item}, you can put the item name into \texttt{noAdditionalIndent} as in + \cref{lst:item-noAdd1}, although a more efficient approach may be to change the relevant + field in \texttt{itemNames} to \texttt{0}. Similarly, you can customise + the indentation that your \texttt{item} receives using \texttt{indentRules}, + as in \cref{lst:item-rules1} \begin{minipage}{.45\textwidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/item-noAdd1.yaml}[yaml-TCB]{\texttt{item-noAdd1.yaml}}{lst:item-noAdd1} @@ -24,9 +24,11 @@ latexindent.pl items1.tex -local item-noAdd1.yaml latexindent.pl items1.tex -local item-rules1.yaml \end{commandshell} - the respective outputs are given in \cref{lst:items1-noAdd1,lst:items1-rules1}; note that in \cref{lst:items1-noAdd1} - that the text after each \texttt{item} has not received any additional indentation, and in \cref{lst:items1-rules1}, - the text after each \texttt{item} has received a single space of indentation, specified by \cref{lst:item-rules1}. + the respective outputs are given in \cref{lst:items1-noAdd1,lst:items1-rules1}; note that in + \cref{lst:items1-noAdd1} that the text after each \texttt{item} has not received + any additional indentation, and in \cref{lst:items1-rules1}, the text after each + \texttt{item} has received a single space of indentation, specified by + \cref{lst:item-rules1}. \begin{minipage}{.45\textwidth} \cmhlistingsfromfile{demonstrations/items1-noAdd1.tex}{\texttt{items1.tex} using \cref{lst:item-noAdd1}}{lst:items1-noAdd1} @@ -36,10 +38,12 @@ latexindent.pl items1.tex -local item-rules1.yaml \cmhlistingsfromfile[showtabs=true,showspaces=true]{demonstrations/items1-rules1.tex}{\texttt{items1.tex} using \cref{lst:item-rules1}}{lst:items1-rules1} \end{minipage} - Alternatively, you might like to populate \texttt{noAdditionalIndentGlobal} or \texttt{indentRulesGlobal} using the \texttt{items} - key, as demonstrated in \cref{lst:items-noAdditionalGlobal,lst:items-indentRulesGlobal}. Note that there is a need to - `reset/remove' the \texttt{item} field from \texttt{indentRules} in both cases (see the hierarchy description given on \cpageref{sec:noadd-indent-rules}) - as the \texttt{item} command is a member of \texttt{indentRules} by default. + Alternatively, you might like to populate \texttt{noAdditionalIndentGlobal} or + \texttt{indentRulesGlobal} using the \texttt{items} key, as demonstrated in + \cref{lst:items-noAdditionalGlobal,lst:items-indentRulesGlobal}. Note that there is a need to `reset/remove' the + \texttt{item} field from \texttt{indentRules} in both cases (see the hierarchy + description given on \cpageref{sec:noadd-indent-rules}) as the \texttt{item} command is a + member of \texttt{indentRules} by default. \begin{minipage}{.45\textwidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/items-noAdditionalGlobal.yaml}[yaml-TCB]{\texttt{items-noAdditionalGlobal.yaml}}{lst:items-noAdditionalGlobal} @@ -55,5 +59,6 @@ latexindent.pl items1.tex -local items-noAdditionalGlobal.yaml latexindent.pl items1.tex -local items-indentRulesGlobal.yaml \end{commandshell} the respective outputs from \cref{lst:items1-noAdd1,lst:items1-rules1} are obtained; note, however, that - \emph{all} such \texttt{item} commands without their own individual \texttt{noAdditionalIndent} or \texttt{indentRules} - settings would behave as in these listings. + \emph{all} such \texttt{item} commands without their own individual + \texttt{noAdditionalIndent} or \texttt{indentRules} settings would behave as in these + listings. diff --git a/Master/texmf-dist/doc/support/latexindent/subsubsec-headings.tex b/Master/texmf-dist/doc/support/latexindent/subsubsec-headings.tex index 65a01eaaa91..a8a344e41c1 100644 --- a/Master/texmf-dist/doc/support/latexindent/subsubsec-headings.tex +++ b/Master/texmf-dist/doc/support/latexindent/subsubsec-headings.tex @@ -1,7 +1,8 @@ % arara: pdflatex: {shell: yes, files: [latexindent]} \subsubsection{afterHeading code blocks}\label{subsubsec-headings-no-add-indent-rules} - Let's use the example \cref{lst:headings2} for demonstration throughout this \namecref{subsubsec-headings-no-add-indent-rules}. - As discussed on \cpageref{lst:headings1}, by default \texttt{latexindent.pl} will not add indentation after headings. + Let's use the example \cref{lst:headings2} for demonstration throughout this + \namecref{subsubsec-headings-no-add-indent-rules}. As discussed on \cpageref{lst:headings1}, by default + \texttt{latexindent.pl} will not add indentation after headings. \cmhlistingsfromfile{demonstrations/headings2.tex}{\texttt{headings2.tex}}{lst:headings2} @@ -9,8 +10,9 @@ \begin{commandshell} latexindent.pl headings2.tex -l headings3.yaml \end{commandshell} - we obtain the output in \cref{lst:headings2-mod3}. Note that the argument of \texttt{paragraph} has received (default) indentation, - and that the body after the heading statement has received (default) indentation. + we obtain the output in \cref{lst:headings2-mod3}. Note that the argument of + \texttt{paragraph} has received (default) indentation, and that the body after the + heading statement has received (default) indentation. \begin{minipage}{.45\textwidth} \cmhlistingsfromfile{demonstrations/headings2-mod3.tex}{\texttt{headings2.tex} using \cref{lst:headings3yaml}}{lst:headings2-mod3} @@ -24,8 +26,10 @@ latexindent.pl headings2.tex -l headings3.yaml \begin{commandshell} latexindent.pl headings2.tex -l headings4.yaml \end{commandshell} - then we receive the output in \cref{lst:headings2-mod4}. Note that the arguments \emph{and} the body after the heading - of \texttt{paragraph} has received no additional indentation, because we have specified \texttt{noAdditionalIndent} in scalar form. + then we receive the output in \cref{lst:headings2-mod4}. Note that the arguments + \emph{and} the body after the heading of \texttt{paragraph} has received + no additional indentation, because we have specified \texttt{noAdditionalIndent} in scalar + form. \begin{minipage}{.45\textwidth} \cmhlistingsfromfile{demonstrations/headings2-mod4.tex}{\texttt{headings2.tex} using \cref{lst:headings4yaml}}{lst:headings2-mod4} @@ -35,9 +39,11 @@ latexindent.pl headings2.tex -l headings4.yaml \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/headings4.yaml}[yaml-TCB]{\texttt{headings4.yaml}}{lst:headings4yaml} \end{minipage} - Similarly, if we specify \texttt{indentRules} as in \cref{lst:headings5yaml} and run analogous commands to those above, - we receive the output in \cref{lst:headings2-mod5}; note that the \emph{body}, \emph{mandatory argument} and content - \emph{after the heading} of \texttt{paragraph} have \emph{all} received three tabs worth of indentation. + Similarly, if we specify \texttt{indentRules} as in \cref{lst:headings5yaml} and run + analogous commands to those above, we receive the output in \cref{lst:headings2-mod5}; note + that the \emph{body}, \emph{mandatory argument} and content + \emph{after the heading} of \texttt{paragraph} have \emph{all} received + three tabs worth of indentation. \begin{minipage}{.55\textwidth} \cmhlistingsfromfile[showtabs=true]{demonstrations/headings2-mod5.tex}{\texttt{headings2.tex} using \cref{lst:headings5yaml}}{lst:headings2-mod5} @@ -47,7 +53,8 @@ latexindent.pl headings2.tex -l headings4.yaml \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/headings5.yaml}[yaml-TCB]{\texttt{headings5.yaml}}{lst:headings5yaml} \end{minipage} - We may, instead, specify \texttt{noAdditionalIndent} in `field' form, as in \cref{lst:headings6yaml} which gives the output in \cref{lst:headings2-mod6}. + We may, instead, specify \texttt{noAdditionalIndent} in `field' form, as in + \cref{lst:headings6yaml} which gives the output in \cref{lst:headings2-mod6}. \begin{minipage}{.45\textwidth} \cmhlistingsfromfile{demonstrations/headings2-mod6.tex}{\texttt{headings2.tex} using \cref{lst:headings6yaml}}{lst:headings2-mod6} @@ -57,9 +64,10 @@ latexindent.pl headings2.tex -l headings4.yaml \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/headings6.yaml}[yaml-TCB]{\texttt{headings6.yaml}}{lst:headings6yaml} \end{minipage} - Analogously, we may specify \texttt{indentRules} as in \cref{lst:headings7yaml} which gives the output in \cref{lst:headings2-mod7}; - note that mandatory argument text has only received a single space of indentation, while the body after the heading has - received three tabs worth of indentation. + Analogously, we may specify \texttt{indentRules} as in \cref{lst:headings7yaml} which + gives the output in \cref{lst:headings2-mod7}; note that mandatory argument text has only + received a single space of indentation, while the body after the heading has received + three tabs worth of indentation. \begin{minipage}{.45\textwidth} \cmhlistingsfromfile[showtabs=true]{demonstrations/headings2-mod7.tex}{\texttt{headings2.tex} using \cref{lst:headings7yaml}}{lst:headings2-mod7} @@ -69,12 +77,14 @@ latexindent.pl headings2.tex -l headings4.yaml \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/headings7.yaml}[yaml-TCB]{\texttt{headings7.yaml}}{lst:headings7yaml} \end{minipage} - Finally, let's consider \texttt{noAdditionalIndentGlobal} and \texttt{indentRulesGlobal} shown in \cref{lst:headings8yaml,lst:headings9yaml} - respectively, with respective output in \cref{lst:headings2-mod8,lst:headings2-mod9}. Note that in \cref{lst:headings8yaml} the - \emph{mandatory argument} of \texttt{paragraph} has received a (default) tab's worth of indentation, while the body after the - heading has received \emph{no additional indentation}. Similarly, in \cref{lst:headings2-mod9}, the \emph{argument} has received both a - (default) tab plus two spaces of indentation (from the global rule specified in \cref{lst:headings9yaml}), and the remaining body - after \texttt{paragraph} has received just two spaces of indentation. + Finally, let's consider \texttt{noAdditionalIndentGlobal} and \texttt{indentRulesGlobal} shown in + \cref{lst:headings8yaml,lst:headings9yaml} respectively, with respective output in \cref{lst:headings2-mod8,lst:headings2-mod9}. + Note that in \cref{lst:headings8yaml} the \emph{mandatory argument} of \texttt{paragraph} + has received a (default) tab's worth of indentation, while the body after the heading has + received \emph{no additional indentation}. Similarly, in \cref{lst:headings2-mod9}, the + \emph{argument} has received both a (default) tab plus two spaces of indentation + (from the global rule specified in \cref{lst:headings9yaml}), and the remaining body after + \texttt{paragraph} has received just two spaces of indentation. \begin{minipage}{.45\textwidth} \cmhlistingsfromfile{demonstrations/headings2-mod8.tex}{\texttt{headings2.tex} using \cref{lst:headings8yaml}}{lst:headings2-mod8} diff --git a/Master/texmf-dist/doc/support/latexindent/subsubsec-ifelsefi.tex b/Master/texmf-dist/doc/support/latexindent/subsubsec-ifelsefi.tex index f105498ca24..8be17304247 100644 --- a/Master/texmf-dist/doc/support/latexindent/subsubsec-ifelsefi.tex +++ b/Master/texmf-dist/doc/support/latexindent/subsubsec-ifelsefi.tex @@ -1,9 +1,9 @@ % arara: pdflatex: {shell: yes, files: [latexindent]} \subsubsection{ifelsefi code blocks} - Let's use the simple example shown in \cref{lst:ifelsefi1}; when - \texttt{latexindent.pl} operates on this file, the output as in \cref{lst:ifelsefi1-default}; - note that the body of each of the \lstinline!\if! statements have been indented, - and that the \lstinline!\else! statement has been accounted for correctly. + Let's use the simple example shown in \cref{lst:ifelsefi1}; when \texttt{latexindent.pl} + operates on this file, the output as in \cref{lst:ifelsefi1-default}; note that the body of + each of the \lstinline!\if! statements have been indented, and that the + \lstinline!\else! statement has been accounted for correctly. \begin{minipage}{.45\textwidth} \cmhlistingsfromfile{demonstrations/ifelsefi1.tex}{\texttt{ifelsefi1.tex}}{lst:ifelsefi1} @@ -13,9 +13,10 @@ \cmhlistingsfromfile{demonstrations/ifelsefi1-default.tex}{\texttt{ifelsefi1.tex} default output}{lst:ifelsefi1-default} \end{minipage} - It is recommended to specify \texttt{noAdditionalIndent} and \texttt{indentRules} in the `scalar' form only - for these type of code blocks, although the `field' form would work, assuming that \texttt{body} was specified. - Examples are shown in \cref{lst:ifnum-noAdd,lst:ifnum-indent-rules}. + It is recommended to specify \texttt{noAdditionalIndent} and \texttt{indentRules} in the + `scalar' form only for these type of code blocks, although the `field' form would work, + assuming that \texttt{body} was specified. Examples are shown in + \cref{lst:ifnum-noAdd,lst:ifnum-indent-rules}. \begin{minipage}{.45\textwidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/ifnum-noAdd.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{ifnum-noAdd.yaml}}{lst:ifnum-noAdd} @@ -30,9 +31,10 @@ latexindent.pl ifelsefi1.tex -local ifnum-noAdd.yaml latexindent.pl ifelsefi1.tex -l ifnum-indent-rules.yaml \end{commandshell} - we receive the respective output given in \cref{lst:ifelsefi1-output-noAdd,lst:ifelsefi1-output-indent-rules}; note that - in \cref{lst:ifelsefi1-output-noAdd}, the \texttt{ifnum} code block has \emph{not} received any additional indentation, - while in \cref{lst:ifelsefi1-output-indent-rules}, the \texttt{ifnum} code block has received one tab and two spaces of indentation. + we receive the respective output given in \cref{lst:ifelsefi1-output-noAdd,lst:ifelsefi1-output-indent-rules}; note that in + \cref{lst:ifelsefi1-output-noAdd}, the \texttt{ifnum} code block has \emph{not} + received any additional indentation, while in \cref{lst:ifelsefi1-output-indent-rules}, the + \texttt{ifnum} code block has received one tab and two spaces of indentation. \begin{minipage}{.45\textwidth} \cmhlistingsfromfile{demonstrations/ifelsefi1-noAdd.tex}{\texttt{ifelsefi1.tex} using \cref{lst:ifnum-noAdd}}{lst:ifelsefi1-output-noAdd} @@ -42,7 +44,8 @@ latexindent.pl ifelsefi1.tex -l ifnum-indent-rules.yaml \cmhlistingsfromfile[showspaces=true,showtabs=true]{demonstrations/ifelsefi1-indent-rules.tex}{\texttt{ifelsefi1.tex} using \cref{lst:ifnum-indent-rules}}{lst:ifelsefi1-output-indent-rules} \end{minipage} - We may specify \texttt{noAdditionalIndentGlobal} and \texttt{indentRulesGlobal} as in \cref{lst:ifelsefi-noAdd-glob,lst:ifelsefi-indent-rules-global}. + We may specify \texttt{noAdditionalIndentGlobal} and \texttt{indentRulesGlobal} as in + \cref{lst:ifelsefi-noAdd-glob,lst:ifelsefi-indent-rules-global}. \begin{minipage}{.49\textwidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/ifelsefi-noAdd-glob.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{ifelsefi-noAdd-glob.yaml}}{lst:ifelsefi-noAdd-glob} @@ -57,8 +60,8 @@ latexindent.pl ifelsefi1.tex -l ifnum-indent-rules.yaml latexindent.pl ifelsefi1.tex -local ifelsefi-noAdd-glob.yaml latexindent.pl ifelsefi1.tex -l ifelsefi-indent-rules-global.yaml \end{commandshell} - we receive the outputs in \cref{lst:ifelsefi1-output-noAdd-glob,lst:ifelsefi1-output-indent-rules-global}; notice that in - \cref{lst:ifelsefi1-output-noAdd-glob} neither of the \texttt{ifelsefi} code blocks have received indentation, while in + we receive the outputs in \cref{lst:ifelsefi1-output-noAdd-glob,lst:ifelsefi1-output-indent-rules-global}; notice that in \cref{lst:ifelsefi1-output-noAdd-glob} + neither of the \texttt{ifelsefi} code blocks have received indentation, while in \cref{lst:ifelsefi1-output-indent-rules-global} both code blocks have received a single space of indentation. \begin{minipage}{.45\textwidth} @@ -69,15 +72,16 @@ latexindent.pl ifelsefi1.tex -l ifelsefi-indent-rules-global.yaml \cmhlistingsfromfile[showspaces=true]{demonstrations/ifelsefi1-indent-rules-global.tex}{\texttt{ifelsefi1.tex} using \cref{lst:ifelsefi-indent-rules-global}}{lst:ifelsefi1-output-indent-rules-global} \end{minipage} - We can further explore the treatment of \texttt{ifElseFi} code blocks% - \announce*{2018-04-27}*{updates to ifElseFi code blocks} in \cref{lst:ifelsefi2}, - and the associated default output given in \cref{lst:ifelsefi2-default}; note, in particular, that the bodies of each of the `or statements' - have been indented. + We can further explore the treatment of \texttt{ifElseFi} code + blocks%%%% + \announce{2018-04-27}*{updates to ifElseFi code blocks} in \cref{lst:ifelsefi2}, + and the associated default output given in \cref{lst:ifelsefi2-default}; note, in particular, + that the bodies of each of the `or statements' have been indented. \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile*{demonstrations/ifelsefi2.tex}{\texttt{ifelsefi2.tex}}{lst:ifelsefi2} + \cmhlistingsfromfile{demonstrations/ifelsefi2.tex}{\texttt{ifelsefi2.tex}}{lst:ifelsefi2} \end{minipage}% \hfill \begin{minipage}{.54\textwidth} - \cmhlistingsfromfile*{demonstrations/ifelsefi2-default.tex}{\texttt{ifelsefi2.tex} default output}{lst:ifelsefi2-default} + \cmhlistingsfromfile{demonstrations/ifelsefi2-default.tex}{\texttt{ifelsefi2.tex} default output}{lst:ifelsefi2-default} \end{minipage} 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 c69685d36d7..e9f6c36ebb6 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 @@ -1,21 +1,23 @@ % arara: pdflatex: {shell: yes, files: [latexindent]} \subsubsection{The remaining code blocks} Referencing the different types of code blocks in \vref{tab:code-blocks}, we have a few - code blocks yet to cover; these are very similar to the \texttt{commands} code block type - covered comprehensively in \vref{subsubsec:commands-arguments}, but a small discussion - defining these remaining code blocks is necessary. + code blocks yet to cover; these are very similar to the \texttt{commands} code block + type covered comprehensively in \vref{subsubsec:commands-arguments}, but a small discussion defining + these remaining code blocks is necessary. \paragraph{keyEqualsValuesBracesBrackets} \texttt{latexindent.pl} defines this type of code block by the following criteria: \begin{itemize} - \item it must immediately follow either \lstinline!{! OR \lstinline![! OR \lstinline!,! with comments - and blank lines allowed; + \item it must immediately follow either \lstinline!{! OR \lstinline![! OR + \lstinline!,! with comments and blank lines allowed; \item then it has a name made up of the characters detailed in \vref{tab:code-blocks}; \item then an $=$ symbol; - \item then at least one set of curly braces or square brackets (comments and line breaks allowed throughout). + \item then at least one set of curly braces or square brackets (comments and line breaks + allowed throughout). \end{itemize} - An example is shown in \cref{lst:pgfkeysbefore}, with the default output given in \cref{lst:pgfkeys1:default}. + An example is shown in \cref{lst:pgfkeysbefore}, with the default output given in + \cref{lst:pgfkeys1:default}. \begin{minipage}{.45\textwidth} \cmhlistingsfromfile{demonstrations/pgfkeys1.tex}{\texttt{pgfkeys1.tex}}{lst:pgfkeysbefore} @@ -25,23 +27,29 @@ \cmhlistingsfromfile[showtabs=true]{demonstrations/pgfkeys1-default.tex}{\texttt{pgfkeys1.tex} default output}{lst:pgfkeys1:default} \end{minipage}% - In \cref{lst:pgfkeys1:default}, note that the maximum indentation is three tabs, and these come from: + In \cref{lst:pgfkeys1:default}, note that the maximum indentation is three tabs, and these + come from: \begin{itemize} \item the \lstinline!\pgfkeys! command's mandatory argument; \item the \lstinline!start coordinate/.initial! key's mandatory argument; - \item the \lstinline!start coordinate/.initial! key's body, which is defined as any lines following the name of the - key that include its arguments. This is the part controlled by the \emph{body} field for \texttt{noAdditionalIndent} - and friends from \cpageref{sec:noadd-indent-rules}. + \item the \lstinline!start coordinate/.initial! key's body, which is defined as any lines following the name + of the key that include its arguments. This is the part controlled by the + \emph{body} field for \texttt{noAdditionalIndent} and friends from + \cpageref{sec:noadd-indent-rules}. \end{itemize} \paragraph{namedGroupingBracesBrackets} - This type of code block is mostly motivated by tikz-based code; we define this code block as follows: + This type of code block is mostly motivated by tikz-based code; we define this code block + as follows: \begin{itemize} - \item it must immediately follow either \emph{horizontal space} OR \emph{one or more line breaks} OR \lstinline!{! OR \lstinline![! - OR \lstinline!$! OR \lstinline!)! OR \lstinline!(!; + \item it must immediately follow either \emph{horizontal space} OR \emph{one or more line breaks} OR + \lstinline!{! OR \lstinline![! OR \lstinline!$! OR + \lstinline!)! OR \lstinline!(!; \item the name may contain the characters detailed in \vref{tab:code-blocks}; - \item then at least one set of curly braces or square brackets (comments and line breaks allowed throughout). + \item then at least one set of curly braces or square brackets (comments and line breaks + allowed throughout). \end{itemize} - A simple example is given in \cref{lst:child1}, with default output in \cref{lst:child1:default}. + A simple example is given in \cref{lst:child1}, with default output in + \cref{lst:child1:default}. \begin{minipage}{.45\textwidth} \cmhlistingsfromfile{demonstrations/child1.tex}{\texttt{child1.tex}}{lst:child1} @@ -51,26 +59,31 @@ \cmhlistingsfromfile[showtabs=true]{demonstrations/child1-default.tex}{\texttt{child1.tex} default output}{lst:child1:default} \end{minipage}% - In particular, \texttt{latexindent.pl} considers \texttt{child}, \texttt{parent} and \texttt{node} all to be \texttt{namedGroupingBracesBrackets}\footnote{ - You may like to verify this by using the \texttt{-tt} option and checking \texttt{indent.log}! }. - Referencing \cref{lst:child1:default}, - note that the maximum indentation is two tabs, and these come from: + In particular, \texttt{latexindent.pl} considers \texttt{child}, + \texttt{parent} and \texttt{node} all to be + \texttt{namedGroupingBracesBrackets}\footnote{ + You may like to verify this by using the \texttt{-tt} option and checking \texttt{indent.log}! }. Referencing \cref{lst:child1:default}, note + that the maximum indentation is two tabs, and these come from: \begin{itemize} \item the \lstinline!child!'s mandatory argument; - \item the \lstinline!child!'s body, which is defined as any lines following the name of the \texttt{namedGroupingBracesBrackets} - that include its arguments. This is the part controlled by the \emph{body} field for \texttt{noAdditionalIndent} - and friends from \cpageref{sec:noadd-indent-rules}. + \item the \lstinline!child!'s body, which is defined as any lines following the name of + the \texttt{namedGroupingBracesBrackets} that include its arguments. This is the part controlled by the + \emph{body} field for \texttt{noAdditionalIndent} and friends from + \cpageref{sec:noadd-indent-rules}. \end{itemize} \paragraph{UnNamedGroupingBracesBrackets} occur in a variety of situations; specifically, we define this type of code block as satisfying the following criteria: \begin{itemize} - \item it must immediately follow either \lstinline!{! OR \lstinline![! OR \lstinline!,! OR \lstinline!&! OR \lstinline!)! OR \lstinline!(! - OR \lstinline!$!; - \item then at least one set of curly braces or square brackets (comments and line breaks allowed throughout). + \item it must immediately follow either \lstinline!{! OR \lstinline![! OR + \lstinline!,! OR \lstinline!&! OR \lstinline!)! OR + \lstinline!(! OR \lstinline!$!; + \item then at least one set of curly braces or square brackets (comments and line breaks + allowed throughout). \end{itemize} - An example is shown in \cref{lst:psforeach1} with default output give in \cref{lst:psforeach:default}. + An example is shown in \cref{lst:psforeach1} with default output give in + \cref{lst:psforeach:default}. \begin{minipage}{.45\textwidth} \cmhlistingsfromfile{demonstrations/psforeach1.tex}{\texttt{psforeach1.tex}}{lst:psforeach1} @@ -80,23 +93,27 @@ \cmhlistingsfromfile[showtabs=true]{demonstrations/psforeach1-default.tex}{\texttt{psforeach1.tex} default output}{lst:psforeach:default} \end{minipage}% - Referencing \cref{lst:psforeach:default}, there are \emph{three} sets of unnamed braces. Note also that the maximum value - of indentation is three tabs, and these come from: + Referencing \cref{lst:psforeach:default}, there are \emph{three} sets of unnamed + braces. Note also that the maximum value of indentation is three tabs, and these come + from: \begin{itemize} \item the \lstinline!\psforeach! command's mandatory argument; \item the \emph{first} un-named braces mandatory argument; - \item the \emph{first} un-named braces \emph{body}, which we define as any lines following the first opening \lstinline!{! or \lstinline![! - that defined the code block. This is the part controlled by the \emph{body} field for \texttt{noAdditionalIndent} - and friends from \cpageref{sec:noadd-indent-rules}. + \item the \emph{first} un-named braces \emph{body}, which we define as any + lines following the first opening \lstinline!{! or \lstinline![! that + defined the code block. This is the part controlled by the \emph{body} field + for \texttt{noAdditionalIndent} and friends from \cpageref{sec:noadd-indent-rules}. \end{itemize} - Users wishing to customise the mandatory and/or optional arguments on a \emph{per-name} basis for the \texttt{UnNamedGroupingBracesBrackets} - should use \texttt{always-un-named}. + Users wishing to customise the mandatory and/or optional arguments on a + \emph{per-name} basis for the \texttt{UnNamedGroupingBracesBrackets} should use + \texttt{always-un-named}. - \paragraph{filecontents} code blocks behave just as \texttt{environments}, except that neither arguments nor items are sought. + \paragraph{filecontents} code blocks behave just as \texttt{environments}, except that + neither arguments nor items are sought. \subsubsection{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. + 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. \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 0ec7d78c38a..d93f8926e12 100644 --- a/Master/texmf-dist/doc/support/latexindent/subsubsec-special.tex +++ b/Master/texmf-dist/doc/support/latexindent/subsubsec-special.tex @@ -3,9 +3,10 @@ Let's use the example from \vref{lst:specialbefore} which has default output shown in \vref{lst:specialafter}. - It is recommended to specify \texttt{noAdditionalIndent} and \texttt{indentRules} in the `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}. + It is recommended to specify \texttt{noAdditionalIndent} and \texttt{indentRules} in the + `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}. \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} @@ -20,9 +21,10 @@ latexindent.pl special1.tex -local displayMath-noAdd.yaml latexindent.pl special1.tex -l displayMath-indent-rules.yaml \end{commandshell} - we receive the respective output given in \cref{lst:special1-output-noAdd,lst:special1-output-indent-rules}; note that - in \cref{lst:special1-output-noAdd}, the \texttt{displayMath} code block has \emph{not} received any additional indentation, - while in \cref{lst:special1-output-indent-rules}, the \texttt{displayMath} code block has received three tabs worth of indentation. + we receive the respective output given in \cref{lst:special1-output-noAdd,lst:special1-output-indent-rules}; note that in + \cref{lst:special1-output-noAdd}, the \texttt{displayMath} code block has \emph{not} + received any additional indentation, while in \cref{lst:special1-output-indent-rules}, the + \texttt{displayMath} code block has received three tabs worth of indentation. \begin{minipage}{.45\textwidth} \cmhlistingsfromfile{demonstrations/special1-noAdd.tex}{\texttt{special1.tex} using \cref{lst:displayMath-noAdd}}{lst:special1-output-noAdd} @@ -32,7 +34,8 @@ latexindent.pl special1.tex -l displayMath-indent-rules.yaml \cmhlistingsfromfile[showtabs=true]{demonstrations/special1-indent-rules.tex}{\texttt{special1.tex} using \cref{lst:displayMath-indent-rules}}{lst:special1-output-indent-rules} \end{minipage} - We may specify \texttt{noAdditionalIndentGlobal} and \texttt{indentRulesGlobal} as in \cref{lst:special-noAdd-glob,lst:special-indent-rules-global}. + We may specify \texttt{noAdditionalIndentGlobal} and \texttt{indentRulesGlobal} as in + \cref{lst:special-noAdd-glob,lst:special-indent-rules-global}. \begin{minipage}{.49\textwidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/special-noAdd-glob.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{special-noAdd-glob.yaml}}{lst:special-noAdd-glob} @@ -47,8 +50,8 @@ latexindent.pl special1.tex -l displayMath-indent-rules.yaml latexindent.pl special1.tex -local special-noAdd-glob.yaml latexindent.pl special1.tex -l special-indent-rules-global.yaml \end{commandshell} - we receive the outputs in \cref{lst:special1-output-noAdd-glob,lst:special1-output-indent-rules-global}; notice that in - \cref{lst:special1-output-noAdd-glob} neither of the \texttt{special} code blocks have received indentation, while in + we receive the outputs in \cref{lst:special1-output-noAdd-glob,lst:special1-output-indent-rules-global}; notice that in \cref{lst:special1-output-noAdd-glob} + neither of the \texttt{special} code blocks have received indentation, while in \cref{lst:special1-output-indent-rules-global} both code blocks have received a single space of indentation. \begin{minipage}{.45\textwidth} diff --git a/Master/texmf-dist/doc/support/latexindent/title.tex b/Master/texmf-dist/doc/support/latexindent/title.tex index 1e0596c4df6..f1aaa7a4b7e 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.4.3 + \centering\ttfamily\bfseries latexindent.pl\\[1cm] Version 3.5 \end{tcolorbox} } \author{Chris Hughes \thanks{and contributors! diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/AlignmentAtAmpersand.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/AlignmentAtAmpersand.pm index 50fe2410141..7a4a9727c89 100644 --- a/Master/texmf-dist/scripts/latexindent/LatexIndent/AlignmentAtAmpersand.pm +++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/AlignmentAtAmpersand.pm @@ -107,7 +107,7 @@ sub find_aligned_block{ return; } -sub modify_line_breaks_settings{ +sub yaml_modify_line_breaks_settings{ return; } diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/Arguments.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/Arguments.pm index 8c8b5af38f1..7c84a0e65f3 100644 --- a/Master/texmf-dist/scripts/latexindent/LatexIndent/Arguments.pm +++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/Arguments.pm @@ -78,6 +78,14 @@ sub find_opt_mand_arguments{ # give unique id $arguments->create_unique_id; + + # text wrapping can make the ID split across lines + ${$arguments}{idRegExp} = ${$arguments}{id}; + + if($is_m_switch_active){ + my $IDwithLineBreaks = join("\\R?\\h*",split(//,${$arguments}{id})); + ${$arguments}{idRegExp} = qr/$IDwithLineBreaks/s; + } # determine which comes first, optional or mandatory if(${$arguments}{body} =~ m/.*?((?find_optional_arguments; } + # it's possible not to have any mandatory or optional arguments, see + # https://github.com/cmhughes/latexindent.pl/issues/123 + if( !(defined ${$arguments}{children}) ){ + $logger->trace("No optional or mandatory arguments found; searching for matching round parenthesis") if $is_t_switch_active; + $arguments->find_round_brackets; + } } else { $logger->trace("Searching for round brackets ONLY") if $is_t_switch_active; # look for round brackets diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/BlankLines.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/BlankLines.pm index e4041ce26d5..abd1ed73a3c 100644 --- a/Master/texmf-dist/scripts/latexindent/LatexIndent/BlankLines.pm +++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/BlankLines.pm @@ -26,6 +26,18 @@ our @EXPORT_OK = qw/protect_blank_lines unprotect_blank_lines condense_blank_lin sub protect_blank_lines{ return unless $is_m_switch_active; my $self = shift; + + # the text wrap routine, under some circumstances, can + # cause new blank lines that haven't been awarded a token; see, for example, + # test-cases/maxLineChars/multi-object-all.tex -l=multi-object2.yaml -m + # we can circumvent this by forcing blank lines to be protected if + # the text wrap option is active, which allows us to remove blank + # lines from wrapped text + if(ref ${$masterSettings{modifyLineBreaks}{textWrapOptions}}{columns} eq "HASH" + or ${$masterSettings{modifyLineBreaks}{textWrapOptions}}{columns}>0 ){ + ${$masterSettings{modifyLineBreaks}}{preserveBlankLines} = 1; + } + unless(${$masterSettings{modifyLineBreaks}}{preserveBlankLines}){ $logger->trace("*Blank lines will not be protected (preserveBlankLines=0)") if $is_t_switch_active; @@ -43,7 +55,7 @@ sub condense_blank_lines{ return unless ${$masterSettings{modifyLineBreaks}}{condenseMultipleBlankLinesInto}>0; my $self = shift; - + $logger->trace("*condense blank lines routine") if $is_t_switch_active; # if preserveBlankLines is set to 0, then the blank-line-token will not be present # in the document -- we change that here @@ -84,9 +96,13 @@ sub unprotect_blank_lines{ return unless ${$masterSettings{modifyLineBreaks}}{preserveBlankLines}; my $self = shift; + + # remove any empty lines that might have been added by the text_wrap routine; see, for example, + # test-cases/maxLineChars/multi-object-all.tex -l=multi-object2.yaml -m + ${$self}{body} =~ s/^\h*\R//mg; $logger->trace("Unprotecting blank lines (see preserveBlankLines)") if $is_t_switch_active; - my $blankLineToken = $tokens{blanklines}; + my $blankLineToken = join("(?:\\h|\\R)*",split(//,$tokens{blanklines})); # loop through the body, looking for the blank line token while(${$self}{body} =~ m/$blankLineToken/s){ diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/Document.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/Document.pm index 48d93c622d5..1b9d3811fb9 100644 --- a/Master/texmf-dist/scripts/latexindent/LatexIndent/Document.pm +++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/Document.pm @@ -23,11 +23,11 @@ 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/; use LatexIndent::LogFile qw/processSwitches $logger/; -use LatexIndent::GetYamlSettings qw/readSettings modify_line_breaks_settings get_indentation_settings_for_this_object get_every_or_custom_value get_indentation_information get_object_attribute_for_indentation_settings alignment_at_ampersand_settings %masterSettings/; +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/; use LatexIndent::BackUpFileProcedure qw/create_back_up_file/; use LatexIndent::BlankLines qw/protect_blank_lines unprotect_blank_lines condense_blank_lines/; -use LatexIndent::ModifyLineBreaks qw/modify_line_breaks_body modify_line_breaks_end remove_line_breaks_begin adjust_line_breaks_end_parent max_char_per_line paragraphs_on_one_line construct_paragraph_reg_exp one_sentence_per_line/; +use LatexIndent::ModifyLineBreaks qw/modify_line_breaks_body modify_line_breaks_end remove_line_breaks_begin adjust_line_breaks_end_parent text_wrap remove_paragraph_line_breaks construct_paragraph_reg_exp one_sentence_per_line text_wrap_remove_paragraph_line_breaks/; use LatexIndent::TrailingComments qw/remove_trailing_comments put_trailing_comments_back_in add_comment_symbol construct_trailing_comment_regexp/; use LatexIndent::HorizontalWhiteSpace qw/remove_trailing_whitespace remove_leading_space/; use LatexIndent::Indent qw/indent wrap_up_statement determine_total_indentation indent_begin indent_body indent_end_statement final_indentation_check get_surrounding_indentation indent_children_recursively check_for_blank_lines_at_beginning put_blank_lines_back_in_at_beginning add_surrounding_indentation_to_begin_statement post_indentation_check/; @@ -37,7 +37,7 @@ use LatexIndent::AlignmentAtAmpersand qw/align_at_ampersand find_aligned_block/; use LatexIndent::DoubleBackSlash qw/dodge_double_backslash un_dodge_double_backslash/; # code blocks -use LatexIndent::Verbatim qw/put_verbatim_back_in find_verbatim_environments find_noindent_block find_verbatim_commands put_verbatim_commands_back_in/; +use LatexIndent::Verbatim qw/put_verbatim_back_in find_verbatim_environments find_noindent_block find_verbatim_commands put_verbatim_commands_back_in find_verbatim_special/; use LatexIndent::Environment qw/find_environments $environmentBasicRegExp/; use LatexIndent::IfElseFi qw/find_ifelsefi construct_ifelsefi_regexp $ifElseFiBasicRegExp/; use LatexIndent::Else qw/check_for_else_statement/; @@ -88,7 +88,8 @@ sub operate_on_file{ $self->find_aligned_block; $self->remove_trailing_comments; $self->find_verbatim_environments; - $self->max_char_per_line; + $self->find_verbatim_special; + $self->text_wrap if ($is_m_switch_active and !${$masterSettings{modifyLineBreaks}{textWrapOptions}}{perCodeBlockBasis} and ${$masterSettings{modifyLineBreaks}{textWrapOptions}}{columns}>1); $self->protect_blank_lines; $self->remove_trailing_whitespace(when=>"before"); $self->find_file_contents_environments_and_preamble; @@ -196,8 +197,16 @@ sub find_objects{ # documents without preamble need a manual call to the paragraph_one_line routine if ($is_m_switch_active and !${$self}{preamblePresent}){ - ${$self}{removeParagraphLineBreaks} = ${$masterSettings{modifyLineBreaks}{removeParagraphLineBreaks}}{all}||${$masterSettings{modifyLineBreaks}{removeParagraphLineBreaks}}{masterDocument}||0; - $self->paragraphs_on_one_line ; + $self->yaml_get_textwrap_removeparagraphline_breaks; + + # call the remove_paragraph_line_breaks and text_wrap routines + if(${$masterSettings{modifyLineBreaks}{removeParagraphLineBreaks}}{beforeTextWrap}){ + $self->remove_paragraph_line_breaks if ${$self}{removeParagraphLineBreaks}; + $self->text_wrap if (${$self}{textWrapOptions} and ${$masterSettings{modifyLineBreaks}{textWrapOptions}}{perCodeBlockBasis}); + } else { + $self->text_wrap if (${$self}{textWrapOptions} and ${$masterSettings{modifyLineBreaks}{textWrapOptions}}{perCodeBlockBasis}); + $self->remove_paragraph_line_breaks if ${$self}{removeParagraphLineBreaks}; + } } # if there are no children, return @@ -255,6 +264,9 @@ sub get_settings_and_store_new_object{ # tasks particular to each object $latexIndentObject->tasks_particular_to_each_object; + + # removeParagraphLineBreaks and textWrapping fun! + $latexIndentObject->text_wrap_remove_paragraph_line_breaks if($is_m_switch_active); # store children in special hash push(@{${$self}{children}},$latexIndentObject); @@ -295,7 +307,7 @@ sub tasks_common_to_each_object{ ${$self}{bodyLineBreaks} = $bodyLineBreaks; # get settings for this object - $self->get_indentation_settings_for_this_object; + $self->yaml_get_indentation_settings_for_this_object; # give unique id $self->create_unique_id; @@ -303,6 +315,14 @@ sub tasks_common_to_each_object{ # add trailing text to the id to stop, e.g LATEX-INDENT-ENVIRONMENT1 matching LATEX-INDENT-ENVIRONMENT10 ${$self}{id} .= $tokens{endOfToken}; + # text wrapping can make the ID split across lines + ${$self}{idRegExp} = ${$self}{id}; + + if($is_m_switch_active){ + my $IDwithLineBreaks = join("\\R?\\h*",split(//,${$self}{id})); + ${$self}{idRegExp} = qr/$IDwithLineBreaks/s; + } + # the replacement text can be just the ID, but the ID might have a line break at the end of it $self->get_replacement_text; @@ -362,7 +382,7 @@ sub wrap_up_tasks{ my $child = @{${$self}{children}}[-1]; # check if the last object was the last thing in the body, and if it has adjusted linebreaks - $self->adjust_line_breaks_end_parent; + $self->adjust_line_breaks_end_parent if $is_m_switch_active; $logger->trace(Dumper(\%{$child})) if($is_tt_switch_active); $logger->trace("replaced with ID: ${$child}{id}") if $is_t_switch_active; diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/Else.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/Else.pm index 698fc6c1b90..10b1cc4d41b 100644 --- a/Master/texmf-dist/scripts/latexindent/LatexIndent/Else.pm +++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/Else.pm @@ -113,7 +113,7 @@ sub tasks_particular_to_each_object{ return; } -sub get_indentation_information{ +sub yaml_get_indentation_information{ return q(); } diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/Environment.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/Environment.pm index 2ecaf6d4e36..2c74f47554e 100755 --- a/Master/texmf-dist/scripts/latexindent/LatexIndent/Environment.pm +++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/Environment.pm @@ -19,7 +19,7 @@ use warnings; use LatexIndent::Tokens qw/%tokens/; use LatexIndent::TrailingComments qw/$trailingCommentRegExp/; use LatexIndent::GetYamlSettings qw/%masterSettings/; -use LatexIndent::Switches qw/$is_t_switch_active $is_tt_switch_active/; +use LatexIndent::Switches qw/$is_t_switch_active $is_tt_switch_active $is_m_switch_active/; use LatexIndent::LogFile qw/$logger/; use LatexIndent::Braces qw/$braceBracketRegExpBasic/; use LatexIndent::IfElseFi qw/$ifElseFiBasicRegExp/; @@ -90,7 +90,7 @@ sub find_environments{ $self->get_settings_and_store_new_object($env); ${@{${$self}{children}}[-1]}{replacementText}.($9?$9:q()).($10?$10:q()); /xseg; - $self->adjust_line_breaks_end_parent; + $self->adjust_line_breaks_end_parent if $is_m_switch_active; } return; } diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/FileContents.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/FileContents.pm index f3fba5fab75..cbb20e51483 100644 --- a/Master/texmf-dist/scripts/latexindent/LatexIndent/FileContents.pm +++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/FileContents.pm @@ -18,7 +18,7 @@ use strict; use warnings; use LatexIndent::Tokens qw/%tokens/; use LatexIndent::GetYamlSettings qw/%masterSettings/; -use LatexIndent::Switches qw/$is_t_switch_active $is_tt_switch_active/; +use LatexIndent::Switches qw/$is_t_switch_active $is_tt_switch_active $is_m_switch_active/; use LatexIndent::LogFile qw/$logger/; use LatexIndent::Environment qw/$environmentBasicRegExp/; use LatexIndent::IfElseFi qw/$ifElseFiBasicRegExp/; @@ -83,6 +83,14 @@ sub find_file_contents_environments_and_preamble{ ); # give unique id $fileContentsBlock->create_unique_id; + + # text wrapping can make the ID split across lines + ${$fileContentsBlock}{idRegExp} = ${$fileContentsBlock}{id}; + + if($is_m_switch_active){ + my $IDwithLineBreaks = join("\\R?\\h*",split(//,${$fileContentsBlock}{id})); + ${$fileContentsBlock}{idRegExp} = qr/$IDwithLineBreaks/s; + } # the replacement text can be just the ID, but the ID might have a line break at the end of it $fileContentsBlock->get_replacement_text; @@ -142,6 +150,14 @@ sub find_file_contents_environments_and_preamble{ # give unique id $preamble->create_unique_id; + + # text wrapping can make the ID split across lines + ${$preamble}{idRegExp} = ${$preamble}{id}; + + if($is_m_switch_active){ + my $IDwithLineBreaks = join("\\R?\\h*",split(//,${$preamble}{id})); + ${$preamble}{idRegExp} = qr/$IDwithLineBreaks/s; + } # get the replacement_text $preamble->get_replacement_text; @@ -189,7 +205,7 @@ sub find_file_contents_environments_and_preamble{ # store the child, if necessary if($indentThisChild){ $_->remove_leading_space; - $_->get_indentation_settings_for_this_object; + $_->yaml_get_indentation_settings_for_this_object; $_->tasks_particular_to_each_object; push(@{${$self}{children}},$_); @@ -230,6 +246,20 @@ sub tasks_particular_to_each_object{ # search for commands and special code blocks $self->find_commands_or_key_equals_values_braces_and_special if ${$self}{body} =~ m/$specialBeginAndBracesBracketsBasicRegExp/s; + + # text wrapping, remove paragraph line breaks + if ($is_m_switch_active){ + $self->yaml_get_textwrap_removeparagraphline_breaks; + + # call the remove_paragraph_line_breaks and text_wrap routines + if(${$masterSettings{modifyLineBreaks}{removeParagraphLineBreaks}}{beforeTextWrap}){ + $self->remove_paragraph_line_breaks if ${$self}{removeParagraphLineBreaks}; + $self->text_wrap if (${$self}{textWrapOptions} and ${$masterSettings{modifyLineBreaks}{textWrapOptions}}{perCodeBlockBasis}); + } else { + $self->text_wrap if (${$self}{textWrapOptions} and ${$masterSettings{modifyLineBreaks}{textWrapOptions}}{perCodeBlockBasis}); + $self->remove_paragraph_line_breaks if ${$self}{removeParagraphLineBreaks}; + } + } } 1; diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/GetYamlSettings.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/GetYamlSettings.pm index 00af6ab2ae4..84558485951 100644 --- a/Master/texmf-dist/scripts/latexindent/LatexIndent/GetYamlSettings.pm +++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/GetYamlSettings.pm @@ -22,7 +22,7 @@ use File::Basename; # to get the filename and directory path use File::HomeDir; use Log::Log4perl qw(get_logger :levels); use Exporter qw/import/; -our @EXPORT_OK = qw/readSettings modify_line_breaks_settings get_indentation_settings_for_this_object get_every_or_custom_value get_indentation_information get_object_attribute_for_indentation_settings alignment_at_ampersand_settings %masterSettings/; +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 our $defaultSettings; @@ -44,7 +44,7 @@ our @alignAtAmpersandInformation = ( {name=>"lookForAlignDelims",yamlname=>"de {name=>"justification",default=>"left"}, ); -sub readSettings{ +sub yaml_read_settings{ my $self = shift; # read the default settings @@ -431,7 +431,7 @@ sub readSettings{ return; } -sub get_indentation_settings_for_this_object{ +sub yaml_get_indentation_settings_for_this_object{ my $self = shift; # create a name for previously found settings @@ -449,13 +449,13 @@ sub get_indentation_settings_for_this_object{ # check for noAdditionalIndent and indentRules # otherwise use defaultIndent - my $indentation = $self->get_indentation_information; + my $indentation = $self->yaml_get_indentation_information; # check for alignment at ampersand settings - $self->alignment_at_ampersand_settings; + $self->yaml_alignment_at_ampersand_settings; # check for line break settings - $self->modify_line_breaks_settings if $is_m_switch_active; + $self->yaml_modify_line_breaks_settings if $is_m_switch_active; # store the settings %{${previouslyFoundSettings}{$storageName}} = ( @@ -465,6 +465,8 @@ sub get_indentation_settings_for_this_object{ EndStartsOnOwnLine=>${$self}{EndStartsOnOwnLine}, EndFinishesWithLineBreak=>${$self}{EndFinishesWithLineBreak}, removeParagraphLineBreaks=>${$self}{removeParagraphLineBreaks}, + textWrapOptions=>${$self}{textWrapOptions}, + columns=>${$self}{columns}, ); # don't forget alignment settings! @@ -492,7 +494,7 @@ sub get_indentation_settings_for_this_object{ return; } -sub alignment_at_ampersand_settings{ +sub yaml_alignment_at_ampersand_settings{ my $self = shift; # if the YamlName is, for example, optionalArguments, mandatoryArguments, heading, then we'll be looking for information about the *parent* @@ -534,14 +536,15 @@ sub alignment_at_ampersand_settings{ return; } -sub modify_line_breaks_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, looking for settings for ${$self}{name} ") if $is_t_switch_active; + $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; # some objects, e.g ifElseFi, can have extra assignments, e.g ElseStartsOnOwnLine my @toBeAssignedTo = ${$self}{additionalAssignments} ? @{${$self}{additionalAssignments}} : (); @@ -551,47 +554,201 @@ sub modify_line_breaks_settings{ # we can efficiently loop through the following foreach (@toBeAssignedTo){ - $self->get_every_or_custom_value( + $self->yaml_poly_switch_get_every_or_custom_value( toBeAssignedTo=>$_, toBeAssignedToAlias=> ${$self}{aliases}{$_} ? ${$self}{aliases}{$_} : $_, ); - } + }; - # paragraph line break settings - ${$self}{removeParagraphLineBreaks} = ${$masterSettings{modifyLineBreaks}{removeParagraphLineBreaks}}{all}; + $self->yaml_get_textwrap_removeparagraphline_breaks; + return; +} - return if(${$self}{removeParagraphLineBreaks}); +sub yaml_get_textwrap_removeparagraphline_breaks{ + my $self = shift; + + # grab the logging object + my $logger = get_logger("Document"); - # the removeParagraphLineBreaks can contain fields that are hashes or scalar, for example: - # - # removeParagraphLineBreaks: - # all: 0 - # environments: 0 - # or - # removeParagraphLineBreaks: - # all: 0 - # environments: - # quotation: 0 + # textWrap and removeParagraphLineBreaks settings + foreach ("textWrapOptions","removeParagraphLineBreaks"){ + + # first check for either + # + # textWrapOptions: + # all: 0 + # + # or + # + # removeParagraphLineBreaks: + # all: 0 + # + # *IMPORTANT* + # even if all is set to 1, then it can still be disabled on either a + # + # per-object: + # + # for example + # + # textWrapOptions: + # all: + # except: + # - environments + # + # will disable textWrapOptions for *all* environments + # + # per-name + # + # for example + # + # textWrapOptions: + # all: + # except: + # - itemize + # + # will disable textWrapOptions for itemize + + # if 'all' is set as a hash, then the default value is 1, to be turned off (possibly) later + ${$self}{$_} = ( ref ${$masterSettings{modifyLineBreaks}{$_}}{all} eq "HASH" ? 1 : ${$masterSettings{modifyLineBreaks}{$_}}{all}); + + # get the columns + if($_ eq "textWrapOptions" and ${$masterSettings{modifyLineBreaks}{textWrapOptions}}{perCodeBlockBasis}){ + $self->yaml_get_columns; + } + + # name of the object in the modifyLineBreaks yaml (e.g environments, ifElseFi, etc) + my $YamlName = ${$self}{modifyLineBreaksYamlName}; + + # if the YamlName is either optionalArguments or mandatoryArguments, then we'll be looking for information about the *parent* + my $name = ($YamlName =~ m/Arguments/) ? ${$self}{parent} : ${$self}{name}; + + # move to the next if + # + # textWrapOptions/removeParagraphLineBreaks:: + # all: 1 + # + if(${$self}{$_} + and + ref ${$masterSettings{modifyLineBreaks}{$_}}{all} ne "HASH" + and + ${$masterSettings{modifyLineBreaks}{$_}}{all}){ + $logger->trace("$_ for $name is ${$self}{$_}") if $is_t_switch_active; + next; + }; + + # otherwise, look for exceptions, either through + # + # textWrapOptions/removeParagraphLineBreaks: + # all: + # except: + # - <*type* of thing or *name* of thing> + # + # so, for example, the following (per code-block) is acceptable + # which makes an exception for all *environments* + # + # all: + # except: + # - 'environments' + # + # the following (per-name) is acceptable + # which only makes an exception for things called itemize + # + # all: + # except: + # - 'itemize' + # + if(${$self}{$_} + and + defined ${${$masterSettings{modifyLineBreaks}{$_}}{all}}{except} + and + ref ${${$masterSettings{modifyLineBreaks}{$_}}{all}}{except} eq "ARRAY" + ){ + my %except = map { $_ => 1 } @{${${$masterSettings{modifyLineBreaks}}{$_}}{all}{except}}; + if( $except{$name} or $except{$YamlName}){ + ${$self}{$_} = 0; + my $detail = ($except{$name} ? "per-name" : "per-code-block-type"); + $logger->trace("$_ for $name is ${$self}{$_} (found as exception $detail, see $_:all:except)") if $is_t_switch_active; + next; + } + } else { + # or otherwise through, for example + # + # all: 0 + # ifElseFi: 1 + # + # the textWrapOptions/removeParagraphLineBreaks can contain fields that are hashes or scalar + # + if(ref ${$masterSettings{modifyLineBreaks}{$_}}{$YamlName} eq "HASH"){ + # textWrapOptions/removeParagraphLineBreaks: + # all: 0 + # environments: + # quotation: 0 + $logger->trace("*$YamlName specified with fields in $_, looking for $name") if $is_t_switch_active; + ${$self}{$_} = ${${$masterSettings{modifyLineBreaks}{$_}}{$YamlName}}{$name} if (defined ${${$masterSettings{modifyLineBreaks}{$_}}{$YamlName}}{$name}); + } elsif(defined ${$masterSettings{modifyLineBreaks}{$_}}{$YamlName}){ + # textWrapOptions/removeParagraphLineBreaks: + # all: 0 + # environments: 0 + $logger->trace("*$YamlName specified with just a number in $_ ${$masterSettings{modifyLineBreaks}{$_}}{$YamlName}") if $is_t_switch_active; + ${$self}{$_} = ${$masterSettings{modifyLineBreaks}{$_}}{$YamlName} if (defined ${$masterSettings{modifyLineBreaks}{$_}}{$YamlName}); + } + } + + # summary to log file + $logger->trace("$_ for $name is ${$self}{$_}") if $is_t_switch_active; + } + + return; +} + +sub yaml_get_columns{ + my $self = shift; - # name of the object in the modifyLineBreaks yaml (e.g environments, ifElseFi, etc) my $YamlName = ${$self}{modifyLineBreaksYamlName}; - # if the YamlName is either optionalArguments or mandatoryArguments, then we'll be looking for information about the *parent* - my $name = ($YamlName =~ m/Arguments/) ? ${$self}{parent} : ${$self}{name}; + # the columns settings can have a variety of different ways of being specified + if(ref ${$masterSettings{modifyLineBreaks}{textWrapOptions}}{columns} eq "HASH"){ + # assign default value of $columns + my $columns; + if(defined ${${$masterSettings{modifyLineBreaks}{textWrapOptions}}{columns}}{default}){ + $columns = ${${$masterSettings{modifyLineBreaks}{textWrapOptions}}{columns}}{default}; + } else { + $columns = 80; + } - if(ref ${$masterSettings{modifyLineBreaks}{removeParagraphLineBreaks}}{$YamlName} eq "HASH"){ - $logger->trace("*$YamlName specified with fields in removeParagraphLineBreaks, looking for $name") if $is_t_switch_active; - ${$self}{removeParagraphLineBreaks} = ${${$masterSettings{modifyLineBreaks}{removeParagraphLineBreaks}}{$YamlName}}{$name}||0; - } else { - if(defined ${$masterSettings{modifyLineBreaks}{removeParagraphLineBreaks}}{$YamlName}){ - $logger->trace("*$YamlName specified with just a number in removeParagraphLineBreaks ${$masterSettings{modifyLineBreaks}{removeParagraphLineBreaks}}{$YamlName}") if $is_t_switch_active; - ${$self}{removeParagraphLineBreaks} = ${$masterSettings{modifyLineBreaks}{removeParagraphLineBreaks}}{$YamlName}; + # possibly specify object wrapping on a per-name basis + if(ref ${${$masterSettings{modifyLineBreaks}{textWrapOptions}}{columns}}{$YamlName} eq "HASH"){ + # for example: + # modifyLineBreaks: + # textWrapOptions: + # columns: + # default: 80 + # environments: + # default: 80 + # something: 10 + # another: 20 + if(defined ${${${$masterSettings{modifyLineBreaks}{textWrapOptions}}{columns}}{$YamlName}}{${$self}{name}}){ + $columns = ${${${$masterSettings{modifyLineBreaks}{textWrapOptions}}{columns}}{$YamlName}}{${$self}{name}}; + } elsif (${${${$masterSettings{modifyLineBreaks}{textWrapOptions}}{columns}}{$YamlName}}{default}){ + $columns = ${${${$masterSettings{modifyLineBreaks}{textWrapOptions}}{columns}}{$YamlName}}{default}; + } + } else { + # for example: + # modifyLineBreaks: + # textWrapOptions: + # columns: + # default: 80 + # environments: 10 + $columns = ${${$masterSettings{modifyLineBreaks}{textWrapOptions}}{columns}}{$YamlName}; } + ${$self}{columns} = $columns; + } else { + ${$self}{columns} = ${$masterSettings{modifyLineBreaks}{textWrapOptions}}{columns}; } return; } -sub get_every_or_custom_value{ +sub yaml_poly_switch_get_every_or_custom_value{ my $self = shift; my %input = @_; @@ -630,7 +787,7 @@ sub get_every_or_custom_value{ return; } -sub get_indentation_information{ +sub yaml_get_indentation_information{ my $self = shift; #************************************** @@ -678,7 +835,7 @@ sub get_indentation_information{ my $name = (defined ${$self}{nameForIndentationSettings}) ? ${$self}{nameForIndentationSettings} : ${$self}{name}; # if the YamlName is not optionalArguments, mandatoryArguments, heading (possibly others) then assume we're looking for 'body' - my $YamlName = $self->get_object_attribute_for_indentation_settings; + my $YamlName = $self->yaml_get_object_attribute_for_indentation_settings; # grab the logging object my $logger = get_logger("Document"); @@ -732,7 +889,7 @@ sub get_indentation_information{ return $masterSettings{defaultIndent}; } -sub get_object_attribute_for_indentation_settings{ +sub yaml_get_object_attribute_for_indentation_settings{ # when looking for noAdditionalIndent or indentRules, we may need to determine # which thing we're looking for, e.g # diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/Heading.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/Heading.pm index 82957e182f1..208dfa9715e 100644 --- a/Master/texmf-dist/scripts/latexindent/LatexIndent/Heading.pm +++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/Heading.pm @@ -174,7 +174,7 @@ sub adjust_replacement_text_line_breaks_at_end{ return; } -sub get_object_attribute_for_indentation_settings{ +sub yaml_get_object_attribute_for_indentation_settings{ # when looking for noAdditionalIndent or indentRules, we may need to determine # which thing we're looking for, e.g # diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/HiddenChildren.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/HiddenChildren.pm index 1ddfa1bb537..878939fd41a 100644 --- a/Master/texmf-dist/scripts/latexindent/LatexIndent/HiddenChildren.pm +++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/HiddenChildren.pm @@ -16,7 +16,7 @@ package LatexIndent::HiddenChildren; # For all communication, please visit: https://github.com/cmhughes/latexindent.pl use strict; use warnings; -use LatexIndent::Switches qw/$is_t_switch_active $is_tt_switch_active/; +use LatexIndent::Switches qw/$is_t_switch_active $is_tt_switch_active $is_m_switch_active /; use LatexIndent::Tokens qw/%tokens/; use LatexIndent::LogFile qw/$logger/; use Data::Dumper; @@ -156,8 +156,21 @@ sub check_for_hidden_children{ my $self = shift; + my @matched; # grab the matches - my @matched = (${$self}{body} =~ /((?:$tokens{ifelsefiSpecial})?$tokens{beginOfToken}.[-a-z0-9]+?$tokens{endOfToken})/ig); + if($is_m_switch_active){ + # if modifyLineBreaks is active, then the IDS can be split across lines + my $ifElseFiSpecialBegin = join("\\R?\\h*",split(//,$tokens{ifelsefiSpecial})); + my $BeginwithLineBreaks = join("\\R?\\h*",split(//,$tokens{beginOfToken})); + my $EndwithLineBreaks = join("\\R?\\h*",split(//,$tokens{endOfToken})); + my $BlankLinesWithLineBreaks = join("\\R?\\h*",split(//,$tokens{blanklines})); + @matched = (${$self}{body} =~ /(?!$BlankLinesWithLineBreaks)((?:$ifElseFiSpecialBegin)?$BeginwithLineBreaks[-a-z0-9\n]+?$EndwithLineBreaks)/ig); + + # remove line breaks and horizontal space from matches + $_ =~ s/\R|\h//gs foreach (@matched); + } else { + @matched = (${$self}{body} =~ /((?:$tokens{ifelsefiSpecial})?$tokens{beginOfToken}.[-a-z0-9]+?$tokens{endOfToken})/igs); + } # log file $logger->trace("*Hidden children check") if $is_t_switch_active; diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/Indent.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/Indent.pm index 57bcd225add..fce49e2c660 100644 --- a/Master/texmf-dist/scripts/latexindent/LatexIndent/Indent.pm +++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/Indent.pm @@ -124,7 +124,7 @@ sub indent_body{ $self->align_at_ampersand if ${$self}{lookForAlignDelims}; # possibly remove paragraph line breaks - $self->paragraphs_on_one_line if $is_m_switch_active; + $self->remove_paragraph_line_breaks if ($is_m_switch_active and ${$self}{removeParagraphLineBreaks} and !${$masterSettings{modifyLineBreaks}{removeParagraphLineBreaks}}{beforeTextWrap}); # body indendation if(${$self}{linebreaksAtEnd}{begin}==1){ @@ -279,7 +279,7 @@ sub indent_children_recursively{ # we work through the array *in order* foreach my $child (@{${$self}{children}}){ $logger->trace("Searching ${$self}{name} for ${$child}{id}...") if $is_t_switch_active; - if(${$self}{body} =~ m/${$child}{id}/s){ + if(${$self}{body} =~ m/${$child}{idRegExp}/s){ # we only care if id is first non-white space character # and if followed by line break # if m switch is active @@ -288,11 +288,11 @@ sub indent_children_recursively{ # update the above two, if necessary if ($is_m_switch_active){ - $IDFirstNonWhiteSpaceCharacter = (${$self}{body} =~ m/^${$child}{id}/m + $IDFirstNonWhiteSpaceCharacter = (${$self}{body} =~ m/^${$child}{idRegExp}/m or - ${$self}{body} =~ m/^\h\h*${$child}{id}/m + ${$self}{body} =~ m/^\h\h*${$child}{idRegExp}/m ) ?1:0; - $IDFollowedImmediatelyByLineBreak = (${$self}{body} =~ m/${$child}{id}\h*\R+/m) ?1:0; + $IDFollowedImmediatelyByLineBreak = (${$self}{body} =~ m/${$child}{idRegExp}\h*\R+/m) ?1:0; ${$child}{IDFollowedImmediatelyByLineBreak} = $IDFollowedImmediatelyByLineBreak; } @@ -308,7 +308,7 @@ sub indent_children_recursively{ # remove line break *after* , if appropriate my $EndStringLogFile = ${$child}{aliases}{EndFinishesWithLineBreak}||"EndFinishesWithLineBreak"; $logger->trace("Removing linebreak after ${$child}{end} (see $EndStringLogFile)") if $is_t_switch_active; - ${$self}{body} =~ s/${$child}{id}(\h*)?(\R|\h)*/${$child}{id}$1/s; + ${$self}{body} =~ s/${$child}{idRegExp}(\h*)?(\R|\h)*/${$child}{id}$1/s; ${$child}{linebreaksAtEnd}{end} = 0; } @@ -332,7 +332,7 @@ sub indent_children_recursively{ my $trailingCharacterToken = q(); if(${$child}{BeginStartsOnOwnLine}==2){ $logger->trace("Removing space immediately before ${$child}{id}, in preparation for adding % ($BeginStringLogFile == 2)") if $is_t_switch_active; - ${$self}{body} =~ s/\h*${$child}{id}/${$child}{id}/s; + ${$self}{body} =~ s/\h*${$child}{idRegExp}/${$child}{id}/s; $logger->trace("Adding a % at the end of the line that ${$child}{begin} is on, then a linebreak ($BeginStringLogFile == 2)") if $is_t_switch_active; $trailingCharacterToken = "%".$self->add_comment_symbol; } elsif (${$child}{BeginStartsOnOwnLine}==3){ @@ -352,9 +352,9 @@ sub indent_children_recursively{ # finally, if BeginStartsOnOwnLine == -1 then we might need to *remove* a blank line(s) # important to check we don't move the begin statement next to a blank-line-token my $blankLineToken = $tokens{blanklines}; - if(${$self}{body} !~ m/$blankLineToken\R*\h*${$child}{id}/s){ + if(${$self}{body} !~ m/$blankLineToken\R*\h*${$child}{idRegExp}/s){ $logger->trace("Removing linebreak before ${$child}{begin} (see $BeginStringLogFile in ${$child}{modifyLineBreaksYamlName} YAML)") if $is_t_switch_active; - ${$self}{body} =~ s/(\h*)(?:\R*|\h*)+${$child}{id}/$1${$child}{id}/s; + ${$self}{body} =~ s/(\h*)(?:\R*|\h*)+${$child}{idRegExp}/$1${$child}{id}/s; } else { $logger->trace("Not removing linebreak ahead of ${$child}{begin}, as blank-line-token present (see preserveBlankLines)") if $is_t_switch_active; } @@ -364,7 +364,7 @@ sub indent_children_recursively{ $logger->trace(Dumper(\%{$child})) if($is_tt_switch_active); # replace ids with body - ${$self}{body} =~ s/${$child}{id}/${$child}{begin}${$child}{body}${$child}{end}/; + ${$self}{body} =~ s/${$child}{idRegExp}/${$child}{begin}${$child}{body}${$child}{end}/; # log file info $logger->trace("Body (${$self}{name}) now looks like:") if $is_tt_switch_active; diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/LogFile.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/LogFile.pm index 8f3dee24066..b8ebc034b3a 100644 --- a/Master/texmf-dist/scripts/latexindent/LatexIndent/LogFile.pm +++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/LogFile.pm @@ -140,7 +140,7 @@ ENDQUOTE if($switches{screenlog}){ $appender_screen = Log::Log4perl::Appender->new( "Log::Log4perl::Appender::Screen", - stderr => 0, + stderr => 1, utf8 => 1, ); @@ -160,7 +160,7 @@ ENDQUOTE } else { $logger->info("Reading input from STDIN"); my $buttonText = ($FindBin::Script eq 'latexindent.exe') ? 'CTRL+Z followed by ENTER':'CTRL+D'; - print "Please enter text to be indented: (press $buttonText when finished)\n"; + print STDERR "Please enter text to be indented: (press $buttonText when finished)\n"; } # log the switches from the user @@ -205,7 +205,7 @@ ENDQUOTE } # read the YAML settings - $self->readSettings; + $self->yaml_read_settings; # the user may have specified their own settings for the rest of the log file, # for example: diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/MandatoryArgument.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/MandatoryArgument.pm index ba6e220d09e..0b641231f2a 100644 --- a/Master/texmf-dist/scripts/latexindent/LatexIndent/MandatoryArgument.pm +++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/MandatoryArgument.pm @@ -113,7 +113,7 @@ sub get_mand_arg_reg_exp{ return $mandArgRegExp; } -sub get_object_attribute_for_indentation_settings{ +sub yaml_get_object_attribute_for_indentation_settings{ my $self = shift; return ${$self}{modifyLineBreaksYamlName}; diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/ModifyLineBreaks.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/ModifyLineBreaks.pm index 7b704736c02..afa1360369d 100644 --- a/Master/texmf-dist/scripts/latexindent/LatexIndent/ModifyLineBreaks.pm +++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/ModifyLineBreaks.pm @@ -25,13 +25,13 @@ use LatexIndent::TrailingComments qw/$trailingCommentRegExp/; use LatexIndent::Switches qw/$is_m_switch_active $is_t_switch_active $is_tt_switch_active/; use LatexIndent::Item qw/$listOfItems/; use LatexIndent::LogFile qw/$logger/; -our @EXPORT_OK = qw/modify_line_breaks_body modify_line_breaks_end adjust_line_breaks_end_parent remove_line_breaks_begin max_char_per_line paragraphs_on_one_line construct_paragraph_reg_exp one_sentence_per_line/; +our @EXPORT_OK = qw/modify_line_breaks_body modify_line_breaks_end adjust_line_breaks_end_parent remove_line_breaks_begin text_wrap remove_paragraph_line_breaks construct_paragraph_reg_exp one_sentence_per_line text_wrap_remove_paragraph_line_breaks/; our $paragraphRegExp = q(); sub modify_line_breaks_body{ my $self = shift; - + # add a line break after \begin{statement} if appropriate if(defined ${$self}{BodyStartsOnOwnLine}){ my $BodyStringLogFile = ${$self}{aliases}{BodyStartsOnOwnLine}||"BodyStartsOnOwnLine"; @@ -177,7 +177,6 @@ sub modify_line_breaks_end{ sub adjust_line_breaks_end_parent{ # when a parent object contains a child object, the line break # at the end of the parent object can become messy - return unless $is_m_switch_active; my $self = shift; @@ -208,14 +207,44 @@ sub adjust_line_breaks_end_parent{ } -sub max_char_per_line{ - return unless $is_m_switch_active; +sub text_wrap_remove_paragraph_line_breaks{ + my $self = shift; + + if(${$masterSettings{modifyLineBreaks}{removeParagraphLineBreaks}}{beforeTextWrap}){ + $self->remove_paragraph_line_breaks if ${$self}{removeParagraphLineBreaks}; + $self->text_wrap if (${$self}{textWrapOptions} and ${$masterSettings{modifyLineBreaks}{textWrapOptions}}{perCodeBlockBasis}); + } else { + $self->text_wrap if (${$self}{textWrapOptions} and ${$masterSettings{modifyLineBreaks}{textWrapOptions}}{perCodeBlockBasis}); + } + +} + +sub text_wrap{ my $self = shift; - return unless ${$masterSettings{modifyLineBreaks}{textWrapOptions}}{columns}>1; + + # alignment at ampersand can take priority + return if(${$self}{lookForAlignDelims} and ${$masterSettings{modifyLineBreaks}{textWrapOptions}}{alignAtAmpersandTakesPriority}); # call the text wrapping routine - $Text::Wrap::columns=${$masterSettings{modifyLineBreaks}{textWrapOptions}}{columns}; + my $columns; + + # columns might have been defined by the user + if(defined ${$self}{columns}){ + $columns = ${$self}{columns}; + } elsif(ref ${$masterSettings{modifyLineBreaks}{textWrapOptions}}{columns} eq "HASH"){ + if(defined ${${$masterSettings{modifyLineBreaks}{textWrapOptions}}{columns}}{default}){ + $columns = ${${$masterSettings{modifyLineBreaks}{textWrapOptions}}{columns}}{default}; + } else { + $columns = 80; + } + } elsif (defined ${$masterSettings{modifyLineBreaks}{textWrapOptions}}{columns}){ + $columns = ${$masterSettings{modifyLineBreaks}{textWrapOptions}}{columns} ; + } else { + $columns = 80; + } + + $Text::Wrap::columns=$columns; if(${$masterSettings{modifyLineBreaks}{textWrapOptions}}{separator} ne ''){ $Text::Wrap::separator=${$masterSettings{modifyLineBreaks}{textWrapOptions}}{separator}; } @@ -271,7 +300,7 @@ sub construct_paragraph_reg_exp{ $logger->trace($paragraphRegExp) if $is_tt_switch_active ; } -sub paragraphs_on_one_line{ +sub remove_paragraph_line_breaks{ my $self = shift; return unless ${$self}{removeParagraphLineBreaks}; @@ -481,6 +510,39 @@ sub one_sentence_per_line{ while( my $sentence = pop @sentenceStorage){ my $sentenceStorageID = ${$sentence}{id}; my $sentenceStorageValue = ${$sentence}{value}; + + # option to text wrap (and option to indent) sentences + if(${$masterSettings{modifyLineBreaks}{oneSentencePerLine}}{textWrapSentences}){ + my $sentenceObj = LatexIndent::Document->new(body=>$sentenceStorageValue, + name=>"sentence", + modifyLineBreaksYamlName=>"sentence", + ); + + # text wrapping + $sentenceObj->yaml_get_columns; + $sentenceObj->text_wrap; + + # indentation of sentences + if(${$sentenceObj}{body} =~ m/ + (.*?) # content of first line + \R # first line break + (.*$) # rest of body + /sx){ + my $bodyFirstLine = $1; + my $remainingBody = $2; + my $indentation = ${$masterSettings{modifyLineBreaks}{oneSentencePerLine}}{sentenceIndent}; + $logger->trace("first line of sencent: $bodyFirstLine") if $is_tt_switch_active; + $logger->trace("remaining body (before indentation):\n'$remainingBody'") if($is_tt_switch_active); + + # add the indentation to all the body except first line + $remainingBody =~ s/^/$indentation/mg unless($remainingBody eq ''); # add indentation + $logger->trace("remaining body (after indentation):\n$remainingBody'") if($is_tt_switch_active); + + # put the body back together + ${$sentenceObj}{body} = $bodyFirstLine."\n".$remainingBody; + } + $sentenceStorageValue = ${$sentenceObj}{body}; + }; # sentence at the very END ${$self}{body} =~ s/\h*$sentenceStorageID\h*$/$sentenceStorageValue/s; # sentence at the very BEGINNING diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/OptionalArgument.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/OptionalArgument.pm index f98acac4874..60e03ca91d4 100644 --- a/Master/texmf-dist/scripts/latexindent/LatexIndent/OptionalArgument.pm +++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/OptionalArgument.pm @@ -90,7 +90,7 @@ sub find_optional_arguments{ } } -sub get_object_attribute_for_indentation_settings{ +sub yaml_get_object_attribute_for_indentation_settings{ my $self = shift; return ${$self}{modifyLineBreaksYamlName}; diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/Preamble.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/Preamble.pm index 306b423e5a9..a31efd1a49e 100644 --- a/Master/texmf-dist/scripts/latexindent/LatexIndent/Preamble.pm +++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/Preamble.pm @@ -17,7 +17,7 @@ package LatexIndent::Preamble; use strict; use warnings; use LatexIndent::Tokens qw/%tokens/; -use LatexIndent::Switches qw/$is_t_switch_active/; +use LatexIndent::Switches qw/$is_t_switch_active $is_m_switch_active/; use LatexIndent::GetYamlSettings qw/%masterSettings/; use LatexIndent::LogFile qw/$logger/; use LatexIndent::Environment qw/$environmentBasicRegExp/; @@ -69,7 +69,21 @@ sub tasks_particular_to_each_object{ # search for special begin/end $self->find_special if ${$self}{body} =~ m/$specialBeginBasicRegExp/s; - } + } + + # text wrapping, remove paragraph line breaks + if ($is_m_switch_active){ + $self->yaml_get_textwrap_removeparagraphline_breaks; + + # call the remove_paragraph_line_breaks and text_wrap routines + if(${$masterSettings{modifyLineBreaks}{removeParagraphLineBreaks}}{beforeTextWrap}){ + $self->remove_paragraph_line_breaks if ${$self}{removeParagraphLineBreaks}; + $self->text_wrap if (${$self}{textWrapOptions} and ${$masterSettings{modifyLineBreaks}{textWrapOptions}}{perCodeBlockBasis}); + } else { + $self->text_wrap if (${$self}{textWrapOptions} and ${$masterSettings{modifyLineBreaks}{textWrapOptions}}{perCodeBlockBasis}); + $self->remove_paragraph_line_breaks if ${$self}{removeParagraphLineBreaks}; + } + } } diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/RoundBrackets.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/RoundBrackets.pm index f320d007fa2..fff5efedd00 100644 --- a/Master/texmf-dist/scripts/latexindent/LatexIndent/RoundBrackets.pm +++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/RoundBrackets.pm @@ -79,7 +79,7 @@ sub find_round_brackets{ } } -sub get_object_attribute_for_indentation_settings{ +sub yaml_get_object_attribute_for_indentation_settings{ my $self = shift; return ${$self}{modifyLineBreaksYamlName}; diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/Special.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/Special.pm index aa17f24df13..8898697d0f3 100644 --- a/Master/texmf-dist/scripts/latexindent/LatexIndent/Special.pm +++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/Special.pm @@ -40,7 +40,7 @@ sub construct_special_begin{ while( my ($specialName,$BeginEnd)= each %{$masterSettings{specialBeginEnd}}){ if(ref($BeginEnd) eq "HASH"){ # only append the regexps if lookForThis is 1 - $specialBegins .= ($specialBegins eq ""?q():"|").${$BeginEnd}{begin} if(${$BeginEnd}{lookForThis}); + $specialBegins .= ($specialBegins eq ""?q():"|").${$BeginEnd}{begin} if(${$BeginEnd}{lookForThis}=~m/\d/s and ${$BeginEnd}{lookForThis} == 1); } } @@ -48,9 +48,7 @@ sub construct_special_begin{ while( my ($specialName,$BeginEnd)= each %{$masterSettings{specialBeginEnd}}){ # only append the regexps if lookForThis is 1 - if( (ref($BeginEnd) eq "HASH") and ${$BeginEnd}{lookForThis}){ - # the beginning parts - $specialBegins .= ($specialBegins eq ""?q():"|").${$BeginEnd}{begin}; + if( (ref($BeginEnd) eq "HASH") and ${$BeginEnd}{lookForThis}=~m/\d/s and ${$BeginEnd}{lookForThis} == 1){ # the overall regexp $specialAllMatchesRegExp .= ($specialAllMatchesRegExp eq ""?q():"|") @@ -128,7 +126,7 @@ sub find_special{ while( my ($specialName,$BeginEnd)= each %{$masterSettings{specialBeginEnd}}){ # log file - if((ref($BeginEnd) eq "HASH") and ${$BeginEnd}{lookForThis}){ + if((ref($BeginEnd) eq "HASH") and ${$BeginEnd}{lookForThis}=~m/\d/s and ${$BeginEnd}{lookForThis} == 1){ $logger->trace("Looking for $specialName") if $is_t_switch_active ; } else { $logger->trace("Not looking for $specialName (see lookForThis)") if ($is_t_switch_active and (ref($BeginEnd) eq "HASH")); diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/TrailingComments.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/TrailingComments.pm index 7f2b8e12738..6ec052a0f3b 100644 --- a/Master/texmf-dist/scripts/latexindent/LatexIndent/TrailingComments.pm +++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/TrailingComments.pm @@ -103,7 +103,7 @@ sub put_trailing_comments_back_in{ if(${$masterSettings{modifyLineBreaks}{textWrapOptions}}{separator} ne ''){ $trailingcommentIDwithLineBreaks = join("\\".${$masterSettings{modifyLineBreaks}{textWrapOptions}}{separator}."?",split(//,$trailingcommentID)); } else { - $trailingcommentIDwithLineBreaks = join("\\R?",split(//,$trailingcommentID)); + $trailingcommentIDwithLineBreaks = join("(?:\\h|\\R)*",split(//,$trailingcommentID)); } my $trailingcommentIDwithLineBreaksRegExp = qr/$trailingcommentIDwithLineBreaks/s; diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/Verbatim.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/Verbatim.pm index c79d9604715..836e7ccd88d 100644 --- a/Master/texmf-dist/scripts/latexindent/LatexIndent/Verbatim.pm +++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/Verbatim.pm @@ -22,7 +22,7 @@ use LatexIndent::Tokens qw/%tokens/; use LatexIndent::GetYamlSettings qw/%masterSettings/; use LatexIndent::Switches qw/$is_t_switch_active $is_tt_switch_active $is_m_switch_active/; use LatexIndent::LogFile qw/$logger/; -our @EXPORT_OK = qw/put_verbatim_back_in find_verbatim_environments find_noindent_block find_verbatim_commands put_verbatim_commands_back_in/; +our @EXPORT_OK = qw/put_verbatim_back_in find_verbatim_environments find_noindent_block find_verbatim_commands put_verbatim_commands_back_in find_verbatim_special/; our @ISA = "LatexIndent::Document"; # class inheritance, Programming Perl, pg 321 our $verbatimCounter; @@ -307,6 +307,57 @@ sub put_verbatim_commands_back_in { return; } +sub find_verbatim_special{ + my $self = shift; + + # loop through specialBeginEnd + while( my ($specialName,$BeginEnd)= each %{$masterSettings{specialBeginEnd}}){ + + # only classify special Verbatim if lookForThis is 'verbatim' + if( (ref($BeginEnd) eq "HASH") and ${$BeginEnd}{lookForThis}=~m/v/s and ${$BeginEnd}{lookForThis} eq 'verbatim'){ + $logger->trace('*Searching for VERBATIM special (see specialBeginEnd)') if $is_t_switch_active; + + my $verbatimRegExp = qr/ + ( + ${$BeginEnd}{begin} + ) + ( + .*? + ) + ( + ${$BeginEnd}{end} + ) + /sx; + + while( ${$self}{body} =~ m/$verbatimRegExp/sx){ + + # create a new Environment object + my $verbatimBlock = LatexIndent::Verbatim->new( begin=>$1, + body=>$2, + end=>$3, + name=>$specialName, + ); + # give unique id + $verbatimBlock->create_unique_id; + + # verbatim children go in special hash + ${$self}{verbatim}{${$verbatimBlock}{id}}=$verbatimBlock; + + # log file output + $logger->trace("*VERBATIM special found: $specialName") if $is_t_switch_active; + + # remove the special block, and replace with unique ID + ${$self}{body} =~ s/$verbatimRegExp/${$verbatimBlock}{id}/sx; + + $logger->trace("replaced with ID: ${$verbatimBlock}{id}") if $is_t_switch_active; + + # possible decoration in log file + $logger->trace(${$masterSettings{logFilePreferences}}{showDecorationFinishCodeBlockTrace}) if ${$masterSettings{logFilePreferences}}{showDecorationFinishCodeBlockTrace}; + } + } + } +} + sub create_unique_id{ my $self = shift; diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/Version.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/Version.pm index bfec70b7942..989d4f73fb1 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.4.3'; -our $versionDate = '2018-06-08'; +our $versionNumber = '3.5'; +our $versionDate = '2018-08-13'; 1 diff --git a/Master/texmf-dist/scripts/latexindent/defaultSettings.yaml b/Master/texmf-dist/scripts/latexindent/defaultSettings.yaml index 785b805eed7..a1ef1172aca 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.4.3, 2018-06-08 +# defaultSettings.yaml for latexindent.pl, version 3.5, 2018-08-13 # a script that aims to # beautify .tex, .sty, .cls files # @@ -394,12 +394,11 @@ commandCodeBlocks: modifyLineBreaks: preserveBlankLines: 1 condenseMultipleBlankLinesInto: 1 - textWrapOptions: - columns: 0 - separator: "" oneSentencePerLine: manipulateSentences: 0 removeSentenceLineBreaks: 1 + textWrapSentences: 0 + sentenceIndent: "" sentencesFollow: par: 1 blankLine: 1 @@ -419,8 +418,26 @@ modifyLineBreaks: exclamationMark: 1 questionMark: 1 other: 0 + textWrapOptions: + columns: 0 + separator: "" + perCodeBlockBasis: 0 + all: 0 + alignAtAmpersandTakesPriority: 1 + environments: + quotation: 0 + ifElseFi: 0 + optionalArguments: 0 + mandatoryArguments: 0 + items: 0 + specialBeginEnd: 0 + afterHeading: 0 + preamble: 0 + filecontents: 0 + masterDocument: 0 removeParagraphLineBreaks: all: 0 + beforeTextWrap: 0 alignAtAmpersandTakesPriority: 1 environments: quotation: 0 @@ -430,10 +447,12 @@ modifyLineBreaks: items: 0 specialBeginEnd: 0 afterHeading: 0 + preamble: 0 filecontents: 0 masterDocument: 0 paragraphsStopAt: environments: 1 + verbatim: 1 commands: 0 ifElseFi: 0 items: 0 diff --git a/Master/texmf-dist/scripts/latexindent/latexindent.pl b/Master/texmf-dist/scripts/latexindent/latexindent.pl index c9835ccbe37..0945273d857 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.4.3, 2018-06-08 +# latexindent.pl, version 3.5, 2018-08-13 # # 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 @@ -73,6 +73,6 @@ if(defined($switches{readLocalSettings}) and ($switches{readLocalSettings} eq '' # allow STDIN as input, if a filename is not present unshift( @ARGV, '-' ) unless @ARGV; -my $document = bless ({name=>"masterDocument",fileName=>$ARGV[0],switches=>\%switches},"LatexIndent::Document"); +my $document = bless ({name=>"masterDocument",modifyLineBreaksYamlName=>"masterDocument",fileName=>$ARGV[0],switches=>\%switches},"LatexIndent::Document"); $document->latexindent; exit(0); -- cgit v1.2.3