texlive[65208] trunk: latexindent (5dec22)
commits+karl at tug.org
commits+karl at tug.org
Mon Dec 5 22:30:11 CET 2022
Revision: 65208
http://tug.org/svn/texlive?view=revision&revision=65208
Author: karl
Date: 2022-12-05 22:30:10 +0100 (Mon, 05 Dec 2022)
Log Message:
-----------
latexindent (5dec22)
Modified Paths:
--------------
trunk/Build/source/texk/texlive/linked_scripts/Makefile.am
trunk/Build/source/texk/texlive/linked_scripts/Makefile.in
trunk/Build/source/texk/texlive/linked_scripts/latexindent/latexindent.pl
trunk/Build/source/texk/texlive/linked_scripts/scripts.lst
trunk/Master/bin/win32/latexindent.exe
trunk/Master/texmf-dist/doc/support/latexindent/README
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/ModifyLineBreaks.pm
trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Version.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/Makefile.am
===================================================================
--- trunk/Build/source/texk/texlive/linked_scripts/Makefile.am 2022-12-05 21:25:15 UTC (rev 65207)
+++ trunk/Build/source/texk/texlive/linked_scripts/Makefile.am 2022-12-05 21:30:10 UTC (rev 65208)
@@ -133,6 +133,7 @@
ctanupload/ctanupload.pl \
de-macro/de-macro \
diadia/diadia.lua \
+ digestif/digestif.texlua \
dosepsbin/dosepsbin.pl \
dviasm/dviasm.py \
dviinfox/dviinfox.pl \
Modified: trunk/Build/source/texk/texlive/linked_scripts/Makefile.in
===================================================================
--- trunk/Build/source/texk/texlive/linked_scripts/Makefile.in 2022-12-05 21:25:15 UTC (rev 65207)
+++ trunk/Build/source/texk/texlive/linked_scripts/Makefile.in 2022-12-05 21:30:10 UTC (rev 65208)
@@ -347,6 +347,7 @@
ctanupload/ctanupload.pl \
de-macro/de-macro \
diadia/diadia.lua \
+ digestif/digestif.texlua \
dosepsbin/dosepsbin.pl \
dviasm/dviasm.py \
dviinfox/dviinfox.pl \
Modified: trunk/Build/source/texk/texlive/linked_scripts/latexindent/latexindent.pl
===================================================================
(Binary files differ)
Modified: trunk/Build/source/texk/texlive/linked_scripts/scripts.lst
===================================================================
--- trunk/Build/source/texk/texlive/linked_scripts/scripts.lst 2022-12-05 21:25:15 UTC (rev 65207)
+++ trunk/Build/source/texk/texlive/linked_scripts/scripts.lst 2022-12-05 21:30:10 UTC (rev 65208)
@@ -72,6 +72,7 @@
ctanupload/ctanupload.pl
de-macro/de-macro
diadia/diadia.lua
+digestif/digestif.texlua
dosepsbin/dosepsbin.pl
dviasm/dviasm.py
dviinfox/dviinfox.pl
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 2022-12-05 21:25:15 UTC (rev 65207)
+++ trunk/Master/texmf-dist/doc/support/latexindent/README 2022-12-05 21:30:10 UTC (rev 65208)
@@ -1,5 +1,5 @@
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
- latexindent.pl, version 3.19, 2022-10-30
+ latexindent.pl, version 3.19.1, 2022-12-04
PERL script to indent code within environments, and align delimited
environments in .tex files.
Modified: trunk/Master/texmf-dist/doc/support/latexindent/latexindent-yaml-schema.json
===================================================================
--- trunk/Master/texmf-dist/doc/support/latexindent/latexindent-yaml-schema.json 2022-12-05 21:25:15 UTC (rev 65207)
+++ trunk/Master/texmf-dist/doc/support/latexindent/latexindent-yaml-schema.json 2022-12-05 21:30:10 UTC (rev 65208)
@@ -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 2022-10-30",
+ "description": "latexindent.pl YAML schema helper, V3.19.1 2022-12-04",
"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 2022-12-05 21:25:15 UTC (rev 65207)
+++ trunk/Master/texmf-dist/doc/support/latexindent/latexindent.tex 2022-12-05 21:30:10 UTC (rev 65208)
@@ -289,10 +289,12 @@
% command shell
\newtcblisting{commandshell}{colback=black,colupper=white,colframe=yellow!75!black,
- listing only,listing options={style=tcblatex,language=sh,
+ listing only,
+ listing options={style=tcblatex,language=sh,
morekeywords={latexindent,pl},
keywordstyle=\color{blue!35!white}\bfseries,
},
+ before=\par,
listing engine=listings,
left=0cm,
every listing line={\textcolor{red}{\small\ttfamily\fontseries{b}\selectfont cmh:$\sim$\$ }}}
@@ -561,28 +563,27 @@
\newtcolorbox[auto counter]{example}{breakable,
enhanced jigsaw,
- before skip=6pt,after skip=6pt,
+ before skip balanced,
+ after skip balanced,
frame hidden,
- title={\llap{Example~\thetcbcounter\hspace{3mm}}},
- fonttitle=\bfseries,
+ %
+ % title stuff
+ %
+ title={example~\thetcbcounter},
+ fonttitle=\bfseries\sffamily,
+ detach title,
+ before upper={\llap{\tcbtitle\hspace{5mm}}},
coltitle=black,
- attach title to upper,
- grow to left by=5mm,
- top=3mm,
+ colback=white,
+ grow to left by=6mm,
+ %
+ % circles and line by the side
+ %
overlay unbroken={%
- \draw[thick,cmhgray] ([xshift=3mm]interior.north east)--([xshift=3mm]interior.south east);
- \path [fill=cmhgray] ([xshift=3mm]interior.north east) circle (.5mm);
- \path [fill=cmhgray] ([xshift=3mm]interior.south east) circle (1mm);
+ \path [fill=black] ([xshift=1mm,yshift=3mm]interior.south east) node{\hbox{\rule{1ex}{1ex}}};
},
- overlay first={%
- \draw[thick,cmhgray] ([xshift=3mm]interior.north east)--([xshift=3mm]interior.south east);
- \path [fill=cmhgray] ([xshift=3mm]interior.north east) circle (.5mm);
- %\path [draw=cmhgray,fill=white] ([xshift=3mm]interior.south east) circle (.5mm);
- },
overlay last={%
- \draw[thick,cmhgray] ([xshift=3mm]interior.north east)--([xshift=3mm]interior.south east);
- %\path [fill=white,draw=cmhgray] ([xshift=3mm]interior.north east) circle (.5mm);
- \path [fill=cmhgray] ([xshift=3mm]interior.south east) circle (1mm);
+ \path [fill=black] ([xshift=1mm,yshift=3mm]interior.south east) node{\hbox{\rule{1ex}{1ex}}};
},
parbox=false,
}
@@ -845,9 +846,11 @@
\subsection{Quick start}\label{sec:quickstart}
If you'd like to get started with \texttt{latexindent.pl} then simply type
+
\begin{commandshell}
latexindent.pl myfile.tex
\end{commandshell}
+
from the command line.
We give an introduction to \texttt{latexindent.pl} using \cref{lst:quick-start}; there is
@@ -857,107 +860,123 @@
\cmhlistingsfromfile{demonstrations/quick-start.tex}{\texttt{quick-start.tex}}{lst:quick-start}
Running
+
\begin{commandshell}
latexindent.pl quick-start.tex
\end{commandshell}
+
gives \cref{lst:quick-start-default}.
\cmhlistingsfromfile{demonstrations/quick-start-default.tex}{\texttt{quick-start-default.tex}}{lst:quick-start-default}
\begin{example}
- Running
- \begin{commandshell}
+ Running
+
+ \begin{commandshell}
latexindent.pl -l quick-start1.yaml quick-start.tex
\end{commandshell}
- 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}
- \end{cmhtcbraster}
+ 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}
+ \end{cmhtcbraster}
\end{example}
\begin{example}
- Running
- \begin{commandshell}
+ Running
+
+ \begin{commandshell}
latexindent.pl -l quick-start2.yaml quick-start.tex
\end{commandshell}
- 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}
- \end{cmhtcbraster}
+ 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}
+ \end{cmhtcbraster}
\end{example}
\begin{example}
- Running
- \begin{commandshell}
+ Running
+
+ \begin{commandshell}
latexindent.pl -l quick-start3.yaml quick-start.tex
\end{commandshell}
- 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}
- \end{cmhtcbraster}
+ 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}
+ \end{cmhtcbraster}
\end{example}
\begin{example}
- Running
- \begin{commandshell}
+ Running
+
+ \begin{commandshell}
latexindent.pl -m -l quick-start4.yaml quick-start.tex
\end{commandshell}
- 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}
- \end{cmhtcbraster}
- Full details of text wrapping in \cref{subsec:textwrapping}.
+ 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}
+ \end{cmhtcbraster}
+ Full details of text wrapping in \cref{subsec:textwrapping}.
\end{example}
\begin{example}
- Running
- \begin{commandshell}
+ Running
+
+ \begin{commandshell}
latexindent.pl -m -l quick-start5.yaml quick-start.tex
\end{commandshell}
- 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}
- \end{cmhtcbraster}
- Full details of text wrapping in \cref{subsec:textwrapping}.
+ 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}
+ \end{cmhtcbraster}
+ Full details of text wrapping in \cref{subsec:textwrapping}.
\end{example}
\begin{example}
- Running
- \begin{commandshell}
+ Running
+
+ \begin{commandshell}
latexindent.pl -m -l quick-start6.yaml quick-start.tex
\end{commandshell}
- 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}
- \end{cmhtcbraster}
- This is an example of a \emph{poly-switch}; full details of \emph{poly-switches} are
- covered in \cref{sec:poly-switches}.
+ 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}
+ \end{cmhtcbraster}
+ This is an example of a \emph{poly-switch}; full details of \emph{poly-switches} are
+ covered in \cref{sec:poly-switches}.
\end{example}
\begin{example}
- Running
- \begin{commandshell}
+ Running
+
+ \begin{commandshell}
latexindent.pl -m -l quick-start7.yaml quick-start.tex
\end{commandshell}
- 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}
- \end{cmhtcbraster}
- Full details of \emph{poly-switches} are covered in \cref{sec:poly-switches}.
+ 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}
+ \end{cmhtcbraster}
+ Full details of \emph{poly-switches} are covered in \cref{sec:poly-switches}.
\end{example}
\subsection{Required perl modules}
@@ -969,9 +988,11 @@
\end{cmhlistings}
\texttt{latexindent.pl} ships with a script to help with this process; if you run the
following script, you should be prompted to install the appropriate modules.
+
\begin{commandshell}
perl latexindent-module-installer.pl
\end{commandshell}
+
You might also like to see
\href{https://stackoverflow.com/questions/19590042/error-cant-locate-file-homedir-pm-in-inc}{https://stackoverflow.com/questions/19590042/error-cant-locate-file-homedir-pm-in-inc},
for example, as well as \vref{sec:requiredmodules}.
@@ -1152,19 +1173,23 @@
\flagbox{-v, --version}
\index{switches!-v, --version definition and details}
\announce{2017-06-25}{version}
+
\begin{commandshell}
latexindent.pl -v
latexindent.pl --version
\end{commandshell}
+
This will output only the version number to the terminal.
\flagbox{-vv, --vversion}
\index{switches!-vv, --vversion definition and details}
\announce{2022-01-08}{vversion switch}
+
\begin{commandshell}
latexindent.pl -vv
latexindent.pl --vversion
\end{commandshell}
+
This will output \emph{verbose} version details to the terminal, including the location
of \texttt{latexindent.pl} and \texttt{defaultSettings.yaml}.
@@ -1178,6 +1203,7 @@
As above this will output a welcome message to the terminal, including the version number
and available options.
+
\begin{commandshell}
latexindent.pl myfile.tex
\end{commandshell}
@@ -1188,14 +1214,17 @@
You can \announce{2022-03-25}{batches of files demonstration} instruct
\texttt{latexindent.pl} to operate on multiple (batches) of files, for example
+
\begin{commandshell}
latexindent.pl myfile1.tex myfile2.tex
\end{commandshell}
+
Full details are given in \vref{sec:batches}.
\flagbox{-w, --overwrite}
\index{switches!-w, --overwrite definition and details}
\index{backup files!overwrite switch, -w}
+
\begin{commandshell}
latexindent.pl -w myfile.tex
latexindent.pl --overwrite myfile.tex
@@ -1216,6 +1245,7 @@
\index{switches!-wd, --overwriteIfDifferent definition and details}
\index{backup files!overwriteIfDifferent switch, -wd}
\announce{2022-03-25}{overwriteIfDifferent switch}
+
\begin{commandshell}
latexindent.pl -wd myfile.tex
latexindent.pl --overwriteIfDifferent myfile.tex
@@ -1232,6 +1262,7 @@
\flagbox{-o=output.tex,--outputfile=output.tex}
\index{switches!-o, --output definition and details}
+
\begin{commandshell}
latexindent.pl -o=output.tex myfile.tex
latexindent.pl myfile.tex -o=output.tex
@@ -1249,6 +1280,7 @@
\texttt{-o} switch takes priority over it.
Note that using \texttt{-o} as above is equivalent to using
+
\begin{commandshell}
latexindent.pl myfile.tex > output.tex
\end{commandshell}
@@ -1257,6 +1289,7 @@
extension; in \announce{2017-06-25}{upgrade to -o switch} this case,
\texttt{latexindent.pl} will use the extension from the original file. For example, the
following two calls to \texttt{latexindent.pl} are equivalent:%
+
\begin{commandshell}
latexindent.pl myfile.tex -o=output
latexindent.pl myfile.tex -o=output.tex
@@ -1266,6 +1299,7 @@
\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}
latexindent.pl myfile.tex -o=+new
latexindent.pl myfile.tex -o=myfilenew.tex
@@ -1275,29 +1309,36 @@
\announce{2017-06-25}{++ in o switch} of your output file; this tells
\texttt{latexindent.pl} to search successively for the name of your output file
concatenated with $0, 1, \ldots$ while the name of the output file exists. For example,%
+
\begin{commandshell}
latexindent.pl myfile.tex -o=output++
\end{commandshell}
+
tells \texttt{latexindent.pl} to output to \texttt{output0.tex}, but if it exists then
output to \texttt{output1.tex}, and so on.
Calling \texttt{latexindent.pl} with simply
+
\begin{commandshell}
latexindent.pl myfile.tex -o=++
\end{commandshell}
+
tells it to output to \texttt{myfile0.tex}, but if it exists then output to
\texttt{myfile1.tex} and so on.
The \texttt{+} and \texttt{++} feature of the \texttt{-o} switch can be combined; for
example, calling
+
\begin{commandshell}
latexindent.pl myfile.tex -o=+out++
\end{commandshell}
+
tells \texttt{latexindent.pl} to output to \texttt{myfileout0.tex}, but if it exists,
then try \texttt{myfileout1.tex}, and so on.
There is no need to specify a file extension when using the \texttt{++} feature, but if
you wish to, then you should include it \emph{after} the \texttt{++} symbols, for example
+
\begin{commandshell}
latexindent.pl myfile.tex -o=+out++.tex
\end{commandshell}
@@ -1305,6 +1346,7 @@
See \vref{app:differences} for details of how the interface has changed from Version 2.2
to Version 3.0 for this flag. \flagbox{-s, --silent} \index{switches!-s, --silent
definition and details}
+
\begin{commandshell}
latexindent.pl -s myfile.tex
latexindent.pl myfile.tex -s
@@ -1314,6 +1356,7 @@
\flagbox{-t, --trace}
\index{switches!-t, --trace definition and details}
+
\begin{commandshell}
latexindent.pl -t myfile.tex
latexindent.pl myfile.tex -t
@@ -1328,6 +1371,7 @@
\flagbox{-tt, --ttrace}
\index{switches!-tt, --ttrace definition and details}
+
\begin{commandshell}
latexindent.pl -tt myfile.tex
latexindent.pl myfile.tex -tt
@@ -1340,6 +1384,7 @@
\flagbox{-l, --local[=myyaml.yaml,other.yaml,...]}
\index{switches!-l, --local definition and details}
+
\begin{commandshell}
latexindent.pl -l myfile.tex
latexindent.pl -l=myyaml.yaml myfile.tex
@@ -1366,35 +1411,45 @@
the current working directory that is \emph{not} called \texttt{localSettings.yaml}.
\announce{2017-08-21}*{-l switch absolute paths} In fact, you can specify both
\emph{relative} and \emph{absolute paths} for your YAML files; for example%
+
\begin{commandshell}
latexindent.pl -l=../../myyaml.yaml myfile.tex
latexindent.pl -l=/home/cmhughes/Desktop/myyaml.yaml myfile.tex
latexindent.pl -l=C:\Users\cmhughes\Desktop\myyaml.yaml myfile.tex
\end{commandshell}
+
You will find a lot of other explicit demonstrations of how to use the \texttt{-l} switch
throughout this documentation,
You 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:
+
\begin{commandshell}
latexindent.pl -l=+myyaml.yaml myfile.tex
latexindent.pl -l "+ myyaml.yaml" myfile.tex
latexindent.pl -l=myyaml.yaml+ myfile.tex
\end{commandshell}
+
which translate, respectively, to
+
\begin{commandshell}
latexindent.pl -l=localSettings.yaml,myyaml.yaml myfile.tex
latexindent.pl -l=localSettings.yaml,myyaml.yaml myfile.tex
latexindent.pl -l=myyaml.yaml,localSettings.yaml myfile.tex
\end{commandshell}
+
Note that the following is \emph{not} allowed:
+
\begin{commandshell}
latexindent.pl -l+myyaml.yaml myfile.tex
\end{commandshell}
+
and
+
\begin{commandshell}
latexindent.pl -l + myyaml.yaml myfile.tex
\end{commandshell}
+
will \emph{only} load \texttt{localSettings.yaml}, and \texttt{myyaml.yaml} will be
ignored. If you wish to use spaces between any of the YAML settings, then you must wrap
the entire list of YAML files in quotes, as demonstrated above.
@@ -1401,13 +1456,16 @@
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
\end{commandshell}
+
\flagbox{-y, --yaml=yaml settings}
\index{switches!-y, --yaml definition and details}
\index{indentation!default}
\index{indentation!defaultIndent using -y switch}
+
\begin{commandshell}
latexindent.pl myfile.tex -y="defaultIndent: ' '"
latexindent.pl myfile.tex -y="defaultIndent: ' ',maximumIndentation:' '"
@@ -1415,6 +1473,7 @@
latexindent.pl myfile.tex -y='modifyLineBreaks:environments:EndStartsOnOwnLine:3' -m
latexindent.pl myfile.tex -y='modifyLineBreaks:environments:one:EndStartsOnOwnLine:3' -m
\end{commandshell}
+
\label{page:yamlswitch}You%
\announce{2017-08-21}{the -y switch} can specify YAML settings from the command line
using the \texttt{-y} or \texttt{--yaml} switch; sample demonstrations are given above.
@@ -1425,6 +1484,7 @@
Any settings specified via this switch will be loaded \emph{after} any specified using
the \texttt{-l} switch. This is discussed further in \vref{sec:loadorder}. \flagbox{-d,
--onlydefault} \index{switches!-d, --onlydefault definition and details}
+
\begin{commandshell}
latexindent.pl -d myfile.tex
\end{commandshell}
@@ -1441,6 +1501,7 @@
\flagbox{-c, --cruft=<directory>}
\index{switches!-c, --cruft definition and details}
+
\begin{commandshell}
latexindent.pl -c=/path/to/directory/ myfile.tex
\end{commandshell}
@@ -1451,6 +1512,7 @@
\flagbox{-g, --logfile=<name of log file>}
\index{switches!-g, --logfile definition and details}
+
\begin{commandshell}
latexindent.pl -g=other.log myfile.tex
latexindent.pl -g other.log myfile.tex
@@ -1465,6 +1527,7 @@
\announce{2021-05-07}{log file creation updated} If \texttt{latexindent.pl} can not open
the log file that you specify, then the script will operate, and no log file will be
produced; this might be helpful to users who wish to specify the following, for example
+
\begin{commandshell}
latexindent.pl -g /dev/null myfile.tex
\end{commandshell}
@@ -1471,10 +1534,12 @@
\flagbox{-sl, --screenlog}
\index{switches!-sl, --screenlog definition and details}
+
\begin{commandshell}
latexindent.pl -sl myfile.tex
latexindent.pl -screenlog myfile.tex
\end{commandshell}
+
Using this \announce{2018-01-13}{screenlog switch created} option tells
\texttt{latexindent.pl} to output the log file to the screen, as well as to your chosen
log file.%
@@ -1481,6 +1546,7 @@
\flagbox{-m, --modifylinebreaks}
\index{switches!-m, --modifylinebreaks definition and details}
+
\begin{commandshell}
latexindent.pl -m myfile.tex
latexindent.pl -modifylinebreaks myfile.tex
@@ -1491,15 +1557,19 @@
\texttt{latexindent.pl} can also be called on a file without the file extension, for
example
+
\begin{commandshell}
latexindent.pl myfile
\end{commandshell}
+
and in which case, you can specify the order in which extensions are searched for; see
\vref{lst:fileExtensionPreference} for full details. \flagbox{STDIN}
+
\begin{commandshell}
cat myfile.tex | latexindent.pl
cat myfile.tex | latexindent.pl -
\end{commandshell}
+
\texttt{latexindent.pl} will%
\announce{2018-01-13}{STDIN allowed} allow input from STDIN, which means that you can
pipe output from other commands directly into the script. For example assuming that you
@@ -1508,6 +1578,7 @@
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 -
\end{commandshell}
@@ -1515,6 +1586,7 @@
Similarly, if you \announce{2018-01-13}*{no options/filename updated} simply type
\texttt{latexindent.pl} at the command line, then it will expect (STDIN) input from the
command line.%
+
\begin{commandshell}
latexindent.pl
\end{commandshell}
@@ -1527,10 +1599,12 @@
to signify that your input has finished. Thanks to \cite{xu-cheng} for an update to this
feature. \flagbox{-r, --replacement} \index{switches!-r, --replacement definition and
details}
+
\begin{commandshell}
latexindent.pl -r myfile.tex
latexindent.pl -replacement myfile.tex
\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,
@@ -1538,10 +1612,12 @@
\flagbox{-rv, --replacementrespectverb}
\index{switches!-rv, --replacementrespectverb definition and details}
+
\begin{commandshell}
latexindent.pl -rv myfile.tex
latexindent.pl -replacementrespectverb myfile.tex
\end{commandshell}
+
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
@@ -1549,10 +1625,12 @@
\flagbox{-rr, --onlyreplacement}
\index{switches!-rr, --onlyreplacement definition and details}
+
\begin{commandshell}
latexindent.pl -rr myfile.tex
latexindent.pl -onlyreplacement myfile.tex
\end{commandshell}
+
You can \announce{2019-07-13}{replacement (only) mode switch} instruct
\texttt{latexindent.pl} to skip all of its other indentation operations and \emph{only}
perform replacements/substitutions by using the \texttt{-rr} switch; full details and
@@ -1560,10 +1638,12 @@
\flagbox{-k, --check}
\index{switches!-k, --check definition and details}
+
\begin{commandshell}
latexindent.pl -k myfile.tex
latexindent.pl -check myfile.tex
\end{commandshell}
+
You can \announce{2021-09-16}{-k,-check switch} instruct \texttt{latexindent.pl} to check
if the text after indentation matches that given in the original file.%
@@ -1584,10 +1664,12 @@
\flagbox{-kv, --checkv}
\index{switches!-kv, --checkv definition and details}
+
\begin{commandshell}
latexindent.pl -kv myfile.tex
latexindent.pl -checkv myfile.tex
\end{commandshell}
+
\announce{2021-09-16}{-kv, -checkv: check verbose switch} The \texttt{check verbose}
switch is exactly the same as the \texttt{-k} switch, except that it is \emph{verbose},
and it will output the (simple) diff to the terminal, as well as to \texttt{indent.log}.
@@ -1594,10 +1676,12 @@
\flagbox{-n, --lines=MIN-MAX}
\index{switches!-n, --lines definition and details}
+
\begin{commandshell}
latexindent.pl -n 5-8 myfile.tex
latexindent.pl -lines 5-8 myfile.tex
\end{commandshell}
+
\announce{2021-09-16}{-n, -lines switch} The \texttt{lines} switch instructs
\texttt{latexindent.pl} to operate only on specific line ranges within
\texttt{myfile.tex}.
@@ -1606,9 +1690,11 @@
\flagbox{--GCString}
\index{switches!--GCString}
+
\begin{commandshell}
latexindent.pl --GCString myfile.tex
\end{commandshell}
+
\announce{2022-03-25}{GCString switch} instructs \texttt{latexindent.pl} to load the
\texttt{Unicode::GCString} module. This should only be necessary if you find that the
alignment at ampersand routine (described in \cref{subsec:align-at-delimiters}) does not
@@ -1622,9 +1708,11 @@
\subsection{Summary of exit codes}
\index{exit code!summary}
Assuming that you call \texttt{latexindent.pl} on \texttt{myfile.tex}
+
\begin{commandshell}
latexindent.pl myfile.tex
\end{commandshell}
+
then \texttt{latexindent.pl} can exit with the exit codes given in \cref{tab:exit-codes}.
\begin{table}[!htb]
@@ -1746,9 +1834,11 @@
\announce{2021-03-14}*{-l
switch: localSettings and friends} example, if you use the following command
\index{switches!-l demonstration}
+
\begin{commandshell}
latexindent.pl -l myfile.tex
\end{commandshell}
+
then \texttt{latexindent.pl} will search for and then, assuming they exist, load each of
the following files in the following order:
\begin{enumerate}
@@ -1766,6 +1856,7 @@
If you'd prefer to name your \texttt{localSettings.yaml} file something different, (say,
\texttt{mysettings.yaml} as in \cref{lst:mysettings}) then you can call
\texttt{latexindent.pl} using, for example,
+
\begin{commandshell}
latexindent.pl -l=mysettings.yaml myfile.tex
\end{commandshell}
@@ -1797,21 +1888,27 @@
specify the settings from \cref{lst:localSettings} using the \texttt{-y} switch, then you
could use the following command:
\index{verbatim!verbatimEnvironments demonstration (-y switch)}
+
\begin{commandshell}
latexindent.pl -y="verbatimEnvironments:cmhenvironment:0;myenv:1" myfile.tex
\end{commandshell}
+
Note the use of \texttt{;} to specify another field within \texttt{verbatimEnvironments}.
This is shorthand, and equivalent, to using the following command: \index{switches!-y
demonstration}
+
\begin{commandshell}
latexindent.pl -y="verbatimEnvironments:cmhenvironment:0,verbatimEnvironments:myenv:1" myfile.tex
\end{commandshell}
+
You may, of course, specify settings using the \texttt{-y} switch as well as, for
example, settings loaded using the \texttt{-l} switch; for example, \index{switches!-l
demonstration} \index{switches!-y demonstration}
+
\begin{commandshell}
latexindent.pl -l=mysettings.yaml -y="verbatimEnvironments:cmhenvironment:0;myenv:1" myfile.tex
\end{commandshell}
+
Any settings specified using the \texttt{-y} switch will be loaded \emph{after} any
specified using \texttt{indentconfig.yaml} and the \texttt{-l} switch.
@@ -1821,6 +1918,7 @@
(\vref{sec:onesentenceperline}) and the listings within \vref{lst:sentencesEndWith}, the
following settings give the option to have sentences end with a semicolon
\index{switches!-y demonstration}
+
\begin{commandshell}
latexindent.pl -m --yaml='modifyLineBreaks:oneSentencePerLine:sentencesEndWith:other:\;'
\end{commandshell}
@@ -1876,9 +1974,11 @@
\yamltitle{fileExtensionPreference}*{fields}
\texttt{latexindent.pl} can be called to
act on a file without specifying the file extension. For example we can call
+
\begin{commandshell}
latexindent.pl myfile
\end{commandshell}
+
in which case the script will look for \texttt{myfile} with the extensions specified in
\texttt{fileExtensionPreference} in their numeric order. If no match is found, the script
will exit. As with all of the fields, you should change and/or add to this as necessary.
@@ -1936,6 +2036,7 @@
copy myfile.bak3 to myfile.bak2
copy myfile.bak4 to myfile.bak3
\end{commandshell}
+
The default value of \texttt{cycleThroughBackUps} is \texttt{0}.
\yamltitle{logFilePreferences}*{fields}
@@ -1992,6 +2093,7 @@
\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
\texttt{latexcode}, \texttt{latexcode*}, \texttt{pythoncode} and \texttt{pythoncode*},
then the listings given in \cref{lst:nameAsRegex1,lst:nameAsRegex2} are equivalent.
@@ -2010,6 +2112,7 @@
\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{verbatimCommands}*{fields}
A field that contains a list of commands that are verbatim commands, for example
@@ -2026,6 +2129,7 @@
\texttt{verbatimCommands} 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 commands
\texttt{verbinline}, \texttt{myinline} then the listings given in
\cref{lst:nameAsRegex3,lst:nameAsRegex4} are equivalent.
@@ -2044,6 +2148,7 @@
\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
@@ -2062,9 +2167,10 @@
Important note: it is assumed that the \texttt{noindent} block statements specified in
this way appear on their own line.
- The \announce{2021-06-19}{noIndentBlock specified as regex} \texttt{noIndentBlock} fields
- can also be specified in terms of \texttt{begin} and \texttt{end} fields. We use the code
- in \cref{lst:noIndentBlock1} to demonstrate this feature.%
+ \begin{example}
+ The \texttt{noIndentBlock} fields can also be specified in terms of \texttt{begin} and
+ \texttt{end} fields. We use the code in \cref{lst:noIndentBlock1} to demonstrate this
+ feature.\announce{2021-06-19}{noIndentBlock specified as regex}%
\cmhlistingsfromfile{demonstrations/noindentblock1.tex}{\texttt{noIndentBlock1.tex}}{lst:noIndentBlock1}
@@ -2080,14 +2186,18 @@
\end{cmhtcbraster}
Upon running the commands
+
\begin{commandshell}
latexindent.pl -l noindent1.yaml noindent1
latexindent.pl -l noindent2.yaml noindent1
\end{commandshell}
+
then we receive the output given in \cref{lst:noIndentBlock1-mod1}.
\cmhlistingsfromfile{demonstrations/noindentblock1-mod1.tex}{\texttt{noIndentBlock1.tex} using \cref{lst:noindent1} or \cref{lst:noindent2}}{lst:noIndentBlock1-mod1}
+ \end{example}
+
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
@@ -2097,15 +2207,20 @@
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
the command
+
\begin{commandshell}
latexindent.pl -l noindent3.yaml noindent1
\end{commandshell}
+
gives the output in \cref{lst:noIndentBlock1-mod3}.
\cmhlistingsfromfile{demonstrations/noindentblock1-mod3.tex}{\texttt{noIndentBlock1.tex} using \cref{lst:noindent3}}{lst:noIndentBlock1-mod3}
+ \end{example}
+
We will demonstrate this feature later in the documentation in \cref{lst:href3}.
You can, optionally, specify \announce{2021-10-30}{noIndentBlock name feature} the
@@ -2112,6 +2227,7 @@
\texttt{noIndentBlock} 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
\texttt{testnoindent}, \texttt{testnoindent*} then the listings given in
\cref{lst:nameAsRegex5,lst:nameAsRegex6} are equivalent.
@@ -2132,6 +2248,8 @@
\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}
\yamltitle{fileContentsEnvironments}*{field}
@@ -2193,15 +2311,10 @@
\vref{lst:removeTWS-before,lst:env-mlb5-modAll,lst:env-mlb5-modAll-remove-WS} for before
and after results. Thanks to \cite{vosskuhle} for providing this feature.
- \begin{minipage}{.4\textwidth}
+ \begin{cmhtcbraster}
\cmhlistingsfromfile[style=removeTrailingWhitespace]{../defaultSettings.yaml}[before=\centering,yaml-TCB]{removeTrailingWhitespace}{lst:removeTrailingWhitespace}
- \end{minipage}%
- \hfill
- \begin{minipage}{.5\textwidth}
- \begin{yaml}[numbers=none]{removeTrailingWhitespace (alt)}[before=\centering]{lst:removeTrailingWhitespace-alt}
-removeTrailingWhitespace: 1
-\end{yaml}
- \end{minipage}%
+ \cmhlistingsfromfile[style=yaml-LST]{demonstrations/remove-tws-alt.yaml}[yaml-TCB]{removeTrailingWhitespace (alt)}{lst:removeTrailingWhitespace-alt}
+ \end{cmhtcbraster}
You can specify \texttt{removeTrailingWhitespace} simply as \texttt{0} or \texttt{1}, if
you wish; in this case, \announce{2017-06-28}{removeTrailingWhitespace}
@@ -2233,6 +2346,11 @@
in \cref{sec:knownlimitations}), but in many cases it will produce results such as those
in \cref{lst:tabularbefore:basic,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}
+ \end{cmhtcbraster}
+
If you find that \texttt{latexindent.pl} does not perform satisfactorily on such
environments then you can set the relevant key to \texttt{0}, for example
\texttt{tabular: 0}; alternatively, if you just want to ignore \emph{specific} instances
@@ -2239,11 +2357,6 @@
of the environment, you could wrap them in something from \texttt{noIndentBlock} (see
\vref{lst:noIndentBlock}).
- \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}
- \end{cmhtcbraster}
-
If, for example, you wish to remove the alignment of the \lstinline!\\! within a
delimiter-aligned block, then the advanced form of \texttt{lookForAlignDelims} shown in
\cref{lst:aligndelims:advanced} is for you. \index{regular expressions!delimiterRegEx}
@@ -2303,6 +2416,7 @@
discussed in \cref{sec:lookForChildCodeBlocks}.
\end{itemize}
+ \begin{example}
We will explore most of these features using the file \texttt{tabular2.tex} in
\cref{lst:tabular2} (which contains a \lstinline!\multicolumn! command), and the YAML
files in \crefrange{lst:tabular2YAML}{lst:tabular8YAML}; we will explore
@@ -2341,6 +2455,7 @@
On running the commands \index{delimiters!spacing demonstration} \index{switches!-l
demonstration}
+
\begin{commandshell}
latexindent.pl tabular2.tex
latexindent.pl tabular2.tex -l tabular2.yaml
@@ -2351,6 +2466,7 @@
latexindent.pl tabular2.tex -l tabular2.yaml,tabular7.yaml
latexindent.pl tabular2.tex -l tabular2.yaml,tabular8.yaml
\end{commandshell}
+
we obtain the respective outputs given in
\crefrange{lst:tabular2-default}{lst:tabular2-mod8}.
@@ -2395,6 +2511,7 @@
above and below the \lstinline!\multicol! statements have still been group correctly,
because of the settings in \cref{lst:tabular2YAML}.
\end{itemize}
+ \end{example}
\subsubsection{lookForAlignDelims: spacesBeforeAmpersand}
The \texttt{spacesBeforeAmpersand} \announce{2021-06-19}*{spacesBeforeAmpersand leading
@@ -2404,11 +2521,14 @@
column}; that is, when the first column contains only zero-width entries. We refer to
this as the \emph{advanced} form.%
+ \begin{example}
We demonstrate this feature in relation to \cref{lst:aligned1}; upon running the
following command
+
\begin{commandshell}
latexindent.pl aligned1.tex -o=+-default
\end{commandshell}
+
then we receive the default output given in \cref{lst:aligned1-default}.
\begin{cmhtcbraster}
@@ -2426,6 +2546,7 @@
\cmhlistingsfromfile{demonstrations/sba4.yaml}[yaml-TCB]{\texttt{sba4.yaml}}{lst:sba4}
\end{cmhtcbraster}
Upon running the following commands
+
\begin{commandshell}
latexindent.pl aligned1.tex -l sba1.yaml
latexindent.pl aligned1.tex -l sba2.yaml
@@ -2432,6 +2553,7 @@
latexindent.pl aligned1.tex -l sba3.yaml
latexindent.pl aligned1.tex -l sba4.yaml
\end{commandshell}
+
then we receive the (same) output given in \cref{lst:aligned1-mod1}; we note that there
is \emph{one space} before each ampersand.
@@ -2459,6 +2581,9 @@
We note that \emph{default} has not been specified, and it will be set to \texttt{1} by
default.
\end{itemize}
+ \end{example}
+
+ \begin{example}
We can customise the space before the ampersand in the \emph{leading blank column} of
\cref{lst:aligned1-mod1} by using either of \cref{lst:sba5,lst:sba6}, which are
equivalent.
@@ -2469,10 +2594,12 @@
\end{cmhtcbraster}
Upon running
+
\begin{commandshell}
latexindent.pl aligned1.tex -l sba5.yaml
latexindent.pl aligned1.tex -l sba6.yaml
\end{commandshell}
+
then we receive the (same) output given in \cref{lst:aligned1-mod5}. We note that the
space before the ampersand in the \emph{leading blank column} has been set to \texttt{0}
by \cref{lst:sba6}.
@@ -2487,15 +2614,23 @@
\cmhlistingsfromfile{demonstrations/aligned1-mod7.tex}{\texttt{aligned1.tex} using \cref{lst:sba7}}{lst:aligned1-mod7}
\cmhlistingsfromfile{demonstrations/sba7.yaml}[yaml-TCB]{\texttt{sba7.yaml}}{lst:sba7}
\end{cmhtcbraster}
+ \end{example}
+
\subsubsection{lookForAlignDelims: alignFinalDoubleBackSlash}
- We explore \announce{2020-03-21}{alignFinalDoubleBackSlash demonstration} the
- \texttt{alignFinalDoubleBackSlash} feature by using the file in \cref{lst:tabular4}. Upon
- running the following commands \index{delimiters!double backslash demonstration}
- \index{switches!-y demonstration} \index{switches!-o demonstration}%
+ There may be times when a line of a code block contains more than \lstinline!\\!, and in
+ which case, you may want the \emph{final} double backslash to be aligned.
+
+ \begin{example}
+ We explore the \texttt{alignFinalDoubleBackSlash} feature by using the file in
+ \cref{lst:tabular4}. Upon running the following commands \index{delimiters!double
+ backslash demonstration} \index{switches!-y demonstration} \index{switches!-o
+ demonstration}\announce{2020-03-21}{alignFinalDoubleBackSlash demonstration}%
+
\begin{commandshell}
latexindent.pl tabular4.tex -o=+-default
latexindent.pl tabular4.tex -o=+-FDBS -y="lookForAlignDelims:tabular:alignFinalDoubleBackSlash:1"
\end{commandshell}
+
then we receive the respective outputs given in \cref{lst:tabular4-default} and
\cref{lst:tabular4-FDBS}.
@@ -2515,15 +2650,21 @@
\item \cref{lst:tabular4-FDBS}, the \emph{final} set of double back slashes 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
- \cpageref{yaml:specialBeginEnd}); for example, assuming that you have a command called
- \lstinline!\matrix! and that it is populated within \texttt{lookForAlignDelims} (which it
- is, by default), and that you run the command
+ \cpageref{yaml:specialBeginEnd}).
+
+ \begin{example}
+ Assuming that you have a command called \lstinline!\matrix! and that it is populated
+ within \texttt{lookForAlignDelims} (which it is, by default), and that you run the
+ command
+
\begin{commandshell}
latexindent.pl matrix1.tex
\end{commandshell}
+
then the before-and-after results shown in \cref{lst:matrixbefore,lst:matrixafter} are
achievable by default.
@@ -2531,6 +2672,7 @@
\cmhlistingsfromfile{demonstrations/matrix1.tex}{\texttt{matrix1.tex}}{lst:matrixbefore}
\cmhlistingsfromfile{demonstrations/matrix1-default.tex}{\texttt{matrix1.tex} default output}{lst:matrixafter}
\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}!,
@@ -2552,10 +2694,13 @@
\subsubsection{lookForAlignDelims: the dontMeasure feature}\label{sec:dontMeasure}
The \announce{2020-03-21}{don't measure feature} \texttt{lookForAlignDelims} field can,
optionally, receive the \texttt{dontMeasure} option which can be specified in a few
- different ways. We will explore this feature in relation to the code given in
- \cref{lst:tabular-DM}; the default output is shown in \cref{lst:tabular-DM-default}.
- \index{delimiters!dontMeasure feature}%
+ different ways.
+ \begin{example}
+ We will explore this feature in relation to the code given in \cref{lst:tabular-DM}; the
+ default output is shown in \cref{lst:tabular-DM-default}. \index{delimiters!dontMeasure
+ feature}%
+
\begin{cmhtcbraster}[raster left skip=-1.5cm,]
\cmhlistingsfromfile{demonstrations/tabular-DM.tex}{\texttt{tabular-DM.tex}}{lst:tabular-DM}
\cmhlistingsfromfile{demonstrations/tabular-DM-default.tex}{\texttt{tabular-DM.tex} default output}{lst:tabular-DM-default}
@@ -2564,9 +2709,11 @@
The \texttt{dontMeasure} field can be specified as \texttt{largest}, and in which case,
the largest element will not be measured; with reference to the YAML file given in
\cref{lst:dontMeasure1}, we can run the command \index{switches!-l demonstration}
+
\begin{commandshell}
latexindent.pl tabular-DM.tex -l=dontMeasure1.yaml
\end{commandshell}
+
and receive the output given in \cref{lst:tabular-DM-mod1}.
\begin{cmhtcbraster}
@@ -2576,13 +2723,17 @@
We note that the \emph{largest} column entries have not contributed to the measuring
routine.
+ \end{example}
+ \begin{example}
The \texttt{dontMeasure} field can also be specified in the form demonstrated in
\cref{lst:dontMeasure2}. On running the following commands, \index{switches!-l
demonstration}
+
\begin{commandshell}
latexindent.pl tabular-DM.tex -l=dontMeasure2.yaml
\end{commandshell}
+
we receive the output in \cref{lst:tabular-DM-mod2}. \index{regular
expressions!dontMeasure feature, cell}
@@ -2593,14 +2744,18 @@
We note that in \cref{lst:dontMeasure2} we have specified entries not to be measured, one
entry per line.
+ \end{example}
+ \begin{example}
The \texttt{dontMeasure} field can also be specified in the forms demonstrated in
\cref{lst:dontMeasure3} and \cref{lst:dontMeasure4}. Upon running the commands
\index{switches!-l demonstration}
+
\begin{commandshell}
latexindent.pl tabular-DM.tex -l=dontMeasure3.yaml
latexindent.pl tabular-DM.tex -l=dontMeasure4.yaml
\end{commandshell}
+
we receive the output given in \cref{lst:tabular-DM-mod3} \index{regular
expressions!lowercase alph a-z}
\begin{cmhtcbraster}[raster columns=3,
@@ -2624,24 +2779,32 @@
\end{itemize}
In both cases, the default value of \texttt{applyTo} is \texttt{cell}, and does not need
to be specified.
+ \end{example}
+ \begin{example}
We may also specify the \texttt{applyTo} field as \texttt{row}, a demonstration of which
is given in \cref{lst:dontMeasure5}; upon running \index{switches!-l demonstration}
+
\begin{commandshell}
latexindent.pl tabular-DM.tex -l=dontMeasure5.yaml
\end{commandshell}
+
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}
\end{cmhtcbraster}
+ \end{example}
+ \begin{example}
Finally, the \texttt{applyTo} field can be specified as \texttt{row}, together with a
\texttt{regex} expression. For example, for the settings given in
\cref{lst:dontMeasure6}, upon running \index{switches!-l demonstration}
+
\begin{commandshell}
latexindent.pl tabular-DM.tex -l=dontMeasure6.yaml
\end{commandshell}
+
we receive the output in \cref{lst:tabular-DM-mod6}. \index{regular
expressions!dontMeasure feature, row} \index{regular expressions!lowercase alph a-z}
@@ -2649,6 +2812,7 @@
\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}
\end{cmhtcbraster}
+ \end{example}
\subsubsection{lookForAlignDelims: the delimiterRegEx and delimiterJustification feature}\label{sec:delimiter-reg-ex}
@@ -2666,6 +2830,7 @@
if you intend to customise this field, then be sure to include them appropriately.
\end{warning}
+ \begin{example}
We demonstrate how to customise this with respect to the code given in
\cref{lst:tabbing}; the default output from \lstinline!latexindent.pl! is given in
\cref{lst:tabbing-default}.
@@ -2678,9 +2843,11 @@
Let's say that we wish to align the code at either the \lstinline!\=! or \lstinline!\>!.
We employ the settings given in \cref{lst:delimiterRegEx1} and run the command
\index{switches!-l demonstration}
+
\begin{commandshell}
latexindent.pl tabbing.tex -l=delimiterRegEx1.yaml
\end{commandshell}
+
to receive the output given in \cref{lst:tabbing-mod1}. \index{regular
expressions!delimiter regex at \textbackslash= or \textbackslash>}
@@ -2696,11 +2863,16 @@
using grouping parenthesis, specified a backslash using \lstinline!\\! and said that it
must be followed by either \lstinline!=! or \lstinline!>!.
\end{itemize}
+ \end{example}
+
+ \begin{example}
We can explore \texttt{delimiterRegEx} a little further using the settings in
\cref{lst:delimiterRegEx2} and run the command \index{switches!-l demonstration}
+
\begin{commandshell}
latexindent.pl tabbing.tex -l=delimiterRegEx2.yaml
\end{commandshell}
+
to receive the output given in \cref{lst:tabbing-mod2}. \index{regular
expressions!delimiter regex at only \textbackslash>}
@@ -2709,15 +2881,19 @@
\cmhlistingsfromfile{demonstrations/delimiterRegEx2.yaml}[yaml-TCB]{\texttt{delimiterRegEx2.yaml}}{lst:delimiterRegEx2}
\end{cmhtcbraster}
We note that only the \lstinline!\>! have been aligned.
+ \end{example}
+ \begin{example}
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}
+
\begin{commandshell}
latexindent.pl tabbing.tex -l=delimiterRegEx3.yaml
\end{commandshell}
+
to receive the output given in \cref{lst:tabbing-mod3}.
\begin{cmhtcbraster}
@@ -2724,7 +2900,9 @@
\cmhlistingsfromfile{demonstrations/tabbing-mod3.tex}{\texttt{tabbing.tex} using \cref{lst:delimiterRegEx3}}{lst:tabbing-mod3}
\cmhlistingsfromfile{demonstrations/delimiterRegEx3.yaml}[yaml-TCB]{\texttt{delimiterRegEx3.yaml}}{lst:delimiterRegEx3}
\end{cmhtcbraster}
+ \end{example}
+ \begin{example}
It is possible that delimiters specified within \texttt{delimiterRegEx} can be of
different lengths. Consider the file in \cref{lst:tabbing1}, and associated YAML in
\cref{lst:delimiterRegEx4}. Note that the \cref{lst:delimiterRegEx4} specifies the option
@@ -2731,9 +2909,11 @@
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
\end{commandshell}
+
we receive the output in \cref{lst:tabbing1-mod4}. \index{regular expressions!delimiter
regex at \#}
@@ -2745,14 +2925,18 @@
\cmhlistingsfromfile{demonstrations/tabbing1-mod4.tex}{\texttt{tabbing1-mod4.tex}}{lst:tabbing1-mod4}
\cmhlistingsfromfile{demonstrations/delimiterRegEx4.yaml}[yaml-TCB]{\texttt{delimiterRegEx4.yaml}}{lst:delimiterRegEx4}
\end{cmhtcbraster}
+ \end{example}
+ \begin{example}
You can set the \emph{delimiter} justification as either \texttt{left} (default) or
\texttt{right}, which will only have effect when delimiters in the same column have
different lengths. Using the settings in \cref{lst:delimiterRegEx5} and running the
command \index{switches!-l demonstration} \index{switches!-o demonstration}
+
\begin{commandshell}
latexindent.pl tabbing1.tex -l=delimiterRegEx5.yaml -o=+-mod5
\end{commandshell}
+
gives the output in \cref{lst:tabbing1-mod5}. \index{regular expressions!delimiter regex
at \# or \textbackslash>}
@@ -2763,6 +2947,7 @@
Note that in \cref{lst:tabbing1-mod5} the second set of delimiters have been \emph{right
aligned} -- it is quite subtle!
+ \end{example}
\subsubsection{lookForAlignDelims: lookForChildCodeBlocks}\label{sec:lookForChildCodeBlocks}
There \announce{2021-12-13}{lookForChildCodeBlocks demonstration} may be scenarios in
@@ -2770,11 +2955,14 @@
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}
and running the command
+
\begin{commandshell}
latexindent.pl tabular-DM-1.tex -l=dontMeasure1.yaml -o=+-mod1
\end{commandshell}
+
gives the output in \cref{lst:tabular-DM-1-mod1}.
\begin{cmhtcbraster}
\cmhlistingsfromfile{demonstrations/tabular-DM-1.tex}{\texttt{tabular-DM-1.tex}}{lst:tabular-DM-1}
@@ -2783,9 +2971,11 @@
We can improve the output from \cref{lst:tabular-DM-1-mod1} by employing the settings in
\cref{lst:dontMeasure1a}
+
\begin{commandshell}
latexindent.pl tabular-DM-1.tex -l=dontMeasure1a.yaml -o=+-mod1a
\end{commandshell}
+
which gives the output in \cref{lst:dontMeasure1a}.
\begin{cmhtcbraster}
@@ -2792,6 +2982,7 @@
\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}
\end{cmhtcbraster}
+ \end{example}
\subsection{Indent after items, specials and headings}
\yamltitle{indentAfterItems}*{fields}
@@ -2833,6 +3024,7 @@
You can, of course, rename these in your own YAML files (see \vref{sec:localsettings});
indeed, you might like to set up your own special begin and end statements.
+ \begin{example}
A demonstration of the before-and-after results are shown in
\cref{lst:specialbefore,lst:specialafter}.
@@ -2840,6 +3032,7 @@
\cmhlistingsfromfile{demonstrations/special1.tex}{\texttt{special1.tex} before}{lst:specialbefore}
\cmhlistingsfromfile{demonstrations/special1-default.tex}{\texttt{special1.tex} default output}{lst:specialafter}
\end{cmhtcbraster}
+ \end{example}
For each field, \texttt{lookForThis} is set to \texttt{1} by default, which means that
\texttt{latexindent.pl} will look for this pattern; you can tell \texttt{latexindent.pl}
@@ -2847,9 +3040,11 @@
There are \announce{2017-08-21}{specialBeforeCommand} examples in which it is
advantageous to search for \texttt{specialBeginEnd} fields \emph{before} searching for
- commands, and the \texttt{specialBeforeCommand} switch controls this behaviour. For
- example, consider the file shown in \cref{lst:specialLRbefore}.%
+ commands, and the \texttt{specialBeforeCommand} switch controls this behaviour.
+ \begin{example}
+ For example, consider the file shown in \cref{lst:specialLRbefore}.%
+
\cmhlistingsfromfile{demonstrations/specialLR.tex}{\texttt{specialLR.tex}}{lst:specialLRbefore}
Now consider the YAML files shown in
@@ -2863,10 +3058,12 @@
Upon running the following commands \index{switches!-l demonstration}
\begin{widepage}
+
\begin{commandshell}
latexindent.pl specialLR.tex -l=specialsLeftRight.yaml
latexindent.pl specialLR.tex -l=specialsLeftRight.yaml,specialBeforeCommand.yaml
\end{commandshell}
+
\end{widepage}
we receive the respective outputs in
\cref{lst:specialLR-comm-first-tex,lst:specialLR-special-first-tex}.
@@ -2888,10 +3085,13 @@
has been obeyed because \cref{lst:specialBeforeCommand-yaml} specifies that the
\texttt{specialBeginEnd} should be sought \emph{before} commands.
\end{itemize}
+ \end{example}
You can,optionally, specify \announce{2018-04-27}{update to specialBeginEnd} the
- \texttt{middle} field for anything that you specify in \texttt{specialBeginEnd}. For
- example, let's consider the \texttt{.tex} file in \cref{lst:special2}.
+ \texttt{middle} field for anything that you specify in \texttt{specialBeginEnd}.
+
+ \begin{example}
+ For example, let's consider the \texttt{.tex} file in \cref{lst:special2}.
\index{specialBeginEnd!middle} \index{specialBeginEnd!IfElsFi example}%
\cmhlistingsfromfile{demonstrations/special2.tex}{\texttt{special2.tex}}{lst:special2}
@@ -2898,10 +3098,12 @@
Upon saving the YAML settings in \cref{lst:middle-yaml,lst:middle1-yaml} and running the
commands \index{switches!-l demonstration}
+
\begin{commandshell}
latexindent.pl special2.tex -l=middle
latexindent.pl special2.tex -l=middle1
\end{commandshell}
+
then we obtain the output given in \cref{lst:special2-mod1,lst:special2-mod2}.
\begin{cmhtcbraster}
@@ -2924,16 +3126,20 @@
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}
You may \announce{2018-08-13}{specialBeginEnd verbatim} specify fields in
\texttt{specialBeginEnd} to be treated as verbatim code blocks by changing
\texttt{lookForThis} to be \texttt{verbatim}. \index{verbatim!specialBeginEnd}%
+ \begin{example}
For example, beginning with the code in \cref{lst:special3-mod1} and the YAML in
\cref{lst:special-verb1-yaml}, and running \index{switches!-l demonstration}
+
\begin{commandshell}
latexindent.pl special3.tex -l=special-verb1
\end{commandshell}
+
then the output in \cref{lst:special3-mod1} is unchanged.
\index{specialBeginEnd!specifying as verbatim}
@@ -2941,8 +3147,11 @@
\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}
\end{cmhtcbraster}
+ \end{example}
We can combine the \texttt{specialBeginEnd} with the \texttt{lookForAlignDelims} feature.
+
+ \begin{example}
We begin with the code in \cref{lst:special-align}.
\cmhlistingsfromfile{demonstrations/special-align.tex}{\texttt{special-align.tex}}{lst:special-align}
@@ -2950,9 +3159,11 @@
Let's assume that our goal is to align the code at the \texttt{edge} and \texttt{node}
text; we employ the code given in \cref{lst:edge-node1} and run the command
\index{switches!-l demonstration} \index{switches!-o demonstration}
+
\begin{commandshell}
latexindent.pl special-align.tex -l edge-node1.yaml -o=+-mod1
\end{commandshell}
+
to receive the output in \cref{lst:special-align-mod1}. \index{specialBeginEnd!combined
with lookForAlignDelims} \index{specialBeginEnd!delimiterRegEx}
\index{specialBeginEnd!alignment at delimiter} \index{specialBeginEnd!tikz example}
@@ -2968,9 +3179,11 @@
within \cref{lst:edge-node1} in order to improve the output; in particular, we employ the
code in \cref{lst:edge-node2} and run the command \index{switches!-l demonstration}
\index{switches!-o demonstration} \index{regular expressions!uppercase alph A-Z}
+
\begin{commandshell}
latexindent.pl special-align.tex -l edge-node2.yaml -o=+-mod2
\end{commandshell}
+
to receive the output in \cref{lst:special-align-mod2}.
\index{specialBeginEnd!delimiterRegEx tweaked} \index{regular expressions!at least one +}
\index{regular expressions!horizontal space \textbackslash{h}}
@@ -2979,6 +3192,7 @@
\cmhlistingsfromfile{demonstrations/edge-node2.yaml}[yaml-TCB]{\texttt{edge-node2.yaml}}{lst:edge-node2}
\cmhlistingsfromfile{demonstrations/special-align-mod2.tex}{\texttt{special-align.tex} using \cref{lst:edge-node2}}{lst:special-align-mod2}
\end{cmhtcbraster}
+ \end{example}
The \texttt{lookForThis} field can be considered optional;
\announce{2021-06-19}*{lookForThis optional for specialBeginEnd} by default, it is
@@ -3007,6 +3221,7 @@
\texttt{latexindent.pl} simply to use a space character after \texttt{chapter} headings
(once \texttt{indent} is set to \texttt{1} for \texttt{chapter}).
+ \begin{example}
For example, assuming that you have the code in \cref{lst:headings1yaml} saved into
\texttt{headings1.yaml}, and that you have the text from \cref{lst:headings1} saved into
\texttt{headings1.tex}.
@@ -3017,9 +3232,11 @@
\end{cmhtcbraster}
If you run the command \index{switches!-l demonstration}
+
\begin{commandshell}
latexindent.pl headings1.tex -l=headings1.yaml
\end{commandshell}
+
then you should receive the output given in \cref{lst:headings1-mod1}.
\begin{minipage}{.45\textwidth}
@@ -3029,13 +3246,16 @@
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile[showtabs=true]{demonstrations/headings1-mod2.tex}{\texttt{headings1.tex} second modification}{lst:headings1-mod2}
\end{minipage}
+ \end{example}
Now say that you modify the \texttt{YAML} from \cref{lst:headings1yaml} so that the
\texttt{paragraph} \texttt{level} is \texttt{1}; after running \index{switches!-l
demonstration}
+
\begin{commandshell}
latexindent.pl headings1.tex -l=headings1.yaml
\end{commandshell}
+
you should receive the code given in \cref{lst:headings1-mod2}; notice that the
\texttt{paragraph} and \texttt{subsection} are at the same indentation level.
@@ -3047,6 +3267,7 @@
field as horizontal space (but \emph{not} including tabs). This feature uses the
\texttt{Text::Tabs} module \cite{texttabs}, and is \emph{off} by default.%
+ \begin{example}
For example, consider the example shown in \cref{lst:mult-nested} together with the
default output shown in \cref{lst:mult-nested-default}.
@@ -3054,13 +3275,17 @@
\cmhlistingsfromfile{demonstrations/mult-nested.tex}{\texttt{mult-nested.tex}}{lst:mult-nested}
\cmhlistingsfromfile[showtabs=true]{demonstrations/mult-nested-default.tex}{\texttt{mult-nested.tex} default output}{lst:mult-nested-default}
\end{cmhtcbraster}
+ \end{example}
+ \begin{example}
Now say that, for example, you have the \texttt{max-indentation1.yaml} from
\cref{lst:max-indentation1yaml} and that you run the following command:
\index{switches!-l demonstration}
+
\begin{commandshell}
latexindent.pl mult-nested.tex -l=max-indentation1
\end{commandshell}
+
You should receive the output shown in \cref{lst:mult-nested-max-ind1}.
\begin{cmhtcbraster}
@@ -3067,6 +3292,7 @@
\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.
@@ -3201,6 +3427,7 @@
\cmhlistingsfromfile{demonstrations/myenvironment-simple.tex}{\texttt{myenv.tex}}{lst:myenvtex}
\yamltitle{noAdditionalIndent}*{fields}
+ \begin{example}
If we do not wish \texttt{myenv} to receive any additional indentation, we have a few
choices available to us, as demonstrated in \cref{lst:myenv-noAdd1,lst:myenv-noAdd2}.
@@ -3213,34 +3440,39 @@
\end{minipage}
On applying either of the following commands, \index{switches!-l demonstration}
+
\begin{commandshell}
latexindent.pl myenv.tex -l myenv-noAdd1.yaml
latexindent.pl myenv.tex -l myenv-noAdd2.yaml
\end{commandshell}
+
we obtain the output given in \cref{lst:myenv-output}; note in particular that the
environment \texttt{myenv} has not received any \emph{additional} indentation, but that
the \texttt{outer} environment \emph{has} still received indentation.
\cmhlistingsfromfile{demonstrations/myenvironment-simple-noAdd-body1.tex}{\texttt{myenv.tex} output (using either \cref{lst:myenv-noAdd1} or \cref{lst:myenv-noAdd2})}{lst:myenv-output}
+ \end{example}
+ \begin{example}
Upon changing the YAML files to those shown in \cref{lst:myenv-noAdd3,lst:myenv-noAdd4},
and running either \index{switches!-l demonstration}
+
\begin{commandshell}
latexindent.pl myenv.tex -l myenv-noAdd3.yaml
latexindent.pl myenv.tex -l myenv-noAdd4.yaml
\end{commandshell}
+
we obtain the output given in \cref{lst:myenv-output-4}.
- \begin{minipage}{.45\textwidth}
+ \begin{cmhtcbraster}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/myenv-noAdd3.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-noAdd3.yaml}}{lst:myenv-noAdd3}
- \end{minipage}
- \hfill
- \begin{minipage}{.45\textwidth}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/myenv-noAdd4.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-noAdd4.yaml}}{lst:myenv-noAdd4}
- \end{minipage}
+ \end{cmhtcbraster}
\cmhlistingsfromfile{demonstrations/myenvironment-simple-noAdd-body4.tex}{\texttt{myenv.tex output} (using either \cref{lst:myenv-noAdd3} or \cref{lst:myenv-noAdd4})}{lst:myenv-output-4}
+ \end{example}
+ \begin{example}
Let's now allow \texttt{myenv} to have some optional and mandatory arguments, as in
\cref{lst:myenv-args}.
@@ -3247,9 +3479,11 @@
\cmhlistingsfromfile{demonstrations/myenvironment-args.tex}{\texttt{myenv-args.tex}}{lst:myenv-args}
Upon running \index{switches!-l demonstration}
+
\begin{commandshell}
latexindent.pl -l=myenv-noAdd1.yaml myenv-args.tex
\end{commandshell}
+
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
@@ -3256,24 +3490,25 @@
\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}
+ \end{example}
+ \begin{example}
We may customise \texttt{noAdditionalIndent} for optional and mandatory arguments of the
\texttt{myenv} environment, as shown in, for example,
\cref{lst:myenv-noAdd5,lst:myenv-noAdd6}.
- \begin{minipage}{.49\textwidth}
+ \begin{cmhtcbraster}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/myenv-noAdd5.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-noAdd5.yaml}}{lst:myenv-noAdd5}
- \end{minipage}
- \hfill
- \begin{minipage}{.49\textwidth}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/myenv-noAdd6.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-noAdd6.yaml}}{lst:myenv-noAdd6}
- \end{minipage}
+ \end{cmhtcbraster}
Upon running \index{switches!-l demonstration}
+
\begin{commandshell}
latexindent.pl myenv.tex -l myenv-noAdd5.yaml
latexindent.pl myenv.tex -l myenv-noAdd6.yaml
\end{commandshell}
+
we obtain the respective outputs given in
\cref{lst:myenv-args-noAdd5,lst:myenv-args-noAdd6}. Note that in
\cref{lst:myenv-args-noAdd5} the text for the \emph{optional} argument has not received
@@ -3281,15 +3516,14 @@
argument has not received any additional indentation; in both cases, the \emph{body} has
not received any additional indentation.
- \begin{minipage}{.45\textwidth}
+ \begin{cmhtcbraster}
\cmhlistingsfromfile{demonstrations/myenvironment-args-noAdd5.tex}{\texttt{myenv-args.tex} using \cref{lst:myenv-noAdd5}}{lst:myenv-args-noAdd5}
- \end{minipage}
- \hfill
- \begin{minipage}{.45\textwidth}
\cmhlistingsfromfile{demonstrations/myenvironment-args-noAdd6.tex}{\texttt{myenv-args.tex} using \cref{lst:myenv-noAdd6}}{lst:myenv-args-noAdd6}
- \end{minipage}
+ \end{cmhtcbraster}
+ \end{example}
\yamltitle{indentRules}*{fields}
+ \begin{example}
We may also specify indentation rules for environment code blocks using the
\texttt{indentRules} field; see, for example, \cref{lst:myenv-rules1,lst:myenv-rules2}.
@@ -3299,29 +3533,37 @@
\end{cmhtcbraster}
On applying either of the following commands, \index{switches!-l demonstration}
+
\begin{commandshell}
latexindent.pl myenv.tex -l myenv-rules1.yaml
latexindent.pl myenv.tex -l myenv-rules2.yaml
\end{commandshell}
+
we obtain the output given in \cref{lst:myenv-rules-output}; note in particular that the
environment \texttt{myenv} has received one tab (from the \texttt{outer} environment)
plus three spaces from \cref{lst:myenv-rules1} or \ref{lst:myenv-rules2}.
\cmhlistingsfromfile[showtabs=true,showspaces=true]{demonstrations/myenv-rules1.tex}{\texttt{myenv.tex} output (using either \cref{lst:myenv-rules1} or \cref{lst:myenv-rules2})}{lst:myenv-rules-output}
+ \end{example}
If you specify a field in \texttt{indentRules} using anything other than horizontal
space, it will be ignored.
+ \begin{example}
Returning to the example in \cref{lst:myenv-args} that contains optional and mandatory
arguments. Upon using \cref{lst:myenv-rules1} as in \index{switches!-l demonstration}
+
\begin{commandshell}
latexindent.pl myenv-args.tex -l=myenv-rules1.yaml
\end{commandshell}
+
we obtain the output in \cref{lst:myenv-args-rules1}; note that the body, optional
argument and mandatory argument of \texttt{myenv} have \emph{all} received the same
customised indentation.
\cmhlistingsfromfile[showtabs=true,showspaces=true]{demonstrations/myenvironment-args-rules1.tex}{\texttt{myenv-args.tex} using \cref{lst:myenv-rules1}}{lst:myenv-args-rules1}
+ \end{example}
+ \begin{example}
You can specify different indentation rules for the different features using, for
example, \cref{lst:myenv-rules3,lst:myenv-rules4}
@@ -3334,10 +3576,12 @@
\end{minipage}
After running \index{switches!-l demonstration}
+
\begin{commandshell}
latexindent.pl myenv-args.tex -l myenv-rules3.yaml
latexindent.pl myenv-args.tex -l myenv-rules4.yaml
\end{commandshell}
+
then we obtain the respective outputs given in
\cref{lst:myenv-args-rules3,lst:myenv-args-rules4}.
@@ -3358,6 +3602,7 @@
In \cref{lst:myenv-args-rules4}, the optional argument has received the default (tab)
indentation, the mandatory argument has received two tabs of indentation, and the body
has received three spaces of indentation.
+ \end{example}
\yamltitle{noAdditionalIndentGlobal}*{fields}
Assuming that your environment name is not found within neither
@@ -3367,15 +3612,18 @@
\cmhlistingsfromfile[style=noAdditionalIndentGlobalEnv]{../defaultSettings.yaml}[width=.5\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
\cref{lst:noAdditionalIndentGlobal:environments}, and that you run \index{switches!-l
demonstration}
\begin{widepage}
+
\begin{commandshell}
latexindent.pl myenv-args.tex -l env-noAdditionalGlobal.yaml
latexindent.pl myenv-args.tex -l myenv-rules1.yaml,env-noAdditionalGlobal.yaml
\end{commandshell}
+
\end{widepage}
The respective output from these two commands are in
@@ -3387,31 +3635,29 @@
\texttt{myenv-rules1.yaml} (in \vref{lst:myenv-rules1}), the \texttt{myenv} environment
still \emph{does} receive indentation.
- \begin{minipage}{.45\textwidth}
+ \begin{cmhtcbraster}
\cmhlistingsfromfile{demonstrations/myenvironment-args-rules1-noAddGlobal1.tex}{\texttt{myenv-args.tex} using \cref{lst:noAdditionalIndentGlobal:environments}}{lst:myenv-args-no-add-global1}
- \end{minipage}
- \hfill
- \begin{minipage}{.45\textwidth}
\cmhlistingsfromfile{demonstrations/myenvironment-args-rules1-noAddGlobal2.tex}{\texttt{myenv-args.tex} using \cref{lst:noAdditionalIndentGlobal:environments,lst:myenv-rules1}}{lst:myenv-args-no-add-global2}
- \end{minipage}
+ \end{cmhtcbraster}
+ \end{example}
+ \begin{example}
In fact, \texttt{noAdditionalIndentGlobal} also contains keys that control the
indentation of optional and mandatory arguments; on referencing
\cref{lst:opt-args-no-add-glob,lst:mand-args-no-add-glob}
- \begin{minipage}{.49\textwidth}
+ \begin{cmhtcbraster}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/opt-args-no-add-glob.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{opt-args-no-add-glob.yaml}}{lst:opt-args-no-add-glob}
- \end{minipage}
- \hfill
- \begin{minipage}{.49\textwidth}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/mand-args-no-add-glob.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{mand-args-no-add-glob.yaml}}{lst:mand-args-no-add-glob}
- \end{minipage}
+ \end{cmhtcbraster}
we may run the commands \index{switches!-l demonstration}
+
\begin{commandshell}
latexindent.pl myenv-args.tex -local opt-args-no-add-glob.yaml
latexindent.pl myenv-args.tex -local mand-args-no-add-glob.yaml
\end{commandshell}
+
which produces the respective outputs given in
\cref{lst:myenv-args-no-add-opt,lst:myenv-args-no-add-mand}. Notice that in
\cref{lst:myenv-args-no-add-opt} the \emph{optional} argument has not received any
@@ -3418,13 +3664,11 @@
additional indentation, and in \cref{lst:myenv-args-no-add-mand} the \emph{mandatory}
argument has not received any additional indentation.
- \begin{minipage}{.45\textwidth}
+ \begin{cmhtcbraster}
\cmhlistingsfromfile{demonstrations/myenvironment-args-rules1-noAddGlobal3.tex}{\texttt{myenv-args.tex} using \cref{lst:opt-args-no-add-glob}}{lst:myenv-args-no-add-opt}
- \end{minipage}
- \hfill
- \begin{minipage}{.45\textwidth}
\cmhlistingsfromfile{demonstrations/myenvironment-args-rules1-noAddGlobal4.tex}{\texttt{myenv-args.tex} using \cref{lst:mand-args-no-add-glob}}{lst:myenv-args-no-add-mand}
- \end{minipage}
+ \end{cmhtcbraster}
+ \end{example}
\yamltitle{indentRulesGlobal}*{fields}
The final check that \texttt{latexindent.pl} will make is to look for
@@ -3432,6 +3676,7 @@
\cmhlistingsfromfile[style=indentRulesGlobalEnv]{../defaultSettings.yaml}[width=.5\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}
@@ -3439,6 +3684,7 @@
latexindent.pl myenv-args.tex -l env-indentRules.yaml
latexindent.pl myenv-args.tex -l myenv-rules1.yaml,env-indentRules.yaml
\end{commandshell}
+
then the respective output is shown in
\cref{lst:myenv-args-indent-rules-global1,lst:myenv-args-indent-rules-global2}. Note that
in \cref{lst:myenv-args-indent-rules-global1}, both the environment blocks have received
@@ -3448,30 +3694,28 @@
specified by the particular \texttt{indentRules} for \texttt{myenv}
\vref{lst:myenv-rules1}.
- \begin{minipage}{.45\textwidth}
+ \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}
- \end{minipage}
- \hfill
- \begin{minipage}{.45\textwidth}
\cmhlistingsfromfile[showspaces=true]{demonstrations/myenvironment-args-global-rules2.tex}{\texttt{myenv-args.tex} using \cref{lst:myenv-rules1,lst:indentRulesGlobal:environments}}{lst:myenv-args-indent-rules-global2}
- \end{minipage}
+ \end{cmhtcbraster}
+ \end{example}
+ \begin{example}
You can specify \texttt{indentRulesGlobal} for both optional and mandatory arguments, as
detailed in \cref{lst:opt-args-indent-rules-glob,lst:mand-args-indent-rules-glob}
- \begin{minipage}{.49\textwidth}
+ \begin{cmhtcbraster}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/opt-args-indent-rules-glob.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{opt-args-indent-rules-glob.yaml}}{lst:opt-args-indent-rules-glob}
- \end{minipage}
- \hfill
- \begin{minipage}{.49\textwidth}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/mand-args-indent-rules-glob.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{mand-args-indent-rules-glob.yaml}}{lst:mand-args-indent-rules-glob}
- \end{minipage}
+ \end{cmhtcbraster}
Upon running the following commands \index{switches!-l demonstration}
+
\begin{commandshell}
latexindent.pl myenv-args.tex -local opt-args-indent-rules-glob.yaml
latexindent.pl myenv-args.tex -local mand-args-indent-rules-glob.yaml
\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
@@ -3487,6 +3731,7 @@
\cmhlistingsfromfile[showtabs=true]{demonstrations/myenvironment-args-global-rules4.tex}{\texttt{myenv-args.tex} using \cref{lst:mand-args-indent-rules-glob}}{lst:myenv-args-indent-rules-global4}
\end{minipage}
\end{widepage}
+ \end{example}
% arara: pdflatex: { files: [latexindent]}
\subsubsection{Environments with items}
With reference to \vref{lst:indentafteritems,lst:itemNames}, some commands may contain
@@ -3496,9 +3741,12 @@
Assuming that you've populated \texttt{itemNames} with the name of your \texttt{item},
you can put the item name into \texttt{noAdditionalIndent} as in \cref{lst:item-noAdd1},
although a more efficient approach may be to change the relevant field in
- \texttt{itemNames} to \texttt{0}. Similarly, you can customise the indentation that your
- \texttt{item} receives using \texttt{indentRules}, as in \cref{lst:item-rules1}
+ \texttt{itemNames} to \texttt{0}.
+ \begin{example}
+ Similarly, you can customise the indentation that your \texttt{item} receives using
+ \texttt{indentRules}, as in \cref{lst:item-rules1}
+
\begin{cmhtcbraster}[raster column skip=.1\linewidth]
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/item-noAdd1.yaml}[yaml-TCB]{\texttt{item-noAdd1.yaml}}{lst:item-noAdd1}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/item-rules1.yaml}[yaml-TCB]{\texttt{item-rules1.yaml}}{lst:item-rules1}
@@ -3505,10 +3753,12 @@
\end{cmhtcbraster}
Upon running the following commands \index{switches!-l demonstration}
+
\begin{commandshell}
latexindent.pl items1.tex -local item-noAdd1.yaml
latexindent.pl items1.tex -local item-rules1.yaml
\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
@@ -3515,14 +3765,13 @@
\texttt{item} has received a single space of indentation, specified by
\cref{lst:item-rules1}.
- \begin{minipage}{.45\textwidth}
+ \begin{cmhtcbraster}
\cmhlistingsfromfile{demonstrations/items1-noAdd1.tex}{\texttt{items1.tex} using \cref{lst:item-noAdd1}}{lst:items1-noAdd1}
- \end{minipage}
- \hfill
- \begin{minipage}{.45\textwidth}
\cmhlistingsfromfile[showtabs=true,showspaces=true]{demonstrations/items1-rules1.tex}{\texttt{items1.tex} using \cref{lst:item-rules1}}{lst:items1-rules1}
- \end{minipage}
+ \end{cmhtcbraster}
+ \end{example}
+ \begin{example}
Alternatively, you might like to populate \texttt{noAdditionalIndentGlobal} or
\texttt{indentRulesGlobal} using the \texttt{items} key, as demonstrated in
\cref{lst:items-noAdditionalGlobal,lst:items-indentRulesGlobal}. Note that there is a
@@ -3530,25 +3779,26 @@
(see the hierarchy description given on \cpageref{sec:noadd-indent-rules}) as the
\texttt{item} command is a member of \texttt{indentRules} by default.
- \begin{minipage}{.45\textwidth}
+ \begin{cmhtcbraster}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/items-noAdditionalGlobal.yaml}[yaml-TCB]{\texttt{items-noAdditionalGlobal.yaml}}{lst:items-noAdditionalGlobal}
- \end{minipage}%
- \hfill
- \begin{minipage}{.45\textwidth}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/items-indentRulesGlobal.yaml}[yaml-TCB]{\texttt{items-indentRulesGlobal.yaml}}{lst:items-indentRulesGlobal}
- \end{minipage}
+ \end{cmhtcbraster}
Upon running the following commands, \index{switches!-l demonstration}
+
\begin{commandshell}
latexindent.pl items1.tex -local items-noAdditionalGlobal.yaml
latexindent.pl items1.tex -local items-indentRulesGlobal.yaml
\end{commandshell}
+
the respective outputs from \cref{lst:items1-noAdd1,lst:items1-rules1} are obtained;
note, however, that \emph{all} such \texttt{item} commands without their own individual
\texttt{noAdditionalIndent} or \texttt{indentRules} settings would behave as in these
listings.
+ \end{example}
% 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
@@ -3563,29 +3813,25 @@
specify \texttt{noAdditionalIndent} either in `scalar' form, or in `field' form, as shown
in \cref{lst:mycommand-noAdd1,lst:mycommand-noAdd2}
- \begin{minipage}{.45\textwidth}
+ \begin{cmhtcbraster}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycommand-noAdd1.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{mycommand-noAdd1.yaml}}{lst:mycommand-noAdd1}
- \end{minipage}
- \hfill
- \begin{minipage}{.45\textwidth}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycommand-noAdd2.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{mycommand-noAdd2.yaml}}{lst:mycommand-noAdd2}
- \end{minipage}
+ \end{cmhtcbraster}
After running the following commands, \index{switches!-l demonstration}
+
\begin{commandshell}
latexindent.pl mycommand.tex -l mycommand-noAdd1.yaml
latexindent.pl mycommand.tex -l mycommand-noAdd2.yaml
\end{commandshell}
+
we receive the respective output given in
\cref{lst:mycommand-output-noAdd1,lst:mycommand-output-noAdd2}
- \begin{minipage}{.45\textwidth}
+ \begin{cmhtcbraster}
\cmhlistingsfromfile{demonstrations/mycommand-noAdd1.tex}{\texttt{mycommand.tex} using \cref{lst:mycommand-noAdd1}}{lst:mycommand-output-noAdd1}
- \end{minipage}
- \hfill
- \begin{minipage}{.45\textwidth}
\cmhlistingsfromfile{demonstrations/mycommand-noAdd2.tex}{\texttt{mycommand.tex} using \cref{lst:mycommand-noAdd2}}{lst:mycommand-output-noAdd2}
- \end{minipage}
+ \end{cmhtcbraster}
Note that in \cref{lst:mycommand-output-noAdd1} that the `body', optional argument
\emph{and} mandatory argument have \emph{all} received no additional indentation, while
@@ -3592,35 +3838,35 @@
in \cref{lst:mycommand-output-noAdd2}, only the `body' has not received any additional
indentation. We define the `body' of a command as any lines following the command name
that include its optional or mandatory arguments.
+ \end{example}
+ \begin{example}
We may further customise \texttt{noAdditionalIndent} for \texttt{mycommand} as we did in
\vref{lst:myenv-noAdd5,lst:myenv-noAdd6}; explicit examples are given in
\cref{lst:mycommand-noAdd3,lst:mycommand-noAdd4}.
- \begin{minipage}{.45\textwidth}
+ \begin{cmhtcbraster}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycommand-noAdd3.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{mycommand-noAdd3.yaml}}{lst:mycommand-noAdd3}
- \end{minipage}
- \hfill
- \begin{minipage}{.45\textwidth}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycommand-noAdd4.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{mycommand-noAdd4.yaml}}{lst:mycommand-noAdd4}
- \end{minipage}
+ \end{cmhtcbraster}
After running the following commands, \index{switches!-l demonstration}
+
\begin{commandshell}
latexindent.pl mycommand.tex -l mycommand-noAdd3.yaml
latexindent.pl mycommand.tex -l mycommand-noAdd4.yaml
\end{commandshell}
+
we receive the respective output given in
\cref{lst:mycommand-output-noAdd3,lst:mycommand-output-noAdd4}.
- \begin{minipage}{.45\textwidth}
+ \begin{cmhtcbraster}
\cmhlistingsfromfile{demonstrations/mycommand-noAdd3.tex}{\texttt{mycommand.tex} using \cref{lst:mycommand-noAdd3}}{lst:mycommand-output-noAdd3}
- \end{minipage}
- \hfill
- \begin{minipage}{.45\textwidth}
\cmhlistingsfromfile{demonstrations/mycommand-noAdd4.tex}{\texttt{mycommand.tex} using \cref{lst:mycommand-noAdd4}}{lst:mycommand-output-noAdd4}
- \end{minipage}
+ \end{cmhtcbraster}
+ \end{example}
+ \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
@@ -3629,29 +3875,26 @@
this can be easily fixed as in
\cref{lst:mycommand-noAdd5,lst:mycommand-noAdd6}.\label{page:command:noAddGlobal}
- \begin{minipage}{.45\textwidth}
+ \begin{cmhtcbraster}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycommand-noAdd5.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{mycommand-noAdd5.yaml}}{lst:mycommand-noAdd5}
- \end{minipage}
- \hfill
- \begin{minipage}{.45\textwidth}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycommand-noAdd6.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{mycommand-noAdd6.yaml}}{lst:mycommand-noAdd6}
- \end{minipage}
+ \end{cmhtcbraster}
After running the following commands, \index{switches!-l demonstration}
+
\begin{commandshell}
latexindent.pl mycommand.tex -l mycommand-noAdd5.yaml
latexindent.pl mycommand.tex -l mycommand-noAdd6.yaml
\end{commandshell}
+
we receive the respective output given in
\cref{lst:mycommand-output-noAdd5,lst:mycommand-output-noAdd6}.
- \begin{minipage}{.45\textwidth}
+ \begin{cmhtcbraster}
\cmhlistingsfromfile{demonstrations/mycommand-noAdd5.tex}{\texttt{mycommand.tex} using \cref{lst:mycommand-noAdd5}}{lst:mycommand-output-noAdd5}
- \end{minipage}
- \hfill
- \begin{minipage}{.45\textwidth}
\cmhlistingsfromfile{demonstrations/mycommand-noAdd6.tex}{\texttt{mycommand.tex} using \cref{lst:mycommand-noAdd6}}{lst:mycommand-output-noAdd6}
- \end{minipage}
+ \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
@@ -3658,18 +3901,16 @@
\vref{lst:indentRulesGlobal:environments,lst:opt-args-indent-rules-glob,lst:mand-args-indent-rules-glob}.
% arara: pdflatex: { files: [latexindent]}
\subsubsection{ifelsefi code blocks}
+ \begin{example}
Let's use the simple example shown in \cref{lst:ifelsefi1}; when \texttt{latexindent.pl}
operates on this file, the output as in \cref{lst:ifelsefi1-default}; note that the body
of each of the \lstinline!\if! statements have been indented, and that the
\lstinline!\else! statement has been accounted for correctly.
- \begin{minipage}{.45\textwidth}
+ \begin{cmhtcbraster}
\cmhlistingsfromfile{demonstrations/ifelsefi1.tex}{\texttt{ifelsefi1.tex}}{lst:ifelsefi1}
- \end{minipage}%
- \hfill
- \begin{minipage}{.54\textwidth}
\cmhlistingsfromfile{demonstrations/ifelsefi1-default.tex}{\texttt{ifelsefi1.tex} default output}{lst:ifelsefi1-default}
- \end{minipage}
+ \end{cmhtcbraster}
It is recommended to specify \texttt{noAdditionalIndent} and \texttt{indentRules} in the
`scalar' form only for these type of code blocks, although the `field' form would work,
@@ -3676,19 +3917,18 @@
assuming that \texttt{body} was specified. Examples are shown in
\cref{lst:ifnum-noAdd,lst:ifnum-indent-rules}.
- \begin{minipage}{.45\textwidth}
+ \begin{cmhtcbraster}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/ifnum-noAdd.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{ifnum-noAdd.yaml}}{lst:ifnum-noAdd}
- \end{minipage}
- \hfill
- \begin{minipage}{.45\textwidth}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/ifnum-indent-rules.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{ifnum-indent-rules.yaml}}{lst:ifnum-indent-rules}
- \end{minipage}
+ \end{cmhtcbraster}
After running the following commands, \index{switches!-l demonstration}
+
\begin{commandshell}
latexindent.pl ifelsefi1.tex -local ifnum-noAdd.yaml
latexindent.pl ifelsefi1.tex -l ifnum-indent-rules.yaml
\end{commandshell}
+
we receive the respective output given in
\cref{lst:ifelsefi1-output-noAdd,lst:ifelsefi1-output-indent-rules}; note that in
\cref{lst:ifelsefi1-output-noAdd}, the \texttt{ifnum} code block has \emph{not} received
@@ -3695,30 +3935,28 @@
any additional indentation, while in \cref{lst:ifelsefi1-output-indent-rules}, the
\texttt{ifnum} code block has received one tab and two spaces of indentation.
- \begin{minipage}{.45\textwidth}
+ \begin{cmhtcbraster}
\cmhlistingsfromfile{demonstrations/ifelsefi1-noAdd.tex}{\texttt{ifelsefi1.tex} using \cref{lst:ifnum-noAdd}}{lst:ifelsefi1-output-noAdd}
- \end{minipage}
- \hfill
- \begin{minipage}{.5\textwidth}
\cmhlistingsfromfile[showspaces=true,showtabs=true]{demonstrations/ifelsefi1-indent-rules.tex}{\texttt{ifelsefi1.tex} using \cref{lst:ifnum-indent-rules}}{lst:ifelsefi1-output-indent-rules}
- \end{minipage}
+ \end{cmhtcbraster}
+ \end{example}
+ \begin{example}
We may specify \texttt{noAdditionalIndentGlobal} and \texttt{indentRulesGlobal} as in
\cref{lst:ifelsefi-noAdd-glob,lst:ifelsefi-indent-rules-global}.
- \begin{minipage}{.49\textwidth}
+ \begin{cmhtcbraster}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/ifelsefi-noAdd-glob.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{ifelsefi-noAdd-glob.yaml}}{lst:ifelsefi-noAdd-glob}
- \end{minipage}
- \hfill
- \begin{minipage}{.49\textwidth}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/ifelsefi-indent-rules-global.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{ifelsefi-indent-rules-global.yaml}}{lst:ifelsefi-indent-rules-global}
- \end{minipage}
+ \end{cmhtcbraster}
Upon running the following commands \index{switches!-l demonstration}
+
\begin{commandshell}
latexindent.pl ifelsefi1.tex -local ifelsefi-noAdd-glob.yaml
latexindent.pl ifelsefi1.tex -l ifelsefi-indent-rules-global.yaml
\end{commandshell}
+
we receive the outputs in
\cref{lst:ifelsefi1-output-noAdd-glob,lst:ifelsefi1-output-indent-rules-global}; notice
that in \cref{lst:ifelsefi1-output-noAdd-glob} neither of the \texttt{ifelsefi} code
@@ -3726,28 +3964,29 @@
\cref{lst:ifelsefi1-output-indent-rules-global} both code blocks have received a single
space of indentation.
- \begin{minipage}{.45\textwidth}
+ \begin{cmhtcbraster}
\cmhlistingsfromfile{demonstrations/ifelsefi1-noAdd-glob.tex}{\texttt{ifelsefi1.tex} using \cref{lst:ifelsefi-noAdd-glob}}{lst:ifelsefi1-output-noAdd-glob}
- \end{minipage}
- \hfill
- \begin{minipage}{.45\textwidth}
\cmhlistingsfromfile[showspaces=true]{demonstrations/ifelsefi1-indent-rules-global.tex}{\texttt{ifelsefi1.tex} using \cref{lst:ifelsefi-indent-rules-global}}{lst:ifelsefi1-output-indent-rules-global}
- \end{minipage}
+ \end{cmhtcbraster}
+ \end{example}
- We can further explore the treatment of \texttt{ifElseFi} code blocks
- \announce{2018-04-27}*{updates to ifElseFi code blocks} in \cref{lst:ifelsefi2}, and the
- associated default output given in \cref{lst:ifelsefi2-default}; note, in particular,
- that the bodies of each of the `or statements' have been indented.%
+ \begin{example}
+ We can further explore the treatment of \texttt{ifElseFi} code blocks in
+ \cref{lst:ifelsefi2}, and the associated default output given in
+ \cref{lst:ifelsefi2-default}; note, in particular,\announce{2018-04-27}*{updates to
+ ifElseFi code blocks} that the bodies of each of the `or statements' have been indented.%
\begin{cmhtcbraster}[raster column skip=.1\linewidth]
\cmhlistingsfromfile{demonstrations/ifelsefi2.tex}{\texttt{ifelsefi2.tex}}{lst:ifelsefi2}
\cmhlistingsfromfile{demonstrations/ifelsefi2-default.tex}{\texttt{ifelsefi2.tex} default output}{lst:ifelsefi2-default}
\end{cmhtcbraster}
+ \end{example}
% arara: pdflatex: {files: [latexindent]}
\subsubsection{specialBeginEnd code blocks}
Let's use the example from \vref{lst:specialbefore} which has default output shown in
\vref{lst:specialafter}.
+ \begin{example}
It is recommended to specify \texttt{noAdditionalIndent} and \texttt{indentRules} in the
`scalar' form for these type of code blocks, although the `field' form would work,
assuming that \texttt{body} was specified. Examples are shown in
@@ -3754,19 +3993,18 @@
\cref{lst:displayMath-noAdd,lst:displayMath-indent-rules}.
\index{specialBeginEnd!noAdditionalIndent} \index{specialBeginEnd!indentRules example}
- \begin{minipage}{.49\textwidth}
+ \begin{cmhtcbraster}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/displayMath-noAdd.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{displayMath-noAdd.yaml}}{lst:displayMath-noAdd}
- \end{minipage}
- \hfill
- \begin{minipage}{.49\textwidth}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/displayMath-indent-rules.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{displayMath-indent-rules.yaml}}{lst:displayMath-indent-rules}
- \end{minipage}
+ \end{cmhtcbraster}
After running the following commands, \index{switches!-l demonstration}
+
\begin{commandshell}
latexindent.pl special1.tex -local displayMath-noAdd.yaml
latexindent.pl special1.tex -l displayMath-indent-rules.yaml
\end{commandshell}
+
we receive the respective output given in
\cref{lst:special1-output-noAdd,lst:special1-output-indent-rules}; note that in
\cref{lst:special1-output-noAdd}, the \texttt{displayMath} code block has \emph{not}
@@ -3773,30 +4011,28 @@
received any additional indentation, while in \cref{lst:special1-output-indent-rules},
the \texttt{displayMath} code block has received three tabs worth of indentation.
- \begin{minipage}{.45\textwidth}
+ \begin{cmhtcbraster}
\cmhlistingsfromfile{demonstrations/special1-noAdd.tex}{\texttt{special1.tex} using \cref{lst:displayMath-noAdd}}{lst:special1-output-noAdd}
- \end{minipage}
- \hfill
- \begin{minipage}{.45\textwidth}
\cmhlistingsfromfile[showtabs=true]{demonstrations/special1-indent-rules.tex}{\texttt{special1.tex} using \cref{lst:displayMath-indent-rules}}{lst:special1-output-indent-rules}
- \end{minipage}
+ \end{cmhtcbraster}
+ \end{example}
+ \begin{example}
We may specify \texttt{noAdditionalIndentGlobal} and \texttt{indentRulesGlobal} as in
\cref{lst:special-noAdd-glob,lst:special-indent-rules-global}.
- \begin{minipage}{.49\textwidth}
+ \begin{cmhtcbraster}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/special-noAdd-glob.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{special-noAdd-glob.yaml}}{lst:special-noAdd-glob}
- \end{minipage}
- \hfill
- \begin{minipage}{.49\textwidth}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/special-indent-rules-global.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{special-indent-rules-global.yaml}}{lst:special-indent-rules-global}
- \end{minipage}
+ \end{cmhtcbraster}
Upon running the following commands \index{switches!-l demonstration}
+
\begin{commandshell}
latexindent.pl special1.tex -local special-noAdd-glob.yaml
latexindent.pl special1.tex -l special-indent-rules-global.yaml
\end{commandshell}
+
we receive the outputs in
\cref{lst:special1-output-noAdd-glob,lst:special1-output-indent-rules-global}; notice
that in \cref{lst:special1-output-noAdd-glob} neither of the \texttt{special} code blocks
@@ -3803,13 +4039,11 @@
have received indentation, while in \cref{lst:special1-output-indent-rules-global} both
code blocks have received a single space of indentation.
- \begin{minipage}{.45\textwidth}
+ \begin{cmhtcbraster}
\cmhlistingsfromfile{demonstrations/special1-noAdd-glob.tex}{\texttt{special1.tex} using \cref{lst:special-noAdd-glob}}{lst:special1-output-noAdd-glob}
- \end{minipage}
- \hfill
- \begin{minipage}{.45\textwidth}
\cmhlistingsfromfile[showspaces=true]{demonstrations/special1-indent-rules-global.tex}{\texttt{special1.tex} using \cref{lst:special-indent-rules-global}}{lst:special1-output-indent-rules-global}
- \end{minipage}
+ \end{cmhtcbraster}
+ \end{example}
% arara: pdflatex: { files: [latexindent]}
\subsubsection{afterHeading code blocks}\label{subsubsec-headings-no-add-indent-rules}
Let's use the example \cref{lst:headings2} for demonstration throughout this
@@ -3819,11 +4053,14 @@
\cmhlistingsfromfile{demonstrations/headings2.tex}{\texttt{headings2.tex}}{lst:headings2}
+ \begin{example}
On using the YAML file in \cref{lst:headings3yaml} by running the command
\index{switches!-l demonstration}
+
\begin{commandshell}
latexindent.pl headings2.tex -l headings3.yaml
\end{commandshell}
+
we obtain the output in \cref{lst:headings2-mod3}. Note that the argument of
\texttt{paragraph} has received (default) indentation, and that the body after the
heading statement has received (default) indentation.
@@ -3835,9 +4072,11 @@
If we specify \texttt{noAdditionalIndent} as in \cref{lst:headings4yaml} and run the
command \index{switches!-l demonstration}
+
\begin{commandshell}
latexindent.pl headings2.tex -l headings4.yaml
\end{commandshell}
+
then we receive the output in \cref{lst:headings2-mod4}. Note that the arguments
\emph{and} the body after the heading of \texttt{paragraph} has received no additional
indentation, because we have specified \texttt{noAdditionalIndent} in scalar form.
@@ -3846,7 +4085,9 @@
\cmhlistingsfromfile{demonstrations/headings2-mod4.tex}{\texttt{headings2.tex} using \cref{lst:headings4yaml}}{lst:headings2-mod4}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/headings4.yaml}[yaml-TCB]{\texttt{headings4.yaml}}{lst:headings4yaml}
\end{cmhtcbraster}
+ \end{example}
+ \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}
@@ -3859,7 +4100,9 @@
\cmhlistingsfromfile[showtabs=true]{demonstrations/headings2-mod5.tex}{\texttt{headings2.tex} using \cref{lst:headings5yaml}}{lst:headings2-mod5}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/headings5.yaml}[yaml-TCB]{\texttt{headings5.yaml}}{lst:headings5yaml}
\end{cmhtcbraster}
+ \end{example}
+ \begin{example}
We may, instead, specify \texttt{noAdditionalIndent} in `field' form, as in
\cref{lst:headings6yaml} which gives the output in \cref{lst:headings2-mod6}.
@@ -3867,7 +4110,9 @@
\cmhlistingsfromfile{demonstrations/headings2-mod6.tex}{\texttt{headings2.tex} using \cref{lst:headings6yaml}}{lst:headings2-mod6}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/headings6.yaml}[yaml-TCB]{\texttt{headings6.yaml}}{lst:headings6yaml}
\end{cmhtcbraster}
+ \end{example}
+ \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
@@ -3877,7 +4122,9 @@
\cmhlistingsfromfile[showtabs=true]{demonstrations/headings2-mod7.tex}{\texttt{headings2.tex} using \cref{lst:headings7yaml}}{lst:headings2-mod7}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/headings7.yaml}[yaml-TCB]{\texttt{headings7.yaml}}{lst:headings7yaml}
\end{cmhtcbraster}
+ \end{example}
+ \begin{example}
Finally, let's consider \texttt{noAdditionalIndentGlobal} and \texttt{indentRulesGlobal}
shown in \cref{lst:headings8yaml,lst:headings9yaml} respectively, with respective output
in \cref{lst:headings2-mod8,lst:headings2-mod9}. Note that in \cref{lst:headings8yaml}
@@ -3897,6 +4144,7 @@
\cmhlistingsfromfile[showspaces=true,showtabs=true]{demonstrations/headings2-mod9.tex}{\texttt{headings2.tex} using \cref{lst:headings9yaml}}{lst:headings2-mod9}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/headings9.yaml}[yaml-TCB]{\texttt{headings9.yaml}}{lst:headings9yaml}
\end{cmhtcbraster}
+ \end{example}
% 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
@@ -3918,16 +4166,14 @@
\texttt{keyEqualsValuesBracesBrackets: name} fields of the fine tuning section in
\vref{lst:fineTuning} \announce{2019-07-13}{fine tuning: keyEqualsValuesBracesBrackets}%
+ \begin{example}
An example is shown in \cref{lst:pgfkeysbefore}, with the default output given in
\cref{lst:pgfkeys1:default}.
- \begin{minipage}{.45\textwidth}
+ \begin{cmhtcbraster}
\cmhlistingsfromfile{demonstrations/pgfkeys1.tex}{\texttt{pgfkeys1.tex}}{lst:pgfkeysbefore}
- \end{minipage}%
- \hfill
- \begin{minipage}{.5\textwidth}
\cmhlistingsfromfile[showtabs=true]{demonstrations/pgfkeys1-default.tex}{\texttt{pgfkeys1.tex} default output}{lst:pgfkeys1:default}
- \end{minipage}%
+ \end{cmhtcbraster}
In \cref{lst:pgfkeys1:default}, note that the maximum indentation is three tabs, and
these come from:
@@ -3939,6 +4185,8 @@
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:
\begin{itemize}
@@ -3953,16 +4201,14 @@
\texttt{NamedGroupingBracesBrackets: name} fields of the fine tuning section in
\vref{lst:fineTuning} \announce{2019-07-13}{fine tuning: namedGroupingBracesBrackets}%
+ \begin{example}
A simple example is given in \cref{lst:child1}, with default output in
\cref{lst:child1:default}.
- \begin{minipage}{.45\textwidth}
+ \begin{cmhtcbraster}
\cmhlistingsfromfile{demonstrations/child1.tex}{\texttt{child1.tex}}{lst:child1}
- \end{minipage}%
- \hfill
- \begin{minipage}{.5\textwidth}
\cmhlistingsfromfile[showtabs=true]{demonstrations/child1-default.tex}{\texttt{child1.tex} default output}{lst:child1:default}
- \end{minipage}%
+ \end{cmhtcbraster}
In particular, \texttt{latexindent.pl} considers \texttt{child}, \texttt{parent} and
\texttt{node} all to be \texttt{namedGroupingBracesBrackets}\footnote{ You may like to
@@ -3976,6 +4222,7 @@
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:
@@ -3988,16 +4235,14 @@
See the \texttt{UnNamedGroupingBracesBrackets: follow} field of the fine tuning section
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
\cref{lst:psforeach:default}.
- \begin{minipage}{.45\textwidth}
+ \begin{cmhtcbraster}
\cmhlistingsfromfile{demonstrations/psforeach1.tex}{\texttt{psforeach1.tex}}{lst:psforeach1}
- \end{minipage}%
- \hfill
- \begin{minipage}{.5\textwidth}
\cmhlistingsfromfile[showtabs=true]{demonstrations/psforeach1-default.tex}{\texttt{psforeach1.tex} default output}{lst:psforeach:default}
- \end{minipage}%
+ \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:
@@ -4009,6 +4254,8 @@
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}.
@@ -4046,17 +4293,15 @@
\yamltitle{roundParenthesesAllowed}{0|1}
+ \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}.
- \begin{minipage}{.45\textwidth}
+ \begin{cmhtcbraster}
\cmhlistingsfromfile{demonstrations/pstricks1.tex}{\texttt{pstricks1.tex}}{lst:pstricks1}
- \end{minipage}
- \hfill
- \begin{minipage}{.45\textwidth}
\cmhlistingsfromfile{demonstrations/pstricks1-default.tex}{\texttt{pstricks1} default output}{lst:pstricks1-default}
- \end{minipage}
+ \end{cmhtcbraster}
Notice that the \lstinline!\defFunction! command has an optional argument, followed by a
mandatory argument, followed by a round-parenthesis argument, $(u,v)$.
@@ -4074,9 +4319,11 @@
Upon using the YAML settings in \cref{lst:noRoundParentheses}, and running the command
\index{switches!-l demonstration}
+
\begin{commandshell}
latexindent.pl pstricks1.tex -l noRoundParentheses.yaml
\end{commandshell}
+
we obtain the output given in \cref{lst:pstricks1-nrp}.
\begin{cmhtcbraster}[raster column skip=.1\linewidth]
@@ -4091,12 +4338,16 @@
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}
+ \begin{example}
Let's explore this using the YAML given in \cref{lst:defFunction} and run the command
\index{switches!-l demonstration}
+
\begin{commandshell}
latexindent.pl pstricks1.tex -l defFunction.yaml
\end{commandshell}
+
then the output is as in \cref{lst:pstricks1-indent-rules}.
\begin{cmhtcbraster}[raster column skip=.1\linewidth]
@@ -4108,19 +4359,18 @@
\lstinline!defFunction! command i.e, the subsequent lines containing arguments after the
command name, have received the single space of indentation specified by
\cref{lst:defFunction}.
+ \end{example}
\yamltitle{stringsAllowedBetweenArguments}*{fields}
+ \begin{example}
\texttt{tikz} users may well specify code such as that given in
\cref{lst:tikz-node1}; processing this code using
\texttt{latexindent.pl} gives the default output in \cref{lst:tikz-node1-default}.
- \begin{minipage}{.45\textwidth}
- \cmhlistingsfromfile[columns=fixed]{demonstrations/tikz-node1.tex}{\texttt{tikz-node1.tex}}{lst:tikz-node1}
- \end{minipage}
- \hfill
- \begin{minipage}{.45\textwidth}
- \cmhlistingsfromfile[columns=fixed]{demonstrations/tikz-node1-default.tex}{\texttt{tikz-node1} default output}{lst:tikz-node1-default}
- \end{minipage}
+ \begin{cmhtcbraster}
+ \cmhlistingsfromfile{demonstrations/tikz-node1.tex}{\texttt{tikz-node1.tex}}{lst:tikz-node1}
+ \cmhlistingsfromfile{demonstrations/tikz-node1-default.tex}{\texttt{tikz-node1} default output}{lst:tikz-node1-default}
+ \end{cmhtcbraster}
With reference to \vref{lst:commandCodeBlocks}, we see that the strings
\begin{quote}
@@ -4141,12 +4391,16 @@
\item the string \lstinline!node! (specified in \texttt{stringsAllowedBetweenArguments})
\item the optional argument \lstinline![below,align=left,scale=0.5]!
\end{itemize}
+ \end{example}
+ \begin{example}
We can explore this further, for example using \cref{lst:draw} and running the command
\index{switches!-l demonstration}
+
\begin{commandshell}
latexindent.pl tikz-node1.tex -l draw.yaml
\end{commandshell}
+
we receive the output given in \cref{lst:tikz-node1-draw}.
\begin{cmhtcbraster}[raster column skip=.1\linewidth]
@@ -4160,9 +4414,11 @@
Let's compare this with the output from using the YAML settings in \cref{lst:no-strings},
and running the command \index{switches!-l demonstration}
+
\begin{commandshell}
latexindent.pl tikz-node1.tex -l no-strings.yaml
\end{commandshell}
+
given in \cref{lst:tikz-node1-no-strings}.
\begin{cmhtcbraster}[raster column skip=.1\linewidth]
@@ -4180,6 +4436,7 @@
\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}
Referencing \vref{lst:commandCodeBlocks}, \announce{2018-04-27}*{amalgamate feature in
commandCodeBlocks}, we see that the first field in the
@@ -4209,6 +4466,7 @@
field, and specified using the syntax given in
\cref{lst:amalgamate-demo1,lst:amalgamate-demo2,lst:amalgamate-demo3}.
+ \begin{example}
We may explore this feature further with the code in \cref{lst:for-each}, whose default
output is given in \cref{lst:for-each-default}.
@@ -4219,9 +4477,11 @@
Let's compare this with the output from using the YAML settings in \cref{lst:foreach},
and running the command \index{switches!-l demonstration}
+
\begin{commandshell}
latexindent.pl for-each.tex -l foreach.yaml
\end{commandshell}
+
given in \cref{lst:for-each-mod1}.
\begin{cmhtcbraster}[raster column skip=.1\linewidth]
@@ -4236,6 +4496,7 @@
\cref{lst:for-each-mod1} the \texttt{foreach} command has been allowed to have
\lstinline!\x/\y! and \texttt{in} between arguments because of the settings given in
\cref{lst:foreach}.
+ \end{example}
\yamltitle{commandNameSpecial}*{fields}
There are some special command names \announce{2018-04-27}*{commandNameSpecial} that do
@@ -4246,6 +4507,7 @@
\texttt{latexindent.pl} would not be able to label it as such, because the \lstinline![!
is, necessarily, not matched by a closing \lstinline!]!.%
+ \begin{example}
For example, consider the sample file in \cref{lst:ifnextchar}, which has default output
in \cref{lst:ifnextchar-default}.
@@ -4271,6 +4533,7 @@
\cmhlistingsfromfile{demonstrations/ifnextchar-off.tex}{\texttt{ifnextchar.tex} using \cref{lst:no-ifnextchar}}{lst:ifnextchar-off}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/no-ifnextchar.yaml}[yaml-TCB]{\texttt{no-ifnextchar.yaml}}{lst:no-ifnextchar}
\end{cmhtcbraster}
+ \end{example}
The \texttt{amalgamate} field can be used for \texttt{commandNameSpecial}, just as for
\texttt{stringsAllowedBetweenArguments}. The same condition holds as stated previously,
@@ -4329,11 +4592,16 @@
\yamltitle{condenseMultipleBlankLinesInto}*{positive integer}
Assuming that this switch takes an integer value greater than \texttt{0},
\texttt{latexindent.pl} will condense multiple blank lines into the number of blank lines
- illustrated by this switch. As an example, \cref{lst:mlb-bl} shows a sample file with
- blank lines; upon running \index{switches!-m demonstration}
+ illustrated by this switch.
+
+ \begin{example}
+ As an example, \cref{lst:mlb-bl} shows a sample file with blank lines; upon running
+ \index{switches!-m demonstration}
+
\begin{commandshell}
latexindent.pl myfile.tex -m -o=+-mod1
\end{commandshell}
+
the output is shown in \cref{lst:mlb-bl-out}; note that the multiple blank lines have
been condensed into one blank line, and note also that we have used the \texttt{-m}
switch!
@@ -4342,6 +4610,7 @@
\cmhlistingsfromfile{demonstrations/mlb1.tex}{\texttt{mlb1.tex}}{lst:mlb-bl}
\cmhlistingsfromfile{demonstrations/mlb1-out.tex}{\texttt{mlb1-mod1.tex}}{lst:mlb-bl-out}
\end{cmhtcbraster}
+ \end{example}
% arara: pdflatex: { files: [latexindent]}
\subsection{Text Wrapping}\label{subsec:textwrapping}
\announce{2022-03-13}{text wrap overhaul}\emph{The text wrapping routine has been over-hauled as
@@ -4392,58 +4661,64 @@
\subsubsection{Text wrap: simple examples}\label{subsec:textwrapping-quick-start}
\begin{example}
- Let's use the sample text given in \cref{lst:textwrap1}. \index{text wrap!quick start}
+ Let's use the sample text given in \cref{lst:textwrap1}. \index{text wrap!quick start}
- \cmhlistingsfromfile{demonstrations/textwrap1.tex}{\texttt{textwrap1.tex}}{lst:textwrap1}
+ \cmhlistingsfromfile{demonstrations/textwrap1.tex}{\texttt{textwrap1.tex}}{lst:textwrap1}
- We will change the value of \texttt{columns} in \cref{lst:textwrap1-yaml} and then run
- the command
- \begin{commandshell}
+ We will change the value of \texttt{columns} in \cref{lst:textwrap1-yaml} and then run
+ the command
+
+ \begin{commandshell}
latexindent.pl -m -l textwrap1.yaml textwrap1.tex
\end{commandshell}
- then we receive the output given in \cref{lst:textwrap1-mod1}.
- \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}
- \end{cmhtcbraster}
+ then we receive the output given in \cref{lst:textwrap1-mod1}.
+
+ \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}
+ \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}
+ 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{demonstrations/textwrap1A.yaml}[MLB-TCB]{\texttt{textwrap1A.yaml}}{lst:textwrap1A-yaml}
- and running
- \begin{commandshell}
+ and running
+
+ \begin{commandshell}
latexindent.pl -m -l textwrap1A.yaml textwrap1-mod1.tex
\end{commandshell}
- gives the output in \cref{lst:textwrap1-mod1A}.
- \cmhlistingsfromfile{demonstrations/textwrap1-mod1A.tex}{\texttt{textwrap1-mod1A.tex}}{lst:textwrap1-mod1A}
+ gives the output in \cref{lst:textwrap1-mod1A}.
+
+ \cmhlistingsfromfile{demonstrations/textwrap1-mod1A.tex}{\texttt{textwrap1-mod1A.tex}}{lst:textwrap1-mod1A}
\end{example}
\begin{example}
- By default, the text wrapping routine will convert multiple spaces into single spaces.
- You can change this behaviour by flicking the switch \texttt{multipleSpacesToSingle}
- which we have done in \cref{lst:textwrap1B-yaml}
+ By default, the text wrapping routine will convert multiple spaces into single spaces.
+ You can change this behaviour by flicking the switch \texttt{multipleSpacesToSingle}
+ which we have done in \cref{lst:textwrap1B-yaml}
- Using the settings in \cref{lst:textwrap1B-yaml} and running
- \begin{commandshell}
+ Using the settings in \cref{lst:textwrap1B-yaml} and running
+
+ \begin{commandshell}
latexindent.pl -m -l textwrap1B.yaml textwrap1-mod1.tex
\end{commandshell}
- 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}
- \end{cmhtcbraster}
- We note that in \cref{lst:textwrap1-mod1B} the multiple spaces have \emph{not} been
- condensed into single spaces.
+
+ 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}
+ \end{cmhtcbraster}
+ We note that in \cref{lst:textwrap1-mod1B} the multiple spaces have \emph{not} been
+ condensed into single spaces.
\end{example}
\subsubsection{Text wrap: \texttt{blocksFollow} examples}
@@ -4451,77 +4726,82 @@
wrap!blocksFollow}
\begin{example}
- Let's use the sample text given in \cref{lst:tw-headings1}. \index{text
- wrap!blocksFollow!headings}
+ Let's use the sample text given in \cref{lst:tw-headings1}. \index{text
+ wrap!blocksFollow!headings}
- \cmhlistingsfromfile{demonstrations/tw-headings1.tex}{\texttt{tw-headings1.tex}}{lst:tw-headings1}
+ \cmhlistingsfromfile{demonstrations/tw-headings1.tex}{\texttt{tw-headings1.tex}}{lst:tw-headings1}
- We note that \cref{lst:tw-headings1} contains the heading commands \texttt{section} and
- \texttt{subsection}. Upon running the command
- \begin{commandshell}
+ We note that \cref{lst:tw-headings1} contains the heading commands \texttt{section} and
+ \texttt{subsection}. Upon running the command
+
+ \begin{commandshell}
latexindent.pl -m -l textwrap1.yaml tw-headings1.tex
\end{commandshell}
- then we receive the output given in \cref{lst:tw-headings1-mod1}.
- \cmhlistingsfromfile{demonstrations/tw-headings1-mod1.tex}{\texttt{tw-headings1-mod1.tex}}{lst:tw-headings1-mod1}
+ then we receive the output given in \cref{lst:tw-headings1-mod1}.
- 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.
- \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.
+ \cmhlistingsfromfile{demonstrations/tw-headings1-mod1.tex}{\texttt{tw-headings1-mod1.tex}}{lst:tw-headings1-mod1}
- We can turn off \texttt{headings} as in \cref{lst:bf-no-headings-yaml} and then run
- \begin{commandshell}
+ 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.
+ \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.
+
+ We can turn off \texttt{headings} as in \cref{lst:bf-no-headings-yaml} and then run
+
+ \begin{commandshell}
latexindent.pl -m -l textwrap1.yaml,bf-no-headings.yaml tw-headings1.tex
\end{commandshell}
- gives the output in \cref{lst:tw-headings1-mod2}, in which text wrapping has been
- instructed \emph{not to happen} following headings.
- \begin{cmhtcbraster}[raster column skip=.1\linewidth,
- raster left skip=-3.5cm,
- raster right skip=-2cm,
- ]
- \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}
- \end{cmhtcbraster}
+
+ 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}
+ \end{cmhtcbraster}
\end{example}
\begin{example}
- Let's use the sample text given in \cref{lst:tw-comments1}. \index{text
- wrap!blocksFollow!comments}
+ Let's use the sample text given in \cref{lst:tw-comments1}. \index{text
+ wrap!blocksFollow!comments}
- \cmhlistingsfromfile{demonstrations/tw-comments1.tex}{\texttt{tw-comments1.tex}}{lst:tw-comments1}
+ \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
- \begin{commandshell}
+ 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
\end{commandshell}
- then we receive the output given in \cref{lst:tw-comments1-mod1}.
- \cmhlistingsfromfile{demonstrations/tw-comments1-mod1.tex}{\texttt{tw-comments1-mod1.tex}}{lst:tw-comments1-mod1}
+ then we receive the output given in \cref{lst:tw-comments1-mod1}.
- With reference to \vref{lst:textWrapOptionsAll} the \texttt{commentOnPreviousLine} field
- is set to \texttt{1}, which instructs \texttt{latexindent.pl} to find text wrap blocks
- after a comment on its own line.
+ \cmhlistingsfromfile{demonstrations/tw-comments1-mod1.tex}{\texttt{tw-comments1-mod1.tex}}{lst:tw-comments1-mod1}
- We can turn off \texttt{comments} as in \cref{lst:bf-no-comments-yaml} and then run
- \begin{commandshell}
+ With reference to \vref{lst:textWrapOptionsAll} the \texttt{commentOnPreviousLine} field
+ is set to \texttt{1}, which instructs \texttt{latexindent.pl} to find text wrap blocks
+ after a comment on its own line.
+
+ We can turn off \texttt{comments} as in \cref{lst:bf-no-comments-yaml} and then run
+
+ \begin{commandshell}
latexindent.pl -m -l textwrap1.yaml,bf-no-comments.yaml tw-comments1.tex
\end{commandshell}
- gives the output in \cref{lst:tw-comments1-mod2}, in which text wrapping has been
- instructed \emph{not to happen} following comments on their own line.
- \begin{cmhtcbraster}[raster column skip=.1\linewidth,
- 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}
- \end{cmhtcbraster}
+
+ gives the output in \cref{lst:tw-comments1-mod2}, in which text wrapping has been
+ instructed \emph{not to happen} following comments on their own line.
+ \begin{cmhtcbraster}[raster column skip=.1\linewidth,
+ 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}
+ \end{cmhtcbraster}
\end{example}
Referencing \vref{lst:textWrapOptionsAll} the \texttt{blocksFollow} fields \texttt{par},
@@ -4535,37 +4815,41 @@
bracket}, or in other words, \emph{end of display math} or an item command.
\begin{example}
- Let's use the sample text given in \cref{lst:tw-disp-math1}. \index{text
- wrap!blocksFollow!other} \index{regular expressions!text wrap!blocksFollow}
+ Let's use the sample text given in \cref{lst:tw-disp-math1}. \index{text
+ wrap!blocksFollow!other} \index{regular expressions!text wrap!blocksFollow}
- \cmhlistingsfromfile{demonstrations/tw-disp-math1.tex}{\texttt{tw-disp-math1.tex}}{lst:tw-disp-math1}
+ \cmhlistingsfromfile{demonstrations/tw-disp-math1.tex}{\texttt{tw-disp-math1.tex}}{lst:tw-disp-math1}
- We note that \cref{lst:tw-disp-math1} contains display math. Upon running the command
- \begin{commandshell}
+ We note that \cref{lst:tw-disp-math1} contains display math. Upon running the command
+
+ \begin{commandshell}
latexindent.pl -m -l textwrap1.yaml tw-disp-math1.tex
\end{commandshell}
- then we receive the output given in \cref{lst:tw-disp-math1-mod1}.
- \cmhlistingsfromfile{demonstrations/tw-disp-math1-mod1.tex}{\texttt{tw-disp-math1-mod1.tex}}{lst:tw-disp-math1-mod1}
+ then we receive the output given in \cref{lst:tw-disp-math1-mod1}.
- With reference to \vref{lst:textWrapOptionsAll} the \texttt{other} field is set to
- \lstinline!\\\]!, which instructs \texttt{latexindent.pl} to find text wrap blocks after
- the end of display math.
+ \cmhlistingsfromfile{demonstrations/tw-disp-math1-mod1.tex}{\texttt{tw-disp-math1-mod1.tex}}{lst:tw-disp-math1-mod1}
- We can turn off this switch as in \cref{lst:bf-no-disp-math-yaml} and then run
- \begin{widepage}
- \begin{commandshell}
+ With reference to \vref{lst:textWrapOptionsAll} the \texttt{other} field is set to
+ \lstinline!\\\]!, which instructs \texttt{latexindent.pl} to find text wrap blocks after
+ the end of display math.
+
+ We can turn off this switch as in \cref{lst:bf-no-disp-math-yaml} and then run
+ \begin{widepage}
+
+ \begin{commandshell}
latexindent.pl -m -l textwrap1.yaml,bf-no-disp-math.yaml tw-disp-math1.tex
\end{commandshell}
- \end{widepage}
- 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}
- \end{cmhtcbraster}
- Naturally, you should feel encouraged to customise this as you see fit.
+ \end{widepage}
+ 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}
+ \end{cmhtcbraster}
+
+ Naturally, you should feel encouraged to customise this as you see fit.
\end{example}
The \texttt{blocksFollow} field \emph{deliberately} does not default to allowing text
@@ -4574,35 +4858,39 @@
text wrap individually, as in the next example.
\begin{example}
- Let's use the sample text given in \cref{lst:tw-bf-myenv1}. \index{text
- wrap!blocksFollow!other} \index{regular expressions!text wrap!blocksFollow}
+ Let's use the sample text given in \cref{lst:tw-bf-myenv1}. \index{text
+ wrap!blocksFollow!other} \index{regular expressions!text wrap!blocksFollow}
- \cmhlistingsfromfile{demonstrations/tw-bf-myenv1.tex}{\texttt{tw-bf-myenv1.tex}}{lst:tw-bf-myenv1}
+ \cmhlistingsfromfile{demonstrations/tw-bf-myenv1.tex}{\texttt{tw-bf-myenv1.tex}}{lst:tw-bf-myenv1}
- We note that \cref{lst:tw-bf-myenv1} contains \texttt{myenv} environment. Upon running
- the command
- \begin{commandshell}
+ We note that \cref{lst:tw-bf-myenv1} contains \texttt{myenv} environment. Upon running
+ the command
+
+ \begin{commandshell}
latexindent.pl -m -l textwrap1.yaml tw-bf-myenv1.tex
\end{commandshell}
- then we receive the output given in \cref{lst:tw-bf-myenv1-mod1}.
- \cmhlistingsfromfile{demonstrations/tw-bf-myenv1-mod1.tex}{\texttt{tw-bf-myenv1-mod1.tex}}{lst:tw-bf-myenv1-mod1}
+ then we receive the output given in \cref{lst:tw-bf-myenv1-mod1}.
- We note that we have \emph{not} received much text wrapping. We can turn do better by
- employing \cref{lst:tw-bf-myenv-yaml} and then run
- \begin{commandshell}
+ \cmhlistingsfromfile{demonstrations/tw-bf-myenv1-mod1.tex}{\texttt{tw-bf-myenv1-mod1.tex}}{lst:tw-bf-myenv1-mod1}
+
+ We note that we have \emph{not} received much text wrapping. We can turn do better by
+ employing \cref{lst:tw-bf-myenv-yaml} and then run
+
+ \begin{commandshell}
latexindent.pl -m -l textwrap1.yaml,tw-bf-myenv.yaml tw-bf-myenv1.tex
\end{commandshell}
- 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,
- ]
- \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}
- \end{cmhtcbraster}
+ 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,
+ ]
+ \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}
+ \end{cmhtcbraster}
+
\end{example}
\subsubsection{Text wrap: \texttt{blocksBeginWith} examples}
@@ -4610,56 +4898,64 @@
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}
- and run the command
- \begin{commandshell}
+ 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}
+ and run the command
+
+ \begin{commandshell}
latexindent.pl -m -l textwrap1.yaml tw-0-9.tex
\end{commandshell}
- then we receive the output given in \cref{lst:tw-0-9-mod1} in which text wrapping has
- \emph{not} occured.
- \cmhlistingsfromfile{demonstrations/tw-0-9-mod1.tex}{\texttt{tw-0-9-mod1.tex}}{lst:tw-0-9-mod1}
- We can allow paragraphs to begin with \texttt{0-9} characters by using the settings in
- \cref{lst:bb-0-9-yaml} and running
- \begin{commandshell}
+ then we receive the output given in \cref{lst:tw-0-9-mod1} in which text wrapping has
+ \emph{not} occured.
+ \cmhlistingsfromfile{demonstrations/tw-0-9-mod1.tex}{\texttt{tw-0-9-mod1.tex}}{lst:tw-0-9-mod1}
+
+ We can allow paragraphs to begin with \texttt{0-9} characters by using the settings in
+ \cref{lst:bb-0-9-yaml} and running
+
+ \begin{commandshell}
latexindent.pl -m -l textwrap1.yaml,bb-0-9-yaml tw-0-9.tex
\end{commandshell}
- 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}
- \end{cmhtcbraster}
+
+ 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}
+ \end{cmhtcbraster}
\end{example}
\begin{example}
- Let's now use the file given in \cref{lst:tw-bb-announce1}
- \cmhlistingsfromfile{demonstrations/tw-bb-announce1.tex}{\texttt{tw-bb-announce1.tex}}{lst:tw-bb-announce1}
- and run the command
- \begin{commandshell}
+ Let's now use the file given in \cref{lst:tw-bb-announce1}
+ \cmhlistingsfromfile{demonstrations/tw-bb-announce1.tex}{\texttt{tw-bb-announce1.tex}}{lst:tw-bb-announce1}
+ and run the command
+
+ \begin{commandshell}
latexindent.pl -m -l textwrap1.yaml tw-bb-announce1.tex
\end{commandshell}
- then we receive the output given in \cref{lst:tw-bb-announce1-mod1} in which text
- wrapping has \emph{not} occured.
- \cmhlistingsfromfile{demonstrations/tw-bb-announce1-mod1.tex}{\texttt{tw-bb-announce1-mod1.tex}}{lst:tw-bb-announce1-mod1}
+ then we receive the output given in \cref{lst:tw-bb-announce1-mod1} in which text
+ wrapping has \emph{not} occured.
- We can allow \lstinline!\announce! to be at the beginning of paragraphs by using the
- settings in \cref{lst:tw-bb-announce-yaml} and running
- \begin{widepage}
- \begin{commandshell}
+ \cmhlistingsfromfile{demonstrations/tw-bb-announce1-mod1.tex}{\texttt{tw-bb-announce1-mod1.tex}}{lst:tw-bb-announce1-mod1}
+
+ We can allow \lstinline!\announce! to be at the beginning of paragraphs by using the
+ settings in \cref{lst:tw-bb-announce-yaml} and running
+ \begin{widepage}
+
+ \begin{commandshell}
latexindent.pl -m -l textwrap1.yaml,tw-bb-announce.yaml tw-bb-announce1.tex
\end{commandshell}
- \end{widepage}
- 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}
- \end{cmhtcbraster}
+ \end{widepage}
+ 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}
+ \end{cmhtcbraster}
+
\end{example}
\subsubsection{Text wrap: \texttt{blocksEndBefore} examples}
@@ -4667,40 +4963,44 @@
series of examples. \index{text wrap!blocksEndBefore}
\begin{example}
- Let's use the sample text given in \cref{lst:tw-be-equation}. \index{text
- wrap!blocksFollow!other} \index{regular expressions!text wrap!blocksFollow}
+ Let's use the sample text given in \cref{lst:tw-be-equation}. \index{text
+ wrap!blocksFollow!other} \index{regular expressions!text wrap!blocksFollow}
- \cmhlistingsfromfile{demonstrations/tw-be-equation.tex}{\texttt{tw-be-equation.tex}}{lst:tw-be-equation}
+ \cmhlistingsfromfile{demonstrations/tw-be-equation.tex}{\texttt{tw-be-equation.tex}}{lst:tw-be-equation}
- We note that \cref{lst:tw-be-equation} contains an environment. Upon running the command
- \begin{commandshell}
+ We note that \cref{lst:tw-be-equation} contains an environment. Upon running the command
+
+ \begin{commandshell}
latexindent.pl -m -l textwrap1A.yaml tw-be-equation.tex
\end{commandshell}
- then we receive the output given in \cref{lst:tw-be-equation-mod1}.
- \cmhlistingsfromfile{demonstrations/tw-be-equation-mod1.tex}{\texttt{tw-be-equation-mod1.tex}}{lst:tw-be-equation-mod1}
+ then we receive the output given in \cref{lst:tw-be-equation-mod1}.
- With reference to \vref{lst:textWrapOptionsAll} the \texttt{other} field is set to
- \lstinline!\\begin\{|\\\[|\\end\{!, which instructs \texttt{latexindent.pl} to
- \emph{stop} text wrap blocks before \texttt{begin} statements, display math, and
- \texttt{end} statements.
+ \cmhlistingsfromfile{demonstrations/tw-be-equation-mod1.tex}{\texttt{tw-be-equation-mod1.tex}}{lst:tw-be-equation-mod1}
- We can turn off this switch as in \cref{lst:tw-be-equation-yaml} and then run
- \begin{widepage}
- \begin{commandshell}
+ With reference to \vref{lst:textWrapOptionsAll} the \texttt{other} field is set to
+ \lstinline!\\begin\{|\\\[|\\end\{!, which instructs \texttt{latexindent.pl} to
+ \emph{stop} text wrap blocks before \texttt{begin} statements, display math, and
+ \texttt{end} statements.
+
+ We can turn off this switch as in \cref{lst:tw-be-equation-yaml} and then run
+ \begin{widepage}
+
+ \begin{commandshell}
latexindent.pl -m -l textwrap1A.yaml,tw-be-equation.yaml tw-be-equation.tex
\end{commandshell}
- \end{widepage}
- 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}
+ \end{widepage}
+ gives the output in \cref{lst:tw-be-equation-mod2}, in which text wrapping has been
+ instructed \emph{not} to stop at these statements.
- \begin{widepage}
- \cmhlistingsfromfile{demonstrations/tw-be-equation-mod2.tex}{\texttt{tw-be-equation-mod2.tex}}{lst:tw-be-equation-mod2}
- \end{widepage}
+ \cmhlistingsfromfile{demonstrations/tw-be-equation.yaml}[MLB-TCB]{\texttt{tw-be-equation.yaml}}{lst:tw-be-equation-yaml}
- Naturally, you should feel encouraged to customise this as you see fit.
+ \begin{widepage}
+ \cmhlistingsfromfile{demonstrations/tw-be-equation-mod2.tex}{\texttt{tw-be-equation-mod2.tex}}{lst:tw-be-equation-mod2}
+ \end{widepage}
+
+ Naturally, you should feel encouraged to customise this as you see fit.
\end{example}
\subsubsection{Text wrap: trailing comments and spaces}
@@ -4708,94 +5008,106 @@
the following examples.
\begin{example}
- The file in \cref{lst:tw-tc1} contains a trailing comment which \emph{does} have a space
- infront of it.
+ The file in \cref{lst:tw-tc1} contains a trailing comment which \emph{does} have a space
+ infront of it.
- Running the command
- \begin{commandshell}
+ Running the command
+
+ \begin{commandshell}
latexindent.pl -m tw-tc1.tex -l textwrap1A.yaml -o=+-mod1
\end{commandshell}
- gives the output given in \cref{lst:tw-tc1-mod1}.
- \begin{cmhtcbraster}[raster column skip=.1\linewidth]
- \cmhlistingsfromfile[showspaces=true]{demonstrations/tw-tc1.tex}{\texttt{tw-tc1.tex}}{lst:tw-tc1}
- \cmhlistingsfromfile{demonstrations/tw-tc1-mod1.tex}{\texttt{tw-tc1-mod1.tex}}{lst:tw-tc1-mod1}
- \end{cmhtcbraster}
+ gives the output given in \cref{lst:tw-tc1-mod1}.
+
+ \begin{cmhtcbraster}[raster column skip=.1\linewidth]
+ \cmhlistingsfromfile[showspaces=true]{demonstrations/tw-tc1.tex}{\texttt{tw-tc1.tex}}{lst:tw-tc1}
+ \cmhlistingsfromfile{demonstrations/tw-tc1-mod1.tex}{\texttt{tw-tc1-mod1.tex}}{lst:tw-tc1-mod1}
+ \end{cmhtcbraster}
\end{example}
\begin{example}
- The file in \cref{lst:tw-tc2} contains a trailing comment which does \emph{not} have a
- space infront of it.
+ The file in \cref{lst:tw-tc2} contains a trailing comment which does \emph{not} have a
+ space infront of it.
- Running the command
- \begin{commandshell}
+ Running the command
+
+ \begin{commandshell}
latexindent.pl -m tw-tc2.tex -l textwrap1A.yaml -o=+-mod1
\end{commandshell}
- gives the output in \cref{lst:tw-tc2-mod1}.
- \begin{cmhtcbraster}[raster column skip=.1\linewidth]
- \cmhlistingsfromfile{demonstrations/tw-tc2.tex}{\texttt{tw-tc2.tex}}{lst:tw-tc2}
- \cmhlistingsfromfile{demonstrations/tw-tc2-mod1.tex}{\texttt{tw-tc2-mod1.tex}}{lst:tw-tc2-mod1}
- \end{cmhtcbraster}
- We note that, because there is \emph{not} a space before the trailing comment, that the
- lines have been joined \emph{without} a space.
+
+ gives the output in \cref{lst:tw-tc2-mod1}.
+ \begin{cmhtcbraster}[raster column skip=.1\linewidth]
+ \cmhlistingsfromfile{demonstrations/tw-tc2.tex}{\texttt{tw-tc2.tex}}{lst:tw-tc2}
+ \cmhlistingsfromfile{demonstrations/tw-tc2-mod1.tex}{\texttt{tw-tc2-mod1.tex}}{lst:tw-tc2-mod1}
+ \end{cmhtcbraster}
+ We note that, because there is \emph{not} a space before the trailing comment, that the
+ lines have been joined \emph{without} a space.
\end{example}
\begin{example}
- The file in \cref{lst:tw-tc3} contains multiple trailing comments.
+ The file in \cref{lst:tw-tc3} contains multiple trailing comments.
- Running the command
- \begin{commandshell}
+ Running the command
+
+ \begin{commandshell}
latexindent.pl -m tw-tc3.tex -l textwrap1A.yaml -o=+-mod1
\end{commandshell}
- gives the output in \cref{lst:tw-tc3-mod1}.
- \begin{cmhtcbraster}[raster column skip=.1\linewidth]
- \cmhlistingsfromfile{demonstrations/tw-tc3.tex}{\texttt{tw-tc3.tex}}{lst:tw-tc3}
- \cmhlistingsfromfile{demonstrations/tw-tc3-mod1.tex}{\texttt{tw-tc3-mod1.tex}}{lst:tw-tc3-mod1}
- \end{cmhtcbraster}
+
+ gives the output in \cref{lst:tw-tc3-mod1}.
+ \begin{cmhtcbraster}[raster column skip=.1\linewidth]
+ \cmhlistingsfromfile{demonstrations/tw-tc3.tex}{\texttt{tw-tc3.tex}}{lst:tw-tc3}
+ \cmhlistingsfromfile{demonstrations/tw-tc3-mod1.tex}{\texttt{tw-tc3-mod1.tex}}{lst:tw-tc3-mod1}
+ \end{cmhtcbraster}
\end{example}
\begin{example}
- The file in \cref{lst:tw-tc4} contains multiple trailing comments.
+ The file in \cref{lst:tw-tc4} contains multiple trailing comments.
- Running the command
- \begin{commandshell}
+ Running the command
+
+ \begin{commandshell}
latexindent.pl -m tw-tc4.tex -l textwrap1A.yaml -o=+-mod1
\end{commandshell}
- gives the output in \cref{lst:tw-tc4-mod1}.
- \begin{cmhtcbraster}[raster column skip=.1\linewidth]
- \cmhlistingsfromfile{demonstrations/tw-tc4.tex}{\texttt{tw-tc4.tex}}{lst:tw-tc4}
- \cmhlistingsfromfile{demonstrations/tw-tc4-mod1.tex}{\texttt{tw-tc4-mod1.tex}}{lst:tw-tc4-mod1}
- \end{cmhtcbraster}
+
+ gives the output in \cref{lst:tw-tc4-mod1}.
+ \begin{cmhtcbraster}[raster column skip=.1\linewidth]
+ \cmhlistingsfromfile{demonstrations/tw-tc4.tex}{\texttt{tw-tc4.tex}}{lst:tw-tc4}
+ \cmhlistingsfromfile{demonstrations/tw-tc4-mod1.tex}{\texttt{tw-tc4-mod1.tex}}{lst:tw-tc4-mod1}
+ \end{cmhtcbraster}
\end{example}
\begin{example}
- The file in \cref{lst:tw-tc5} contains multiple trailing comments.
+ The file in \cref{lst:tw-tc5} contains multiple trailing comments.
- Running the command
- \begin{commandshell}
+ Running the command
+
+ \begin{commandshell}
latexindent.pl -m tw-tc5.tex -l textwrap1A.yaml -o=+-mod1
\end{commandshell}
- gives the output in \cref{lst:tw-tc5-mod1}.
- \begin{cmhtcbraster}[raster column skip=.1\linewidth]
- \cmhlistingsfromfile[showspaces=true]{demonstrations/tw-tc5.tex}{\texttt{tw-tc5.tex}}{lst:tw-tc5}
- \cmhlistingsfromfile[showspaces=true]{demonstrations/tw-tc5-mod1.tex}{\texttt{tw-tc5-mod1.tex}}{lst:tw-tc5-mod1}
- \end{cmhtcbraster}
- The space at the end of the text block has been preserved.
+
+ gives the output in \cref{lst:tw-tc5-mod1}.
+ \begin{cmhtcbraster}[raster column skip=.1\linewidth]
+ \cmhlistingsfromfile[showspaces=true]{demonstrations/tw-tc5.tex}{\texttt{tw-tc5.tex}}{lst:tw-tc5}
+ \cmhlistingsfromfile[showspaces=true]{demonstrations/tw-tc5-mod1.tex}{\texttt{tw-tc5-mod1.tex}}{lst:tw-tc5-mod1}
+ \end{cmhtcbraster}
+ The space at the end of the text block has been preserved.
\end{example}
\begin{example}
- The file in \cref{lst:tw-tc6} contains multiple trailing comments.
+ The file in \cref{lst:tw-tc6} contains multiple trailing comments.
- Running the command
- \begin{commandshell}
+ Running the command
+
+ \begin{commandshell}
latexindent.pl -m tw-tc6.tex -l textwrap1A.yaml -o=+-mod1
\end{commandshell}
- gives the output in \cref{lst:tw-tc6-mod1}.
- \begin{cmhtcbraster}[raster column skip=.1\linewidth]
- \cmhlistingsfromfile[showspaces=true]{demonstrations/tw-tc6.tex}{\texttt{tw-tc6.tex}}{lst:tw-tc6}
- \cmhlistingsfromfile[showspaces=true]{demonstrations/tw-tc6-mod1.tex}{\texttt{tw-tc6-mod1.tex}}{lst:tw-tc6-mod1}
- \end{cmhtcbraster}
- The space at the end of the text block has been preserved.
+
+ gives the output in \cref{lst:tw-tc6-mod1}.
+ \begin{cmhtcbraster}[raster column skip=.1\linewidth]
+ \cmhlistingsfromfile[showspaces=true]{demonstrations/tw-tc6.tex}{\texttt{tw-tc6.tex}}{lst:tw-tc6}
+ \cmhlistingsfromfile[showspaces=true]{demonstrations/tw-tc6-mod1.tex}{\texttt{tw-tc6-mod1.tex}}{lst:tw-tc6-mod1}
+ \end{cmhtcbraster}
+ The space at the end of the text block has been preserved.
\end{example}
\subsubsection{Text wrap: huge, tabstop and separator}
@@ -4815,13 +5127,16 @@
recommend changing this field.
\end{warning}
+ \begin{example}
For example, using the settings in \cref{lst:textwrap2A-yaml,lst:textwrap2B-yaml} and
running the commands \index{switches!-l demonstration} \index{switches!-m demonstration}
\index{switches!-o demonstration}
+
\begin{commandshell}
latexindent.pl -m textwrap4.tex -o=+-mod2A -l textwrap2A.yaml
latexindent.pl -m textwrap4.tex -o=+-mod2B -l textwrap2B.yaml
\end{commandshell}
+
gives the respective output in \cref{lst:textwrap4-mod2A,lst:textwrap4-mod2B}.
\begin{cmhtcbraster}[raster column skip=.1\linewidth]
@@ -4831,15 +5146,21 @@
\cmhlistingsfromfile{demonstrations/textwrap4-mod2B.tex}{\texttt{textwrap4-mod2B.tex}}{lst:textwrap4-mod2B}
\cmhlistingsfromfile{demonstrations/textwrap2B.yaml}[MLB-TCB]{\texttt{textwrap2B.yaml}}{lst:textwrap2B-yaml}
\end{cmhtcbraster}
+ \end{example}
You can also specify the \texttt{tabstop} field \announce{2020-11-06}{tabstop option for
text wrap module} as an integer value, which is passed to the text wrap module; see
- \cite{textwrap} for details. Starting with the code in \cref{lst:textwrap-ts} with
- settings in \cref{lst:tabstop}, and running the command \index{switches!-l demonstration}
- \index{switches!-m demonstration} \index{switches!-o demonstration}%
+ \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}%
+
\begin{commandshell}
latexindent.pl -m textwrap-ts.tex -o=+-mod1 -l tabstop.yaml
\end{commandshell}
+
gives the code given in \cref{lst:textwrap-ts-mod1}.
\begin{cmhtcbraster}[raster columns=3,
raster left skip=-3.5cm,
@@ -4849,6 +5170,7 @@
\cmhlistingsfromfile{demonstrations/tabstop.yaml}[MLB-TCB]{\texttt{tabstop.yaml}}{lst:tabstop}
\cmhlistingsfromfile[showtabs=true]{demonstrations/textwrap-ts-mod1.tex}{\texttt{textwrap-ts-mod1.tex}}{lst:textwrap-ts-mod1}
\end{cmhtcbraster}
+ \end{example}
You can specify \texttt{separator}, \texttt{break} and \texttt{unexpand} options in your
settings in analogous ways to those demonstrated in
@@ -4881,6 +5203,7 @@
switch to \texttt{0} instructs \texttt{latexindent.pl} not to do so.
\index{sentences!removing sentence line breaks}
+ \begin{example}
For example, consider \texttt{multiple-sentences.tex} shown in
\cref{lst:multiple-sentences}.
@@ -4890,10 +5213,12 @@
\cref{lst:manipulate-sentences-yaml,lst:keep-sen-line-breaks-yaml}, and run the commands
\index{switches!-l demonstration} \index{switches!-m demonstration}
\begin{widepage}
+
\begin{commandshell}
latexindent.pl multiple-sentences -m -l=manipulate-sentences.yaml
latexindent.pl multiple-sentences -m -l=keep-sen-line-breaks.yaml
\end{commandshell}
+
\end{widepage}
then we obtain the respective output given in
\cref{lst:multiple-sentences-mod1,lst:multiple-sentences-mod2}.
@@ -4911,6 +5236,7 @@
Notice, in particular, that the `internal' sentence line breaks in
\cref{lst:multiple-sentences} have been removed in \cref{lst:multiple-sentences-mod1},
but have not been removed in \cref{lst:multiple-sentences-mod2}.
+ \end{example}
\yamltitle{multipleSpacesToSingle}{0|1}
\announce{2022-03-25}*{multipleSpacesToSingle for oneSentencePerLine} By default, the
@@ -4947,13 +5273,17 @@
\end{cmhtcbraster}
\subsubsection{sentencesFollow}
- Let's explore a few of the switches in \texttt{sentencesFollow}; let's start with
- \vref{lst:multiple-sentences}, and use the YAML settings given in
+ Let's explore a few of the switches in \texttt{sentencesFollow}.
+
+ \begin{example}
+ We start with \vref{lst:multiple-sentences}, and use the YAML settings given in
\cref{lst:sentences-follow1-yaml}. Using the command \index{sentences!follow}
\index{switches!-l demonstration} \index{switches!-m demonstration}
+
\begin{commandshell}
latexindent.pl multiple-sentences -m -l=sentences-follow1.yaml
\end{commandshell}
+
we obtain the output given in \cref{lst:multiple-sentences-mod3}.
\begin{cmhtcbraster}
@@ -4964,7 +5294,9 @@
Notice that, because \texttt{blankLine} is set to \texttt{0}, \texttt{latexindent.pl}
will not seek sentences following a blank line, and so the fourth sentence has not been
accounted for.
+ \end{example}
+ \begin{example}
We can explore the \texttt{other} field in \cref{lst:sentencesFollow} with the
\texttt{.tex} file detailed in \cref{lst:multiple-sentences1}.
@@ -4973,10 +5305,12 @@
Upon running the following commands \index{switches!-l demonstration} \index{switches!-m
demonstration}
\begin{widepage}
+
\begin{commandshell}
latexindent.pl multiple-sentences1 -m -l=manipulate-sentences.yaml
latexindent.pl multiple-sentences1 -m -l=manipulate-sentences.yaml,sentences-follow2.yaml
\end{commandshell}
+
\end{widepage}
then we obtain the respective output given in
\cref{lst:multiple-sentences1-mod1,lst:multiple-sentences1-mod2}.
@@ -4995,6 +5329,7 @@
\cref{lst:sentences-follow2-yaml}, the output given in
\cref{lst:multiple-sentences1-mod2} demonstrates that the sentence \emph{has} been
accounted for correctly.
+ \end{example}
\subsubsection{sentencesBeginWith}
By default, \texttt{latexindent.pl} will only assume that sentences begin with the upper
@@ -5002,15 +5337,20 @@
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}.
+
\cmhlistingsfromfile{demonstrations/multiple-sentences2.tex}{\texttt{multiple-sentences2.tex}}{lst:multiple-sentences2}
Upon running the following commands \index{switches!-l demonstration} \index{switches!-m
demonstration}
\begin{widepage}
+
\begin{commandshell}
latexindent.pl multiple-sentences2 -m -l=manipulate-sentences.yaml
latexindent.pl multiple-sentences2 -m -l=manipulate-sentences.yaml,sentences-begin1.yaml
\end{commandshell}
+
\end{widepage}
then we obtain the respective output given in
\cref{lst:multiple-sentences2-mod1,lst:multiple-sentences2-mod2}.
@@ -5029,8 +5369,10 @@
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}
+ \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
\vref{lst:multiple-sentences-mod1}. We can populate the \texttt{other} field with any
@@ -5037,10 +5379,12 @@
character that we wish; for example, using the YAML specified in
\cref{lst:sentences-end1-yaml} and the command \index{sentences!end with}
\index{switches!-l demonstration} \index{switches!-m demonstration}
+
\begin{commandshell}
latexindent.pl multiple-sentences -m -l=sentences-end1.yaml
latexindent.pl multiple-sentences -m -l=sentences-end2.yaml
\end{commandshell}
+
then we obtain the output in \cref{lst:multiple-sentences-mod4}. \index{regular
expressions!lowercase alph a-z}
@@ -5061,11 +5405,13 @@
lower case letters. We have changed this by using the settings in
\cref{lst:sentences-end2-yaml}, and the associated output in
\cref{lst:multiple-sentences-mod5} reflects this.
+ \end{example}
Referencing \vref{lst:sentencesEndWith}, you'll notice that there is a field called
\texttt{basicFullStop}, which is set to \texttt{0}, and that the \texttt{betterFullStop}
is set to \texttt{1} by default.
+ \begin{example}
Let's consider the file shown in \cref{lst:url}.
\cmhlistingsfromfile{demonstrations/url.tex}{\texttt{url.tex}}{lst:url}
@@ -5072,9 +5418,11 @@
Upon running the following commands \index{switches!-l demonstration} \index{switches!-m
demonstration}
+
\begin{commandshell}
latexindent.pl url -m -l=manipulate-sentences.yaml
\end{commandshell}
+
we obtain the output given in \cref{lst:url-mod1}.
\cmhlistingsfromfile{demonstrations/url-mod1.tex}{\texttt{url.tex} using \vref{lst:manipulate-sentences-yaml}}{lst:url-mod1}
@@ -5087,6 +5435,8 @@
\item they can not be immediately followed by a lower case or upper case letter;
\item they can not be immediately followed by a hyphen, comma, or number.
\end{itemize}
+ \end{example}
+
If you find that the \texttt{betterFullStop} does not work for your purposes, then you
can switch it off by setting it to \texttt{0}, and you can experiment with the
\texttt{other} field. \announce{2019-07-13}{fine tuning the betterFullStop} You can also
@@ -5094,11 +5444,16 @@
detailed in \vref{lst:fineTuning}.%
The \texttt{basicFullStop} routine should probably be avoided in most situations, as it
- does not accommodate the specifications above. For example, using the following command
- \index{switches!-l demonstration} \index{switches!-m demonstration}
+ does not accommodate the specifications above.
+
+ \begin{example}
+ For example, using the following command \index{switches!-l demonstration}
+ \index{switches!-m demonstration}
+
\begin{commandshell}
latexindent.pl url -m -l=alt-full-stop1.yaml
\end{commandshell}
+
and the YAML in \cref{lst:alt-full-stop1-yaml} gives the output in \cref{lst:url-mod2}.
\begin{cmhtcbraster}[ raster left skip=-3.5cm,
@@ -5112,6 +5467,7 @@
Notice that the full stop within the URL has not been accommodated correctly because of
the non-default settings in \cref{lst:alt-full-stop1-yaml}.
+ \end{example}
\subsubsection{Features of the oneSentencePerLine routine}
The sentence manipulation routine takes place \emph{after} verbatim \index{verbatim!in
@@ -5119,23 +5475,30 @@
accounted for; this means that any characters within these types of code blocks will not
be part of the sentence manipulation routine.
+ \begin{example}
For example, if we begin with the \texttt{.tex} file in \cref{lst:multiple-sentences3},
and run the command \index{switches!-l demonstration} \index{switches!-m demonstration}
+
\begin{commandshell}
latexindent.pl multiple-sentences3 -m -l=manipulate-sentences.yaml
\end{commandshell}
+
then we obtain the output in \cref{lst:multiple-sentences3-mod1}.
\cmhlistingsfromfile{demonstrations/multiple-sentences3.tex}{\texttt{multiple-sentences3.tex}}{lst:multiple-sentences3}
\cmhlistingsfromfile{demonstrations/multiple-sentences3-mod1.tex}{\texttt{multiple-sentences3.tex} using \vref{lst:manipulate-sentences-yaml}}{lst:multiple-sentences3-mod1}
+ \end{example}
+ \begin{example}
Furthermore, if sentences run across environments then, by default, the line breaks
internal to the sentence will be removed. For example, if we use the \texttt{.tex} file
in \cref{lst:multiple-sentences4} and run the commands \index{switches!-l demonstration}
\index{switches!-m demonstration}
+
\begin{commandshell}
latexindent.pl multiple-sentences4 -m -l=manipulate-sentences.yaml
latexindent.pl multiple-sentences4 -m -l=keep-sen-line-breaks.yaml
\end{commandshell}
+
then we obtain the output in
\cref{lst:multiple-sentences4-mod1,lst:multiple-sentences4-mod2}.
\cmhlistingsfromfile{demonstrations/multiple-sentences4.tex}{\texttt{multiple-sentences4.tex}}{lst:multiple-sentences4}
@@ -5143,13 +5506,17 @@
\cmhlistingsfromfile{demonstrations/multiple-sentences4-mod1.tex}{\texttt{multiple-sentences4.tex} using \vref{lst:manipulate-sentences-yaml}}{lst:multiple-sentences4-mod1}
\end{widepage}
\cmhlistingsfromfile{demonstrations/multiple-sentences4-mod2.tex}{\texttt{multiple-sentences4.tex} using \vref{lst:keep-sen-line-breaks-yaml}}{lst:multiple-sentences4-mod2}
+ \end{example}
+ \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}
+
\begin{commandshell}
latexindent.pl multiple-sentences4 -m -l=item-rules2.yaml
\end{commandshell}
+
the output of which is shown in \cref{lst:multiple-sentences4-mod3}.
\begin{cmhtcbraster}
@@ -5156,6 +5523,7 @@
\cmhlistingsfromfile{demonstrations/multiple-sentences4-mod3.tex}{\texttt{multiple-sentences4.tex} using \cref{lst:item-rules2-yaml}}{lst:multiple-sentences4-mod3}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/item-rules2.yaml}[MLB-TCB]{\texttt{item-rules2.yaml}}{lst:item-rules2-yaml}
\end{cmhtcbraster}
+ \end{example}
\subsubsection{Text wrapping and indenting sentences}
The \texttt{oneSentencePerLine} \announce{2018-08-13}{oneSentencePerline text wrap and
@@ -5162,6 +5530,7 @@
indent} can be instructed to perform text wrapping and indentation upon sentences.
\index{sentences!text wrapping} \index{sentences!indenting}%
+ \begin{example}
Let's use the code in \cref{lst:multiple-sentences5}.
\cmhlistingsfromfile{demonstrations/multiple-sentences5.tex}{\texttt{multiple-sentences5.tex}}{lst:multiple-sentences5}
@@ -5168,9 +5537,11 @@
Referencing \cref{lst:sentence-wrap1-yaml}, and running the following command
\index{switches!-l demonstration} \index{switches!-m demonstration}
+
\begin{commandshell}
latexindent.pl multiple-sentences5 -m -l=sentence-wrap1.yaml
\end{commandshell}
+
we receive the output given in \cref{lst:multiple-sentences5-mod1}.
\begin{cmhtcbraster}[ raster left skip=-3.5cm,
@@ -5181,11 +5552,13 @@
\cmhlistingsfromfile{demonstrations/multiple-sentences5-mod1.tex}{\texttt{multiple-sentences5.tex} using \cref{lst:sentence-wrap1-yaml}}{lst:multiple-sentences5-mod1}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/sentence-wrap1.yaml}[MLB-TCB,width=0.5\textwidth]{\texttt{sentence-wrap1.yaml}}{lst:sentence-wrap1-yaml}
\end{cmhtcbraster}
+ \end{example}
If you specify \texttt{textWrapSentences} as 1, but do \emph{not} specify a value for
\texttt{columns} then the text wrapping will \emph{not} operate on sentences, and you
will see a warning in \texttt{indent.log}.
+ \begin{example}
The indentation of sentences requires that sentences are stored as code blocks. This
means that you may need to tweak \vref{lst:sentencesEndWith}. Let's explore this in
relation to \cref{lst:multiple-sentences6}.
@@ -5195,10 +5568,12 @@
By default, \texttt{latexindent.pl} will find the full-stop within the first
\texttt{item}, which means that, upon running the following commands \index{switches!-l
demonstration} \index{switches!-m demonstration} \index{switches!-y demonstration}
+
\begin{commandshell}
latexindent.pl multiple-sentences6 -m -l=sentence-wrap1.yaml
latexindent.pl multiple-sentences6 -m -l=sentence-wrap1.yaml -y="modifyLineBreaks:oneSentencePerLine:sentenceIndent:''"
\end{commandshell}
+
we receive the respective output in \cref{lst:multiple-sentences6-mod1} and
\cref{lst:multiple-sentences6-mod2}.
@@ -5210,7 +5585,9 @@
\emph{not} been indented appropriately. This is because the oneSentencePerLine has been
instructed to store sentences (because \cref{lst:sentence-wrap1-yaml}); each sentence is
then searched for code blocks.
+ \end{example}
+ \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,
@@ -5222,9 +5599,11 @@
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/itemized.yaml}[MLB-TCB]{\texttt{itemize.yaml}}{lst:itemize-yaml}
Upon running \index{switches!-l demonstration} \index{switches!-m demonstration}
+
\begin{commandshell}
latexindent.pl multiple-sentences6 -m -l=sentence-wrap1.yaml,itemize.yaml
\end{commandshell}
+
we receive the output in \cref{lst:multiple-sentences6-mod3}.
\cmhlistingsfromfile{demonstrations/multiple-sentences6-mod3.tex}{\texttt{multiple-sentences6-mod3.tex} using \cref{lst:sentence-wrap1-yaml} and \cref{lst:itemize-yaml}}{lst:multiple-sentences6-mod3}
@@ -5231,6 +5610,7 @@
Notice that the sentence has received indentation, and that the \texttt{itemize} code
block has been found and indented correctly.
+ \end{example}
Text \announce{2022-04-04}*{oneSentencePerLine text wrapping update} wrapping when using
the \texttt{oneSentencePerLine} routine determines if it will remove line breaks while
@@ -5294,25 +5674,25 @@
\end{cmhlistings}
\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
block} \index{poly-switches!adding line breaks: set to 1}
- \begin{minipage}{.45\textwidth}
+ \begin{cmhtcbraster}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb1.yaml}[MLB-TCB]{\texttt{env-mlb1.yaml}}{lst:env-mlb1}
- \end{minipage}
- \hfill
- \begin{minipage}{.45\textwidth}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb2.yaml}[MLB-TCB]{\texttt{env-mlb2.yaml}}{lst:env-mlb2}
- \end{minipage}
+ \end{cmhtcbraster}
After running the following commands, \index{switches!-l demonstration}
\index{switches!-m demonstration}
+
\begin{commandshell}
latexindent.pl -m env-mlb.tex -l env-mlb1.yaml
latexindent.pl -m env-mlb.tex -l env-mlb2.yaml
\end{commandshell}
+
the output is as in \cref{lst:env-mlb-mod1,lst:env-mlb-mod2} respectively.
\begin{widepage}
@@ -5334,19 +5714,18 @@
$\BodyStartsOnOwnLine$ in \cref{lst:env-mlb1-tex}; furthermore, note that the \emph{body}
of \texttt{myenv} has received the appropriate (default) indentation.
\end{itemize}
+ \end{example}
+ \begin{example}
Let's now change each of the \texttt{1} values in \cref{lst:env-mlb1,lst:env-mlb2} so
that they are $2$ and save them into \texttt{env-mlb3.yaml} and \texttt{env-mlb4.yaml}
respectively (see \cref{lst:env-mlb3,lst:env-mlb4}). \index{poly-switches!adding comments
and then line breaks: set to 2}
- \begin{minipage}{.45\textwidth}
+ \begin{cmhtcbraster}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb3.yaml}[MLB-TCB]{\texttt{env-mlb3.yaml}}{lst:env-mlb3}
- \end{minipage}
- \hfill
- \begin{minipage}{.45\textwidth}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb4.yaml}[MLB-TCB]{\texttt{env-mlb4.yaml}}{lst:env-mlb4}
- \end{minipage}
+ \end{cmhtcbraster}
Upon running commands analogous to the above, we obtain
\cref{lst:env-mlb-mod3,lst:env-mlb-mod4}.
@@ -5364,19 +5743,18 @@
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}
- Let's \announce{2017-08-21}{demonstration of blank line poly-switch (3)} now change each
- of the \texttt{1} values in \cref{lst:env-mlb1,lst:env-mlb2} so that they are $3$ and
- save them into \texttt{env-mlb5.yaml} and \texttt{env-mlb6.yaml} respectively (see
- \cref{lst:env-mlb5,lst:env-mlb6}). \index{poly-switches!adding blank lines: set to 3}%
+ \begin{example}
+ Let's now change each of the \texttt{1} values in \cref{lst:env-mlb1,lst:env-mlb2} so
+ that they are $3$ and save them into \texttt{env-mlb5.yaml} and \texttt{env-mlb6.yaml}
+ respectively (see \cref{lst:env-mlb5,lst:env-mlb6}). \index{poly-switches!adding blank
+ lines: set to 3}\announce{2017-08-21}{demonstration of blank line poly-switch (3)}%
- \begin{minipage}{.45\textwidth}
+ \begin{cmhtcbraster}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb5.yaml}[MLB-TCB]{\texttt{env-mlb5.yaml}}{lst:env-mlb5}
- \end{minipage}
- \hfill
- \begin{minipage}{.45\textwidth}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb6.yaml}[MLB-TCB]{\texttt{env-mlb6.yaml}}{lst:env-mlb6}
- \end{minipage}
+ \end{cmhtcbraster}
Upon running commands analogous to the above, we obtain
\cref{lst:env-mlb-mod5,lst:env-mlb-mod6}.
@@ -5393,20 +5771,20 @@
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}
- Let's now change \announce{2019-07-13}{demonstration of new blank line poly-switch} each
- of the \texttt{1} values in \cref{lst:env-mlb5,lst:env-mlb6} so that they are $4$ and
- save them into \texttt{env-beg4.yaml} and \texttt{env-body4.yaml} respectively (see
- \cref{lst:env-beg4,lst:env-body4}). \index{poly-switches!adding blank lines (again"!):
- set to 4}%
+ \begin{example}
+ Let's now change each of the \texttt{1} values in \cref{lst:env-mlb5,lst:env-mlb6} so
+ that they are $4$ and save them into \texttt{env-beg4.yaml} and \texttt{env-body4.yaml}
+ respectively (see \cref{lst:env-beg4,lst:env-body4}). \index{poly-switches!adding blank
+ lines (again"!): set to 4} \announce{2019-07-13}{demonstration of new blank line
+ poly-switch}
+ %
- \begin{minipage}{.45\textwidth}
+ \begin{cmhtcbraster}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-beg4.yaml}[MLB-TCB]{\texttt{env-beg4.yaml}}{lst:env-beg4}
- \end{minipage}
- \hfill
- \begin{minipage}{.45\textwidth}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-body4.yaml}[MLB-TCB]{\texttt{env-body4.yaml}}{lst:env-body4}
- \end{minipage}
+ \end{cmhtcbraster}
We will demonstrate this poly-switch value using the code in \cref{lst:env-mlb1-text}.
@@ -5414,6 +5792,7 @@
Upon running the commands \index{switches!-l demonstration} \index{switches!-m
demonstration}
+
\begin{commandshell}
latexindent.pl -m env-mlb1.tex -l env-beg4.yaml
latexindent.pl -m env-mlb.1tex -l env-body4.yaml
@@ -5433,38 +5812,37 @@
\item in \cref{lst:env-mlb1-body4} a blank line has been inserted before the beginning of the
\emph{body}, even though it already began on its own line.
\end{enumerate}
+ \end{example}
- \paragraph{Adding line breaks using EndStartsOnOwnLine and EndFinishesWithLineBreak}
+ \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}
\index{poly-switches!adding line breaks: set to 1}
- \begin{minipage}{.49\textwidth}
+ \begin{cmhtcbraster}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb7.yaml}[MLB-TCB]{\texttt{env-mlb7.yaml}}{lst:env-mlb7}
- \end{minipage}
- \hfill
- \begin{minipage}{.49\textwidth}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb8.yaml}[MLB-TCB]{\texttt{env-mlb8.yaml}}{lst:env-mlb8}
- \end{minipage}
+ \end{cmhtcbraster}
After running the following commands, \index{switches!-l demonstration}
\index{switches!-m demonstration}
+
\begin{commandshell}
latexindent.pl -m env-mlb.tex -l env-mlb7.yaml
latexindent.pl -m env-mlb.tex -l env-mlb8.yaml
\end{commandshell}
+
the output is as in \cref{lst:env-mlb-mod7,lst:env-mlb-mod8}.
- \begin{widepage}
- \begin{minipage}{.42\linewidth}
- \cmhlistingsfromfile{demonstrations/env-mlb-mod7.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb7}}{lst:env-mlb-mod7}
- \end{minipage}
- \hfill
- \begin{minipage}{.57\linewidth}
- \cmhlistingsfromfile{demonstrations/env-mlb-mod8.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb8}}{lst:env-mlb-mod8}
- \end{minipage}
- \end{widepage}
+ \begin{cmhtcbraster}[raster columns=3,
+ raster left skip=-3.5cm,
+ raster right skip=-2cm,
+ raster column skip=.06\linewidth]
+ \cmhlistingsfromfile{demonstrations/env-mlb-mod7.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb7}}{lst:env-mlb-mod7}
+ \cmhlistingsfromfile{demonstrations/env-mlb-mod8.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb8}}{lst:env-mlb-mod8}
+ \end{cmhtcbraster}
There are a couple of points to note:
\begin{itemize}
@@ -5475,19 +5853,18 @@
\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}
+ \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 $2$ and save them into \texttt{env-mlb9.yaml} and \texttt{env-mlb10.yaml}
respectively (see \cref{lst:env-mlb9,lst:env-mlb10}). \index{poly-switches!adding
comments and then line breaks: set to 2}
- \begin{minipage}{.49\textwidth}
+ \begin{cmhtcbraster}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb9.yaml}[MLB-TCB]{\texttt{env-mlb9.yaml}}{lst:env-mlb9}
- \end{minipage}
- \hfill
- \begin{minipage}{.49\textwidth}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb10.yaml}[MLB-TCB]{\texttt{env-mlb10.yaml}}{lst:env-mlb10}
- \end{minipage}
+ \end{cmhtcbraster}
Upon running commands analogous to the above, we obtain
\cref{lst:env-mlb-mod9,lst:env-mlb-mod10}.
@@ -5505,19 +5882,18 @@
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}
- Let's \announce{2017-08-21}{demonstration of blank line poly-switch (3)} now change each
- of the \texttt{1} values in \cref{lst:env-mlb7,lst:env-mlb8} so that they are $3$ and
- save them into \texttt{env-mlb11.yaml} and \texttt{env-mlb12.yaml} respectively (see
- \cref{lst:env-mlb11,lst:env-mlb12}). \index{poly-switches!adding blank lines: set to 3}%
+ \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)}%
- \begin{minipage}{.49\textwidth}
+ \begin{cmhtcbraster}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb11.yaml}[MLB-TCB]{\texttt{env-mlb11.yaml}}{lst:env-mlb11}
- \end{minipage}
- \hfill
- \begin{minipage}{.49\textwidth}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb12.yaml}[MLB-TCB]{\texttt{env-mlb12.yaml}}{lst:env-mlb12}
- \end{minipage}
+ \end{cmhtcbraster}
Upon running commands analogous to the above, we obtain
\cref{lst:env-mlb-mod11,lst:env-mlb-mod12}.
@@ -5534,25 +5910,25 @@
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}
- Let's now change \announce{2019-07-13}{demonstration of new blank line poly-switch} 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}). \index{poly-switches!adding blank lines (again"!):
- set to 4}%
+ \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}).
+ \announce{2019-07-13}{demonstration of new blank line poly-switch}
+ \index{poly-switches!adding blank lines (again"!): set to 4}%
- \begin{minipage}{.45\textwidth}
+ \begin{cmhtcbraster}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-end4.yaml}[MLB-TCB]{\texttt{env-end4.yaml}}{lst:env-end4}
- \end{minipage}
- \hfill
- \begin{minipage}{.5\textwidth}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-end-f4.yaml}[MLB-TCB]{\texttt{env-end-f4.yaml}}{lst:env-end-f4}
- \end{minipage}
+ \end{cmhtcbraster}
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}
+
\begin{commandshell}
latexindent.pl -m env-mlb1.tex -l env-end4.yaml
latexindent.pl -m env-mlb.1tex -l env-end-f4.yaml
@@ -5572,20 +5948,21 @@
\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. 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.
+ poly-switch value of $1$ (or $2$ or $3$), it will only do so if necessary.
- \begin{minipage}{.45\linewidth}
+ \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.
+
+ \begin{cmhtcbraster}
\cmhlistingsfromfile{demonstrations/env-mlb2.tex}{\texttt{env-mlb2.tex}}{lst:mlb2}
- \end{minipage}
- \hfill
- \begin{minipage}{.45\linewidth}
\cmhlistingsfromfile{demonstrations/env-mlb3.tex}{\texttt{env-mlb3.tex}}{lst:mlb3}
- \end{minipage}
+ \end{cmhtcbraster}
+ \end{example}
Setting the poly-switches to a value of $4$ instructs \texttt{latexindent.pl} to add a
line break even if the \emph{<part of thing>} is already on its own line; see
@@ -5592,6 +5969,7 @@
\cref{lst:env-mlb1-beg4,lst:env-mlb1-body4} and
\cref{lst:env-mlb1-end4,lst:env-mlb1-end-f4}.
+ \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
@@ -5605,6 +5983,7 @@
\cmhlistingsfromfile{demonstrations/env-mlb3-mod2.tex}{\texttt{env-mlb3.tex} using \vref{lst:env-mlb2}}{lst:env-mlb3-mod2}
\cmhlistingsfromfile{demonstrations/env-mlb3-mod4.tex}{\texttt{env-mlb3.tex} using \vref{lst:env-mlb4}}{lst:env-mlb3-mod4}
\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
@@ -5614,13 +5993,15 @@
\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. We will consider the example code given in
- \cref{lst:mlb4}, noting in particular the positions of the line break highlighters,
- $\BeginStartsOnOwnLine$, $\BodyStartsOnOwnLine$, $\EndStartsOnOwnLine$ and
- $\EndFinishesWithLineBreak$, together with the associated YAML files in
- \crefrange{lst:env-mlb13}{lst:env-mlb16}. \index{poly-switches!removing line breaks: set
- to -1}
+ \emph{<part of the thing>}, if necessary.
+ \begin{example}
+ We will consider the example code given in \cref{lst:mlb4}, noting in particular the
+ positions of the line break highlighters, $\BeginStartsOnOwnLine$,
+ $\BodyStartsOnOwnLine$, $\EndStartsOnOwnLine$ and $\EndFinishesWithLineBreak$, together
+ with the associated YAML files in \crefrange{lst:env-mlb13}{lst:env-mlb16}.
+ \index{poly-switches!removing line breaks: set to -1}
+
\begin{minipage}{.45\linewidth}
\begin{cmhlistings}[style=tcblatex,escapeinside={(*@}{@*)}]{\texttt{env-mlb4.tex}}{lst:mlb4}
before words(*@$\BeginStartsOnOwnLine$@*)
@@ -5643,6 +6024,7 @@
After running the commands \index{switches!-l demonstration} \index{switches!-m
demonstration}
+
\begin{commandshell}
latexindent.pl -m env-mlb4.tex -l env-mlb13.yaml
latexindent.pl -m env-mlb4.tex -l env-mlb14.yaml
@@ -5652,21 +6034,15 @@
we obtain the respective output in \crefrange{lst:env-mlb4-mod13}{lst:env-mlb4-mod16}.
- \begin{minipage}{.45\linewidth}
+ \begin{cmhtcbraster}
\cmhlistingsfromfile{demonstrations/env-mlb4-mod13.tex}{\texttt{env-mlb4.tex} using \cref{lst:env-mlb13}}{lst:env-mlb4-mod13}
- \end{minipage}
- \hfill
- \begin{minipage}{.45\linewidth}
\cmhlistingsfromfile{demonstrations/env-mlb4-mod14.tex}{\texttt{env-mlb4.tex} using \cref{lst:env-mlb14}}{lst:env-mlb4-mod14}
- \end{minipage}
+ \end{cmhtcbraster}
- \begin{minipage}{.45\linewidth}
+ \begin{cmhtcbraster}
\cmhlistingsfromfile{demonstrations/env-mlb4-mod15.tex}{\texttt{env-mlb4.tex} using \cref{lst:env-mlb15}}{lst:env-mlb4-mod15}
- \end{minipage}
- \hfill
- \begin{minipage}{.45\linewidth}
\cmhlistingsfromfile{demonstrations/env-mlb4-mod16.tex}{\texttt{env-mlb4.tex} using \cref{lst:env-mlb16}}{lst:env-mlb4-mod16}
- \end{minipage}
+ \end{cmhtcbraster}
Notice that in:
\begin{itemize}
@@ -5685,11 +6061,14 @@
following command, for example \index{switches!-l demonstration} \index{switches!-m
demonstration}
\begin{widepage}
+
\begin{commandshell}
latexindent.pl -m env-mlb4.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,env-mlb16.yaml
\end{commandshell}
+
\end{widepage}
which gives the output in \vref{lst:env-mlb1-tex}.
+ \end{example}
\paragraph{About trailing horizontal space}
Recall that on \cpageref{yaml:removeTrailingWhitespace} we discussed the YAML field
@@ -5696,9 +6075,11 @@
\texttt{removeTrailingWhitespace}, and that it has two (binary) switches to determine if
horizontal space should be removed \texttt{beforeProcessing} and
\texttt{afterProcessing}. The \texttt{beforeProcessing} is particularly relevant when
- considering the \texttt{-m} switch; let's consider the file shown in \cref{lst:mlb5},
- which highlights trailing spaces.
+ considering the \texttt{-m} switch.
+ \begin{example}
+ We consider the file shown in \cref{lst:mlb5}, which highlights trailing spaces.
+
\begin{cmhtcbraster}
\begin{cmhlistings}[style=tcblatex,showspaces=true,escapeinside={(*@}{@*)}]{\texttt{env-mlb5.tex}}{lst:mlb5}
before words (*@$\BeginStartsOnOwnLine$@*)
@@ -5713,10 +6094,12 @@
The output from the following commands \index{switches!-l demonstration}
\index{switches!-m demonstration}
\begin{widepage}
+
\begin{commandshell}
latexindent.pl -m env-mlb5.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,env-mlb16.yaml
latexindent.pl -m env-mlb5.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,env-mlb16.yaml,removeTWS-before.yaml
\end{commandshell}
+
\end{widepage}
is shown, respectively, in \cref{lst:env-mlb5-modAll,lst:env-mlb5-modAll-remove-WS}; note
that the trailing horizontal white space has been preserved (by default) in
@@ -5728,8 +6111,10 @@
\cmhlistingsfromfile[showspaces=true]{demonstrations/env-mlb5-modAll-remove-WS.tex}{\texttt{env-mlb5.tex} using \crefrange{lst:env-mlb4-mod13}{lst:env-mlb4-mod16} \emph{and} \cref{lst:removeTWS-before}}{lst:env-mlb5-modAll-remove-WS}
\end{widepage}
+ \end{example}
\paragraph{poly-switch line break removal and blank lines}
+ \begin{example}
Now let's consider the file in \cref{lst:mlb6}, which contains blank lines.
\index{poly-switches!blank lines}
@@ -5754,10 +6139,12 @@
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
\end{commandshell}
+
\end{widepage}
we receive the respective outputs in
\cref{lst:env-mlb6-modAll,lst:env-mlb6-modAll-un-Preserve-Blank-Lines}. In
@@ -5777,7 +6164,9 @@
\cmhlistingsfromfile{demonstrations/env-mlb6-modAll.tex}{\texttt{env-mlb6.tex} using \crefrange{lst:env-mlb4-mod13}{lst:env-mlb4-mod16}}{lst:env-mlb6-modAll}
\cmhlistingsfromfile{demonstrations/env-mlb6-modAll-un-Preserve-Blank-Lines.tex}{\texttt{env-mlb6.tex} using \crefrange{lst:env-mlb4-mod13}{lst:env-mlb4-mod16} \emph{and} \cref{lst:UnpreserveBlankLines}}{lst:env-mlb6-modAll-un-Preserve-Blank-Lines}
\end{cmhtcbraster}
+ \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}.
@@ -5785,10 +6174,12 @@
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
\end{commandshell}
+
we receive the outputs given in \cref{lst:env-mlb7-preserve,lst:env-mlb7-no-preserve}.
\cmhlistingsfromfile{demonstrations/env-mlb7-preserve.tex}{\texttt{env-mlb7-preserve.tex}}{lst:env-mlb7-preserve}
@@ -5804,6 +6195,7 @@
\item \cref{lst:env-mlb7-no-preserve}, by contrast, has had the additional line-break removed,
because of the settings in \cref{lst:UnpreserveBlankLines}.
\end{itemize}
+ \end{example}
\subsubsection{Poly-switches for double back slash}\label{subsec:dbs}
With reference to \texttt{lookForAlignDelims} (see \vref{lst:aligndelims:basic})
@@ -5834,23 +6226,26 @@
Let's explore each of these in turn.
\paragraph{Double back slash 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}
+
\begin{commandshell}
latexindent.pl -m tabular3.tex -l DBS1.yaml
latexindent.pl -m tabular3.tex -l DBS2.yaml
\end{commandshell}
+
then we receive the respective output given in \cref{lst:tabular3-DBS1} and
\cref{lst:tabular3-DBS2}.
- \begin{cmhtcbraster}[raster column skip=.01\linewidth]
+ \begin{cmhtcbraster}
\cmhlistingsfromfile{demonstrations/tabular3-mod1.tex}{\texttt{tabular3.tex} using \cref{lst:DBS1}}{lst:tabular3-DBS1}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/DBS1.yaml}[MLB-TCB]{\texttt{DBS1.yaml}}{lst:DBS1}
\end{cmhtcbraster}
- \begin{cmhtcbraster}[raster column skip=.01\linewidth]
+ \begin{cmhtcbraster}
\cmhlistingsfromfile{demonstrations/tabular3-mod2.tex}{\texttt{tabular3.tex} using \cref{lst:DBS2}}{lst:tabular3-DBS2}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/DBS2.yaml}[MLB-TCB]{\texttt{DBS2.yaml}}{lst:DBS2}
\end{cmhtcbraster}
@@ -5868,26 +6263,30 @@
the double back slashes from \cref{lst:dbs-demo} have been moved to their own line in
\cref{lst:tabular3-DBS2}, having added comment symbols before moving them.
\end{itemize}
+ \end{example}
\paragraph{Double back slash 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
demonstration} \index{switches!-m demonstration}
+
\begin{commandshell}
latexindent.pl -m tabular3.tex -l DBS3.yaml
latexindent.pl -m tabular3.tex -l DBS4.yaml
\end{commandshell}
+
then we receive the respective output given in \cref{lst:tabular3-DBS3} and
\cref{lst:tabular3-DBS4}.
- \begin{cmhtcbraster}[raster column skip=.01\linewidth]
+ \begin{cmhtcbraster}
\cmhlistingsfromfile{demonstrations/tabular3-mod3.tex}{\texttt{tabular3.tex} using \cref{lst:DBS3}}{lst:tabular3-DBS3}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/DBS3.yaml}[MLB-TCB]{\texttt{DBS3.yaml}}{lst:DBS3}
\end{cmhtcbraster}
- \begin{cmhtcbraster}[raster column skip=.01\linewidth]
+ \begin{cmhtcbraster}
\cmhlistingsfromfile{demonstrations/tabular3-mod4.tex}{\texttt{tabular3.tex} using \cref{lst:DBS4}}{lst:tabular3-DBS4}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/DBS4.yaml}[MLB-TCB]{\texttt{DBS4.yaml}}{lst:DBS4}
\end{cmhtcbraster}
@@ -5907,8 +6306,10 @@
them; the final double back slashes have \emph{not} added a line break as they are at the
end of the body within the code block.
\end{itemize}
+ \end{example}
\paragraph{Double back slash 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
@@ -5920,9 +6321,11 @@
Upon using the YAML settings in \cref{lst:DBS5}, and running the command
\index{switches!-l demonstration} \index{switches!-m demonstration}
+
\begin{commandshell}
latexindent.pl -m special4.tex -l DBS5.yaml
\end{commandshell}
+
then we receive the output given in \cref{lst:special4-DBS5}. \index{delimiters!with
specialBeginEnd and the -m switch}
@@ -5943,20 +6346,26 @@
\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
- poly-switches for optional and mandatory arguments. We begin with the code in
- \cref{lst:mycommand2}. \index{poly-switches!for double back slash (delimiters)}
+ 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)}
+
\cmhlistingsfromfile{demonstrations/mycommand2.tex}{\texttt{mycommand2.tex}}{lst:mycommand2}
Upon using the YAML settings in \cref{lst:DBS6,lst:DBS7}, and running the command
\index{switches!-l demonstration} \index{switches!-m demonstration}
+
\begin{commandshell}
latexindent.pl -m mycommand2.tex -l DBS6.yaml
latexindent.pl -m mycommand2.tex -l DBS7.yaml
\end{commandshell}
+
then we receive the output given in \cref{lst:mycommand2-DBS6,lst:mycommand2-DBS7}.
\begin{cmhtcbraster}[
@@ -5974,6 +6383,7 @@
\cmhlistingsfromfile{demonstrations/mycommand2-mod7.tex}{\texttt{mycommand2.tex} using \cref{lst:DBS7}}{lst:mycommand2-DBS7}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/DBS7.yaml}[MLB-TCB,width=0.6\textwidth]{\texttt{DBS7.yaml}}{lst:DBS7}
\end{cmhtcbraster}
+ \end{example}
\paragraph{Double back slash optional square brackets}
The pattern matching for the double back slash will also, optionally, allow trailing
@@ -5980,6 +6390,7 @@
square brackets that contain a measurement of vertical spacing, for example
\lstinline!\\[3pt]!. \index{poly-switches!for double back slash (delimiters)}
+ \begin{example}
For example, beginning with the code in \cref{lst:pmatrix3}
\cmhlistingsfromfile{demonstrations/pmatrix3.tex}{\texttt{pmatrix3.tex}}{lst:pmatrix3}
@@ -5986,12 +6397,15 @@
and running the following command, using \cref{lst:DBS3}, \index{switches!-l
demonstration} \index{switches!-m demonstration}
+
\begin{commandshell}
latexindent.pl -m pmatrix3.tex -l DBS3.yaml
\end{commandshell}
+
then we receive the output given in \cref{lst:pmatrix3-DBS3}.
\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
tuning} field detailed in \vref{lst:fineTuning}.
@@ -6087,6 +6501,7 @@
\texttt{LCuBStartsOnOwnLine} for mandatory arguments, and \texttt{LSqBStartsOnOwnLine}
for optional arguments. \index{poly-switches!conflicting partnering}
+ \begin{example}
Let's begin with the code in \cref{lst:mycommand1} and the YAML settings in
\cref{lst:mycom-mlb1}; with reference to \vref{tab:poly-switch-mapping}, the key
\texttt{CommandNameFinishesWithLineBreak} is an alias for \texttt{BodyStartsOnOwnLine}.
@@ -6095,9 +6510,11 @@
Upon running the command \index{switches!-l demonstration} \index{switches!-m
demonstration}
+
\begin{commandshell}
latexindent.pl -m -l=mycom-mlb1.yaml mycommand1.tex
\end{commandshell}
+
we obtain \cref{lst:mycommand1-mlb1}; note that the \emph{second} mandatory argument
beginning brace \lstinline!{! has had its leading line break removed, but that the
\emph{first} brace has not.
@@ -6109,7 +6526,9 @@
\cmhlistingsfromfile{demonstrations/mycommand1-mlb1.tex}{\texttt{mycommand1.tex} using \cref{lst:mycom-mlb1}}{lst:mycommand1-mlb1}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycom-mlb1.yaml}[MLB-TCB,width=.6\textwidth]{\texttt{mycom-mlb1.yaml}}{lst:mycom-mlb1}
\end{cmhtcbraster}
+ \end{example}
+ \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.
@@ -6121,7 +6540,9 @@
\cmhlistingsfromfile{demonstrations/mycommand1-mlb2.tex}{\texttt{mycommand1.tex} using \cref{lst:mycom-mlb2}}{lst:mycommand1-mlb2}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycom-mlb2.yaml}[MLB-TCB,width=.6\textwidth]{\texttt{mycom-mlb2.yaml}}{lst:mycom-mlb2}
\end{cmhtcbraster}
+ \end{example}
+ \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}.
@@ -6132,15 +6553,20 @@
\cmhlistingsfromfile{demonstrations/mycommand1-mlb3.tex}{\texttt{mycommand1.tex} using \cref{lst:mycom-mlb3}}{lst:mycommand1-mlb3}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycom-mlb3.yaml}[MLB-TCB,width=.6\textwidth]{\texttt{mycom-mlb3.yaml}}{lst:mycom-mlb3}
\end{cmhtcbraster}
+ \end{example}
\subsubsection{Conflicting poly-switches: sequential code blocks}
- It is very easy to have conflicting poly-switches; if we use the example from
- \vref{lst:mycommand1}, and consider the YAML settings given in \cref{lst:mycom-mlb4}. The
- output from running \index{poly-switches!conflicting switches} \index{switches!-l
- demonstration} \index{switches!-m demonstration}
+ It is very easy to have conflicting poly-switches.
+
+ \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}
+
\begin{commandshell}
latexindent.pl -m -l=mycom-mlb4.yaml mycommand1.tex
\end{commandshell}
+
is given in \cref{lst:mycom-mlb4}.
\begin{cmhtcbraster}
@@ -6160,13 +6586,17 @@
clear that \texttt{LCuBStartsOnOwnLine} won this conflict, and the reason is that
\emph{the second argument was processed after the first} -- in general, the most
recently-processed code block and associated poly-switch takes priority.
+ \end{example}
+ \begin{example}
We can explore this further by considering the YAML settings in \cref{lst:mycom-mlb5};
upon running the command \index{switches!-l demonstration} \index{switches!-m
demonstration}
+
\begin{commandshell}
latexindent.pl -m -l=mycom-mlb5.yaml mycommand1.tex
\end{commandshell}
+
we obtain the output given in \cref{lst:mycommand1-mlb5}.
\begin{cmhtcbraster}[raster column skip=.1\linewidth]
@@ -6192,8 +6622,10 @@
\emph{not} begin on its own line, and so because \texttt{LCuBStartsOnOwnLine} is set to
$2$, it adds a comment, followed by a line break.
\end{itemize}
+ \end{example}
\subsubsection{Conflicting poly-switches: nested code blocks}
+ \begin{example}
Now let's consider an example when nested code blocks have conflicting poly-switches;
we'll use the code in \cref{lst:nested-env}, noting that it contains nested environments.
\index{poly-switches!conflicting switches}
@@ -6202,9 +6634,11 @@
Let's use the YAML settings given in \cref{lst:nested-env-mlb1-yaml}, which upon running
the command \index{switches!-l demonstration} \index{switches!-m demonstration}
+
\begin{commandshell}
latexindent.pl -m -l=nested-env-mlb1.yaml nested-env.tex
\end{commandshell}
+
gives the output in \cref{lst:nested-env-mlb1}.
\begin{cmhtcbraster}[raster column skip=.05\linewidth]
@@ -6216,6 +6650,7 @@
received the appropriate (default) indentation; secondly, note that the poly-switch
\texttt{EndStartsOnOwnLine} appears to have won the conflict, as \lstinline!\end{one}!
has had its leading line break removed.
+ \end{example}
To understand it, let's talk about the three basic phases \label{page:phases}of
\texttt{latexindent.pl}:
@@ -6262,11 +6697,14 @@
of knowing how much indentation to add to the subsequent text (in this case,
\lstinline!\end{one}!).
+ \begin{example}
We can explore this further using the poly-switches in \cref{lst:nested-env-mlb2}; upon
running the command \index{switches!-l demonstration} \index{switches!-m demonstration}
+
\begin{commandshell}
latexindent.pl -m -l=nested-env-mlb2.yaml nested-env.tex
\end{commandshell}
+
we obtain the output given in \cref{lst:nested-env-mlb2-output}.
\begin{cmhtcbraster}
@@ -6288,6 +6726,7 @@
stage}, the \texttt{two} environment finds \texttt{EndFinishesWithLineBreak} is $-1$, so
it removes the trailing line break; remember, at this point, \texttt{latexindent.pl} has
completely finished with the \texttt{one} environment.
+ \end{example}
% arara: pdflatex: { files: [latexindent]}
\section{The -r, -rv and -rr switches}\label{sec:replacements}
\fancyhead[R]{\bfseries\thepage%
@@ -6346,11 +6785,14 @@
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}.
+ \begin{example}
Beginning with the code in \cref{lst:replace1} and running the command \index{switches!-r
demonstration}
+
\begin{commandshell}
latexindent.pl -r replace1.tex
\end{commandshell}
+
gives the output given in \cref{lst:replace1-r1}.
\begin{cmhtcbraster}[raster column skip=.01\linewidth]
@@ -6362,9 +6804,11 @@
\vref{lst:replacements} by changing \texttt{lookForThis} to 0; we perform this action in
\cref{lst:replace1-yaml}, and run the command \index{switches!-l demonstration}
\index{switches!-r demonstration}
+
\begin{commandshell}
latexindent.pl -r replace1.tex -l=replace1.yaml
\end{commandshell}
+
which gives the output in \cref{lst:replace1-mod1}.
\begin{cmhtcbraster}[raster column skip=.01\linewidth]
@@ -6374,6 +6818,7 @@
Note that in \cref{lst:replace1-yaml} we have specified \texttt{amalgamate} as 0 so that
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.
@@ -6397,248 +6842,268 @@
\subsection{Examples of replacements}
\begin{example}
- We begin with code given in \cref{lst:colsep}
+ We begin with code given in \cref{lst:colsep}
- \cmhlistingsfromfile{demonstrations/colsep.tex}{\texttt{colsep.tex}}{lst:colsep}
+ \cmhlistingsfromfile{demonstrations/colsep.tex}{\texttt{colsep.tex}}{lst:colsep}
- Let's assume that our goal is to remove both of the \texttt{arraycolsep} statements; we
- can achieve this in a few different ways.
+ Let's assume that our goal is to remove both of the \texttt{arraycolsep} statements; we
+ can achieve this in a few different ways.
- Using the YAML in \cref{lst:colsep-yaml}, and running the command \index{switches!-l
- demonstration} \index{switches!-r demonstration}
- \begin{commandshell}
+ Using the YAML in \cref{lst:colsep-yaml}, and running the command \index{switches!-l
+ demonstration} \index{switches!-r demonstration}
+
+ \begin{commandshell}
latexindent.pl -r colsep.tex -l=colsep.yaml
\end{commandshell}
- then we achieve the output in \cref{lst:colsep-mod0}.
- \begin{cmhtcbraster}[raster column skip=.01\linewidth]
- \cmhlistingsfromfile{demonstrations/colsep-mod0.tex}{\texttt{colsep.tex} using \cref{lst:colsep}}{lst:colsep-mod0}
- \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
- \texttt{latexindent.pl};
- We can make the YAML in \cref{lst:colsep-yaml} more concise by exploring the
- \texttt{substitution} field. Using the settings in \cref{lst:colsep1} and running the
- command \index{switches!-l demonstration} \index{switches!-r demonstration}
- \begin{commandshell}
+ then we achieve the output in \cref{lst:colsep-mod0}.
+
+ \begin{cmhtcbraster}
+ \cmhlistingsfromfile{demonstrations/colsep-mod0.tex}{\texttt{colsep.tex} using \cref{lst:colsep}}{lst:colsep-mod0}
+ \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
+ \texttt{latexindent.pl};
+
+ We can make the YAML in \cref{lst:colsep-yaml} more concise by exploring the
+ \texttt{substitution} field. Using the settings in \cref{lst:colsep1} and running the
+ command \index{switches!-l demonstration} \index{switches!-r demonstration}
+
+ \begin{commandshell}
latexindent.pl -r colsep.tex -l=colsep1.yaml
\end{commandshell}
- then we achieve the output in \cref{lst:colsep-mod1}. \index{regular
- expressions!substitution field, arraycolsep} \index{regular expressions!at least one +}
- \begin{cmhtcbraster}[raster column skip=.01\linewidth,
- raster force size=false,
- raster column 1/.style={add to width=-.1\textwidth}]
- \cmhlistingsfromfile{demonstrations/colsep-mod1.tex}{\texttt{colsep.tex} using \cref{lst:colsep1}}{lst:colsep-mod1}
- \cmhlistingsfromfile[style=yaml-LST]{demonstrations/colsep1.yaml}[replace-TCB,width=0.6\textwidth]{\texttt{colsep1.yaml}}{lst:colsep1}
- \end{cmhtcbraster}
- The code given in \cref{lst:colsep1} is an example of a \emph{regular expression}, which
- we may abbreviate to \emph{regex} in what follows. 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. With reference to
- \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;
- \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.
- \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.
+ then we achieve the output in \cref{lst:colsep-mod1}. \index{regular
+ expressions!substitution field, arraycolsep} \index{regular expressions!at least one +}
+
+ \begin{cmhtcbraster}
+ \cmhlistingsfromfile{demonstrations/colsep-mod1.tex}{\texttt{colsep.tex} using \cref{lst:colsep1}}{lst:colsep-mod1}
+ \cmhlistingsfromfile[style=yaml-LST]{demonstrations/colsep1.yaml}[replace-TCB,width=0.6\textwidth]{\texttt{colsep1.yaml}}{lst:colsep1}
+ \end{cmhtcbraster}
+
+ The code given in \cref{lst:colsep1} is an example of a \emph{regular expression}, which
+ we may abbreviate to \emph{regex} in what follows. 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. With reference to
+ \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;
+ \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.
+ \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.
\end{example}
\begin{example}
- We'll keep working with the file in \vref{lst:colsep} for this example.
+ We'll keep working with the file in \vref{lst:colsep} for this example.
- Using the YAML in \cref{lst:multi-line}, and running the command \index{switches!-l
- demonstration} \index{switches!-r demonstration}
- \begin{commandshell}
+ Using the YAML in \cref{lst:multi-line}, and running the command \index{switches!-l
+ demonstration} \index{switches!-r demonstration}
+
+ \begin{commandshell}
latexindent.pl -r colsep.tex -l=multi-line.yaml
\end{commandshell}
- then we achieve the output in \cref{lst:colsep-mod2}.
- \begin{cmhtcbraster}[raster column skip=.01\linewidth]
- \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
- 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.
- This is a natural point to explore the \texttt{when} field, specified in
- \vref{lst:replacements}. This field can take two values: \emph{before} and \emph{after},
- which respectively instruct \texttt{latexindent.pl} to perform the replacements
- \emph{before} indentation or \emph{after} it. The default value is \texttt{before}.
+ then we achieve the output in \cref{lst:colsep-mod2}.
+ \begin{cmhtcbraster}[raster column skip=.01\linewidth]
+ \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
+ 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.
- Using the YAML in \cref{lst:multi-line1}, and running the command \index{switches!-l
- demonstration} \index{switches!-r demonstration}
- \begin{commandshell}
+ This is a natural point to explore the \texttt{when} field, specified in
+ \vref{lst:replacements}. This field can take two values: \emph{before} and \emph{after},
+ which respectively instruct \texttt{latexindent.pl} to perform the replacements
+ \emph{before} indentation or \emph{after} it. The default value is \texttt{before}.
+
+ Using the YAML in \cref{lst:multi-line1}, and running the command \index{switches!-l
+ demonstration} \index{switches!-r demonstration}
+
+ \begin{commandshell}
latexindent.pl -r colsep.tex -l=multi-line1.yaml
\end{commandshell}
- then we achieve the output in \cref{lst:colsep-mod3}.
- \begin{cmhtcbraster}[raster column skip=.01\linewidth]
- \cmhlistingsfromfile{demonstrations/colsep-mod3.tex}{\texttt{colsep.tex} using \cref{lst:multi-line1}}{lst:colsep-mod3}
- \cmhlistingsfromfile[style=yaml-LST]{demonstrations/multi-line1.yaml}[replace-TCB]{\texttt{multi-line1.yaml}}{lst:multi-line1}
- \end{cmhtcbraster}
- We note that, because we have specified \texttt{when: after}, that
- \texttt{latexindent.pl} has not found the string specified in \cref{lst:multi-line1}
- within the file in \vref{lst:colsep}. As it has looked for the string within
- \cref{lst:multi-line1} \emph{after} the indentation has been performed. After
- indentation, the string as written in \cref{lst:multi-line1} is no longer part of the
- file, and has therefore not been replaced.
- As a final note on this example, if you use the \texttt{-rr} switch, as follows,
- \index{switches!-l demonstration} \index{switches!-rr demonstration}
- \begin{commandshell}
+ then we achieve the output in \cref{lst:colsep-mod3}.
+ \begin{cmhtcbraster}[raster column skip=.01\linewidth]
+ \cmhlistingsfromfile{demonstrations/colsep-mod3.tex}{\texttt{colsep.tex} using \cref{lst:multi-line1}}{lst:colsep-mod3}
+ \cmhlistingsfromfile[style=yaml-LST]{demonstrations/multi-line1.yaml}[replace-TCB]{\texttt{multi-line1.yaml}}{lst:multi-line1}
+ \end{cmhtcbraster}
+ We note that, because we have specified \texttt{when: after}, that
+ \texttt{latexindent.pl} has not found the string specified in \cref{lst:multi-line1}
+ within the file in \vref{lst:colsep}. As it has looked for the string within
+ \cref{lst:multi-line1} \emph{after} the indentation has been performed. After
+ indentation, the string as written in \cref{lst:multi-line1} is no longer part of the
+ file, and has therefore not been replaced.
+
+ As a final note on this example, if you use the \texttt{-rr} switch, as follows,
+ \index{switches!-l demonstration} \index{switches!-rr demonstration}
+
+ \begin{commandshell}
latexindent.pl -rr colsep.tex -l=multi-line1.yaml
\end{commandshell}
- then the \texttt{when} field is ignored, no indentation is done, and the output is as in
- \cref{lst:colsep-mod2}.
+
+ then the \texttt{when} field is ignored, no indentation is done, and the output is as in
+ \cref{lst:colsep-mod2}.
\end{example}
\begin{example}
- An important part of the substitution routine is in \emph{capture groups}.
+ An important part of the substitution routine is in \emph{capture groups}.
- Assuming that we start with the code in \cref{lst:displaymath}, let's assume that our
- goal is to replace each occurrence of \lstinline!$$...$$! with
- \lstinline!\begin{equation*}...\end{equation*}!. This example is partly motivated by
- \href{https://tex.stackexchange.com/questions/242150/good-looking-latex-code}{tex
- stackexchange question 242150}.
+ Assuming that we start with the code in \cref{lst:displaymath}, let's assume that our
+ goal is to replace each occurrence of \lstinline!$$...$$! with
+ \lstinline!\begin{equation*}...\end{equation*}!. This example is partly motivated by
+ \href{https://tex.stackexchange.com/questions/242150/good-looking-latex-code}{tex
+ stackexchange question 242150}.
- \cmhlistingsfromfile{demonstrations/displaymath.tex}{\texttt{displaymath.tex}}{lst:displaymath}
+ \cmhlistingsfromfile{demonstrations/displaymath.tex}{\texttt{displaymath.tex}}{lst:displaymath}
- We use the settings in \cref{lst:displaymath1} and run the command \index{switches!-l
- demonstration} \index{switches!-r demonstration}
- \begin{commandshell}
+ We use the settings in \cref{lst:displaymath1} and run the command \index{switches!-l
+ demonstration} \index{switches!-r demonstration}
+
+ \begin{commandshell}
latexindent.pl -r displaymath.tex -l=displaymath1.yaml
\end{commandshell}
- to receive the output given in \cref{lst:displaymath-mod1}. \index{regular
- expressions!substitution field, equation}
- \begin{cmhtcbraster}[raster left skip=-3.75cm,
- raster right skip=-2cm,]
- \cmhlistingsfromfile{demonstrations/displaymath-mod1.tex}{\texttt{displaymath.tex} using \cref{lst:displaymath1}}{lst:displaymath-mod1}
- \cmhlistingsfromfile[style=yaml-LST]{demonstrations/displaymath1.yaml}[replace-TCB]{\texttt{displaymath1.yaml}}{lst:displaymath1}
- \end{cmhtcbraster}
+ to receive the output given in \cref{lst:displaymath-mod1}. \index{regular
+ expressions!substitution field, equation}
- 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.
- \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.
+ \begin{cmhtcbraster}[raster left skip=-3.75cm,
+ raster right skip=-2cm,]
+ \cmhlistingsfromfile{demonstrations/displaymath-mod1.tex}{\texttt{displaymath.tex} using \cref{lst:displaymath1}}{lst:displaymath-mod1}
+ \cmhlistingsfromfile[style=yaml-LST]{demonstrations/displaymath1.yaml}[replace-TCB]{\texttt{displaymath1.yaml}}{lst:displaymath1}
+ \end{cmhtcbraster}
- The features of the replacement switches can, of course, be combined with others from the
- toolkit of \texttt{latexindent.pl}. For example, we can combine the poly-switches of
- \vref{sec:poly-switches}, which we do in \cref{lst:equation}; upon running the command
- \index{switches!-l demonstration} \index{switches!-m demonstration} \index{switches!-r
- demonstration}
- \begin{commandshell}
+ 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.
+ \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
+ \vref{sec:poly-switches}, which we do in \cref{lst:equation}; upon running the command
+ \index{switches!-l demonstration} \index{switches!-m demonstration} \index{switches!-r
+ demonstration}
+
+ \begin{commandshell}
latexindent.pl -r -m displaymath.tex -l=displaymath1.yaml,equation.yaml
\end{commandshell}
- then we receive the output in \cref{lst:displaymath-mod2}.
- \begin{cmhtcbraster}[
- raster force size=false,
- raster column 1/.style={add to width=-.1\textwidth},
- raster column skip=.06\linewidth]
- \cmhlistingsfromfile{demonstrations/displaymath-mod2.tex}{\texttt{displaymath.tex} using \cref{lst:displaymath1,lst:equation}}{lst:displaymath-mod2}
- \cmhlistingsfromfile[style=yaml-LST]{demonstrations/equation.yaml}[MLB-TCB,width=0.55\textwidth]{\texttt{equation.yaml}}{lst:equation}
- \end{cmhtcbraster}
+ then we receive the output in \cref{lst:displaymath-mod2}.
+
+ \begin{cmhtcbraster}[
+ raster force size=false,
+ raster column 1/.style={add to width=-.1\textwidth},
+ raster column skip=.06\linewidth]
+ \cmhlistingsfromfile{demonstrations/displaymath-mod2.tex}{\texttt{displaymath.tex} using \cref{lst:displaymath1,lst:equation}}{lst:displaymath-mod2}
+ \cmhlistingsfromfile[style=yaml-LST]{demonstrations/equation.yaml}[MLB-TCB,width=0.55\textwidth]{\texttt{equation.yaml}}{lst:equation}
+ \end{cmhtcbraster}
\end{example}
\begin{example}
- This example is motivated by
- \href{https://tex.stackexchange.com/questions/490086/bring-several-lines-together-to-fill-blank-spaces-in-texmaker}{tex
- stackexchange question 490086}. We begin with the code in \cref{lst:phrase}.
+ This example is motivated by
+ \href{https://tex.stackexchange.com/questions/490086/bring-several-lines-together-to-fill-blank-spaces-in-texmaker}{tex
+ stackexchange question 490086}. We begin with the code in \cref{lst:phrase}.
- \cmhlistingsfromfile{demonstrations/phrase.tex}{\texttt{phrase.tex}}{lst:phrase}
+ \cmhlistingsfromfile{demonstrations/phrase.tex}{\texttt{phrase.tex}}{lst:phrase}
- Our goal is to make the spacing uniform between the phrases. To achieve this, we employ
- the settings in \cref{lst:hspace}, and run the command \index{switches!-l demonstration}
- \index{switches!-r demonstration}
- \begin{commandshell}
+ Our goal is to make the spacing uniform between the phrases. To achieve this, we employ
+ the settings in \cref{lst:hspace}, and run the command \index{switches!-l demonstration}
+ \index{switches!-r demonstration}
+
+ \begin{commandshell}
latexindent.pl -r phrase.tex -l=hspace.yaml
\end{commandshell}
- which gives the output in \cref{lst:phrase-mod1}. \index{regular expressions!at least one
- +} \index{regular expressions!horizontal space \textbackslash{h}}
- \begin{cmhtcbraster}
- \cmhlistingsfromfile{demonstrations/phrase-mod1.tex}{\texttt{phrase.tex} using \cref{lst:hspace}}{lst:phrase-mod1}
- \cmhlistingsfromfile[style=yaml-LST]{demonstrations/hspace.yaml}[replace-TCB]{\texttt{hspace.yaml}}{lst:hspace}
- \end{cmhtcbraster}
+ which gives the output in \cref{lst:phrase-mod1}. \index{regular expressions!at least one
+ +} \index{regular expressions!horizontal space \textbackslash{h}}
- The \lstinline!\h+! setting in \cref{lst:hspace} say to replace \emph{at least one
- horizontal space} with a single space.
+ \begin{cmhtcbraster}
+ \cmhlistingsfromfile{demonstrations/phrase-mod1.tex}{\texttt{phrase.tex} using \cref{lst:hspace}}{lst:phrase-mod1}
+ \cmhlistingsfromfile[style=yaml-LST]{demonstrations/hspace.yaml}[replace-TCB]{\texttt{hspace.yaml}}{lst:hspace}
+ \end{cmhtcbraster}
+
+ The \lstinline!\h+! setting in \cref{lst:hspace} say to replace \emph{at least one
+ horizontal space} with a single space.
\end{example}
\begin{example}
- We begin with the code in \cref{lst:references}.
+ We begin with the code in \cref{lst:references}.
- \cmhlistingsfromfile{demonstrations/references.tex}{\texttt{references.tex}}{lst:references}
+ \cmhlistingsfromfile{demonstrations/references.tex}{\texttt{references.tex}}{lst:references}
- Our goal is to change each reference so that both the text and the reference are
- contained within one hyperlink. We achieve this by employing \cref{lst:reference} and
- running the command \index{switches!-l demonstration} \index{switches!-r demonstration}
- \begin{commandshell}
+ Our goal is to change each reference so that both the text and the reference are
+ contained within one hyperlink. We achieve this by employing \cref{lst:reference} and
+ running the command \index{switches!-l demonstration} \index{switches!-r demonstration}
+
+ \begin{commandshell}
latexindent.pl -r references.tex -l=reference.yaml
\end{commandshell}
- which gives the output in \cref{lst:references-mod1}. \index{regular
- expressions!horizontal space \textbackslash{h}}
- \cmhlistingsfromfile{demonstrations/references-mod1.tex}{\texttt{references.tex} using \cref{lst:reference}}{lst:references-mod1}
+ which gives the output in \cref{lst:references-mod1}. \index{regular
+ expressions!horizontal space \textbackslash{h}}
- \cmhlistingsfromfile[style=yaml-LST]{demonstrations/reference.yaml}[replace-TCB]{\texttt{reference.yaml}}{lst:reference}
+ \cmhlistingsfromfile{demonstrations/references-mod1.tex}{\texttt{references.tex} using \cref{lst:reference}}{lst:references-mod1}
- Referencing \cref{lst:reference}, the \lstinline!|! means \emph{or}, we have used
- \emph{capture groups}, together with an example of an \emph{optional} pattern,
- \lstinline!(?:eq)?!.
+ \cmhlistingsfromfile[style=yaml-LST]{demonstrations/reference.yaml}[replace-TCB]{\texttt{reference.yaml}}{lst:reference}
+
+ Referencing \cref{lst:reference}, the \lstinline!|! means \emph{or}, we have used
+ \emph{capture groups}, together with an example of an \emph{optional} pattern,
+ \lstinline!(?:eq)?!.
\end{example}
\begin{example}
- Let's explore the three replacement mode switches (see \vref{tab:replacementswitches}) in
- the context of an example that contains a verbatim code block, \cref{lst:verb1}; we will
- use the settings in \cref{lst:verbatim1-yaml}.
+ Let's explore the three replacement mode switches (see \vref{tab:replacementswitches}) in
+ the context of an example that contains a verbatim code block, \cref{lst:verb1}; we will
+ use the settings in \cref{lst:verbatim1-yaml}.
- \begin{cmhtcbraster}
- \cmhlistingsfromfile{demonstrations/verb1.tex}{\texttt{verb1.tex}}{lst:verb1}
- \cmhlistingsfromfile[style=yaml-LST]{demonstrations/verbatim1.yaml}[replace-TCB]{\texttt{verbatim1.yaml}}{lst:verbatim1-yaml}
- \end{cmhtcbraster}
+ \begin{cmhtcbraster}
+ \cmhlistingsfromfile{demonstrations/verb1.tex}{\texttt{verb1.tex}}{lst:verb1}
+ \cmhlistingsfromfile[style=yaml-LST]{demonstrations/verbatim1.yaml}[replace-TCB]{\texttt{verbatim1.yaml}}{lst:verbatim1-yaml}
+ \end{cmhtcbraster}
- Upon running the following commands, \index{verbatim!comparison with -r and -rr switches}
- \index{switches!-l demonstration} \index{switches!-o demonstration} \index{switches!-r
- demonstration} \index{switches!-rv demonstration} \index{switches!-rr demonstration}
- \begin{commandshell}
+ Upon running the following commands, \index{verbatim!comparison with -r and -rr switches}
+ \index{switches!-l demonstration} \index{switches!-o demonstration} \index{switches!-r
+ demonstration} \index{switches!-rv demonstration} \index{switches!-rr demonstration}
+
+ \begin{commandshell}
latexindent.pl -r verb1.tex -l=verbatim1.yaml -o=+mod1
latexindent.pl -rv verb1.tex -l=verbatim1.yaml -o=+-rv-mod1
latexindent.pl -rr verb1.tex -l=verbatim1.yaml -o=+-rr-mod1
\end{commandshell}
- we receive the respective output in \crefrange{lst:verb1-mod1}{lst:verb1-rr-mod1}
- \begin{cmhtcbraster}[raster columns=3,
- raster left skip=-3.75cm,
- raster right skip=-2cm,]
- \cmhlistingsfromfile{demonstrations/verb1-mod1.tex}{\texttt{verb1-mod1.tex}}{lst:verb1-mod1}
- \cmhlistingsfromfile{demonstrations/verb1-rv-mod1.tex}{\texttt{verb1-rv-mod1.tex}}{lst:verb1-rv-mod1}
- \cmhlistingsfromfile{demonstrations/verb1-rr-mod1.tex}{\texttt{verb1-rr-mod1.tex}}{lst:verb1-rr-mod1}
- \end{cmhtcbraster}
+ we receive the respective output in \crefrange{lst:verb1-mod1}{lst:verb1-rr-mod1}
+
+ \begin{cmhtcbraster}[raster columns=3,
+ raster left skip=-3.75cm,
+ raster right skip=-2cm,]
+ \cmhlistingsfromfile{demonstrations/verb1-mod1.tex}{\texttt{verb1-mod1.tex}}{lst:verb1-mod1}
+ \cmhlistingsfromfile{demonstrations/verb1-rv-mod1.tex}{\texttt{verb1-rv-mod1.tex}}{lst:verb1-rv-mod1}
+ \cmhlistingsfromfile{demonstrations/verb1-rr-mod1.tex}{\texttt{verb1-rr-mod1.tex}}{lst:verb1-rr-mod1}
+ \end{cmhtcbraster}
\end{example}
We note that:
@@ -6655,45 +7120,47 @@
See the summary within \vref{tab:replacementswitches}.
\begin{example}
- Let's explore the \texttt{amalgamate} field from \vref{lst:replacements} in the context
- of the file specified in \cref{lst:amalg1}.
+ Let's explore the \texttt{amalgamate} field from \vref{lst:replacements} in the context
+ of the file specified in \cref{lst:amalg1}.
- \cmhlistingsfromfile{demonstrations/amalg1.tex}{\texttt{amalg1.tex}}{lst:amalg1}
+ \cmhlistingsfromfile{demonstrations/amalg1.tex}{\texttt{amalg1.tex}}{lst:amalg1}
- Let's consider the YAML files given in \crefrange{lst:amalg1-yaml}{lst:amalg3-yaml}.
+ Let's consider the YAML files given in \crefrange{lst:amalg1-yaml}{lst:amalg3-yaml}.
- \begin{cmhtcbraster}[raster columns=3,
- raster left skip=-3.75cm,
- raster right skip=-2cm,]
- \cmhlistingsfromfile[style=yaml-LST]{demonstrations/amalg1-yaml.yaml}[replace-TCB]{\texttt{amalg1-yaml.yaml}}{lst:amalg1-yaml}
- \cmhlistingsfromfile[style=yaml-LST]{demonstrations/amalg2-yaml.yaml}[replace-TCB]{\texttt{amalg2-yaml.yaml}}{lst:amalg2-yaml}
- \cmhlistingsfromfile[style=yaml-LST]{demonstrations/amalg3-yaml.yaml}[replace-TCB]{\texttt{amalg3-yaml.yaml}}{lst:amalg3-yaml}
- \end{cmhtcbraster}
+ \begin{cmhtcbraster}[raster columns=3,
+ raster left skip=-3.75cm,
+ raster right skip=-2cm,]
+ \cmhlistingsfromfile[style=yaml-LST]{demonstrations/amalg1-yaml.yaml}[replace-TCB]{\texttt{amalg1-yaml.yaml}}{lst:amalg1-yaml}
+ \cmhlistingsfromfile[style=yaml-LST]{demonstrations/amalg2-yaml.yaml}[replace-TCB]{\texttt{amalg2-yaml.yaml}}{lst:amalg2-yaml}
+ \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}
- \begin{commandshell}
+ Upon running the following commands, \index{switches!-l demonstration} \index{switches!-r
+ demonstration}
+
+ \begin{commandshell}
latexindent.pl -r amalg1.tex -l=amalg1-yaml
latexindent.pl -r amalg1.tex -l=amalg1-yaml,amalg2-yaml
latexindent.pl -r amalg1.tex -l=amalg1-yaml,amalg2-yaml,amalg3-yaml
\end{commandshell}
- we receive the respective output in \crefrange{lst:amalg1-mod1}{lst:amalg1-mod123}.
- \begin{cmhtcbraster}[raster columns=3,
- raster left skip=-3.75cm,
- raster right skip=-2cm,]
- \cmhlistingsfromfile{demonstrations/amalg1-mod1.tex}{\texttt{amalg1.tex} using \cref{lst:amalg1-yaml}}{lst:amalg1-mod1}
- \cmhlistingsfromfile{demonstrations/amalg1-mod12.tex}{\texttt{amalg1.tex} using \cref{lst:amalg1-yaml,lst:amalg2-yaml}}{lst:amalg1-mod12}
- \cmhlistingsfromfile{demonstrations/amalg1-mod123.tex}{\texttt{amalg1.tex} using \cref{lst:amalg1-yaml,lst:amalg2-yaml,lst:amalg3-yaml}}{lst:amalg1-mod123}
- \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.
- \end{enumerate}
+ we receive the respective output in \crefrange{lst:amalg1-mod1}{lst:amalg1-mod123}.
+
+ \begin{cmhtcbraster}[raster columns=3,
+ raster left skip=-3.75cm,
+ raster right skip=-2cm,]
+ \cmhlistingsfromfile{demonstrations/amalg1-mod1.tex}{\texttt{amalg1.tex} using \cref{lst:amalg1-yaml}}{lst:amalg1-mod1}
+ \cmhlistingsfromfile{demonstrations/amalg1-mod12.tex}{\texttt{amalg1.tex} using \cref{lst:amalg1-yaml,lst:amalg2-yaml}}{lst:amalg1-mod12}
+ \cmhlistingsfromfile{demonstrations/amalg1-mod123.tex}{\texttt{amalg1.tex} using \cref{lst:amalg1-yaml,lst:amalg2-yaml,lst:amalg3-yaml}}{lst:amalg1-mod123}
+ \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.
+ \end{enumerate}
\end{example}
% arara: pdflatex: { files: [latexindent]}
\section{The --lines switch}\label{sec:line-switch}
@@ -6705,10 +7172,12 @@
\index{switches!-lines demonstration}
The basic syntax is \texttt{--lines MIN-MAX}, so for example
+
\begin{commandshell}
latexindent.pl --lines 3-7 myfile.tex
latexindent.pl -n 3-7 myfile.tex
\end{commandshell}
+
will only operate upon lines 3 to 7 in \texttt{myfile.tex}. All of the other lines will
\emph{not} be operated upon by \texttt{latexindent.pl}.
@@ -6727,171 +7196,203 @@
\cmhlistingsfromfile[style=lineNumbersTeX]{demonstrations/myfile.tex}[tex-TCB]{\texttt{myfile.tex}}{lst:myfile}
\begin{example}
- We demonstrate the basic usage using the command
- \begin{commandshell}
+ We demonstrate the basic usage using the command
+
+ \begin{commandshell}
latexindent.pl --lines 3-7 myfile.tex -o=+-mod1
\end{commandshell}
- which instructs \texttt{latexindent.pl} to only operate on lines 3 to 7; the output is
- given in \cref{lst:myfile-mod1}.
- \cmhlistingsfromfile[style=lineNumbersTeX]{demonstrations/myfile-mod1.tex}[tex-TCB]{\texttt{myfile-mod1.tex}}{lst:myfile-mod1}
+ which instructs \texttt{latexindent.pl} to only operate on lines 3 to 7; the output is
+ given in \cref{lst:myfile-mod1}.
- The following two calls to \texttt{latexindent.pl} are equivalent
- \begin{commandshell}
+ \cmhlistingsfromfile[style=lineNumbersTeX]{demonstrations/myfile-mod1.tex}[tex-TCB]{\texttt{myfile-mod1.tex}}{lst:myfile-mod1}
+
+ The following two calls to \texttt{latexindent.pl} are equivalent
+
+ \begin{commandshell}
latexindent.pl --lines 3-7 myfile.tex -o=+-mod1
latexindent.pl --lines 7-3 myfile.tex -o=+-mod1
\end{commandshell}
- as \texttt{latexindent.pl} performs a check to put the lowest number first.
+
+ as \texttt{latexindent.pl} performs a check to put the lowest number first.
\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
- \begin{commandshell}
+ 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
\end{commandshell}
- instructs \texttt{latexindent.pl} to only operate on line 5; the output is given in
- \cref{lst:myfile-mod2}.
- \cmhlistingsfromfile[style=lineNumbersTeX]{demonstrations/myfile-mod2.tex}[tex-TCB]{\texttt{myfile-mod2.tex}}{lst:myfile-mod2}
+ instructs \texttt{latexindent.pl} to only operate on line 5; the output is given in
+ \cref{lst:myfile-mod2}.
- The following two calls are equivalent:
- \begin{commandshell}
+ \cmhlistingsfromfile[style=lineNumbersTeX]{demonstrations/myfile-mod2.tex}[tex-TCB]{\texttt{myfile-mod2.tex}}{lst:myfile-mod2}
+
+ The following two calls are equivalent:
+
+ \begin{commandshell}
latexindent.pl --lines 5 myfile.tex
latexindent.pl --lines 5-5 myfile.tex
\end{commandshell}
+
\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
- \begin{commandshell}
+ For example, in the following call
+
+ \begin{commandshell}
latexindent.pl --lines 11-13 myfile.tex
\end{commandshell}
- \texttt{latexindent.pl} will ignore the \texttt{lines} argument, and \emph{operate on the entire file} because \cref{lst:myfile} only has 12 lines.
- Similarly, in the call
- \begin{commandshell}
+ \texttt{latexindent.pl} will ignore the \texttt{lines} argument, and \emph{operate on the entire file} because \cref{lst:myfile} only has 12 lines.
+
+ Similarly, in the call
+
+ \begin{commandshell}
latexindent.pl --lines -1-3 myfile.tex
\end{commandshell}
- \texttt{latexindent.pl} will ignore the \texttt{lines} argument, and \emph{operate on the entire file} because we assume that negatively numbered
- lines in a file do not exist.
+
+ \texttt{latexindent.pl} will ignore the \texttt{lines} argument, and \emph{operate on the entire file} because we assume that negatively numbered
+ lines in a file do not exist.
\end{example}
\begin{example}
- You can specify \emph{multiple line ranges} as in the following
- \begin{commandshell}
+ You can specify \emph{multiple line ranges} as in the following
+
+ \begin{commandshell}
latexindent.pl --lines 3-5,8-10 myfile.tex -o=+-mod3
\end{commandshell}
- which instructs \texttt{latexindent.pl} to operate upon lines 3 to 5 and lines 8 to 10;
- the output is given in \cref{lst:myfile-mod3}.
- \cmhlistingsfromfile[style=lineNumbersTeX]{demonstrations/myfile-mod3.tex}[tex-TCB]{\texttt{myfile-mod3.tex}}{lst:myfile-mod3}
+ which instructs \texttt{latexindent.pl} to operate upon lines 3 to 5 and lines 8 to 10;
+ the output is given in \cref{lst:myfile-mod3}.
- The following calls to \texttt{latexindent.pl} are all equivalent
- \begin{commandshell}
+ \cmhlistingsfromfile[style=lineNumbersTeX]{demonstrations/myfile-mod3.tex}[tex-TCB]{\texttt{myfile-mod3.tex}}{lst:myfile-mod3}
+
+ The following calls to \texttt{latexindent.pl} are all equivalent
+
+ \begin{commandshell}
latexindent.pl --lines 3-5,8-10 myfile.tex
latexindent.pl --lines 8-10,3-5 myfile.tex
latexindent.pl --lines 10-8,3-5 myfile.tex
latexindent.pl --lines 10-8,5-3 myfile.tex
\end{commandshell}
- as \texttt{latexindent.pl} performs a check to put the lowest line ranges first, and
- within each line range, it puts the lowest number first.
+
+ as \texttt{latexindent.pl} performs a check to put the lowest line ranges first, and
+ within each line range, it puts the lowest number first.
\end{example}
\begin{example}
- There's no limit to the number of line ranges that you can specify, they just need to be
- separated by commas. For example
- \begin{commandshell}
+ There's no limit to the number of line ranges that you can specify, they just need to be
+ separated by commas. For example
+
+ \begin{commandshell}
latexindent.pl --lines 1-2,4-5,9-10,12 myfile.tex -o=+-mod4
\end{commandshell}
- has four line ranges: lines 1 to 2, lines 4 to 5, lines 9 to 10 and line 12. The output
- is given in \cref{lst:myfile-mod4}.
- \cmhlistingsfromfile[style=lineNumbersTeX]{demonstrations/myfile-mod4.tex}[tex-TCB]{\texttt{myfile-mod4.tex}}{lst:myfile-mod4}
+ has four line ranges: lines 1 to 2, lines 4 to 5, lines 9 to 10 and line 12. The output
+ is given in \cref{lst:myfile-mod4}.
- As previously, the ordering does not matter, and the following calls to
- \texttt{latexindent.pl} are all equivalent
- \begin{commandshell}
+ \cmhlistingsfromfile[style=lineNumbersTeX]{demonstrations/myfile-mod4.tex}[tex-TCB]{\texttt{myfile-mod4.tex}}{lst:myfile-mod4}
+
+ As previously, the ordering does not matter, and the following calls to
+ \texttt{latexindent.pl} are all equivalent
+
+ \begin{commandshell}
latexindent.pl --lines 1-2,4-5,9-10,12 myfile.tex
latexindent.pl --lines 2-1,4-5,9-10,12 myfile.tex
latexindent.pl --lines 4-5,1-2,9-10,12 myfile.tex
latexindent.pl --lines 12,4-5,1-2,9-10 myfile.tex
\end{commandshell}
- as \texttt{latexindent.pl} performs a check to put the lowest line ranges first, and
- within each line range, it puts the lowest number first.
+
+ as \texttt{latexindent.pl} performs a check to put the lowest line ranges first, and
+ within each line range, it puts the lowest number first.
\end{example}
\begin{example}
- \index{switches!-lines demonstration, negation}
- You can specify \emph{negated line ranges} by using \texttt{!} as in
- \begin{commandshell}
+ \index{switches!-lines demonstration, negation}
+ You can specify \emph{negated line ranges} by using \texttt{!} as in
+
+ \begin{commandshell}
latexindent.pl --lines !5-7 myfile.tex -o=+-mod5
\end{commandshell}
- 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:
- \begin{commandshell}
+ 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:
+
+ \begin{commandshell}
latexindent.pl --lines !5-7 myfile.tex
latexindent.pl --lines 1-4,8-12 myfile.tex
\end{commandshell}
- The output is given in \cref{lst:myfile-mod5}.
- \cmhlistingsfromfile[style=lineNumbersTeX]{demonstrations/myfile-mod5.tex}[tex-TCB]{\texttt{myfile-mod5.tex}}{lst:myfile-mod5}
+ The output is given in \cref{lst:myfile-mod5}.
+ \cmhlistingsfromfile[style=lineNumbersTeX]{demonstrations/myfile-mod5.tex}[tex-TCB]{\texttt{myfile-mod5.tex}}{lst:myfile-mod5}
+
\end{example}
\begin{example}
- \index{switches!-lines demonstration, negation}
- You can specify \emph{multiple negated line ranges} such as
- \begin{commandshell}
+ \index{switches!-lines demonstration, negation}
+ You can specify \emph{multiple negated line ranges} such as
+
+ \begin{commandshell}
latexindent.pl --lines !5-7,!9-10 myfile.tex -o=+-mod6
\end{commandshell}
- which is equivalent to:
- \begin{commandshell}
+
+ which is equivalent to:
+
+ \begin{commandshell}
latexindent.pl --lines 1-4,8,11-12 myfile.tex -o=+-mod6
\end{commandshell}
- The output is given in \cref{lst:myfile-mod6}.
- \cmhlistingsfromfile[style=lineNumbersTeX]{demonstrations/myfile-mod6.tex}[tex-TCB]{\texttt{myfile-mod6.tex}}{lst:myfile-mod6}
+ The output is given in \cref{lst:myfile-mod6}.
+
+ \cmhlistingsfromfile[style=lineNumbersTeX]{demonstrations/myfile-mod6.tex}[tex-TCB]{\texttt{myfile-mod6.tex}}{lst:myfile-mod6}
\end{example}
\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}.
+ 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}.
- Sample calls that result in the \texttt{lines} argument being ignored include the
- following:
- \begin{commandshell}
+ Sample calls that result in the \texttt{lines} argument being ignored include the
+ following:
+
+ \begin{commandshell}
latexindent.pl --lines 1-x myfile.tex
latexindent.pl --lines !y-3 myfile.tex
\end{commandshell}
+
\end{example}
\begin{example}
- We can, of course, use the \texttt{lines} switch in combination with other switches.
+ We can, of course, use the \texttt{lines} switch in combination with other switches.
- For example, let's use with the file in \cref{lst:myfile1}.
+ For example, let's use with the file in \cref{lst:myfile1}.
- \cmhlistingsfromfile[style=lineNumbersTeX]{demonstrations/myfile1.tex}[tex-TCB]{\texttt{myfile1.tex}}{lst:myfile1}
+ \cmhlistingsfromfile[style=lineNumbersTeX]{demonstrations/myfile1.tex}[tex-TCB]{\texttt{myfile1.tex}}{lst:myfile1}
- We can demonstrate interaction with the \texttt{-m} switch (see
- \vref{sec:modifylinebreaks}); in particular, if we use \vref{lst:mlb2},
- \vref{lst:env-mlb7} and \vref{lst:env-mlb8} and run
- \begin{widepage}
- \begin{commandshell}
+ We can demonstrate interaction with the \texttt{-m} switch (see
+ \vref{sec:modifylinebreaks}); in particular, if we use \vref{lst:mlb2},
+ \vref{lst:env-mlb7} and \vref{lst:env-mlb8} and run
+ \begin{widepage}
+
+ \begin{commandshell}
latexindent.pl --lines 6 myfile1.tex -o=+-mod1 -m -l env-mlb2,env-mlb7,env-mlb8 -o=+-mod1
\end{commandshell}
- \end{widepage}
- then we receive the output in \cref{lst:myfile1-mod1}.
- \cmhlistingsfromfile[style=lineNumbersTeX]{demonstrations/myfile1-mod1.tex}[tex-TCB]{\texttt{myfile1-mod1.tex}}{lst:myfile1-mod1}
+ \end{widepage}
+ then we receive the output in \cref{lst:myfile1-mod1}.
+
+ \cmhlistingsfromfile[style=lineNumbersTeX]{demonstrations/myfile1-mod1.tex}[tex-TCB]{\texttt{myfile1-mod1.tex}}{lst:myfile1-mod1}
\end{example}
% arara: pdflatex: { files: [latexindent]}
\section{Fine tuning}\label{sec:finetuning}
@@ -6991,218 +7492,242 @@
\end{warning}
\begin{example}
- As a demonstration, consider the file given in \cref{lst:finetuning1}, together with its
- default output using the command
- \begin{commandshell}
+ As a demonstration, consider the file given in \cref{lst:finetuning1}, together with its
+ default output using the command
+
+ \begin{commandshell}
latexindent.pl finetuning1.tex
\end{commandshell}
- is given in \cref{lst:finetuning1-default}.
- \begin{cmhtcbraster}[raster column skip=.01\linewidth]
- \cmhlistingsfromfile{demonstrations/finetuning1.tex}{\texttt{finetuning1.tex}}{lst:finetuning1}
- \cmhlistingsfromfile{demonstrations/finetuning1-default.tex}{\texttt{finetuning1.tex} default}{lst:finetuning1-default}
- \end{cmhtcbraster}
+ is given in \cref{lst:finetuning1-default}.
- 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}
+ \begin{cmhtcbraster}[raster column skip=.01\linewidth]
+ \cmhlistingsfromfile{demonstrations/finetuning1.tex}{\texttt{finetuning1.tex}}{lst:finetuning1}
+ \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
+ demonstration}
+
+ \begin{commandshell}
latexindent.pl finetuning1.tex -l=fine-tuning1.yaml
\end{commandshell}
- and the associated (desired) output is given in \cref{lst:finetuning1-mod1}.
- \index{regular expressions!at least one +}
- \begin{cmhtcbraster}[raster column skip=.01\linewidth]
- \cmhlistingsfromfile{demonstrations/finetuning1-mod1.tex}{\texttt{finetuning1.tex} using \cref{lst:fine-tuning1}}{lst:finetuning1-mod1}
- \cmhlistingsfromfile[style=yaml-LST]{demonstrations/fine-tuning1.yaml}[yaml-TCB]{\texttt{finetuning1.yaml}}{lst:fine-tuning1}
- \end{cmhtcbraster}
+ and the associated (desired) output is given in \cref{lst:finetuning1-mod1}.
+ \index{regular expressions!at least one +}
+
+ \begin{cmhtcbraster}[raster column skip=.01\linewidth]
+ \cmhlistingsfromfile{demonstrations/finetuning1-mod1.tex}{\texttt{finetuning1.tex} using \cref{lst:fine-tuning1}}{lst:finetuning1-mod1}
+ \cmhlistingsfromfile[style=yaml-LST]{demonstrations/fine-tuning1.yaml}[yaml-TCB]{\texttt{finetuning1.yaml}}{lst:fine-tuning1}
+ \end{cmhtcbraster}
\end{example}
\begin{example}
- Let's have another demonstration; consider the file given in \cref{lst:finetuning2},
- together with its default output using the command
- \begin{commandshell}
+ Let's have another demonstration; consider the file given in \cref{lst:finetuning2},
+ together with its default output using the command
+
+ \begin{commandshell}
latexindent.pl finetuning2.tex
\end{commandshell}
- is given in \cref{lst:finetuning2-default}.
- \begin{cmhtcbraster}[raster column skip=.01\linewidth,
- raster left skip=-3.75cm,
- raster right skip=0cm,]
- \cmhlistingsfromfile{demonstrations/finetuning2.tex}{\texttt{finetuning2.tex}}{lst:finetuning2}
- \cmhlistingsfromfile{demonstrations/finetuning2-default.tex}{\texttt{finetuning2.tex} default}{lst:finetuning2-default}
- \end{cmhtcbraster}
+ is given in \cref{lst:finetuning2-default}.
- 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}
+ \begin{cmhtcbraster}[raster column skip=.01\linewidth,
+ raster left skip=-3.75cm,
+ raster right skip=0cm,]
+ \cmhlistingsfromfile{demonstrations/finetuning2.tex}{\texttt{finetuning2.tex}}{lst:finetuning2}
+ \cmhlistingsfromfile{demonstrations/finetuning2-default.tex}{\texttt{finetuning2.tex} default}{lst:finetuning2-default}
+ \end{cmhtcbraster}
+
+ It's clear from \cref{lst:finetuning2-default} that the indentation scheme has not worked
+ as expected. We can \emph{fine tune} the indentation scheme by employing the settings
+ given in \cref{lst:fine-tuning2} and running the command \index{switches!-l
+ demonstration}
+
+ \begin{commandshell}
latexindent.pl finetuning2.tex -l=fine-tuning2.yaml
\end{commandshell}
- and the associated (desired) output is given in \cref{lst:finetuning2-mod1}.
- \begin{cmhtcbraster}[raster column skip=.01\linewidth,
- raster left skip=-3.75cm,
- raster right skip=0cm,]
- \cmhlistingsfromfile{demonstrations/finetuning2-mod1.tex}{\texttt{finetuning2.tex} using \cref{lst:fine-tuning2}}{lst:finetuning2-mod1}
- \cmhlistingsfromfile[style=yaml-LST]{demonstrations/fine-tuning2.yaml}[yaml-TCB]{\texttt{finetuning2.yaml}}{lst:fine-tuning2}
- \end{cmhtcbraster}
+ and the associated (desired) output is given in \cref{lst:finetuning2-mod1}.
- In particular, note that the settings in \cref{lst:fine-tuning2} specify that
- \texttt{NamedGroupingBracesBrackets} and \texttt{UnNamedGroupingBracesBrackets} can
- follow \texttt{"} and that we allow \lstinline!---! between arguments.
+ \begin{cmhtcbraster}[raster column skip=.01\linewidth,
+ raster left skip=-3.75cm,
+ raster right skip=0cm,]
+ \cmhlistingsfromfile{demonstrations/finetuning2-mod1.tex}{\texttt{finetuning2.tex} using \cref{lst:fine-tuning2}}{lst:finetuning2-mod1}
+ \cmhlistingsfromfile[style=yaml-LST]{demonstrations/fine-tuning2.yaml}[yaml-TCB]{\texttt{finetuning2.yaml}}{lst:fine-tuning2}
+ \end{cmhtcbraster}
+
+ In particular, note that the settings in \cref{lst:fine-tuning2} specify that
+ \texttt{NamedGroupingBracesBrackets} and \texttt{UnNamedGroupingBracesBrackets} can
+ follow \texttt{"} and that we allow \lstinline!---! between arguments.
\end{example}
\begin{example}
- You can tweak the \texttt{fineTuning} using the \texttt{-y} switch, but to be sure to use
- quotes appropriately. For example, starting with the code in \cref{lst:finetuning3} and
- running the following command
- \begin{commandshell}
+ 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
\end{commandshell}
- gives the output shown in \cref{lst:finetuning3-mod1}.
- \cmhlistingsfromfile{demonstrations/finetuning3.tex}{\texttt{finetuning3.tex}}{lst:finetuning3}
- \cmhlistingsfromfile{demonstrations/finetuning3-mod1.tex}{\texttt{finetuning3.tex} using -y switch}{lst:finetuning3-mod1}
+ gives the output shown in \cref{lst:finetuning3-mod1}.
+
+ \cmhlistingsfromfile{demonstrations/finetuning3.tex}{\texttt{finetuning3.tex}}{lst:finetuning3}
+ \cmhlistingsfromfile{demonstrations/finetuning3-mod1.tex}{\texttt{finetuning3.tex} using -y switch}{lst:finetuning3-mod1}
\end{example}
\begin{example}
- We can tweak the \texttt{fineTuning} for how trailing comments are classified. For
- motivation, let's consider the code given in \cref{lst:finetuning4}
+ We can tweak the \texttt{fineTuning} for how trailing comments are classified. For
+ motivation, let's consider the code given in \cref{lst:finetuning4}
- \cmhlistingsfromfile{demonstrations/finetuning4.tex}{\texttt{finetuning4.tex}}{lst:finetuning4}
+ \cmhlistingsfromfile{demonstrations/finetuning4.tex}{\texttt{finetuning4.tex}}{lst:finetuning4}
- We will compare the settings given in \cref{lst:href1,lst:href2}.
+ We will compare the settings given in \cref{lst:href1,lst:href2}.
- \begin{cmhtcbraster}[raster column skip=.01\linewidth,
- raster left skip=0cm,
- raster right skip=-0.5cm,]
- \cmhlistingsfromfile[style=yaml-LST]{demonstrations/href1.yaml}[MLB-TCB]{\texttt{href1.yaml}}{lst:href1}
- \cmhlistingsfromfile[style=yaml-LST]{demonstrations/href2.yaml}[MLB-TCB]{\texttt{href2.yaml}}{lst:href2}
- \end{cmhtcbraster}
+ \begin{cmhtcbraster}[raster column skip=.01\linewidth,
+ raster left skip=0cm,
+ raster right skip=-0.5cm,]
+ \cmhlistingsfromfile[style=yaml-LST]{demonstrations/href1.yaml}[MLB-TCB]{\texttt{href1.yaml}}{lst:href1}
+ \cmhlistingsfromfile[style=yaml-LST]{demonstrations/href2.yaml}[MLB-TCB]{\texttt{href2.yaml}}{lst:href2}
+ \end{cmhtcbraster}
- Upon running the following commands
- \begin{commandshell}
+ Upon running the following commands
+
+ \begin{commandshell}
latexindent.pl -m finetuning4.tex -o=+-mod1 -l=href1
latexindent.pl -m finetuning4.tex -o=+-mod2 -l=href2
\end{commandshell}
- we receive the respective output in \cref{lst:finetuning4-mod1,lst:finetuning4-mod2}.
- \begin{widepage}
- \cmhlistingsfromfile{demonstrations/finetuning4-mod1.tex}{\texttt{finetuning4.tex} using \cref{lst:href1}}{lst:finetuning4-mod1}
+ we receive the respective output in \cref{lst:finetuning4-mod1,lst:finetuning4-mod2}.
- \cmhlistingsfromfile{demonstrations/finetuning4-mod2.tex}{\texttt{finetuning4.tex} using \cref{lst:href2}}{lst:finetuning4-mod2}
- \end{widepage}
+ \begin{widepage}
+ \cmhlistingsfromfile{demonstrations/finetuning4-mod1.tex}{\texttt{finetuning4.tex} using \cref{lst:href1}}{lst:finetuning4-mod1}
- We note that in:
- \begin{itemize}
- \item \cref{lst:finetuning4-mod1} the trailing comments are assumed to be everything following
- the first comment symbol, which has meant that everything following it has been moved to
- the end of the line; this is undesirable, clearly!
- \item \cref{lst:finetuning4-mod2} has fine-tuned the trailing comment matching, and says that
- \% cannot
- be immediately preceeded by the words `Handbook', `for' or `Spoken', which means that
- none of the \% symbols have been treated as trailing comments, and the output is
- desirable.
- \end{itemize}
+ \cmhlistingsfromfile{demonstrations/finetuning4-mod2.tex}{\texttt{finetuning4.tex} using \cref{lst:href2}}{lst:finetuning4-mod2}
+ \end{widepage}
- Another approach to this situation, which does not use \texttt{fineTuning}, is to use
- \texttt{noIndentBlock} which we discussed in \vref{lst:noIndentBlock}; using the settings
- in \cref{lst:href3} and running the command
- \begin{commandshell}
+ We note that in:
+ \begin{itemize}
+ \item \cref{lst:finetuning4-mod1} the trailing comments are assumed to be everything following
+ the first comment symbol, which has meant that everything following it has been moved to
+ the end of the line; this is undesirable, clearly!
+ \item \cref{lst:finetuning4-mod2} has fine-tuned the trailing comment matching, and says that
+ \% cannot
+ be immediately preceeded by the words `Handbook', `for' or `Spoken', which means that
+ none of the \% symbols have been treated as trailing comments, and the output is
+ desirable.
+ \end{itemize}
+ \end{example}
+
+ \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
+
+ \begin{commandshell}
latexindent.pl -m finetuning4.tex -o=+-mod3 -l=href3
\end{commandshell}
- then we receive the same output given in \cref{lst:finetuning4-mod2}.
- \cmhlistingsfromfile[style=yaml-LST]{demonstrations/href3.yaml}[MLB-TCB]{\texttt{href3.yaml}}{lst:href3}
+ then we receive the same output given in \cref{lst:finetuning4-mod2}.
- With reference to the \texttt{body} field in \cref{lst:href3}, we note that the
- \texttt{body} field can be interpreted as: the fewest number of zero or more characters
- that are not right braces. This is an example of character class. \index{regular
- expressions!character class demonstration}
+ \cmhlistingsfromfile[style=yaml-LST]{demonstrations/href3.yaml}[MLB-TCB]{\texttt{href3.yaml}}{lst:href3}
+
+ With reference to the \texttt{body} field in \cref{lst:href3}, we note that the
+ \texttt{body} field can be interpreted as: the fewest number of zero or more characters
+ that are not right braces. This is an example of character class. \index{regular
+ expressions!character class demonstration}
\end{example}
\begin{example}
- We can use the \texttt{fineTuning} field to assist in the formatting of bibliography
- files. \index{bibliography files} \index{regular expressions!delimiterRegEx}
- \index{regular expressions!capturing parenthesis} \index{regular expressions!ampersand
- alignment} \index{delimiters!delimiterRegEx}
+ We can use the \texttt{fineTuning} field to assist in the formatting of bibliography
+ files. \index{bibliography files} \index{regular expressions!delimiterRegEx}
+ \index{regular expressions!capturing parenthesis} \index{regular expressions!ampersand
+ alignment} \index{delimiters!delimiterRegEx}
- Starting with the file in \cref{lst:bib1} and running the command
- \begin{commandshell}
+ Starting with the file in \cref{lst:bib1} and running the command
+
+ \begin{commandshell}
latexindent.pl bib1.tex -o=+-mod1
\end{commandshell}
- gives the output in \cref{lst:bib1-mod1}.
- \begin{widepage}
- \begin{cmhtcbraster}[raster column skip=.01\linewidth]
- \cmhlistingsfromfile{demonstrations/bib1.bib}{\texttt{bib1.bib}}{lst:bib1}
- \cmhlistingsfromfile{demonstrations/bib1-mod1.bib}{\texttt{bib1-mod1.bib}}{lst:bib1-mod1}
- \end{cmhtcbraster}
- \end{widepage}
+ gives the output in \cref{lst:bib1-mod1}.
- Let's assume that we would like to format the output so as to align the \texttt{=}
- symbols. Using the settings in \cref{lst:bibsettings1} and running the command
- \begin{commandshell}
+ \begin{widepage}
+ \begin{cmhtcbraster}[raster column skip=.01\linewidth]
+ \cmhlistingsfromfile{demonstrations/bib1.bib}{\texttt{bib1.bib}}{lst:bib1}
+ \cmhlistingsfromfile{demonstrations/bib1-mod1.bib}{\texttt{bib1-mod1.bib}}{lst:bib1-mod1}
+ \end{cmhtcbraster}
+ \end{widepage}
+
+ Let's assume that we would like to format the output so as to align the \texttt{=}
+ symbols. Using the settings in \cref{lst:bibsettings1} and running the command
+
+ \begin{commandshell}
latexindent.pl bib1.bib -l bibsettings1.yaml -o=+-mod2
\end{commandshell}
- gives the output in \cref{lst:bib1-mod2}.
- \begin{widepage}
- \begin{cmhtcbraster}[raster column skip=.1\linewidth]
- \cmhlistingsfromfile{demonstrations/bib1-mod2.bib}{\texttt{bib1.bib} using \cref{lst:bibsettings1}}{lst:bib1-mod2}
- \cmhlistingsfromfile[style=yaml-LST]{demonstrations/bibsettings1.yaml}[yaml-TCB]{\texttt{bibsettings1.yaml}}{lst:bibsettings1}
- \end{cmhtcbraster}
- \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.
- \end{itemize}
+ gives the output in \cref{lst:bib1-mod2}.
+
+ \begin{widepage}
+ \begin{cmhtcbraster}[raster column skip=.1\linewidth]
+ \cmhlistingsfromfile{demonstrations/bib1-mod2.bib}{\texttt{bib1.bib} using \cref{lst:bibsettings1}}{lst:bib1-mod2}
+ \cmhlistingsfromfile[style=yaml-LST]{demonstrations/bibsettings1.yaml}[yaml-TCB]{\texttt{bibsettings1.yaml}}{lst:bibsettings1}
+ \end{cmhtcbraster}
+ \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.
+ \end{itemize}
\end{example}
\begin{example}
- We can build upon \cref{lst:bibsettings1} for slightly more complicated bibliography
- files.
+ We can build upon \cref{lst:bibsettings1} for slightly more complicated bibliography
+ files.
- Starting with the file in \cref{lst:bib2} and running the command
- \begin{commandshell}
+ Starting with the file in \cref{lst:bib2} and running the command
+
+ \begin{commandshell}
latexindent.pl bib2.bib -l bibsettings1.yaml -o=+-mod1
\end{commandshell}
- gives the output in \cref{lst:bib2-mod1}.
- \begin{widepage}
- \cmhlistingsfromfile{demonstrations/bib2.bib}{\texttt{bib2.bib}}{lst:bib2}
- \cmhlistingsfromfile{demonstrations/bib2-mod1.bib}{\texttt{bib2-mod1.bib}}{lst:bib2-mod1}
- \end{widepage}
+ gives the output in \cref{lst:bib2-mod1}.
- The output in \cref{lst:bib2-mod1} is not ideal, as the \texttt{=} symbol within the url
- field has been incorrectly used as an alignment delimiter.
+ \begin{widepage}
+ \cmhlistingsfromfile{demonstrations/bib2.bib}{\texttt{bib2.bib}}{lst:bib2}
+ \cmhlistingsfromfile{demonstrations/bib2-mod1.bib}{\texttt{bib2-mod1.bib}}{lst:bib2-mod1}
+ \end{widepage}
- We address this by tweaking the \texttt{delimiterRegEx} field in \cref{lst:bibsettings2}.
+ 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.
- \cmhlistingsfromfile[style=yaml-LST]{demonstrations/bibsettings2.yaml}[yaml-TCB]{\texttt{bibsettings2.yaml}}{lst:bibsettings2}
+ We address this by tweaking the \texttt{delimiterRegEx} field in \cref{lst:bibsettings2}.
- Upon running the command
- \begin{commandshell}
+ \cmhlistingsfromfile[style=yaml-LST]{demonstrations/bibsettings2.yaml}[yaml-TCB]{\texttt{bibsettings2.yaml}}{lst:bibsettings2}
+
+ Upon running the command
+
+ \begin{commandshell}
latexindent.pl bib2.bib -l bibsettings1.yaml,bibsettings2.yaml -o=+-mod2
\end{commandshell}
- we receive the \emph{desired} output in \cref{lst:bib2-mod2}.
- \cmhlistingsfromfile{demonstrations/bib2-mod2.bib}{\texttt{bib2-mod2.bib}}{lst:bib2-mod2}
+ we receive the \emph{desired} output in \cref{lst:bib2-mod2}.
- With reference to \cref{lst:bibsettings2} we note that the \texttt{delimiterRegEx} has
- been adjusted so that \texttt{=} symbols are used as the delimiter, but only when they
- are \emph{not preceeded} by either \texttt{v} or \texttt{spfreload}.
+ \cmhlistingsfromfile{demonstrations/bib2-mod2.bib}{\texttt{bib2-mod2.bib}}{lst:bib2-mod2}
+
+ With reference to \cref{lst:bibsettings2} we note that the \texttt{delimiterRegEx} has
+ been adjusted so that \texttt{=} symbols are used as the delimiter, but only when they
+ are \emph{not preceeded} by either \texttt{v} or \texttt{spfreload}.
\end{example}
% arara: pdflatex: { files: [latexindent]}
\section{Conclusions and known limitations}\label{sec:knownlimitations}
@@ -7257,9 +7782,11 @@
Perl modules.
If you can run the minimum code in \cref{lst:helloworld} as in
+
\begin{commandshell}
perl helloworld.pl
\end{commandshell}
+
then you will be able to run \texttt{latexindent.pl}, otherwise you may need to install
the missing modules; see \cref{sec:module-installer,sec:manual-module-instal}.
@@ -7290,9 +7817,11 @@
\announce{2018-01-13}{perl module helper script} \texttt{latexindent.pl} ships with a
helper script that will install any missing \texttt{perl} modules on your system; if you
run
+
\begin{commandshell}
perl latexindent-module-installer.pl
\end{commandshell}
+
or
\begin{dosprompt}
perl latexindent-module-installer.pl
@@ -7308,20 +7837,23 @@
\paragraph{perlbrew}
Linux users may be interested in exploring Perlbrew \cite{perlbrew}; an example
installation would be:
+
\begin{commandshell}
sudo apt-get install perlbrew
perlbrew init
-perlbrew install perl-5.28.1
-perlbrew switch perl-5.28.1
+perlbrew install perl-5.34.0
+perlbrew switch perl-5.34.0
sudo apt-get install curl
curl -L http://cpanmin.us | perl - App::cpanminus
cpanm YAML::Tiny
cpanm File::HomeDir
\end{commandshell}
+
\index{cpan}
\paragraph{Ubuntu/Debian}
For other distributions, the Ubuntu/Debian approach may work as follows
+
\begin{commandshell}
sudo apt install perl
sudo cpan -i App::cpanminus
@@ -7328,7 +7860,9 @@
sudo cpanm YAML::Tiny
sudo cpanm File::HomeDir
\end{commandshell}
+
or else by running, for example,
+
\begin{commandshell}
sudo perl -MCPAN -e'install "File::HomeDir"'
\end{commandshell}
@@ -7335,11 +7869,14 @@
\paragraph{Ubuntu: using the texlive from apt-get}
Ubuntu users that install texlive using \texttt{apt-get} as in the following
+
\begin{commandshell}
sudo apt install texlive
sudo apt install texlive-latex-recommended
\end{commandshell}
+
may need the following additional command to work with \texttt{latexindent.pl}
+
\begin{commandshell}
sudo apt install texlive-extra-utils
\end{commandshell}
@@ -7352,14 +7889,18 @@
\paragraph{Arch-based distributions}
First install the dependencies
+
\begin{commandshell}
sudo pacman -S perl cpanminus
\end{commandshell}
+
In addition, install \texttt{perl-file-homedir} from AUR, using your AUR helper of
choice,
+
\begin{commandshell}
sudo paru -S perl-file-homedir
\end{commandshell}
+
then run the latexindent-module-installer.pl file located at helper-scripts/
\paragraph{Alpine}
@@ -7397,6 +7938,7 @@
\subsubsection{Mac}
Users of the Macintosh operating system might like to explore the following commands, for
example:
+
\begin{commandshell}
brew install perl
brew install cpanm
@@ -7404,7 +7946,9 @@
cpanm YAML::Tiny
cpanm File::HomeDir
\end{commandshell}
+
Alternatively,
+
\begin{commandshell}
brew install latexindent
\end{commandshell}
@@ -7434,11 +7978,14 @@
This can be loaded by calling \texttt{latexindent.pl} with the \texttt{GCString} switch
as in
+
\begin{commandshell}
latexindent.pl --GCString myfile.tex
\end{commandshell}
+
In this case, you will need to have the \texttt{Unicode::GCString} installed in your
\texttt{perl} distribution by using, for example,
+
\begin{commandshell}
cpanm Unicode::GCString
\end{commandshell}
@@ -7462,11 +8009,14 @@
\texttt{CMakeLists.txt} and \lstinline!cmake_uninstall.cmake.in! from
\cite{latexindent-home}/path-helper-files to this directory;
\item run
+
\begin{commandshell}
ls /usr/local/bin
\end{commandshell}
+
to see what is \emph{currently} in there;
\item run the following commands
+
\begin{commandshell}
sudo apt-get update
sudo apt-get install --no-install-recommends cmake make # or any other generator
@@ -7474,17 +8024,22 @@
cmake ../path-helper-files
sudo make install
\end{commandshell}
+
\item run
+
\begin{commandshell}
ls /usr/local/bin
\end{commandshell}
+
again to check that \texttt{latexindent.pl}, its modules and
\texttt{defaultSettings.yaml} have been added.
\end{enumerate}
To \emph{remove} the files, run
+
\begin{commandshell}
sudo make uninstall
\end{commandshell}
+
\subsection{Add to path for Windows}
To add \texttt{latexindent.exe} to the path for Windows, follow these steps:
\begin{enumerate}
@@ -7510,6 +8065,7 @@
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 myfile2.tex
@@ -7527,17 +8083,21 @@
\subsection{interaction with -w switch}
If the \texttt{-w} switch is active, as in
+
\begin{commandshell}
latexindent.pl -w myfile*.tex
\end{commandshell}
+
then files will be overwritten individually. Back-up files can be re-directed via the
\texttt{-c} switch.
\subsection{interaction with -o switch}
If \texttt{latexindent.pl} is called using the \texttt{-o} switch as in
+
\begin{commandshell}
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.
@@ -7545,16 +8105,20 @@
beginning, then the \texttt{-o} switch will be ignored, and is turned it off.
For example
+
\begin{commandshell}
latexindent.pl myfile*.tex -o=+myfile
\end{commandshell}
+
\emph{will} work fine because \emph{each} \texttt{.tex} file will output to
\texttt{<basename>myfile.tex}
Similarly,
+
\begin{commandshell}
latexindent.pl myfile*.tex -o=++
\end{commandshell}
+
\emph{will} work because the `existence check/incrementation' routine will be applied.
\subsection{interaction with lines switch}
@@ -7565,9 +8129,11 @@
The exit codes for \texttt{latexindent.pl} are given in \vref{tab:exit-codes}.
When operating on multiple files with the check switch active, as in
+
\begin{commandshell}
latexindent.pl myfile*.tex --check
\end{commandshell}
+
then
\begin{itemize}
\item exit code 0 means that the text from \emph{none} of the files has been changed;
@@ -7639,9 +8205,11 @@
\section{Using conda}\label{sec:app:conda}
If you use conda you'll only need
+
\begin{commandshell}
conda install latexindent.pl -c conda-forge
\end{commandshell}
+
This will install the executable and all its dependencies (including perl) in the
activate environment. You don't even have to worry about \texttt{defaultSettings.yaml} as
it included too, you can thus skip \cref{sec:requiredmodules,sec:updating-path}.
@@ -7652,6 +8220,7 @@
\subsection{Sample conda installation on Ubuntu}
On Ubuntu I followed the 64-bit installation instructions at \cite{condainstallubuntu}
and then I ran the following commands:
+
\begin{commandshell}
conda create -n latexindent.pl
conda activate latexindent.pl
@@ -7660,13 +8229,16 @@
conda list
conda run latexindent.pl -vv
\end{commandshell}
+
I found the details given at \cite{condainstallhelp} to be helpful.
\section{Using docker}\label{sec:app:docker}
If you use docker you'll only need \announce{2022-06-12}{docker support}
+
\begin{commandshell}
docker pull ghcr.io/cmhughes/latexindent.pl
\end{commandshell}
+
This will download the image packed \texttt{latexindent}'s executable and its all
dependencies. \index{docker} Thank you to \cite{eggplants} for contributing this feature;
see also \cite{cmhughesio}. For reference, \emph{ghcr} stands for \emph{GitHub Container
@@ -7691,6 +8263,7 @@
\subsection{How to format on Docker}
When you use \texttt{latexindent} with the docker image, you have to mount target \texttt{tex} file like this:
+
\begin{commandshell}
docker run -v /path/to/local/myfile.tex:/myfile.tex ghcr.io/cmhughes/latexindent.pl -s -w myfile.tex
\end{commandshell}
@@ -7709,9 +8282,11 @@
\subsection{Sample pre-commit installation on Ubuntu}\label{sec:pre-commit-ubuntu}
On Ubuntu I ran the following command:
+
\begin{commandshell}
python3 -m pip install pre-commit
\end{commandshell}
+
I then updated my path via .bashrc so that it includes the line in
\cref{lst:bashrc-update}.
\begin{cmhlistings}[style=tcblatex,language=Bash]{\texttt{.bashrc} update}{lst:bashrc-update}
@@ -7746,9 +8321,11 @@
\cmhlistingsfromfile{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
\end{commandshell}
+
A few notes about \cref{lst:.pre-commit-config.yaml-cpan}:
\begin{itemize}
\item the settings given in \cref{lst:.pre-commit-config.yaml-cpan} instruct
@@ -7756,9 +8333,11 @@
\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
\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]}.
@@ -7775,9 +8354,11 @@
\cmhlistingsfromfile{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
\end{commandshell}
+
A few notes about \cref{lst:.pre-commit-config.yaml-cpan}:
\begin{itemize}
\item the settings given in \cref{lst:.pre-commit-config.yaml-conda} instruct
@@ -7785,9 +8366,11 @@
\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
\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]}.
@@ -7801,9 +8384,11 @@
\cmhlistingsfromfile{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}
pre-commit run --all-files
\end{commandshell}
+
A few notes about \cref{lst:.pre-commit-config.yaml-cpan}:
\begin{itemize}
\item the settings given in \cref{lst:.pre-commit-config.yaml-docker} instruct
@@ -7811,9 +8396,11 @@
\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
+
\begin{commandshell}
docker run -v /path/to/myfile.tex:/myfile.tex ghcr.io/cmhughes/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]}.
@@ -7824,8 +8411,8 @@
\texttt{.latexindent.yaml}.
\begin{example}
- We use the local settings given in \cref{lst:.latexindent.yaml}.
- \begin{cmhlistings}[style=tcblatex]{\texttt{.latexindent.yaml}}{lst:.latexindent.yaml}
+ We use the local settings given in \cref{lst:.latexindent.yaml}.
+ \begin{cmhlistings}[style=tcblatex]{\texttt{.latexindent.yaml}}{lst:.latexindent.yaml}
onlyOneBackUp: 1
modifyLineBreaks:
@@ -7833,35 +8420,41 @@
manipulateSentences: 1
\end{cmhlistings}
- and \texttt{.pre-commit-config.yaml} as in \cref{lst:.latexindent.yaml-switches}:
+ 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}
- Now running
- \begin{commandshell}
+ \cmhlistingsfromfile{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
\end{commandshell}
- is equivalent to running
- \begin{commandshell}
+
+ is equivalent to running
+
+ \begin{commandshell}
latexindent.pl -l -m -s -w myfile.tex
\end{commandshell}
- for each \texttt{.tex} file in your repository.
- 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 \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}
+ for each \texttt{.tex} file in your repository.
+
+ 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 \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{logFilePreferences}\label{app:logfile-demo}
\Vref{lst:logFilePreferences} describes the options for customising the information given
- to the log file, and we provide a few demonstrations here. Let's say that we start with
- the code given in \cref{lst:simple}, and the settings specified in
- \cref{lst:logfile-prefs1-yaml}.
+ to the log file, and we provide a few demonstrations here.
+ \begin{example}
+ Let's say that we start with the code given in \cref{lst:simple}, and the settings
+ specified in \cref{lst:logfile-prefs1-yaml}.
+
\begin{minipage}{.35\linewidth}
\cmhlistingsfromfile{demonstrations/simple.tex}{\texttt{simple.tex}}{lst:simple}
\end{minipage}
@@ -7871,9 +8464,11 @@
\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
\end{commandshell}
+
then on inspection of \texttt{indent.log} we will find the snippet given in
\cref{lst:indentlog}.
\begin{cmhlistings}[style=tcblatex,morekeywords={TRACE}]{\texttt{indent.log}}{lst:indentlog}
@@ -7894,6 +8489,7 @@
\end{cmhlistings}
Notice that the information given about \texttt{myenv} is `framed' using \texttt{+++++}
and \lstinline!-----! respectively.
+ \end{example}
\section{Encoding indentconfig.yaml}\label{app:encoding}
In relation to \vref{sec:indentconfig}, Windows users that encounter encoding issues with
@@ -7931,11 +8527,14 @@
There are a few (small) changes to the interface when comparing Version 2.2 to Version
3.0. Explicitly, in previous versions you might have run, for example, \index{switches!-o
demonstration}
+
\begin{commandshell}
latexindent.pl -o myfile.tex outputfile.tex
\end{commandshell}
+
whereas in Version 3.0 you would run any of the following, for example,
\index{switches!-o demonstration}
+
\begin{commandshell}
latexindent.pl -o=outputfile.tex myfile.tex
latexindent.pl -o outputfile.tex myfile.tex
@@ -7944,6 +8543,7 @@
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.
Modified: trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/ModifyLineBreaks.pm
===================================================================
--- trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/ModifyLineBreaks.pm 2022-12-05 21:25:15 UTC (rev 65207)
+++ trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/ModifyLineBreaks.pm 2022-12-05 21:30:10 UTC (rev 65208)
@@ -317,36 +317,43 @@
my $BeginStringLogFile = ${$child}{aliases}{BeginStartsOnOwnLine};
$logger->trace("*$BeginStringLogFile is ${$child}{BeginStartsOnOwnLine} for ${$child}{name}")
if $is_t_switch_active;
- if ( ${$child}{BeginStartsOnOwnLine} == -1 ) {
- # VerbatimStartsOnOwnLine = -1
- if ( ${$self}{body} =~ m/^\h*${$child}{id}/m ) {
- $logger->trace("${$child}{name} begins on its own line, removing leading line break")
- if $is_t_switch_active;
- ${$self}{body} =~ s/(\R|\h)*${$child}{id}/${$child}{id}/s;
+ my @polySwitchValues
+ = ( ${$child}{BeginStartsOnOwnLine} == 4 ) ? ( -1, 3 ) : ( ${$child}{BeginStartsOnOwnLine} );
+
+ foreach (@polySwitchValues) {
+ if ( $_ == -1 ) {
+
+ # VerbatimStartsOnOwnLine = -1
+ if ( ${$self}{body} =~ m/^\h*${$child}{id}/m ) {
+ $logger->trace("${$child}{name} begins on its own line, removing leading line break")
+ if $is_t_switch_active;
+ ${$self}{body} =~ s/(\R|\h)*${$child}{id}/${$child}{id}/s;
+ }
}
- }
- elsif ( ${$child}{BeginStartsOnOwnLine} >= 1 and ${$self}{body} !~ m/^\h*${$child}{id}/m ) {
+ elsif ( $_ >= 1 and ${$self}{body} !~ m/^\h*${$child}{id}/m ) {
- # VerbatimStartsOnOwnLine = 1, 2 or 3
- my $trailingCharacterToken = q();
- if ( ${$child}{BeginStartsOnOwnLine} == 1 ) {
- $logger->trace("Adding a linebreak at the beginning of ${$child}{begin} (see $BeginStringLogFile)")
- if $is_t_switch_active;
+ # VerbatimStartsOnOwnLine = 1, 2 or 3
+ my $trailingCharacterToken = q();
+ if ( $_ == 1 ) {
+ $logger->trace(
+ "Adding a linebreak at the beginning of ${$child}{begin} (see $BeginStringLogFile)")
+ if $is_t_switch_active;
+ }
+ elsif ( $_ == 2 ) {
+ $logger->trace(
+ "Adding a % at the end of the line that ${$child}{begin} is on, then a linebreak ($BeginStringLogFile == 2)"
+ ) if $is_t_switch_active;
+ $trailingCharacterToken = "%" . $self->add_comment_symbol;
+ }
+ elsif ( $_ == 3 ) {
+ $logger->trace(
+ "Adding a blank line at the end of the line that ${$child}{begin} is on, then a linebreak ($BeginStringLogFile == 3)"
+ ) if $is_t_switch_active;
+ $trailingCharacterToken = "\n";
+ }
+ ${$self}{body} =~ s/\h*${$child}{id}/$trailingCharacterToken\n${$child}{id}/s;
}
- elsif ( ${$child}{BeginStartsOnOwnLine} == 2 ) {
- $logger->trace(
- "Adding a % at the end of the line that ${$child}{begin} is on, then a linebreak ($BeginStringLogFile == 2)"
- ) if $is_t_switch_active;
- $trailingCharacterToken = "%" . $self->add_comment_symbol;
- }
- elsif ( ${$child}{BeginStartsOnOwnLine} == 3 ) {
- $logger->trace(
- "Adding a blank line at the end of the line that ${$child}{begin} is on, then a linebreak ($BeginStringLogFile == 3)"
- ) if $is_t_switch_active;
- $trailingCharacterToken = "\n";
- }
- ${$self}{body} =~ s/\h*${$child}{id}/$trailingCharacterToken\n${$child}{id}/s;
}
}
Modified: trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Version.pm
===================================================================
--- trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Version.pm 2022-12-05 21:25:15 UTC (rev 65207)
+++ trunk/Master/texmf-dist/scripts/latexindent/LatexIndent/Version.pm 2022-12-05 21:30:10 UTC (rev 65208)
@@ -20,6 +20,6 @@
use Exporter qw/import/;
our @EXPORT_OK = qw/$versionNumber $versionDate/;
-our $versionNumber = '3.19';
-our $versionDate = '2022-10-30';
+our $versionNumber = '3.19.1';
+our $versionDate = '2022-12-04';
1
Modified: trunk/Master/texmf-dist/scripts/latexindent/defaultSettings.yaml
===================================================================
--- trunk/Master/texmf-dist/scripts/latexindent/defaultSettings.yaml 2022-12-05 21:25:15 UTC (rev 65207)
+++ trunk/Master/texmf-dist/scripts/latexindent/defaultSettings.yaml 2022-12-05 21:30:10 UTC (rev 65208)
@@ -1,4 +1,4 @@
-# defaultSettings.yaml for latexindent.pl, version 3.19, 2022-10-30
+# defaultSettings.yaml for latexindent.pl, version 3.19.1, 2022-12-04
# a script that aims to
# beautify .tex, .sty, .cls files
#
Modified: trunk/Master/texmf-dist/scripts/latexindent/latexindent.pl
===================================================================
(Binary files differ)
More information about the tex-live-commits
mailing list.