texlive[65427] trunk: latexindent (1jan23)
commits+karl at tug.org
commits+karl at tug.org
Sun Jan 1 21:33:08 CET 2023
Revision: 65427
http://tug.org/svn/texlive?view=revision&revision=65427
Author: karl
Date: 2023-01-01 21:33:08 +0100 (Sun, 01 Jan 2023)
Log Message:
-----------
latexindent (1jan23)
Modified Paths:
--------------
trunk/Build/source/texk/texlive/linked_scripts/latexindent/latexindent.pl
trunk/Master/bin/win32/latexindent.exe
trunk/Master/texmf-dist/doc/support/latexindent/README
trunk/Master/texmf-dist/doc/support/latexindent/contributors.bib
trunk/Master/texmf-dist/doc/support/latexindent/latexindent-yaml-schema.json
trunk/Master/texmf-dist/doc/support/latexindent/latexindent.pdf
trunk/Master/texmf-dist/doc/support/latexindent/latexindent.tex
trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Document.pm
trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/GetYamlSettings.pm
trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Sentence.pm
trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/TrailingComments.pm
trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Version.pm
trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Wrap.pm
trunk/Master/texmf-dist/scripts/latexindent/defaultSettings.yaml
trunk/Master/texmf-dist/scripts/latexindent/latexindent.pl
Modified: trunk/Build/source/texk/texlive/linked_scripts/latexindent/latexindent.pl
===================================================================
(Binary files differ)
Modified: trunk/Master/bin/win32/latexindent.exe
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/support/latexindent/README
===================================================================
--- trunk/Master/texmf-dist/doc/support/latexindent/README 2023-01-01 20:32:34 UTC (rev 65426)
+++ trunk/Master/texmf-dist/doc/support/latexindent/README 2023-01-01 20:33:08 UTC (rev 65427)
@@ -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.
Modified: trunk/Master/texmf-dist/doc/support/latexindent/contributors.bib
===================================================================
--- trunk/Master/texmf-dist/doc/support/latexindent/contributors.bib 2023-01-01 20:32:34 UTC (rev 65426)
+++ trunk/Master/texmf-dist/doc/support/latexindent/contributors.bib 2023-01-01 20:33:08 UTC (rev 65427)
@@ -174,3 +174,11 @@
author = "eggplants",
urldate = {2022-06-12},
keywords = {contributor},}
+
+ at 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},}
Modified: trunk/Master/texmf-dist/doc/support/latexindent/latexindent-yaml-schema.json
===================================================================
--- trunk/Master/texmf-dist/doc/support/latexindent/latexindent-yaml-schema.json 2023-01-01 20:32:34 UTC (rev 65426)
+++ trunk/Master/texmf-dist/doc/support/latexindent/latexindent-yaml-schema.json 2023-01-01 20:33:08 UTC (rev 65427)
@@ -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": {
Modified: trunk/Master/texmf-dist/doc/support/latexindent/latexindent.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/support/latexindent/latexindent.tex
===================================================================
--- trunk/Master/texmf-dist/doc/support/latexindent/latexindent.tex 2023-01-01 20:32:34 UTC (rev 65426)
+++ trunk/Master/texmf-dist/doc/support/latexindent/latexindent.tex 2023-01-01 20:33:08 UTC (rev 65427)
@@ -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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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,9 +1111,9 @@
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
@@ -1072,12 +1120,12 @@
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 @@
\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 @@
\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 --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 @@
\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
\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.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 @@
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 @@
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=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 @@
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 @@
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 @@
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 @@
\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 @@
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 -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 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,11 +1787,15 @@
\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
\texttt{indentconfig.yaml}
@@ -1754,27 +1809,14 @@
\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.
+ 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
+ \cmhlistingsfromfile[style=yaml-LST]{demonstrations/indent-config.yaml}[yaml-TCB]{\texttt{indentconfig.yaml} (sample)}{lst:indentconfig}
-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}
-
Note that the \texttt{.yaml} files you specify in \texttt{indentconfig.yaml} will be
loaded in the order in which you write them. Each file doesn't have to have every switch
from \texttt{defaultSettings.yaml}; in fact, I recommend that you only keep the switches
@@ -1783,28 +1825,21 @@
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"
+ \cmhlistingsfromfile[style=yaml-LST]{demonstrations/tabbing.yaml}[yaml-TCB]{\texttt{mysettings.yaml} (example)}{lst:mysettings}
-# environments that have tab delimiters, add more
-# as needed
-lookForAlignDelims:
- tabbing: 1
-\end{yaml}
-
You can make sure that your settings are loaded by checking \texttt{indent.log} for
details -- if you have specified a path that \texttt{latexindent.pl} doesn't 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 @@
\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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
\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 @@
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 @@
\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 @@
\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 @@
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 @@
\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 @@
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 @@
\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 @@
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 @@
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,30 +2273,30 @@
\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}
@@ -2264,10 +2303,10 @@
\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 @@
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 @@
\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 @@
\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 @@
\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,10 +2382,16 @@
\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}
\cmhlistingsfromfile{demonstrations/tabular1-default.tex}{\texttt{tabular1.tex} default output}{lst:tabularafter:basic}
@@ -2383,37 +2429,38 @@
\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
+ 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}{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:
+ \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 @@
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 @@
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 @@
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 @@
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,8 +2655,8 @@
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,
@@ -2612,7 +2663,7 @@
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 @@
\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 @@
\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 @@
\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 @@
\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 @@
\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 @@
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 @@
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 @@
\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 @@
\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 @@
\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 @@
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,7 +2951,7 @@
\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}
@@ -2905,10 +2958,10 @@
\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 @@
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 @@
\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 @@
\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 @@
\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 @@
\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,8 +3079,14 @@
\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}
\cmhlistingsfromfile{demonstrations/special1-default.tex}{\texttt{special1.tex} default output}{lst:specialafter}
@@ -3107,24 +3166,25 @@
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 @@
\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,18 +3228,19 @@
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
@@ -3185,12 +3247,12 @@
\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 @@
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 @@
\texttt{headings1.tex}.
\begin{cmhtcbraster}
+ \cmhlistingsfromfile{demonstrations/headings1.tex}{\texttt{headings1.tex}}{lst:headings1}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/headings1.yaml}[yaml-TCB]{\texttt{headings1.yaml}}{lst:headings1yaml}
- \cmhlistingsfromfile{demonstrations/headings1.tex}{\texttt{headings1.tex}}{lst:headings1}
\end{cmhtcbraster}
If you run the command \index{switches!-l demonstration}
@@ -3289,13 +3351,13 @@
You should receive the output shown in \cref{lst:mult-nested-max-ind1}.
\begin{cmhtcbraster}
+ \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}
- \cmhlistingsfromfile[showspaces=true]{demonstrations/mult-nested-max-ind1.tex}{\texttt{mult-nested.tex} using \cref{lst:max-indentation1yaml}}{lst:mult-nested-max-ind1}
\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 @@
\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 @@
\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 @@
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 @@
\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 @@
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 @@
\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 @@
\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-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 @@
% 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 @@
\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 @@
\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 @@
\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 @@
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 @@
\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 @@
\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 @@
% 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 @@
\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 @@
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 @@
\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 @@
\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 @@
\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 @@
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 @@
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 @@
\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 @@
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 @@
\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 @@
\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 @@
\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 @@
\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,9 +4699,12 @@
\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}
@@ -4638,22 +4711,28 @@
\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 @@
\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 @@
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 @@
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 @@
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 @@
\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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
\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 @@
\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 @@
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 @@
% 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 @@
\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 @@
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 @@
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 @@
\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 @@
\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 @@
\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 @@
\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 @@
\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 @@
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 @@
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 @@
\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,11 +6066,12 @@
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}
@@ -5719,8 +6078,8 @@
\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}
@@ -5727,9 +6086,15 @@
\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}
\cmhlistingsfromfile{demonstrations/env-mlb-mod3.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb3}}{lst:env-mlb-mod3}
@@ -5740,9 +6105,9 @@
\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,9 +6121,15 @@
\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}
\cmhlistingsfromfile{demonstrations/env-mlb-mod5.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb5}}{lst:env-mlb-mod5}
@@ -5769,8 +6140,8 @@
\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 @@
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,10 +6177,11 @@
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}
@@ -5817,8 +6188,8 @@
\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 @@
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,9 +6237,15 @@
\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}
\cmhlistingsfromfile{demonstrations/env-mlb-mod9.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb9}}{lst:env-mlb-mod9}
@@ -5879,16 +6256,17 @@
\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}
@@ -5895,9 +6273,15 @@
\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}
\cmhlistingsfromfile{demonstrations/env-mlb-mod11.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb11}}{lst:env-mlb-mod11}
@@ -5908,14 +6292,14 @@
\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 @@
\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 @@
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 @@
\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 @@
\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 @@
\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 @@
\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 @@
\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 @@
\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 @@
\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 @@
\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 @@
\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 @@
\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 @@
\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 @@
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 @@
\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 @@
\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,9 +6920,15 @@
\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,
raster column 1/.style={add to width=-1cm},
@@ -6544,8 +6940,14 @@
\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,
raster column 1/.style={add to width=-1cm},
@@ -6560,8 +6962,8 @@
\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 @@
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,28 +7001,37 @@
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}
@@ -6627,8 +7038,8 @@
\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,22 +7072,23 @@
\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}
@@ -6683,18 +7095,20 @@
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 @@
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 @@
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 @@
\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 @@
\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 @@
\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 @@
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 @@
\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 @@
\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 @@
\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 @@
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 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,9 +7497,9 @@
\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}
@@ -7085,9 +7506,10 @@
\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 @@
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 @@
\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 @@
\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 @@
\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 @@
\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 @@
\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 @@
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 @@
\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 @@
\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,8 +7840,8 @@
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}
@@ -7423,14 +7848,14 @@
\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 @@
\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 @@
\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 @@
\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 @@
\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 @@
\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 @@
\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 @@
\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 @@
\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 @@
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 @@
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 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 @@
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 @@
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 @@
\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 @@
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 @@
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 @@
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 @@
\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,7 +8483,8 @@
\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.
@@ -8063,11 +8491,12 @@
\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 @@
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 @@
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 @@
\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,18 +8601,18 @@
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
@@ -8189,7 +8619,7 @@
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 @@
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 @@
\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 @@
\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 @@
\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 @@
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,14 +8748,14 @@
\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}:
@@ -8330,17 +8762,19 @@
\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,11 +8786,11 @@
\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}:
@@ -8363,17 +8797,19 @@
\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 @@
\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 @@
\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 @@
\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 @@
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 @@
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 @@
\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 @@
\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 @@
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 @@
\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 @@
\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
Modified: trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Document.pm
===================================================================
--- trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Document.pm 2023-01-01 20:32:34 UTC (rev 65426)
+++ trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Document.pm 2023-01-01 20:33:08 UTC (rev 65427)
@@ -37,7 +37,7 @@
use LatexIndent::ModifyLineBreaks
qw/modify_line_breaks_body modify_line_breaks_end modify_line_breaks_end_after remove_line_breaks_begin adjust_line_breaks_end_parent verbatim_modify_line_breaks/;
use LatexIndent::Sentence qw/one_sentence_per_line/;
-use LatexIndent::Wrap qw/text_wrap/;
+use LatexIndent::Wrap qw/text_wrap text_wrap_comment_blocks/;
use LatexIndent::TrailingComments
qw/remove_trailing_comments put_trailing_comments_back_in add_comment_symbol construct_trailing_comment_regexp/;
use LatexIndent::HorizontalWhiteSpace qw/remove_trailing_whitespace remove_leading_space/;
@@ -297,6 +297,31 @@
$logger->info('*Phase 4: final indentation check');
$self->final_indentation_check;
+ # one sentence per line: sentences are objects, as of V3.5.1
+ if ( $is_m_switch_active
+ and ${ $mainSettings{modifyLineBreaks}{oneSentencePerLine} }{manipulateSentences}
+ and ${ $mainSettings{modifyLineBreaks}{textWrapOptions} }{when} eq 'after' )
+ {
+ $logger->trace("*one-sentence-per-line text wrapping routine, textWrapOptions:when set to 'after'")
+ if $is_tt_switch_active;
+ $self->one_sentence_per_line( textWrap => 1 );
+ }
+
+ # option for text wrap
+ if ( $is_m_switch_active
+ and !${ $mainSettings{modifyLineBreaks}{oneSentencePerLine} }{manipulateSentences}
+ and !${ $mainSettings{modifyLineBreaks}{oneSentencePerLine} }{textWrapSentences}
+ and ${ $mainSettings{modifyLineBreaks}{textWrapOptions} }{columns} != 0
+ and ${ $mainSettings{modifyLineBreaks}{textWrapOptions} }{when} eq 'after' )
+ {
+ $self->text_wrap();
+ }
+
+ # option for comment text wrap
+ $self->text_wrap_comment_blocks()
+ if ($is_m_switch_active
+ and ${ ${ $mainSettings{modifyLineBreaks}{textWrapOptions} }{comments} }{wrap}
+ and ${ $mainSettings{modifyLineBreaks}{textWrapOptions} }{when} eq 'after' );
return;
}
@@ -304,8 +329,10 @@
my $self = shift;
# one sentence per line: sentences are objects, as of V3.5.1
- $self->one_sentence_per_line
- if ( $is_m_switch_active and ${ $mainSettings{modifyLineBreaks}{oneSentencePerLine} }{manipulateSentences} );
+ $self->one_sentence_per_line(
+ textWrap => ( ${ $mainSettings{modifyLineBreaks}{textWrapOptions} }{when} eq 'before' ) )
+ if ( $is_m_switch_active
+ and ${ $mainSettings{modifyLineBreaks}{oneSentencePerLine} }{manipulateSentences} );
# text wrapping
#
@@ -319,7 +346,8 @@
if ( $is_m_switch_active
and !${ $mainSettings{modifyLineBreaks}{oneSentencePerLine} }{manipulateSentences}
and !${ $mainSettings{modifyLineBreaks}{oneSentencePerLine} }{textWrapSentences}
- and ${ $mainSettings{modifyLineBreaks}{textWrapOptions} }{columns} != 0 )
+ and ${ $mainSettings{modifyLineBreaks}{textWrapOptions} }{columns} != 0
+ and ${ $mainSettings{modifyLineBreaks}{textWrapOptions} }{when} eq 'before' )
{
$self->text_wrap();
@@ -327,6 +355,12 @@
$self->verbatim_modify_line_breaks( when => "afterTextWrap" );
}
+ # option for comment text wrap
+ $self->text_wrap_comment_blocks()
+ if ($is_m_switch_active
+ and ${ ${ $mainSettings{modifyLineBreaks}{textWrapOptions} }{comments} }{wrap}
+ and ${ $mainSettings{modifyLineBreaks}{textWrapOptions} }{when} eq 'before' );
+
# search for environments
$logger->trace('*looking for ENVIRONMENTS') if $is_t_switch_active;
$self->find_environments if ${$self}{body} =~ m/$environmentBasicRegExp/s;
@@ -496,7 +530,13 @@
$self->check_for_hidden_children if ${$self}{body} =~ m/$tokens{beginOfToken}/;
# double back slash poly-switch check
- $self->double_back_slash_else if ( $is_m_switch_active and ${$self}{lookForAlignDelims} );
+ $self->double_back_slash_else
+ if (
+ $is_m_switch_active
+ and ( ${$self}{lookForAlignDelims}
+ or ( defined ${$self}{DBSStartsOnOwnLine} and ${$self}{DBSStartsOnOwnLine} != 0 )
+ or ( defined ${$self}{DBSFinishesWithLineBreak} and ${$self}{DBSFinishesWithLineBreak} != 0 ) )
+ );
# some objects can format their body to align at the & character
$self->align_at_ampersand if ( ${$self}{lookForAlignDelims} and !${$self}{measureHiddenChildren} );
Modified: trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/GetYamlSettings.pm
===================================================================
--- trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/GetYamlSettings.pm 2023-01-01 20:32:34 UTC (rev 65426)
+++ trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/GetYamlSettings.pm 2023-01-01 20:33:08 UTC (rev 65427)
@@ -117,16 +117,75 @@
# we'll need the home directory a lot in what follows
my $homeDir = File::HomeDir->my_home;
- $logger->info("*YAML settings read: indentconfig.yaml or .indentconfig.yaml") unless $switches{onlyDefault};
+ $logger->info("*YAML reading settings") unless $switches{onlyDefault};
- # get information about user settings- first check if indentconfig.yaml exists
- my $indentconfig = "$homeDir/indentconfig.yaml";
+ my $indentconfig = undef;
+ if ( defined $ENV{LATEXINDENT_CONFIG} && !$switches{onlyDefault} ) {
+ if ( -f $ENV{LATEXINDENT_CONFIG} ) {
+ $indentconfig = $ENV{LATEXINDENT_CONFIG};
+ $logger->info('The $LATEXINDENT_CONFIG variable was detected.');
+ $logger->info( 'The value of $LATEXINDENT_CONFIG is: "' . $ENV{LATEXINDENT_CONFIG} . '"' );
+ }
+ else {
+ $logger->warn('*The $LATEXINDENT_CONFIG variable is assigned, but does not point to a file!');
+ $logger->warn( 'The value of $LATEXINDENT_CONFIG is: "' . $ENV{LATEXINDENT_CONFIG} . '"' );
+ }
+ }
+ if ( !defined $indentconfig && !$switches{onlyDefault} ) {
- # if indentconfig.yaml doesn't exist, check for the hidden file, .indentconfig.yaml
- $indentconfig = "$homeDir/.indentconfig.yaml" if ( !-e $indentconfig );
+# see all possible values of $^O here: https://perldoc.perl.org/perlport#Unix and https://perldoc.perl.org/perlport#DOS-and-Derivatives
+ if ( $^O eq "linux" ) {
+ if ( defined $ENV{XDG_CONFIG_HOME} && -f "$ENV{XDG_CONFIG_HOME}/latexindent/indentconfig.yaml" ) {
+ $indentconfig = "$ENV{XDG_CONFIG_HOME}/latexindent/indentconfig.yaml";
+ $logger->info( 'The $XDG_CONFIG_HOME variable and the config file in "'
+ . "$ENV{XDG_CONFIG_HOME}/latexindent/indentconfig.yaml"
+ . '" were recognized' );
+ $logger->info( 'The value of $XDG_CONFIG_HOME is: "' . $ENV{XDG_CONFIG_HOME} . '"' );
+ }
+ elsif ( -f "$homeDir/.config/latexindent/indentconfig.yaml" ) {
+ $indentconfig = "$homeDir/.config/latexindent/indentconfig.yaml";
+ $logger->info(
+ 'The config file in "' . "$homeDir/.config/latexindent/indentconfig.yaml" . '" was recognized' );
+ }
+ }
+ elsif ( $^O eq "darwin" ) {
+ if ( -f "$homeDir/Library/Preferences/latexindent/indentconfig.yaml" ) {
+ $indentconfig = "$homeDir/Library/Preferences/latexindent/indentconfig.yaml";
+ $logger->info( 'The config file in "'
+ . "$homeDir/Library/Preferences/latexindent/indentconfig.yaml"
+ . '" was recognized' );
+ }
+ }
+ elsif ( $^O eq "MSWin32" || $^O eq "cygwin" ) {
+ if ( defined $ENV{LOCALAPPDATA} && -f "$ENV{LOCALAPPDATA}/latexindent/indentconfig.yaml" ) {
+ $indentconfig = "$ENV{LOCALAPPDATA}/latexindent/indentconfig.yaml";
+ $logger->info( 'The $LOCALAPPDATA variable and the config file in "'
+ . "$ENV{LOCALAPPDATA}"
+ . '\latexindent\indentconfig.yaml" were recognized' );
+ $logger->info( 'The value of $LOCALAPPDATA is: "' . $ENV{LOCALAPPDATA} . '"' );
+ }
+ elsif ( -f "$homeDir/AppData/Local/latexindent/indentconfig.yaml" ) {
+ $indentconfig = "$homeDir/AppData/Local/latexindent/indentconfig.yaml";
+ $logger->info( 'The config file in "'
+ . "$homeDir"
+ . '\AppData\Local\latexindent\indentconfig.yaml" was recognized' );
+ }
+ }
+ # if $indentconfig is still not defined, fallback to the location in $homeDir
+ if ( !defined $indentconfig ) {
+
+ # if all of these don't exist check home directly, with the non hidden file
+ $indentconfig = ( -f "$homeDir/indentconfig.yaml" ) ? "$homeDir/indentconfig.yaml" : undef;
+
+ # if indentconfig.yaml doesn't exist, check for the hidden file, .indentconfig.yaml
+ $indentconfig = ( -f "$homeDir/.indentconfig.yaml" ) ? "$homeDir/.indentconfig.yaml" : undef;
+ $logger->info( 'The config file in "' . "$indentconfig" . '" was recognized' ) if defined $indentconfig;
+ }
+ }
+
# messages for indentconfig.yaml and/or .indentconfig.yaml
- if ( -e $indentconfig and !$switches{onlyDefault} ) {
+ if ( defined $indentconfig && -f $indentconfig && !$switches{onlyDefault} ) {
# read the absolute paths from indentconfig.yaml
$userSettings = YAML::Tiny->read("$indentconfig");
@@ -135,19 +194,6 @@
if ( $userSettings and ( ref( $userSettings->[0] ) eq 'HASH' ) and $userSettings->[0]->{paths} ) {
$logger->info("Reading path information from $indentconfig");
- # if both indentconfig.yaml and .indentconfig.yaml exist
- if ( -e File::HomeDir->my_home . "/indentconfig.yaml"
- and -e File::HomeDir->my_home . "/.indentconfig.yaml" )
- {
- $logger->info("$homeDir/.indentconfig.yaml has been found, but $indentconfig takes priority");
- }
- elsif ( -e File::HomeDir->my_home . "/indentconfig.yaml" ) {
- $logger->info("(Alternatively $homeDir/.indentconfig.yaml can be used)");
- }
- elsif ( -e File::HomeDir->my_home . "/.indentconfig.yaml" ) {
- $logger->info("(Alternatively $homeDir/indentconfig.yaml can be used)");
- }
-
# output the contents of indentconfig to the log file
$logger->info( Dump \%{ $userSettings->[0] } );
@@ -190,7 +236,8 @@
else {
if ( $switches{onlyDefault} ) {
$logger->info("*-d switch active: only default settings requested");
- $logger->info("not reading USER settings from $indentconfig") if ( -e $indentconfig );
+ $logger->info("not reading USER settings from $indentconfig")
+ if ( defined $indentconfig && -e $indentconfig );
$logger->info("Ignoring the -l switch: $switches{readLocalSettings} (you used the -d switch)")
if ( $switches{readLocalSettings} );
$logger->info("Ignoring the -y switch: $switches{yaml} (you used the -d switch)") if ( $switches{yaml} );
@@ -198,9 +245,9 @@
$switches{yaml} = 0;
}
else {
- # give the user instructions on where to put indentconfig.yaml or .indentconfig.yaml
+ # give the user instructions on where to put the config file
$logger->info(
- "Home directory is $homeDir (didn't find either indentconfig.yaml or .indentconfig.yaml)\nTo specify user settings you would put indentconfig.yaml here: $homeDir/indentconfig.yaml\nAlternatively, you can use the hidden file .indentconfig.yaml as: $homeDir/.indentconfig.yaml"
+ "Home directory is $homeDir (didn't find a config file, see all posible locations here: https://latexindentpl.readthedocs.io/en/latest/sec-appendices.html#indentconfig-options)"
);
}
}
@@ -693,6 +740,25 @@
}
+ # the following are incompatible:
+ #
+ # modifyLineBreaks:
+ # oneSentencePerLine:
+ # manipulateSentences: 1
+ # textWrapSentences: 1
+ # sentenceIndent: " " <!------
+ # textWrapOptions:
+ # columns: 100
+ # when: after <!------
+ #
+ if ( $is_m_switch_active
+ and ${ $mainSettings{modifyLineBreaks}{textWrapOptions} }{when} eq 'after'
+ and ${ $mainSettings{modifyLineBreaks}{oneSentencePerLine} }{sentenceIndent} =~ m/\h+/ )
+ {
+ $logger->warn("*one-sentence-per-line *ignoring* sentenceIndent, as text wrapping set to 'after'");
+ ${ $mainSettings{modifyLineBreaks}{oneSentencePerLine} }{sentenceIndent} = q();
+ }
+
# some users may wish to see showAmalgamatedSettings
# which details the overall state of the settings modified
# from the default in various user files
@@ -887,8 +953,12 @@
my @toBeAssignedTo = ${$self}{additionalAssignments} ? @{ ${$self}{additionalAssignments} } : ();
# the following will *definitley* be in the array, so let's add them
- push( @toBeAssignedTo,
- ( "BeginStartsOnOwnLine", "BodyStartsOnOwnLine", "EndStartsOnOwnLine", "EndFinishesWithLineBreak" ) );
+ push(
+ @toBeAssignedTo,
+ ( "BeginStartsOnOwnLine", "BodyStartsOnOwnLine", "EndStartsOnOwnLine", "EndFinishesWithLineBreak",
+ "DBSStartsOnOwnLine", "DBSFinishesWithLineBreak"
+ )
+ );
# we can efficiently loop through the following
foreach (@toBeAssignedTo) {
Modified: trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Sentence.pm
===================================================================
--- trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Sentence.pm 2023-01-01 20:32:34 UTC (rev 65426)
+++ trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Sentence.pm 2023-01-01 20:33:08 UTC (rev 65427)
@@ -32,15 +32,16 @@
our $sentenceCounter;
sub one_sentence_per_line {
- my $self = shift;
+ my $self = shift;
+ my %input = @_;
$logger->trace(
"*One sentence per line regular expression construction: (see oneSentencePerLine: manipulateSentences)")
if $is_t_switch_active;
+ #
# sentences FOLLOW
- # sentences FOLLOW
- # sentences FOLLOW
+ #
my $sentencesFollow = q();
while ( my ( $sentencesFollowEachPart, $yesNo )
@@ -105,9 +106,9 @@
$logger->trace("Sentences follow regexp:") if $is_tt_switch_active;
$logger->trace($sentencesFollow) if $is_tt_switch_active;
+ #
# sentences BEGIN with
- # sentences BEGIN with
- # sentences BEGIN with
+ #
my $sentencesBeginWith = q();
while ( my ( $sentencesBeginWithEachPart, $yesNo )
@@ -136,9 +137,9 @@
}
$sentencesBeginWith = qr/$sentencesBeginWith/;
+ #
# sentences END with
- # sentences END with
- # sentences END with
+ #
${ ${ $mainSettings{modifyLineBreaks}{oneSentencePerLine} }{sentencesEndWith} }{basicFullStop} = 0
if ${ ${ $mainSettings{modifyLineBreaks}{oneSentencePerLine} }{sentencesEndWith} }{betterFullStop};
my $sentencesEndWith = q();
@@ -181,9 +182,9 @@
}
$sentencesEndWith = qr/$sentencesEndWith/;
+ #
# the OVERALL sentence regexp
- # the OVERALL sentence regexp
- # the OVERALL sentence regexp
+ #
$logger->trace("Overall sentences end with regexp:") if $is_tt_switch_active;
$logger->trace($sentencesEndWith) if $is_tt_switch_active;
@@ -268,12 +269,26 @@
$replacementText = ${@{${$self}{children}}[-1]}{replacementText};
} else {
$sentenceCounter++;
- push(@sentenceStorage,{id=>$tokens{sentence}.$sentenceCounter.$tokens{endOfToken},value=>$middle.$end});
+ push(@sentenceStorage,{id=>$tokens{sentence}.$sentenceCounter.$tokens{endOfToken},value=>$middle.$end,leadingHorizontalSpace=>$h_space,follows=>$beginning});
$replacementText = $beginning.$h_space.$tokens{sentence}.$sentenceCounter.$tokens{endOfToken}.$trailingComments.$trailing.($lineBreaksAtEnd ? q() : "\n");
};
$replacementText;
/xsge;
+ #
+ # remove spaces between trailing comments
+ #
+ #
+ # from:
+ #
+ # % first comment %second comment
+ # ^
+ # into:
+ #
+ # % first comment%second comment
+ #
+ ${$self}{body} =~ s/($trailingCommentRegExp)\h($trailingCommentRegExp)/$1$2/sg;
+
if ( ${ $mainSettings{modifyLineBreaks}{oneSentencePerLine} }{sentenceIndent} !~ m/\h+/ ) {
# loop back through the sentenceStorage and replace with the sentence, adjusting line breaks
@@ -288,6 +303,8 @@
body => $sentenceStorageValue,
name => "sentence",
modifyLineBreaksYamlName => "sentence",
+ leadingHorizontalSpace => ${$sentence}{leadingHorizontalSpace},
+ follows => ${$sentence}{follows},
);
# text wrapping
@@ -302,7 +319,7 @@
${ $mainSettings{modifyLineBreaks}{oneSentencePerLine} }{textWrapSentences} = 0;
}
else {
- $sentenceObj->text_wrap;
+ $sentenceObj->text_wrap if $input{textWrap};
}
# indentation of sentences
@@ -316,7 +333,7 @@
my $bodyFirstLine = $1;
my $remainingBody = $2;
my $indentation = ${ $mainSettings{modifyLineBreaks}{oneSentencePerLine} }{sentenceIndent};
- $logger->trace("first line of sencent: $bodyFirstLine") if $is_tt_switch_active;
+ $logger->trace("first line of sentence: $bodyFirstLine") if $is_tt_switch_active;
$logger->trace("remaining body (before indentation):\n'$remainingBody'") if ($is_tt_switch_active);
# add the indentation to all the body except first line
@@ -326,6 +343,7 @@
# put the body back together
${$sentenceObj}{body} = $bodyFirstLine . "\n" . $remainingBody;
}
+
$sentenceStorageValue = ${$sentenceObj}{body};
}
Modified: trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/TrailingComments.pm
===================================================================
--- trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/TrailingComments.pm 2023-01-01 20:32:34 UTC (rev 65426)
+++ trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/TrailingComments.pm 2023-01-01 20:33:08 UTC (rev 65427)
@@ -24,7 +24,7 @@
use Data::Dumper;
use Exporter qw/import/;
our @EXPORT_OK
- = qw/remove_trailing_comments put_trailing_comments_back_in $trailingCommentRegExp add_comment_symbol construct_trailing_comment_regexp/;
+ = qw/remove_trailing_comments put_trailing_comments_back_in $trailingCommentRegExp add_comment_symbol construct_trailing_comment_regexp @trailingComments/;
our @trailingComments;
our $commentCounter = 0;
our $trailingCommentRegExp;
@@ -39,13 +39,17 @@
# add a trailing comment token after, for example, a square brace [
# or a curly brace { when, for example, BeginStartsOnOwnLine == 2
- my $self = shift;
+ my $self = shift;
+ my %input = @_;
+ my $commentValue = ( defined $input{value} ? $input{value} : q() );
+
# increment the comment counter
$commentCounter++;
# store the comment -- without this, it won't get processed correctly at the end
- push( @trailingComments, { id => $tokens{trailingComment} . $commentCounter . $tokens{endOfToken}, value => q() } );
+ push( @trailingComments,
+ { id => $tokens{trailingComment} . $commentCounter . $tokens{endOfToken}, value => $commentValue } );
# log file info
$logger->trace("*Updating trailing comment array") if $is_t_switch_active;
@@ -145,8 +149,6 @@
$logger->trace("Comment not at end of line $trailingcommentID, moving it to end of line")
if $is_t_switch_active;
${$self}{body} =~ s/%$trailingcommentID(.*)$/$1%$trailingcommentValue/m;
- #####if(${$self}{body} =~ m/%$trailingcommentID\h*[^%]+?$/mx){
- ##### $logger->trace("Comment not at end of line $trailingcommentID, moving it to end of line") if $is_t_switch_active;
}
else {
${$self}{body} =~ s/%$trailingcommentID/%$trailingcommentValue/;
Modified: trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Version.pm
===================================================================
--- trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Version.pm 2023-01-01 20:32:34 UTC (rev 65426)
+++ trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Version.pm 2023-01-01 20:33:08 UTC (rev 65427)
@@ -20,6 +20,6 @@
use Exporter qw/import/;
our @EXPORT_OK = qw/$versionNumber $versionDate/;
-our $versionNumber = '3.19.1';
-our $versionDate = '2022-12-04';
+our $versionNumber = '3.20';
+our $versionDate = '2023-01-01';
1
Modified: trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Wrap.pm
===================================================================
--- trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Wrap.pm 2023-01-01 20:32:34 UTC (rev 65426)
+++ trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Wrap.pm 2023-01-01 20:33:08 UTC (rev 65427)
@@ -20,14 +20,14 @@
use Text::Wrap;
use LatexIndent::Tokens qw/%tokens/;
use LatexIndent::AlignmentAtAmpersand qw/get_column_width/;
-use LatexIndent::TrailingComments qw/$trailingCommentRegExp/;
+use LatexIndent::TrailingComments qw/$trailingCommentRegExp @trailingComments/;
use LatexIndent::GetYamlSettings qw/%mainSettings/;
use LatexIndent::Switches qw/$is_t_switch_active $is_tt_switch_active $is_m_switch_active/;
use LatexIndent::LogFile qw/$logger/;
use LatexIndent::Verbatim qw/%verbatimStorage/;
use Exporter qw/import/;
-our @ISA = "LatexIndent::Document"; # class inheritance, Programming Perl, pg 321
-our @EXPORT_OK = qw/text_wrap/;
+our @ISA = "LatexIndent::Document"; # class inheritance, Programming Perl, pg 321
+our @EXPORT_OK = qw/text_wrap text_wrap_comment_blocks/;
our $sentenceCounter;
sub text_wrap {
@@ -35,13 +35,15 @@
$logger->trace("*Text wrap regular expression construction: (see textWrapOptions: )") if $is_t_switch_active;
+ #
# textWrap Blocks FOLLOW
- # textWrap Blocks FOLLOW
- # textWrap Blocks FOLLOW
+ #
my $blocksFollow = q();
my $blocksFollowHash = \%{ ${ $mainSettings{modifyLineBreaks}{textWrapOptions} }{blocksFollow} };
foreach my $blocksFollowEachPart ( sort keys %{$blocksFollowHash} ) {
+ last if ${$self}{modifyLineBreaksYamlName} eq 'sentence';
+
my $yesNo = $blocksFollowHash->{$blocksFollowEachPart};
if ($yesNo) {
if ( $blocksFollowEachPart eq "par" ) {
@@ -118,16 +120,19 @@
# followed by 0 or more h-space and line breaks
$blocksFollow = ( $blocksFollow eq '' ? q() : qr/(?:$blocksFollow)(?:\h|\R)*/sx );
- $logger->trace("textWrap blocks follow regexp:") if $is_tt_switch_active;
+ $logger->trace("textWrap blocks follow regexp:")
+ if ( $is_tt_switch_active and ${$self}{modifyLineBreaksYamlName} ne 'sentence' );
$logger->trace($blocksFollow) if $is_tt_switch_active;
+ #
# textWrap Blocks BEGIN with
- # textWrap Blocks BEGIN with
- # textWrap Blocks BEGIN with
+ #
my $blocksBeginWith = q();
my $blocksBeginWithHash = \%{ ${ $mainSettings{modifyLineBreaks}{textWrapOptions} }{blocksBeginWith} };
foreach my $blocksBeginWithEachPart ( sort keys %{$blocksBeginWithHash} ) {
+ last if ${$self}{modifyLineBreaksYamlName} eq 'sentence';
+
my $yesNo = $blocksBeginWithHash->{$blocksBeginWithEachPart};
if ($yesNo) {
if ( $blocksBeginWithEachPart eq "A-Z" ) {
@@ -156,13 +161,15 @@
}
$blocksBeginWith = qr/$blocksBeginWith/;
+ #
# textWrap Blocks END with
- # textWrap Blocks END with
- # textWrap Blocks END with
+ #
my $blocksEndBefore = q();
my $blocksEndBeforeHash = \%{ ${ $mainSettings{modifyLineBreaks}{textWrapOptions} }{blocksEndBefore} };
foreach my $blocksEndBeforeEachPart ( sort keys %{$blocksEndBeforeHash} ) {
+ last if ${$self}{modifyLineBreaksYamlName} eq 'sentence';
+
my $yesNo = $blocksEndBeforeHash->{$blocksEndBeforeEachPart};
if ($yesNo) {
if ( $blocksEndBeforeEachPart eq "other" ) {
@@ -191,14 +198,17 @@
}
$blocksEndBefore = qr/$blocksEndBefore/;
+ #
# the OVERALL textWrap Blocks regexp
- # the OVERALL textWrap Blocks regexp
- # the OVERALL textWrap Blocks regexp
- $logger->trace("Overall textWrap Blocks end with regexp:") if $is_tt_switch_active;
+ #
+ $logger->trace("Overall textWrap Blocks end with regexp:")
+ if ( $is_tt_switch_active and ${$self}{modifyLineBreaksYamlName} ne 'sentence' );
$logger->trace($blocksEndBefore) if $is_tt_switch_active;
# store the text wrap blocks
my @textWrapBlockStorage = split( /($blocksFollow)/, ${$self}{body} );
+ @textWrapBlockStorage = split( /(\s*$blocksFollow)/, ${$self}{body} )
+ if ${ $mainSettings{modifyLineBreaks}{textWrapOptions} }{when} eq 'after';
# sentences need special treatment
if ( ${$self}{modifyLineBreaksYamlName} eq 'sentence' ) {
@@ -209,8 +219,9 @@
my $columns = ${ $mainSettings{modifyLineBreaks}{textWrapOptions} }{columns};
# vital Text::Wrap options
- $Text::Wrap::columns = $columns;
- $Text::Wrap::huge = ${ $mainSettings{modifyLineBreaks}{textWrapOptions} }{huge};
+ $Text::Wrap::columns = $columns;
+ $Text::Wrap::huge = ${ $mainSettings{modifyLineBreaks}{textWrapOptions} }{huge};
+ $Text::Wrap::unexpand = 0;
# all other Text::Wrap options not usually needed/helpful, but available
$Text::Wrap::separator = ${ $mainSettings{modifyLineBreaks}{textWrapOptions} }{separator}
@@ -222,17 +233,123 @@
$Text::Wrap::tabstop = ${ $mainSettings{modifyLineBreaks}{textWrapOptions} }{tabstop}
if ${ $mainSettings{modifyLineBreaks}{textWrapOptions} }{tabstop};
+ # only needed if when:after
+ my $subsequentSpace = q();
+
# clear the body, which will be updated with newly wrapped body
${$self}{body} = q();
+ # text wrap block loop counter
+ my $textWrapBlockCount = -1;
+
# loop back through the text wrap block storage
foreach my $textWrapBlockStorageValue (@textWrapBlockStorage) {
+
+ # increment text wrap block loop counter
+ $textWrapBlockCount++;
+
if ( $textWrapBlockStorageValue =~ m/^\s*$blocksBeginWith/s
or ${$self}{modifyLineBreaksYamlName} eq 'sentence' )
{
+# text wrap AFTER indentation needs to turn, for example (with columns: 100),
+#
+# before:
+#
+# \begin{abstract}
+# This is a very long sentence that should be wrapped at some point, which is the case but is is is is line width is not respected because of the indentation.
+# \end{abstract}
+#
+# after:
+#
+# \begin{abstract}
+# This is a very long sentence that should be wrapped at some point, which is the case but is is
+# is is line width is not respected because of the indentation.
+# \end{abstract}
+# ----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|
+# 5 10 15 20 25 30 35 40 45 50 55 60 65 70 75 80 85 90 95 100 105 110
+#
+# note: it respects the column width AND indentation
+#
+# see also: test-cases/text-wrap/issue-359*.tex
+#
+ if ( ${ $mainSettings{modifyLineBreaks}{textWrapOptions} }{when} eq 'after' ) {
+
+ # reset columns
+ $Text::Wrap::columns = $columns;
+
+ # reset subsequent Space
+ $subsequentSpace = q();
+
+ my $numberOfTABS = 0;
+
+ # measure leading horizontal space
+ if ( ${$self}{modifyLineBreaksYamlName} eq 'sentence' ) {
+ my $thingToMeasure = ( split( /\R/, ${$self}{follows} ) )[-1];
+
+ $subsequentSpace
+ = ( ${$self}{follows} ? " " x length($thingToMeasure) : q() );
+
+ # possible tab adjustments
+ $thingToMeasure = q() if ( not defined $thingToMeasure );
+ $numberOfTABS = () = $thingToMeasure =~ m/\t/g;
+ for ( my $i = 1; $i <= $numberOfTABS; $i++ ) {
+ $subsequentSpace =~ s/ / /;
+ }
+ }
+ else {
+ # note, in the above we have defined
+ #
+ # @textWrapBlockStorage = split( /(\s*$blocksFollow)/, ${$self}{body} )
+ #
+ # so that both the *match* AND the *block* are stored, so
+ #
+ # ( split( /\R/, $textWrapBlockStorage[ $textWrapBlockCount - 1 ] ) )[-1]
+ #
+ # represents the *match*
+ #
+
+ # scenarios such as
+ #
+ # % comment goes here
+ # text that isn't commented
+ #
+ # means that the *match* doesn't contain a linebreak
+ #
+ if ( scalar( split( /\R/, $textWrapBlockStorage[ $textWrapBlockCount - 1 ] ) ) == 1
+ and ( split( /\R/, $textWrapBlockStorage[ $textWrapBlockCount - 1 ] ) )[-1]
+ =~ m/$trailingCommentRegExp/ )
+ {
+ $subsequentSpace = q();
+ }
+ else {
+ my $thingToMeasure = ( split( /\R/, $textWrapBlockStorage[ $textWrapBlockCount - 1 ] ) )[-1];
+
+ $subsequentSpace = (
+ $textWrapBlockCount == 0
+ ? q()
+ : " " x length($thingToMeasure)
+ );
+
+ # possible tab adjustments
+ $numberOfTABS = () = $thingToMeasure =~ m/\t/g;
+ for ( my $i = 1; $i <= $numberOfTABS; $i++ ) {
+ $subsequentSpace =~ s/ / /;
+ }
+ }
+ }
+ $Text::Wrap::columns = $columns - length($subsequentSpace);
+
+ # possible tab adjustments
+ for ( my $i = 1; $i <= $numberOfTABS; $i++ ) {
+ $subsequentSpace =~ s/ /\t/;
+ }
+ }
+
# LIMIT is one greater than the maximum number of times EXPR may be split
my @textWrapBeforeEndWith = split( /($blocksEndBefore)/, $textWrapBlockStorageValue, 2 );
+ @textWrapBeforeEndWith = split( /(\s*$blocksEndBefore)/, $textWrapBlockStorageValue, 2 )
+ if ${ $mainSettings{modifyLineBreaks}{textWrapOptions} }{when} eq 'after';
# sentences need special treatment
if ( ${$self}{modifyLineBreaksYamlName} eq 'sentence' ) {
@@ -355,6 +472,75 @@
$textWrapBlockStorageValue = wrap( '', '', $textWrapBlockStorageValue )
if ${ $mainSettings{modifyLineBreaks}{textWrapOptions} }{columns} > 0;
+ # if text wrap has happened *AFTER* indentation,
+ # then we need to add the leading indentation
+ # onto the lines of the text wrap block
+ #
+ # before:
+ #
+ # \begin{abstract}
+ # This is a very long sentence that should be wrapped at some point, which is the case but is is
+ # is is line width is not respected because of the indentation.
+ # ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ # \end{abstract}
+ #
+ # after:
+ #
+ # \begin{abstract}
+ # This is a very long sentence that should be wrapped at some point, which is the case but is is
+ # is is line width is not respected because of the indentation.
+ # ^^^^
+ # \end{abstract}
+ if ( ${ $mainSettings{modifyLineBreaks}{textWrapOptions} }{when} eq 'after' ) {
+
+ # add leading indentation back in to the text-wrapped block
+ $textWrapBlockStorageValue =~ s/^/$subsequentSpace/mg;
+
+ # remove the very first leading space, which is already handled by blocks follow
+ $textWrapBlockStorageValue =~ s/^\h*//s unless ${$self}{modifyLineBreaksYamlName} eq 'sentence';
+ }
+
+ #
+ # optionally wrap comments
+ #
+ if ( ${ ${ $mainSettings{modifyLineBreaks}{textWrapOptions} }{comments} }{wrap}
+ and $trailingComments ne '' )
+ {
+
+ my $commentValue = q();
+
+ # split the trailing comments, and put the *values* together
+ foreach ( split( /([0-9]+)$tokens{endOfToken}/, $trailingComments ) ) {
+ next unless $_ =~ m/[0-9]/;
+
+ $commentValue .= ${ $trailingComments[ $_ - 1 ] }{value};
+ }
+
+# leading comment space, e.g.
+#
+# % This is a very very long trailing comment that needs to be wrapped by latexindent to make sure the visual display is in a good shape.
+# ^^^^^
+#
+ $commentValue =~ m/^(\h+)/s;
+ my $leadingCommentSpace = ( $1 ? $1 : ' ' );
+
+ # reset columns
+ $Text::Wrap::columns
+ = $columns - &get_column_width( ( split( /\R/, $textWrapBlockStorageValue ) )[-1] );
+ $commentValue = wrap( '', '', $commentValue );
+
+ # the 2nd and subsequent lines need further attention
+ my @commentArray = ( split( /\R/, $commentValue ) );
+ my $firstLine = shift(@commentArray);
+ my $secondCommentLineOnwards = join( " ", @commentArray );
+ $secondCommentLineOnwards =~ s/\h{2,}/ /sg;
+
+ # assemble the new trailing comments, which will be wrapped after this routine as a comment block
+ $trailingComments = "%" . $self->add_comment_symbol( value => $firstLine );
+ $trailingComments .= "\n$subsequentSpace%"
+ . $self->add_comment_symbol( value => $leadingCommentSpace . $secondCommentLineOnwards );
+ }
+
# append trailing comments from WITHIN the block
$textWrapBlockStorageValue =~ s/\R?$/$trailingComments\n/s if ( $trailingComments ne '' );
@@ -383,4 +569,142 @@
}
+sub text_wrap_comment_blocks {
+
+ my $self = shift;
+
+ # call the text wrapping routine
+ my $columns = ${ $mainSettings{modifyLineBreaks}{textWrapOptions} }{columns};
+
+ #
+ # text wrap comment blocks
+ #
+ #
+ # from:
+ #
+ # % first comment
+ # % second comment
+ # % third comment
+ # % fourth comment
+ # % fifth comment
+ #
+ # into:
+ #
+ # % first comment second comment
+ # % third comment fourth comment
+ # % fifth comment
+ #
+ ${$self}{body} =~ s&((?:^\h*$trailingCommentRegExp\R)+)&
+ my @commentBlocks = $1;
+ my $trailingComments = q();
+
+ # loop through comment blocks
+ foreach my $commentBlock (@commentBlocks){
+
+ my $leadingHorizontalSpace = ($commentBlock =~ m|^(\h*\t*)|s? $1 : q());
+ my $numberOfTABS = () = $leadingHorizontalSpace =~ m/\t/g;
+ $leadingHorizontalSpace =~ s/\t/ /g;
+
+ my $commentValue = q();
+ $trailingComments = q();
+
+ # split the trailing comments, and put the *values* together
+ foreach (split(/([0-9]+)$tokens{endOfToken}/,$commentBlock)){
+ next unless $_ =~ m/[0-9]/;
+
+ $commentValue .= " ".${$trailingComments[$_-1]}{value};
+ }
+
+ # very first space
+ $commentValue =~ s|^\h||s;
+
+ # leading space
+ $commentValue =~ s|^(\h*)||s;
+ my $leadingSpace = (${${ $mainSettings{modifyLineBreaks}{textWrapOptions} }{comments}}{inheritLeadingSpace}? $1: ' ' );
+
+ $commentValue =~ s/\h{2,}/ /sg if ${ $mainSettings{modifyLineBreaks}{textWrapOptions} }{multipleSpacesToSingle};
+
+ # reset columns
+ $Text::Wrap::columns = $columns - length($leadingHorizontalSpace)-length($leadingSpace);
+ # ^^
+ # for the space added after comment symbol below
+
+ # tab adjustment
+ for (my $i=1; $i<=$numberOfTABS;$i++){
+ $leadingHorizontalSpace =~ s/ /\t/;
+ }
+
+ # wrap the comments
+ $commentValue = wrap( '', '', $commentValue );
+
+ # put them into storage
+ $trailingComments .= $leadingHorizontalSpace."%".$self->add_comment_symbol(value=>$leadingSpace.$_)."\n" foreach (split( /\R/, $commentValue ) );
+
+ }
+ $trailingComments;
+ &xemg;
+
+ #
+ # text wrap multiple comments on a line
+ #
+ # from:
+ #
+ # % fifth comment% fourth comment% third comment% second comment% first comment
+ #
+ # into:
+ #
+ # % first comment second comment
+ # % third comment fourth comment
+ # % fifth comment
+ #
+ ${$self}{body} =~ s&((?:$trailingCommentRegExp\h*)+)&
+ my @commentBlocks = $1;
+ my $trailingComments = q();
+
+ # loop through comment blocks
+ foreach my $commentBlock (@commentBlocks){
+
+ my $leadingHorizontalSpace = ($commentBlock =~ m|^(\h*\t*)|s? $1 : q());
+ my $numberOfTABS = () = $leadingHorizontalSpace =~ m/\t/g;
+ $leadingHorizontalSpace =~ s/\t/ /g;
+
+ my $commentValue = q();
+ $trailingComments = q();
+
+ # split the trailing comments, and put the *values* together
+ foreach (split(/([0-9]+)$tokens{endOfToken}/,$commentBlock)){
+ next unless $_ =~ m/[0-9]/;
+
+ $commentValue .= " ".${$trailingComments[$_-1]}{value};
+ }
+
+ # very first space
+ $commentValue =~ s|^\h||s;
+
+ # leading space
+ $commentValue =~ s|^(\h*)||s;
+ my $leadingSpace = (${${ $mainSettings{modifyLineBreaks}{textWrapOptions} }{comments}}{inheritLeadingSpace}? $1: ' ' );
+
+ $commentValue =~ s/\h{2,}/ /sg if ${ $mainSettings{modifyLineBreaks}{textWrapOptions} }{multipleSpacesToSingle};
+
+ # reset columns
+ $Text::Wrap::columns = $columns - length($leadingHorizontalSpace)-length($leadingSpace);
+ # ^^
+ # for the space added after comment symbol below
+
+ # tab adjustment
+ for (my $i=1; $i<=$numberOfTABS;$i++){
+ $leadingHorizontalSpace =~ s/ /\t/;
+ }
+
+ # wrap the comments
+ $commentValue = wrap( '', '', $commentValue );
+
+ # put them into storage
+ $trailingComments .= $leadingHorizontalSpace."%".$self->add_comment_symbol(value=>$leadingSpace.$_)."\n" foreach (split( /\R/, $commentValue ) );
+
+ }
+ $trailingComments;
+ &xemg;
+}
1;
Modified: trunk/Master/texmf-dist/scripts/latexindent/defaultSettings.yaml
===================================================================
--- trunk/Master/texmf-dist/scripts/latexindent/defaultSettings.yaml 2023-01-01 20:32:34 UTC (rev 65426)
+++ trunk/Master/texmf-dist/scripts/latexindent/defaultSettings.yaml 2023-01-01 20:33:08 UTC (rev 65427)
@@ -1,4 +1,4 @@
-# defaultSettings.yaml for latexindent.pl, version 3.19.1, 2022-12-04
+# defaultSettings.yaml for latexindent.pl, version 3.20, 2023-01-01
# a script that aims to
# beautify .tex, .sty, .cls files
#
@@ -164,7 +164,7 @@
justification: left
alignFinalDoubleBackSlash: 0
dontMeasure: 0
- delimiterRegEx: '(?<!\\)(&)'
+ delimiterRegEx: (?<!\\)(&)
delimiterJustification: left
lookForChildCodeBlocks: 1
tabularx:
@@ -252,16 +252,16 @@
# there's no restrictions
specialBeginEnd:
displayMath:
- begin: '\\\['
- end: '\\\]'
- lookForThis: 1
+ begin: (?<!\\)\\\[ # \[ but *not* \\[
+ end: \\\] # \]
+ lookForThis: 1
inlineMath:
- begin: '(?<!\$)(?<!\\)\$(?!\$)'
- end: '(?<!\\)\$(?!\$)'
+ begin: (?<!\$)(?<!\\)\$(?!\$) # $ but *not* \$ or $$
+ end: (?<!\\)\$(?!\$) # $ but *not* \$ or $$
lookForThis: 1
displayMathTeX:
- begin: '\$\$'
- end: '\$\$'
+ begin: \$\$ # $$
+ end: \$\$ # $$
lookForThis: 1
specialBeforeCommand: 0
@@ -332,34 +332,34 @@
# set noAdditionalIndent globally for codeblocks
noAdditionalIndentGlobal:
- environments: 0
- commands: 1
- optionalArguments: 0
- mandatoryArguments: 0
- ifElseFi: 0
- items: 0
- keyEqualsValuesBracesBrackets: 0
- namedGroupingBracesBrackets: 0
- UnNamedGroupingBracesBrackets: 0
- specialBeginEnd: 0
- afterHeading: 0
- filecontents: 0
+ environments: 0 # 0/1
+ commands: 1 # 0/1
+ optionalArguments: 0 # 0/1
+ mandatoryArguments: 0 # 0/1
+ ifElseFi: 0 # 0/1
+ items: 0 # 0/1
+ keyEqualsValuesBracesBrackets: 0 # 0/1
+ namedGroupingBracesBrackets: 0 # 0/1
+ UnNamedGroupingBracesBrackets: 0 # 0/1
+ specialBeginEnd: 0 # 0/1
+ afterHeading: 0 # 0/1
+ filecontents: 0 # 0/1
# set indentRules globally for codeblocks; these need
# to be horizontal spaces, if they are to be used
indentRulesGlobal:
- environments: 0
- commands: 0
- optionalArguments: 0
- mandatoryArguments: 0
- ifElseFi: 0
- items: 0
- keyEqualsValuesBracesBrackets: 0
- namedGroupingBracesBrackets: 0
- UnNamedGroupingBracesBrackets: 0
- specialBeginEnd: 0
- afterHeading: 0
- filecontents: 0
+ environments: 0 # 0/1
+ commands: 0 # 0/1
+ optionalArguments: 0 # 0/1
+ mandatoryArguments: 0 # 0/1
+ ifElseFi: 0 # 0/1
+ items: 0 # 0/1
+ keyEqualsValuesBracesBrackets: 0 # 0/1
+ namedGroupingBracesBrackets: 0 # 0/1
+ UnNamedGroupingBracesBrackets: 0 # 0/1
+ specialBeginEnd: 0 # 0/1
+ afterHeading: 0 # 0/1
+ filecontents: 0 # 0/1
# command code block details
commandCodeBlocks:
@@ -367,13 +367,13 @@
stringsAllowedBetweenArguments:
-
amalgamate: 1
- - 'node'
- - 'at'
- - 'to'
- - 'decoration'
- - '\+\+'
- - '\-\-'
- - '\#\#\d'
+ - node
+ - at
+ - to
+ - decoration
+ - \+\+
+ - \-\-
+ - \#\#\d
commandNameSpecial:
-
amalgamate: 1
@@ -493,117 +493,121 @@
#
# you can specify settings on a per-name basis
modifyLineBreaks:
- preserveBlankLines: 1
- condenseMultipleBlankLinesInto: 1
+ preserveBlankLines: 1 # 0/1
+ condenseMultipleBlankLinesInto: 1 # 0/1
oneSentencePerLine:
- manipulateSentences: 0
- removeSentenceLineBreaks: 1
- multipleSpacesToSingle: 1
- textWrapSentences: 0 # setting to 1 disables main textWrap routine
+ manipulateSentences: 0 # 0/1
+ removeSentenceLineBreaks: 1 # 0/1
+ multipleSpacesToSingle: 1 # 0/1
+ textWrapSentences: 0 # 1 disables main textWrap
sentenceIndent: ""
sentencesFollow:
- par: 1
- blankLine: 1
- fullStop: 1
- exclamationMark: 1
- questionMark: 1
- rightBrace: 1
- commentOnPreviousLine: 1
- other: 0
- sentencesBeginWith:
- A-Z: 1
- a-z: 0
- other: 0
+ par: 1 # 0/1
+ blankLine: 1 # 0/1
+ fullStop: 1 # 0/1
+ exclamationMark: 1 # 0/1
+ questionMark: 1 # 0/1
+ rightBrace: 1 # 0/1
+ commentOnPreviousLine: 1 # 0/1
+ other: 0 # regex
+ sentencesBeginWith:
+ A-Z: 1 # 0/1
+ a-z: 0 # 0/1
+ other: 0 # regex
sentencesEndWith:
- basicFullStop: 0
- betterFullStop: 1
- exclamationMark: 1
- questionMark: 1
- other: 0
+ basicFullStop: 0 # 0/1
+ betterFullStop: 1 # 0/1
+ exclamationMark: 1 # 0/1
+ questionMark: 1 # 0/1
+ other: 0 # regex
textWrapOptions:
columns: 0
- multipleSpacesToSingle: 1
+ multipleSpacesToSingle: 1
removeBlockLineBreaks: 1
+ when: before # before/after
+ comments:
+ wrap: 0 # 0/1
+ inheritLeadingSpace: 0 # 0/1
blocksFollow:
- headings: 1
- commentOnPreviousLine: 1
- par: 1
- blankLine: 1
- verbatim: 1
- filecontents: 1
- other: '\\\]|\\item(?:\h|\[)' # regex
+ headings: 1 # 0/1
+ commentOnPreviousLine: 1 # 0/1
+ par: 1 # 0/1
+ blankLine: 1 # 0/1
+ verbatim: 1 # 0/1
+ filecontents: 1 # 0/1
+ other: \\\]|\\item(?:\h|\[) # regex
blocksBeginWith:
- A-Z: 1
- a-z: 1
- 0-9: 0
- other: 0 # regex
+ A-Z: 1 # 0/1
+ a-z: 1 # 0/1
+ 0-9: 0 # 0/1
+ other: 0 # regex
blocksEndBefore:
- commentOnOwnLine: 1
- verbatim: 1
- filecontents: 1
- other: '\\begin\{|\\\[|\\end\{' # regex
- huge: overflow # forbid mid-word line breaks
+ commentOnOwnLine: 1 # 0/1
+ verbatim: 1 # 0/1
+ filecontents: 1 # 0/1
+ other: \\begin\{|\\\[|\\end\{ # regex
+ huge: overflow # forbid mid-word line breaks
separator: ""
- # poly-switches below here
- environments:
- BeginStartsOnOwnLine: 0
- BodyStartsOnOwnLine: 0
- EndStartsOnOwnLine: 0
- EndFinishesWithLineBreak: 0
- equation*:
- BeginStartsOnOwnLine: 0
- BodyStartsOnOwnLine: 0
- EndStartsOnOwnLine: 0
- EndFinishesWithLineBreak: 0
+ # poly-switches below here # -1: remove, 0: off, 1: add, 2: comment+add, 3: add blank line, 4: add blank line
+ environments:
+ BeginStartsOnOwnLine: 0 # -1,0,1,2,3,4
+ BodyStartsOnOwnLine: 0 # -1,0,1,2,3,4
+ EndStartsOnOwnLine: 0 # -1,0,1,2,3,4
+ EndFinishesWithLineBreak: 0 # -1,0,1,2,3,4
+ equation*:
+ BeginStartsOnOwnLine: 0 # -1,0,1,2,3,4
+ BodyStartsOnOwnLine: 0 # -1,0,1,2,3,4
+ EndStartsOnOwnLine: 0 # -1,0,1,2,3,4
+ EndFinishesWithLineBreak: 0 # -1,0,1,2,3,4
ifElseFi:
- IfStartsOnOwnLine: 0
- BodyStartsOnOwnLine: 0
- OrStartsOnOwnLine: 0
- OrFinishesWithLineBreak: 0
- ElseStartsOnOwnLine: 0
- ElseFinishesWithLineBreak: 0
- FiStartsOnOwnLine: 0
- FiFinishesWithLineBreak: 0
+ IfStartsOnOwnLine: 0 # -1,0,1,2,3,4
+ BodyStartsOnOwnLine: 0 # -1,0,1,2,3,4
+ OrStartsOnOwnLine: 0 # -1,0,1,2,3,4
+ OrFinishesWithLineBreak: 0 # -1,0,1,2,3,4
+ ElseStartsOnOwnLine: 0 # -1,0,1,2,3,4
+ ElseFinishesWithLineBreak: 0 # -1,0,1,2,3,4
+ FiStartsOnOwnLine: 0 # -1,0,1,2,3,4
+ FiFinishesWithLineBreak: 0 # -1,0,1,2,3,4
ifnum:
- IfStartsOnOwnLine: 0
- BodyStartsOnOwnLine: 0
- OrStartsOnOwnLine: 0
- OrFinishesWithLineBreak: 0
- ElseStartsOnOwnLine: 0
- ElseFinishesWithLineBreak: 0
- FiStartsOnOwnLine: 0
- FiFinishesWithLineBreak: 0
+ IfStartsOnOwnLine: 0 # -1,0,1,2,3,4
+ BodyStartsOnOwnLine: 0 # -1,0,1,2,3,4
+ OrStartsOnOwnLine: 0 # -1,0,1,2,3,4
+ OrFinishesWithLineBreak: 0 # -1,0,1,2,3,4
+ ElseStartsOnOwnLine: 0 # -1,0,1,2,3,4
+ ElseFinishesWithLineBreak: 0 # -1,0,1,2,3,4
+ FiStartsOnOwnLine: 0 # -1,0,1,2,3,4
+ FiFinishesWithLineBreak: 0 # -1,0,1,2,3,4
commands:
- CommandStartsOnOwnLine: 0
+ CommandStartsOnOwnLine: 0
CommandNameFinishesWithLineBreak: 0
optionalArguments:
- LSqBStartsOnOwnLine: 0
- OptArgBodyStartsOnOwnLine: 0
- RSqBStartsOnOwnLine: 0
- RSqBFinishesWithLineBreak: 0
- mandatoryArguments:
- LCuBStartsOnOwnLine: 0
- MandArgBodyStartsOnOwnLine: 0
- RCuBStartsOnOwnLine: 0
- RCuBFinishesWithLineBreak: 0
+ LSqBStartsOnOwnLine: 0 # -1,0,1,2,3,4
+ OptArgBodyStartsOnOwnLine: 0 # -1,0,1,2,3,4
+ RSqBStartsOnOwnLine: 0 # -1,0,1,2,3,4
+ RSqBFinishesWithLineBreak: 0 # -1,0,1,2,3,4
+ mandatoryArguments:
+ LCuBStartsOnOwnLine: 0 # -1,0,1,2,3,4
+ MandArgBodyStartsOnOwnLine: 0 # -1,0,1,2,3,4
+ RCuBStartsOnOwnLine: 0 # -1,0,1,2,3,4
+ RCuBFinishesWithLineBreak: 0 # -1,0,1,2,3,4
keyEqualsValuesBracesBrackets:
- KeyStartsOnOwnLine: 0
- EqualsStartsOnOwnLine: 0
- EqualsFinishesWithLineBreak: 0
- items:
- ItemStartsOnOwnLine: 0
- ItemFinishesWithLineBreak: 0
+ KeyStartsOnOwnLine: 0 # -1,0,1,2,3,4
+ EqualsStartsOnOwnLine: 0 # -1,0,1,2,3,4
+ EqualsFinishesWithLineBreak: 0 # -1,0,1,2,3,4
+ items:
+ ItemStartsOnOwnLine: 0 # -1,0,1,2,3,4
+ ItemFinishesWithLineBreak: 0 # -1,0,1,2,3,4
namedGroupingBracesBrackets:
- NameStartsOnOwnLine: 0
- NameFinishesWithLineBreak: 0
+ NameStartsOnOwnLine: 0 # -1,0,1,2,3,4
+ NameFinishesWithLineBreak: 0 # -1,0,1,2,3,4
specialBeginEnd:
- SpecialBeginStartsOnOwnLine: 0
- SpecialBodyStartsOnOwnLine: 0
- SpecialEndStartsOnOwnLine: 0
- SpecialEndFinishesWithLineBreak: 0
+ SpecialBeginStartsOnOwnLine: 0 # -1,0,1,2,3,4
+ SpecialBodyStartsOnOwnLine: 0 # -1,0,1,2,3,4
+ SpecialEndStartsOnOwnLine: 0 # -1,0,1,2,3,4
+ SpecialEndFinishesWithLineBreak: 0 # -1,0,1,2,3,4
verbatim:
- VerbatimBeginStartsOnOwnLine: 0
- VerbatimEndFinishesWithLineBreak: 0
+ VerbatimBeginStartsOnOwnLine: 0 # -1,0,1,2,3,4
+ VerbatimEndFinishesWithLineBreak: 0 # -1,0,1,2,3,4
# replacements, only active when either -r or -rr switches are active
replacements:
@@ -610,8 +614,8 @@
-
amalgamate: 1
-
- this: 'latexindent.pl'
- that: 'pl.latexindent'
+ this: latexindent.pl
+ that: pl.latexindent
lookForThis: 0
when: before
@@ -619,28 +623,28 @@
# is central to latexindent.pl
fineTuning:
environments:
- name: '[a-zA-Z@\*0-9_\\]+'
+ name: [a-zA-Z@\*0-9_\\]+
ifElseFi:
- name: '(?!@?if[a-zA-Z@]*?\{)@?if[a-zA-Z@]*?'
+ name: (?!@?if[a-zA-Z@]*?\{)@?if[a-zA-Z@]*?
commands:
- name: '[+a-zA-Z@\*0-9_\:]+?'
+ name: [+a-zA-Z@\*0-9_\:]+?
items:
- canBeFollowedBy: '(?:\[[^]]*?\])|(?:<[^>]*?>)'
+ canBeFollowedBy: (?:\[[^]]*?\])|(?:<[^>]*?>)
keyEqualsValuesBracesBrackets:
- name: '[a-zA-Z@\*0-9_\/.:\#-]+[a-zA-Z@\*0-9_\/.\h\{\}:\#-]*?'
- follow: '(?:(?<!\\)\{)|,|(?:(?<!\\)\[)'
+ name: [a-zA-Z@\*0-9_\/.:\#-]+[a-zA-Z@\*0-9_\/.\h\{\}:\#-]*?
+ follow: (?:(?<!\\)\{)|,|(?:(?<!\\)\[)
namedGroupingBracesBrackets:
- name: '[0-9\.a-zA-Z@\*><]+?'
- follow: '\h|\R|\{|\[|\$|\)|\('
+ name: [0-9\.a-zA-Z@\*><]+?
+ follow: \h|\R|\{|\[|\$|\)|\(
UnNamedGroupingBracesBrackets:
- follow: '\{|\[|,|&|\)|\(|\$'
+ follow: \{|\[|,|&|\)|\(|\$
arguments:
- before: '(?:#\d\h*;?,?\/?)+|\<.*?\>'
- between: '_|\^|\*'
+ before: (?:#\d\h*;?,?\/?)+|\<.*?\>
+ between: _|\^|\*
trailingComments:
- notPreceededBy: '(?<!\\)'
+ notPreceededBy: (?<!\\)
modifyLineBreaks:
- doubleBackSlash: '\\\\(?:\h*\[\h*\d+\h*[a-zA-Z]+\h*\])?'
+ doubleBackSlash: \\\\(?:\h*\[\h*\d+\h*[a-zA-Z]+\h*\])?
comma: ','
betterFullStop: |-
(?x) # ignore spaces in the below
Modified: trunk/Master/texmf-dist/scripts/latexindent/latexindent.pl
===================================================================
(Binary files differ)
More information about the tex-live-commits
mailing list.