diff options
author | Karl Berry <karl@freefriends.org> | 2023-01-01 20:33:08 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2023-01-01 20:33:08 +0000 |
commit | 50f06dfb39538412ac53208846b25f243cd5b6f4 (patch) | |
tree | 7fedb48a15a8249fd561133c148c19aad7b15b34 /Master/texmf-dist/doc/support | |
parent | 35311fd4a540d53f0a3626adf611e21fade0cb06 (diff) |
latexindent (1jan23)
git-svn-id: svn://tug.org/texlive/trunk@65427 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/support')
-rw-r--r-- | Master/texmf-dist/doc/support/latexindent/README | 2 | ||||
-rw-r--r-- | Master/texmf-dist/doc/support/latexindent/contributors.bib | 8 | ||||
-rw-r--r-- | Master/texmf-dist/doc/support/latexindent/latexindent-yaml-schema.json | 2 | ||||
-rw-r--r-- | Master/texmf-dist/doc/support/latexindent/latexindent.pdf | bin | 1166672 -> 1240112 bytes | |||
-rw-r--r-- | Master/texmf-dist/doc/support/latexindent/latexindent.tex | 2514 |
5 files changed, 1548 insertions, 978 deletions
diff --git a/Master/texmf-dist/doc/support/latexindent/README b/Master/texmf-dist/doc/support/latexindent/README index 52b5bfcce71..ed1737c8ef4 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.19.1, 2022-12-04 + latexindent.pl, version 3.20, 2023-01-01 PERL script to indent code within environments, and align delimited environments in .tex files. diff --git a/Master/texmf-dist/doc/support/latexindent/contributors.bib b/Master/texmf-dist/doc/support/latexindent/contributors.bib index 4b7af4f8daa..0e74a4798bd 100644 --- a/Master/texmf-dist/doc/support/latexindent/contributors.bib +++ b/Master/texmf-dist/doc/support/latexindent/contributors.bib @@ -174,3 +174,11 @@ author = "eggplants", urldate = {2022-06-12}, keywords = {contributor},} + +@online{nehctargl, + title = " Added support for the XDG specification", + url = "https://github.com/cmhughes/latexindent.pl/pull/397", + date = {2022-12-23}, + author = "Nehctargl", + urldate = {2022-12-23}, + keywords = {contributor},} diff --git a/Master/texmf-dist/doc/support/latexindent/latexindent-yaml-schema.json b/Master/texmf-dist/doc/support/latexindent/latexindent-yaml-schema.json index b8492f4b159..5d490c800c1 100644 --- a/Master/texmf-dist/doc/support/latexindent/latexindent-yaml-schema.json +++ b/Master/texmf-dist/doc/support/latexindent/latexindent-yaml-schema.json @@ -2,7 +2,7 @@ "$schema": "http://json-schema.org/schema", "$id": "latexindent-yaml-schema.json", "title": "latexindent.pl YAML schema", - "description": "latexindent.pl YAML schema helper, V3.19.1 2022-12-04", + "description": "latexindent.pl YAML schema helper, V3.20 2023-01-01", "type": "object", "properties": { "fileExtensionPreference": { diff --git a/Master/texmf-dist/doc/support/latexindent/latexindent.pdf b/Master/texmf-dist/doc/support/latexindent/latexindent.pdf Binary files differindex 383437f181d..2717823a164 100644 --- a/Master/texmf-dist/doc/support/latexindent/latexindent.pdf +++ b/Master/texmf-dist/doc/support/latexindent/latexindent.pdf diff --git a/Master/texmf-dist/doc/support/latexindent/latexindent.tex b/Master/texmf-dist/doc/support/latexindent/latexindent.tex index d58def5ed89..a1fa404dda0 100644 --- a/Master/texmf-dist/doc/support/latexindent/latexindent.tex +++ b/Master/texmf-dist/doc/support/latexindent/latexindent.tex @@ -335,10 +335,17 @@ #3, } +% reference: https://tex.stackexchange.com/questions/145504/yaml-syntax-highlighting/654987#654987 \lstdefinestyle{yaml-LST}{ style=tcblatex, numbers=none, - numberstyle=\color{red}, + numberstyle=\color{red}\small, + basicstyle=\color{black}\ttfamily\small, + string=[s]{'}{'}, + stringstyle=\color{black}\ttfamily\small, + comment=[l]{:}, + commentstyle=\color{blue}\ttfamily\small, + morecomment=[l]{-}, } \lstdefinestyle{demo}{ @@ -474,7 +481,7 @@ \lstdefinestyle{textWrapOptionsAll}{ style=yaml-LST, - firstnumber=523,linerange={523-546}, + firstnumber=523,linerange={523-550}, numbers=left, } @@ -504,19 +511,19 @@ \lstdefinestyle{modifylinebreaksEnv}{ style=yaml-LST, - firstnumber=548,linerange={548-557}, + firstnumber=552,linerange={552-561}, numbers=left, } \lstdefinestyle{replacements}{ style=yaml-LST, - firstnumber=609,linerange={609-617}, + firstnumber=613,linerange={613-621}, numbers=left, } \lstdefinestyle{fineTuning}{ style=yaml-LST, - firstnumber=620,linerange={620-672}, + firstnumber=624,linerange={624-676}, numbers=left, } @@ -807,9 +814,9 @@ 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}. + 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 @@ -821,8 +828,8 @@ \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: + 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 @@ -831,8 +838,9 @@ \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 - complete minimum working example as I would like to improve the code as much as possible. + the correct settings, and then feel free to let me know at \cite{latexindent-home} with + a complete minimum working example as I would like to improve the code as much as + possible. \begin{warning} Before you try the script on anything important (like your thesis), test it out on the @@ -853,9 +861,9 @@ latexindent.pl myfile.tex from the command line. - We give an introduction to \texttt{latexindent.pl} using \cref{lst:quick-start}; there is - no explanation in this section, which is deliberate for a quick start. The rest of the - manual is more verbose. + We give an introduction to \texttt{latexindent.pl} using \cref{lst:quick-start}; there + is no explanation in this section, which is deliberate for a quick start. The rest of + the manual is more verbose. \cmhlistingsfromfile{demonstrations/quick-start.tex}{\texttt{quick-start.tex}}{lst:quick-start} @@ -879,9 +887,10 @@ latexindent.pl -l quick-start1.yaml quick-start.tex gives \cref{lst:quick-start-mod1}. \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/quick-start1.yaml}[yaml-TCB]{\texttt{quick-start1.yaml}}{lst:quick-start1yaml} \cmhlistingsfromfile[showspaces=true]{demonstrations/quick-start-mod1.tex}{\texttt{quick-start-mod1.tex}}{lst:quick-start-mod1} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/quick-start1.yaml}[yaml-TCB]{\texttt{quick-start1.yaml}}{lst:quick-start1yaml} \end{cmhtcbraster} + See \cref{subsec:indentation:and:horizontal:space}. \end{example} \begin{example} @@ -894,9 +903,10 @@ latexindent.pl -l quick-start2.yaml quick-start.tex gives \cref{lst:quick-start-mod2}. \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/quick-start2.yaml}[yaml-TCB]{\texttt{quick-start2.yaml}}{lst:quick-start2yaml} \cmhlistingsfromfile[showspaces=true]{demonstrations/quick-start-mod2.tex}{\texttt{quick-start-mod2.tex}}{lst:quick-start-mod2} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/quick-start2.yaml}[yaml-TCB]{\texttt{quick-start2.yaml}}{lst:quick-start2yaml} \end{cmhtcbraster} + See \cref{sec:noadd-indent-rules}. \end{example} \begin{example} @@ -909,9 +919,10 @@ latexindent.pl -l quick-start3.yaml quick-start.tex gives \cref{lst:quick-start-mod3}. \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/quick-start3.yaml}[yaml-TCB]{\texttt{quick-start3.yaml}}{lst:quick-start3yaml} \cmhlistingsfromfile{demonstrations/quick-start-mod3.tex}{\texttt{quick-start-mod3.tex}}{lst:quick-start-mod3} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/quick-start3.yaml}[yaml-TCB]{\texttt{quick-start3.yaml}}{lst:quick-start3yaml} \end{cmhtcbraster} + See \cref{sec:noadd-indent-rules}. \end{example} \begin{example} @@ -924,8 +935,8 @@ latexindent.pl -m -l quick-start4.yaml quick-start.tex gives \cref{lst:quick-start-mod4}. \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/quick-start4.yaml}[MLB-TCB]{\texttt{quick-start4.yaml}}{lst:quick-start4yaml} \cmhlistingsfromfile{demonstrations/quick-start-mod4.tex}{\texttt{quick-start-mod4.tex}}{lst:quick-start-mod4} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/quick-start4.yaml}[MLB-TCB]{\texttt{quick-start4.yaml}}{lst:quick-start4yaml} \end{cmhtcbraster} Full details of text wrapping in \cref{subsec:textwrapping}. \end{example} @@ -940,8 +951,8 @@ latexindent.pl -m -l quick-start5.yaml quick-start.tex gives \cref{lst:quick-start-mod5}. \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/quick-start5.yaml}[MLB-TCB]{\texttt{quick-start5.yaml}}{lst:quick-start5yaml} \cmhlistingsfromfile{demonstrations/quick-start-mod5.tex}{\texttt{quick-start-mod5.tex}}{lst:quick-start-mod5} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/quick-start5.yaml}[MLB-TCB]{\texttt{quick-start5.yaml}}{lst:quick-start5yaml} \end{cmhtcbraster} Full details of text wrapping in \cref{subsec:textwrapping}. \end{example} @@ -956,8 +967,8 @@ latexindent.pl -m -l quick-start6.yaml quick-start.tex gives \cref{lst:quick-start-mod6}. \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/quick-start6.yaml}[MLB-TCB]{\texttt{quick-start6.yaml}}{lst:quick-start6yaml} \cmhlistingsfromfile{demonstrations/quick-start-mod6.tex}{\texttt{quick-start-mod6.tex}}{lst:quick-start-mod6} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/quick-start6.yaml}[MLB-TCB]{\texttt{quick-start6.yaml}}{lst:quick-start6yaml} \end{cmhtcbraster} This is an example of a \emph{poly-switch}; full details of \emph{poly-switches} are covered in \cref{sec:poly-switches}. @@ -973,12 +984,47 @@ latexindent.pl -m -l quick-start7.yaml quick-start.tex gives \cref{lst:quick-start-mod7}. \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/quick-start7.yaml}[MLB-TCB]{\texttt{quick-start7.yaml}}{lst:quick-start7yaml} \cmhlistingsfromfile{demonstrations/quick-start-mod7.tex}{\texttt{quick-start-mod7.tex}}{lst:quick-start-mod7} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/quick-start7.yaml}[MLB-TCB]{\texttt{quick-start7.yaml}}{lst:quick-start7yaml} \end{cmhtcbraster} Full details of \emph{poly-switches} are covered in \cref{sec:poly-switches}. \end{example} + \begin{example} + Running + + \begin{commandshell} +latexindent.pl -l quick-start8.yaml quick-start.tex +\end{commandshell} + + gives \cref{lst:quick-start-mod8}; note that the \emph{preamble} has been indented. + + \begin{cmhtcbraster} + \cmhlistingsfromfile*{demonstrations/quick-start-mod8.tex}{\texttt{quick-start-mod8.tex}}{lst:quick-start-mod8} + \cmhlistingsfromfile*[style=yaml-LST]{demonstrations/quick-start8.yaml}[yaml-TCB]{\texttt{quick-start8.yaml}}{lst:quick-start8yaml} + \end{cmhtcbraster} + + See \cref{subsec:filecontents:preamble}. + + \end{example} + + \begin{example} + Running + + \begin{commandshell} +latexindent.pl -l quick-start9.yaml quick-start.tex +\end{commandshell} + + gives \cref{lst:quick-start-mod9}. + + \begin{cmhtcbraster} + \cmhlistingsfromfile*{demonstrations/quick-start-mod9.tex}{\texttt{quick-start-mod9.tex}}{lst:quick-start-mod9} + \cmhlistingsfromfile*[style=yaml-LST]{demonstrations/quick-start9.yaml}[yaml-TCB]{\texttt{quick-start9.yaml}}{lst:quick-start9yaml} + \end{cmhtcbraster} + + See \cref{sec:noadd-indent-rules}. + \end{example} + \subsection{Required perl modules} If you receive an error message such as that given in \cref{lst:poss-errors}, then you need to install the missing perl modules. @@ -1005,43 +1051,45 @@ perl latexindent-module-installer.pl The different listings are presented using different styles: - \begin{minipage}{.4\textwidth} - \cmhlistingsfromfile{demonstrations/demo-tex.tex}{\texttt{demo-tex.tex}}{lst:demo-tex} - \end{minipage}% - \hfill - \begin{minipage}{.4\textwidth} - This type of listing is a \texttt{.tex} file. - \end{minipage}% + \begin{widepage} + \begin{minipage}{.4\linewidth} + \cmhlistingsfromfile{demonstrations/demo-tex.tex}{\texttt{demo-tex.tex}}{lst:demo-tex} + \end{minipage}% + \hfill + \begin{minipage}{.4\linewidth} + This type of listing is a \texttt{.tex} file. + \end{minipage}% - \begin{minipage}{.4\textwidth} - \cmhlistingsfromfile[style=fileExtensionPreference]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{fileExtensionPreference}}{lst:fileExtensionPreference-demo} - \end{minipage}% - \hfill - \begin{minipage}{.4\textwidth} - This type of listing is a \texttt{.yaml} file; when you see line numbers given (as here) - it means that the snippet is taken directly from \texttt{defaultSettings.yaml}, discussed in - detail in \vref{sec:defuseloc}. - \end{minipage}% + \begin{minipage}{.4\linewidth} + \cmhlistingsfromfile[style=fileExtensionPreference]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{fileExtensionPreference}}{lst:fileExtensionPreference-demo} + \end{minipage}% + \hfill + \begin{minipage}{.4\linewidth} + This type of listing is a \texttt{.yaml} file; when you see line numbers given (as here) + it means that the snippet is taken directly from \texttt{defaultSettings.yaml}, discussed in + detail in \vref{sec:defuseloc}. + \end{minipage}% - \begin{minipage}{.55\textwidth} - \cmhlistingsfromfile[style=modifylinebreaks]{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{modifyLineBreaks}}{lst:modifylinebreaks-demo} - \end{minipage}% - \hfill - \begin{minipage}{.4\textwidth} - This type of listing is a \texttt{.yaml} file, but it will only - be relevant when the \texttt{-m} switch is active; see \vref{sec:modifylinebreaks} - for more details. - \end{minipage}% + \begin{minipage}{.6\linewidth} + \cmhlistingsfromfile[style=modifylinebreaks]{../defaultSettings.yaml}[MLB-TCB,width=.95\linewidth,before=\centering]{\texttt{modifyLineBreaks}}{lst:modifylinebreaks-demo} + \end{minipage}% + \hfill + \begin{minipage}{.4\linewidth} + This type of listing is a \texttt{.yaml} file, but it will only + be relevant when the \texttt{-m} switch is active; see \vref{sec:modifylinebreaks} + for more details. + \end{minipage}% - \begin{minipage}{.55\textwidth} - \cmhlistingsfromfile[style=replacements]{../defaultSettings.yaml}[replace-TCB,width=.85\linewidth,before=\centering]{\texttt{replacements}}{lst:replacements-demo} - \end{minipage}% - \hfill - \begin{minipage}{.4\textwidth} - This type of listing is a \texttt{.yaml} file, but it will only - be relevant when the \texttt{-r} switch is active; see \vref{sec:replacements} - for more details. - \end{minipage}% + \begin{minipage}{.6\linewidth} + \cmhlistingsfromfile[style=replacements]{../defaultSettings.yaml}[replace-TCB,width=.95\linewidth,before=\centering]{\texttt{replacements}}{lst:replacements-demo} + \end{minipage}% + \hfill + \begin{minipage}{.4\linewidth} + This type of listing is a \texttt{.yaml} file, but it will only + be relevant when the \texttt{-r} switch is active; see \vref{sec:replacements} + for more details. + \end{minipage}% + \end{widepage} % \begin{latexonly} You will occasionally see dates shown in the margin (for example, next to this @@ -1063,21 +1111,21 @@ perl latexindent-module-installer.pl expressions, and if you'd like to read about them, I recommend \cite{masteringregexp}. % arara: pdflatex: { 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 personalise 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 - environment or \texttt{noIndentBlock} is specified -- more on this in - \cref{sec:defuseloc}). + 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} \centering @@ -1143,7 +1191,7 @@ perl latexindent-module-installer.pl \index{latexindent-linux} \index{linux} \index{TeXLive} \texttt{latexindent-linux} is available from \cite{latexindent-home}. - \announce*{2022-10-30}{Linux Ubuntu standalone executable} + \announce{2022-10-30}{Linux Ubuntu standalone executable} \subsubsection{macOS users without perl} \texttt{latexindent.pl} ships with \texttt{latexindent-macos} for macOS @@ -1151,7 +1199,7 @@ perl latexindent-module-installer.pl \index{latexindent-macos} \index{macOS} \index{TeXLive} \texttt{latexindent-macOS} is available from \cite{latexindent-home}. - \announce*{2022-10-30}{macOS standalone executable} + \announce{2022-10-30}{macOS standalone executable} \subsubsection{conda users} Users of \texttt{conda} should see the details given in \cref{sec:app:conda}. @@ -1201,8 +1249,8 @@ latexindent.pl -h latexindent.pl --help \end{commandshell} - As above this will output a welcome message to the terminal, including the version number - and available options. + As above this will output a welcome message to the terminal, including the version + number and available options. \begin{commandshell} latexindent.pl myfile.tex @@ -1237,9 +1285,9 @@ latexindent.pl myfile.tex --overwrite \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{-wd, --overwriteIfDifferent} \index{switches!-wd, --overwriteIfDifferent definition and details} @@ -1270,14 +1318,14 @@ latexindent.pl --outputfile=output.tex myfile.tex latexindent.pl --outputfile output.tex myfile.tex \end{commandshell} - 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}. + 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). The same is true for the \texttt{-wd} switch, and the - \texttt{-o} switch takes priority over it. + switches, then \texttt{-w} will be ignored and \texttt{-o} will take priority (this + seems safer than the other way round). The same is true for the \texttt{-wd} switch, and + the \texttt{-o} switch takes priority over it. Note that using \texttt{-o} as above is equivalent to using @@ -1295,9 +1343,9 @@ 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 - \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 + 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:% \begin{commandshell} @@ -1337,7 +1385,8 @@ latexindent.pl myfile.tex -o=+out++ 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 + you wish to, then you should include it \emph{after} the \texttt{++} symbols, for + example \begin{commandshell} latexindent.pl myfile.tex -o=+out++.tex @@ -1407,8 +1456,8 @@ latexindent.pl myfile.tex -l=first.yaml,second.yaml,third.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}. + \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% @@ -1418,8 +1467,8 @@ 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: @@ -1454,8 +1503,8 @@ latexindent.pl -l + myyaml.yaml myfile.tex 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}% + You may also choose to omit the \texttt{yaml} extension, such as + \announce{2017-06-25}{no extension for -l switch}% \begin{commandshell} latexindent.pl -l=localSettings,myyaml myfile.tex @@ -1493,8 +1542,8 @@ latexindent.pl -d myfile.tex 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{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.% @@ -1576,8 +1625,9 @@ cat myfile.tex | latexindent.pl - have content in \texttt{myfile.tex}, then the above command will output the results of operating upon \texttt{myfile.tex}. - If you wish to use this feature with your own local settings, via the \texttt{-l} switch, - then you should finish your call to \texttt{latexindent.pl} with a \texttt{-} sign: + If you wish to use this feature with your own local settings, via the \texttt{-l} + switch, then you should finish your call to \texttt{latexindent.pl} with a \texttt{-} + sign: \begin{commandshell} cat myfile.tex | latexindent.pl -l=mysettings.yaml - @@ -1606,9 +1656,9 @@ latexindent.pl -replacement myfile.tex \end{commandshell} You can \announce{2019-07-13}{replacement mode switch} call \texttt{latexindent.pl} with - the \texttt{-r} switch to instruct it to perform replacements/substitutions on your file; - full details and examples are given in \vref{sec:replacements}. \index{verbatim!rv, - replacementrespectverb switch}% + the \texttt{-r} switch to instruct it to perform replacements/substitutions on your + file; full details and examples are given in \vref{sec:replacements}. + \index{verbatim!rv, replacementrespectverb switch}% \flagbox{-rv, --replacementrespectverb} \index{switches!-rv, --replacementrespectverb definition and details} @@ -1620,8 +1670,8 @@ latexindent.pl -replacementrespectverb myfile.tex You can \announce{2019-07-13}{replacement mode switch, respecting verbatim} instruct \texttt{latexindent.pl} to perform replacements/substitutions by using the \texttt{-rv} - switch, but will \emph{respect verbatim code blocks}; full details and examples are given - in \vref{sec:replacements}.% + switch, but will \emph{respect verbatim code blocks}; full details and examples are + given in \vref{sec:replacements}.% \flagbox{-rr, --onlyreplacement} \index{switches!-rr, --onlyreplacement definition and details} @@ -1644,16 +1694,16 @@ latexindent.pl -k myfile.tex latexindent.pl -check myfile.tex \end{commandshell} - You can \announce{2021-09-16}{-k,-check switch} instruct \texttt{latexindent.pl} to check - if the text after indentation matches that given in the original file.% + You can \announce{2021-09-16}{-k,-check switch} instruct \texttt{latexindent.pl} to + check if the text after indentation matches that given in the original file.% The \texttt{exit} code \index{exit code} of \texttt{latexindent.pl} is 0 by default. If you use the \texttt{-k} switch then \begin{itemize} - \item if the text after indentation matches that given in the original file, then the exit code - is 0; - \item if the text after indentation does \emph{not} match that given in the original file, then - the exit code is 1. + \item if the text after indentation matches that given in the original file, then the + exit code is 0; + \item if the text after indentation does \emph{not} match that given in the original + file, then the exit code is 1. \end{itemize} The value of the exit code may be important to those wishing to, for example, check the @@ -1713,7 +1763,8 @@ latexindent.pl --GCString myfile.tex latexindent.pl myfile.tex \end{commandshell} - then \texttt{latexindent.pl} can exit with the exit codes given in \cref{tab:exit-codes}. + then \texttt{latexindent.pl} can exit with the exit codes given in + \cref{tab:exit-codes}. \begin{table}[!htb] \caption{Exit codes for \texttt{latexindent.pl}} @@ -1736,10 +1787,14 @@ latexindent.pl myfile.tex \end{table} % arara: pdflatex: { 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. + + We focus our discussion on \texttt{indentconfig.yaml}, but there are other options which + are detailed in \cref{app:indentconfig:options}. \announce*{2023-01-01}{indentconfig + location options} \subsection{indentconfig.yaml and .indentconfig.yaml} \texttt{latexindent.pl} will always check your home directory for @@ -1754,26 +1809,13 @@ latexindent.pl myfile.tex \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. - - \begin{yaml}{\texttt{indentconfig.yaml} (sample)}{lst:indentconfig} -# Paths to user settings for latexindent.pl -# -# Note that the settings will be read in the order you -# specify here- each successive settings file will overwrite -# the variables that you specify - -paths: -- /home/cmhughes/Documents/yamlfiles/mysettings.yaml -- /home/cmhughes/folder/othersettings.yaml -- /some/other/folder/anynameyouwant.yaml -- C:\Users\chughes\Documents\mysettings.yaml -- C:\Users\chughes\Desktop\test spaces\more spaces.yaml -\end{yaml} + 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. + + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/indent-config.yaml}[yaml-TCB]{\texttt{indentconfig.yaml} (sample)}{lst:indentconfig} 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 @@ -1783,28 +1825,21 @@ paths: 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 + 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. \index{indentation!defaultIndent using YAML file} - \begin{yaml}{\texttt{mysettings.yaml} (example)}{lst:mysettings} -# Default value of indentation -defaultIndent: "\t\t\t\t" - -# environments that have tab delimiters, add more -# as needed -lookForAlignDelims: - tabbing: 1 -\end{yaml} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/tabbing.yaml}[yaml-TCB]{\texttt{mysettings.yaml} (example)}{lst:mysettings} 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 recognise - then you'll get a warning, otherwise you'll get confirmation that \texttt{latexindent.pl} - has read your settings file \footnote{Windows users may find that they have to end - \texttt{.yaml} files with a blank line}. \index{warning!editing YAML files} + then you'll get a warning, otherwise you'll get confirmation that + \texttt{latexindent.pl} has read your settings file \footnote{Windows users may find + that they have to end \texttt{.yaml} files with a blank line}. \index{warning!editing + YAML files} \begin{warning} When editing \texttt{.yaml} files it is \emph{extremely} important to remember how @@ -1817,12 +1852,12 @@ lookForAlignDelims: \end{warning} If you find that \announce{2021-06-19}{encoding option for indentconfig.yaml} - \texttt{latexindent.pl} does not read your YAML file, then it might be as a result of the - default commandline encoding not being UTF-8; normally this will only occcur for Windows - users. In this case, you might like to explore the \texttt{encoding} option for + \texttt{latexindent.pl} does not read your YAML file, then it might be as a result of + the default commandline encoding not being UTF-8; normally this will only occcur for + Windows users. In this case, you might like to explore the \texttt{encoding} option for \texttt{indentconfig.yaml} as demonstrated in \cref{lst:indentconfig-encoding}.% - \cmhlistingsfromfile{demonstrations/encoding.yaml}[yaml-TCB]{The \texttt{encoding} option for \texttt{indentconfig.yaml}}{lst:indentconfig-encoding} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/encoding.yaml}[yaml-TCB]{The \texttt{encoding} option for \texttt{indentconfig.yaml}}{lst:indentconfig-encoding} Thank you to \cite{qiancy98} for this contribution; please see \vref{app:encoding} and details within \cite{encoding} for further information. @@ -1877,9 +1912,10 @@ 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% @@ -1893,9 +1929,9 @@ verbatimEnvironments: latexindent.pl -y="verbatimEnvironments:cmhenvironment:0;myenv:1" myfile.tex \end{commandshell} - Note the use of \texttt{;} to specify another field within \texttt{verbatimEnvironments}. - This is shorthand, and equivalent, to using the following command: \index{switches!-y - demonstration} + Note the use of \texttt{;} to specify another field within + \texttt{verbatimEnvironments}. This is shorthand, and equivalent, to using the following + command: \index{switches!-y demonstration} \begin{commandshell} latexindent.pl -y="verbatimEnvironments:cmhenvironment:0,verbatimEnvironments:myenv:1" myfile.tex @@ -1913,11 +1949,11 @@ latexindent.pl -l=mysettings.yaml -y="verbatimEnvironments:cmhenvironment:0;myen specified using \texttt{indentconfig.yaml} and the \texttt{-l} switch. If you wish to specify any regex-based settings using the \texttt{-y} switch, - \index{regular expressions!using -y switch} it is important not to use quotes surrounding - the regex; for example, with reference to the `one sentence per line' feature - (\vref{sec:onesentenceperline}) and the listings within \vref{lst:sentencesEndWith}, the - following settings give the option to have sentences end with a semicolon - \index{switches!-y demonstration} + \index{regular expressions!using -y switch} it is important not to use quotes + surrounding the regex; for example, with reference to the `one sentence per line' + feature (\vref{sec:onesentenceperline}) and the listings within + \vref{lst:sentencesEndWith}, the following settings give the option to have sentences + end with a semicolon \index{switches!-y demonstration} \begin{commandshell} latexindent.pl -m --yaml='modifyLineBreaks:oneSentencePerLine:sentencesEndWith:other:\;' @@ -1937,8 +1973,8 @@ latexindent.pl -m --yaml='modifyLineBreaks:oneSentencePerLine:sentencesEndWith:o 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 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}. @@ -1966,10 +2002,11 @@ latexindent.pl -m --yaml='modifyLineBreaks:oneSentencePerLine:sentencesEndWith:o 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. - For most of the settings in \texttt{defaultSettings.yaml} that are specified as integers, - then we understand \texttt{0} to represent `off' and \texttt{1} to represent `on'. For - fields that allow values other than \texttt{0} or \texttt{1}, it is hoped that the - specific context and associated commentary should make it clear which values are allowed. + For most of the settings in \texttt{defaultSettings.yaml} that are specified as + integers, then we understand \texttt{0} to represent `off' and \texttt{1} to represent + `on'. For fields that allow values other than \texttt{0} or \texttt{1}, it is hoped that + the specific context and associated commentary should make it clear which values are + allowed. \yamltitle{fileExtensionPreference}*{fields} \texttt{latexindent.pl} can be called to @@ -1980,8 +2017,9 @@ latexindent.pl myfile \end{commandshell} 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. + \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. \cmhlistingsfromfile[style=fileExtensionPreference]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{fileExtensionPreference}}{lst:fileExtensionPreference} @@ -2001,8 +2039,8 @@ latexindent.pl myfile 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: + 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} @@ -2017,10 +2055,10 @@ latexindent.pl myfile \index{backup files!number of backup files} \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 + 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} @@ -2051,11 +2089,11 @@ copy myfile.bak4 to myfile.bak3 \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 + 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}.% @@ -2070,14 +2108,15 @@ copy myfile.bak4 to myfile.bak3 options} for Perl's \texttt{Dumper} module can be specified in \cref{lst:logFilePreferences}; see \cite{dumper} and \cite{dumperdemo} for more information. These options will mostly be helpful for those calling - \texttt{latexindent.pl} with the \texttt{-tt} option described in \cref{sec:commandline}.% + \texttt{latexindent.pl} with the \texttt{-tt} option described in + \cref{sec:commandline}.% \subsection{Verbatim code blocks} \yamltitle{verbatimEnvironments}*{fields} - A field that contains a list of environments that you would like left completely alone -- - no indentation will be performed on environments that you have specified in this field, - see \cref{lst:verbatimEnvironments}. \index{verbatim!environments} + A field that contains a list of environments that you would like left completely alone + -- no indentation will be performed on environments that you have specified in this + field, see \cref{lst:verbatimEnvironments}. \index{verbatim!environments} \index{verbatim!commands} \begin{cmhtcbraster}[raster column skip=.1\linewidth] @@ -2085,13 +2124,13 @@ copy myfile.bak4 to myfile.bak3 \cmhlistingsfromfile[style=verbatimCommands]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{verbatimCommands}}{lst:verbatimCommands} \end{cmhtcbraster} - Note that if you put an environment in \texttt{verbatimEnvironments} and in other fields + 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}. You can, optionally, specify \announce{2021-10-30}{verbatim name feature} the - \texttt{verbatim} field using the \texttt{name} field which takes a regular expression as - its argument; thank you to \cite{XuehaiPan} for contributing this feature. + \texttt{verbatim} field using the \texttt{name} field which takes a regular expression + as its argument; thank you to \cite{XuehaiPan} for contributing this feature. \begin{example} For demonstration, then assuming that your file contains the environments @@ -2099,18 +2138,18 @@ copy myfile.bak4 to myfile.bak3 then the listings given in \cref{lst:nameAsRegex1,lst:nameAsRegex2} are equivalent. \begin{cmhtcbraster}[raster column skip=.1\linewidth] - \cmhlistingsfromfile{demonstrations/nameAsRegex1.yaml}[yaml-TCB]{\texttt{nameAsRegex1.yaml}}{lst:nameAsRegex1} - \cmhlistingsfromfile{demonstrations/nameAsRegex2.yaml}[yaml-TCB]{\texttt{nameAsRegex2.yaml}}{lst:nameAsRegex2} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/nameAsRegex1.yaml}[yaml-TCB]{\texttt{nameAsRegex1.yaml}}{lst:nameAsRegex1} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/nameAsRegex2.yaml}[yaml-TCB]{\texttt{nameAsRegex2.yaml}}{lst:nameAsRegex2} \end{cmhtcbraster} With reference to \cref{lst:nameAsRegex2}: \begin{itemize} - \item the \texttt{name} field as specified here means \emph{any word followed by the word code, - optionally followed by *}; - \item we have used \texttt{nameAsRegex} to identify this field, but you can use any description - you like; - \item the \texttt{lookForThis} field is optional, and can take the values 0 (off) or 1 (on); by - default, it is assumed to be 1 (on). + \item the \texttt{name} field as specified here means \emph{any word followed by the + word code, optionally followed by *}; + \item we have used \texttt{nameAsRegex} to identify this field, but you can use any + description you like; + \item the \texttt{lookForThis} field is optional, and can take the values 0 (off) or 1 + (on); by default, it is assumed to be 1 (on). \end{itemize} \end{example} @@ -2135,26 +2174,26 @@ copy myfile.bak4 to myfile.bak3 \cref{lst:nameAsRegex3,lst:nameAsRegex4} are equivalent. \begin{cmhtcbraster}[raster column skip=.1\linewidth] - \cmhlistingsfromfile{demonstrations/nameAsRegex3.yaml}[yaml-TCB]{\texttt{nameAsRegex3.yaml}}{lst:nameAsRegex3} - \cmhlistingsfromfile{demonstrations/nameAsRegex4.yaml}[yaml-TCB]{\texttt{nameAsRegex4.yaml}}{lst:nameAsRegex4} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/nameAsRegex3.yaml}[yaml-TCB]{\texttt{nameAsRegex3.yaml}}{lst:nameAsRegex3} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/nameAsRegex4.yaml}[yaml-TCB]{\texttt{nameAsRegex4.yaml}}{lst:nameAsRegex4} \end{cmhtcbraster} With reference to \cref{lst:nameAsRegex4}: \begin{itemize} - \item the \texttt{name} field as specified here means \emph{any word followed by the word - inline}; - \item we have used \texttt{nameAsRegex} to identify this field, but you can use any description - you like; - \item the \texttt{lookForThis} field is optional, and can take the values 0 (off) or 1 (on); by - default, it is assumed to be 1 (on). + \item the \texttt{name} field as specified here means \emph{any word followed by the + word inline}; + \item we have used \texttt{nameAsRegex} to identify this field, but you can use any + description you like; + \item the \texttt{lookForThis} field is optional, and can take the values 0 (off) or 1 + (on); by default, it is assumed to be 1 (on). \end{itemize} \end{example} \yamltitle{noIndentBlock}*{fields} - If you have a block of code that you don't want \texttt{latexindent.pl} to touch (even if - \index{verbatim!noIndentBlock} it is \emph{not} a verbatim-like environment) then you can - wrap it in an environment from \texttt{noIndentBlock}; you can use any name you like for - this, provided you populate it as demonstrate in \cref{lst:noIndentBlock}. + If you have a block of code that you don't want \texttt{latexindent.pl} to touch (even + if \index{verbatim!noIndentBlock} it is \emph{not} a verbatim-like environment) then you + can wrap it in an environment from \texttt{noIndentBlock}; you can use any name you like + for this, provided you populate it as demonstrate in \cref{lst:noIndentBlock}. \cmhlistingsfromfile[style=noIndentBlock]{../defaultSettings.yaml}[width=.4\linewidth,before=\centering,yaml-TCB]{\texttt{noIndentBlock}}{lst:noIndentBlock} @@ -2180,9 +2219,9 @@ copy myfile.bak4 to myfile.bak3 raster left skip=-3.5cm, raster right skip=-2cm, raster column skip=.03\linewidth] - \cmhlistingsfromfile{demonstrations/noindent1.yaml}[yaml-TCB]{\texttt{noindent1.yaml}}{lst:noindent1} - \cmhlistingsfromfile{demonstrations/noindent2.yaml}[yaml-TCB]{\texttt{noindent2.yaml}}{lst:noindent2} - \cmhlistingsfromfile{demonstrations/noindent3.yaml}[yaml-TCB]{\texttt{noindent3.yaml}}{lst:noindent3} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/noindent1.yaml}[yaml-TCB]{\texttt{noindent1.yaml}}{lst:noindent1} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/noindent2.yaml}[yaml-TCB]{\texttt{noindent2.yaml}}{lst:noindent2} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/noindent3.yaml}[yaml-TCB]{\texttt{noindent3.yaml}}{lst:noindent3} \end{cmhtcbraster} Upon running the commands @@ -2201,11 +2240,11 @@ latexindent.pl -l noindent2.yaml noindent1 The \texttt{begin}, \texttt{body} and \texttt{end} fields for \texttt{noIndentBlock} are all \emph{regular expressions}. If the \texttt{body} field is not specified, then it takes a default value of \lstinline!.*?! which is written explicitly in - \cref{lst:noindent1}. In this context, we interpret \lstinline!.*?! in words as \emph{the - fewest number of characters (possibly none) until the `end' field is reached}. + \cref{lst:noindent1}. In this context, we interpret \lstinline!.*?! in words as + \emph{the fewest number of characters (possibly none) until the `end' field is reached}. - The \texttt{lookForThis} field is optional, and can take the values 0 (off) or 1 (on); by - default, it is assumed to be 1 (on). + The \texttt{lookForThis} field is optional, and can take the values 0 (off) or 1 (on); + by default, it is assumed to be 1 (on). \begin{example} Using \cref{lst:noindent3} demonstrates setting \texttt{lookForThis} to 0 (off); running @@ -2234,40 +2273,40 @@ latexindent.pl -l noindent3.yaml noindent1 \begin{widepage} \begin{cmhtcbraster}[raster column skip=.1\linewidth] - \cmhlistingsfromfile{demonstrations/nameAsRegex5.yaml}[yaml-TCB]{\texttt{nameAsRegex5.yaml}}{lst:nameAsRegex5} - \cmhlistingsfromfile{demonstrations/nameAsRegex6.yaml}[yaml-TCB]{\texttt{nameAsRegex6.yaml}}{lst:nameAsRegex6} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/nameAsRegex5.yaml}[yaml-TCB]{\texttt{nameAsRegex5.yaml}}{lst:nameAsRegex5} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/nameAsRegex6.yaml}[yaml-TCB]{\texttt{nameAsRegex6.yaml}}{lst:nameAsRegex6} \end{cmhtcbraster} \end{widepage} With reference to \cref{lst:nameAsRegex6}: \begin{itemize} - \item the \texttt{name} field as specified here means \emph{any word followed by the word - noindent, optionally followed by *}; - \item we have used \texttt{nameAsRegex} to identify this field, but you can use any description - you like; - \item the \texttt{lookForThis} field is optional, and can take the values 0 (off) or 1 (on); by - default, it is assumed to be 1 (on). + \item the \texttt{name} field as specified here means \emph{any word followed by the + word noindent, optionally followed by *}; + \item we have used \texttt{nameAsRegex} to identify this field, but you can use any + description you like; + \item the \texttt{lookForThis} field is optional, and can take the values 0 (off) or 1 + (on); by default, it is assumed to be 1 (on). \end{itemize} \end{example} -\subsection{filecontents and preamble} +\subsection{filecontents and preamble}\label{subsec:filecontents:preamble} \yamltitle{fileContentsEnvironments}*{field} 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. + \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. \cmhlistingsfromfile[style=fileContentsEnvironments]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{fileContentsEnvironments}}{lst:fileContentsEnvironments} \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}. + \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} @@ -2282,8 +2321,8 @@ latexindent.pl -l noindent3.yaml noindent1 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}. + 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} ... @@ -2294,11 +2333,12 @@ postfoothook=\end{mdframed}, \index{indentation!defaultIndent description} -\subsection{Indentation and horizontal space} +\subsection{Indentation and horizontal space}\label{subsec:indentation:and:horizontal:space} \yamltitle{defaultIndent}*{horizontal space} This is the default indentation used in the absence of other details for the code block - with which we are working. The default value is \lstinline!\t! which means a tab; we will - explore customisation beyond \texttt{defaultIndent} in \vref{sec:noadd-indent-rules}. + with which we are working. The default value is \lstinline!\t! which means a tab; we + will explore customisation beyond \texttt{defaultIndent} in + \vref{sec:noadd-indent-rules}. If you're interested in experimenting with \texttt{latexindent.pl} then you can \emph{remove} all indentation by setting \texttt{defaultIndent: ""}. @@ -2306,8 +2346,8 @@ postfoothook=\end{mdframed}, \yamltitle{removeTrailingWhitespace}*{fields}\label{yaml:removeTrailingWhitespace} Trailing white space can be removed both \emph{before} and \emph{after} processing the - document, as detailed in \cref{lst:removeTrailingWhitespace}; each of the fields can take - the values \texttt{0} or \texttt{1}. See + 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. @@ -2328,8 +2368,8 @@ postfoothook=\end{mdframed}, \texttt{latexindent.pl} (see \cref{lst:aligndelims:basic}). In fact, the fields in \texttt{lookForAlignDelims} can actually take two different forms: the \emph{basic} version is shown in \cref{lst:aligndelims:basic} and the \emph{advanced} version in - \cref{lst:aligndelims:advanced}; we will discuss each in turn. \index{delimiters!advanced - settings of lookForAlignDelims} + \cref{lst:aligndelims:advanced}; we will discuss each in turn. + \index{delimiters!advanced settings of lookForAlignDelims} \begin{yaml}[numbers=none]{\texttt{lookForAlignDelims} (basic)}[width=.8\linewidth,before=\centering]{lst:aligndelims:basic} lookForAlignDelims: @@ -2342,9 +2382,15 @@ lookForAlignDelims: \end{yaml} Specifying code blocks in this field instructs \texttt{latexindent.pl} to try and align - each column by its alignment delimiters. It does have some limitations (discussed further - in \cref{sec:knownlimitations}), but in many cases it will produce results such as those - in \cref{lst:tabularbefore:basic,lst:tabularafter:basic}. + each column by its alignment delimiters. It does have some limitations (discussed + further in \cref{sec:knownlimitations}), but in many cases it will produce results such + as those in \cref{lst:tabularbefore:basic,lst:tabularafter:basic}; running the command + + \begin{commandshell} +latexindent.pl tabular1.tex + \end{commandshell} + + gives the output given in \cref{lst:tabularafter:basic}. \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/tabular1.tex}{\texttt{tabular1.tex}}{lst:tabularbefore:basic} @@ -2383,37 +2429,38 @@ lookForAlignDelims: \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{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 spaces to be placed \emph{before} ampersands (default: 1); + 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 spaces to be placed \emph{After} ampersands (default: 1); + 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{2020-03-21}{align final double back slash}{alignFinalDoubleBackSlash} - optionally specifies if the \emph{final} double back slash should be used for alignment - (default: 0); + alignment}\texttt{justification}: optionally specifies the justification of each + cell as either \emph{left} or \emph{right} (default: left); + \item \announce{2020-03-21}{align final double backslash}{alignFinalDoubleBackSlash} + optionally specifies if the \emph{final} double backslash should be used for + alignment (default: 0); \item \announce{2020-03-21}{don't measure feature}{dontMeasure} optionally specifies if - user-specified cells, rows or the largest entries should \emph{not} be measured (default: - 0); - \item \announce{2020-03-21}{delimiter RegEx feature}{delimiterRegEx} optionally specifies the - pattern matching to be used for the alignment delimeter (default: + user-specified cells, rows or the largest entries should \emph{not} be measured + (default: 0); + \item \announce{2020-03-21}{delimiter RegEx feature}{delimiterRegEx} optionally + specifies the pattern matching to be used for the alignment delimeter (default: \lstinline* '(?<!\\)(&)'*); \item \announce{2020-03-21}{delimiter justification}{delimiterJustification} optionally - specifies the justification for the alignment delimeters (default: left); note that this - feature is only useful if you have delimiters of different lengths in the same column, - discussed in \cref{sec:delimiter-reg-ex}; - \item \announce{2021-12-13}{lookForChildCodeBlocks feature}{lookForChildCodeBlocks} optionally - instructs \texttt{latexindent.pl} to search for child code blocks or not (default: 1), - discussed in \cref{sec:lookForChildCodeBlocks}. + specifies the justification for the alignment delimeters (default: left); note + that this feature is only useful if you have delimiters of different lengths in + the same column, discussed in \cref{sec:delimiter-reg-ex}; + \item \announce{2021-12-13}{lookForChildCodeBlocks feature}{lookForChildCodeBlocks} + optionally instructs \texttt{latexindent.pl} to search for child code blocks or + not (default: 1), discussed in \cref{sec:lookForChildCodeBlocks}. \end{itemize} \begin{example} @@ -2483,33 +2530,37 @@ 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 + \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-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-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} \end{example} @@ -2540,10 +2591,10 @@ latexindent.pl aligned1.tex -o=+-default not-yet discussed \texttt{noAdditionalIndent} field (see \vref{sec:noadd-indent-rules}) which will assist in the demonstration in what follows. \begin{cmhtcbraster}[raster columns=2, ] - \cmhlistingsfromfile{demonstrations/sba1.yaml}[yaml-TCB]{\texttt{sba1.yaml}}{lst:sba1} - \cmhlistingsfromfile{demonstrations/sba2.yaml}[yaml-TCB]{\texttt{sba2.yaml}}{lst:sba2} - \cmhlistingsfromfile{demonstrations/sba3.yaml}[yaml-TCB]{\texttt{sba3.yaml}}{lst:sba3} - \cmhlistingsfromfile{demonstrations/sba4.yaml}[yaml-TCB]{\texttt{sba4.yaml}}{lst:sba4} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/sba1.yaml}[yaml-TCB]{\texttt{sba1.yaml}}{lst:sba1} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/sba2.yaml}[yaml-TCB]{\texttt{sba2.yaml}}{lst:sba2} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/sba3.yaml}[yaml-TCB]{\texttt{sba3.yaml}}{lst:sba3} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/sba4.yaml}[yaml-TCB]{\texttt{sba4.yaml}}{lst:sba4} \end{cmhtcbraster} Upon running the following commands @@ -2574,8 +2625,8 @@ latexindent.pl aligned1.tex -l sba4.yaml for us to set the \texttt{default} value that sets the number of spaces before ampersands which are \emph{not} in leading blank columns. The default value is \texttt{1}. - We note that \texttt{leadingBlankColumn} has not been specified in \cref{lst:sba3}, and - it will inherit the value from \texttt{default}; + We note that \texttt{leadingBlankColumn} has not been specified in + \cref{lst:sba3}, and it will inherit the value from \texttt{default}; \item \cref{lst:sba4} demonstrates spaces to be used before amperands for \emph{leading blank columns}. We note that \emph{default} has not been specified, and it will be set to \texttt{1} by @@ -2589,8 +2640,8 @@ latexindent.pl aligned1.tex -l sba4.yaml equivalent. \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/sba5.yaml}[yaml-TCB]{\texttt{sba5.yaml}}{lst:sba5} - \cmhlistingsfromfile{demonstrations/sba6.yaml}[yaml-TCB]{\texttt{sba6.yaml}}{lst:sba6} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/sba5.yaml}[yaml-TCB]{\texttt{sba5.yaml}}{lst:sba5} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/sba6.yaml}[yaml-TCB]{\texttt{sba6.yaml}}{lst:sba6} \end{cmhtcbraster} Upon running @@ -2604,15 +2655,15 @@ latexindent.pl aligned1.tex -l sba6.yaml space before the ampersand in the \emph{leading blank column} has been set to \texttt{0} by \cref{lst:sba6}. - We can demonstrated this feature further using the settings in \cref{lst:sba7} which give - the output in \cref{lst:aligned1-mod7}. + We can demonstrated this feature further using the settings in \cref{lst:sba7} which + give the output in \cref{lst:aligned1-mod7}. \begin{cmhtcbraster}[raster columns=3, raster left skip=-3.75cm, raster right skip=-2cm,] \cmhlistingsfromfile{demonstrations/aligned1-mod5.tex}{\texttt{aligned1-mod5.tex}}{lst:aligned1-mod5} \cmhlistingsfromfile{demonstrations/aligned1-mod7.tex}{\texttt{aligned1.tex} using \cref{lst:sba7}}{lst:aligned1-mod7} - \cmhlistingsfromfile{demonstrations/sba7.yaml}[yaml-TCB]{\texttt{sba7.yaml}}{lst:sba7} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/sba7.yaml}[yaml-TCB]{\texttt{sba7.yaml}}{lst:sba7} \end{cmhtcbraster} \end{example} @@ -2647,13 +2698,13 @@ latexindent.pl tabular4.tex -o=+-FDBS -y="lookForAlignDelims:tabular:alignFinalD \item \cref{lst:tabular4-default}, by default, the \emph{first} set of double back slashes in the first row of the \texttt{tabular} environment have been used for alignment; - \item \cref{lst:tabular4-FDBS}, the \emph{final} set of double back slashes in the + \item \cref{lst:tabular4-FDBS}, the \emph{final} set of double backslashes in the first row have been used, because we specified \texttt{alignFinalDoubleBackSlash} as 1. \end{itemize} \end{example} - 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 + 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}). \begin{example} @@ -2674,12 +2725,13 @@ latexindent.pl matrix1.tex \end{cmhtcbraster} \end{example} - 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 + 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}. \begin{cmhtcbraster}[raster left skip=-1.5cm,] @@ -2688,8 +2740,9 @@ latexindent.pl matrix1.tex \end{cmhtcbraster} 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}. + \texttt{noAdditionalIndent} and \texttt{indentRules} (see + \vref{sec:noadd-indent-rules}), these comment-marked blocks are considered + \texttt{environments}. \subsubsection{lookForAlignDelims: the dontMeasure feature}\label{sec:dontMeasure} The \announce{2020-03-21}{don't measure feature} \texttt{lookForAlignDelims} field can, @@ -2718,7 +2771,7 @@ latexindent.pl tabular-DM.tex -l=dontMeasure1.yaml \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/tabular-DM-mod1.tex}{\texttt{tabular-DM.tex} using \cref{lst:dontMeasure1}}{lst:tabular-DM-mod1} - \cmhlistingsfromfile{demonstrations/dontMeasure1.yaml}[yaml-TCB]{\texttt{dontMeasure1.yaml}}{lst:dontMeasure1} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/dontMeasure1.yaml}[yaml-TCB]{\texttt{dontMeasure1.yaml}}{lst:dontMeasure1} \end{cmhtcbraster} We note that the \emph{largest} column entries have not contributed to the measuring @@ -2739,11 +2792,11 @@ latexindent.pl tabular-DM.tex -l=dontMeasure2.yaml \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/tabular-DM-mod2.tex}{\texttt{tabular-DM.tex} using \cref{lst:dontMeasure2} or \cref{lst:dontMeasure3}}{lst:tabular-DM-mod2} - \cmhlistingsfromfile{demonstrations/dontMeasure2.yaml}[yaml-TCB]{\texttt{dontMeasure2.yaml}}{lst:dontMeasure2} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/dontMeasure2.yaml}[yaml-TCB]{\texttt{dontMeasure2.yaml}}{lst:dontMeasure2} \end{cmhtcbraster} - We note that in \cref{lst:dontMeasure2} we have specified entries not to be measured, one - entry per line. + We note that in \cref{lst:dontMeasure2} we have specified entries not to be measured, + one entry per line. \end{example} \begin{example} @@ -2763,8 +2816,8 @@ latexindent.pl tabular-DM.tex -l=dontMeasure4.yaml raster right skip=-2cm, raster column skip=.03\linewidth] \cmhlistingsfromfile{demonstrations/tabular-DM-mod3.tex}{\texttt{tabular-DM.tex} using \cref{lst:dontMeasure3} or \cref{lst:dontMeasure3}}{lst:tabular-DM-mod3} - \cmhlistingsfromfile{demonstrations/dontMeasure3.yaml}[yaml-TCB]{\texttt{dontMeasure3.yaml}}{lst:dontMeasure3} - \cmhlistingsfromfile{demonstrations/dontMeasure4.yaml}[yaml-TCB]{\texttt{dontMeasure4.yaml}}{lst:dontMeasure4} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/dontMeasure3.yaml}[yaml-TCB]{\texttt{dontMeasure3.yaml}}{lst:dontMeasure3} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/dontMeasure4.yaml}[yaml-TCB]{\texttt{dontMeasure4.yaml}}{lst:dontMeasure4} \end{cmhtcbraster} We note that in: \begin{itemize} @@ -2792,7 +2845,7 @@ latexindent.pl tabular-DM.tex -l=dontMeasure5.yaml we receive the output in \cref{lst:tabular-DM-mod5}. \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/tabular-DM-mod5.tex}{\texttt{tabular-DM.tex} using \cref{lst:dontMeasure5}}{lst:tabular-DM-mod5} - \cmhlistingsfromfile{demonstrations/dontMeasure5.yaml}[yaml-TCB]{\texttt{dontMeasure5.yaml}}{lst:dontMeasure5} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/dontMeasure5.yaml}[yaml-TCB]{\texttt{dontMeasure5.yaml}}{lst:dontMeasure5} \end{cmhtcbraster} \end{example} @@ -2810,7 +2863,7 @@ latexindent.pl tabular-DM.tex -l=dontMeasure6.yaml \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/tabular-DM-mod6.tex}{\texttt{tabular-DM.tex} using \cref{lst:dontMeasure6}}{lst:tabular-DM-mod6} - \cmhlistingsfromfile{demonstrations/dontMeasure6.yaml}[yaml-TCB]{\texttt{dontMeasure6.yaml}}{lst:dontMeasure6} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/dontMeasure6.yaml}[yaml-TCB]{\texttt{dontMeasure6.yaml}}{lst:dontMeasure6} \end{cmhtcbraster} \end{example} @@ -2853,15 +2906,15 @@ latexindent.pl tabbing.tex -l=delimiterRegEx1.yaml \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/tabbing-mod1.tex}{\texttt{tabbing.tex} using \cref{lst:delimiterRegEx1}}{lst:tabbing-mod1} - \cmhlistingsfromfile{demonstrations/delimiterRegEx1.yaml}[yaml-TCB]{\texttt{delimiterRegEx1.yaml}}{lst:delimiterRegEx1} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/delimiterRegEx1.yaml}[yaml-TCB]{\texttt{delimiterRegEx1.yaml}}{lst:delimiterRegEx1} \end{cmhtcbraster} We note that: \begin{itemize} \item in \cref{lst:tabbing-mod1} the code has been aligned, as intended, at both the \lstinline!\=! and \lstinline!\>!; - \item in \cref{lst:delimiterRegEx1} we have heeded the warning and captured the expression - using grouping parenthesis, specified a backslash using \lstinline!\\! and said that it - must be followed by either \lstinline!=! or \lstinline!>!. + \item in \cref{lst:delimiterRegEx1} we have heeded the warning and captured the + expression using grouping parenthesis, specified a backslash using \lstinline!\\! + and said that it must be followed by either \lstinline!=! or \lstinline!>!. \end{itemize} \end{example} @@ -2878,7 +2931,7 @@ latexindent.pl tabbing.tex -l=delimiterRegEx2.yaml \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/tabbing-mod2.tex}{\texttt{tabbing.tex} using \cref{lst:delimiterRegEx2}}{lst:tabbing-mod2} - \cmhlistingsfromfile{demonstrations/delimiterRegEx2.yaml}[yaml-TCB]{\texttt{delimiterRegEx2.yaml}}{lst:delimiterRegEx2} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/delimiterRegEx2.yaml}[yaml-TCB]{\texttt{delimiterRegEx2.yaml}}{lst:delimiterRegEx2} \end{cmhtcbraster} We note that only the \lstinline!\>! have been aligned. \end{example} @@ -2887,8 +2940,8 @@ latexindent.pl tabbing.tex -l=delimiterRegEx2.yaml Of course, the other lookForAlignDelims options can be used alongside the \texttt{delimiterRegEx}; regardless of the type of delimiter being used (ampersand or anything else), the fields from \vref{lst:aligndelims:advanced} remain the same; for - example, using the settings in \cref{lst:delimiterRegEx3}, and running \index{switches!-l - demonstration} + example, using the settings in \cref{lst:delimiterRegEx3}, and running + \index{switches!-l demonstration} \begin{commandshell} latexindent.pl tabbing.tex -l=delimiterRegEx3.yaml @@ -2898,17 +2951,17 @@ latexindent.pl tabbing.tex -l=delimiterRegEx3.yaml \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/tabbing-mod3.tex}{\texttt{tabbing.tex} using \cref{lst:delimiterRegEx3}}{lst:tabbing-mod3} - \cmhlistingsfromfile{demonstrations/delimiterRegEx3.yaml}[yaml-TCB]{\texttt{delimiterRegEx3.yaml}}{lst:delimiterRegEx3} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/delimiterRegEx3.yaml}[yaml-TCB]{\texttt{delimiterRegEx3.yaml}}{lst:delimiterRegEx3} \end{cmhtcbraster} \end{example} \begin{example} It is possible that delimiters specified within \texttt{delimiterRegEx} can be of different lengths. Consider the file in \cref{lst:tabbing1}, and associated YAML in - \cref{lst:delimiterRegEx4}. Note that the \cref{lst:delimiterRegEx4} specifies the option - for the delimiter to be either \lstinline!#! or \lstinline!\>!, \emph{which are different - lengths}. Upon running the command \index{switches!-l demonstration} \index{switches!-o - demonstration} + \cref{lst:delimiterRegEx4}. Note that the \cref{lst:delimiterRegEx4} specifies the + option for the delimiter to be either \lstinline!#! or \lstinline!\>!, \emph{which are + different lengths}. Upon running the command \index{switches!-l demonstration} + \index{switches!-o demonstration} \begin{commandshell} latexindent.pl tabbing1.tex -l=delimiterRegEx4.yaml -o=+-mod4 @@ -2923,7 +2976,7 @@ latexindent.pl tabbing1.tex -l=delimiterRegEx4.yaml -o=+-mod4 raster column skip=.03\linewidth] \cmhlistingsfromfile{demonstrations/tabbing1.tex}{\texttt{tabbing1.tex}}{lst:tabbing1} \cmhlistingsfromfile{demonstrations/tabbing1-mod4.tex}{\texttt{tabbing1-mod4.tex}}{lst:tabbing1-mod4} - \cmhlistingsfromfile{demonstrations/delimiterRegEx4.yaml}[yaml-TCB]{\texttt{delimiterRegEx4.yaml}}{lst:delimiterRegEx4} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/delimiterRegEx4.yaml}[yaml-TCB]{\texttt{delimiterRegEx4.yaml}}{lst:delimiterRegEx4} \end{cmhtcbraster} \end{example} @@ -2942,7 +2995,7 @@ latexindent.pl tabbing1.tex -l=delimiterRegEx5.yaml -o=+-mod5 \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/tabbing1-mod5.tex}{\texttt{tabbing1-mod5.tex}}{lst:tabbing1-mod5} - \cmhlistingsfromfile{demonstrations/delimiterRegEx5.yaml}[yaml-TCB]{\texttt{delimiterRegEx5.yaml}}{lst:delimiterRegEx5} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/delimiterRegEx5.yaml}[yaml-TCB]{\texttt{delimiterRegEx5.yaml}}{lst:delimiterRegEx5} \end{cmhtcbraster} Note that in \cref{lst:tabbing1-mod5} the second set of delimiters have been \emph{right @@ -2951,9 +3004,9 @@ latexindent.pl tabbing1.tex -l=delimiterRegEx5.yaml -o=+-mod5 \subsubsection{lookForAlignDelims: lookForChildCodeBlocks}\label{sec:lookForChildCodeBlocks} There \announce{2021-12-13}{lookForChildCodeBlocks demonstration} may be scenarios in - which you would prefer to instruct \texttt{latexindent.pl} \emph{not} to search for child - blocks; in which case setting \texttt{lookForChildCodeBlocks} to 0 may be a good way to - proceed. + which you would prefer to instruct \texttt{latexindent.pl} \emph{not} to search for + child blocks; in which case setting \texttt{lookForChildCodeBlocks} to 0 may be a good + way to proceed. \begin{example} Using the settings from \vref{lst:dontMeasure1} on the file in \cref{lst:tabular-DM-1} @@ -2980,16 +3033,16 @@ latexindent.pl tabular-DM-1.tex -l=dontMeasure1a.yaml -o=+-mod1a \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/tabular-DM-1-mod1a.tex}{\texttt{tabular-DM-1-mod1a.tex}}{lst:tabular-DM-1-mod1a} - \cmhlistingsfromfile{demonstrations/dontMeasure1a.yaml}[yaml-TCB]{\texttt{dontMeasure1a.yaml}}{lst:dontMeasure1a} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/dontMeasure1a.yaml}[yaml-TCB]{\texttt{dontMeasure1a.yaml}}{lst:dontMeasure1a} \end{cmhtcbraster} \end{example} \subsection{Indent after items, specials and headings} \yamltitle{indentAfterItems}*{fields} - The environment names specified in \texttt{indentAfterItems} tell \texttt{latexindent.pl} - to look for \lstinline!\item! commands; if these switches are set to \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{cmhtcbraster}[raster columns=3, raster left skip=-3.5cm, @@ -3012,10 +3065,10 @@ latexindent.pl tabular-DM-1.tex -l=dontMeasure1a.yaml -o=+-mod1a \yamltitle{specialBeginEnd}*{fields}\label{yaml:specialBeginEnd} The fields specified \index{specialBeginEnd!introduction} - \announce{2017-08-21}*{specialBeginEnd} in \texttt{specialBeginEnd} are, in their default - state, focused on math mode begin and end statements, but there is no requirement for - this to be the case; \cref{lst:specialBeginEnd} shows the default settings of - \texttt{specialBeginEnd}. \index{specialBeginEnd!default settings}% + \announce{2017-08-21}*{specialBeginEnd} in \texttt{specialBeginEnd} are, in their + default state, focused on math mode begin and end statements, but there is no + requirement for this to be the case; \cref{lst:specialBeginEnd} shows the default + settings of \texttt{specialBeginEnd}. \index{specialBeginEnd!default settings}% \cmhlistingsfromfile[style=specialBeginEnd]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{specialBeginEnd}}{lst:specialBeginEnd} @@ -3026,7 +3079,13 @@ latexindent.pl tabular-DM-1.tex -l=dontMeasure1a.yaml -o=+-mod1a \begin{example} A demonstration of the before-and-after results are shown in - \cref{lst:specialbefore,lst:specialafter}. + \cref{lst:specialbefore,lst:specialafter}; explicitly, running the command + + \begin{commandshell} +latexindent.pl special1.tex -o=+-default + \end{commandshell} + + gives the output given in \cref{lst:specialafter}. \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/special1.tex}{\texttt{special1.tex} before}{lst:specialbefore} @@ -3107,24 +3166,25 @@ latexindent.pl special2.tex -l=middle1 then we obtain the output given in \cref{lst:special2-mod1,lst:special2-mod2}. \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/middle.yaml}[yaml-TCB]{\texttt{middle.yaml}}{lst:middle-yaml} \cmhlistingsfromfile{demonstrations/special2-mod1.tex}{\texttt{special2.tex} using \cref{lst:middle-yaml}}{lst:special2-mod1} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/middle.yaml}[yaml-TCB]{\texttt{middle.yaml}}{lst:middle-yaml} \end{cmhtcbraster} \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/middle1.yaml}[yaml-TCB]{\texttt{middle1.yaml}}{lst:middle1-yaml} \cmhlistingsfromfile{demonstrations/special2-mod2.tex}{\texttt{special2.tex} using \cref{lst:middle1-yaml}}{lst:special2-mod2} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/middle1.yaml}[yaml-TCB]{\texttt{middle1.yaml}}{lst:middle1-yaml} \end{cmhtcbraster} 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 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 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} \end{example} @@ -3144,12 +3204,13 @@ latexindent.pl special3.tex -l=special-verb1 \index{specialBeginEnd!specifying as verbatim} \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/special-verb1.yaml}[yaml-TCB]{\texttt{special-verb1.yaml}}{lst:special-verb1-yaml} \cmhlistingsfromfile{demonstrations/special3-mod1.tex}{\texttt{special3.tex} and output using \cref{lst:special-verb1-yaml}}{lst:special3-mod1} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/special-verb1.yaml}[yaml-TCB]{\texttt{special-verb1.yaml}}{lst:special-verb1-yaml} \end{cmhtcbraster} \end{example} - We can combine the \texttt{specialBeginEnd} with the \texttt{lookForAlignDelims} feature. + We can combine the \texttt{specialBeginEnd} with the \texttt{lookForAlignDelims} + feature. \begin{example} We begin with the code in \cref{lst:special-align}. @@ -3167,30 +3228,31 @@ latexindent.pl special-align.tex -l edge-node1.yaml -o=+-mod1 to receive the output in \cref{lst:special-align-mod1}. \index{specialBeginEnd!combined with lookForAlignDelims} \index{specialBeginEnd!delimiterRegEx} \index{specialBeginEnd!alignment at delimiter} \index{specialBeginEnd!tikz example} - \index{regular expressions!delimiter alignment for edge or node} \index{delimiters!within - specialBeginEnd blocks} \index{regular expressions!numeric 0-9} + \index{regular expressions!delimiter alignment for edge or node} + \index{delimiters!within specialBeginEnd blocks} \index{regular expressions!numeric 0-9} \begin{cmhtcbraster}[ raster left skip=-3.5cm,] - \cmhlistingsfromfile{demonstrations/edge-node1.yaml}[yaml-TCB]{\texttt{edge-node1.yaml}}{lst:edge-node1} \cmhlistingsfromfile{demonstrations/special-align-mod1.tex}{\texttt{special-align.tex} using \cref{lst:edge-node1}}{lst:special-align-mod1} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/edge-node1.yaml}[yaml-TCB]{\texttt{edge-node1.yaml}}{lst:edge-node1} \end{cmhtcbraster} - The output in \cref{lst:special-align-mod1} is not quite ideal. We can tweak the settings - within \cref{lst:edge-node1} in order to improve the output; in particular, we employ the - code in \cref{lst:edge-node2} and run the command \index{switches!-l demonstration} - \index{switches!-o demonstration} \index{regular expressions!uppercase alph A-Z} + The output in \cref{lst:special-align-mod1} is not quite ideal. We can tweak the + settings within \cref{lst:edge-node1} in order to improve the output; in particular, we + employ the code in \cref{lst:edge-node2} and run the command \index{switches!-l + demonstration} \index{switches!-o demonstration} \index{regular expressions!uppercase + alph A-Z} \begin{commandshell} latexindent.pl special-align.tex -l edge-node2.yaml -o=+-mod2 \end{commandshell} to receive the output in \cref{lst:special-align-mod2}. - \index{specialBeginEnd!delimiterRegEx tweaked} \index{regular expressions!at least one +} - \index{regular expressions!horizontal space \textbackslash{h}} + \index{specialBeginEnd!delimiterRegEx tweaked} \index{regular expressions!at least one + +} \index{regular expressions!horizontal space \textbackslash{h}} \begin{cmhtcbraster}[ raster left skip=-3.5cm,] - \cmhlistingsfromfile{demonstrations/edge-node2.yaml}[yaml-TCB]{\texttt{edge-node2.yaml}}{lst:edge-node2} \cmhlistingsfromfile{demonstrations/special-align-mod2.tex}{\texttt{special-align.tex} using \cref{lst:edge-node2}}{lst:special-align-mod2} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/edge-node2.yaml}[yaml-TCB]{\texttt{edge-node2.yaml}}{lst:edge-node2} \end{cmhtcbraster} \end{example} @@ -3209,10 +3271,10 @@ latexindent.pl special-align.tex -l edge-node2.yaml -o=+-mod2 The default settings do \emph{not} place indentation after a heading, but you can easily switch them on by changing \texttt{indentAfterThisHeading} from 0 to 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. + \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 @@ -3227,8 +3289,8 @@ latexindent.pl special-align.tex -l edge-node2.yaml -o=+-mod2 \texttt{headings1.tex}. \begin{cmhtcbraster} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/headings1.yaml}[yaml-TCB]{\texttt{headings1.yaml}}{lst:headings1yaml} \cmhlistingsfromfile{demonstrations/headings1.tex}{\texttt{headings1.tex}}{lst:headings1} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/headings1.yaml}[yaml-TCB]{\texttt{headings1.yaml}}{lst:headings1yaml} \end{cmhtcbraster} If you run the command \index{switches!-l demonstration} @@ -3289,13 +3351,13 @@ latexindent.pl mult-nested.tex -l=max-indentation1 You should receive the output shown in \cref{lst:mult-nested-max-ind1}. \begin{cmhtcbraster} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/max-indentation1.yaml}[yaml-TCB]{\texttt{max-indentation1.yaml}}{lst:max-indentation1yaml} \cmhlistingsfromfile[showspaces=true]{demonstrations/mult-nested-max-ind1.tex}{\texttt{mult-nested.tex} using \cref{lst:max-indentation1yaml}}{lst:mult-nested-max-ind1} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/max-indentation1.yaml}[yaml-TCB]{\texttt{max-indentation1.yaml}}{lst:max-indentation1yaml} \end{cmhtcbraster} \end{example} - 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 @@ -3304,10 +3366,10 @@ latexindent.pl mult-nested.tex -l=max-indentation1 \subsection{The code blocks known latexindent.pl}\label{subsubsec:code-blocks} - As of Version 3.0, \texttt{latexindent.pl} processes documents using code blocks; each of - these are shown in \cref{tab:code-blocks}. \index{regular expressions!uppercase alph A-Z} - \index{regular expressions!lowercase alph a-z} \index{regular expressions!numeric 0-9} - \index{regular expressions!horizontal space \textbackslash{h}} + As of Version 3.0, \texttt{latexindent.pl} processes documents using code blocks; each + of these are shown in \cref{tab:code-blocks}. \index{regular expressions!uppercase alph + A-Z} \index{regular expressions!lowercase alph a-z} \index{regular expressions!numeric + 0-9} \index{regular expressions!horizontal space \textbackslash{h}} \begin{table}[!htp] \begin{widepage} @@ -3485,8 +3547,8 @@ 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 + 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} @@ -3512,9 +3574,9 @@ latexindent.pl myenv.tex -l myenv-noAdd6.yaml 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. + 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{cmhtcbraster} \cmhlistingsfromfile{demonstrations/myenvironment-args-noAdd5.tex}{\texttt{myenv-args.tex} using \cref{lst:myenv-noAdd5}}{lst:myenv-args-noAdd5} @@ -3607,10 +3669,11 @@ latexindent.pl myenv-args.tex -l myenv-rules4.yaml \yamltitle{noAdditionalIndentGlobal}*{fields} 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}). + \texttt{latexindent.pl} will look is \texttt{noAdditionalIndentGlobal}, and in + particular \emph{for the environments} key (see + \cref{lst:noAdditionalIndentGlobal:environments}). - \cmhlistingsfromfile[style=noAdditionalIndentGlobalEnv]{../defaultSettings.yaml}[width=.5\linewidth,before=\centering,yaml-TCB]{\texttt{noAdditionalIndentGlobal}}{lst:noAdditionalIndentGlobal:environments} + \cmhlistingsfromfile[style=noAdditionalIndentGlobalEnv]{../defaultSettings.yaml}[width=.7\linewidth,before=\centering,yaml-TCB]{\texttt{noAdditionalIndentGlobal}}{lst:noAdditionalIndentGlobal:environments} \begin{example} Let's say that you change the value of \texttt{environments} to \texttt{1} in @@ -3674,11 +3737,12 @@ latexindent.pl myenv-args.tex -local mand-args-no-add-glob.yaml The final check that \texttt{latexindent.pl} will make is to look for \texttt{indentRulesGlobal} as detailed in \cref{lst:indentRulesGlobal:environments}. - \cmhlistingsfromfile[style=indentRulesGlobalEnv]{../defaultSettings.yaml}[width=.5\linewidth,before=\centering,yaml-TCB]{\texttt{indentRulesGlobal}}{lst:indentRulesGlobal:environments} + \cmhlistingsfromfile[style=indentRulesGlobalEnv]{../defaultSettings.yaml}[width=.7\linewidth,before=\centering,yaml-TCB]{\texttt{indentRulesGlobal}}{lst:indentRulesGlobal:environments} \begin{example} - If you change the \texttt{environments} field to anything involving horizontal space, say - \lstinline!" "!, and then run the following commands \index{switches!-l demonstration} + If you change the \texttt{environments} field to anything involving horizontal space, + say \lstinline!" "!, and then run the following commands \index{switches!-l + demonstration} \begin{commandshell} latexindent.pl myenv-args.tex -l env-indentRules.yaml @@ -3686,13 +3750,13 @@ 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}. + \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{cmhtcbraster} \cmhlistingsfromfile[showspaces=true]{demonstrations/myenvironment-args-global-rules1.tex}{\texttt{myenv-args.tex} using \cref{lst:indentRulesGlobal:environments}}{lst:myenv-args-indent-rules-global1} @@ -3717,10 +3781,10 @@ 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}. + \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} @@ -3759,9 +3823,9 @@ 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 + 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}. @@ -3799,10 +3863,10 @@ latexindent.pl items1.tex -local items-indentRulesGlobal.yaml % arara: pdflatex: { files: [latexindent]} \subsubsection{Commands with arguments}\label{subsubsec:commands-arguments} \begin{example} - 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}.} + 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{cmhtcbraster}[raster column skip=.1\linewidth] \cmhlistingsfromfile{demonstrations/mycommand.tex}{\texttt{mycommand.tex}}{lst:mycommand} @@ -3810,8 +3874,8 @@ latexindent.pl items1.tex -local items-indentRulesGlobal.yaml \end{cmhtcbraster} 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} + specify \texttt{noAdditionalIndent} either in `scalar' form, or in `field' form, as + shown in \cref{lst:mycommand-noAdd1,lst:mycommand-noAdd2} \begin{cmhtcbraster} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycommand-noAdd1.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{mycommand-noAdd1.yaml}}{lst:mycommand-noAdd1} @@ -3868,8 +3932,8 @@ latexindent.pl mycommand.tex -l mycommand-noAdd4.yaml \begin{example} 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-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 @@ -3896,8 +3960,8 @@ latexindent.pl mycommand.tex -l mycommand-noAdd6.yaml \end{cmhtcbraster} \end{example} - 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 + 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}. % arara: pdflatex: { files: [latexindent]} \subsubsection{ifelsefi code blocks} @@ -4035,9 +4099,10 @@ latexindent.pl special1.tex -l special-indent-rules-global.yaml 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. + 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{cmhtcbraster} \cmhlistingsfromfile{demonstrations/special1-noAdd-glob.tex}{\texttt{special1.tex} using \cref{lst:special-noAdd-glob}}{lst:special1-output-noAdd-glob} @@ -4090,8 +4155,8 @@ latexindent.pl headings2.tex -l headings4.yaml \begin{example} 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. + 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{cmhtcbraster}[raster force size=false, raster column 1/.style={add to width=1cm}, @@ -4114,9 +4179,9 @@ latexindent.pl headings2.tex -l headings4.yaml \begin{example} 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. + 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{cmhtcbraster} \cmhlistingsfromfile[showtabs=true]{demonstrations/headings2-mod7.tex}{\texttt{headings2.tex} using \cref{lst:headings7yaml}}{lst:headings2-mod7} @@ -4148,19 +4213,19 @@ latexindent.pl headings2.tex -l headings4.yaml % arara: pdflatex: { 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} See the \texttt{keyEqualsValuesBracesBrackets: follow} and \texttt{keyEqualsValuesBracesBrackets: name} fields of the fine tuning section in @@ -4180,22 +4245,22 @@ latexindent.pl headings2.tex -l headings4.yaml \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} \end{example} \paragraph{namedGroupingBracesBrackets} This type of code block is mostly motivated by - tikz-based code; we define this code block as follows: + 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} See the \texttt{NamedGroupingBracesBrackets: follow} and \texttt{NamedGroupingBracesBrackets: name} fields of the fine tuning section in @@ -4213,27 +4278,29 @@ latexindent.pl headings2.tex -l headings4.yaml 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: + 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} \end{example} - \paragraph{UnNamedGroupingBracesBrackets} occur in a variety of situations; specifically, we - define this type of code block as satisfying the following criteria: + \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} See the \texttt{UnNamedGroupingBracesBrackets: follow} field of the fine tuning section - in \vref{lst:fineTuning} \announce{2019-07-13}{fine tuning: namedGroupingBracesBrackets}% + in \vref{lst:fineTuning} \announce{2019-07-13}{fine tuning: + namedGroupingBracesBrackets}% \begin{example} An example is shown in \cref{lst:psforeach1} with default output give in @@ -4244,23 +4311,25 @@ latexindent.pl headings2.tex -l headings4.yaml \cmhlistingsfromfile[showtabs=true]{demonstrations/psforeach1-default.tex}{\texttt{psforeach1.tex} default output}{lst:psforeach:default} \end{cmhtcbraster} - 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} \end{example} 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}. + 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. + neither arguments nor items are sought. \subsubsection{Summary} \index{indentation!summary} @@ -4286,8 +4355,8 @@ latexindent.pl headings2.tex -l headings4.yaml \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} @@ -4295,8 +4364,8 @@ latexindent.pl headings2.tex -l headings4.yaml \begin{example} 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}. + images in \texttt{PSTricks} and \texttt{tikz}; for example, let's consider the code + given in \cref{lst:pstricks1}. \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/pstricks1.tex}{\texttt{pstricks1.tex}}{lst:pstricks1} @@ -4333,9 +4402,9 @@ latexindent.pl pstricks1.tex -l noRoundParentheses.yaml 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 + 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}. \end{example} @@ -4381,14 +4450,15 @@ latexindent.pl pstricks1.tex -l defFunction.yaml 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 string \lstinline!node! (specified in \texttt{stringsAllowedBetweenArguments}) + \item the string \lstinline!node! (specified in + \texttt{stringsAllowedBetweenArguments}) \item the optional argument \lstinline![below,align=left,scale=0.5]! \end{itemize} \end{example} @@ -4409,11 +4479,11 @@ latexindent.pl tikz-node1.tex -l draw.yaml \end{cmhtcbraster} 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}. + \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 \index{switches!-l demonstration} + Let's compare this with the output from using the YAML settings in + \cref{lst:no-strings}, and running the command \index{switches!-l demonstration} \begin{commandshell} latexindent.pl tikz-node1.tex -l no-strings.yaml @@ -4429,12 +4499,12 @@ latexindent.pl tikz-node1.tex -l no-strings.yaml 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; + \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 it finds another \texttt{namedGroupingBracesBrackets} but this time called + \texttt{node} with argument \lstinline![below,align=left,scale=0.5]! \end{itemize} \end{example} @@ -4456,14 +4526,14 @@ latexindent.pl tikz-node1.tex -l no-strings.yaml \end{cmhtcbraster} 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. + 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} - 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 + 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}. \begin{example} @@ -4500,10 +4570,10 @@ latexindent.pl for-each.tex -l foreach.yaml \yamltitle{commandNameSpecial}*{fields} There are some special command names \announce{2018-04-27}*{commandNameSpecial} that do - not fit within the names recognised 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, + not fit within the names recognised 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!]!.% @@ -4516,8 +4586,8 @@ latexindent.pl for-each.tex -l foreach.yaml \cmhlistingsfromfile{demonstrations/ifnextchar-default.tex}{\texttt{ifnextchar.tex} default output}{lst:ifnextchar-default} \end{cmhtcbraster} - 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 + 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 <thing> and works outwards}, discussed in more detail on \cpageref{page:phases}. @@ -4591,8 +4661,8 @@ latexindent.pl for-each.tex -l foreach.yaml \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. + \texttt{latexindent.pl} will condense multiple blank lines into the number of blank + lines illustrated by this switch. \begin{example} As an example, \cref{lst:mlb-bl} shows a sample file with blank lines; upon running @@ -4629,31 +4699,40 @@ latexindent.pl myfile.tex -m -o=+-mod1 \item it happens \emph{after} verbatim blocks have been found; \item it happens \emph{after} the oneSentencePerLine routine (see \cref{sec:onesentenceperline}); - \item it happens \emph{before} all of the other code blocks are found and does \emph{not} - operate on a per-code-block basis; this means that, including indentation, you may - receive a column width wider than that which you specify in \texttt{columns} + \item it can happen \emph{before} or \emph{after} \announce*{2023-01-01}{text wrap: + before/after} all of the other code blocks are found and does \emph{not} operate + on a per-code-block basis; when using \texttt{before} this means that, including + indentation, you may receive a column width wider than that which you specify in + \texttt{columns}, and in which case you probably wish to explore \texttt{after} + in \cref{subsubsec:tw:before:after}; \item code blocks to be text wrapped will: \begin{enumerate} \item \emph{follow} the fields specified in \texttt{blocksFollow} \item \emph{begin} with the fields specified in \texttt{blocksBeginWith} \item \emph{end} before the fields specified in \texttt{blocksEndBefore} \end{enumerate} - \item setting \texttt{columns} to a value $>0$ will text wrap blocks by first removing line - breaks, and then wrapping according to the specified value of \texttt{columns}; - \item setting \texttt{columns} to $-1$ will \emph{only} remove line breaks within the text wrap - block; - \item by default, the text wrapping routine will remove line breaks within text blocks because - \texttt{removeBlockLineBreaks} is set to 1; switch it to 0 if you wish to change this; + \item setting \texttt{columns} to a value $>0$ will text wrap blocks by first removing + line breaks, and then wrapping according to the specified value of + \texttt{columns}; + \item setting \texttt{columns} to $-1$ will \emph{only} remove line breaks within the + text wrap block; + \item by default, the text wrapping routine will remove line breaks within text blocks + because \texttt{removeBlockLineBreaks} is set to 1; switch it to 0 if you wish to + change this; \item about trailing comments within text wrap blocks: \begin{enumerate} - \item trailing comments that do \emph{not} have leading space instruct the text wrap routine to - connect the lines \emph{without} space (see \cref{lst:tw-tc2}); - \item multiple trailing comments will be connected at the end of the text wrap block (see - \cref{lst:tw-tc4}); - \item the number of spaces between the end of the text wrap block and the (possibly combined) - trailing comments is determined by the spaces (if any) at the end of the text wrap block - (see \cref{lst:tw-tc5}). + \item trailing comments that do \emph{not} have leading space instruct the text + wrap routine to connect the lines \emph{without} space (see + \cref{lst:tw-tc2}); + \item multiple trailing comments will be connected at the end of the text wrap + block (see \cref{lst:tw-tc4}); + \item the number of spaces between the end of the text wrap block and the + (possibly combined) trailing comments is determined by the spaces (if any) + at the end of the text wrap block (see \cref{lst:tw-tc5}); \end{enumerate} + \item trailing comments can receive text wrapping \announce*{2023-01-01}{text wrap + trailing comments}; examples are shown in \cref{subsubsec:tw:comments} and + \cref{subsubsec:ospl:tw:comments}. \end{enumerate} We demonstrate this feature using a series of examples. @@ -4676,19 +4755,19 @@ latexindent.pl -m -l textwrap1.yaml textwrap1.tex \begin{cmhtcbraster}[raster column skip=.1\linewidth] \cmhlistingsfromfile{demonstrations/textwrap1-mod1.tex}{\texttt{textwrap1-mod1.tex}}{lst:textwrap1-mod1} - \cmhlistingsfromfile{demonstrations/textwrap1.yaml}[MLB-TCB]{\texttt{textwrap1.yaml}}{lst:textwrap1-yaml} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/textwrap1.yaml}[MLB-TCB]{\texttt{textwrap1.yaml}}{lst:textwrap1-yaml} \end{cmhtcbraster} \end{example} \begin{example} - If we set \texttt{columns} to $-1$ then \texttt{latexindent.pl} remove line breaks within - the text wrap block, and will \emph{not} perform text wrapping. We can use this to undo - text wrapping. \index{text wrap!setting columns to -1} + If we set \texttt{columns} to $-1$ then \texttt{latexindent.pl} remove line breaks + within the text wrap block, and will \emph{not} perform text wrapping. We can use this + to undo text wrapping. \index{text wrap!setting columns to -1} Starting from the file in \cref{lst:textwrap1-mod1} and using the settings in \cref{lst:textwrap1A-yaml} - \cmhlistingsfromfile{demonstrations/textwrap1A.yaml}[MLB-TCB]{\texttt{textwrap1A.yaml}}{lst:textwrap1A-yaml} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/textwrap1A.yaml}[MLB-TCB]{\texttt{textwrap1A.yaml}}{lst:textwrap1A-yaml} and running @@ -4714,8 +4793,8 @@ latexindent.pl -m -l textwrap1B.yaml textwrap1-mod1.tex gives the output in \cref{lst:textwrap1-mod1B}. \begin{cmhtcbraster}[raster column skip=.1\linewidth] - \cmhlistingsfromfile{demonstrations/textwrap1B.yaml}[MLB-TCB]{\texttt{textwrap1B.yaml}}{lst:textwrap1B-yaml} \cmhlistingsfromfile[showspaces=true]{demonstrations/textwrap1-mod1B.tex}{\texttt{textwrap1-mod1B.tex}}{lst:textwrap1-mod1B} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/textwrap1B.yaml}[MLB-TCB]{\texttt{textwrap1B.yaml}}{lst:textwrap1B-yaml} \end{cmhtcbraster} We note that in \cref{lst:textwrap1-mod1B} the multiple spaces have \emph{not} been condensed into single spaces. @@ -4744,14 +4823,15 @@ latexindent.pl -m -l textwrap1.yaml tw-headings1.tex We reference \vref{lst:textWrapOptionsAll} and also \vref{lst:indentAfterHeadings}: \begin{itemize} - \item in \cref{lst:textWrapOptionsAll} the \texttt{headings} field is set to \texttt{1}, which - instructs \texttt{latexindent.pl} to read the fields from \vref{lst:indentAfterHeadings}, - \emph{regardless of the value of indentAfterThisHeading or level}; - \item the default is to assume that the heading command can, optionally, be followed by a - \texttt{label} command. + \item in \cref{lst:textWrapOptionsAll} the \texttt{headings} field is set to + \texttt{1}, which instructs \texttt{latexindent.pl} to read the fields from + \vref{lst:indentAfterHeadings}, \emph{regardless of the value of + indentAfterThisHeading or level}; + \item the default is to assume that the heading command can, optionally, be followed by + a \texttt{label} command. \end{itemize} - If you find scenarios in which the default value of \texttt{headings} does not work, then - you can explore the \texttt{other} field. + If you find scenarios in which the default value of \texttt{headings} does not work, + then you can explore the \texttt{other} field. We can turn off \texttt{headings} as in \cref{lst:bf-no-headings-yaml} and then run @@ -4762,8 +4842,8 @@ latexindent.pl -m -l textwrap1.yaml,bf-no-headings.yaml tw-headings1.tex gives the output in \cref{lst:tw-headings1-mod2}, in which text wrapping has been instructed \emph{not to happen} following headings. \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/bf-no-headings.yaml}[MLB-TCB]{\texttt{bf-no-headings.yaml}}{lst:bf-no-headings-yaml} \cmhlistingsfromfile{demonstrations/tw-headings1-mod2.tex}{\texttt{tw-headings1-mod2.tex}}{lst:tw-headings1-mod2} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/bf-no-headings.yaml}[MLB-TCB]{\texttt{bf-no-headings.yaml}}{lst:bf-no-headings-yaml} \end{cmhtcbraster} \end{example} @@ -4773,7 +4853,8 @@ latexindent.pl -m -l textwrap1.yaml,bf-no-headings.yaml tw-headings1.tex \cmhlistingsfromfile{demonstrations/tw-comments1.tex}{\texttt{tw-comments1.tex}}{lst:tw-comments1} - We note that \cref{lst:tw-comments1} contains trailing comments. Upon running the command + We note that \cref{lst:tw-comments1} contains trailing comments. Upon running the + command \begin{commandshell} latexindent.pl -m -l textwrap1.yaml tw-comments1.tex @@ -4799,8 +4880,8 @@ latexindent.pl -m -l textwrap1.yaml,bf-no-comments.yaml tw-comments1.tex raster left skip=-3.5cm, raster right skip=-2cm, ] - \cmhlistingsfromfile{demonstrations/bf-no-comments.yaml}[MLB-TCB]{\texttt{bf-no-comments.yaml}}{lst:bf-no-comments-yaml} \cmhlistingsfromfile{demonstrations/tw-comments1-mod2.tex}{\texttt{tw-comments1-mod2.tex}}{lst:tw-comments1-mod2} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/bf-no-comments.yaml}[MLB-TCB]{\texttt{bf-no-comments.yaml}}{lst:bf-no-comments-yaml} \end{cmhtcbraster} \end{example} @@ -4810,8 +4891,8 @@ latexindent.pl -m -l textwrap1.yaml,bf-no-comments.yaml tw-comments1.tex The \texttt{other} field of the \texttt{blocksFollow} can either be \texttt{0} (turned off) or set as a regular expression. The default value is set to - \lstinline!\\\]|\\item(?:\h|\[)! which can be translated to \emph{backslash followed by a - square bracket} or \emph{backslash item followed by horizontal space or a square + \lstinline!\\\]|\\item(?:\h|\[)! which can be translated to \emph{backslash followed by + a square bracket} or \emph{backslash item followed by horizontal space or a square bracket}, or in other words, \emph{end of display math} or an item command. \begin{example} @@ -4845,8 +4926,8 @@ latexindent.pl -m -l textwrap1.yaml,bf-no-disp-math.yaml tw-disp-math1.tex gives the output in \cref{lst:tw-disp-math1-mod2}, in which text wrapping has been instructed \emph{not to happen} following display math. \begin{cmhtcbraster}[raster column skip=.1\linewidth] - \cmhlistingsfromfile{demonstrations/bf-no-disp-math.yaml}[MLB-TCB]{\texttt{bf-no-disp-math.yaml}}{lst:bf-no-disp-math-yaml} \cmhlistingsfromfile{demonstrations/tw-disp-math1-mod2.tex}{\texttt{tw-disp-math1-mod2.tex}}{lst:tw-disp-math1-mod2} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/bf-no-disp-math.yaml}[MLB-TCB]{\texttt{bf-no-disp-math.yaml}}{lst:bf-no-disp-math-yaml} \end{cmhtcbraster} Naturally, you should feel encouraged to customise this as you see fit. @@ -4883,12 +4964,14 @@ latexindent.pl -m -l textwrap1.yaml,tw-bf-myenv.yaml tw-bf-myenv1.tex which gives the output in \cref{lst:tw-bf-myenv1-mod2}, in which text wrapping has been implemented across the file. - \begin{cmhtcbraster}[raster column skip=.1\linewidth, - raster left skip=-3.5cm, - raster right skip=-2cm, + \begin{cmhtcbraster}[raster column skip=.01\linewidth, + raster left skip=-1.5cm, + raster force size=false, + raster column 1/.style={add to width=-.1\textwidth}, + raster column 2/.style={add to width=.1\textwidth}, ] - \cmhlistingsfromfile{demonstrations/tw-bf-myenv.yaml}[MLB-TCB]{\texttt{tw-bf-myenv.yaml}}{lst:tw-bf-myenv-yaml} \cmhlistingsfromfile{demonstrations/tw-bf-myenv1-mod2.tex}{\texttt{tw-bf-myenv1-mod2.tex}}{lst:tw-bf-myenv1-mod2} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/tw-bf-myenv.yaml}[MLB-TCB,width=0.6\linewidth]{\texttt{tw-bf-myenv.yaml}}{lst:tw-bf-myenv-yaml} \end{cmhtcbraster} \end{example} @@ -4898,7 +4981,8 @@ latexindent.pl -m -l textwrap1.yaml,tw-bf-myenv.yaml tw-bf-myenv1.tex series of examples. \index{text wrap!blocksBeginWith} \begin{example} - By default, text wrap blocks can begin with the characters \texttt{a-z} and \texttt{A-Z}. + By default, text wrap blocks can begin with the characters \texttt{a-z} and + \texttt{A-Z}. If we start with the file given in \cref{lst:tw-0-9} \cmhlistingsfromfile{demonstrations/tw-0-9.tex}{\texttt{tw-0-9.tex}}{lst:tw-0-9} @@ -4921,8 +5005,8 @@ latexindent.pl -m -l textwrap1.yaml,bb-0-9-yaml tw-0-9.tex gives the output in \cref{lst:tw-0-9-mod2}, in which text wrapping \emph{has} happened. \begin{cmhtcbraster}[raster column skip=.1\linewidth,] - \cmhlistingsfromfile{demonstrations/bb-0-9.yaml}[MLB-TCB]{\texttt{bb-0-9.yaml.yaml}}{lst:bb-0-9-yaml} \cmhlistingsfromfile{demonstrations/tw-0-9-mod2.tex}{\texttt{tw-0-9-mod2.tex}}{lst:tw-0-9-mod2} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/bb-0-9.yaml}[MLB-TCB]{\texttt{bb-0-9.yaml.yaml}}{lst:bb-0-9-yaml} \end{cmhtcbraster} \end{example} @@ -4952,8 +5036,8 @@ latexindent.pl -m -l textwrap1.yaml,tw-bb-announce.yaml tw-bb-announce1.tex gives the output in \cref{lst:tw-bb-announce1-mod2}, in which text wrapping \emph{has} happened. \begin{cmhtcbraster}[raster column skip=.1\linewidth,] - \cmhlistingsfromfile{demonstrations/tw-bb-announce.yaml}[MLB-TCB]{\texttt{tw-bb-announce.yaml}}{lst:tw-bb-announce-yaml} \cmhlistingsfromfile{demonstrations/tw-bb-announce1-mod2.tex}{\texttt{tw-bb-announce1-mod2.tex}}{lst:tw-bb-announce1-mod2} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/tw-bb-announce.yaml}[MLB-TCB]{\texttt{tw-bb-announce.yaml}}{lst:tw-bb-announce-yaml} \end{cmhtcbraster} \end{example} @@ -4994,7 +5078,7 @@ latexindent.pl -m -l textwrap1A.yaml,tw-be-equation.yaml tw-be-equation.tex gives the output in \cref{lst:tw-be-equation-mod2}, in which text wrapping has been instructed \emph{not} to stop at these statements. - \cmhlistingsfromfile{demonstrations/tw-be-equation.yaml}[MLB-TCB]{\texttt{tw-be-equation.yaml}}{lst:tw-be-equation-yaml} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/tw-be-equation.yaml}[MLB-TCB]{\texttt{tw-be-equation.yaml}}{lst:tw-be-equation-yaml} \begin{widepage} \cmhlistingsfromfile{demonstrations/tw-be-equation-mod2.tex}{\texttt{tw-be-equation-mod2.tex}}{lst:tw-be-equation-mod2} @@ -5110,6 +5194,150 @@ latexindent.pl -m tw-tc6.tex -l textwrap1A.yaml -o=+-mod1 The space at the end of the text block has been preserved. \end{example} +\subsubsection{Text wrap: when before/after}\label{subsubsec:tw:before:after} + The text wrapping routine operates, by default, \texttt{before} the + \announce*{2023-01-01}{text wrap: before/after details} code blocks have been found, but + this can be changed to \texttt{after}: + \begin{itemize} + \item \texttt{before} means it is likely that the columns of wrapped text may \emph{exceed} the + value specified in \texttt{columns}; + \item \texttt{after} means it columns of wrapped text should \emph{not} exceed the value + specified in \texttt{columns}. + \end{itemize} + We demonstrate this in the following examples. See also + \cref{subsubsec:ospl:before:after}. + + \begin{example} + Let's begin with the file in \cref{lst:textwrap8}. + + \cmhlistingsfromfile*{demonstrations/textwrap8.tex}{\texttt{textwrap8.tex}}{lst:textwrap8} + + Using the settings given in \cref{lst:tw-before1} and running the command + + \begin{commandshell} +latexindent.pl textwrap8.tex -o=+-mod1.tex -l=tw-before1.yaml -m + \end{commandshell} + + gives the output given in \cref{lst:textwrap8-mod1}. + + \begin{cmhtcbraster}[raster columns=2, + raster left skip=-1.5cm, + raster right skip=-0cm, + raster column skip=.06\linewidth] + \cmhlistingsfromfile*{demonstrations/textwrap8-mod1.tex}{\texttt{textwrap8-mod1.tex}}{lst:textwrap8-mod1} + \cmhlistingsfromfile*[style=yaml-LST]{demonstrations/tw-before1.yaml}[MLB-TCB,width=0.4\linewidth]{\texttt{tw-before1.yaml}}{lst:tw-before1} + \end{cmhtcbraster} + + We note that, in \cref{lst:textwrap8-mod1}, that the wrapped text has \emph{exceeded} + the specified value of \texttt{columns} (35) given in \cref{lst:tw-before1}. We can + affect this by changing \texttt{when}; we explore this next. + \end{example} + + \begin{example} + We continue working with \cref{lst:textwrap8}. + + Using the settings given in \cref{lst:tw-after1} and running the command + + \begin{commandshell} +latexindent.pl textwrap8.tex -o=+-mod2.tex -l=tw-after1.yaml -m + \end{commandshell} + + gives the output given in \cref{lst:textwrap8-mod2}. + + \begin{cmhtcbraster}[raster columns=2, + raster left skip=-1.5cm, + raster right skip=-0cm, + raster column skip=.06\linewidth] + \cmhlistingsfromfile*{demonstrations/textwrap8-mod2.tex}{\texttt{textwrap8-mod2.tex}}{lst:textwrap8-mod2} + \cmhlistingsfromfile*[style=yaml-LST]{demonstrations/tw-after1.yaml}[MLB-TCB,width=0.4\linewidth]{\texttt{tw-after1.yaml}}{lst:tw-after1} + \end{cmhtcbraster} + + We note that, in \cref{lst:textwrap8-mod2}, that the wrapped text has \emph{obeyed} the + specified value of \texttt{columns} (35) given in \cref{lst:tw-after1}. + \end{example} + +\subsubsection{Text wrap: wrapping comments}\label{subsubsec:tw:comments} + You can instruct \texttt{latexindent.pl} to apply text wrapping to comments + \announce*{2023-01-01}{text wrap trailing comments}; we demonstrate this with examples, + see also \cref{subsubsec:ospl:tw:comments}. \index{comments!text wrap} \index{text + wrap!comments} + + \begin{example} + We use the file in \cref{lst:textwrap9} which contains a trailing comment block. + + \cmhlistingsfromfile*{demonstrations/textwrap9.tex}{\texttt{textwrap9.tex}}{lst:textwrap9} + + Using the settings given in \cref{lst:wrap-comments1} and running the command + + \begin{commandshell} +latexindent.pl textwrap9.tex -o=+-mod1.tex -l=wrap-comments1.yaml -m + \end{commandshell} + + gives the output given in \cref{lst:textwrap9-mod1}. + + \begin{cmhtcbraster}[raster columns=2, + raster left skip=-1.5cm, + raster right skip=-0cm, + raster column skip=.06\linewidth] + \cmhlistingsfromfile*{demonstrations/textwrap9-mod1.tex}{\texttt{textwrap9-mod1.tex}}{lst:textwrap9-mod1} + \cmhlistingsfromfile*[style=yaml-LST]{demonstrations/wrap-comments1.yaml}[MLB-TCB,width=0.4\linewidth]{\texttt{wrap-comments1.yaml}}{lst:wrap-comments1} + \end{cmhtcbraster} + + We note that, in \cref{lst:textwrap9-mod1}, that the comments have been \emph{combined + and wrapped} because of the annotated line specified in \cref{lst:wrap-comments1}. + \end{example} + + \begin{example} + We use the file in \cref{lst:textwrap10} which contains a trailing comment block. + + \cmhlistingsfromfile*{demonstrations/textwrap10.tex}{\texttt{textwrap10.tex}}{lst:textwrap10} + + Using the settings given in \cref{lst:wrap-comments1:repeat} and running the command + + \begin{commandshell} +latexindent.pl textwrap10.tex -o=+-mod1.tex -l=wrap-comments1.yaml -m + \end{commandshell} + + gives the output given in \cref{lst:textwrap10-mod1}. + + \begin{cmhtcbraster}[raster columns=2, + raster left skip=-1.5cm, + raster right skip=-0cm, + raster column skip=.06\linewidth] + \cmhlistingsfromfile*{demonstrations/textwrap10-mod1.tex}{\texttt{textwrap10-mod1.tex}}{lst:textwrap10-mod1} + \cmhlistingsfromfile*[style=yaml-LST]{demonstrations/wrap-comments1.yaml}[MLB-TCB,width=0.4\linewidth]{\texttt{wrap-comments1.yaml}}{lst:wrap-comments1:repeat} + \end{cmhtcbraster} + + We note that, in \cref{lst:textwrap10-mod1}, that the comments have been \emph{combined + and wrapped} because of the annotated line specified in + \cref{lst:wrap-comments1:repeat}, and that the space from the leading comment has not + been inherited; we will explore this further in the next example. + \end{example} + + \begin{example} + We continue to use the file in \cref{lst:textwrap10}. + + Using the settings given in \cref{lst:wrap-comments2} and running the command + + \begin{commandshell} +latexindent.pl textwrap10.tex -o=+-mod2.tex -l=wrap-comments2.yaml -m + \end{commandshell} + + gives the output given in \cref{lst:textwrap10-mod2}. + + \begin{cmhtcbraster}[raster columns=2, + raster left skip=-1.5cm, + raster right skip=-0cm, + raster column skip=.06\linewidth] + \cmhlistingsfromfile*{demonstrations/textwrap10-mod2.tex}{\texttt{textwrap10-mod2.tex}}{lst:textwrap10-mod2} + \cmhlistingsfromfile*[style=yaml-LST]{demonstrations/wrap-comments2.yaml}[MLB-TCB,width=0.4\linewidth]{\texttt{wrap-comments2.yaml}}{lst:wrap-comments2} + \end{cmhtcbraster} + + We note that, in \cref{lst:textwrap10-mod2}, that the comments have been \emph{combined + and wrapped} and that the leading space has been inherited because of the annotated + lines specified in \cref{lst:wrap-comments2}. + \end{example} + \subsubsection{Text wrap: huge, tabstop and separator} The \announce{2021-07-23}*{huge:overflow is now default} default value of \texttt{huge} is \texttt{overflow}, which means that words will \emph{not} be broken by the text @@ -5123,8 +5351,8 @@ latexindent.pl -m tw-tc6.tex -l textwrap1A.yaml -o=+-mod1 down \texttt{latexindent.pl} significantly when the \texttt{-m} switch is active. Furthermore, changing \texttt{huge} means that you may have some words \emph{or - commands}(!) split across lines in your .tex file, which may affect your output. I do not - recommend changing this field. + commands}(!) split across lines in your .tex file, which may affect your output. I do + not recommend changing this field. \end{warning} \begin{example} @@ -5141,10 +5369,10 @@ latexindent.pl -m tw-tc6.tex -l textwrap1A.yaml -o=+-mod1 \begin{cmhtcbraster}[raster column skip=.1\linewidth] \cmhlistingsfromfile{demonstrations/textwrap4-mod2A.tex}{\texttt{textwrap4-mod2A.tex}}{lst:textwrap4-mod2A} - \cmhlistingsfromfile{demonstrations/textwrap2A.yaml}[MLB-TCB]{\texttt{textwrap2A.yaml}}{lst:textwrap2A-yaml} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/textwrap2A.yaml}[MLB-TCB]{\texttt{textwrap2A.yaml}}{lst:textwrap2A-yaml} \cmhlistingsfromfile{demonstrations/textwrap4-mod2B.tex}{\texttt{textwrap4-mod2B.tex}}{lst:textwrap4-mod2B} - \cmhlistingsfromfile{demonstrations/textwrap2B.yaml}[MLB-TCB]{\texttt{textwrap2B.yaml}}{lst:textwrap2B-yaml} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/textwrap2B.yaml}[MLB-TCB]{\texttt{textwrap2B.yaml}}{lst:textwrap2B-yaml} \end{cmhtcbraster} \end{example} @@ -5153,9 +5381,9 @@ latexindent.pl -m tw-tc6.tex -l textwrap1A.yaml -o=+-mod1 \cite{textwrap} for details. \begin{example} - Starting with the code in \cref{lst:textwrap-ts} with settings in \cref{lst:tabstop}, and - running the command \index{switches!-l demonstration} \index{switches!-m demonstration} - \index{switches!-o demonstration}% + Starting with the code in \cref{lst:textwrap-ts} with settings in \cref{lst:tabstop}, + and running the command \index{switches!-l demonstration} \index{switches!-m + demonstration} \index{switches!-o demonstration}% \begin{commandshell} latexindent.pl -m textwrap-ts.tex -o=+-mod1 -l tabstop.yaml @@ -5167,7 +5395,7 @@ latexindent.pl -m tw-tc6.tex -l textwrap1A.yaml -o=+-mod1 raster right skip=-2cm, raster column skip=.03\linewidth] \cmhlistingsfromfile[showtabs=true]{demonstrations/textwrap-ts.tex}{\texttt{textwrap-ts.tex}}{lst:textwrap-ts} - \cmhlistingsfromfile{demonstrations/tabstop.yaml}[MLB-TCB]{\texttt{tabstop.yaml}}{lst:tabstop} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/tabstop.yaml}[MLB-TCB]{\texttt{tabstop.yaml}}{lst:tabstop} \cmhlistingsfromfile[showtabs=true]{demonstrations/textwrap-ts-mod1.tex}{\texttt{textwrap-ts-mod1.tex}}{lst:textwrap-ts-mod1} \end{cmhtcbraster} \end{example} @@ -5180,8 +5408,8 @@ latexindent.pl -m tw-tc6.tex -l textwrap1A.yaml -o=+-mod1 % arara: pdflatex: { files: [latexindent]} \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 + 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. \index{modifying linebreaks! by using one sentence per line} @@ -5191,6 +5419,37 @@ latexindent.pl -m tw-tc6.tex -l textwrap1A.yaml -o=+-mod1 \cmhlistingsfromfile[style=oneSentencePerLine]{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{oneSentencePerLine}}{lst:oneSentencePerLine} +\subsubsection{oneSentencePerLine: overview} + An overview of how the oneSentencePerLine routine feature works: + \begin{enumerate} + \item the default value of \texttt{manipulateSentences} is 0, which means that + oneSentencePerLine will \emph{not} happen by default; + \item it happens \emph{after} verbatim blocks have been found; + \item it happens \emph{before} the text wrapping routine (see + \cref{subsec:textwrapping}); + \item it happens \emph{before} the main code blocks have been found; + \item sentences to be found: + \begin{enumerate} + \item \emph{follow} the fields specified in \texttt{sentencesFollow} + \item \emph{begin} with the fields specified in \texttt{sentencesBeginWith} + \item \emph{end} with the fields specified in \texttt{sentencesEndWith} + \end{enumerate} + \item by default, the oneSentencePerLine routine will remove line breaks within + sentences because \texttt{removeBlockLineBreaks} is set to 1; switch it to 0 if + you wish to change this; + \item sentences can be text wrapped according to \texttt{textWrapSentences}, and will + be done either \texttt{before} or \texttt{after} the main indentation routine + (see \cref{subsubsec:ospl:before:after}); + \item about trailing comments within text wrap blocks: + \begin{enumerate} + \item multiple trailing comments will be connected at the end of the sentence; + \item the number of spaces between the end of the sentence and the (possibly + combined) trailing comments is determined by the spaces (if any) at the + end of the sentence. + \end{enumerate} + \end{enumerate} + + We demonstrate this feature using a series of examples. \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 @@ -5263,16 +5522,17 @@ latexindent.pl multiple-sentences -m -l=keep-sen-line-breaks.yaml expressions. \index{regular expressions!lowercase alph a-z} \index{regular expressions!uppercase alph A-Z} - \begin{cmhtcbraster}[raster columns=3, + \begin{cmhtcbraster}[raster columns=2, raster left skip=-3.5cm, raster right skip=-2cm, raster column skip=.06\linewidth] \cmhlistingsfromfile[style=sentencesFollow]{../defaultSettings.yaml}[MLB-TCB,width=.9\linewidth,before=\centering]{\texttt{sentencesFollow}}{lst:sentencesFollow} \cmhlistingsfromfile[style=sentencesBeginWith]{../defaultSettings.yaml}[MLB-TCB,width=.9\linewidth,before=\centering]{\texttt{sentencesBeginWith}}{lst:sentencesBeginWith} - \cmhlistingsfromfile[style=sentencesEndWith]{../defaultSettings.yaml}[MLB-TCB,width=.9\linewidth,before=\centering]{\texttt{sentencesEndWith}}{lst:sentencesEndWith} \end{cmhtcbraster} -\subsubsection{sentencesFollow} + \cmhlistingsfromfile[style=sentencesEndWith]{../defaultSettings.yaml}[MLB-TCB,width=.9\linewidth,before=\centering]{\texttt{sentencesEndWith}}{lst:sentencesEndWith} + +\subsubsection{oneSentencePerLine: sentencesFollow} Let's explore a few of the switches in \texttt{sentencesFollow}. \begin{example} @@ -5331,11 +5591,12 @@ latexindent.pl multiple-sentences1 -m -l=manipulate-sentences.yaml,sentences-fol accounted for correctly. \end{example} -\subsubsection{sentencesBeginWith} +\subsubsection{oneSentencePerLine: 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. \index{sentences!begin with} + lower case letters (see \cref{lst:sentencesBeginWith}), and we can use the + \texttt{other} field to define sentences to begin with other characters. + \index{sentences!begin with} \begin{example} We use the file in \cref{lst:multiple-sentences2}. @@ -5364,14 +5625,15 @@ latexindent.pl multiple-sentences2 -m -l=manipulate-sentences.yaml,sentences-beg \cmhlistingsfromfile{demonstrations/multiple-sentences2-mod2.tex}{\texttt{multiple-sentences2.tex} using \cref{lst:sentences-begin1-yaml}}{lst:multiple-sentences2-mod2} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/sentences-begin1.yaml}[MLB-TCB,width=.45\textwidth]{\texttt{sentences-begin1.yaml}}{lst:sentences-begin1-yaml} \end{cmhtcbraster} - 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}. \end{example} -\subsubsection{sentencesEndWith} +\subsubsection{oneSentencePerLine: sentencesEndWith} \begin{example} 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 @@ -5427,9 +5689,9 @@ 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; @@ -5510,8 +5772,9 @@ latexindent.pl multiple-sentences4 -m -l=keep-sen-line-breaks.yaml \begin{example} Once you've read \cref{sec:poly-switches}, you will know that you can accommodate the - removal of internal sentence line breaks by using the YAML in \cref{lst:item-rules2-yaml} - and the command \index{switches!-l demonstration} \index{switches!-m demonstration} + removal of internal sentence line breaks by using the YAML in + \cref{lst:item-rules2-yaml} and the command \index{switches!-l demonstration} + \index{switches!-m demonstration} \begin{commandshell} latexindent.pl multiple-sentences4 -m -l=item-rules2.yaml @@ -5525,7 +5788,7 @@ latexindent.pl multiple-sentences4 -m -l=item-rules2.yaml \end{cmhtcbraster} \end{example} -\subsubsection{Text wrapping and indenting sentences} +\subsubsection{oneSentencePerLine: 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. \index{sentences!text wrapping} \index{sentences!indenting}% @@ -5590,13 +5853,13 @@ latexindent.pl multiple-sentences6 -m -l=sentence-wrap1.yaml -y="modifyLineBreak \begin{example} We can tweak the settings in \vref{lst:sentencesEndWith} to ensure that full stops are not followed by \texttt{item} commands, and that the end of sentences contains - \lstinline!\end{itemize}! as in \cref{lst:itemize-yaml} (if you intend to use this, - ensure that you remove the line breaks from the \texttt{other} field). \index{regular - expressions!lowercase alph a-z} \index{regular expressions!uppercase alph A-Z} - \index{regular expressions!numeric 0-9} \index{regular expressions!horizontal space - \textbackslash{h}} + \lstinline!\end{itemize}! as in \cref{lst:itemize-yaml}. This setting is actually an + appended version of the \texttt{betterFullStop} from the \texttt{fineTuning}, detailed + in \vref{lst:fineTuning}. \index{regular expressions!lowercase alph a-z} \index{regular + expressions!uppercase alph A-Z} \index{regular expressions!numeric 0-9} \index{regular + expressions!horizontal space \textbackslash{h}} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/itemized.yaml}[MLB-TCB]{\texttt{itemize.yaml}}{lst:itemize-yaml} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/itemize.yaml}[enhanced jigsaw,breakable,MLB-TCB]{\texttt{itemize.yaml}}{lst:itemize-yaml} Upon running \index{switches!-l demonstration} \index{switches!-m demonstration} @@ -5615,6 +5878,101 @@ latexindent.pl multiple-sentences6 -m -l=sentence-wrap1.yaml,itemize.yaml Text \announce{2022-04-04}*{oneSentencePerLine text wrapping update} wrapping when using the \texttt{oneSentencePerLine} routine determines if it will remove line breaks while text wrapping, from the value of \texttt{removeSentenceLineBreaks}. + +\subsubsection{oneSentencePerLine: text wrapping and indenting sentences, when before/after}\label{subsubsec:ospl:before:after} + The text wrapping routine operates, by default, \texttt{before} the + \announce*{2023-01-01}{text wrap: before/after details} code blocks have been found, but + this can be changed to \texttt{after}: + \begin{itemize} + \item \texttt{before} means it is likely that the columns of wrapped text may \emph{exceed} the + value specified in \texttt{columns}; + \item \texttt{after} means it columns of wrapped text should \emph{not} exceed the value + specified in \texttt{columns}. + \end{itemize} + We demonstrate this in the following examples. See also + \cref{subsubsec:tw:before:after}. + + \begin{example} + Let's begin with the file in \cref{lst:multiple-sentences8}. + + \cmhlistingsfromfile*{demonstrations/multiple-sentences8.tex}{\texttt{multiple-sentences8.tex}}{lst:multiple-sentences8} + + Using the settings given in \cref{lst:sentence-wrap2} and running the command + + \begin{commandshell} +latexindent.pl multiple-sentences8 -o=+-mod1.tex -l=sentence-wrap2 -m + \end{commandshell} + + gives the output given in \cref{lst:multiple-sentences8-mod1}. + + \begin{cmhtcbraster}[raster columns=2, + raster left skip=-1.5cm, + raster right skip=-0cm, + raster column skip=.06\linewidth] + \cmhlistingsfromfile*{demonstrations/multiple-sentences8-mod1.tex}{\texttt{multiple-sentences8-mod1.tex}}{lst:multiple-sentences8-mod1} + \cmhlistingsfromfile*[style=yaml-LST]{demonstrations/sentence-wrap2.yaml}[MLB-TCB,width=0.4\linewidth]{\texttt{sentence-wrap2.yaml}}{lst:sentence-wrap2} + \end{cmhtcbraster} + + We note that, in \cref{lst:multiple-sentences8-mod1}, that the wrapped text has + \emph{exceeded} the specified value of \texttt{columns} (35) given in + \cref{lst:sentence-wrap2}. We can affect this by changing \texttt{when}; we explore this + next. + \end{example} + + \begin{example} + We continue working with \cref{lst:multiple-sentences8}. + + Using the settings given in \cref{lst:sentence-wrap3} and running the command + + \begin{commandshell} +latexindent.pl multiple-sentences8.tex -o=+-mod2.tex -l=sentence-wrap3 -m + \end{commandshell} + + gives the output given in \cref{lst:multiple-sentences8-mod2}. + + \begin{cmhtcbraster}[raster columns=2, + raster left skip=-1.5cm, + raster right skip=-0cm, + raster column skip=.06\linewidth] + \cmhlistingsfromfile*{demonstrations/multiple-sentences8-mod2.tex}{\texttt{multiple-sentences8-mod2.tex}}{lst:multiple-sentences8-mod2} + \cmhlistingsfromfile*[style=yaml-LST]{demonstrations/sentence-wrap3.yaml}[MLB-TCB,width=0.4\linewidth]{\texttt{sentence-wrap3.yaml}}{lst:sentence-wrap3} + \end{cmhtcbraster} + + We note that, in \cref{lst:multiple-sentences8-mod2}, that the wrapped text has + \emph{obeyed} the specified value of \texttt{columns} (35) given in + \cref{lst:sentence-wrap3}. + \end{example} + +\subsubsection{oneSentencePerLine: text wrapping sentences and comments}\label{subsubsec:ospl:tw:comments} + We demonstrate the one sentence per line routine with respect to text wrapping + \emph{comments}. See also \cref{subsubsec:tw:comments}. \index{comments!text wrap} + \index{text wrap!comments} \index{sentences!comments} \index{sentences!text wrap} + + \begin{example} + Let's begin with the file in \cref{lst:multiple-sentences9}. + + \cmhlistingsfromfile*{demonstrations/multiple-sentences9.tex}{\texttt{multiple-sentences9.tex}}{lst:multiple-sentences9} + + Using the settings given in \cref{lst:sentence-wrap4} and running the command + + \begin{commandshell} +latexindent.pl multiple-sentences9 -o=+-mod1.tex -l=sentence-wrap4 -m + \end{commandshell} + + gives the output given in \cref{lst:multiple-sentences9-mod1}. + + \begin{cmhtcbraster}[raster columns=2, + raster left skip=-1.5cm, + raster right skip=-0cm, + raster column skip=.06\linewidth] + \cmhlistingsfromfile*{demonstrations/multiple-sentences9-mod1.tex}{\texttt{multiple-sentences9-mod1.tex}}{lst:multiple-sentences9-mod1} + \cmhlistingsfromfile*[style=yaml-LST]{demonstrations/sentence-wrap4.yaml}[MLB-TCB,width=0.4\linewidth]{\texttt{sentence-wrap4.yaml}}{lst:sentence-wrap4} + \end{cmhtcbraster} + + We note that, in \cref{lst:multiple-sentences9-mod1}, that the sentences have been + wrapped, and so too have the comments because of the annotated line in + \cref{lst:sentence-wrap4}. + \end{example} % arara: pdflatex: { files: [latexindent]} \subsection{Poly-switches}\label{sec:poly-switches} Every other field in the \texttt{modifyLineBreaks} field uses poly-switches, and can take @@ -5648,17 +6006,17 @@ latexindent.pl multiple-sentences6 -m -l=sentence-wrap1.yaml,itemize.yaml In the above, \emph{<part of thing>} 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. + \texttt{latexindent.pl} searches first of all for per-name settings, and then followed + by global per-thing settings. \subsubsection{Poly-switches for environments}\label{sec:modifylinebreaks-environments} We start by viewing a snippet of \texttt{defaultSettings.yaml} in \cref{lst:environments-mlb}; note that it contains \emph{global} settings (immediately - after the \texttt{environments} field) and that \emph{per-name} settings are also allowed - -- in the case of \cref{lst:environments-mlb}, settings for \texttt{equation*} have been - specified for demonstration. Note that all poly-switches are \emph{off} (set to 0) by - default. \index{poly-switches!default values} \index{poly-switches!environment global - example} \index{poly-switches!environment per-code block example} + after the \texttt{environments} field) and that \emph{per-name} settings are also + allowed -- in the case of \cref{lst:environments-mlb}, settings for \texttt{equation*} + have been specified for demonstration. Note that all poly-switches are \emph{off} (set + to 0) by default. \index{poly-switches!default values} \index{poly-switches!environment + global example} \index{poly-switches!environment per-code block example} \cmhlistingsfromfile[style=modifylinebreaksEnv]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,MLB-TCB]{\texttt{environments}}{lst:environments-mlb} @@ -5676,8 +6034,8 @@ before words(*@$\BeginStartsOnOwnLine$@*) \begin{myenv}(*@$\BodyStartsOnOwnLine$ \paragraph{Adding line breaks: BeginStartsOnOwnLine and BodyStartsOnOwnLine} \begin{example} Let's explore \texttt{BeginStartsOnOwnLine} and \texttt{BodyStartsOnOwnLine} in - \cref{lst:env-mlb1,lst:env-mlb2}, and in particular, let's allow each of them in turn to - take a value of $1$. \index{modifying linebreaks! at the \emph{beginning} of a code + \cref{lst:env-mlb1,lst:env-mlb2}, and in particular, let's allow each of them in turn + to take a value of $1$. \index{modifying linebreaks! at the \emph{beginning} of a code block} \index{poly-switches!adding line breaks: set to 1} \begin{cmhtcbraster} @@ -5708,27 +6066,34 @@ 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; + $\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. + $\BodyStartsOnOwnLine$ in \cref{lst:env-mlb1-tex}; furthermore, note that the + \emph{body} of \texttt{myenv} has received the appropriate (default) + indentation. \end{itemize} \end{example} \begin{example} 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}). \index{poly-switches!adding comments - and then line breaks: set to 2} + respectively (see \cref{lst:env-mlb3,lst:env-mlb4}). \index{poly-switches!adding + comments and then line breaks: set to 2} \begin{cmhtcbraster} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb3.yaml}[MLB-TCB]{\texttt{env-mlb3.yaml}}{lst:env-mlb3} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb4.yaml}[MLB-TCB]{\texttt{env-mlb4.yaml}}{lst:env-mlb4} \end{cmhtcbraster} - Upon running commands analogous to the above, we obtain - \cref{lst:env-mlb-mod3,lst:env-mlb-mod4}. + Upon running the commands + + \begin{commandshell} +latexindent.pl -m env-mlb.tex -l env-mlb3.yaml +latexindent.pl -m env-mlb.tex -l env-mlb4.yaml +\end{commandshell} + + we obtain \cref{lst:env-mlb-mod3,lst:env-mlb-mod4}. \begin{widepage} \begin{minipage}{.56\linewidth} @@ -5740,9 +6105,9 @@ 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. \end{example} \begin{example} @@ -5756,8 +6121,14 @@ latexindent.pl -m env-mlb.tex -l env-mlb2.yaml \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb6.yaml}[MLB-TCB]{\texttt{env-mlb6.yaml}}{lst:env-mlb6} \end{cmhtcbraster} - Upon running commands analogous to the above, we obtain - \cref{lst:env-mlb-mod5,lst:env-mlb-mod6}. + Upon running the commands + + \begin{commandshell} +latexindent.pl -m env-mlb.tex -l env-mlb5.yaml +latexindent.pl -m env-mlb.tex -l env-mlb6.yaml +\end{commandshell} + + we obtain \cref{lst:env-mlb-mod5,lst:env-mlb-mod6}. \begin{widepage} \begin{minipage}{.56\linewidth} @@ -5769,8 +6140,8 @@ 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. \end{example} \begin{example} @@ -5778,8 +6149,7 @@ latexindent.pl -m env-mlb.tex -l env-mlb2.yaml that they are $4$ and save them into \texttt{env-beg4.yaml} and \texttt{env-body4.yaml} respectively (see \cref{lst:env-beg4,lst:env-body4}). \index{poly-switches!adding blank lines (again"!): set to 4} \announce{2019-07-13}{demonstration of new blank line - poly-switch} - % + poly-switch} % \begin{cmhtcbraster} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-beg4.yaml}[MLB-TCB]{\texttt{env-beg4.yaml}}{lst:env-beg4} @@ -5807,18 +6177,19 @@ latexindent.pl -m env-mlb.1tex -l env-body4.yaml We note in particular that, by design, for this value of the poly-switches: \begin{enumerate} - \item in \cref{lst:env-mlb1-beg4} a blank line has been inserted before the \lstinline!\begin! - statement, even though the \lstinline!\begin! statement was already on its own line; - \item in \cref{lst:env-mlb1-body4} a blank line has been inserted before the beginning of the - \emph{body}, even though it already began on its own line. + \item in \cref{lst:env-mlb1-beg4} a blank line has been inserted before the + \lstinline!\begin! statement, even though the \lstinline!\begin! statement was + already on its own line; + \item in \cref{lst:env-mlb1-body4} a blank line has been inserted before the beginning + of the \emph{body}, even though it already began on its own line. \end{enumerate} \end{example} \paragraph{Adding line breaks: EndStartsOnOwnLine and EndFinishesWithLineBreak} \begin{example} Let's explore \texttt{EndStartsOnOwnLine} and \texttt{EndFinishesWithLineBreak} in - \cref{lst:env-mlb7,lst:env-mlb8}, and in particular, let's allow each of them in turn to - take a value of $1$. \index{modifying linebreaks! at the \emph{end} of a code block} + \cref{lst:env-mlb7,lst:env-mlb8}, and in particular, let's allow each of them in turn + to take a value of $1$. \index{modifying linebreaks! at the \emph{end} of a code block} \index{poly-switches!adding line breaks: set to 1} \begin{cmhtcbraster} @@ -5847,9 +6218,9 @@ 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); + $\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} @@ -5866,8 +6237,14 @@ latexindent.pl -m env-mlb.tex -l env-mlb8.yaml \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb10.yaml}[MLB-TCB]{\texttt{env-mlb10.yaml}}{lst:env-mlb10} \end{cmhtcbraster} - Upon running commands analogous to the above, we obtain - \cref{lst:env-mlb-mod9,lst:env-mlb-mod10}. + Upon running the commands + + \begin{commandshell} +latexindent.pl -m env-mlb.tex -l env-mlb9.yaml +latexindent.pl -m env-mlb.tex -l env-mlb10.yaml +\end{commandshell} + + we obtain \cref{lst:env-mlb-mod9,lst:env-mlb-mod10}. \begin{widepage} \begin{minipage}{.43\linewidth} @@ -5879,24 +6256,31 @@ 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. \end{example} \begin{example} Let's 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}). \index{poly-switches!adding blank - lines: set to 3}\announce{2017-08-21}{demonstration of blank line poly-switch (3)}% + that they are $3$ and save them into \texttt{env-mlb11.yaml} and + \texttt{env-mlb12.yaml} respectively (see \cref{lst:env-mlb11,lst:env-mlb12}). + \index{poly-switches!adding blank lines: set to 3}\announce{2017-08-21}{demonstration + of blank line poly-switch (3)}% \begin{cmhtcbraster} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb11.yaml}[MLB-TCB]{\texttt{env-mlb11.yaml}}{lst:env-mlb11} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb12.yaml}[MLB-TCB]{\texttt{env-mlb12.yaml}}{lst:env-mlb12} \end{cmhtcbraster} - Upon running commands analogous to the above, we obtain - \cref{lst:env-mlb-mod11,lst:env-mlb-mod12}. + Upon running the commands + + \begin{commandshell} +latexindent.pl -m env-mlb.tex -l env-mlb11.yaml +latexindent.pl -m env-mlb.tex -l env-mlb12.yaml +\end{commandshell} + + we obtain \cref{lst:env-mlb-mod11,lst:env-mlb-mod12}. \begin{widepage} \begin{minipage}{.42\linewidth} @@ -5908,14 +6292,14 @@ 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. \end{example} \begin{example} Let's now change each of the \texttt{1} values in \cref{lst:env-mlb11,lst:env-mlb12} so - that they are $4$ and save them into \texttt{env-end4.yaml} and \texttt{env-end-f4.yaml} - respectively (see \cref{lst:env-end4,lst:env-end-f4}). + that they are $4$ and save them into \texttt{env-end4.yaml} and + \texttt{env-end-f4.yaml} respectively (see \cref{lst:env-end4,lst:env-end-f4}). \announce{2019-07-13}{demonstration of new blank line poly-switch} \index{poly-switches!adding blank lines (again"!): set to 4}% @@ -5924,7 +6308,8 @@ latexindent.pl -m env-mlb.tex -l env-mlb8.yaml \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-end-f4.yaml}[MLB-TCB]{\texttt{env-end-f4.yaml}}{lst:env-end-f4} \end{cmhtcbraster} - We will demonstrate this poly-switch value using the code from \vref{lst:env-mlb1-text}. + We will demonstrate this poly-switch value using the code from + \vref{lst:env-mlb1-text}. Upon running the commands \index{switches!-l demonstration} \index{switches!-m demonstration} @@ -5943,20 +6328,21 @@ latexindent.pl -m env-mlb.1tex -l env-end-f4.yaml We note in particular that, by design, for this value of the poly-switches: \begin{enumerate} - \item in \cref{lst:env-mlb1-end4} a blank line has been inserted before the \lstinline!\end! - statement, even though the \lstinline!\end! statement was already on its own line; - \item in \cref{lst:env-mlb1-end-f4} a blank line has been inserted after the \lstinline!\end! - statement, even though it already began on its own line. + \item in \cref{lst:env-mlb1-end4} a blank line has been inserted before the + \lstinline!\end! statement, even though the \lstinline!\end! statement was + already on its own line; + \item in \cref{lst:env-mlb1-end-f4} a blank line has been inserted after the + \lstinline!\end! statement, even though it already began on its own line. \end{enumerate} \end{example} \paragraph{poly-switches 1, 2, and 3 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$ or $3$), it will only do so if 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$ or $3$), it will only do so if necessary. \begin{example} - For example, if you process the file in \vref{lst:mlb2} using poly-switch values of 1, 2, - or 3, it will be left unchanged. + For example, if you process the file in \vref{lst:mlb2} using poly-switch values of 1, + 2, or 3, it will be left unchanged. \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/env-mlb2.tex}{\texttt{env-mlb2.tex}}{lst:mlb2} @@ -5971,13 +6357,14 @@ latexindent.pl -m env-mlb.1tex -l env-end-f4.yaml \begin{example} 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. + 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{cmhtcbraster}[raster column skip=.1\linewidth] \cmhlistingsfromfile{demonstrations/env-mlb3-mod2.tex}{\texttt{env-mlb3.tex} using \vref{lst:env-mlb2}}{lst:env-mlb3-mod2} @@ -5985,15 +6372,15 @@ latexindent.pl -m env-mlb.1tex -l env-end-f4.yaml \end{cmhtcbraster} \end{example} - 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. \paragraph{Removing line breaks (poly-switches set to $-1$)} - Setting poly-switches to $-1$ tells \texttt{latexindent.pl} to remove line breaks of the - \emph{<part of the thing>}, if necessary. + Setting poly-switches to $-1$ tells \texttt{latexindent.pl} to remove line breaks of + the \emph{<part of the thing>}, if necessary. \begin{example} We will consider the example code given in \cref{lst:mlb4}, noting in particular the @@ -6057,8 +6444,8 @@ latexindent.pl -m env-mlb4.tex -l env-mlb16.yaml \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 \index{switches!-l demonstration} \index{switches!-m + file; alternatively, you could tell \texttt{latexindent.pl} to load them all by using + the following command, for example \index{switches!-l demonstration} \index{switches!-m demonstration} \begin{widepage} @@ -6072,8 +6459,8 @@ latexindent.pl -m env-mlb4.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,e \paragraph{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{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. @@ -6096,13 +6483,13 @@ after words \begin{widepage} \begin{commandshell} -latexindent.pl -m env-mlb5.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,env-mlb16.yaml -latexindent.pl -m env-mlb5.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,env-mlb16.yaml,removeTWS-before.yaml +latexindent.pl -m env-mlb5.tex -l env-mlb13,env-mlb14,env-mlb15,env-mlb16 +latexindent.pl -m env-mlb5.tex -l env-mlb13,env-mlb14,env-mlb15,env-mlb16,removeTWS-before \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 + 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}. @@ -6136,20 +6523,20 @@ after words \cmhlistingsfromfile[style=yaml-LST]{demonstrations/UnpreserveBlankLines.yaml}[MLB-TCB]{\texttt{UnpreserveBlankLines.yaml}}{lst:UnpreserveBlankLines} \end{cmhtcbraster} - Upon running the following commands \index{switches!-l demonstration} \index{switches!-m - demonstration} + Upon running the following commands \index{switches!-l demonstration} + \index{switches!-m demonstration} \begin{widepage} \begin{commandshell} -latexindent.pl -m env-mlb6.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,env-mlb16.yaml -latexindent.pl -m env-mlb6.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,env-mlb16.yaml,UnpreserveBlankLines.yaml +latexindent.pl -m env-mlb6.tex -l env-mlb13,env-mlb14,env-mlb15,env-mlb16 +latexindent.pl -m env-mlb6.tex -l env-mlb13,env-mlb14,env-mlb15,env-mlb16,UnpreserveBlankLines \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 + \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 @@ -6167,17 +6554,17 @@ latexindent.pl -m env-mlb6.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,e \end{example} \begin{example} - 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} - Upon running the following commands \index{switches!-l demonstration} \index{switches!-m - demonstration} + Upon running the following commands \index{switches!-l demonstration} + \index{switches!-m demonstration} \begin{commandshell} latexindent.pl -m env-mlb7.tex -l env-mlb12.yaml,env-mlb13.yaml -latexindent.pl -m env-mlb7.tex -l env-mlb13.yaml,env-mlb14.yaml,UnpreserveBlankLines.yaml +latexindent.pl -m env-mlb7.tex -l env-mlb13,env-mlb14,UnpreserveBlankLines \end{commandshell} we receive the outputs given in \cref{lst:env-mlb7-preserve,lst:env-mlb7-no-preserve}. @@ -6197,16 +6584,17 @@ latexindent.pl -m env-mlb7.tex -l env-mlb13.yaml,env-mlb14.yaml,UnpreserveBlankL \end{itemize} \end{example} -\subsubsection{Poly-switches for double back slash}\label{subsec:dbs} +\subsubsection{Poly-switches for double backslash}\label{subsec:dbs} With reference to \texttt{lookForAlignDelims} (see \vref{lst:aligndelims:basic}) - \announce{2019-07-13}{poly-switch for double back slash} you can specify poly-switches to - dictate the line-break behaviour of double back slashes in environments + \announce{2019-07-13}{poly-switch for double backslash} you can specify poly-switches to + dictate the line-break behaviour of double backslashes in environments (\vref{lst:tabularafter:basic}), commands (\vref{lst:matrixafter}), or special code - blocks (\vref{lst:specialafter}). Note that for these poly-switches to take effect, the - name of the code block must necessarily be specified within \texttt{lookForAlignDelims} - (\vref{lst:aligndelims:basic}); we will demonstrate this in what follows. - \index{delimiters!poly-switches for double back slash} \index{modifying linebreaks! - surrounding double back slash} \index{poly-switches!for double back slash (delimiters)}% + blocks (\vref{lst:specialafter}). \footnote{There is no longer any need for the code + block to be specified within \texttt{lookForAlignDelims} for DBS poly-switches to + activate. \announce*{2023-01-01}*{DBS poly-switches no need to specify + lookForAlignDelims}} \index{delimiters!poly-switches for double backslash} + \index{modifying linebreaks! surrounding double backslash} \index{poly-switches!for + double back slash (delimiters)}% Consider the code given in \cref{lst:dbs-demo}. \begin{cmhlistings}[style=tcblatex,escapeinside={(*@}{@*)}]{\texttt{tabular3.tex}}{lst:dbs-demo} @@ -6216,21 +6604,22 @@ latexindent.pl -m env-mlb7.tex -l env-mlb13.yaml,env-mlb14.yaml,UnpreserveBlankL \end{cmhlistings} Referencing \cref{lst:dbs-demo}: \begin{itemize} - \item \texttt{DBS} stands for \emph{double back slash}; - \item line breaks ahead of the double back slash are annotated by $\ElseStartsOnOwnLine$, and - are controlled by \texttt{DBSStartsOnOwnLine}; - \item line breaks after the double back slash are annotated by $\ElseFinishesWithLineBreak$, - and are controlled by \texttt{DBSFinishesWithLineBreak}. + \item \texttt{DBS} stands for \emph{double backslash}; + \item line breaks ahead of the double backslash are annotated by + $\ElseStartsOnOwnLine$, and are controlled by \texttt{DBSStartsOnOwnLine}; + \item line breaks after the double backslash are annotated by + $\ElseFinishesWithLineBreak$, and are controlled by + \texttt{DBSFinishesWithLineBreak}. \end{itemize} Let's explore each of these in turn. - \paragraph{Double back slash starts on own line} + \paragraph{Double backslash starts on own line} \begin{example} We explore \texttt{DBSStartsOnOwnLine} ($\ElseStartsOnOwnLine$ in \cref{lst:dbs-demo}); starting with the code in \cref{lst:dbs-demo}, together with the YAML files given in - \cref{lst:DBS1} and \cref{lst:DBS2} and running the following commands \index{switches!-l - demonstration} \index{switches!-m demonstration} + \cref{lst:DBS1} and \cref{lst:DBS2} and running the following commands + \index{switches!-l demonstration} \index{switches!-m demonstration} \begin{commandshell} latexindent.pl -m tabular3.tex -l DBS1.yaml @@ -6255,22 +6644,22 @@ latexindent.pl -m tabular3.tex -l DBS2.yaml \item \cref{lst:DBS1} specifies \texttt{DBSStartsOnOwnLine} for \emph{every} environment (that is within \texttt{lookForAlignDelims}, \vref{lst:aligndelims:advanced}); - the double back slashes from \cref{lst:dbs-demo} have been moved to their own line in + the double backslashes from \cref{lst:dbs-demo} have been moved to their own line in \cref{lst:tabular3-DBS1}; \item \cref{lst:DBS2} specifies \texttt{DBSStartsOnOwnLine} on a \emph{per-name} basis for \texttt{tabular} (that is within \texttt{lookForAlignDelims}, \vref{lst:aligndelims:advanced}); - the double back slashes from \cref{lst:dbs-demo} have been moved to their own line in + the double backslashes from \cref{lst:dbs-demo} have been moved to their own line in \cref{lst:tabular3-DBS2}, having added comment symbols before moving them. \end{itemize} \end{example} - \paragraph{Double back slash finishes with line break} + \paragraph{Double backslash finishes with line break} \begin{example} Let's now explore \texttt{DBSFinishesWithLineBreak} ($\ElseFinishesWithLineBreak$ in \cref{lst:dbs-demo}); starting with the code in \cref{lst:dbs-demo}, together with the YAML files given in \cref{lst:DBS3} and \cref{lst:DBS4} and running the following - commands \index{poly-switches!for double back slash (delimiters)} \index{switches!-l + commands \index{poly-switches!for double backslash (delimiters)} \index{switches!-l demonstration} \index{switches!-m demonstration} \begin{commandshell} @@ -6296,25 +6685,25 @@ latexindent.pl -m tabular3.tex -l DBS4.yaml \item \cref{lst:DBS3} specifies \texttt{DBSFinishesWithLineBreak} for \emph{every} environment (that is within \texttt{lookForAlignDelims}, \vref{lst:aligndelims:advanced}); - the code following the double back slashes from \cref{lst:dbs-demo} has been moved to + the code following the double backslashes from \cref{lst:dbs-demo} has been moved to their own line in \cref{lst:tabular3-DBS3}; \item \cref{lst:DBS4} specifies \texttt{DBSFinishesWithLineBreak} on a \emph{per-name} basis for \texttt{tabular} (that is within \texttt{lookForAlignDelims}, \vref{lst:aligndelims:advanced}); - the first double back slashes from \cref{lst:dbs-demo} have moved code following them to + the first double backslashes from \cref{lst:dbs-demo} have moved code following them to their own line in \cref{lst:tabular3-DBS4}, having added comment symbols before moving - them; the final double back slashes have \emph{not} added a line break as they are at the + them; the final double backslashes have \emph{not} added a line break as they are at the end of the body within the code block. \end{itemize} \end{example} - \paragraph{Double back slash poly-switches for specialBeginEnd} + \paragraph{Double backslash poly-switches for specialBeginEnd} \begin{example} - Let's explore the double back slash poly-switches for code blocks within - \texttt{specialBeginEnd} code blocks (\vref{lst:specialBeginEnd}); we begin with the code - within \cref{lst:special4}. \index{specialBeginEnd!double backslash poly-switch + Let's explore the double backslash poly-switches for code blocks within + \texttt{specialBeginEnd} code blocks (\vref{lst:specialBeginEnd}); we begin with the + code within \cref{lst:special4}. \index{specialBeginEnd!double backslash poly-switch demonstration} \index{poly-switches!double backslash} \index{poly-switches!for double - back slash (delimiters)} \index{specialBeginEnd!lookForAlignDelims} \index{delimiters} + backslash (delimiters)} \index{specialBeginEnd!lookForAlignDelims} \index{delimiters} \index{linebreaks!summary of poly-switches} \cmhlistingsfromfile{demonstrations/special4.tex}{\texttt{special4.tex}}{lst:special4} @@ -6339,22 +6728,23 @@ latexindent.pl -m special4.tex -l DBS5.yaml There are a few things to note: \begin{itemize} - \item in \cref{lst:DBS5} we have specified \texttt{cmhMath} within \texttt{lookForAlignDelims}; - without this, the double back slash poly-switches would be ignored for this code block; + \item in \cref{lst:DBS5} we have specified \texttt{cmhMath} within + \texttt{lookForAlignDelims}; without this, the double backslash poly-switches + would be ignored for this code block; \item the \texttt{DBSFinishesWithLineBreak} poly-switch has controlled the line breaks - following the double back slashes; - \item the \texttt{SpecialEndStartsOnOwnLine} poly-switch has controlled the addition of a - comment symbol, followed by a line break, as it is set to a value of 2. + following the double backslashes; + \item the \texttt{SpecialEndStartsOnOwnLine} poly-switch has controlled the addition + of a comment symbol, followed by a line break, as it is set to a value of 2. \end{itemize} \end{example} - \paragraph{Double back slash poly-switches for optional and mandatory arguments} - For clarity, we provide a demonstration of controlling the double back slash + \paragraph{Double backslash poly-switches for optional and mandatory arguments} + For clarity, we provide a demonstration of controlling the double backslash poly-switches for optional and mandatory arguments. \begin{example} - We use with the code in \cref{lst:mycommand2}. \index{poly-switches!for double back slash - (delimiters)} + We use with the code in \cref{lst:mycommand2}. \index{poly-switches!for double + backslash (delimiters)} \cmhlistingsfromfile{demonstrations/mycommand2.tex}{\texttt{mycommand2.tex}}{lst:mycommand2} @@ -6385,10 +6775,10 @@ latexindent.pl -m mycommand2.tex -l DBS7.yaml \end{cmhtcbraster} \end{example} - \paragraph{Double back slash optional square brackets} - The pattern matching for the double back slash will also, optionally, allow trailing + \paragraph{Double backslash optional square brackets} + The pattern matching for the double backslash will also, optionally, allow trailing square brackets that contain a measurement of vertical spacing, for example - \lstinline!\\[3pt]!. \index{poly-switches!for double back slash (delimiters)} + \lstinline!\\[3pt]!. \index{poly-switches!for double backslash (delimiters)} \begin{example} For example, beginning with the code in \cref{lst:pmatrix3} @@ -6407,7 +6797,7 @@ latexindent.pl -m pmatrix3.tex -l DBS3.yaml \cmhlistingsfromfile{demonstrations/pmatrix3-mod3.tex}{\texttt{pmatrix3.tex} using \cref{lst:DBS3}}{lst:pmatrix3-DBS3} \end{example} - You can customise the pattern for the double back slash by exploring the \emph{fine + You can customise the pattern for the double backslash by exploring the \emph{fine tuning} field detailed in \vref{lst:fineTuning}. \subsubsection{Poly-switches for other code blocks} @@ -6530,8 +6920,14 @@ latexindent.pl -m -l=mycom-mlb1.yaml mycommand1.tex \begin{example} 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. + the command + + \begin{commandshell} +latexindent.pl -m -l=mycom-mlb2.yaml mycommand1.tex +\end{commandshell} + + we obtain \cref{lst:mycommand1-mlb2}; both beginning braces \lstinline!{! have had their + leading line breaks removed. \begin{cmhtcbraster}[ raster force size=false, @@ -6544,7 +6940,13 @@ latexindent.pl -m -l=mycom-mlb1.yaml mycommand1.tex \begin{example} 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}. + the command + + \begin{commandshell} +latexindent.pl -m -l=mycom-mlb3.yaml mycommand1.tex +\end{commandshell} + + we obtain \cref{lst:mycommand1-mlb3}. \begin{cmhtcbraster}[ raster force size=false, @@ -6560,8 +6962,8 @@ latexindent.pl -m -l=mycom-mlb1.yaml mycommand1.tex \begin{example} We use the example from \vref{lst:mycommand1}, and consider the YAML settings given in - \cref{lst:mycom-mlb4}. The output from running \index{poly-switches!conflicting switches} - \index{switches!-l demonstration} \index{switches!-m demonstration} + \cref{lst:mycom-mlb4}. The output from running \index{poly-switches!conflicting + switches} \index{switches!-l demonstration} \index{switches!-m demonstration} \begin{commandshell} latexindent.pl -m -l=mycom-mlb4.yaml mycommand1.tex @@ -6577,10 +6979,10 @@ latexindent.pl -m -l=mycom-mlb4.yaml mycommand1.tex 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 other hand, \texttt{RCuBFinishesWithLineBreak} \emph{should} finish with a line - break. + \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 @@ -6599,36 +7001,45 @@ latexindent.pl -m -l=mycom-mlb5.yaml mycommand1.tex we obtain the output given in \cref{lst:mycommand1-mlb5}. - \begin{cmhtcbraster}[raster column skip=.1\linewidth] + \begin{cmhtcbraster}[raster column skip=.05\linewidth] \cmhlistingsfromfile{demonstrations/mycommand1-mlb5.tex}{\texttt{mycommand1.tex} using \cref{lst:mycom-mlb5}}{lst:mycommand1-mlb5} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycom-mlb5.yaml}[MLB-TCB,width=\linewidth]{\texttt{mycom-mlb5.yaml}}{lst:mycom-mlb5} \end{cmhtcbraster} 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}. + second (i.e, \emph{last}) argument. - \begin{cmhtcbraster}[raster column skip=.1\linewidth] + Exploring this further, we consider the YAML settings in \cref{lst:mycom-mlb6}, and run + the command + + \begin{commandshell} +latexindent.pl -m -l=mycom-mlb6.yaml mycommand1.tex +\end{commandshell} + + which gives the output in \cref{lst:mycommand1-mlb6}. + + \begin{cmhtcbraster}[raster column skip=.05\linewidth] \cmhlistingsfromfile{demonstrations/mycommand1-mlb6.tex}{\texttt{mycommand1.tex} using \cref{lst:mycom-mlb6}}{lst:mycommand1-mlb6} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycom-mlb6.yaml}[MLB-TCB,width=\linewidth]{\texttt{mycom-mlb6.yaml}}{lst:mycom-mlb6} \end{cmhtcbraster} - 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} \end{example} \subsubsection{Conflicting poly-switches: nested code blocks} \begin{example} Now let's consider an example when nested code blocks have conflicting poly-switches; - we'll use the code in \cref{lst:nested-env}, noting that it contains nested environments. - \index{poly-switches!conflicting switches} + we'll use the code in \cref{lst:nested-env}, noting that it contains nested + environments. \index{poly-switches!conflicting switches} \cmhlistingsfromfile{demonstrations/nested-env.tex}{\texttt{nested-env.tex}}{lst:nested-env} @@ -6661,40 +7072,43 @@ latexindent.pl -m -l=nested-env-mlb1.yaml nested-env.tex \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$). + \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 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. + \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$. + \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, + 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}!). \begin{example} @@ -6715,9 +7129,10 @@ 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. + \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} @@ -6736,12 +7151,13 @@ latexindent.pl -m -l=nested-env-mlb2.yaml nested-env.tex You can instruct \texttt{latexindent.pl} to perform replacements/substitutions on your \announce{2019-07-13}{replacement mode switches} file by using any of the \texttt{-r}, - \texttt{-rv} or \texttt{-rr} switches: \index{verbatim!rv, replacementrespectverb switch} + \texttt{-rv} or \texttt{-rr} switches: \index{verbatim!rv, replacementrespectverb + switch} \begin{itemize} - \item the \texttt{-r} switch will perform indentation and replacements, not respecting verbatim - code blocks; - \item the \texttt{-rv} switch will perform indentation and replacements, and \emph{will} - respect verbatim code blocks; + \item the \texttt{-r} switch will perform indentation and replacements, not respecting + verbatim code blocks; + \item the \texttt{-rv} switch will perform indentation and replacements, and + \emph{will} respect verbatim code blocks; \item the \texttt{-rr} switch will \emph{not} perform indentation, and will perform replacements not respecting verbatim code blocks. \end{itemize} @@ -6763,18 +7179,19 @@ latexindent.pl -m -l=nested-env-mlb2.yaml nested-env.tex \end{tabular} \end{table} - The default value of the \texttt{replacements} field is shown in \cref{lst:replacements}; - as with all of the other fields, you are encouraged to customise and change this as you - see fit. The options in this field will \emph{only} be considered if the \texttt{-r}, - \texttt{-rv} or \texttt{-rr} switches are active; when discussing YAML settings related - to the replacement-mode switches, we will use the style given in \cref{lst:replacements}. + The default value of the \texttt{replacements} field is shown in + \cref{lst:replacements}; as with all of the other fields, you are encouraged to + customise and change this as you see fit. The options in this field will \emph{only} be + considered if the \texttt{-r}, \texttt{-rv} or \texttt{-rr} switches are active; when + discussing YAML settings related to the replacement-mode switches, we will use the style + given in \cref{lst:replacements}. \cmhlistingsfromfile[style=replacements]{../defaultSettings.yaml}[width=0.95\linewidth,before=\centering,replace-TCB]{\texttt{replacements}}{lst:replacements} The first entry within the \texttt{replacements} field is \texttt{amalgamate}, and is - \emph{optional}; by default it is set to 1, so that replacements will be amalgamated from - each settings file that you specify. As you'll see in the demonstrations that follow, - there is no need to specify this field. + \emph{optional}; by default it is set to 1, so that replacements will be amalgamated + from each settings file that you specify. As you'll see in the demonstrations that + follow, there is no need to specify this field. You'll notice that, by default, there is only \emph{one} entry in the \texttt{replacements} field, but it can take as many entries as you would like; each one @@ -6782,12 +7199,11 @@ latexindent.pl -m -l=nested-env-mlb2.yaml nested-env.tex \subsection{Introduction to replacements} Let's explore the action of the default settings, and then we'll demonstrate the feature - with further examples. With reference to \cref{lst:replacements}, the default action will - replace every instance of the text \texttt{latexindent.pl} with \texttt{pl.latexindent}. + with further examples. \begin{example} - Beginning with the code in \cref{lst:replace1} and running the command \index{switches!-r - demonstration} + Beginning with the code in \cref{lst:replace1} and running the command + \index{switches!-r demonstration} \begin{commandshell} latexindent.pl -r replace1.tex @@ -6800,9 +7216,13 @@ latexindent.pl -r replace1.tex \cmhlistingsfromfile{demonstrations/replace1-r1.tex}{\texttt{replace1.tex} default}{lst:replace1-r1} \end{cmhtcbraster} - If we don't wish to perform this replacement, then we can tweak the default settings of - \vref{lst:replacements} by changing \texttt{lookForThis} to 0; we perform this action in - \cref{lst:replace1-yaml}, and run the command \index{switches!-l demonstration} + We note that in \cref{lst:replacements}, because \texttt{lookForThis} is set to 0, the + specified replacement has \emph{not} been made, and there is no difference between + \cref{lst:replace1,lst:replace1-r1}. + + If we \emph{do} wish to perform this replacement, then we can tweak the default settings + of \vref{lst:replacements} by changing \texttt{lookForThis} to 1; we perform this action + in \cref{lst:replace1-yaml}, and run the command \index{switches!-l demonstration} \index{switches!-r demonstration} \begin{commandshell} @@ -6820,8 +7240,8 @@ latexindent.pl -r replace1.tex -l=replace1.yaml the default replacements are overwritten. \end{example} - We haven't yet discussed the \texttt{when} field; don't worry, we'll get to it as part of - the discussion in what follows. + We haven't yet discussed the \texttt{when} field; don't worry, we'll get to it as part + of the discussion in what follows. \subsection{The two types of replacements} There are two types of replacements: @@ -6863,8 +7283,8 @@ latexindent.pl -r colsep.tex -l=colsep.yaml \cmhlistingsfromfile[style=yaml-LST]{demonstrations/colsep.yaml}[replace-TCB]{\texttt{colsep.yaml}}{lst:colsep-yaml} \end{cmhtcbraster} Note that in \cref{lst:colsep-yaml}, we have specified \emph{two} separate fields, each - with their own `\emph{this}' field; furthermore, for both of the separate fields, we have - not specified `\texttt{that}', so the \texttt{that} field is assumed to be blank by + with their own `\emph{this}' field; furthermore, for both of the separate fields, we + have not specified `\texttt{that}', so the \texttt{that} field is assumed to be blank by \texttt{latexindent.pl}; We can make the YAML in \cref{lst:colsep-yaml} more concise by exploring the @@ -6890,21 +7310,21 @@ latexindent.pl -r colsep.tex -l=colsep1.yaml \cref{lst:colsep1}, we do note the following: \begin{itemize} \item the general form of the \texttt{substitution} field is - \lstinline!s/regex/replacement/modifiers!. You can place any regular expression you like - within this; + \lstinline!s/regex/replacement/modifiers!. You can place any regular expression + you like within this; \item we have `escaped' the backslash by using \lstinline!\\! \item we have used \lstinline!\d+! to represent \emph{at least} one digit - \item the \texttt{s} \emph{modifier} (in the \texttt{sg} at the end of the line) instructs - \texttt{latexindent.pl} to treat your file as one single line; - \item the \texttt{g} \emph{modifier} (in the \texttt{sg} at the end of the line) instructs - \texttt{latexindent.pl} to make the substitution \emph{globally} throughout your file; - you might try removing the \texttt{g} modifier from \cref{lst:colsep1} and observing the - difference in output. + \item the \texttt{s} \emph{modifier} (in the \texttt{sg} at the end of the line) + instructs \texttt{latexindent.pl} to treat your file as one single line; + \item the \texttt{g} \emph{modifier} (in the \texttt{sg} at the end of the line) + instructs \texttt{latexindent.pl} to make the substitution \emph{globally} + throughout your file; you might try removing the \texttt{g} modifier from + \cref{lst:colsep1} and observing the difference in output. \end{itemize} You might like to see \href{https://perldoc.perl.org/perlre.html#Modifiers}{https://perldoc.perl.org/perlre.html\#Modifiers} - for details of modifiers; in general, I recommend starting with the \texttt{sg} modifiers - for this feature. + for details of modifiers; in general, I recommend starting with the \texttt{sg} + modifiers for this feature. \end{example} \begin{example} @@ -6922,8 +7342,8 @@ latexindent.pl -r colsep.tex -l=multi-line.yaml \cmhlistingsfromfile{demonstrations/colsep-mod2.tex}{\texttt{colsep.tex} using \cref{lst:multi-line}}{lst:colsep-mod2} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/multi-line.yaml}[replace-TCB]{\texttt{multi-line.yaml}}{lst:multi-line} \end{cmhtcbraster} - With reference to \cref{lst:multi-line}, we have specified a \emph{multi-line} version of - \texttt{this} by employing the \emph{literal} YAML style \lstinline!|-!. See, for + With reference to \cref{lst:multi-line}, we have specified a \emph{multi-line} version + of \texttt{this} by employing the \emph{literal} YAML style \lstinline!|-!. See, for example, \href{https://stackoverflow.com/questions/3790454/in-yaml-how-do-i-break-a-string-over-multiple-lines}{https://stackoverflow.com/questions/3790454/in-yaml-how-do-i-break-a-string-over-multiple-lines} for further options, all of which can be used in your YAML file. @@ -6992,18 +7412,19 @@ latexindent.pl -r displaymath.tex -l=displaymath1.yaml A few notes about \cref{lst:displaymath1}: \begin{enumerate} - \item we have used the \texttt{x} modifier, which allows us to have white space within the - regex; - \item we have used a capture group, \lstinline!(.*?)! which captures the content between the - \lstinline!$$...$$! into the special variable, \lstinline!$1!; - \item we have used the content of the capture group, \lstinline!$1!, in the replacement text. + \item we have used the \texttt{x} modifier, which allows us to have white space within + the regex; + \item we have used a capture group, \lstinline!(.*?)! which captures the content + between the \lstinline!$$...$$! into the special variable, \lstinline!$1!; + \item we have used the content of the capture group, \lstinline!$1!, in the replacement + text. \end{enumerate} See \href{https://perldoc.perl.org/perlre.html#Capture-groups}{https://perldoc.perl.org/perlre.html\#Capture-groups} for a discussion of capture groups. - The features of the replacement switches can, of course, be combined with others from the - toolkit of \texttt{latexindent.pl}. For example, we can combine the poly-switches of + The features of the replacement switches can, of course, be combined with others from + the toolkit of \texttt{latexindent.pl}. For example, we can combine the poly-switches of \vref{sec:poly-switches}, which we do in \cref{lst:equation}; upon running the command \index{switches!-l demonstration} \index{switches!-m demonstration} \index{switches!-r demonstration} @@ -7038,8 +7459,8 @@ latexindent.pl -r -m displaymath.tex -l=displaymath1.yaml,equation.yaml latexindent.pl -r phrase.tex -l=hspace.yaml \end{commandshell} - which gives the output in \cref{lst:phrase-mod1}. \index{regular expressions!at least one - +} \index{regular expressions!horizontal space \textbackslash{h}} + which gives the output in \cref{lst:phrase-mod1}. \index{regular expressions!at least + one +} \index{regular expressions!horizontal space \textbackslash{h}} \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/phrase-mod1.tex}{\texttt{phrase.tex} using \cref{lst:hspace}}{lst:phrase-mod1} @@ -7076,18 +7497,19 @@ latexindent.pl -r references.tex -l=reference.yaml \end{example} \begin{example} - Let's explore the three replacement mode switches (see \vref{tab:replacementswitches}) in - the context of an example that contains a verbatim code block, \cref{lst:verb1}; we will - use the settings in \cref{lst:verbatim1-yaml}. + Let's explore the three replacement mode switches (see \vref{tab:replacementswitches}) + in the context of an example that contains a verbatim code block, \cref{lst:verb1}; we + will use the settings in \cref{lst:verbatim1-yaml}. \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/verb1.tex}{\texttt{verb1.tex}}{lst:verb1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/verbatim1.yaml}[replace-TCB]{\texttt{verbatim1.yaml}}{lst:verbatim1-yaml} \end{cmhtcbraster} - Upon running the following commands, \index{verbatim!comparison with -r and -rr switches} - \index{switches!-l demonstration} \index{switches!-o demonstration} \index{switches!-r - demonstration} \index{switches!-rv demonstration} \index{switches!-rr demonstration} + Upon running the following commands, \index{verbatim!comparison with -r and -rr + switches} \index{switches!-l demonstration} \index{switches!-o demonstration} + \index{switches!-r demonstration} \index{switches!-rv demonstration} \index{switches!-rr + demonstration} \begin{commandshell} latexindent.pl -r verb1.tex -l=verbatim1.yaml -o=+mod1 @@ -7108,12 +7530,12 @@ latexindent.pl -rr verb1.tex -l=verbatim1.yaml -o=+-rr-mod1 We note that: \begin{enumerate} - \item in \cref{lst:verb1-mod1} indentation has been performed, and that the replacements - specified in \cref{lst:verbatim1-yaml} have been performed, even within the verbatim code - block; - \item in \cref{lst:verb1-rv-mod1} indentation has been performed, but that the replacements - have \emph{not} been performed within the verbatim environment, because the \texttt{rv} - switch is active; + \item in \cref{lst:verb1-mod1} indentation has been performed, and that the + replacements specified in \cref{lst:verbatim1-yaml} have been performed, even + within the verbatim code block; + \item in \cref{lst:verb1-rv-mod1} indentation has been performed, but that the + replacements have \emph{not} been performed within the verbatim environment, + because the \texttt{rv} switch is active; \item in \cref{lst:verb1-rr-mod1} indentation has \emph{not} been performed, but that replacements have been performed, not respecting the verbatim code block. \end{enumerate} @@ -7135,8 +7557,8 @@ latexindent.pl -rr verb1.tex -l=verbatim1.yaml -o=+-rr-mod1 \cmhlistingsfromfile[style=yaml-LST]{demonstrations/amalg3-yaml.yaml}[replace-TCB]{\texttt{amalg3-yaml.yaml}}{lst:amalg3-yaml} \end{cmhtcbraster} - Upon running the following commands, \index{switches!-l demonstration} \index{switches!-r - demonstration} + Upon running the following commands, \index{switches!-l demonstration} + \index{switches!-r demonstration} \begin{commandshell} latexindent.pl -r amalg1.tex -l=amalg1-yaml @@ -7155,11 +7577,14 @@ latexindent.pl -r amalg1.tex -l=amalg1-yaml,amalg2-yaml,amalg3-yaml \end{cmhtcbraster} We note that: \begin{enumerate} - \item in \cref{lst:amalg1-mod1} the replacements from \cref{lst:amalg1-yaml} have been used; - \item in \cref{lst:amalg1-mod12} the replacements from \cref{lst:amalg1-yaml,lst:amalg2-yaml} - have \emph{both} been used, because the default value of \texttt{amalgamate} is 1; - \item in \cref{lst:amalg1-mod123} \emph{only} the replacements from \cref{lst:amalg3-yaml} have - been used, because the value of \texttt{amalgamate} has been set to 0. + \item in \cref{lst:amalg1-mod1} the replacements from \cref{lst:amalg1-yaml} have been + used; + \item in \cref{lst:amalg1-mod12} the replacements from + \cref{lst:amalg1-yaml,lst:amalg2-yaml} have \emph{both} been used, because the + default value of \texttt{amalgamate} is 1; + \item in \cref{lst:amalg1-mod123} \emph{only} the replacements from + \cref{lst:amalg3-yaml} have been used, because the value of \texttt{amalgamate} + has been set to 0. \end{enumerate} \end{example} % arara: pdflatex: { files: [latexindent]} @@ -7186,8 +7611,8 @@ latexindent.pl -n 3-7 myfile.tex \item line range, as in \texttt{--lines 3-7} \item single line, as in \texttt{--lines 5} \item multiple line ranges separated by commas, as in \texttt{--lines 3-5,8-10} - \item negated line ranges, as in \texttt{--lines !3-5} which translates to \texttt{--lines - 1-2,6-N}, where N is the number of lines in your file. + \item negated line ranges, as in \texttt{--lines !3-5} which translates to + \texttt{--lines 1-2,6-N}, where N is the number of lines in your file. \end{itemize} We demonstrate this feature, and the available variations in what follows. We will use @@ -7218,8 +7643,8 @@ latexindent.pl --lines 7-3 myfile.tex -o=+-mod1 \end{example} \begin{example} - You can call the \texttt{lines} switch with only \emph{one number} and in which case only - that line will be operated upon. For example + You can call the \texttt{lines} switch with only \emph{one number} and in which case + only that line will be operated upon. For example \begin{commandshell} latexindent.pl --lines 5 myfile.tex -o=+-mod2 @@ -7240,9 +7665,9 @@ latexindent.pl --lines 5-5 myfile.tex \end{example} \begin{example} - If you specify a value outside of the line range of the file then \texttt{latexindent.pl} - will ignore the \texttt{lines} argument, detail as such in the log file, and proceed to - operate on the entire file. + If you specify a value outside of the line range of the file then + \texttt{latexindent.pl} will ignore the \texttt{lines} argument, detail as such in the + log file, and proceed to operate on the entire file. For example, in the following call @@ -7325,8 +7750,8 @@ latexindent.pl --lines !5-7 myfile.tex -o=+-mod5 which instructs \texttt{latexindent.pl} to operate upon all of the lines \emph{except} lines 5 to 7. - In other words, \texttt{latexindent.pl} \emph{will} operate on lines 1 to 4, and 8 to 12, - so the following two calls are equivalent: + In other words, \texttt{latexindent.pl} \emph{will} operate on lines 1 to 4, and 8 to + 12, so the following two calls are equivalent: \begin{commandshell} latexindent.pl --lines !5-7 myfile.tex @@ -7360,8 +7785,8 @@ latexindent.pl --lines 1-4,8,11-12 myfile.tex -o=+-mod6 \begin{example} If you specify a line range with anything other than an integer, then - \texttt{latexindent.pl} will ignore the \texttt{lines} argument, and \emph{operate on the - entire file}. + \texttt{latexindent.pl} will ignore the \texttt{lines} argument, and \emph{operate on + the entire file}. Sample calls that result in the \texttt{lines} argument being ignored include the following: @@ -7403,9 +7828,9 @@ latexindent.pl --lines 6 myfile1.tex -o=+-mod1 -m -l env-mlb2,env-mlb7,env-mlb8 \cref{lst:fineTuning}. This field is for those that would like to peek under the bonnet/hood and make some fine - tuning to \texttt{latexindent.pl}'s operating. \index{warning!fine tuning} \index{regular - expressions!fine tuning} \index{regular expressions!environments} \index{regular - expressions!ifElseFi} \index{regular expressions!commands} \index{regular + tuning to \texttt{latexindent.pl}'s operating. \index{warning!fine tuning} + \index{regular expressions!fine tuning} \index{regular expressions!environments} + \index{regular expressions!ifElseFi} \index{regular expressions!commands} \index{regular expressions!keyEqualsValuesBracesBrackets} \index{regular expressions!NamedGroupingBracesBrackets} \index{regular expressions!UnNamedGroupingBracesBrackets} \index{regular expressions!arguments} @@ -7415,22 +7840,22 @@ latexindent.pl --lines 6 myfile1.tex -o=+-mod1 -m -l env-mlb2,env-mlb7,env-mlb8 space \textbackslash{h}} \begin{warning} - Making changes to the fine tuning may have significant consequences for your indentation - scheme, proceed with caution! + Making changes to the fine tuning may have significant consequences for your + indentation scheme, proceed with caution! \end{warning} \begin{widepage} \cmhlistingsfromfile[style=fineTuning]{../defaultSettings.yaml}[width=.95\linewidth,before=\centering,enhanced jigsaw,breakable,yaml-TCB]{\texttt{fineTuning}}{lst:fineTuning} \end{widepage} - The fields given in \cref{lst:fineTuning} are all \emph{regular expressions}. This manual - is not intended to be a tutorial on regular expressions; you might like to read, for - example, \cite{masteringregexp} for a detailed covering of the topic. + The fields given in \cref{lst:fineTuning} are all \emph{regular expressions}. This + manual is not intended to be a tutorial on regular expressions; you might like to read, + for example, \cite{masteringregexp} for a detailed covering of the topic. We make the following comments with reference to \cref{lst:fineTuning}: \begin{enumerate} - \item the \texttt{environments:name} field details that the \emph{name} of an environment can - contain: + \item the \texttt{environments:name} field details that the \emph{name} of an + environment can contain: \begin{enumerate} \item \texttt{a-z} lower case letters \item \texttt{A-Z} upper case letters @@ -7447,9 +7872,10 @@ latexindent.pl --lines 6 myfile1.tex -o=+-mod1 -m -l env-mlb2,env-mlb7,env-mlb8 \item \lstinline^@?^ means that it \emph{can possibly} begin with \lstinline^@^ \item followed by \texttt{if} - \item followed by 0 or more characters from \texttt{a-z}, \texttt{A-Z} and \texttt{@} - \item the \texttt{?} the end means \emph{non-greedy}, which means `stop the match as soon as - possible' + \item followed by 0 or more characters from \texttt{a-z}, \texttt{A-Z} and + \texttt{@} + \item the \texttt{?} the end means \emph{non-greedy}, which means `stop the + match as soon as possible' \end{enumerate} \item the \texttt{keyEqualsValuesBracesBrackets} contains some interesting syntax: \begin{enumerate} @@ -7473,7 +7899,7 @@ latexindent.pl --lines 6 myfile1.tex -o=+-mod1 -m -l env-mlb2,env-mlb7,env-mlb8 \item \texttt{betterFullStop} is in relation to the one sentence per line routine, detailed in \vref{sec:onesentenceperline} \item \texttt{doubleBackSlash} is in relation to the \texttt{DBSStartsOnOwnLine} and - \texttt{DBSFinishesWithLineBreak} polyswitches surrounding double back slashes, see + \texttt{DBSFinishesWithLineBreak} polyswitches surrounding double backslashes, see \vref{subsec:dbs} \item \texttt{comma} is in relation to the \texttt{CommaStartsOnOwnLine} and \texttt{CommaFinishesWithLineBreak} polyswitches surrounding commas in optional and @@ -7487,8 +7913,9 @@ latexindent.pl --lines 6 myfile1.tex -o=+-mod1 -m -l env-mlb2,env-mlb7,env-mlb8 \index{warning!capture groups} \begin{warning} - For the \texttt{fineTuning} feature you should only ever use \emph{non}-capturing groups, - such as \lstinline!(?:...)! and \emph{not} capturing groups, which are \lstinline!(...)! + For the \texttt{fineTuning} feature you should only ever use \emph{non}-capturing + groups, such as \lstinline!(?:...)! and \emph{not} capturing groups, which are + \lstinline!(...)! \end{warning} \begin{example} @@ -7506,9 +7933,9 @@ latexindent.pl finetuning1.tex \cmhlistingsfromfile{demonstrations/finetuning1-default.tex}{\texttt{finetuning1.tex} default}{lst:finetuning1-default} \end{cmhtcbraster} - It's clear from \cref{lst:finetuning1-default} that the indentation scheme has not worked - as expected. We can \emph{fine tune} the indentation scheme by employing the settings - given in \cref{lst:fine-tuning1} and running the command \index{switches!-l + It's clear from \cref{lst:finetuning1-default} that the indentation scheme has not + worked as expected. We can \emph{fine tune} the indentation scheme by employing the + settings given in \cref{lst:fine-tuning1} and running the command \index{switches!-l demonstration} \begin{commandshell} @@ -7541,9 +7968,9 @@ latexindent.pl finetuning2.tex \cmhlistingsfromfile{demonstrations/finetuning2-default.tex}{\texttt{finetuning2.tex} default}{lst:finetuning2-default} \end{cmhtcbraster} - It's clear from \cref{lst:finetuning2-default} that the indentation scheme has not worked - as expected. We can \emph{fine tune} the indentation scheme by employing the settings - given in \cref{lst:fine-tuning2} and running the command \index{switches!-l + It's clear from \cref{lst:finetuning2-default} that the indentation scheme has not + worked as expected. We can \emph{fine tune} the indentation scheme by employing the + settings given in \cref{lst:fine-tuning2} and running the command \index{switches!-l demonstration} \begin{commandshell} @@ -7565,9 +7992,9 @@ latexindent.pl finetuning2.tex -l=fine-tuning2.yaml \end{example} \begin{example} - You can tweak the \texttt{fineTuning} using the \texttt{-y} switch, but to be sure to use - quotes appropriately. For example, starting with the code in \cref{lst:finetuning3} and - running the following command + You can tweak the \texttt{fineTuning} using the \texttt{-y} switch, but to be sure to + use quotes appropriately. For example, starting with the code in \cref{lst:finetuning3} + and running the following command \begin{commandshell} latexindent.pl -m -y='modifyLineBreaks:oneSentencePerLine:manipulateSentences: 1, modifyLineBreaks:oneSentencePerLine:sentencesBeginWith:a-z: 1, fineTuning:modifyLineBreaks:betterFullStop: "(?:\.|;|:(?![a-z]))|(?:(?<!(?:(?:e\.g)|(?:i\.e)|(?:etc))))\.(?!(?:[a-z]|[A-Z]|\-|~|\,|[0-9]))"' issue-243.tex -o=+-mod1 @@ -7624,8 +8051,8 @@ latexindent.pl -m finetuning4.tex -o=+-mod2 -l=href2 \begin{example} Another approach to this situation, which does not use \texttt{fineTuning}, is to use - \texttt{noIndentBlock} which we discussed in \vref{lst:noIndentBlock}; using the settings - in \cref{lst:href3} and running the command + \texttt{noIndentBlock} which we discussed in \vref{lst:noIndentBlock}; using the + settings in \cref{lst:href3} and running the command \begin{commandshell} latexindent.pl -m finetuning4.tex -o=+-mod3 -l=href3 @@ -7679,15 +8106,16 @@ latexindent.pl bib1.bib -l bibsettings1.yaml -o=+-mod2 \end{widepage} Some notes about \cref{lst:bibsettings1}: \begin{itemize} - \item we have populated the \texttt{lookForAlignDelims} field with the \texttt{online} command, - and have used the \texttt{delimiterRegEx}, discussed in \vref{sec:delimiter-reg-ex}; - \item we have tweaked the \texttt{keyEqualsValuesBracesBrackets} code block so that it will - \emph{not} be found following a comma; this means that, in contrast to the default - behaviour, the lines such as \lstinline!date={2013-05-23},! will \emph{not} be treated as - key-equals-value braces; - \item the adjustment to \texttt{keyEqualsValuesBracesBrackets} necessitates the associated - change to the \texttt{UnNamedGroupingBracesBrackets} field so that they will be searched - for following \texttt{=} symbols. + \item we have populated the \texttt{lookForAlignDelims} field with the \texttt{online} + command, and have used the \texttt{delimiterRegEx}, discussed in + \vref{sec:delimiter-reg-ex}; + \item we have tweaked the \texttt{keyEqualsValuesBracesBrackets} code block so that it + will \emph{not} be found following a comma; this means that, in contrast to the + default behaviour, the lines such as \lstinline!date={2013-05-23},! will + \emph{not} be treated as key-equals-value braces; + \item the adjustment to \texttt{keyEqualsValuesBracesBrackets} necessitates the + associated change to the \texttt{UnNamedGroupingBracesBrackets} field so that + they will be searched for following \texttt{=} symbols. \end{itemize} \end{example} @@ -7711,7 +8139,8 @@ latexindent.pl bib2.bib -l bibsettings1.yaml -o=+-mod1 The output in \cref{lst:bib2-mod1} is not ideal, as the \texttt{=} symbol within the url field has been incorrectly used as an alignment delimiter. - We address this by tweaking the \texttt{delimiterRegEx} field in \cref{lst:bibsettings2}. + We address this by tweaking the \texttt{delimiterRegEx} field in + \cref{lst:bibsettings2}. \cmhlistingsfromfile[style=yaml-LST]{demonstrations/bibsettings2.yaml}[yaml-TCB]{\texttt{bibsettings2.yaml}}{lst:bibsettings2} @@ -7734,16 +8163,13 @@ latexindent.pl bib2.bib -l bibsettings1.yaml,bibsettings2.yaml -o=+-mod2 There are a number of known limitations of the script, and almost certainly quite a few that are \emph{unknown}! The known issues include: \begin{description} - \item[multicolumn alignment] when working with code blocks in which multicolumn commands - overlap, the algorithm can fail; see \vref{lst:tabular2-mod2}. - \item[text wrap] routine operates \emph{before} indentation occurs; this means that it is - likely that your final, indented, text wrapped text may exceed the value of - \texttt{columns} that you specify; see \vref{subsec:textwrapping}. - \item[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}); I hope 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. + \item[multicolumn alignment] when working with code blocks in which multicolumn + commands overlap, the algorithm can fail; see \vref{lst:tabular2-mod2}. + \item[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}); I hope + 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. \end{description} You can run \texttt{latexindent} on any file; \announce{2019-07-13}*{ability to call @@ -7797,9 +8223,9 @@ use strict; # | use warnings; # | use Encode; # | use Getopt::Long; # | -use Data::Dumper; # these modules are -use List::Util qw(max); # generally part -use PerlIO::encoding; # of a default perl distribution +use Data::Dumper; # these modules are +use List::Util qw(max); # generally part +use PerlIO::encoding; # of a default perl distribution use open ':std', ':encoding(UTF-8)';# | use Text::Wrap; # | use Text::Tabs; # | @@ -7878,12 +8304,12 @@ sudo apt install texlive-latex-recommended may need the following additional command to work with \texttt{latexindent.pl} \begin{commandshell} -sudo apt install texlive-extra-utils +sudo apt install texlive-extra-utils \end{commandshell} \paragraph{Ubuntu: users without perl} - \texttt{latexindent-linux} is a standalone executable \announce*{2022-10-30}{Linux Ubuntu standalone executable} for Ubuntu Linux (and therefore does not require a Perl distribution) + \texttt{latexindent-linux} is a standalone executable \announce{2022-10-30}{Linux Ubuntu standalone executable} for Ubuntu Linux (and therefore does not require a Perl distribution) and caches copies of the Perl modules onto your system. It is available from \cite{latexindent-home}. \index{latexindent-linux} \index{linux} \index{TeXLive} @@ -7904,10 +8330,10 @@ sudo paru -S perl-file-homedir then run the latexindent-module-installer.pl file located at helper-scripts/ \paragraph{Alpine} - If you are using Alpine, some \texttt{Perl} modules are not build-compatible with Alpine, - but replacements are available through \texttt{apk}. For example, you might use the - commands given in \cref{lst:alpine-install}; thanks to \cite{jun-sheaf} for providing - these details. + If you are using Alpine, some \texttt{Perl} modules are not build-compatible with + Alpine, but replacements are available through \texttt{apk}. For example, you might + use the commands given in \cref{lst:alpine-install}; thanks to \cite{jun-sheaf} for + providing these details. \begin{cmhlistings}[style=tcblatex,language=Bash]{\texttt{alpine-install.sh}}{lst:alpine-install} # Installing perl @@ -7936,8 +8362,8 @@ cpanm -n YAML::Tiny \href{https://github.com/cmhughes/latexindent.pl/issues/222}{https://github.com/cmhughes/latexindent.pl/issues/222} for tips. \subsubsection{Mac} - Users of the Macintosh operating system might like to explore the following commands, for - example: + Users of the Macintosh operating system might like to explore the following commands, + for example: \begin{commandshell} brew install perl @@ -7950,10 +8376,10 @@ cpanm File::HomeDir Alternatively, \begin{commandshell} -brew install latexindent +brew install latexindent \end{commandshell} - \texttt{latexindent-macos} is a standalone executable \announce*{2022-10-30}{macOS standalone executable} for macOS (and therefore does not require a Perl distribution) + \texttt{latexindent-macos} is a standalone executable \announce{2022-10-30}{macOS standalone executable} for macOS (and therefore does not require a Perl distribution) and caches copies of the Perl modules onto your system. It is available from \cite{latexindent-home}. \index{latexindent-macos} \index{macOS} \index{TeXLive} @@ -7990,9 +8416,9 @@ latexindent.pl --GCString myfile.tex cpanm Unicode::GCString \end{commandshell} - Note: this switch does \emph{nothing} for \texttt{latexindent.exe} which loads the module - by default. Users of \texttt{latexindent.exe} should not see any difference in behaviour - whether they use this switch or not, as \texttt{latexindent.exe} loads the + Note: this switch does \emph{nothing} for \texttt{latexindent.exe} which loads the + module by default. Users of \texttt{latexindent.exe} should not see any difference in + behaviour whether they use this switch or not, as \texttt{latexindent.exe} loads the \texttt{Unicode::GCString} module. \section{Updating the path variable}\label{sec:updating-path} @@ -8004,9 +8430,10 @@ cpanm Unicode::GCString 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 + \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 @@ -8045,8 +8472,8 @@ sudo make uninstall \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 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} @@ -8056,18 +8483,20 @@ echo %path% \begin{dosprompt} echo %path% \end{dosprompt} - to check that the appropriate directory has been added to your \lstinline!%path%!. + 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. \section{Batches of files}\label{sec:batches} - You can \announce{2022-03-25}{batches of files details} instruct \texttt{latexindent.pl} - to operate on multiple files. For example, the following calls are all valid + You can \announce{2022-03-25}{batches of files details} instruct + \texttt{latexindent.pl} to operate on multiple files. For example, the following calls + are all valid \begin{commandshell} -latexindent.pl myfile1.tex +latexindent.pl myfile1.tex latexindent.pl myfile1.tex myfile2.tex latexindent.pl myfile*.tex \end{commandshell} @@ -8095,14 +8524,14 @@ latexindent.pl -w myfile*.tex If \texttt{latexindent.pl} is called using the \texttt{-o} switch as in \begin{commandshell} -latexindent.pl myfile*.tex -o=my-output-file.tex +latexindent.pl myfile*.tex -o=my-output-file.tex \end{commandshell} and there are multiple files to operate upon, then the \texttt{-o} switch is ignored because there is only \emph{one} output file specified. - More generally, if the \texttt{-o} switch does \emph{not} have a \texttt{+} symbol at the - beginning, then the \texttt{-o} switch will be ignored, and is turned it off. + More generally, if the \texttt{-o} switch does \emph{not} have a \texttt{+} symbol at + the beginning, then the \texttt{-o} switch will be ignored, and is turned it off. For example @@ -8137,7 +8566,8 @@ latexindent.pl myfile*.tex --check then \begin{itemize} \item exit code 0 means that the text from \emph{none} of the files has been changed; - \item exit code 1 means that the text from \emph{at least one} of the files been file changed. + \item exit code 1 means that the text from \emph{at least one} of the files been file + changed. \end{itemize} The interaction with \texttt{checkv} switch is as in the check switch, but with verbose @@ -8146,17 +8576,17 @@ latexindent.pl myfile*.tex --check \subsection{when a file does not exist} What happens if one of the files can not be operated upon? \begin{itemize} - \item if at least one of the files does not exist and \texttt{latexindent.pl} has been called - to act upon multiple files, then the exit code is 3; note that \texttt{latexindent.pl} - will try to operate on each file that it is called upon, and will not exit with a fatal - message in this case; - \item if at least one of the files can not be read and \texttt{latexindent.pl} has been called - to act upon multiple files, then the exit code is 4; note that \texttt{latexindent.pl} - will try to operate on each file that it is called upon, and will not exit with a fatal - message in this case; - \item if \texttt{latexindent.pl} has been told to operate on multiple files, and some do not - exist and some cannot be read, then the exit code will be either 3 or 4, depending upon - which it scenario it encountered most recently. + \item if at least one of the files does not exist and \texttt{latexindent.pl} has been + called to act upon multiple files, then the exit code is 3; note that + \texttt{latexindent.pl} will try to operate on each file that it is called upon, + and will not exit with a fatal message in this case; + \item if at least one of the files can not be read and \texttt{latexindent.pl} has + been called to act upon multiple files, then the exit code is 4; note that + \texttt{latexindent.pl} will try to operate on each file that it is called upon, + and will not exit with a fatal message in this case; + \item if \texttt{latexindent.pl} has been told to operate on multiple files, and some + do not exist and some cannot be read, then the exit code will be either 3 or 4, + depending upon which it scenario it encountered most recently. \end{itemize} \section{latexindent-yaml-schema.json} @@ -8171,25 +8601,25 @@ latexindent.pl myfile*.tex --check To use \texttt{latexindent-yaml-schema.json} with \texttt{VSCode}, you can use the following steps: \index{VSCode} \index{json!VSCode} \begin{enumerate} - \item download \texttt{latexindent-yaml-schema.json} from the \texttt{documentation} folder of - \cite{latexindent-home}, save it in whichever directory you would like, noting it for - reference; - \item following the instructions from \cite{vscode-yaml-demo}, for example, you should install - the VSCode YAML extension \cite{vscode-yaml-extentions}; - \item set up your \texttt{settings.json} file using the directory you saved the file by - adapting \cref{lst:settings.json}; on my Ubuntu laptop this file lives at + \item download \texttt{latexindent-yaml-schema.json} from the \texttt{documentation} + folder of \cite{latexindent-home}, save it in whichever directory you would + like, noting it for reference; + \item following the instructions from \cite{vscode-yaml-demo}, for example, you should + install the VSCode YAML extension \cite{vscode-yaml-extentions}; + \item set up your \texttt{settings.json} file using the directory you saved the file + by adapting \cref{lst:settings.json}; on my Ubuntu laptop this file lives at \texttt{/home/cmhughes/.config/Code/User/settings.json}. \end{enumerate} \begin{widepage} - \cmhlistingsfromfile{demonstrations/settings.json}[yaml-TCB]{\texttt{settings.json}}{lst:settings.json} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/settings.json}[yaml-TCB]{\texttt{settings.json}}{lst:settings.json} \end{widepage} Alternatively, if you would prefer not to download the json file, you might be able to use an adapted version of \cref{lst:settings-alt.json}. \begin{widepage} - \cmhlistingsfromfile{demonstrations/settings-alt.json}[yaml-TCB]{\texttt{settings-alt.json}}{lst:settings-alt.json} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/settings-alt.json}[yaml-TCB]{\texttt{settings-alt.json}}{lst:settings-alt.json} \end{widepage} Finally, if your TeX distribution is up to date, then @@ -8197,7 +8627,7 @@ latexindent.pl myfile*.tex --check your installation, so an adapted version of \cref{lst:settings-alt1.json} may work. \begin{widepage} - \cmhlistingsfromfile{demonstrations/settings-alt1.json}[yaml-TCB]{\texttt{settings-alt1.json}}{lst:settings-alt1.json} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/settings-alt1.json}[yaml-TCB]{\texttt{settings-alt1.json}}{lst:settings-alt1.json} \end{widepage} If you have details of how to implement this schema in other editors, please feel @@ -8211,8 +8641,8 @@ conda install latexindent.pl -c conda-forge \end{commandshell} This will install the executable and all its dependencies (including perl) in the - activate environment. You don't even have to worry about \texttt{defaultSettings.yaml} as - it included too, you can thus skip \cref{sec:requiredmodules,sec:updating-path}. + activate environment. You don't even have to worry about \texttt{defaultSettings.yaml} + as it included too, you can thus skip \cref{sec:requiredmodules,sec:updating-path}. \index{conda} You can get a conda installation for example from \cite{conda} or from \cite{anacoda}. @@ -8240,14 +8670,14 @@ docker pull ghcr.io/cmhughes/latexindent.pl \end{commandshell} This will download the image packed \texttt{latexindent}'s executable and its all - dependencies. \index{docker} Thank you to \cite{eggplants} for contributing this feature; - see also \cite{cmhughesio}. For reference, \emph{ghcr} stands for \emph{GitHub Container - Repository}. + dependencies. \index{docker} Thank you to \cite{eggplants} for contributing this + feature; see also \cite{cmhughesio}. For reference, \emph{ghcr} stands for \emph{GitHub + Container Repository}. \subsection{Sample docker installation on Ubuntu} To pull the image and show \texttt{latexindent}'s help on Ubuntu: - \begin{cmhlistings}*[style=tcblatex,language=Bash]{\texttt{docker-install.sh}}{lst:docker-install} + \begin{cmhlistings}[style=tcblatex,language=Bash]{\texttt{docker-install.sh}}{lst:docker-install} # setup docker if not already installed if ! command -v docker &> /dev/null; then sudo apt install docker.io -y @@ -8271,14 +8701,16 @@ docker run -v /path/to/local/myfile.tex:/myfile.tex ghcr.io/cmhughes/latexindent \section{pre-commit} Users of \texttt{.git} may be interested \announce{2022-01-21}{pre-commit for - latexindent.pl} in exploring the \texttt{pre-commit} tool \cite{pre-commithome}, which is - supported by \texttt{latexindent.pl}. Thank you to \cite{tdegeusprecommit} for - contributing this feature, and to \cite{holzhausprecommit} for their contribution to it. + latexindent.pl} in exploring the \texttt{pre-commit} tool \cite{pre-commithome}, which + is supported by \texttt{latexindent.pl}. Thank you to \cite{tdegeusprecommit} for + contributing this feature, and to \cite{holzhausprecommit} for their contribution to + it. - To use the \texttt{pre-commit} tool, you will need to install \texttt{pre-commit}; sample - instructions for Ubuntu are given in \cref{sec:pre-commit-ubuntu}. Once installed, there - are two ways to use \texttt{pre-commit}: using \texttt{CPAN} or using \texttt{conda}, - detailed in \cref{sec:pre-commit-cpan} and \cref{sec:pre-commit-conda} respectively. + To use the \texttt{pre-commit} tool, you will need to install \texttt{pre-commit}; + sample instructions for Ubuntu are given in \cref{sec:pre-commit-ubuntu}. Once + installed, there are two ways to use \texttt{pre-commit}: using \texttt{CPAN} or using + \texttt{conda}, detailed in \cref{sec:pre-commit-cpan} and \cref{sec:pre-commit-conda} + respectively. \subsection{Sample pre-commit installation on Ubuntu}\label{sec:pre-commit-ubuntu} On Ubuntu I ran the following command: @@ -8298,7 +8730,7 @@ export PATH=$PATH:/home/cmhughes/.local/bin The default values that are employed by \texttt{pre-commit} are shown in \cref{lst:.pre-commit-yaml-default}. \index{pre-commit!default} - \cmhlistingsfromfile{../.pre-commit-hooks.yaml}[yaml-TCB]{\texttt{.pre-commit-hooks.yaml} (default)}{lst:.pre-commit-yaml-default} + \cmhlistingsfromfile[style=yaml-LST]{../.pre-commit-hooks.yaml}[yaml-TCB]{\texttt{.pre-commit-hooks.yaml} (default)}{lst:.pre-commit-yaml-default} In particular, the decision has deliberately been made (in collaboration with \cite{holzhausprecommit}) to have the default to employ the following switches: @@ -8316,31 +8748,33 @@ export PATH=$PATH:/home/cmhughes/.local/bin \subsection{pre-commit using CPAN}\label{sec:pre-commit-cpan} To use \texttt{latexindent.pl} with \texttt{pre-commit}, create the file - \texttt{.pre-commit-config.yaml} given in \cref{lst:.pre-commit-config.yaml-cpan} in your - git-repository. \index{cpan} \index{git} \index{pre-commit!cpan} + \texttt{.pre-commit-config.yaml} given in \cref{lst:.pre-commit-config.yaml-cpan} in + your git-repository. \index{cpan} \index{git} \index{pre-commit!cpan} - \cmhlistingsfromfile{demonstrations/pre-commit-config-cpan.yaml}[yaml-TCB]{\texttt{.pre-commit-config.yaml} (cpan)}{lst:.pre-commit-config.yaml-cpan} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/pre-commit-config-cpan.yaml}[yaml-TCB]{\texttt{.pre-commit-config.yaml} (cpan)}{lst:.pre-commit-config.yaml-cpan} Once created, you should then be able to run the following command: \begin{commandshell} -pre-commit run --all-files +pre-commit run --all-files \end{commandshell} A few notes about \cref{lst:.pre-commit-config.yaml-cpan}: \begin{itemize} \item the settings given in \cref{lst:.pre-commit-config.yaml-cpan} instruct \texttt{pre-commit} to use \texttt{CPAN} to get dependencies; - \item this requires \texttt{pre-commit} and \texttt{perl} to be installed on your system; + \item this requires \texttt{pre-commit} and \texttt{perl} to be installed on your + system; \item the \texttt{args} lists selected command-line options; the settings in \cref{lst:.pre-commit-config.yaml-cpan} are equivalent to calling \begin{commandshell} -latexindent.pl -s myfile.tex +latexindent.pl -s myfile.tex \end{commandshell} for each \texttt{.tex} file in your repository; - \item to instruct \texttt{latexindent.pl} to overwrite the files in your repository, then you - can update \cref{lst:.pre-commit-config.yaml-cpan} so that \texttt{args: [-s, -w]}. + \item to instruct \texttt{latexindent.pl} to overwrite the files in your repository, + then you can update \cref{lst:.pre-commit-config.yaml-cpan} so that + \texttt{args: [-s, -w]}. \end{itemize} Naturally you can add options, or omit \texttt{-s} and \texttt{-w}, according to your @@ -8352,28 +8786,30 @@ latexindent.pl -s myfile.tex \texttt{CPAN} for all dependencies, including \texttt{latexindent.pl} itself. \index{conda} \index{git} \index{pre-commit!conda} - \cmhlistingsfromfile{demonstrations/pre-commit-config-conda.yaml}[yaml-TCB]{\texttt{.pre-commit-config.yaml} (conda)}{lst:.pre-commit-config.yaml-conda} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/pre-commit-config-conda.yaml}[yaml-TCB]{\texttt{.pre-commit-config.yaml} (conda)}{lst:.pre-commit-config.yaml-conda} Once created, you should then be able to run the following command: \begin{commandshell} -pre-commit run --all-files +pre-commit run --all-files \end{commandshell} A few notes about \cref{lst:.pre-commit-config.yaml-cpan}: \begin{itemize} \item the settings given in \cref{lst:.pre-commit-config.yaml-conda} instruct \texttt{pre-commit} to use \texttt{conda} to get dependencies; - \item this requires \texttt{pre-commit} and \texttt{conda} to be installed on your system; + \item this requires \texttt{pre-commit} and \texttt{conda} to be installed on your + system; \item the \texttt{args} lists selected command-line options; the settings in \cref{lst:.pre-commit-config.yaml-cpan} are equivalent to calling \begin{commandshell} -conda run latexindent.pl -s myfile.tex +conda run latexindent.pl -s myfile.tex \end{commandshell} for each \texttt{.tex} file in your repository; - \item to instruct \texttt{latexindent.pl} to overwrite the files in your repository, then you - can update \cref{lst:.pre-commit-config.yaml-cpan} so that \texttt{args: [-s, -w]}. + \item to instruct \texttt{latexindent.pl} to overwrite the files in your repository, + then you can update \cref{lst:.pre-commit-config.yaml-cpan} so that + \texttt{args: [-s, -w]}. \end{itemize} \subsection{pre-commit using docker}\label{sec:pre-commit-docker} @@ -8382,7 +8818,7 @@ conda run latexindent.pl -s myfile.tex \texttt{CPAN} for all dependencies, including \texttt{latexindent.pl} itself. \index{docker} \index{git} \index{pre-commit!docker} - \cmhlistingsfromfile{demonstrations/pre-commit-config-docker.yaml}[yaml-TCB]{\texttt{.pre-commit-config.yaml} (docker)}{lst:.pre-commit-config.yaml-docker} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/pre-commit-config-docker.yaml}[yaml-TCB]{\texttt{.pre-commit-config.yaml} (docker)}{lst:.pre-commit-config.yaml-docker} Once created, you should then be able to run the following command: \begin{commandshell} @@ -8393,7 +8829,8 @@ pre-commit run --all-files \begin{itemize} \item the settings given in \cref{lst:.pre-commit-config.yaml-docker} instruct \texttt{pre-commit} to use \texttt{docker} to get dependencies; - \item this requires \texttt{pre-commit} and \texttt{docker} to be installed on your system; + \item this requires \texttt{pre-commit} and \texttt{docker} to be installed on your + system; \item the \texttt{args} lists selected command-line options; the settings in \cref{lst:.pre-commit-config.yaml-cpan} are equivalent to calling @@ -8402,8 +8839,9 @@ docker run -v /path/to/myfile.tex:/myfile.tex ghcr.io/cmhughes/latexindent.pl -s \end{commandshell} for each \texttt{.tex} file in your repository; - \item to instruct \texttt{latexindent.pl} to overwrite the files in your repository, then you - can update \cref{lst:.pre-commit-config.yaml-cpan} so that \texttt{args: [-s, -w]}. + \item to instruct \texttt{latexindent.pl} to overwrite the files in your repository, + then you can update \cref{lst:.pre-commit-config.yaml-cpan} so that + \texttt{args: [-s, -w]}. \end{itemize} \subsection{pre-commit example using -l, -m switches} @@ -8422,11 +8860,11 @@ modifyLineBreaks: and \texttt{.pre-commit-config.yaml} as in \cref{lst:.latexindent.yaml-switches}: - \cmhlistingsfromfile{demonstrations/pre-commit-config-demo.yaml}[yaml-TCB]{\texttt{.pre-commit-config.yaml} (demo)}{lst:.latexindent.yaml-switches} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/pre-commit-config-demo.yaml}[yaml-TCB]{\texttt{.pre-commit-config.yaml} (demo)}{lst:.latexindent.yaml-switches} Now running \begin{commandshell} -pre-commit run --all-files +pre-commit run --all-files \end{commandshell} is equivalent to running @@ -8439,14 +8877,137 @@ latexindent.pl -l -m -s -w myfile.tex A few notes about \cref{lst:.latexindent.yaml-switches}: \begin{itemize} - \item the \texttt{-l} option was added to use the local \texttt{.latexindent.yaml} (where it - was specified to only create one back-up file, as \texttt{git} typically takes care of - this when you use \texttt{pre-commit}); + \item the \texttt{-l} option was added to use the local \texttt{.latexindent.yaml} + (where it was specified to only create one back-up file, as \texttt{git} + typically takes care of this when you use \texttt{pre-commit}); \item \texttt{-m} to modify line breaks; in addition to \texttt{-s} to suppress command-line output, and \texttt{-w} to format files in place. \end{itemize} \end{example} + \section{indentconfig options}\label{app:indentconfig:options} + This section describes the possible locations for the main configuration file, + discussed in \cref{sec:indentconfig}. Thank you to \cite{nehctargl} for this + contribution. \announce*{2023-01-01}{indentconfig location options} + + The possible locations of \texttt{indentconfig.yaml} are evaluated one after the other, + and evaluation stops when a valid file is found in one of the paths. + + Before stating the list, we give summarise in \cref{tab:environment:summary}. + \begin{table}[!htb] + \centering + \caption{indentconfig environment variable summaries} + \label{tab:environment:summary} + \begin{tabular}{lllll} + \toprule + environment variable & type & Linux & macOS & Windows \\ + \midrule + LATEXINDENT\_CONFIG & full path to file & \faCheck & \faCheck & \faCheck \\ + XDG\_CONFIG\_HOME & directory path & \faCheck & \faClose & \faClose \\ + LOCALAPPDATA & directory path & \faClose & \faClose & \faCheck \\ + \bottomrule + \end{tabular} + \end{table} + + The following list shows the checked options and is sorted by their respective + priority. It uses capitalized and with a dollar symbol prefixed names (e.g. + \texttt{\$LATEXINDENT\_CONFIG}) to symbolize environment variables. In addition to that + the variable name \texttt{\$homeDir} is used to symbolize your home directory. + + \begin{enumerate} + \item The value of the environment variable \texttt{\$LATEXINDENT\_CONFIG} is treated + as highest priority source for the path to the configuration file. + \item The next options are dependent on your operating system: + \begin{itemize} + \item Linux: + \begin{enumerate} + \item The file at + \texttt{\$XDG\_CONFIG\_HOME/latexindent/indentconfig.yaml} + \item The file at + \texttt{\$homeDir/.config/latexindent/indentconfig.yaml} + \end{enumerate} + \item Windows: + \begin{enumerate} + \item The file at + \texttt{\$LOCALAPPDATA\textbackslash{}latexindent\textbackslash{}indentconfig.yaml} + \item The file at + \texttt{\$homeDir\textbackslash{}AppData\textbackslash{}Local\textbackslash{}latexindent\textbackslash{}indentconfig.yaml} + \end{enumerate} + \item Mac: + \begin{enumerate} + \item The file at + \texttt{\$homeDir/Library/Preferences/latexindent/indentconfig.yaml} + \end{enumerate} + \end{itemize} + \item The file at \texttt{\$homeDir/.indentconfig.yaml} + \item The file at \texttt{\$homeDir/indentconfig.yaml} + \end{enumerate} + \subsection{Why to change the configuration location} + This is mostly a question about what you prefer, some like to put all their configuration files in their home directory (see \texttt{\$homeDir} above), + whilst some like to sort their configuration. And if you don't care about it, you can just continue using the same defaults. + \subsection{How to change the configuration location} + This depends on your preferred location, if, for example, you would like to set a custom location, you would have to change the \texttt{\$LATEXINDENT\_CONFIG} environment variable. + + Although the following example only covers \texttt{\$LATEXINDENT\_CONFIG}, the same + process can be applied to \texttt{\$XDG\_CONFIG\_HOME} or \texttt{\$LOCALAPPDATA} + because both are environment variables. You just have to change the path to your chosen + configuration directory (e.g. \texttt{\$homeDir/.config} or + \texttt{\$homeDir\textbackslash{}AppData\textbackslash{}Local} on Linux or Windows + respectively) + \subsubsection{Linux} + To change \texttt{\$LATEXINDENT\_CONFIG} on Linux you can run the following command in + a terminal after changing the path: + \begin{widepage} + + \begin{commandshell} +echo 'export LATEXINDENT_CONFIG="/home/cmh/latexindent-config.yaml"' >> ~/.profile + \end{commandshell} + + \end{widepage} + Context: This command adds the given line to your \texttt{.profile} file (which is + commonly stored in \texttt{\$HOME/.profile}). All commands in this file a run after + login, so the environment variable will be set after your next login. + + You can check the value of \texttt{\$LATEXINDENT\_CONFIG} by typing + + \begin{commandshell} +echo $LATEXINDENT_CONFIG +/home/cmh/latexindent-config.yaml + \end{commandshell} + + Linux users interested in \texttt{\$XDG\_CONFIG\_HOME} can explore variations of the + following commands + + \begin{commandshell} +echo $XDG_CONFIG_HOME +echo ${XDG_CONFIG_HOME:=$HOME/.config} +echo $XDG_CONFIG_HOME +mkdir /home/cmh/.config/latexindent +touch /home/cmh/.config/latexindent/indentconfig.yaml + \end{commandshell} + + \subsubsection{Windows} + To change \texttt{\$LATEXINDENT\_CONFIG} on Windows you can run the following command + in \texttt{powershell.exe} after changing the path: + \begin{widepage} + \begin{dosprompt} +[Environment]::SetEnvironmentVariable + ("LATEXINDENT_CONFIG", "\your\config\path", "User") + \end{dosprompt} + \end{widepage} + This sets the environment variable for every user session. + \subsubsection{Mac} + To change \texttt{\$LATEXINDENT\_CONFIG} on macOS you can run the following command in + a terminal after changing the path: + + \begin{commandshell} +echo 'export LATEXINDENT_CONFIG="/your/config/path"' >> ~/.profile + \end{commandshell} + + Context: This command adds the line to your \texttt{.profile} file (which is commonly + stored in \texttt{\$HOME/.profile}). All commands in this file a run after login, so + the environment variable will be set after your next login. + \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. @@ -8460,13 +9021,13 @@ latexindent.pl -l -m -s -w myfile.tex \end{minipage} \hfill \begin{minipage}{.6\linewidth} - \cmhlistingsfromfile{demonstrations/logfile-prefs1.yaml}[yaml-TCB]{\texttt{logfile-prefs1.yaml}}{lst:logfile-prefs1-yaml} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/logfile-prefs1.yaml}[yaml-TCB]{\texttt{logfile-prefs1.yaml}}{lst:logfile-prefs1-yaml} \end{minipage} If we run the following command (noting that \texttt{-t} is active) \begin{commandshell} -latexindent.pl -t -l=logfile-prefs1.yaml simple.tex +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 @@ -8492,8 +9053,8 @@ TRACE: Searching myenv for optional and mandatory arguments \end{example} \section{Encoding indentconfig.yaml}\label{app:encoding} - In relation to \vref{sec:indentconfig}, Windows users that encounter encoding issues with - \texttt{indentconfig.yaml}, may wish to run the following command in either + In relation to \vref{sec:indentconfig}, Windows users that encounter encoding issues + with \texttt{indentconfig.yaml}, may wish to run the following command in either \texttt{cmd.exe} or \texttt{powershell.exe}: \begin{dosprompt} chcp @@ -8505,7 +9066,7 @@ Active code page: 936 and can then use the settings given in \cref{lst:indentconfig-encoding1} within their \texttt{indentconfig.yaml}, where 936 is the result of the \texttt{chcp} command. - \cmhlistingsfromfile{demonstrations/encoding1.yaml}[yaml-TCB]{\texttt{encoding} demonstration for \texttt{indentconfig.yaml}}{lst:indentconfig-encoding1} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/encoding1.yaml}[yaml-TCB]{\texttt{encoding} demonstration for \texttt{indentconfig.yaml}}{lst:indentconfig-encoding1} \section{dos2unix linebreak adjustment} @@ -8525,8 +9086,8 @@ latexindent.pl -y="dos2unixlinebreaks:1" myfile.tex \section{Differences from Version 2.2 to 3.0}\label{app:differences} There are a few (small) changes to the interface when comparing Version 2.2 to Version - 3.0. Explicitly, in previous versions you might have run, for example, \index{switches!-o - demonstration} + 3.0. Explicitly, in previous versions you might have run, for example, + \index{switches!-o demonstration} \begin{commandshell} latexindent.pl -o myfile.tex outputfile.tex @@ -8538,43 +9099,44 @@ latexindent.pl -o myfile.tex outputfile.tex \begin{commandshell} latexindent.pl -o=outputfile.tex myfile.tex latexindent.pl -o outputfile.tex myfile.tex -latexindent.pl myfile.tex -o outputfile.tex -latexindent.pl myfile.tex -o=outputfile.tex -latexindent.pl myfile.tex -outputfile=outputfile.tex -latexindent.pl myfile.tex -outputfile outputfile.tex +latexindent.pl myfile.tex -o outputfile.tex +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. - 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} + The fields given in \cref{lst:obsoleteYaml} are \emph{obsolete} from Version 3.0 + onwards. + \cmhlistingsfromfile[style=yaml-LST]{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 + 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} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/indentAfterThisHeadingOld.yaml}[yaml-TCB]{\texttt{indentAfterThisHeading} in Version 2.2}{lst:indentAfterThisHeadingOld} \end{minipage}% \hfill \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile{demonstrations/indentAfterThisHeadingNew.yaml}[yaml-TCB]{\texttt{indentAfterThisHeading} in Version 3.0}{lst:indentAfterThisHeadingNew} + \cmhlistingsfromfile[style=yaml-LST]{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}. \index{specialBeginEnd!update to - displaymath V3.0} + 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}. + \index{specialBeginEnd!update to displaymath V3.0} \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile{demonstrations/noAddtionalIndentOld.yaml}[yaml-TCB]{\texttt{noAdditionalIndent} in Version 2.2}{lst:noAdditionalIndentOld} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/noAddtionalIndentOld.yaml}[yaml-TCB]{\texttt{noAdditionalIndent} in Version 2.2}{lst:noAdditionalIndentOld} \end{minipage}% \hfill \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile{demonstrations/noAddtionalIndentNew.yaml}[yaml-TCB]{\texttt{noAdditionalIndent} for \texttt{displayMath} in Version 3.0}{lst:indentAfterThisHeadingNew1} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/noAddtionalIndentNew.yaml}[yaml-TCB]{\texttt{noAdditionalIndent} for \texttt{displayMath} in Version 3.0}{lst:indentAfterThisHeadingNew1} - \cmhlistingsfromfile{demonstrations/noAddtionalIndentNew1.yaml}[yaml-TCB]{\texttt{noAdditionalIndent} for \texttt{displayMath} in Version 3.0}{lst:indentAfterThisHeadingNew2} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/noAddtionalIndentNew1.yaml}[yaml-TCB]{\texttt{noAdditionalIndent} for \texttt{displayMath} in Version 3.0}{lst:indentAfterThisHeadingNew2} \end{minipage}% \mbox{}\hfill |