} #5 % {<label>} #6 % % for example, % \cmhlistingsfromfile*[listing options]... is NEW % \cmhlistingsfromfile[listing options]... is not new \DeclareTCBInputListing[use counter=lstlisting]{\cmhlistingsfromfile}{s O{} m O{} m m}{% cmhlistings, listing file={#3}, listing options={style=tcblatex,showspaces=false,#2}, title={\color{black}{\scshape Listing \thetcbcounter}: ~#5},label={#6}, #4, IfBooleanTF={#1}{new-to-this-version}{addtolol}, } \makeatletter \@tempswafalse \def\@tempa{draft} \@for\next:=\@classoptionslist\do {\ifx\next\@tempa\@tempswatrue\fi} \if@tempswa % draft option is active \RenewDocumentCommand{\cmhlistingsfromfile}{s O{} s m O{} m m}{\captionof{lstlisting}{#6}\label{#7}} \renewcommand{\stardemo}[1][]{$\star$} \fi % command shell \newtcblisting{commandshell}{colback=black,colupper=white,colframe=yellow!75!black, 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$\$ }}} % dosprompt \newtcblisting{dosprompt}{ colback=black, colupper=white, colframe=yellow!75!black, listing only, listing options={ language=command.com, morekeywords={latexindent,pl}, keywordstyle=\color{blue!35!white}\bfseries, basicstyle=\small\color{white}\ttfamily }, listing engine=listings, left=0cm, every listing line={\textcolor{white}{\small\ttfamily\fontseries{b}\selectfont C:\textbackslash Users\textbackslash cmh$>$}}} \lstset{% basicstyle=\small\ttfamily,language={[LaTeX]TeX}, numberstyle=\ttfamily%\small, breaklines=true, keywordstyle=\color{blue}, % keywords commentstyle=\color{purple}, % comments tabsize=3, }% \DeclareTCBListing[use counter=lstlisting]{yaml}{O{} m O{} m}{ yaml-TCB, listing options={ style=tcblatex, numbers=none, numberstyle=\color{red}, #1, }, title={\color{black}{\scshape Listing \thetcbcounter}: ~#2},label={#4}, #3, } % reference: https://tex.stackexchange.com/questions/145504/yaml-syntax-highlighting/654987#654987 \lstdefinestyle{yaml-LST}{ style=tcblatex, numbers=none, numberstyle=\color{red}\small, basicstyle=\color{black}\ttfamily\small, string=[s]{'}{'}, stringstyle=\color{black}\ttfamily\small, comment=[l]{:}, commentstyle=\color{blue}\ttfamily\small, morecomment=[l]{-}, } \lstdefinestyle{demo}{ numbers=none, linewidth=1.25\textwidth, columns=fullflexible, } \lstdefinestyle{lineNumbersTeX}{ numbers=left, numberstyle=\color{blue}, } \lstdefinestyle{fileExtensionPreference}{ style=yaml-LST, firstnumber=47,linerange={47-51}, numbers=left, } \lstdefinestyle{logFilePreferences}{ style=yaml-LST, firstnumber=90,linerange={90-104}, numbers=left, } \lstdefinestyle{verbatimEnvironments}{ style=yaml-LST, firstnumber=108,linerange={108-111}, numbers=left, } \lstdefinestyle{verbatimCommands}{ style=yaml-LST, firstnumber=114,linerange={114-116}, numbers=left, } \lstdefinestyle{noIndentBlock}{ style=yaml-LST, firstnumber=121,linerange={121-123}, numbers=left, } \lstdefinestyle{removeTrailingWhitespace}{ style=yaml-LST, firstnumber=153,linerange={153-155}, numbers=left, } \lstdefinestyle{fileContentsEnvironments}{ style=yaml-LST, firstnumber=127,linerange={127-129}, numbers=left, } \lstdefinestyle{lookForPreamble}{ style=yaml-LST, firstnumber=135,linerange={135-140}, numbers=left, } \lstdefinestyle{lookForAlignDelims}{ style=yaml-LST, firstnumber=158,linerange={158-177}, numbers=left, } \lstdefinestyle{indentAfterItems}{ style=yaml-LST, firstnumber=242,linerange={242-249}, numbers=left, } \lstdefinestyle{itemNames}{ style=yaml-LST, firstnumber=255,linerange={255-257}, numbers=left, } \lstdefinestyle{specialBeginEnd}{ style=yaml-LST, firstnumber=261,linerange={261-275}, numbers=left, } \lstdefinestyle{indentAfterHeadings}{ style=yaml-LST, firstnumber=285,linerange={285-294}, numbers=left, } \lstdefinestyle{noAdditionalIndentGlobalEnv}{ style=yaml-LST, firstnumber=343,linerange={343-344}, numbers=left, } \lstdefinestyle{noAdditionalIndentGlobal}{ style=yaml-LST, firstnumber=343,linerange={343-355}, numbers=left, } \lstdefinestyle{indentRulesGlobalEnv}{ style=yaml-LST, firstnumber=359,linerange={359-360}, numbers=left, } \lstdefinestyle{indentRulesGlobal}{ style=yaml-LST, firstnumber=359,linerange={359-371}, numbers=left, } \lstdefinestyle{commandCodeBlocks}{ style=yaml-LST, firstnumber=374,linerange={374-389}, numbers=left, } \lstdefinestyle{modifylinebreaks}{ style=yaml-LST, firstnumber=502,linerange={502-504}, numbers=left, } \lstdefinestyle{textWrapOptions}{ style=yaml-LST, firstnumber=532,linerange={532-533}, numbers=left, } \lstdefinestyle{textWrapOptionsAll}{ style=yaml-LST, firstnumber=532,linerange={532-559}, numbers=left, } \lstdefinestyle{oneSentencePerLine}{ style=yaml-LST, firstnumber=505,linerange={505-531}, numbers=left, } \lstdefinestyle{sentencesFollow}{ style=yaml-LST, firstnumber=511,linerange={511-519}, numbers=left, } \lstdefinestyle{sentencesBeginWith}{ style=yaml-LST, firstnumber=520,linerange={520-523}, numbers=left, } \lstdefinestyle{sentencesEndWith}{ style=yaml-LST, firstnumber=524,linerange={524-529}, numbers=left, } \lstdefinestyle{sentencesDoNOTcontain}{ style=yaml-LST, firstnumber=530,linerange={530-531}, numbers=left, } \lstdefinestyle{modifylinebreaksEnv}{ style=yaml-LST, firstnumber=561,linerange={561-570}, numbers=left, } \lstdefinestyle{replacements}{ style=yaml-LST, firstnumber=622,linerange={622-627}, numbers=left, } \lstdefinestyle{fineTuning}{ style=yaml-LST, firstnumber=631,linerange={631-686}, numbers=left, } % stars around contributors \pgfdeclaredecoration{stars}{initial}{ \state{initial}[width=15pt] { \pgfmathparse{round(rnd*100)} \pgfsetfillcolor{yellow!\pgfmathresult!orange} \pgfsetstrokecolor{yellow!\pgfmathresult!red} \pgfnode{star}{center}{}{}{\pgfusepath{stroke,fill}} } \state{final} { \pgfpathmoveto{\pgfpointdecoratedpathlast} } } \newtcolorbox{stars}{% enhanced jigsaw, breakable, % allow page breaks left=0cm, top=0cm, before skip=0.2cm, boxsep=0cm, frame style={draw=none,fill=none}, % hide the default frame colback=white, overlay={ \draw[inner sep=0,minimum size=rnd*15pt+2pt] decorate[decoration={stars,segment length=2cm}] { decorate[decoration={zigzag,segment length=2cm,amplitude=0.3cm}] { ([xshift=-.5cm,yshift=0.1cm]frame.south west) -- ([xshift=-.5cm,yshift=0.4cm]frame.north west) }}; \draw[inner sep=0,minimum size=rnd*15pt+2pt] decorate[decoration={stars,segment length=2cm}] { decorate[decoration={zigzag,segment length=2cm,amplitude=0.3cm}] { ([xshift=.75cm,yshift=0.1cm]frame.south east) -- ([xshift=.75cm,yshift=0.6cm]frame.north east) }}; \node[anchor=north west,outer sep=2pt,opacity=0.25] at ([xshift=-4.25cm]frame.north west) {\resizebox{3cm}{!}{\faGithub}}; }, % paragraph skips obeyed within tcolorbox parbox=false, } \newtcolorbox[auto counter]{example}{breakable, enhanced jigsaw, before skip balanced, after skip balanced, frame hidden, % % title stuff % title={example~\thetcbcounter}, fonttitle=\bfseries\sffamily, detach title, coltitle=black, colback=white, grow to left by=6mm, % % circles and line by the side % overlay unbroken and first={% \node at ([xshift=-8mm,yshift=-4.5mm]interior.north west) {\bfseries example \thetcbcounter}; \path [fill=black] ([xshift=1mm,yshift=3mm]interior.south east) node{\hbox{\rule{1ex}{1ex}}}; }, overlay last={% \path [fill=black] ([xshift=1mm,yshift=3mm]interior.south east) node{\hbox{\rule{1ex}{1ex}}}; }, parbox=false, } % copied from /usr/local/texlive/2013/texmf-dist/tex/latex/biblatex/bbx/numeric.bbx % the only modification is the \stars and \endstars \defbibenvironment{specialbib} {\stars\list {\printtext[labelnumberwidth]{% \printfield{prefixnumber}% \printfield{labelnumber}}} {\setlength{\labelwidth}{\labelnumberwidth}% \setlength{\leftmargin}{\labelwidth}% \setlength{\labelsep}{\biblabelsep}% \addtolength{\leftmargin}{\labelsep}% \setlength{\itemsep}{\bibitemsep}% \setlength{\parsep}{\bibparsep}}% \renewcommand*{\makelabel}[1]{\hss##1}} {\endlist\endstars} {\item} \newcommand{\flagbox}[1]{% \par \makebox[30pt][l]{% \hspace{-1cm}% \ttfamily\fontseries{b}\selectfont #1 }% } \NewDocumentCommand{\yamltitle}{O{} m s m}{% \par \makebox[30pt][l]{% \hspace{-2cm}% \tcbox[colframe=black!50!white,boxrule=.5pt,sharp corners,#1]{% {\ttfamily\fontseries{b}\selectfont{\color{blue!80!white}#2}}: % \IfBooleanTF{#3} {$\langle$\itshape #4$\rangle$} {{\bfseries #4}} }} \par\nobreak% } \newcommand{\fixthis}[1] {% \marginpar{\huge \color{red} \framebox{FIX}}% \typeout{FIXTHIS: p\thepage : #1^^J}% } \newcommand*\ruleline[1]{% \par\noindent\raisebox{.8ex}{\makebox[\linewidth]{\hrulefill\hspace{1ex}\raisebox{-1.8ex}{#1}\hspace{1ex}\hrulefill}}} \newcommand{\imagetouse}{logo-bw} % custom section \titleformat% Formatting the header {\section} % command [block] % shape - Only managed to get it working with block {\normalfont\bfseries\huge} % format - Change here as needed {\centering {\scshape Section \thesection}\\} % the section {0pt} % sep {\centering \ruleline{\includegraphics{\imagetouse}}\\ % The horizontal rule \centering} % And the actual title % custom subsection \titleformat{\subsection} {\normalfont\bfseries} {\llap{\thesubsection\hskip.5cm}} {0pt} {} % custom subsubsection \titleformat{\subsubsection} {\normalfont\bfseries} {\llap{\thesubsubsection\hskip.5cm}} {0pt} {} % custom paragraph \titleformat{\paragraph} {\normalfont\bfseries} {\llap{\theparagraph\hskip.5cm}} {0pt} {} % title spacing \titlespacing\section{0pt}{12pt plus 4pt minus 2pt}{34pt plus 2pt minus 2pt} \titlespacing\subsection{0pt}{12pt plus 4pt minus 2pt}{4pt plus 2pt minus 2pt} \titlespacing\subsubsection{0pt}{12pt plus 4pt minus 2pt}{4pt plus 2pt minus 2pt} \titlespacing\paragraph{0pt}{12pt plus 4pt minus 2pt}{4pt plus 2pt minus 2pt} % list of listings \contentsuse{lstlisting}{lol} \titleclass{\lstlistingstar}{straight}[\section] \titleformat{\lstlistingstar}{}{}{}{} \titlecontents{lstlistingstar}[2em] {\addvspace{0.25pc}} {} {\llap{\stardemo}\thecontentslabel} {\titlerule*[0.5em]{$\cdot$}\contentspage} [] \titlecontents{lstlisting}[2em] {\addvspace{0.25pc}} {\thecontentslabel} {\thecontentslabel} {\titlerule*[0.5em]{$\cdot$}\contentspage} [] \AtBeginDocument{\addtocontents{lol}{\protect\begin{widepage}\protect\begin{multicols}{2}}} \preto{\printindex}{\addtocontents{lol}{\protect\end{multicols}\protect\end{widepage}}} % cleveref settings \crefname{table}{Table}{Tables} \Crefname{table}{Table}{Tables} \crefname{figure}{Figure}{Figures} \Crefname{figure}{Figure}{Figures} \crefname{section}{Section}{Sections} \Crefname{section}{Section}{Sections} \crefname{listing}{Listing}{Listings} \Crefname{listing}{Listing}{Listings} % headers and footers \fancyhf{} % delete current header and footer \fancyhead[R]{\bfseries\thepage% \tikz[remember picture,overlay] { \node at (1,0){\includegraphics{logo-bw}}; } } \fancyhead[L]{\rightmark} \fancyheadoffset[L]{3cm} \pagestyle{fancy} % renew plain style \fancypagestyle{plain}{% \fancyhf{} % clear all header and footer fields \renewcommand{\headrulewidth}{0pt} \renewcommand{\footrulewidth}{0pt}} % widepage environment \newenvironment{widepage}{\begin{adjustwidth}{-3cm}{0cm}}{\end{adjustwidth}} % symbols for the m switch \newcommand{\BeginStartsOnOwnLine}{\color{red}\spadesuit} \newcommand{\BodyStartsOnOwnLine}{\color{red}\heartsuit} \newcommand{\EndStartsOnOwnLine}{\color{red}\diamondsuit} \newcommand{\EndFinishesWithLineBreak}{\color{red}\clubsuit} \newcommand{\ElseStartsOnOwnLine}{\color{red}\bigstar} \newcommand{\ElseFinishesWithLineBreak}{\color{red}\square} \newcommand{\OrStartsOnOwnLine}{\color{red}\blacktriangle} \newcommand{\OrFinishesWithLineBreak}{\color{red}\blacktriangledown} \newcommand{\EqualsStartsOnOwnLine}{\color{red}\bullet} % table rules \setlength\heavyrulewidth{0.25ex} % gitinfo2 settings \renewcommand{\gitMark}{\gitBranch\,@\,\gitAbbrevHash{}\,\textbullet{}\,\gitAuthorDate\,\textbullet{}\faGithub\,\textbullet{}\gitRel} % setting up gitinfo2: % copy the file post-xxx-sample.txt from http://mirror.ctan.org/macros/latex/contrib/gitinfo2 % and put it in .git/hooks/post-checkout % then % cd .git/hooks % chmod g+x post-checkout % chmod +x post-checkout % cp post-checkout post-commit % cp post-checkout post-merge % cd ../.. % git checkout master % git checkout develop % ls .git % and you should see gitHeadInfo.gin % % Make sure that the 'V' is included in the below! % % RELTAG=$(git describe --tags --long --always --dirty='-*' --match 'V[0-9]*.*' 2>/dev/null) % http://tex.stackexchange.com/questions/233843/textasteriskcentered-invisible-with-garamondmathdesign % remove the definition of \textasteriskcentered for TS1 encoding \UndeclareTextCommand{\textasteriskcentered}{TS1} % reinstate a default encoding \DeclareTextSymbolDefault{\textasteriskcentered}{OT1} % suitably define the command \DeclareTextCommand{\textasteriskcentered}{OT1}{\raisebox{-.7ex}[1ex][0pt]{*}} % new features list \newcommand{\listOfNewFeatures}{\setcounter{tocdepth}{4}\@starttoc{new}} \contentsuse{cmhtitle}{new} % toc settings \titleclass{\cmhtitle}{straight}[\subsection] \titleformat{\cmhtitle}{}{}{}{} \titlecontents{cmhtitle}% <paragraph> [2cm]% <left> {\small\itshape}% <above-code> {}% <numbered-entry-format>; you could also use {\thecontentslabel. } to show the numbers {}% <numberless-entry-format> {\titlerule*[0.5em]{$\cdot$}\contentspage} % to explore in the future: % partial toc customisation % https://tex.stackexchange.com/questions/66345/how-to-remove-section-indentation-in-partial-toc-using-titletoc \setcounter{secnumdepth}{6} \setcounter{tocdepth}{4} \makeindex \newif\iftestdefaultsettings \testdefaultsettingsfalse %\testdefaultsettingstrue \begin{document} % arara: pdflatex: { files: [latexindent]} \section{Introduction} \subsection{Thanks} I first created \texttt{latexindent.pl} to help me format chapter files in a big project. After I blogged about it on the \TeX{} stack exchange \cite{cmhblog} I received some positive feedback and follow-up feature requests. A big thank you to Harish Kumar \cite{harish} who helped to develop and test the initial versions of the script. The \texttt{YAML}-based interface of \texttt{latexindent.pl} was inspired by the wonderful \texttt{arara} tool; any similarities are deliberate, and I hope that it is perceived as the compliment that it is. Thank you to Paulo Cereda and the team for releasing this awesome tool; I initially worried that I was going to have to make a GUI for \texttt{latexindent.pl}, but the release of \texttt{arara} has meant there is no need. There have been several contributors to the project so far (and hopefully more in the future!); thank you very much to the people detailed in \vref{sec:contributors} for their valued contributions, and thank you to those who report bugs and request features at \cite{latexindent-home}. \subsection{License} \texttt{latexindent.pl} is free and open source, and it always will be; it is released under the GNU General Public License v3.0. Before you start using it on any important files, bear in mind that \texttt{latexindent.pl} has the option to overwrite your \texttt{.tex} files. It will always make at least one backup (you can choose how many it makes, see \cpageref{page:onlyonebackup}) but you should still be careful when using it. The script has been tested on many files, but there are some known limitations (see \cref{sec:knownlimitations}). You, the user, are responsible for ensuring that you maintain backups of your files before running \texttt{latexindent.pl} on them. I think it is important at this stage to restate an important part of the license here: \begin{quote}\itshape This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. \end{quote} There is certainly no malicious intent in releasing this script, and I do hope that it works as you expect it to; if it does not, please first of all make sure that you have the correct settings, and then feel free to let me know at \cite{latexindent-home} with a complete minimum working example as I would like to improve the code as much as possible. \begin{warning} Before you try the script on anything important (like your thesis), test it out on the sample files in the \texttt{test-case} directory \cite{latexindent-home}. \index{warning!be sure to test before use} \end{warning} \emph{If you have used any version 2.* of \texttt{latexindent.pl}, there are a few changes to the interface; see \vref{app:differences} and the comments throughout this document for details}. \subsection{Quick start}\label{sec:quickstart} When \texttt{latexindent.pl} reads and writes files, the files are read and written in UTF-8 format by default. That is to say, the encoding format for tex and yaml files needs to be in UTF-8 format. 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 no explanation in this section, which is deliberate for a quick start. The rest of the manual is more verbose. \cmhlistingsfromfile{demonstrations/quick-start.tex}{\texttt{quick-start.tex}}{lst:quick-start} 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} latexindent.pl -l quick-start1.yaml quick-start.tex \end{commandshell} gives \cref{lst:quick-start-mod1}. \begin{cmhtcbraster} \cmhlistingsfromfile[showspaces=true]{demonstrations/quick-start-mod1.tex}{\texttt{quick-start-mod1.tex}}{lst:quick-start-mod1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/quick-start1.yaml}[yaml-TCB]{\texttt{quick-start1.yaml}}{lst:quick-start1yaml} \end{cmhtcbraster} See \cref{subsec:indentation:and:horizontal:space}. \end{example} \begin{example} Running \begin{commandshell} latexindent.pl -l quick-start2.yaml quick-start.tex \end{commandshell} gives \cref{lst:quick-start-mod2}. \begin{cmhtcbraster} \cmhlistingsfromfile[showspaces=true]{demonstrations/quick-start-mod2.tex}{\texttt{quick-start-mod2.tex}}{lst:quick-start-mod2} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/quick-start2.yaml}[yaml-TCB]{\texttt{quick-start2.yaml}}{lst:quick-start2yaml} \end{cmhtcbraster} See \cref{sec:noadd-indent-rules}. \end{example} \begin{example} 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-start-mod3.tex}{\texttt{quick-start-mod3.tex}}{lst:quick-start-mod3} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/quick-start3.yaml}[yaml-TCB]{\texttt{quick-start3.yaml}}{lst:quick-start3yaml} \end{cmhtcbraster} See \cref{sec:noadd-indent-rules}. \end{example} \begin{example} 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-start-mod4.tex}{\texttt{quick-start-mod4.tex}}{lst:quick-start-mod4} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/quick-start4.yaml}[MLB-TCB]{\texttt{quick-start4.yaml}}{lst:quick-start4yaml} \end{cmhtcbraster} Full details of text wrapping in \cref{subsec:textwrapping}. \end{example} \begin{example} 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-start-mod5.tex}{\texttt{quick-start-mod5.tex}}{lst:quick-start-mod5} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/quick-start5.yaml}[MLB-TCB]{\texttt{quick-start5.yaml}}{lst:quick-start5yaml} \end{cmhtcbraster} Full details of text wrapping in \cref{subsec:textwrapping}. \end{example} \begin{example} 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-start-mod6.tex}{\texttt{quick-start-mod6.tex}}{lst:quick-start-mod6} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/quick-start6.yaml}[MLB-TCB]{\texttt{quick-start6.yaml}}{lst:quick-start6yaml} \end{cmhtcbraster} This is an example of a \emph{poly-switch}; full details of \emph{poly-switches} are covered in \cref{sec:poly-switches}. \end{example} \begin{example} 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-start-mod7.tex}{\texttt{quick-start-mod7.tex}}{lst:quick-start-mod7} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/quick-start7.yaml}[MLB-TCB]{\texttt{quick-start7.yaml}}{lst:quick-start7yaml} \end{cmhtcbraster} Full details of \emph{poly-switches} are covered in \cref{sec:poly-switches}. \end{example} \begin{example} Running \begin{commandshell} latexindent.pl -l quick-start8.yaml quick-start.tex \end{commandshell} gives \cref{lst:quick-start-mod8}; note that the \emph{preamble} has been indented. \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/quick-start-mod8.tex}{\texttt{quick-start-mod8.tex}}{lst:quick-start-mod8} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/quick-start8.yaml}[yaml-TCB]{\texttt{quick-start8.yaml}}{lst:quick-start8yaml} \end{cmhtcbraster} See \cref{subsec:filecontents:preamble}. \end{example} \begin{example} Running \begin{commandshell} latexindent.pl -l quick-start9.yaml quick-start.tex \end{commandshell} gives \cref{lst:quick-start-mod9}. \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/quick-start-mod9.tex}{\texttt{quick-start-mod9.tex}}{lst:quick-start-mod9} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/quick-start9.yaml}[yaml-TCB]{\texttt{quick-start9.yaml}}{lst:quick-start9yaml} \end{cmhtcbraster} See \cref{sec:noadd-indent-rules}. \end{example} \subsection{Required perl modules} If you receive an error message such as that given in \cref{lst:poss-errors}, then you need to install the missing perl modules. \begin{cmhlistings}[style=tcblatex,language=Perl]{Possible error messages}{lst:poss-errors} Can't locate File/HomeDir.pm in @INC (@INC contains: /Library/Perl/5.12/darwin-thread-multi-2level /Library/Perl/5.12 /Network/Library/Perl/5.12/darwin-thread-multi-2level /Network/Library/Perl/5.12 /Library/Perl/Updates/5.12.4/darwin-thread-multi-2level /Library/Perl/Updates/5.12.4 /System/Library/Perl/5.12/darwin-thread-multi-2level /System/Library/Perl/5.12 /System/Library/Perl/Extras/5.12/darwin-thread-multi-2level /System/Library/Perl/Extras/5.12 .) at helloworld.pl line 10. BEGIN failed--compilation aborted at helloworld.pl line 10. \end{cmhlistings} \texttt{latexindent.pl} ships with a script to help with this process; if you run the following script, you should be prompted to install the appropriate modules. \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}. \subsection{About this documentation} As you read through this documentation, you will see many listings; in this version of the documentation, there are a total of \totallstlistings. This may seem a lot, but I deem it necessary in presenting the various different options of \texttt{latexindent.pl} and the associated output that they are capable of producing. The different listings are presented using different styles: \begin{widepage} \begin{minipage}{.4\linewidth} \cmhlistingsfromfile{demonstrations/demo-tex.tex}{\texttt{demo-tex.tex}}{lst:demo-tex} \end{minipage}% \hfill \begin{minipage}{.4\linewidth} This type of listing is a \texttt{.tex} file. \end{minipage}% \begin{minipage}{.4\linewidth} \cmhlistingsfromfile[style=fileExtensionPreference]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{fileExtensionPreference}}{lst:fileExtensionPreference-demo} \end{minipage}% \hfill \begin{minipage}{.4\linewidth} This type of listing is a \texttt{.yaml} file; when you see line numbers given (as here) it means that the snippet is taken directly from \texttt{defaultSettings.yaml}, discussed in detail in \vref{sec:defuseloc}. \end{minipage}% \begin{minipage}{.6\linewidth} \cmhlistingsfromfile[style=modifylinebreaks]{../defaultSettings.yaml}[MLB-TCB,width=.95\linewidth,before=\centering]{\texttt{modifyLineBreaks}}{lst:modifylinebreaks-demo} \end{minipage}% \hfill \begin{minipage}{.4\linewidth} This type of listing is a \texttt{.yaml} file, but it will only be relevant when the \texttt{-m} switch is active; see \vref{sec:modifylinebreaks} for more details. \end{minipage}% \begin{minipage}{.6\linewidth} \cmhlistingsfromfile[style=replacements]{../defaultSettings.yaml}[replace-TCB,width=.95\linewidth,before=\centering]{\texttt{replacements}}{lst:replacements-demo} \end{minipage}% \hfill \begin{minipage}{.4\linewidth} This type of listing is a \texttt{.yaml} file, but it will only be relevant when the \texttt{-r} switch is active; see \vref{sec:replacements} for more details. \end{minipage}% \end{widepage} % \begin{latexonly} You will occasionally see dates shown in the margin (for example, next to this paragraph!) \announce{2017-06-25}{announce} which detail the date of the version in which the feature was implemented; the `N' stands for `new as of the date shown' and `U' stands for `updated as of the date shown'. If you see \stardemo, it means that the feature is either new (N) or updated (U) as of the release of the current version; if you see \stardemo\, attached to a listing, then it means that listing is new (N) or updated (U) as of the current version. If you have not read this document before (and even if you have!), then you can ignore every occurrence of the \stardemo; they are simply there to highlight new and updated features. The new and updated features in this documentation (\gitRel) are on the following pages: \listOfNewFeatures% % \end{latexonly} \subsection{A word about regular expressions} \index{regular expressions!a word about} As you read this documentation, you may encounter the term \emph{regular expressions}. I've tried to write this documentation in such a way so as to allow you to engage with them or not, as you prefer. This documentation is not designed to be a guide to regular expressions, and if you'd like to read about them, I recommend \cite{masteringregexp}. % arara: pdflatex: { files: [latexindent]} \section{Demonstration: before and after} Let's give a demonstration of some before and after code -- after all, you probably won't want to try the script if you don't much like the results. You might also like to watch the video demonstration I made on youtube \cite{cmh:videodemo} As you look at \crefrange{lst:filecontentsbefore}{lst:pstricksafter}, remember that \texttt{latexindent.pl} is just following its rules, and there is nothing particular about these code snippets. All of the rules can be modified so that you can personalise your indentation scheme. In each of the samples given in \crefrange{lst:filecontentsbefore}{lst:pstricksafter} the `before' case is a `worst case scenario' with no effort to make indentation. The `after' result would be the same, regardless of the leading white space at the beginning of each line which is stripped by \texttt{latexindent.pl} (unless a \texttt{verbatim}-like environment or \texttt{noIndentBlock} is specified -- more on this in \cref{sec:defuseloc}). \begin{widepage} \centering \begin{minipage}{.45\linewidth} \cmhlistingsfromfile{demonstrations/filecontents1.tex}{\texttt{filecontents1.tex}}{lst:filecontentsbefore} \end{minipage}\hfill \begin{minipage}{.45\linewidth} \cmhlistingsfromfile{demonstrations/filecontents1-default.tex}{\texttt{filecontents1.tex} default output}{lst:filecontentsafter} \end{minipage}% \begin{minipage}{.45\linewidth} \cmhlistingsfromfile{demonstrations/tikzset.tex}{\texttt{tikzset.tex}}{lst:tikzsetbefore} \end{minipage}\hfill \begin{minipage}{.45\linewidth} \cmhlistingsfromfile{demonstrations/tikzset-default.tex}{\texttt{tikzset.tex} default output}{lst:tikzsetafter} \end{minipage}% \begin{minipage}{.45\linewidth} \cmhlistingsfromfile{demonstrations/pstricks.tex}{\texttt{pstricks.tex}}{lst:pstricksbefore} \end{minipage}\hfill \begin{minipage}{.45\linewidth} \cmhlistingsfromfile{demonstrations/pstricks-default.tex}{\texttt{pstricks.tex} default output}{lst:pstricksafter} \end{minipage}% \end{widepage} % arara: pdflatex: { files: [latexindent]} \section{How to use the script}\label{sec:how:to:use} \texttt{latexindent.pl} ships as part of the \TeX Live distribution for Linux and Mac users; \texttt{latexindent.exe} ships as part of the \TeX Live for Windows users. These files are also available from github \cite{latexindent-home} should you wish to use them without a \TeX{} distribution; in this case, you may like to read \vref{sec:updating-path} which details how the \texttt{path} variable can be updated. \index{TeXLive} In what follows, we will always refer to \texttt{latexindent.pl}, but depending on your operating system and preference, you might substitute \texttt{latexindent.exe} or simply \texttt{latexindent}. There are two ways to use \texttt{latexindent.pl}: from the command line, and using \texttt{arara}; we discuss these in \cref{sec:commandline} and \cref{sec:arara} respectively. We will discuss how to change the settings and behaviour of the script in \vref{sec:defuseloc}. \subsection{Requirements} \subsubsection{Perl users} Perl users will need a few standard Perl modules -- see \vref{sec:requiredmodules} for details; \announce{2018-01-13}{perl module installer helper script} in particular, note that a module installer helper script is shipped with \texttt{latexindent.pl}.% \subsubsection{Windows users without perl}\label{subsubsec:latexindent:exe} \texttt{latexindent.pl} ships with \texttt{latexindent.exe} for Windows users, so that you can use the script with or without a Perl distribution. \texttt{latexindent.exe} is available from \cite{latexindent-home}. MiKTeX users on Windows may like to see \cite{miktex-guide} for details of how to use \texttt{latexindent.exe} without a Perl installation. \index{MiKTeX} \index{latexindent.exe} \index{Windows} \subsubsection{Ubuntu Linux users without perl} \texttt{latexindent.pl} ships with \texttt{latexindent-linux} for Ubuntu Linux users, so that you can use the script with or without a Perl distribution. \index{latexindent-linux} \index{linux} \index{TeXLive} \texttt{latexindent-linux} is available from \cite{latexindent-home}. \announce{2022-10-30}{Linux Ubuntu standalone executable} \subsubsection{macOS users without perl} \texttt{latexindent.pl} ships with \texttt{latexindent-macos} for macOS users, so that you can use the script with or without a Perl distribution. \index{latexindent-macos} \index{macOS} \index{TeXLive} \texttt{latexindent-macOS} is available from \cite{latexindent-home}. \announce{2022-10-30}{macOS standalone executable} \subsubsection{conda users} Users of \texttt{conda} should see the details given in \cref{sec:app:conda}. \index{conda} \subsubsection{docker users} Users of \texttt{docker} should see the details given in \cref{sec:app:docker}. \index{docker} \subsection{From the command line}\label{sec:commandline} \texttt{latexindent.pl} has a number of different switches/flags/options, which can be combined in any way that you like, either in short or long form as detailed below. \texttt{latexindent.pl} produces a \texttt{.log} file, \texttt{indent.log}, every time it is run; the name of the log file can be customised, but we will refer to the log file as \texttt{indent.log} throughout this document. There is a base of information that is written to \texttt{indent.log}, but other additional information will be written depending on which of the following options are used. When using \texttt{latexindent.pl} in different ways on different systems, the range of characters supported by its switches/flags/options may vary. We discuss these in Section \cref{app:encoding}. \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}. \flagbox{-h, --help} \index{switches!-h, --help definition and details} \begin{commandshell} latexindent.pl -h latexindent.pl --help \end{commandshell} As above this will output a welcome message to the terminal, including the version number and available options. \begin{commandshell} latexindent.pl myfile.tex \end{commandshell} This will operate on \texttt{myfile.tex}, but will simply output to your terminal; \texttt{myfile.tex} will not be changed by \texttt{latexindent.pl} in any way using this command. 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 latexindent.pl myfile.tex --overwrite \end{commandshell} This \emph{will} overwrite \texttt{myfile.tex}, but it will make a copy of \texttt{myfile.tex} first. You can control the name of the extension (default is \texttt{.bak}), and how many different backups are made -- more on this in \cref{sec:defuseloc}, and in particular see \texttt{backupExtension} and \texttt{onlyOneBackUp}. Note that if \texttt{latexindent.pl} can not create the backup, then it will exit without touching your original file; an error message will be given asking you to check the permissions of the backup file. \flagbox{-wd, --overwriteIfDifferent} \index{switches!-wd, --overwriteIfDifferent definition and details} \index{backup files!overwriteIfDifferent switch, -wd} \announce{2022-03-25}{overwriteIfDifferent switch} \begin{commandshell} latexindent.pl -wd myfile.tex latexindent.pl --overwriteIfDifferent myfile.tex latexindent.pl myfile.tex --overwriteIfDifferent \end{commandshell} This \emph{will} overwrite \texttt{myfile.tex} but only \emph{if the indented text is different from the original}. If the indented text is \emph{not} different from the original, then \texttt{myfile.tex} will \emph{not} be overwritten. All other details from the \texttt{-w} switch are relevant here. If you call \texttt{latexindent.pl} with both the \texttt{-wd} and the \texttt{-w} switch, then the \texttt{-w} switch will be deactivated and the \texttt{-wd} switch takes priority. \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 latexindent.pl --outputfile=output.tex myfile.tex latexindent.pl --outputfile output.tex myfile.tex \end{commandshell} This will indent \texttt{myfile.tex} and output it to \texttt{output.tex}, overwriting it (\texttt{output.tex}) if it already exists\footnote{Users of version 2.* should note the subtle change in syntax}. Note that if \texttt{latexindent.pl} is called with both the \texttt{-w} and \texttt{-o} switches, then \texttt{-w} will be ignored and \texttt{-o} will take priority (this seems safer than the other way round). The same is true for the \texttt{-wd} switch, and the \texttt{-o} switch takes priority over it. Note that using \texttt{-o} as above is equivalent to using \begin{commandshell} latexindent.pl myfile.tex > output.tex \end{commandshell} You can call the \texttt{-o} switch with the name of the output file \emph{without} an extension; in \announce{2017-06-25}{upgrade to -o switch} this case, \texttt{latexindent.pl} will use the extension from the original file. For example, the following two calls to \texttt{latexindent.pl} are equivalent:% \begin{commandshell} latexindent.pl myfile.tex -o=output latexindent.pl myfile.tex -o=output.tex \end{commandshell} You can call the \texttt{-o} switch using a \texttt{+} symbol at the beginning; this will \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 \end{commandshell} You can call the \texttt{-o} switch using a \texttt{++} symbol at the end of the name \announce{2017-06-25}{++ in o switch} of your output file; this tells \texttt{latexindent.pl} to search successively for the name of your output file concatenated with $0, 1, \ldots$ while the name of the output file exists. For example,% \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} 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 \end{commandshell} Silent mode: no output will be given to the terminal. \flagbox{-t, --trace} \index{switches!-t, --trace definition and details} \begin{commandshell} latexindent.pl -t myfile.tex latexindent.pl myfile.tex -t \end{commandshell} \label{page:traceswitch} Tracing mode: verbose output will be given to \texttt{indent.log}. This is useful if \texttt{latexindent.pl} has made a mistake and you're trying to find out where and why. You might also be interested in learning about \texttt{latexindent.pl}'s thought process -- if so, this switch is for you, although it should be noted that, especially for large files, this does affect performance of the script. \flagbox{-tt, --ttrace} \index{switches!-tt, --ttrace definition and details} \begin{commandshell} latexindent.pl -tt myfile.tex latexindent.pl myfile.tex -tt \end{commandshell} \emph{More detailed} tracing mode: this option gives more details to \texttt{indent.log} than the standard \texttt{trace} option (note that, even more so than with \texttt{-t}, especially for large files, performance of the script will be affected). \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 latexindent.pl -l myyaml.yaml myfile.tex latexindent.pl -l first.yaml,second.yaml,third.yaml myfile.tex latexindent.pl -l=first.yaml,second.yaml,third.yaml myfile.tex latexindent.pl myfile.tex -l=first.yaml,second.yaml,third.yaml \end{commandshell} \label{page:localswitch} \texttt{latexindent.pl} will always load \texttt{defaultSettings.yaml} (rhymes with camel) and if it is called with the \texttt{-l} switch and it finds \texttt{localSettings.yaml} in the same directory as \texttt{myfile.tex}, then, if not found, it looks for \texttt{localSettings.yaml} (and friends, see \vref{sec:localsettings}) in the current working directory, then these% \announce{2021-03-14}*{-l switch: localSettings and friends} settings will be added to the indentation scheme. Information will be given in \texttt{indent.log} on the success or failure of loading \texttt{localSettings.yaml}. The \texttt{-l} flag can take an \emph{optional} parameter which details the name (or names separated by commas) of a YAML file(s) that resides in the same directory as \texttt{myfile.tex}; you can use this option if you would like to load a settings file in the current working directory that is \emph{not} called \texttt{localSettings.yaml}. \announce{2017-08-21}*{-l switch absolute paths} In fact, you can specify both \emph{relative} and \emph{absolute paths} for your YAML files; for example% \begin{commandshell} latexindent.pl -l=../../myyaml.yaml myfile.tex latexindent.pl -l=/home/cmhughes/Desktop/myyaml.yaml myfile.tex latexindent.pl -l=C:\Users\cmhughes\Desktop\myyaml.yaml myfile.tex \end{commandshell} You will find a lot of other explicit demonstrations of how to use the \texttt{-l} switch throughout this documentation, You 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. 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:' '" latexindent.pl myfile.tex -y="indentRules: one: '\t\t\t\t'" 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. Note, in particular, that multiple settings can be specified by separating them via commas. There is a further option to use a \texttt{;} to separate fields, which is demonstrated in \vref{sec:yamlswitch}. Any settings specified via this switch will be loaded \emph{after} any specified using the \texttt{-l} switch. This is discussed further in \vref{sec:loadorder}. \flagbox{-d, --onlydefault} \index{switches!-d, --onlydefault definition and details} \begin{commandshell} latexindent.pl -d myfile.tex \end{commandshell} Only \texttt{defaultSettings.yaml}: you might like to read \cref{sec:defuseloc} before using this switch. By default, \texttt{latexindent.pl} will always search for \texttt{indentconfig.yaml} or \texttt{.indentconfig.yaml} in your home directory. If you would prefer it not to do so then (instead of deleting or renaming \texttt{indentconfig.yaml} or \texttt{.indentconfig.yaml}) you can simply call the script with the \texttt{-d} switch; note that this will also tell the script to ignore \texttt{localSettings.yaml} even if it has been called with the \texttt{-l} switch; \texttt{latexindent.pl} \announce{2017-08-21}*{updated -d switch} will also ignore any settings specified from the \texttt{-y} switch.% \flagbox{-c, --cruft=<directory>} \index{switches!-c, --cruft definition and details} \begin{commandshell} latexindent.pl -c=/path/to/directory/ myfile.tex \end{commandshell} If you wish to have backup files and \texttt{indent.log} written to a directory other than the current working directory, then you can send these `cruft' files to another directory. Note the use of a trailing forward slash. % this switch was made as a result of http://tex.stackexchange.com/questions/142652/output-latexindent-auxiliary-files-to-a-different-directory If the cruft directory does not exist, \texttt{latexindent.pl} will attempt to create it. \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 latexindent.pl --logfile other.log myfile.tex latexindent.pl myfile.tex -g other.log \end{commandshell} By default, \texttt{latexindent.pl} reports information to \texttt{indent.log}, but if you wish to change the name of this file, simply call the script with your chosen name after the \texttt{-g} switch as demonstrated above. \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} \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.% \flagbox{-m, --modifylinebreaks} \index{switches!-m, --modifylinebreaks definition and details} \begin{commandshell} latexindent.pl -m myfile.tex latexindent.pl -modifylinebreaks myfile.tex \end{commandshell} One of the most exciting developments in Version~3.0 is the ability to modify line breaks; for full details see \vref{sec:modifylinebreaks} \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 have content in \texttt{myfile.tex}, then the above command will output the results of operating upon \texttt{myfile.tex}. If you wish to use this feature with your own local settings, via the \texttt{-l} switch, then you should finish your call to \texttt{latexindent.pl} with a \texttt{-} sign: \begin{commandshell} cat myfile.tex | latexindent.pl -l=mysettings.yaml - \end{commandshell} 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} Once you have finished typing your input, you can press \begin{itemize} \item \texttt{CTRL+D} on Linux \item \texttt{CTRL+Z} followed by \texttt{ENTER} on Windows \end{itemize} to signify that your input has finished. 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, replacementrespectverb switch}% \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 in \vref{sec:replacements}.% \flagbox{-rr, --onlyreplacement} \index{switches!-rr, --onlyreplacement definition and details} \begin{commandshell} latexindent.pl -rr myfile.tex latexindent.pl -onlyreplacement myfile.tex \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 examples are given in \vref{sec:replacements}.% \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.% The \texttt{exit} code \index{exit code} of \texttt{latexindent.pl} is 0 by default. If you use the \texttt{-k} switch then \begin{itemize} \item if the text after indentation matches that given in the original file, then the exit code is 0; \item if the text after indentation does \emph{not} match that given in the original file, then the exit code is 1. \end{itemize} The value of the exit code may be important to those wishing to, for example, check the status of the indentation in continuous integration tools such as GitHub Actions. Full details of the exit codes of \texttt{latexindent.pl} are given in \cref{tab:exit-codes}. A simple \texttt{diff} will be given in \texttt{indent.log}. \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}. \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}. Complete demonstrations are given in \cref{sec:line-switch}. \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 work for your language. Further details are given in \cref{subsec:the-GCString}. \subsection{From arara}\label{sec:arara} Using \texttt{latexindent.pl} from the command line is fine for some folks, but others may find it easier to use from \texttt{arara}; you can find the arara rule for \texttt{latexindent.pl} and its associated documentation at \cite{paulo}. \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] \caption{Exit codes for \texttt{latexindent.pl}} \label{tab:exit-codes} \begin{tabular}{ccl} \toprule exit code & indentation & status \\ \midrule 0 & \faCheck & success; if \texttt{-k} or \texttt{-kv} active, indented text matches original \\ 0 & \faClose & success; if \texttt{-version}, \texttt{-vversion} or \texttt{-help}, no indentation performed \\ 1 & \faCheck & success, and \texttt{-k} or \texttt{-kv} active; indented text \emph{different} from original \\ \midrule 2 & \faClose & failure, \texttt{defaultSettings.yaml} could not be read \\ 3 & \faClose & failure, myfile.tex not found \\ 4 & \faClose & failure, myfile.tex exists but cannot be read \\ 5 & \faClose & failure, \texttt{-w} active, and back-up file cannot be written \\ 6 & \faClose & failure, \texttt{-c} active, and cruft directory could not be created \\ \bottomrule \end{tabular} \end{table} % arara: pdflatex: { files: [latexindent]} \section{indentconfig.yaml, local settings and the -y switch }\label{sec:indentconfig} The behaviour of \texttt{latexindent.pl} is controlled from the settings specified in any of the YAML files that you tell it to load. By default, \texttt{latexindent.pl} will only load \texttt{defaultSettings.yaml}, but there are a few ways that you can tell it to load your own settings files. We focus our discussion on \texttt{indentconfig.yaml}, but there are other options which are detailed in \cref{app:indentconfig:options}. \announce{2023-01-01}{indentconfig location options} \subsection{indentconfig.yaml and .indentconfig.yaml}\label{subsec:indentconfig} \texttt{latexindent.pl} will always check your home directory for \texttt{indentconfig.yaml} and \texttt{.indentconfig.yaml} (unless it is called with the \texttt{-d} switch), which is a plain text file you can create that contains the \emph{absolute} paths for any settings files that you wish \texttt{latexindent.pl} to load. There is no difference between \texttt{indentconfig.yaml} and \texttt{.indentconfig.yaml}, other than the fact that \texttt{.indentconfig.yaml} is a `hidden' file; thank you to \cite{jacobo-diaz-hidden-config} for providing this feature. In what follows, we will use \texttt{indentconfig.yaml}, but it is understood that this could equally represent \texttt{.indentconfig.yaml}. If you have both files in existence then \texttt{indentconfig.yaml} takes priority. For Mac and Linux users, their home directory is \texttt{~/username} while Windows (Vista onwards) is \lstinline!C:\Users\username!\footnote{If you're not sure where to put \texttt{indentconfig.yaml}, don't worry \texttt{latexindent.pl} will tell you in the log file exactly where to put it assuming it doesn't exist already.} \Cref{lst:indentconfig} shows a sample \texttt{indentconfig.yaml} file. \cmhlistingsfromfile[style=yaml-LST]{demonstrations/indent-config.yaml}[yaml-TCB]{\texttt{indentconfig.yaml} (sample)}{lst:indentconfig} Note that the \texttt{.yaml} files you specify in \texttt{indentconfig.yaml} will be loaded in the order in which you write them. Each file doesn't have to have every switch from \texttt{defaultSettings.yaml}; in fact, I recommend that you only keep the switches that you want to \emph{change} in these settings files. To get started with your own settings file, you might like to save a copy of \texttt{defaultSettings.yaml} in another directory and call it, for example, \texttt{mysettings.yaml}. Once you have added the path to \texttt{indentconfig.yaml} you can change the switches and add more code-block names to it as you see fit -- have a look at \cref{lst:mysettings} for an example that uses four tabs for the default indent, adds the \texttt{tabbing} environment/command to the list of environments that contains alignment delimiters; you might also like to refer to the many YAML files detailed throughout the rest of this documentation. \index{indentation!defaultIndent using YAML file} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/tabbing.yaml}[yaml-TCB]{\texttt{mysettings.yaml} (example)}{lst:mysettings} You can make sure that your settings are loaded by checking \texttt{indent.log} for details -- if you have specified a path that \texttt{latexindent.pl} doesn't recognise then you'll get a warning, otherwise you'll get confirmation that \texttt{latexindent.pl} has read your settings file \footnote{Windows users may find that they have to end \texttt{.yaml} files with a blank line}. \index{warning!editing YAML files} \begin{warning} When editing \texttt{.yaml} files it is \emph{extremely} important to remember how sensitive they are to spaces. I highly recommend copying and pasting from \texttt{defaultSettings.yaml} when you create your first \texttt{whatevernameyoulike.yaml} file. If \texttt{latexindent.pl} can not read your \texttt{.yaml} file it will tell you so in \texttt{indent.log}. \end{warning} As of \announce*{2024-04-28}{paths within local YAML settings} you can specify the \texttt{paths} field from \cref{lst:indentconfig} within any of your \texttt{latexindent.yaml} and friends settings files. This can lead to creative nesting of configuration files; a demonstration is given in \vref{sec:appendix:paths}. \subsection{localSettings.yaml and friends}\label{sec:localsettings} The \texttt{-l} switch tells \texttt{latexindent.pl} to look for \texttt{localSettings.yaml} and/or friends in the \emph{same directory} as \texttt{myfile.tex}. For% \announce{2021-03-14}*{-l switch: localSettings and friends} example, if you use the following command \index{switches!-l demonstration} \begin{commandshell} latexindent.pl -l myfile.tex \end{commandshell} then \texttt{latexindent.pl} will search for and then, assuming they exist, load each of the following files in the following order: \begin{enumerate} \item localSettings.yaml \item latexindent.yaml \item .localSettings.yaml \item .latexindent.yaml \end{enumerate} These files will be assumed to be in the same directory as \texttt{myfile.tex}, or otherwise in the current working directory. You do not need to have all of the above files, usually just one will be sufficient. In what follows, whenever we refer to \texttt{localSettings.yaml} it is assumed that it can mean any of the four named options listed above. If you'd prefer to name your \texttt{localSettings.yaml} file something different, (say, \texttt{mysettings.yaml} as in \cref{lst:mysettings}) then you can call \texttt{latexindent.pl} using, for example, \begin{commandshell} latexindent.pl -l=mysettings.yaml myfile.tex \end{commandshell} Any settings file(s) specified using the \texttt{-l} switch will be read \emph{after} \texttt{defaultSettings.yaml} and, assuming they exist, any user setting files specified in \texttt{indentconfig.yaml}. Your settings file can contain any switches that you'd like to change; a sample is shown in \cref{lst:localSettings}, and you'll find plenty of further examples throughout this manual. \index{verbatim!verbatimEnvironments demonstration (-l switch)} \begin{yaml}{\texttt{localSettings.yaml} (example)}{lst:localSettings} # verbatim environments - environments specified # here will not be changed at all! verbatimEnvironments: cmhenvironment: 0 myenv: 1 \end{yaml} You can make sure that your settings file has been loaded by checking \texttt{indent.log} for details; if it can not be read then you receive a warning, otherwise you'll get confirmation that \texttt{latexindent.pl} has read your settings file. \subsection{The -y|yaml switch}\label{sec:yamlswitch} You% \announce{2017-08-21}{demonstration of the -y switch} may use the \texttt{-y} switch to load your settings; for example, if you wished to specify the settings from \cref{lst:localSettings} using the \texttt{-y} switch, then you could use the following command: \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. If you wish to specify any regex-based settings using the \texttt{-y} switch, \index{regular expressions!using -y switch} it is important not to use quotes surrounding the regex; for example, with reference to the `one sentence per line' feature (\vref{sec:onesentenceperline}) and the listings within \vref{lst:sentencesEndWith}, the following settings give the option to have sentences end with a semicolon \index{switches!-y demonstration} \begin{commandshell} latexindent.pl -m --yaml='modifyLineBreaks:oneSentencePerLine:sentencesEndWith:other:\;' \end{commandshell} Note that the \texttt{paths} settings (see \vref{sec:appendix:paths}) can \emph{not} be specified using the \texttt{-y} switch. \subsection{Settings load order}\label{sec:loadorder} \texttt{latexindent.pl} loads the settings files in the following order: \index{switches!-l in relation to other settings} \begin{enumerate} \item \texttt{defaultSettings.yaml} is always loaded, and can not be renamed; \item \texttt{anyUserSettings.yaml} and any other arbitrarily-named files specified in \texttt{indentconfig.yaml}; \item \texttt{localSettings.yaml} but only if found in the same directory as \texttt{myfile.tex} and called with \texttt{-l} switch; this file can be renamed, provided that the call to \texttt{latexindent.pl} is adjusted accordingly (see \cref{sec:localsettings}). You may specify both relative and absolute% \announce{2017-08-21}*{-l absolute paths} paths to other YAML files using the \texttt{-l} switch, separating multiple files using commas; \item any settings \announce{2017-08-21}{-y switch load order} specified in the \texttt{-y} switch.% \end{enumerate} A visual representation of this is given in \cref{fig:loadorder}. \begin{figure}[!htb] \centering \input{figure-schematic} \caption{Schematic of the load order described in \cref{sec:loadorder}; solid lines represent mandatory files, dotted lines represent optional files. \texttt{indentconfig.yaml} can contain as many files as you like. The files will be loaded in order; if you specify settings for the same field in more than one file, the most recent takes priority. } \label{fig:loadorder} \end{figure} % arara: pdflatex: { files: [latexindent]} \section{defaultSettings.yaml}\label{sec:defuseloc} \texttt{latexindent.pl} loads its settings from \texttt{defaultSettings.yaml}. The idea is to separate the behaviour of the script from the internal working -- this is very similar to the way that we separate content from form when writing our documents in \LaTeX. If you look in \texttt{defaultSettings.yaml} you'll find the switches that govern the behaviour of \texttt{latexindent.pl}. If you're not sure where \texttt{defaultSettings.yaml} resides on your computer, don't worry as \texttt{indent.log} will tell you where to find it. \texttt{defaultSettings.yaml} is commented, but here is a description of what each switch is designed to do. The default value is given in each case; whenever you see \emph{integer} in \emph{this} section, assume that it must be greater than or equal to \texttt{0} unless otherwise stated. For most of the settings in \texttt{defaultSettings.yaml} that are specified as integers, then we understand \texttt{0} to represent `off' and \texttt{1} to represent `on'. For fields that allow values other than \texttt{0} or \texttt{1}, it is hoped that the specific context and associated commentary should make it clear which values are allowed. \yamltitle{fileExtensionPreference}*{fields} \texttt{latexindent.pl} can be called to 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. \cmhlistingsfromfile[style=fileExtensionPreference]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{fileExtensionPreference}}{lst:fileExtensionPreference} Calling \texttt{latexindent.pl myfile} with the (default) settings specified in \cref{lst:fileExtensionPreference} means that the script will first look for \texttt{myfile.tex}, then \texttt{myfile.sty}, \texttt{myfile.cls}, and finally \texttt{myfile.bib} in order\footnote{Throughout this manual, listings shown with line numbers represent code taken directly from \texttt{defaultSettings.yaml}.}. \index{backup files!extension settings} \subsection{Backup and log file preferences} \yamltitle{backupExtension}*{extension name} If you call \texttt{latexindent.pl} with the \texttt{-w} switch (to overwrite \texttt{myfile.tex}) then it will create a backup file before doing any indentation; the default extension is \texttt{.bak}, so, for example, \texttt{myfile.bak0} would be created when calling \texttt{latexindent.pl myfile.tex} for the first time. By default, every time you subsequently call \texttt{latexindent.pl} with the \texttt{-w} to act upon \texttt{myfile.tex}, it will create successive back up files: \texttt{myfile.bak1}, \texttt{myfile.bak2}, etc. \yamltitle{onlyOneBackUp}*{integer} \label{page:onlyonebackup} \index{backup files!number of backup files} If you don't want a backup for every time that you call \texttt{latexindent.pl} (so you don't want \texttt{myfile.bak1}, \texttt{myfile.bak2}, etc) and you simply want \texttt{myfile.bak} (or whatever you chose \texttt{backupExtension} to be) then change \texttt{onlyOneBackUp} to \texttt{1}; the default value of \texttt{onlyOneBackUp} is \texttt{0}. \index{backup files!maximum number of backup files} \index{backup files!number of backup files} \yamltitle{maxNumberOfBackUps}*{integer} Some users may only want a finite number of backup files, say at most $3$, in which case, they can change this switch. The smallest value of \texttt{maxNumberOfBackUps} is $0$ which will \emph{not} prevent backup files being made; in this case, the behaviour will be dictated entirely by \texttt{onlyOneBackUp}. The default value of \texttt{maxNumberOfBackUps} is \texttt{0}. \yamltitle{cycleThroughBackUps}*{integer} \index{backup files!cycle through} Some users may wish to cycle through backup files, by deleting the oldest backup file and keeping only the most recent; for example, with \texttt{maxNumberOfBackUps: 4}, and \texttt{cycleThroughBackUps} set to \texttt{1} then the \texttt{copy} procedure given below would be obeyed. \begin{commandshell} copy myfile.bak1 to myfile.bak0 copy myfile.bak2 to myfile.bak1 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} \texttt{latexindent.pl} writes information to \texttt{indent.log}, some of which can be customized by changing \texttt{logFilePreferences}; see \cref{lst:logFilePreferences}. If you load your own user settings (see \vref{sec:indentconfig}) then \texttt{latexindent.pl} will detail them in \texttt{indent.log}; you can choose not to have the details logged by switching \texttt{showEveryYamlRead} to \texttt{0}. Once all of your settings have been loaded, you can see the amalgamated settings in the log file by switching \texttt{showAmalgamatedSettings} to \texttt{1}, if you wish. \cmhlistingsfromfile[style=logFilePreferences,]{../defaultSettings.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{logFilePreferences}}{lst:logFilePreferences} When \announce{2018-01-13}{showDecorationStartCodeBlockTrace feature for log file} either of the \texttt{trace} modes (see \cpageref{page:traceswitch}) are active, you will receive detailed information in \texttt{indent.log}. You can specify character strings to appear before and after the notification of a found code block using, respectively, \texttt{showDecorationStartCodeBlockTrace} and \texttt{showDecorationFinishCodeBlockTrace}. A demonstration is given in \vref{app:logfile-demo}.% The log file will end with the characters given in \texttt{endLogFileWith}, and will report the \texttt{GitHub} address of \texttt{latexindent.pl} to the log file if \texttt{showGitHubInfoFooter} is set to \texttt{1}. Note: \texttt{latexindent.pl} no longer uses the \texttt{log4perl} module to handle the creation of the logfile. \announce{2021-03-14}*{no longer using log4perl}% Some of the options \announce{2021-06-19}*{logFilePreferences updated to include Dumper options} for Perl's \texttt{Dumper} module can be specified in \cref{lst:logFilePreferences}; see \cite{dumper} and \cite{dumperdemo} for more information. These options will mostly be helpful for those calling \texttt{latexindent.pl} with the \texttt{-tt} option described in \cref{sec:commandline}.% \subsection{Verbatim code blocks} \yamltitle{verbatimEnvironments}*{fields} A field that contains a list of environments that you would like left completely alone -- no indentation will be performed on environments that you have specified in this field, see \cref{lst:verbatimEnvironments}. \index{verbatim!environments} \index{verbatim!commands} \begin{cmhtcbraster}[raster column skip=.1\linewidth] \cmhlistingsfromfile[style=verbatimEnvironments]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{verbatimEnvironments}}{lst:verbatimEnvironments} \cmhlistingsfromfile[style=verbatimCommands]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{verbatimCommands}}{lst:verbatimCommands} \end{cmhtcbraster} Note that if you put an environment in \texttt{verbatimEnvironments} and in other fields such as \texttt{lookForAlignDelims} or \texttt{noAdditionalIndent} then \texttt{latexindent.pl} will \emph{always} prioritize \texttt{verbatimEnvironments}. You can, optionally, specify \announce{2021-10-30}{verbatim name feature} the \texttt{verbatim} field using the \texttt{name} field which takes a regular expression as its argument; thank you to \cite{XuehaiPan} for contributing this feature. \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. \begin{cmhtcbraster}[raster column skip=.1\linewidth] \cmhlistingsfromfile[style=yaml-LST]{demonstrations/nameAsRegex1.yaml}[yaml-TCB]{\texttt{nameAsRegex1.yaml}}{lst:nameAsRegex1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/nameAsRegex2.yaml}[yaml-TCB]{\texttt{nameAsRegex2.yaml}}{lst:nameAsRegex2} \end{cmhtcbraster} With reference to \cref{lst:nameAsRegex2}: \begin{itemize} \item the \texttt{name} field as specified here means \emph{any word followed by the word code, optionally followed by *}; \item we have used \texttt{nameAsRegex} to identify this field, but you can use any description you like; \item the \texttt{lookForThis} field is optional, and can take the values 0 (off) or 1 (on); by default, it is assumed to be 1 (on). \end{itemize} \end{example} \yamltitle{verbatimCommands}*{fields} A field that contains a list of commands that are verbatim commands, for example \lstinline|\lstinline|; any commands populated in this field are protected from line breaking routines (only relevant if the \texttt{-m} is active, see \vref{sec:modifylinebreaks}). With reference to \cref{lst:verbatimCommands}, by default \texttt{latexindent.pl} looks for \lstinline|\verb| immediately followed by another character, and then it takes the body as anything up to the next occurrence of the character; this means that, for example, \lstinline|\verb!x+3!| is treated as a \texttt{verbatimCommands}. You can, optionally, specify \announce{2021-10-30}{verbatimCommands name feature} the \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. \begin{cmhtcbraster}[raster column skip=.1\linewidth] \cmhlistingsfromfile[style=yaml-LST]{demonstrations/nameAsRegex3.yaml}[yaml-TCB]{\texttt{nameAsRegex3.yaml}}{lst:nameAsRegex3} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/nameAsRegex4.yaml}[yaml-TCB]{\texttt{nameAsRegex4.yaml}}{lst:nameAsRegex4} \end{cmhtcbraster} With reference to \cref{lst:nameAsRegex4}: \begin{itemize} \item the \texttt{name} field as specified here means \emph{any word followed by the word inline}; \item we have used \texttt{nameAsRegex} to identify this field, but you can use any description you like; \item the \texttt{lookForThis} field is optional, and can take the values 0 (off) or 1 (on); by default, it is assumed to be 1 (on). \end{itemize} \end{example} \yamltitle{noIndentBlock}*{fields} If you have a block of code that you don't want \texttt{latexindent.pl} to touch (even if \index{verbatim!noIndentBlock} it is \emph{not} a verbatim-like environment) then you can wrap it in an environment from \texttt{noIndentBlock}; you can use any name you like for this, provided you populate it as demonstrate in \cref{lst:noIndentBlock}. \cmhlistingsfromfile[style=noIndentBlock]{../defaultSettings.yaml}[width=.4\linewidth,before=\centering,yaml-TCB]{\texttt{noIndentBlock}}{lst:noIndentBlock} Of course, you don't want to have to specify these as null environments in your code, so you use them with a comment symbol, \lstinline!%!, followed by as many spaces (possibly none) as you like; see \cref{lst:noIndentBlockdemo} for example. \cmhlistingsfromfile{demonstrations/noindentblock.tex}{\texttt{noIndentBlock.tex}}{lst:noIndentBlockdemo} Important note: it is assumed that the \texttt{noindent} block statements specified in this way appear on their own line. \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} The settings given in \cref{lst:noindent1,lst:noindent2} are equivalent: \begin{cmhtcbraster}[raster columns=3, raster left skip=-3.5cm, raster right skip=-2cm, raster column skip=.03\linewidth] \cmhlistingsfromfile[style=yaml-LST]{demonstrations/noindent1.yaml}[yaml-TCB]{\texttt{noindent1.yaml}}{lst:noindent1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/noindent2.yaml}[yaml-TCB]{\texttt{noindent2.yaml}}{lst:noindent2} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/noindent3.yaml}[yaml-TCB]{\texttt{noindent3.yaml}}{lst:noindent3} \end{cmhtcbraster} Upon running the commands \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 \cref{lst:noindent1}. In this context, we interpret \lstinline!.*?! in words as \emph{the fewest number of characters (possibly none) until the `end' field is reached}. The \texttt{lookForThis} field is optional, and can take the values 0 (off) or 1 (on); by default, it is assumed to be 1 (on). \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 \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. \begin{widepage} \begin{cmhtcbraster}[raster column skip=.1\linewidth] \cmhlistingsfromfile[style=yaml-LST]{demonstrations/nameAsRegex5.yaml}[yaml-TCB]{\texttt{nameAsRegex5.yaml}}{lst:nameAsRegex5} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/nameAsRegex6.yaml}[yaml-TCB]{\texttt{nameAsRegex6.yaml}}{lst:nameAsRegex6} \end{cmhtcbraster} \end{widepage} With reference to \cref{lst:nameAsRegex6}: \begin{itemize} \item the \texttt{name} field as specified here means \emph{any word followed by the word noindent, optionally followed by *}; \item we have used \texttt{nameAsRegex} to identify this field, but you can use any description you like; \item the \texttt{lookForThis} field is optional, and can take the values 0 (off) or 1 (on); by default, it is assumed to be 1 (on). \end{itemize} \end{example} \subsection{filecontents and preamble}\label{subsec:filecontents:preamble} \yamltitle{fileContentsEnvironments}*{field} Before \texttt{latexindent.pl} determines the difference between preamble (if any) and the main document, it first searches for any of the environments specified in \texttt{fileContentsEnvironments}, see \cref{lst:fileContentsEnvironments}. The behaviour of \texttt{latexindent.pl} on these environments is determined by their location (preamble or not), and the value \texttt{indentPreamble}, discussed next. \cmhlistingsfromfile[style=fileContentsEnvironments]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{fileContentsEnvironments}}{lst:fileContentsEnvironments} \yamltitle{indentPreamble}{0|1} The preamble of a document can sometimes contain some trickier code for \texttt{latexindent.pl} to operate upon. By default, \texttt{latexindent.pl} won't try to operate on the preamble (as \texttt{indentPreamble} is set to \texttt{0}, by default), but if you'd like \texttt{latexindent.pl} to try then change \texttt{indentPreamble} to \texttt{1}. \yamltitle{lookForPreamble}*{fields} Not all files contain preamble; for example, \texttt{sty}, \texttt{cls} and \texttt{bib} files typically do \emph{not}. Referencing \cref{lst:lookForPreamble}, if you set, for example, \texttt{.tex} to \texttt{0}, then regardless of the setting of the value of \texttt{indentPreamble}, preamble will not be assumed when operating upon \texttt{.tex} files. \cmhlistingsfromfile[style=lookForPreamble]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{lookForPreamble}{lst:lookForPreamble} \yamltitle{preambleCommandsBeforeEnvironments}{0|1} Assuming that \texttt{latexindent.pl} is asked to operate upon the preamble of a document, when this switch is set to \texttt{0} then environment code blocks will be sought first, and then command code blocks. When this switch is set to \texttt{1}, commands will be sought first. The example that first motivated this switch contained the code given in \cref{lst:motivatepreambleCommandsBeforeEnvironments}. \begin{cmhlistings}{Motivating \texttt{preambleCommandsBeforeEnvironments}}{lst:motivatepreambleCommandsBeforeEnvironments} ... preheadhook={\begin{mdframed}[style=myframedstyle]}, postfoothook=\end{mdframed}, ... \end{cmhlistings} \index{indentation!defaultIndent description} \subsection{Indentation and horizontal space}\label{subsec:indentation:and:horizontal:space} \yamltitle{defaultIndent}*{horizontal space} This is the default indentation used in the absence of other details for the code block with which we are working. The default value is \lstinline!\t! which means a tab; we will explore customisation beyond \texttt{defaultIndent} in \vref{sec:noadd-indent-rules}. If you're interested in experimenting with \texttt{latexindent.pl} then you can \emph{remove} all indentation by setting \texttt{defaultIndent: ""}. \yamltitle{removeTrailingWhitespace}*{fields}\label{yaml:removeTrailingWhitespace} Trailing white space can be removed both \emph{before} and \emph{after} processing the document, as detailed in \cref{lst:removeTrailingWhitespace}; each of the fields can take the values \texttt{0} or \texttt{1}. See \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{cmhtcbraster} \cmhlistingsfromfile[style=removeTrailingWhitespace]{../defaultSettings.yaml}[before=\centering,yaml-TCB]{removeTrailingWhitespace}{lst:removeTrailingWhitespace} \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} \texttt{latexindent.pl} will set both \texttt{beforeProcessing} and \texttt{afterProcessing} to the value you specify; see \cref{lst:removeTrailingWhitespace-alt}.% \subsection{Aligning at delimiters}\label{subsec:align-at-delimiters} \yamltitle{lookForAlignDelims}*{fields} This contains a list of code blocks that are operated upon in a special way by \texttt{latexindent.pl} (see \cref{lst:aligndelims:basic}). In fact, the fields in \texttt{lookForAlignDelims} can actually take two different forms: the \emph{basic} version is shown in \cref{lst:aligndelims:basic} and the \emph{advanced} version in \cref{lst:aligndelims:advanced}; we will discuss each in turn. \index{delimiters!advanced settings of lookForAlignDelims} \begin{yaml}[numbers=none]{\texttt{lookForAlignDelims} (basic)}[width=.8\linewidth,before=\centering]{lst:aligndelims:basic} lookForAlignDelims: tabular: 1 tabularx: 1 longtable: 1 array: 1 matrix: 1 ... \end{yaml} Specifying code blocks in this field instructs \texttt{latexindent.pl} to try and align each column by its alignment delimiters. It does have some limitations (discussed further in \cref{sec:knownlimitations}), but in many cases it will produce results such as those in \cref{lst:tabularbefore:basic,lst:tabularafter:basic}; running the command \begin{commandshell} latexindent.pl tabular1.tex \end{commandshell} gives the output given in \cref{lst:tabularafter:basic}. \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/tabular1.tex}{\texttt{tabular1.tex}}{lst:tabularbefore:basic} \cmhlistingsfromfile{demonstrations/tabular1-default.tex}{\texttt{tabular1.tex} default output}{lst:tabularafter:basic} \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 of the environment, you could wrap them in something from \texttt{noIndentBlock} (see \vref{lst:noIndentBlock}). If, for example, you wish to remove the alignment of the \lstinline!\\! within a delimiter-aligned block, then the advanced form of \texttt{lookForAlignDelims} shown in \cref{lst:aligndelims:advanced} is for you. \index{regular expressions!delimiterRegEx} \index{regular expressions!ampersand alignment} \index{delimiters!default settings of lookForAlignDelims} \index{delimiters!ampersand \&} \index{delimiters!advanced settings} \index{delimiters!lookForAlignDelims} \cmhlistingsfromfile[style=lookForAlignDelims]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{lookForAlignDelims} (advanced)}{lst:aligndelims:advanced} Note that you can use a mixture of the basic and advanced form: in \cref{lst:aligndelims:advanced} \texttt{tabular} and \texttt{tabularx} are advanced and \texttt{longtable} is basic. When using the advanced form, each field should receive at least 1 sub-field, and \emph{can} (but does not have to) receive any of the following fields: \begin{itemize} \item \texttt{delims}: binary switch (0 or 1) equivalent to simply specifying, for example, \texttt{tabular: 1} in the basic version shown in \cref{lst:aligndelims:basic}. If \texttt{delims} is set to \texttt{0} then the align at ampersand routine will not be called for this code block (default: 1); \item \texttt{alignDoubleBackSlash}: binary switch (0 or 1) to determine if \lstinline!\\! should be aligned (default: 1); \item \texttt{spacesBeforeDoubleBackSlash}: optionally,% \announce{2018-01-13}*{update to spacesBeforeDoubleBackSlash in ampersand alignment} specifies the number (integer $\geq$ 0) of spaces to be inserted before \lstinline!\\! (default: 1); %\footnote{Previously this only activated if \texttt{alignDoubleBackSlash} was set to \texttt{0}.} \item \announce{2017-06-19}{multiColumnGrouping} \texttt{multiColumnGrouping}: binary switch (0 or 1) that details if \texttt{latexindent.pl} should group columns above and below a \lstinline!\multicolumn! command (default: 0); \item \announce{2017-06-19}{alignRowsWithoutMaxDelims} \texttt{alignRowsWithoutMaxDelims}: binary switch (0 or 1) that details if rows that do not contain the maximum number of delimiters should be formatted so as to have the ampersands aligned (default: 1); \item \announce{2018-01-13}{spacesBeforeAmpersand in ampersand alignment}\texttt{spacesBeforeAmpersand}: optionally specifies the number (integer $\geq$ 0) of spaces to be placed \emph{before} ampersands (default: 1); \item \announce{2018-01-13}{spacesAfterAmpersand in ampersand alignment}\texttt{spacesAfterAmpersand}: optionally specifies the number (integer $\geq$ 0) of spaces to be placed \emph{After} ampersands (default: 1); \item \announce{2018-01-13}{justification of cells in ampersand alignment}\texttt{justification}: optionally specifies the justification of each cell as either \emph{left} or \emph{right} (default: left); \item \announce{2020-03-21}{align final double backslash}{alignFinalDoubleBackSlash} optionally specifies if the \emph{final} double backslash should be used for alignment (default: 0); \item \announce{2020-03-21}{don't measure feature}{dontMeasure} optionally specifies if user-specified cells, rows or the largest entries should \emph{not} be measured (default: 0); \item \announce{2020-03-21}{delimiter RegEx feature}{delimiterRegEx} optionally specifies the pattern matching to be used for the alignment delimiter (default: \lstinline* '(?<!\\)(&)'*); \item \announce{2020-03-21}{delimiter justification}{delimiterJustification} optionally specifies the justification for the alignment delimiters (default: left); note that this feature is only useful if you have delimiters of different lengths in the same column, discussed in \cref{sec:delimiter-reg-ex}; \item \announce{2021-12-13}{lookForChildCodeBlocks feature}{lookForChildCodeBlocks} optionally instructs \texttt{latexindent.pl} to search for child code blocks or not (default: 1), discussed in \cref{sec:lookForChildCodeBlocks}; \item \announce{2023-05-01}{alignContentAfterDoubleBackSlash feature} alignContentAfterDoubleBackSlash optionally instructs \texttt{latexindent.pl} to align content \emph{after} double back slash (default: 0), discussed in \cref{sec:alignContentAfterDoubleBackSlash}; \item \announce{2023-05-01}{spacesAfterDoubleBackSlash feature} spacesAfterDoubleBackSlash optionally specifies the number (integer $\geq$ 0) of spaces to be placed \emph{after} the double back slash \emph{when alignContentAfterDoubleBackSlash is active}; demonstrated in \cref{sec:alignContentAfterDoubleBackSlash}. \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 \texttt{alignFinalDoubleBackSlash} in \cref{lst:tabular4}; the \texttt{dontMeasure} feature will be described in \cref{sec:dontMeasure}, and \texttt{delimiterRegEx} in \cref{sec:delimiter-reg-ex}. \cmhlistingsfromfile{demonstrations/tabular2.tex}{\texttt{tabular2.tex}}{lst:tabular2} \begin{minipage}{.45\textwidth} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/tabular2.yaml}[yaml-TCB]{\texttt{tabular2.yaml}}{lst:tabular2YAML} \end{minipage}% \hfill \begin{minipage}{.48\textwidth} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/tabular3.yaml}[yaml-TCB]{\texttt{tabular3.yaml}}{lst:tabular3YAML} \end{minipage}% \begin{minipage}{.45\textwidth} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/tabular4.yaml}[yaml-TCB]{\texttt{tabular4.yaml}}{lst:tabular4YAML} \end{minipage}% \hfill \begin{minipage}{.48\textwidth} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/tabular5.yaml}[yaml-TCB]{\texttt{tabular5.yaml}}{lst:tabular5YAML} \end{minipage}% \begin{minipage}{.45\textwidth} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/tabular6.yaml}[yaml-TCB]{\texttt{tabular6.yaml}}{lst:tabular6YAML} \end{minipage}% \hfill \begin{minipage}{.48\textwidth} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/tabular7.yaml}[yaml-TCB]{\texttt{tabular7.yaml}}{lst:tabular7YAML} \end{minipage}% \begin{minipage}{.48\textwidth} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/tabular8.yaml}[yaml-TCB]{\texttt{tabular8.yaml}}{lst:tabular8YAML} \end{minipage}% 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 latexindent.pl tabular2.tex -l tabular3.yaml latexindent.pl tabular2.tex -l tabular2.yaml,tabular4.yaml latexindent.pl tabular2.tex -l tabular2.yaml,tabular5.yaml latexindent.pl tabular2.tex -l tabular2.yaml,tabular6.yaml 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}. \begin{widepage} \cmhlistingsfromfile{demonstrations/tabular2-default.tex}{\texttt{tabular2.tex} default output}{lst:tabular2-default} \cmhlistingsfromfile{demonstrations/tabular2-mod2.tex}{\texttt{tabular2.tex} using \cref{lst:tabular2YAML}}{lst:tabular2-mod2} \cmhlistingsfromfile{demonstrations/tabular2-mod3.tex}{\texttt{tabular2.tex} using \cref{lst:tabular3YAML}}{lst:tabular2-mod3} \cmhlistingsfromfile{demonstrations/tabular2-mod4.tex}{\texttt{tabular2.tex} using \cref{lst:tabular2YAML,lst:tabular4YAML}}{lst:tabular2-mod4} \cmhlistingsfromfile{demonstrations/tabular2-mod5.tex}{\texttt{tabular2.tex} using \cref{lst:tabular2YAML,lst:tabular5YAML}}{lst:tabular2-mod5} \cmhlistingsfromfile{demonstrations/tabular2-mod6.tex}{\texttt{tabular2.tex} using \cref{lst:tabular2YAML,lst:tabular6YAML}}{lst:tabular2-mod6} \cmhlistingsfromfile{demonstrations/tabular2-mod7.tex}{\texttt{tabular2.tex} using \cref{lst:tabular2YAML,lst:tabular7YAML}}{lst:tabular2-mod7} \cmhlistingsfromfile{demonstrations/tabular2-mod8.tex}{\texttt{tabular2.tex} using \cref{lst:tabular2YAML,lst:tabular8YAML}}{lst:tabular2-mod8} \end{widepage} Notice in particular: \begin{itemize} \item in both \cref{lst:tabular2-default,lst:tabular2-mod2} all rows have been aligned at the ampersand, even those that do not contain the maximum number of ampersands (3 ampersands, in this case); \item in \cref{lst:tabular2-default} the columns have been aligned at the ampersand; \item in \cref{lst:tabular2-mod2} the \lstinline!\multicolumn! command has grouped the $2$ columns beneath \emph{and} above it, because \texttt{multiColumnGrouping} is set to $1$ in \cref{lst:tabular2YAML}; \item in \cref{lst:tabular2-mod3} rows~3 and~6 have \emph{not} been aligned at the ampersand, because \texttt{alignRowsWithoutMaxDelims} has been to set to $0$ in \cref{lst:tabular3YAML}; however, the \lstinline!\\! \emph{have} still been aligned; \item in \cref{lst:tabular2-mod4} the columns beneath and above the \lstinline!\multicolumn! commands have been grouped (because \texttt{multiColumnGrouping} is set to $1$), and there are at least $4$ spaces \emph{before} each aligned ampersand because \texttt{spacesBeforeAmpersand} is set to $4$; \item in \cref{lst:tabular2-mod5} the columns beneath and above the \lstinline!\multicolumn! commands have been grouped (because \texttt{multiColumnGrouping} is set to $1$), and there are at least $4$ spaces \emph{after} each aligned ampersand because \texttt{spacesAfterAmpersand} is set to $4$; \item in \cref{lst:tabular2-mod6} the \lstinline!\\! have \emph{not} been aligned, because \texttt{alignDoubleBackSlash} is set to \texttt{0}, otherwise the output is the same as \cref{lst:tabular2-mod2}; \item in \cref{lst:tabular2-mod7} the \lstinline!\\! \emph{have} been aligned, and because \texttt{spacesBeforeDoubleBackSlash} is set to \texttt{0}, there are no spaces ahead of them; the output is otherwise the same as \cref{lst:tabular2-mod2}; \item in \cref{lst:tabular2-mod8} the cells have been \emph{right}-justified; note that cells above and below the \lstinline!\multicol! statements have still been group correctly, because of the settings in \cref{lst:tabular2YAML}. \end{itemize} \end{example} \subsubsection{lookForAlignDelims: spacesBeforeAmpersand} The \texttt{spacesBeforeAmpersand} \announce{2021-06-19}*{spacesBeforeAmpersand leading blank column upgrade} can be specified in a few different ways. The \emph{basic} form is demonstrated in \cref{lst:tabular4YAML}, but we can customise the behaviour further by specifying if we would like this value to change if it encounters a \emph{leading blank 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} \cmhlistingsfromfile{demonstrations/aligned1.tex}{\texttt{aligned1.tex}}{lst:aligned1} \cmhlistingsfromfile{demonstrations/aligned1-default.tex}{\texttt{aligned1-default.tex}}{lst:aligned1-default} \end{cmhtcbraster} The settings in \crefrange{lst:sba1}{lst:sba4} are all equivlanent; we have used the not-yet discussed \texttt{noAdditionalIndent} field (see \vref{sec:noadd-indent-rules}) which will assist in the demonstration in what follows. \begin{cmhtcbraster}[raster columns=2, ] \cmhlistingsfromfile[style=yaml-LST]{demonstrations/sba1.yaml}[yaml-TCB]{\texttt{sba1.yaml}}{lst:sba1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/sba2.yaml}[yaml-TCB]{\texttt{sba2.yaml}}{lst:sba2} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/sba3.yaml}[yaml-TCB]{\texttt{sba3.yaml}}{lst:sba3} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/sba4.yaml}[yaml-TCB]{\texttt{sba4.yaml}}{lst:sba4} \end{cmhtcbraster} Upon running the following commands \begin{commandshell} latexindent.pl aligned1.tex -l sba1.yaml latexindent.pl aligned1.tex -l sba2.yaml 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. \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/aligned1-mod1.tex}{\texttt{aligned1-mod1.tex}}{lst:aligned1-mod1} \end{cmhtcbraster} We note in particular: \begin{itemize} \item \cref{lst:sba1} demonstrates the \emph{basic} form for \texttt{lookForAlignDelims}; in this case, the default values are specified as in \vref{lst:aligndelims:advanced}; \item \cref{lst:sba2} demonstrates the \emph{advanced} form for \texttt{lookForAlignDelims} and specified \texttt{spacesBeforeAmpersand}. The default value is \texttt{1}; \item \cref{lst:sba3} demonstrates the new \emph{advanced} way to specify \texttt{spacesBeforeAmpersand}, and for us to set the \texttt{default} value that sets the number of spaces before ampersands which are \emph{not} in leading blank columns. The default value is \texttt{1}. We note that \texttt{leadingBlankColumn} has not been specified in \cref{lst:sba3}, and it will inherit the value from \texttt{default}; \item \cref{lst:sba4} demonstrates spaces to be used before amperands for \emph{leading blank columns}. We note that \emph{default} has not been specified, and it will be set to \texttt{1} by 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. \begin{cmhtcbraster} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/sba5.yaml}[yaml-TCB]{\texttt{sba5.yaml}}{lst:sba5} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/sba6.yaml}[yaml-TCB]{\texttt{sba6.yaml}}{lst:sba6} \end{cmhtcbraster} Upon running \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}. We can demonstrated this feature further using the settings in \cref{lst:sba7} which give the output in \cref{lst:aligned1-mod7}. \begin{cmhtcbraster}[raster columns=3, raster left skip=-3.75cm, raster right skip=-2cm,] \cmhlistingsfromfile{demonstrations/aligned1-mod5.tex}{\texttt{aligned1-mod5.tex}}{lst:aligned1-mod5} \cmhlistingsfromfile{demonstrations/aligned1-mod7.tex}{\texttt{aligned1.tex} using \cref{lst:sba7}}{lst:aligned1-mod7} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/sba7.yaml}[yaml-TCB]{\texttt{sba7.yaml}}{lst:sba7} \end{cmhtcbraster} \end{example} \subsubsection{lookForAlignDelims: alignFinalDoubleBackSlash} 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}. \begin{cmhtcbraster}[raster columns=3, raster left skip=-3.75cm, raster right skip=-2cm,] \cmhlistingsfromfile{demonstrations/tabular4.tex}{\texttt{tabular4.tex}}{lst:tabular4} \cmhlistingsfromfile{demonstrations/tabular4-default.tex}{\texttt{tabular4-default.tex}}{lst:tabular4-default} \cmhlistingsfromfile{demonstrations/tabular4-FDBS.tex}{\texttt{tabular4-FDBS.tex}}{lst:tabular4-FDBS} \end{cmhtcbraster} We note that in: \begin{itemize} \item \cref{lst:tabular4-default}, by default, the \emph{first} set of double back slashes in the first row of the \texttt{tabular} environment have been used for alignment; \item \cref{lst:tabular4-FDBS}, the \emph{final} set of double backslashes in the first row have been used, because we specified \texttt{alignFinalDoubleBackSlash} as 1. \end{itemize} \end{example} As of Version 3.0, the alignment routine works on mandatory and optional arguments within commands, and also within `special' code blocks (see \texttt{specialBeginEnd} on \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. \begin{cmhtcbraster} \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}!, then you can use the mark up illustrated in \cref{lst:alignmentmarkup}; the default output is shown in \cref{lst:alignmentmarkup-default}. Note that the \lstinline!%*! must be next to each other, but that there can be any number of spaces (possibly none) between the \lstinline!*! and \lstinline!\begin{tabular}!; note also that you may use any environment name that you have specified in \texttt{lookForAlignDelims}. \begin{cmhtcbraster}[raster left skip=-1.5cm,] \cmhlistingsfromfile{demonstrations/align-block.tex}{\texttt{align-block.tex}}{lst:alignmentmarkup} \cmhlistingsfromfile{demonstrations/align-block-default.tex}{\texttt{align-block.tex} default output}{lst:alignmentmarkup-default} \end{cmhtcbraster} With reference to \vref{tab:code-blocks} and the, yet undiscussed, fields of \texttt{noAdditionalIndent} and \texttt{indentRules} (see \vref{sec:noadd-indent-rules}), these comment-marked blocks are considered \texttt{environments}. \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. \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} \end{cmhtcbraster} 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} \cmhlistingsfromfile{demonstrations/tabular-DM-mod1.tex}{\texttt{tabular-DM.tex} using \cref{lst:dontMeasure1}}{lst:tabular-DM-mod1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/dontMeasure1.yaml}[yaml-TCB]{\texttt{dontMeasure1.yaml}}{lst:dontMeasure1} \end{cmhtcbraster} We note that the \emph{largest} column entries have not contributed to the measuring 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} \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/tabular-DM-mod2.tex}{\texttt{tabular-DM.tex} using \cref{lst:dontMeasure2} or \cref{lst:dontMeasure3}}{lst:tabular-DM-mod2} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/dontMeasure2.yaml}[yaml-TCB]{\texttt{dontMeasure2.yaml}}{lst:dontMeasure2} \end{cmhtcbraster} We note that in \cref{lst:dontMeasure2} we have specified entries not to be measured, one entry per line. \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, raster left skip=-3.5cm, raster right skip=-2cm, raster column skip=.03\linewidth] \cmhlistingsfromfile{demonstrations/tabular-DM-mod3.tex}{\texttt{tabular-DM.tex} using \cref{lst:dontMeasure3} or \cref{lst:dontMeasure3}}{lst:tabular-DM-mod3} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/dontMeasure3.yaml}[yaml-TCB]{\texttt{dontMeasure3.yaml}}{lst:dontMeasure3} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/dontMeasure4.yaml}[yaml-TCB]{\texttt{dontMeasure4.yaml}}{lst:dontMeasure4} \end{cmhtcbraster} We note that in: \begin{itemize} \item \cref{lst:dontMeasure3} we have specified entries not to be measured, each one has a \emph{string} in the \texttt{this} field, together with an optional specification of \texttt{applyTo} as \texttt{cell}; \item \cref{lst:dontMeasure4} we have specified entries not to be measured as a \emph{regular expression} using the \texttt{regex} field, together with an optional specification of \texttt{applyTo} as \texttt{cell} field, together with an optional specification of \texttt{applyTo} as \texttt{cell}. \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[style=yaml-LST]{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} \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/tabular-DM-mod6.tex}{\texttt{tabular-DM.tex} using \cref{lst:dontMeasure6}}{lst:tabular-DM-mod6} \cmhlistingsfromfile[style=yaml-LST]{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} The delimiter alignment \announce{2020-03-21}{delimiterRegEx feature} will, by default, align code blocks at the ampersand character. The behaviour is controlled by the \texttt{delimiterRegEx} field within \texttt{lookForAlignDelims}; the default value is \lstinline*'(?<!\\)(&)'*, which can be read as: \emph{an ampersand, as long as it is not immediately preceded by a backslash}. \index{warning!capturing parenthesis for lookForAlignDelims} \index{capturing parenthesis (regex)} \index{regular expressions!capturing parenthesis} \index{delimiters!delimiterRegEx} \index{delimiters!delimiter justification (left or right)}% \begin{warning} Important: note the `capturing' parenthesis in the \lstinline!(&)! which are necessary; 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}. \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/tabbing.tex}{\texttt{tabbing.tex}}{lst:tabbing} \cmhlistingsfromfile{demonstrations/tabbing-default.tex}{\texttt{tabbing.tex} default output}{lst:tabbing-default} \end{cmhtcbraster} 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>} \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/tabbing-mod1.tex}{\texttt{tabbing.tex} using \cref{lst:delimiterRegEx1}}{lst:tabbing-mod1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/delimiterRegEx1.yaml}[yaml-TCB]{\texttt{delimiterRegEx1.yaml}}{lst:delimiterRegEx1} \end{cmhtcbraster} We note that: \begin{itemize} \item in \cref{lst:tabbing-mod1} the code has been aligned, as intended, at both the \lstinline!\=! and \lstinline!\>!; \item in \cref{lst:delimiterRegEx1} we have heeded the warning and captured the expression using grouping parenthesis, specified a backslash using \lstinline!\\! and said that it must be followed by either \lstinline!=! or \lstinline!>!. \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>} \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/tabbing-mod2.tex}{\texttt{tabbing.tex} using \cref{lst:delimiterRegEx2}}{lst:tabbing-mod2} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/delimiterRegEx2.yaml}[yaml-TCB]{\texttt{delimiterRegEx2.yaml}}{lst:delimiterRegEx2} \end{cmhtcbraster} We note that only the \lstinline!\>! have been aligned. \end{example} \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} \cmhlistingsfromfile{demonstrations/tabbing-mod3.tex}{\texttt{tabbing.tex} using \cref{lst:delimiterRegEx3}}{lst:tabbing-mod3} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/delimiterRegEx3.yaml}[yaml-TCB]{\texttt{delimiterRegEx3.yaml}}{lst:delimiterRegEx3} \end{cmhtcbraster} \end{example} \begin{example} It is possible that delimiters specified within \texttt{delimiterRegEx} can be of different lengths. Consider the file in \cref{lst:tabbing1}, and associated YAML in \cref{lst:delimiterRegEx4}. Note that the \cref{lst:delimiterRegEx4} specifies the option for the delimiter to be either \lstinline!#! or \lstinline!\>!, \emph{which are different lengths}. Upon running the command \index{switches!-l demonstration} \index{switches!-o demonstration} \begin{commandshell} latexindent.pl tabbing1.tex -l=delimiterRegEx4.yaml -o=+-mod4 \end{commandshell} we receive the output in \cref{lst:tabbing1-mod4}. \index{regular expressions!delimiter regex at \#} \begin{cmhtcbraster}[raster columns=3, raster left skip=-3.5cm, raster right skip=-2cm, raster column skip=.03\linewidth] \cmhlistingsfromfile{demonstrations/tabbing1.tex}{\texttt{tabbing1.tex}}{lst:tabbing1} \cmhlistingsfromfile{demonstrations/tabbing1-mod4.tex}{\texttt{tabbing1-mod4.tex}}{lst:tabbing1-mod4} \cmhlistingsfromfile[style=yaml-LST]{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>} \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/tabbing1-mod5.tex}{\texttt{tabbing1-mod5.tex}}{lst:tabbing1-mod5} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/delimiterRegEx5.yaml}[yaml-TCB]{\texttt{delimiterRegEx5.yaml}}{lst:delimiterRegEx5} \end{cmhtcbraster} Note that in \cref{lst:tabbing1-mod5} the second set of delimiters have been \emph{right aligned} -- it is quite subtle! \end{example} \subsubsection{lookForAlignDelims: lookForChildCodeBlocks}\label{sec:lookForChildCodeBlocks} There \announce{2021-12-13}{lookForChildCodeBlocks demonstration} may be scenarios in which you would prefer to instruct \texttt{latexindent.pl} \emph{not} to search for child blocks; in which case setting \texttt{lookForChildCodeBlocks} to 0 may be a good way to proceed. \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} \cmhlistingsfromfile{demonstrations/tabular-DM-1-mod1.tex}{\texttt{tabular-DM-1-mod1.tex}}{lst:tabular-DM-1-mod1} \end{cmhtcbraster} 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} \cmhlistingsfromfile{demonstrations/tabular-DM-1-mod1a.tex}{\texttt{tabular-DM-1-mod1a.tex}}{lst:tabular-DM-1-mod1a} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/dontMeasure1a.yaml}[yaml-TCB]{\texttt{dontMeasure1a.yaml}}{lst:dontMeasure1a} \end{cmhtcbraster} \end{example} \subsubsection{lookForAlignDelims: alignContentAfterDoubleBackSlash}\label{sec:alignContentAfterDoubleBackSlash} You can instruct \texttt{latexindent} to align \announce{2023-05-01}{align content after double back slash} content after the double back slash. See also \vref{subsec:dbs}. \begin{example} We consider the file in \cref{lst:tabular5}, and the default output given in \cref{lst:tabular5-default}. \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/tabular5.tex}{\texttt{tabular5.tex}}{lst:tabular5} \cmhlistingsfromfile{demonstrations/tabular5-default.tex}{\texttt{tabular5-default.tex}}{lst:tabular5-default} \end{cmhtcbraster} Using the settings given in \cref{lst:alignContentAfterDBS1} and running \begin{commandshell} latexindent.pl -s tabular5.tex -l alignContentAfterDBS1 -o=+-mod1 \end{commandshell} gives the output in \cref{lst:tabular5-mod1}. \begin{cmhtcbraster}[raster columns=2, raster left skip=-2.5cm, raster column skip=.03\linewidth] \cmhlistingsfromfile{demonstrations/tabular5-mod1.tex}{\texttt{tabular5-mod1.tex}}{lst:tabular5-mod1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/alignContentAfterDBS1.yaml}[yaml-TCB]{\texttt{alignContentAfterDBS1.yaml}}{lst:alignContentAfterDBS1} \end{cmhtcbraster} \end{example} \begin{example} When using the \texttt{alignContentAfterDoubleBackSlash} feature, then you can also specify how many spaces to insert after the double backslash; the default is 1. \announce{2023-05-01}{specify number of spaces after double back slash when aligning content after double back slash} Starting from \cref{lst:tabular5} and using the the settings given in \cref{lst:alignContentAfterDBS2} \begin{commandshell} latexindent.pl -s tabular5.tex -l alignContentAfterDBS2 -o=+-mod2 \end{commandshell} gives the output in \cref{lst:tabular5-mod2}. \begin{cmhtcbraster}[raster columns=2, raster left skip=-2.5cm, raster column skip=.03\linewidth] \cmhlistingsfromfile{demonstrations/tabular5-mod2.tex}{\texttt{tabular5-mod2.tex}}{lst:tabular5-mod2} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/alignContentAfterDBS2.yaml}[yaml-TCB]{\texttt{alignContentAfterDBS2.yaml}}{lst:alignContentAfterDBS2} \end{cmhtcbraster} \end{example} \subsection{Indent after items, specials and headings} \yamltitle{indentAfterItems}*{fields} The environment names specified in \texttt{indentAfterItems} tell \texttt{latexindent.pl} to look for \lstinline!\item! commands; if these switches are set to \texttt{1} then indentation will be performed so as indent the code after each \texttt{item}. A demonstration is given in \cref{lst:itemsbefore,lst:itemsafter} \begin{cmhtcbraster}[raster columns=3, raster left skip=-3.5cm, raster right skip=-2cm, raster column skip=.03\linewidth] \cmhlistingsfromfile[style=indentAfterItems]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{indentAfterItems}}{lst:indentafteritems} \cmhlistingsfromfile{demonstrations/items1.tex}{\texttt{items1.tex}}{lst:itemsbefore} \cmhlistingsfromfile{demonstrations/items1-default.tex}{\texttt{items1.tex} default output}{lst:itemsafter} \end{cmhtcbraster} \yamltitle{itemNames}*{fields} If you have your own \texttt{item} commands (perhaps you prefer to use \texttt{myitem}, for example) then you can put populate them in \texttt{itemNames}. For example, users of the \texttt{exam} document class might like to add \texttt{parts} to \texttt{indentAfterItems} and \texttt{part} to \texttt{itemNames} to their user settings (see \vref{sec:indentconfig} for details of how to configure user settings, and \vref{lst:mysettings} \\ in particular \label{page:examsettings}.) \cmhlistingsfromfile[style=itemNames]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{itemNames}}{lst:itemNames} \yamltitle{specialBeginEnd}*{fields}\label{yaml:specialBeginEnd} The fields specified \index{specialBeginEnd!introduction} \announce{2017-08-21}*{specialBeginEnd} in \texttt{specialBeginEnd} are, in their default state, focused on math mode begin and end statements, but there is no requirement for this to be the case; \cref{lst:specialBeginEnd} shows the default settings of \texttt{specialBeginEnd}. \index{specialBeginEnd!default settings}% \cmhlistingsfromfile[style=specialBeginEnd]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{specialBeginEnd}}{lst:specialBeginEnd} The field \texttt{displayMath} represents \lstinline!\[...\]!, \texttt{inlineMath} represents \lstinline!$...$! and \texttt{displayMathTex} represents \lstinline!$$...$$!. You can, of course, rename these in your own YAML files (see \vref{sec:localsettings}); indeed, you might like to set up your own special begin and end statements. \begin{example} A demonstration of the before-and-after results are shown in \cref{lst:specialbefore,lst:specialafter}; explicitly, running the command \begin{commandshell} latexindent.pl special1.tex -o=+-default \end{commandshell} gives the output given in \cref{lst:specialafter}. \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/special1.tex}{\texttt{special1.tex} before}{lst:specialbefore} \cmhlistingsfromfile{demonstrations/special1-default.tex}{\texttt{special1.tex} default output}{lst:specialafter} \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} not to look for the pattern, by setting \texttt{lookForThis} to \texttt{0}. There are \announce{2017-08-21}{specialBeforeCommand} examples in which it is advantageous to search for \texttt{specialBeginEnd} fields \emph{before} searching for commands, and the \texttt{specialBeforeCommand} switch controls this behaviour. \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 \cref{lst:specialsLeftRight-yaml,lst:specialBeforeCommand-yaml} \index{specialBeginEnd!searching for special before commands} \begin{cmhtcbraster} \cmhlistingsfromfile[]{demonstrations/specialsLeftRight.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{specialsLeftRight.yaml}}{lst:specialsLeftRight-yaml} \cmhlistingsfromfile[]{demonstrations/specialBeforeCommand.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{specialBeforeCommand.yaml}}{lst:specialBeforeCommand-yaml} \end{cmhtcbraster} 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}. \begin{minipage}{.49\linewidth} \cmhlistingsfromfile{demonstrations/specialLR-comm-first.tex}{\texttt{specialLR.tex} using \cref{lst:specialsLeftRight-yaml}}{lst:specialLR-comm-first-tex} \end{minipage} \hfill \begin{minipage}{.49\linewidth} \cmhlistingsfromfile{demonstrations/specialLR-special-first.tex}{\texttt{specialLR.tex} using \cref{lst:specialsLeftRight-yaml,lst:specialBeforeCommand-yaml}}{lst:specialLR-special-first-tex} \end{minipage} Notice that in: \begin{itemize} \item \cref{lst:specialLR-comm-first-tex} the \lstinline!\left! has been treated as a \emph{command}, with one optional argument; \item \cref{lst:specialLR-special-first-tex} the \texttt{specialBeginEnd} pattern in \cref{lst:specialsLeftRight-yaml} has been obeyed because \cref{lst:specialBeforeCommand-yaml} specifies that the \texttt{specialBeginEnd} should be sought \emph{before} commands. \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}. \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} 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} \cmhlistingsfromfile{demonstrations/special2-mod1.tex}{\texttt{special2.tex} using \cref{lst:middle-yaml}}{lst:special2-mod1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/middle.yaml}[yaml-TCB]{\texttt{middle.yaml}}{lst:middle-yaml} \end{cmhtcbraster} \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/special2-mod2.tex}{\texttt{special2.tex} using \cref{lst:middle1-yaml}}{lst:special2-mod2} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/middle1.yaml}[yaml-TCB]{\texttt{middle1.yaml}}{lst:middle1-yaml} \end{cmhtcbraster} We note that: \begin{itemize} \item in \cref{lst:special2-mod1} the bodies of each of the \texttt{Elsif} statements have been indented appropriately; \item the \texttt{Else} statement has \emph{not} been indented appropriately in \cref{lst:special2-mod1} -- read on! \item we have specified multiple settings for the \texttt{middle} field using the syntax demonstrated in \cref{lst:middle1-yaml} so that the body of the \texttt{Else} statement has been indented appropriately in \cref{lst:special2-mod2}. \end{itemize} \end{example} You may need these fields in your own YAML files (see \vref{sec:localsettings}), if you use popular algorithm packages such as algorithms, algorithm2e or algpseudocode, etc. \begin{example} For example, let’s consider the \texttt{.tex} file in \cref{lst:specialAlgo}. \index{specialBeginEnd!middle} \index{specialBeginEnd!Algorithms example} \cmhlistingsfromfile[basicstyle=\tiny]{demonstrations/specialAlgo.tex}[enhanced jigsaw,breakable]{\texttt{specialAlgo.tex}}{lst:specialAlgo} Upon saving the YAML settings in \cref{lst:algo-yaml} and running the command \index{switches!-l demonstration} \begin{commandshell} latexindent.pl -l=algo.yaml specialAlgo.tex \end{commandshell} then we obtain the output given in \cref{lst:specialAlgo-mod1}. \begin{cmhtcbraster} \cmhlistingsfromfile[basicstyle=\tiny]{demonstrations/specialAlgo-mod1.tex}{\texttt{specialAlgo.tex} using \cref{lst:algo-yaml}}{lst:specialAlgo-mod1} \cmhlistingsfromfile[style=yaml-LST,basicstyle=\tiny,commentstyle=\color{blue}\ttfamily\tiny]{demonstrations/algo.yaml}[yaml-TCB]{\texttt{algo.yaml}}{lst:algo-yaml} \end{cmhtcbraster} \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} \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/special3-mod1.tex}{\texttt{special3.tex} and output using \cref{lst:special-verb1-yaml}}{lst:special3-mod1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/special-verb1.yaml}[yaml-TCB]{\texttt{special-verb1.yaml}}{lst:special-verb1-yaml} \end{cmhtcbraster} \end{example} We can combine the \texttt{specialBeginEnd} with the \texttt{lookForAlignDelims} feature. \begin{example} We begin with the code in \cref{lst:special-align}. \cmhlistingsfromfile{demonstrations/special-align.tex}{\texttt{special-align.tex}}{lst:special-align} Let's assume that our goal is to align the code at the \texttt{edge} and \texttt{node} text; we employ the code given in \cref{lst:edge-node1} and run the command \index{switches!-l demonstration} \index{switches!-o demonstration} \begin{commandshell} latexindent.pl special-align.tex -l edge-node1.yaml -o=+-mod1 \end{commandshell} to receive the output in \cref{lst:special-align-mod1}. \index{specialBeginEnd!combined with lookForAlignDelims} \index{specialBeginEnd!delimiterRegEx} \index{specialBeginEnd!alignment at delimiter} \index{specialBeginEnd!tikz example} \index{regular expressions!delimiter alignment for edge or node} \index{delimiters!within specialBeginEnd blocks} \index{regular expressions!numeric 0-9} \begin{cmhtcbraster}[ raster left skip=-3.5cm,] \cmhlistingsfromfile{demonstrations/special-align-mod1.tex}{\texttt{special-align.tex} using \cref{lst:edge-node1}}{lst:special-align-mod1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/edge-node1.yaml}[yaml-TCB]{\texttt{edge-node1.yaml}}{lst:edge-node1} \end{cmhtcbraster} The output in \cref{lst:special-align-mod1} is not quite ideal. We can tweak the settings within \cref{lst:edge-node1} in order to improve the output; in particular, we employ the code in \cref{lst:edge-node2} and run the command \index{switches!-l demonstration} \index{switches!-o demonstration} \index{regular expressions!uppercase alph A-Z} \begin{commandshell} latexindent.pl special-align.tex -l edge-node2.yaml -o=+-mod2 \end{commandshell} to receive the output in \cref{lst:special-align-mod2}. \index{specialBeginEnd!delimiterRegEx tweaked} \index{regular expressions!at least one +} \index{regular expressions!horizontal space \textbackslash{h}} \begin{cmhtcbraster}[ raster left skip=-3.5cm,] \cmhlistingsfromfile{demonstrations/special-align-mod2.tex}{\texttt{special-align.tex} using \cref{lst:edge-node2}}{lst:special-align-mod2} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/edge-node2.yaml}[yaml-TCB]{\texttt{edge-node2.yaml}}{lst:edge-node2} \end{cmhtcbraster} \end{example} The \texttt{lookForThis} field can be considered optional; \announce{2021-06-19}*{lookForThis optional for specialBeginEnd} by default, it is assumed to be 1, which is demonstrated in \cref{lst:edge-node2}.% Referencing \vref{lst:specialBeginEnd} we see that \announce{2023-09-23}{specialBeginEnd body field} each of the \texttt{specialBeginEnd} fields can \emph{optionally} accept the \texttt{body} field. If the \texttt{body} field is omitted, then \texttt{latexindent.pl} uses a value that means \begin{quote} anything except one of the begin statements from \texttt{specialBeginEnd}. \end{quote} In general, it is usually \emph{not} necessary to specify the \texttt{body} field, but let's detail an example just for reference. \begin{example} We begin with the example in \cref{lst:special-body} \cmhlistingsfromfile{demonstrations/special-body.tex}{\texttt{special-body.tex}}{lst:special-body} Using the settings in \cref{lst:special-body1} and running the command \begin{commandshell} latexindent.pl special-body.tex -l=special-body1.yaml \end{commandshell} gives the output in \cref{lst:special-body-mod1}. \begin{cmhtcbraster}[ raster left skip=-3.5cm,] \cmhlistingsfromfile{demonstrations/special-body-mod1.tex}{\texttt{special-body.tex} using \cref{lst:special-body1}}{lst:special-body-mod1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/special-body1.yaml}[yaml-TCB]{\texttt{special-body1.yaml}}{lst:special-body1} \end{cmhtcbraster} We note that the output in \cref{lst:special-body-mod1} is as we would expect, even \emph{without} the \texttt{body} field specified. Another option (purely for reference) that leaves the output in \cref{lst:special-body-mod1} unchanged is shown in \cref{lst:special-body2}. \cmhlistingsfromfile[style=yaml-LST]{demonstrations/special-body2.yaml}[yaml-TCB]{\texttt{special-body2.yaml}}{lst:special-body2} The \texttt{body} field in \cref{lst:special-body2} means \emph{anything except ( or )}. \end{example} \yamltitle{indentAfterHeadings}*{fields} This field enables the user to specify indentation rules that take effect after heading commands such as \lstinline!\part!, \lstinline!\chapter!, \lstinline!\section!, \lstinline!\subsection*!, or indeed any user-specified command written in this field.\footnote{There is a slight difference in interface for this field when comparing Version 2.2 to Version 3.0; see \vref{app:differences} for details.} \cmhlistingsfromfile[style=indentAfterHeadings]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{indentAfterHeadings}}{lst:indentAfterHeadings} The default settings do \emph{not} place indentation after a heading, but you can easily switch them on by changing \texttt{indentAfterThisHeading} from 0 to 1. The \texttt{level} field tells \texttt{latexindent.pl} the hierarchy of the heading structure in your document. You might, for example, like to have both \texttt{section} and \texttt{subsection} set with \texttt{level: 3} because you do not want the indentation to go too deep. You can add any of your own custom heading commands to this field, specifying the \texttt{level} as appropriate. You can also specify your own indentation in \texttt{indentRules} (see \vref{sec:noadd-indent-rules}); you will find the default \texttt{indentRules} contains \lstinline!chapter: " "! which tells \texttt{latexindent.pl} simply to use a space character after \texttt{chapter} headings (once \texttt{indent} is set to \texttt{1} for \texttt{chapter}). \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}. \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/headings1.tex}{\texttt{headings1.tex}}{lst:headings1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/headings1.yaml}[yaml-TCB]{\texttt{headings1.yaml}}{lst:headings1yaml} \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} \cmhlistingsfromfile[showtabs=true]{demonstrations/headings1-mod1.tex}{\texttt{headings1.tex} using \cref{lst:headings1yaml}}{lst:headings1-mod1} \end{minipage}% \hfill \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. \index{indentation!maximum indetation} \yamltitle{maximumIndentation}*{horizontal space} You can control the maximum indentation given to your file by \announce{2017-08-21}{maximumIndentation} specifying the \texttt{maximumIndentation} field as horizontal space (but \emph{not} including tabs). This feature uses the \texttt{Text::Tabs} module \cite{texttabs}, and is \emph{off} by default.% \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}. \begin{cmhtcbraster}[raster column skip=.1\linewidth] \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} \cmhlistingsfromfile[showspaces=true]{demonstrations/mult-nested-max-ind1.tex}{\texttt{mult-nested.tex} using \cref{lst:max-indentation1yaml}}{lst:mult-nested-max-ind1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/max-indentation1.yaml}[yaml-TCB]{\texttt{max-indentation1.yaml}}{lst:max-indentation1yaml} \end{cmhtcbraster} \end{example} Comparing the output in \cref{lst:mult-nested-default,lst:mult-nested-max-ind1} we notice that the (default) tabs of indentation have been replaced by a single space. In general, when using the \texttt{maximumIndentation} feature, any leading tabs will be replaced by equivalent spaces except, of course, those found in \texttt{verbatimEnvironments} (see \vref{lst:verbatimEnvironments}) or \texttt{noIndentBlock} (see \vref{lst:noIndentBlock}). \subsection{The code blocks known latexindent.pl}\label{subsubsec:code-blocks} As of Version 3.0, \texttt{latexindent.pl} processes documents using code blocks; each of these are shown in \cref{tab:code-blocks}. \index{regular expressions!uppercase alph A-Z} \index{regular expressions!lowercase alph a-z} \index{regular expressions!numeric 0-9} \index{regular expressions!horizontal space \textbackslash{h}} \begin{table}[!htp] \begin{widepage} \centering \caption{Code blocks known to \texttt{latexindent.pl}} \label{tab:code-blocks} \begin{tabular}{m{.3\linewidth}@{\hspace{.25cm}}m{.4\linewidth}@{\hspace{.25cm}}m{.2\linewidth}} \toprule Code block & characters allowed in name & example \\ \midrule environments & \lstinline!a-zA-Z@\*0-9_\\! & \begin{lstlisting}[,nolol=true,] \begin{myenv} body of myenv \end{myenv} \end{lstlisting} \\\cmidrule{2-3} optionalArguments & \emph{inherits} name from parent (e.g environment name) & \begin{lstlisting}[,nolol=true,] [ opt arg text ] \end{lstlisting} \\\cmidrule{2-3} mandatoryArguments & \emph{inherits} name from parent (e.g environment name) & \begin{lstlisting}[,nolol=true,] { mand arg text } \end{lstlisting} \\\cmidrule{2-3} commands & \lstinline!+a-zA-Z@\*0-9_\:! & \lstinline!\mycommand!$\langle$\itshape{arguments}$\rangle$ \\\cmidrule{2-3} keyEqualsValuesBracesBrackets & \lstinline!a-zA-Z@\*0-9_\/.\h\{\}:\#-! & \lstinline!my key/.style=!$\langle$\itshape{arguments}$\rangle$ \\\cmidrule{2-3} namedGroupingBracesBrackets & \lstinline!0-9\.a-zA-Z@\*><! & \lstinline!in!$\langle$\itshape{arguments}$\rangle$ \\\cmidrule{2-3} UnNamedGroupingBracesBrackets & \centering\emph{No name!} & \lstinline!{! or \lstinline![! or \lstinline!,! or \lstinline!\&! or \lstinline!)! or \lstinline!(! or \lstinline!$! followed by $\langle$\itshape{arguments}$\rangle$ \\\cmidrule{2-3} ifElseFi & \lstinline!@a-zA-Z! but must begin with either \newline \lstinline!\if! of \lstinline!\@if! & \begin{lstlisting}[,nolol=true,] \ifnum... ... \else ... \fi \end{lstlisting} \\\cmidrule{2-3} items & User specified, see \vref{lst:indentafteritems,lst:itemNames} & \begin{lstlisting}[,nolol=true,] \begin{enumerate} \item ... \end{enumerate} \end{lstlisting} \\\cmidrule{2-3} specialBeginEnd & User specified, see \vref{lst:specialBeginEnd} & \begin{lstlisting}[,nolol=true,] \[ ... \] \end{lstlisting} \\\cmidrule{2-3} afterHeading & User specified, see \vref{lst:indentAfterHeadings} & \begin{lstlisting}[,morekeywords={chapter},nolol=true,] \chapter{title} ... \section{title} \end{lstlisting} \\\cmidrule{2-3} filecontents & User specified, see \vref{lst:fileContentsEnvironments} & \begin{lstlisting}[,nolol=true,] \begin{filecontents} ... \end{filecontents} \end{lstlisting} \\ \bottomrule \end{tabular} \end{widepage} \end{table} We will refer to these code blocks in what follows. \announce{2019-07-13}{fine tuning of code blocks} Note that the fine tuning of the definition of the code blocks detailed in \cref{tab:code-blocks} is discussed in \vref{sec:finetuning}.% % arara: pdflatex: { files: [latexindent]} % arara: pdflatex: { files: [latexindent]} \index{indentation!no additional indent} \index{indentation!removing indentation per-code block} \index{indentation!customising indentation per-code block} \index{indentation!customising per-name} \index{indentation!no additional indent global} \subsection{noAdditionalIndent and indentRules}\label{sec:noadd-indent-rules} \texttt{latexindent.pl} operates on files by looking for code blocks, as detailed in \vref{subsubsec:code-blocks}; for each type of code block in \vref{tab:code-blocks} (which we will call a \emph{$\langle$thing$\rangle$} in what follows) it searches YAML fields for information in the following order: \begin{enumerate} \item \texttt{noAdditionalIndent} for the \emph{name} of the current \emph{$\langle$thing$\rangle$}; \item \texttt{indentRules} for the \emph{name} of the current \emph{$\langle$thing$\rangle$}; \item \texttt{noAdditionalIndentGlobal} for the \emph{type} of the current \emph{$\langle$thing$\rangle$}; \item \texttt{indentRulesGlobal} for the \emph{type} of the current \emph{$\langle$thing$\rangle$}. \end{enumerate} Using the above list, the first piece of information to be found will be used; failing that, the value of \texttt{defaultIndent} is used. If information is found in multiple fields, the first one according to the list above will be used; for example, if information is present in both \texttt{indentRules} and in \texttt{noAdditionalIndentGlobal}, then the information from \texttt{indentRules} takes priority. We now present details for the different type of code blocks known to \texttt{latexindent.pl}, as detailed in \vref{tab:code-blocks}; for reference, there follows a list of the code blocks covered. \startcontents[noAdditionalIndent] \printcontents[noAdditionalIndent]{}{0}{} % arara: pdflatex: { files: [latexindent]} \subsubsection{Environments and their arguments}\label{subsubsec:env-and-their-args} There are a few different YAML switches governing the indentation of environments; let's start with the code shown in \cref{lst:myenvtex}. \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}. \begin{minipage}{.45\textwidth} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/myenv-noAdd1.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-noAdd1.yaml}}{lst:myenv-noAdd1} \end{minipage} \hfill \begin{minipage}{.45\textwidth} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/myenv-noAdd2.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-noAdd2.yaml}}{lst:myenv-noAdd2} \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{cmhtcbraster} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/myenv-noAdd3.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-noAdd3.yaml}}{lst:myenv-noAdd3} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/myenv-noAdd4.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-noAdd4.yaml}}{lst:myenv-noAdd4} \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}. \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 \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{cmhtcbraster} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/myenv-noAdd5.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-noAdd5.yaml}}{lst:myenv-noAdd5} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/myenv-noAdd6.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-noAdd6.yaml}}{lst:myenv-noAdd6} \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 any additional indentation, and that in \cref{lst:myenv-args-noAdd6} the \emph{mandatory} argument has not received any additional indentation; in both cases, the \emph{body} has not received any additional indentation. \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/myenvironment-args-noAdd5.tex}{\texttt{myenv-args.tex} using \cref{lst:myenv-noAdd5}}{lst:myenv-args-noAdd5} \cmhlistingsfromfile{demonstrations/myenvironment-args-noAdd6.tex}{\texttt{myenv-args.tex} using \cref{lst:myenv-noAdd6}}{lst:myenv-args-noAdd6} \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}. \begin{cmhtcbraster}[raster column skip=.1\linewidth] \cmhlistingsfromfile[style=yaml-LST]{demonstrations/myenv-rules1.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-rules1.yaml}}{lst:myenv-rules1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/myenv-rules2.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-rules2.yaml}}{lst:myenv-rules2} \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} \begin{minipage}{.49\textwidth} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/myenv-rules3.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-rules3.yaml}}{lst:myenv-rules3} \end{minipage} \hfill \begin{minipage}{.49\textwidth} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/myenv-rules4.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-rules4.yaml}}{lst:myenv-rules4} \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}. \begin{widepage} \begin{minipage}{.5\textwidth} \cmhlistingsfromfile[showtabs=true,showspaces=true]{demonstrations/myenvironment-args-rules3.tex}{\texttt{myenv-args.tex} using \cref{lst:myenv-rules3}}{lst:myenv-args-rules3} \end{minipage}% \hfill \begin{minipage}{.5\textwidth} \cmhlistingsfromfile[showtabs=true,showspaces=true]{demonstrations/myenvironment-args-rules4.tex}{\texttt{myenv-args.tex} using \cref{lst:myenv-rules4}}{lst:myenv-args-rules4} \end{minipage} \end{widepage} Note that in \cref{lst:myenv-args-rules3}, the optional argument has only received a single space of indentation, while the mandatory argument has received the default (tab) indentation; the environment body has received three spaces of indentation. 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 \texttt{noAdditionalIndent} nor \texttt{indentRules}, the next place that \texttt{latexindent.pl} will look is \texttt{noAdditionalIndentGlobal}, and in particular \emph{for the environments} key (see \cref{lst:noAdditionalIndentGlobal:environments}). \cmhlistingsfromfile[style=noAdditionalIndentGlobalEnv]{../defaultSettings.yaml}[width=.7\linewidth,before=\centering,yaml-TCB]{\texttt{noAdditionalIndentGlobal}}{lst:noAdditionalIndentGlobal:environments} \begin{example} Let's say that you change the value of \texttt{environments} to \texttt{1} in \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 \cref{lst:myenv-args-no-add-global1,lst:myenv-args-no-add-global2}; in \cref{lst:myenv-args-no-add-global1} notice that \emph{both} environments receive no additional indentation but that the arguments of \texttt{myenv} still \emph{do} receive indentation. In \cref{lst:myenv-args-no-add-global2} notice that the \emph{outer} environment does not receive additional indentation, but because of the settings from \texttt{myenv-rules1.yaml} (in \vref{lst:myenv-rules1}), the \texttt{myenv} environment still \emph{does} receive indentation. \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/myenvironment-args-rules1-noAddGlobal1.tex}{\texttt{myenv-args.tex} using \cref{lst:noAdditionalIndentGlobal:environments}}{lst:myenv-args-no-add-global1} \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{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{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} \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{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 additional indentation, and in \cref{lst:myenv-args-no-add-mand} the \emph{mandatory} argument has not received any additional indentation. \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} \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{cmhtcbraster} \end{example} \yamltitle{indentRulesGlobal}*{fields} The final check that \texttt{latexindent.pl} will make is to look for \texttt{indentRulesGlobal} as detailed in \cref{lst:indentRulesGlobal:environments}. \cmhlistingsfromfile[style=indentRulesGlobalEnv]{../defaultSettings.yaml}[width=.7\linewidth,before=\centering,yaml-TCB]{\texttt{indentRulesGlobal}}{lst:indentRulesGlobal:environments} \begin{example} If you change the \texttt{environments} field to anything involving horizontal space, say \lstinline!" "!, and then run the following commands \index{switches!-l demonstration} \begin{commandshell} latexindent.pl myenv-args.tex -l env-indentRules.yaml latexindent.pl myenv-args.tex -l myenv-rules1.yaml,env-indentRules.yaml \end{commandshell} then the respective output is shown in \cref{lst:myenv-args-indent-rules-global1,lst:myenv-args-indent-rules-global2}. Note that in \cref{lst:myenv-args-indent-rules-global1}, both the environment blocks have received a single-space indentation, whereas in \cref{lst:myenv-args-indent-rules-global2} the \texttt{outer} environment has received single-space indentation (specified by \texttt{indentRulesGlobal}), but \texttt{myenv} has received \lstinline!" "!, as specified by the particular \texttt{indentRules} for \texttt{myenv} \vref{lst:myenv-rules1}. \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} \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{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{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} \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{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 two tabs worth of indentation, while the \emph{mandatory} argument has done so in \cref{lst:myenv-args-indent-rules-global4}. \begin{widepage} \begin{minipage}{.55\textwidth} \cmhlistingsfromfile[showtabs=true]{demonstrations/myenvironment-args-global-rules3.tex}{\texttt{myenv-args.tex} using \cref{lst:opt-args-indent-rules-glob}}{lst:myenv-args-indent-rules-global3} \end{minipage} \hfill \begin{minipage}{.55\textwidth} \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 \texttt{item} commands; for the purposes of this discussion, we will use the code from \vref{lst:itemsbefore}. Assuming that you've populated \texttt{itemNames} with the name of your \texttt{item}, you can put the item name into \texttt{noAdditionalIndent} as in \cref{lst:item-noAdd1}, although a more efficient approach may be to change the relevant field in \texttt{itemNames} to \texttt{0}. \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} \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 \texttt{item} has received a single space of indentation, specified by \cref{lst:item-rules1}. \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/items1-noAdd1.tex}{\texttt{items1.tex} using \cref{lst:item-noAdd1}}{lst:items1-noAdd1} \cmhlistingsfromfile[showtabs=true,showspaces=true]{demonstrations/items1-rules1.tex}{\texttt{items1.tex} using \cref{lst:item-rules1}}{lst:items1-rules1} \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 need to `reset/remove' the \texttt{item} field from \texttt{indentRules} in both cases (see the hierarchy description given on \cpageref{sec:noadd-indent-rules}) as the \texttt{item} command is a member of \texttt{indentRules} by default. \begin{cmhtcbraster} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/items-noAdditionalGlobal.yaml}[yaml-TCB]{\texttt{items-noAdditionalGlobal.yaml}}{lst:items-noAdditionalGlobal} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/items-indentRulesGlobal.yaml}[yaml-TCB]{\texttt{items-indentRulesGlobal.yaml}}{lst:items-indentRulesGlobal} \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 \vref{subsec:commands-string-between}.} \begin{cmhtcbraster}[raster column skip=.1\linewidth] \cmhlistingsfromfile{demonstrations/mycommand.tex}{\texttt{mycommand.tex}}{lst:mycommand} \cmhlistingsfromfile{demonstrations/mycommand-default.tex}{\texttt{mycommand.tex} default output}{lst:mycommand-default} \end{cmhtcbraster} As in the environment-based case (see \vref{lst:myenv-noAdd1,lst:myenv-noAdd2}) we may specify \texttt{noAdditionalIndent} either in `scalar' form, or in `field' form, as shown in \cref{lst:mycommand-noAdd1,lst:mycommand-noAdd2} \begin{cmhtcbraster} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycommand-noAdd1.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{mycommand-noAdd1.yaml}}{lst:mycommand-noAdd1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycommand-noAdd2.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{mycommand-noAdd2.yaml}}{lst:mycommand-noAdd2} \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{cmhtcbraster} \cmhlistingsfromfile{demonstrations/mycommand-noAdd1.tex}{\texttt{mycommand.tex} using \cref{lst:mycommand-noAdd1}}{lst:mycommand-output-noAdd1} \cmhlistingsfromfile{demonstrations/mycommand-noAdd2.tex}{\texttt{mycommand.tex} using \cref{lst:mycommand-noAdd2}}{lst:mycommand-output-noAdd2} \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 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{cmhtcbraster} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycommand-noAdd3.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{mycommand-noAdd3.yaml}}{lst:mycommand-noAdd3} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycommand-noAdd4.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{mycommand-noAdd4.yaml}}{lst:mycommand-noAdd4} \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{cmhtcbraster} \cmhlistingsfromfile{demonstrations/mycommand-noAdd3.tex}{\texttt{mycommand.tex} using \cref{lst:mycommand-noAdd3}}{lst:mycommand-output-noAdd3} \cmhlistingsfromfile{demonstrations/mycommand-noAdd4.tex}{\texttt{mycommand.tex} using \cref{lst:mycommand-noAdd4}}{lst:mycommand-output-noAdd4} \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 \cref{lst:mycommand-noAdd3,lst:mycommand-noAdd4}. This is because, by default, \texttt{noAdditionalIndentGlobal} for \texttt{commands} is set to \texttt{1} by default; this can be easily fixed as in \cref{lst:mycommand-noAdd5,lst:mycommand-noAdd6}.\label{page:command:noAddGlobal} \begin{cmhtcbraster} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycommand-noAdd5.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{mycommand-noAdd5.yaml}}{lst:mycommand-noAdd5} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycommand-noAdd6.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{mycommand-noAdd6.yaml}}{lst:mycommand-noAdd6} \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{cmhtcbraster} \cmhlistingsfromfile{demonstrations/mycommand-noAdd5.tex}{\texttt{mycommand.tex} using \cref{lst:mycommand-noAdd5}}{lst:mycommand-output-noAdd5} \cmhlistingsfromfile{demonstrations/mycommand-noAdd6.tex}{\texttt{mycommand.tex} using \cref{lst:mycommand-noAdd6}}{lst:mycommand-output-noAdd6} \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 \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{cmhtcbraster} \cmhlistingsfromfile{demonstrations/ifelsefi1.tex}{\texttt{ifelsefi1.tex}}{lst:ifelsefi1} \cmhlistingsfromfile{demonstrations/ifelsefi1-default.tex}{\texttt{ifelsefi1.tex} default output}{lst:ifelsefi1-default} \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, assuming that \texttt{body} was specified. Examples are shown in \cref{lst:ifnum-noAdd,lst:ifnum-indent-rules}. \begin{cmhtcbraster} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/ifnum-noAdd.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{ifnum-noAdd.yaml}}{lst:ifnum-noAdd} \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{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 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{cmhtcbraster} \cmhlistingsfromfile{demonstrations/ifelsefi1-noAdd.tex}{\texttt{ifelsefi1.tex} using \cref{lst:ifnum-noAdd}}{lst:ifelsefi1-output-noAdd} \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{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{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} \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{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 blocks have received indentation, while in \cref{lst:ifelsefi1-output-indent-rules-global} both code blocks have received a single space of indentation. \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/ifelsefi1-noAdd-glob.tex}{\texttt{ifelsefi1.tex} using \cref{lst:ifelsefi-noAdd-glob}}{lst:ifelsefi1-output-noAdd-glob} \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{cmhtcbraster} \end{example} \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 \cref{lst:displayMath-noAdd,lst:displayMath-indent-rules}. \index{specialBeginEnd!noAdditionalIndent} \index{specialBeginEnd!indentRules example} \begin{cmhtcbraster} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/displayMath-noAdd.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{displayMath-noAdd.yaml}}{lst:displayMath-noAdd} \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{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} 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{cmhtcbraster} \cmhlistingsfromfile{demonstrations/special1-noAdd.tex}{\texttt{special1.tex} using \cref{lst:displayMath-noAdd}}{lst:special1-output-noAdd} \cmhlistingsfromfile[showtabs=true]{demonstrations/special1-indent-rules.tex}{\texttt{special1.tex} using \cref{lst:displayMath-indent-rules}}{lst:special1-output-indent-rules} \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{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} \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{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 have received indentation, while in \cref{lst:special1-output-indent-rules-global} both code blocks have received a single space of indentation. \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/special1-noAdd-glob.tex}{\texttt{special1.tex} using \cref{lst:special-noAdd-glob}}{lst:special1-output-noAdd-glob} \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{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 \namecref{subsubsec-headings-no-add-indent-rules}. As discussed on \cpageref{lst:headings1}, by default \texttt{latexindent.pl} will not add indentation after headings. \cmhlistingsfromfile{demonstrations/headings2.tex}{\texttt{headings2.tex}}{lst:headings2} \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. \begin{cmhtcbraster}[raster column skip=.1\linewidth] \cmhlistingsfromfile{demonstrations/headings2-mod3.tex}{\texttt{headings2.tex} using \cref{lst:headings3yaml}}{lst:headings2-mod3} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/headings3.yaml}[yaml-TCB]{\texttt{headings3.yaml}}{lst:headings3yaml} \end{cmhtcbraster} If we specify \texttt{noAdditionalIndent} as in \cref{lst:headings4yaml} and run the command \index{switches!-l demonstration} \begin{commandshell} latexindent.pl headings2.tex -l headings4.yaml \end{commandshell} then we receive the output in \cref{lst:headings2-mod4}. Note that the arguments \emph{and} the body after the heading of \texttt{paragraph} has received no additional indentation, because we have specified \texttt{noAdditionalIndent} in scalar form. \begin{cmhtcbraster}[raster column skip=.1\linewidth] \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} of \texttt{paragraph} have \emph{all} received three tabs worth of indentation. \begin{cmhtcbraster}[raster force size=false, raster column 1/.style={add to width=1cm}, raster column 2/.style={add to width=-1cm}, ] \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}. \begin{cmhtcbraster} \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 three tabs worth of indentation. \begin{cmhtcbraster} \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} the \emph{mandatory argument} of \texttt{paragraph} has received a (default) tab's worth of indentation, while the body after the heading has received \emph{no additional indentation}. Similarly, in \cref{lst:headings2-mod9}, the \emph{argument} has received both a (default) tab plus two spaces of indentation (from the global rule specified in \cref{lst:headings9yaml}), and the remaining body after \texttt{paragraph} has received just two spaces of indentation. \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/headings2-mod8.tex}{\texttt{headings2.tex} using \cref{lst:headings8yaml}}{lst:headings2-mod8} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/headings8.yaml}[yaml-TCB]{\texttt{headings8.yaml}}{lst:headings8yaml} \end{cmhtcbraster} \begin{cmhtcbraster} \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 code blocks yet to cover; these are very similar to the \texttt{commands} code block type covered comprehensively in \vref{subsubsec:commands-arguments}, but a small discussion defining these remaining code blocks is necessary. \paragraph{keyEqualsValuesBracesBrackets} \texttt{latexindent.pl} defines this type of code block by the following criteria: \begin{itemize} \item it must immediately follow either \lstinline!{! OR \lstinline![! OR \lstinline!,! with comments and blank lines allowed. \item then it has a name made up of the characters detailed in \vref{tab:code-blocks}; \item then an $=$ symbol; \item then at least one set of curly braces or square brackets (comments and line breaks allowed throughout). \end{itemize} See the \texttt{keyEqualsValuesBracesBrackets: follow} and \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{cmhtcbraster} \cmhlistingsfromfile{demonstrations/pgfkeys1.tex}{\texttt{pgfkeys1.tex}}{lst:pgfkeysbefore} \cmhlistingsfromfile[showtabs=true]{demonstrations/pgfkeys1-default.tex}{\texttt{pgfkeys1.tex} default output}{lst:pgfkeys1:default} \end{cmhtcbraster} In \cref{lst:pgfkeys1:default}, note that the maximum indentation is three tabs, and these come from: \begin{itemize} \item the \lstinline!\pgfkeys! command's mandatory argument; \item the \lstinline!start coordinate/.initial! key's mandatory argument; \item the \lstinline!start coordinate/.initial! key's body, which is defined as any lines following the name of the key that include its arguments. This is the part controlled by the \emph{body} field for \texttt{noAdditionalIndent} and friends from \cpageref{sec:noadd-indent-rules}. \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} \item it must immediately follow either \emph{horizontal space} OR \emph{one or more line breaks} OR \lstinline!{! OR \lstinline![! OR \lstinline!$! OR \lstinline!)! OR \lstinline!(! \item the name may contain the characters detailed in \vref{tab:code-blocks}; \item then at least one set of curly braces or square brackets (comments and line breaks allowed throughout). \end{itemize} See the \texttt{NamedGroupingBracesBrackets: follow} and \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{cmhtcbraster} \cmhlistingsfromfile{demonstrations/child1.tex}{\texttt{child1.tex}}{lst:child1} \cmhlistingsfromfile[showtabs=true]{demonstrations/child1-default.tex}{\texttt{child1.tex} default output}{lst:child1:default} \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 verify this by using the \texttt{-tt} option and checking \texttt{indent.log}! }. Referencing \cref{lst:child1:default}, note that the maximum indentation is two tabs, and these come from: \begin{itemize} \item the \lstinline!child!'s mandatory argument; \item the \lstinline!child!'s body, which is defined as any lines following the name of the \texttt{namedGroupingBracesBrackets} that include its arguments. This is the part controlled by the \emph{body} field for \texttt{noAdditionalIndent} and friends from \cpageref{sec:noadd-indent-rules}. \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: \begin{itemize} \item it must immediately follow either \lstinline!{! OR \lstinline![! OR \lstinline!,! OR \lstinline!&! OR \lstinline!)! OR \lstinline!(! OR \lstinline!$!; \item then at least one set of curly braces or square brackets (comments and line breaks allowed throughout). \end{itemize} 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{cmhtcbraster} \cmhlistingsfromfile{demonstrations/psforeach1.tex}{\texttt{psforeach1.tex}}{lst:psforeach1} \cmhlistingsfromfile[showtabs=true]{demonstrations/psforeach1-default.tex}{\texttt{psforeach1.tex} default output}{lst:psforeach:default} \end{cmhtcbraster} Referencing \cref{lst:psforeach:default}, there are \emph{three} sets of unnamed braces. Note also that the maximum value of indentation is three tabs, and these come from: \begin{itemize} \item the \lstinline!\psforeach! command's mandatory argument; \item the \emph{first} un-named braces mandatory argument; \item the \emph{first} un-named braces \emph{body}, which we define as any lines following the first opening \lstinline!{! or \lstinline![! that defined the code block. This is the part controlled by the \emph{body} field for \texttt{noAdditionalIndent} and friends from \cpageref{sec:noadd-indent-rules}. \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}. \paragraph{filecontents} code blocks behave just as \texttt{environments}, except that neither arguments nor items are sought. \subsubsection{Summary} \index{indentation!summary} Having considered all of the different types of code blocks, the functions of the fields given in \cref{lst:noAdditionalIndentGlobal,lst:indentRulesGlobal} should now make sense. \index{specialBeginEnd!noAdditionalIndentGlobal} \index{specialBeginEnd!indentRulesGlobal} \begin{widepage} \begin{minipage}{.47\linewidth} \cmhlistingsfromfile[style=noAdditionalIndentGlobal]{../defaultSettings.yaml}[before=\centering,yaml-TCB]{\texttt{noAdditionalIndentGlobal}}{lst:noAdditionalIndentGlobal} \end{minipage}% \hfill \begin{minipage}{.47\linewidth} \cmhlistingsfromfile[style=indentRulesGlobal]{../defaultSettings.yaml}[before=\centering,yaml-TCB]{\texttt{indentRulesGlobal}}{lst:indentRulesGlobal} \end{minipage}% \end{widepage} % arara: pdflatex: { files: [latexindent]} \subsection{Commands and the strings between their arguments}\label{subsec:commands-string-between} The \texttt{command} code blocks will always look for optional (square bracketed) and mandatory (curly braced) arguments which can contain comments, line breaks and `beamer' commands \lstinline!<.*?>! between them. There are switches that can allow them to contain other strings, which we discuss next. \yamltitle{commandCodeBlocks}*{fields} The \texttt{commandCodeBlocks} field \announce{2018-04-27}*{commandCodeBlocks} contains a few switches detailed in \cref{lst:commandCodeBlocks}.% \cmhlistingsfromfile[style=commandCodeBlocks]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{commandCodeBlocks}}{lst:commandCodeBlocks} \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{cmhtcbraster} \cmhlistingsfromfile{demonstrations/pstricks1.tex}{\texttt{pstricks1.tex}}{lst:pstricks1} \cmhlistingsfromfile{demonstrations/pstricks1-default.tex}{\texttt{pstricks1} default output}{lst:pstricks1-default} \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)$. By default, because \texttt{roundParenthesesAllowed} is set to $1$ in \cref{lst:commandCodeBlocks}, then \texttt{latexindent.pl} will allow round parenthesis between optional and mandatory arguments. In the case of the code in \cref{lst:pstricks1}, \texttt{latexindent.pl} finds \emph{all} the arguments of \lstinline!defFunction!, both before and after \lstinline!(u,v)!. The default output from running \texttt{latexindent.pl} on \cref{lst:pstricks1} actually leaves it unchanged (see \cref{lst:pstricks1-default}); note in particular, this is because of \texttt{noAdditionalIndentGlobal} as discussed on \cpageref{page:command:noAddGlobal}. 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] \cmhlistingsfromfile{demonstrations/pstricks1-nrp.tex}{\texttt{pstricks1.tex} using \cref{lst:noRoundParentheses}}{lst:pstricks1-nrp} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/noRoundParentheses.yaml}[yaml-TCB]{\texttt{noRoundParentheses.yaml}}{lst:noRoundParentheses} \end{cmhtcbraster} Notice the difference between \cref{lst:pstricks1-default} and \cref{lst:pstricks1-nrp}; in particular, in \cref{lst:pstricks1-nrp}, because round parentheses are \emph{not} allowed, \texttt{latexindent.pl} finds that the \lstinline!\defFunction! command finishes at the first opening round parenthesis. As such, the remaining braced, mandatory, arguments are found to be \texttt{UnNamedGroupingBracesBrackets} (see \vref{tab:code-blocks}) which, by default, assume indentation for their body, and hence the tabbed indentation in \cref{lst:pstricks1-nrp}. \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] \cmhlistingsfromfile[showspaces=true]{demonstrations/pstricks1-indent-rules.tex}{\texttt{pstricks1.tex} using \cref{lst:defFunction}}{lst:pstricks1-indent-rules} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/defFunction.yaml}[yaml-TCB]{\texttt{defFunction.yaml}}{lst:defFunction} \end{cmhtcbraster} Notice in \cref{lst:pstricks1-indent-rules} that the \emph{body} of the \lstinline!defFunction! command i.e, the subsequent lines containing arguments after the command name, have received the single space of indentation specified by \cref{lst:defFunction}. \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{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} to, node, ++ \end{quote} are all allowed to appear between arguments; importantly, you are encouraged to add further names to this field as necessary. This means that when \texttt{latexindent.pl} processes \cref{lst:tikz-node1}, it consumes: \begin{itemize} \item the optional argument \lstinline![thin]! \item the round-bracketed argument \lstinline!(c)! because \texttt{roundParenthesesAllowed} is $1$ by default \item the string \lstinline!to! (specified in \texttt{stringsAllowedBetweenArguments}) \item the optional argument \lstinline![in=110,out=-90]! \item the string \lstinline!++! (specified in \texttt{stringsAllowedBetweenArguments}) \item the round-bracketed argument \lstinline!(0,-0.5cm)! because \texttt{roundParenthesesAllowed} is $1$ by default \item the string \lstinline!node! (specified in \texttt{stringsAllowedBetweenArguments}) \item the 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] \cmhlistingsfromfile[showspaces=true]{demonstrations/tikz-node1-draw.tex}{\texttt{tikz-node1.tex} using \cref{lst:draw}}{lst:tikz-node1-draw} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/draw.yaml}[yaml-TCB]{\texttt{draw.yaml}}{lst:draw} \end{cmhtcbraster} Notice that each line after the \lstinline!\draw! command (its `body') in \cref{lst:tikz-node1-draw} has been given the appropriate two-spaces worth of indentation specified in \cref{lst:draw}. 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] \cmhlistingsfromfile{demonstrations/tikz-node1-no-strings.tex}{\texttt{tikz-node1.tex} using \cref{lst:no-strings}}{lst:tikz-node1-no-strings} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/no-strings.yaml}[yaml-TCB]{\texttt{no-strings.yaml}}{lst:no-strings} \end{cmhtcbraster} In this case, \texttt{latexindent.pl} sees that: \begin{itemize} \item the \lstinline!\draw! command finishes after the \lstinline!(c)!, as \texttt{stringsAllowedBetweenArguments} has been set to $0$ so there are no strings allowed between arguments; \item it finds a \texttt{namedGroupingBracesBrackets} called \texttt{to} (see \vref{tab:code-blocks}) \emph{with} argument \lstinline![in=110,out=-90]! \item it finds another \texttt{namedGroupingBracesBrackets} but this time called \texttt{node} with argument \lstinline![below,align=left,scale=0.5]! \end{itemize} \end{example} Referencing \vref{lst:commandCodeBlocks}, \announce{2018-04-27}*{amalgamate feature in commandCodeBlocks}, we see that the first field in the \texttt{stringsAllowedBetweenArguments} is \texttt{amalgamate} and is set to \texttt{1} by default. This is for users who wish to specify their settings in multiple YAML files. For example, by using the settings in either \cref{lst:amalgamate-demo} or\cref{lst:amalgamate-demo1} is equivalent to using the settings in \cref{lst:amalgamate-demo2}.% \begin{cmhtcbraster}[raster columns=3, raster left skip=-3.5cm, raster right skip=-2cm, raster column skip=.03\linewidth] \cmhlistingsfromfile[style=yaml-LST]{demonstrations/amalgamate-demo.yaml}[yaml-TCB]{\texttt{amalgamate-demo.yaml}}{lst:amalgamate-demo} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/amalgamate-demo1.yaml}[yaml-TCB]{\texttt{amalgamate-demo1.yaml}}{lst:amalgamate-demo1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/amalgamate-demo2.yaml}[yaml-TCB]{\texttt{amalgamate-demo2.yaml}}{lst:amalgamate-demo2} \end{cmhtcbraster} We specify \texttt{amalgamate} to be set to \texttt{0} and in which case any settings loaded prior to those specified, including the default, will be overwritten. For example, using the settings in \cref{lst:amalgamate-demo3} means that only the strings specified in that field will be used. \cmhlistingsfromfile[style=yaml-LST]{demonstrations/amalgamate-demo3.yaml}[yaml-TCB]{\texttt{amalgamate-demo3.yaml}}{lst:amalgamate-demo3} It is important to note that the \texttt{amalgamate} field, if used, must be in the first field, and specified using the syntax given in \cref{lst:amalgamate-demo1,lst:amalgamate-demo2,lst:amalgamate-demo3}. \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}. \begin{cmhtcbraster}[raster column skip=.1\linewidth] \cmhlistingsfromfile{demonstrations/for-each.tex}{\texttt{for-each.tex}}{lst:for-each} \cmhlistingsfromfile{demonstrations/for-each-default.tex}{\texttt{for-each} default output}{lst:for-each-default} \end{cmhtcbraster} 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] \cmhlistingsfromfile{demonstrations/for-each-mod1.tex}{\texttt{for-each.tex} using \cref{lst:foreach}}{lst:for-each-mod1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/foreach.yaml}[yaml-TCB]{\texttt{foreach.yaml}}{lst:foreach} \end{cmhtcbraster} You might like to compare the output given in \cref{lst:for-each-default} and \cref{lst:for-each-mod1}. Note,in particular, in \cref{lst:for-each-default} that the \texttt{foreach} command has not included any of the subsequent strings, and that the braces have been treated as a \texttt{namedGroupingBracesBrackets}. In \cref{lst:for-each-mod1} the \texttt{foreach} command has been allowed to have \lstinline!\x/\y! and \texttt{in} between arguments because of the settings given in \cref{lst:foreach}. \end{example} \yamltitle{commandNameSpecial}*{fields} There are some special command names \announce{2018-04-27}*{commandNameSpecial} that do not fit within the names recognised by \texttt{latexindent.pl}, the first one of which is \lstinline!\@ifnextchar[!. From the perspective of \texttt{latexindent.pl}, the whole of the text \lstinline!\@ifnextchar[! is a command, because it is immediately followed by sets of mandatory arguments. However, without the \texttt{commandNameSpecial} field, \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}. \begin{cmhtcbraster}[raster column skip=.1\linewidth] \cmhlistingsfromfile{demonstrations/ifnextchar.tex}{\texttt{ifnextchar.tex}}{lst:ifnextchar} \cmhlistingsfromfile{demonstrations/ifnextchar-default.tex}{\texttt{ifnextchar.tex} default output}{lst:ifnextchar-default} \end{cmhtcbraster} Notice that in \cref{lst:ifnextchar-default} the \texttt{parbox} command has been able to indent its body, because \texttt{latexindent.pl} has successfully found the command \lstinline!\@ifnextchar! first; the pattern-matching of \texttt{latexindent.pl} starts from \emph{the inner most <thing> and works outwards}, discussed in more detail on \cpageref{page:phases}. For demonstration, we can compare this output with that given in \cref{lst:ifnextchar-off} in which the settings from \cref{lst:no-ifnextchar} have dictated that no special command names, including the \lstinline!\@ifnextchar[! command, should not be searched for specially; as such, the \texttt{parbox} command has been \emph{unable} to indent its body successfully, because the \lstinline!\@ifnextchar[! command has not been found. \begin{cmhtcbraster}[raster column skip=.1\linewidth] \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, which we state again here: \index{warning!amalgamate field} \begin{warning} It is important to note that the \texttt{amalgamate} field, if used, in either \texttt{commandNameSpecial} or \texttt{stringsAllowedBetweenArguments} must be in the first field, and specified using the syntax given in \cref{lst:amalgamate-demo1,lst:amalgamate-demo2,lst:amalgamate-demo3}. \end{warning} % arara: pdflatex: { files: [latexindent]} \renewcommand{\imagetouse}{logo} \section{The -m (modifylinebreaks) switch}\label{sec:modifylinebreaks} \fancyhead[R]{\bfseries\thepage% \tikz[remember picture,overlay] { \node at (1,0){\includegraphics{logo}}; }} All features described in this section will only be relevant if the \texttt{-m} switch is used. \startcontents[the-m-switch] \printcontents[the-m-switch]{}{0}{} \yamltitle{modifylinebreaks}*{fields} \makebox[0pt][r]{% \raisebox{-\totalheight}[0pt][0pt]{% \tikz\node[opacity=1] at (0,0) {\includegraphics[width=4cm]{logo}};}}% As of Version 3.0, \texttt{latexindent.pl} has the \texttt{-m} switch, which permits \texttt{latexindent.pl} to modify line breaks, according to the specifications in the \texttt{modifyLineBreaks} field. \emph{The settings in this field will only be considered if the \texttt{-m} switch has been used}. A snippet of the default settings of this field is shown in \cref{lst:modifylinebreaks}. \cmhlistingsfromfile[style=modifylinebreaks]{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{modifyLineBreaks}}{lst:modifylinebreaks} Having read the previous paragraph, it should sound reasonable that, if you call \texttt{latexindent.pl} using the \texttt{-m} switch, then you give it permission to modify line breaks in your file, but let's be clear: \index{warning!the m switch} \begin{warning} If you call \texttt{latexindent.pl} with the \texttt{-m} switch, then you are giving it permission to modify line breaks. By default, the only thing that will happen is that multiple blank lines will be condensed into one blank line; many other settings are possible, discussed next. \end{warning} \yamltitle{preserveBlankLines}{0|1} This field is directly related to \emph{poly-switches}, discussed in \cref{sec:poly-switches}. By default, it is set to \texttt{1}, which means that blank lines will be \emph{protected} from removal; however, regardless of this setting, multiple blank lines can be condensed if \texttt{condenseMultipleBlankLinesInto} is greater than \texttt{0}, discussed next. \yamltitle{condenseMultipleBlankLinesInto}*{positive integer} Assuming that this switch takes an integer value greater than \texttt{0}, \texttt{latexindent.pl} will condense multiple blank lines into the number of blank lines illustrated by this switch. \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! \begin{cmhtcbraster} \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 of V3.16; I hope that the interface is simpler, and most importantly, the results are better}. The complete settings for this feature are given in \cref{lst:textWrapOptionsAll}. \cmhlistingsfromfile[style=textWrapOptionsAll]{../defaultSettings.yaml}[MLB-TCB,width=.95\linewidth,before=\centering]{\texttt{textWrapOptions}}{lst:textWrapOptionsAll} \subsubsection{Text wrap: overview} An overview of how the text wrapping feature works: \begin{enumerate} \item the default value of \texttt{columns} is 0, which means that text wrapping will \emph{not} happen by default; \item it happens \emph{after} verbatim blocks have been found; \item it happens \emph{after} the oneSentencePerLine routine (see \cref{sec:onesentenceperline}); \item it can happen \emph{before} or \emph{after} \announce{2023-01-01}{text wrap: before/after} all of the other code blocks are found and does \emph{not} operate on a per-code-block basis; when using \texttt{before} this means that, including indentation, you may receive a column width wider than that which you specify in \texttt{columns}, and in which case you probably wish to explore \texttt{after} in \cref{subsubsec:tw:before:after}; \item code blocks to be text wrapped will: \begin{enumerate} \item \emph{follow} the fields specified in \texttt{blocksFollow} \item \emph{begin} with the fields specified in \texttt{blocksBeginWith} \item \emph{end} before the fields specified in \texttt{blocksEndBefore} \end{enumerate} \item setting \texttt{columns} to a value $>0$ will text wrap blocks by first removing line breaks, and then wrapping according to the specified value of \texttt{columns}; \item setting \texttt{columns} to $-1$ will \emph{only} remove line breaks within the text wrap block; \item by default, the text wrapping routine will remove line breaks within text blocks because \texttt{removeBlockLineBreaks} is set to 1; switch it to 0 if you wish to change this; \item about trailing comments within text wrap blocks: \begin{enumerate} \item trailing comments that do \emph{not} have leading space instruct the text wrap routine to connect the lines \emph{without} space (see \cref{lst:tw-tc2}); \item multiple trailing comments will be connected at the end of the text wrap block (see \cref{lst:tw-tc4}); \item the number of spaces between the end of the text wrap block and the (possibly combined) trailing comments is determined by the spaces (if any) at the end of the text wrap block (see \cref{lst:tw-tc5}); \end{enumerate} \item trailing comments can receive text wrapping \announce{2023-01-01}{text wrap trailing comments}; examples are shown in \cref{subsubsec:tw:comments} and \cref{subsubsec:ospl:tw:comments}. \end{enumerate} We demonstrate this feature using a series of examples. \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} \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} 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[style=yaml-LST]{demonstrations/textwrap1.yaml}[MLB-TCB]{\texttt{textwrap1.yaml}}{lst:textwrap1-yaml} \end{cmhtcbraster} \end{example} \begin{example} If we set \texttt{columns} to $-1$ then \texttt{latexindent.pl} remove line breaks within the text wrap block, and will \emph{not} perform text wrapping. We can use this to undo text wrapping. \index{text wrap!setting columns to -1} Starting from the file in \cref{lst:textwrap1-mod1} and using the settings in \cref{lst:textwrap1A-yaml} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/textwrap1A.yaml}[MLB-TCB]{\texttt{textwrap1A.yaml}}{lst:textwrap1A-yaml} 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} \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} 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[showspaces=true]{demonstrations/textwrap1-mod1B.tex}{\texttt{textwrap1-mod1B.tex}}{lst:textwrap1-mod1B} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/textwrap1B.yaml}[MLB-TCB]{\texttt{textwrap1B.yaml}}{lst:textwrap1B-yaml} \end{cmhtcbraster} We note that in \cref{lst:textwrap1-mod1B} the multiple spaces have \emph{not} been condensed into single spaces. \end{example} \subsubsection{Text wrap: \texttt{blocksFollow} examples} We examine the \texttt{blocksFollow} field of \cref{lst:textWrapOptionsAll}. \index{text wrap!blocksFollow} \begin{example} 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} 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} 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} \cmhlistingsfromfile{demonstrations/tw-headings1-mod2.tex}{\texttt{tw-headings1-mod2.tex}}{lst:tw-headings1-mod2} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/bf-no-headings.yaml}[MLB-TCB]{\texttt{bf-no-headings.yaml}}{lst:bf-no-headings-yaml} \end{cmhtcbraster} \end{example} \begin{example} 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} 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} 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/tw-comments1-mod2.tex}{\texttt{tw-comments1-mod2.tex}}{lst:tw-comments1-mod2} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/bf-no-comments.yaml}[MLB-TCB]{\texttt{bf-no-comments.yaml}}{lst:bf-no-comments-yaml} \end{cmhtcbraster} \end{example} Referencing \vref{lst:textWrapOptionsAll} the \texttt{blocksFollow} fields \texttt{par}, \texttt{blankline}, \texttt{verbatim} and \texttt{filecontents} fields operate in analogous ways to those demonstrated in the above. The \texttt{other} field of the \texttt{blocksFollow} can either be \texttt{0} (turned off) or set as a regular expression. The default value is set to \lstinline!\\\]|\\item(?:\h|\[)! which can be translated to \emph{backslash followed by a square bracket} or \emph{backslash item followed by horizontal space or a square 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} \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} 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} 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/tw-disp-math1-mod2.tex}{\texttt{tw-disp-math1-mod2.tex}}{lst:tw-disp-math1-mod2} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/bf-no-disp-math.yaml}[MLB-TCB]{\texttt{bf-no-disp-math.yaml}}{lst:bf-no-disp-math-yaml} \end{cmhtcbraster} Naturally, you should feel encouraged to customise this as you see fit. \end{example} The \texttt{blocksFollow} field \emph{deliberately} does not default to allowing text wrapping to occur after \texttt{begin environment} statements. You are encouraged to customize the \texttt{other} field to accommodate the environments that you would like to 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} \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} 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} 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=.01\linewidth, raster left skip=-1.5cm, raster force size=false, raster column 1/.style={add to width=-.1\textwidth}, raster column 2/.style={add to width=.1\textwidth}, ] \cmhlistingsfromfile{demonstrations/tw-bf-myenv1-mod2.tex}{\texttt{tw-bf-myenv1-mod2.tex}}{lst:tw-bf-myenv1-mod2} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/tw-bf-myenv.yaml}[MLB-TCB,width=0.6\linewidth]{\texttt{tw-bf-myenv.yaml}}{lst:tw-bf-myenv-yaml} \end{cmhtcbraster} \end{example} \subsubsection{Text wrap: \texttt{blocksBeginWith} examples} We examine the \texttt{blocksBeginWith} field of \cref{lst:textWrapOptionsAll} with a 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}. 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} occurred. \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/tw-0-9-mod2.tex}{\texttt{tw-0-9-mod2.tex}}{lst:tw-0-9-mod2} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/bb-0-9.yaml}[MLB-TCB]{\texttt{bb-0-9.yaml.yaml}}{lst:bb-0-9-yaml} \end{cmhtcbraster} \end{example} \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} 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} occurred. \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-announce1-mod2.tex}{\texttt{tw-bb-announce1-mod2.tex}}{lst:tw-bb-announce1-mod2} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/tw-bb-announce.yaml}[MLB-TCB]{\texttt{tw-bb-announce.yaml}}{lst:tw-bb-announce-yaml} \end{cmhtcbraster} \end{example} \subsubsection{Text wrap: \texttt{blocksEndBefore} examples} We examine the \texttt{blocksEndBefore} field of \cref{lst:textWrapOptionsAll} with a 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} \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} 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} 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[style=yaml-LST]{demonstrations/tw-be-equation.yaml}[MLB-TCB]{\texttt{tw-be-equation.yaml}}{lst:tw-be-equation-yaml} \begin{widepage} \cmhlistingsfromfile{demonstrations/tw-be-equation-mod2.tex}{\texttt{tw-be-equation-mod2.tex}}{lst:tw-be-equation-mod2} \end{widepage} Naturally, you should feel encouraged to customise this as you see fit. \end{example} \subsubsection{Text wrap: trailing comments and spaces} We explore the behaviour of the text wrap routine in relation to trailing comments using 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. 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} \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. 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. \end{example} \begin{example} The file in \cref{lst:tw-tc3} contains multiple trailing comments. 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} \end{example} \begin{example} The file in \cref{lst:tw-tc4} contains multiple trailing comments. 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} \end{example} \begin{example} The file in \cref{lst:tw-tc5} contains multiple trailing comments. 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. \end{example} \begin{example} The file in \cref{lst:tw-tc6} contains multiple trailing comments. 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. \end{example} \subsubsection{Text wrap: when before/after}\label{subsubsec:tw:before:after} The text wrapping routine operates, by default, \texttt{before} the \announce{2023-01-01}{text wrap: before/after details} code blocks have been found, but this can be changed to \texttt{after}: \begin{itemize} \item \texttt{before} means it is likely that the columns of wrapped text may \emph{exceed} the value specified in \texttt{columns}; \item \texttt{after} means it columns of wrapped text should \emph{not} exceed the value specified in \texttt{columns}. \end{itemize} We demonstrate this in the following examples. See also \cref{subsubsec:ospl:before:after}. \begin{example} Let's begin with the file in \cref{lst:textwrap8}. \cmhlistingsfromfile{demonstrations/textwrap8.tex}{\texttt{textwrap8.tex}}{lst:textwrap8} Using the settings given in \cref{lst:tw-before1} and running the command \begin{commandshell} latexindent.pl textwrap8.tex -o=+-mod1.tex -l=tw-before1.yaml -m \end{commandshell} gives the output given in \cref{lst:textwrap8-mod1}. \begin{cmhtcbraster}[raster columns=2, raster left skip=-1.5cm, raster right skip=-0cm, raster column skip=.06\linewidth] \cmhlistingsfromfile{demonstrations/textwrap8-mod1.tex}{\texttt{textwrap8-mod1.tex}}{lst:textwrap8-mod1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/tw-before1.yaml}[MLB-TCB,width=0.4\linewidth]{\texttt{tw-before1.yaml}}{lst:tw-before1} \end{cmhtcbraster} We note that, in \cref{lst:textwrap8-mod1}, that the wrapped text has \emph{exceeded} the specified value of \texttt{columns} (35) given in \cref{lst:tw-before1}. We can affect this by changing \texttt{when}; we explore this next. \end{example} \begin{example} We continue working with \cref{lst:textwrap8}. Using the settings given in \cref{lst:tw-after1} and running the command \begin{commandshell} latexindent.pl textwrap8.tex -o=+-mod2.tex -l=tw-after1.yaml -m \end{commandshell} gives the output given in \cref{lst:textwrap8-mod2}. \begin{cmhtcbraster}[raster columns=2, raster left skip=-1.5cm, raster right skip=-0cm, raster column skip=.06\linewidth] \cmhlistingsfromfile{demonstrations/textwrap8-mod2.tex}{\texttt{textwrap8-mod2.tex}}{lst:textwrap8-mod2} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/tw-after1.yaml}[MLB-TCB,width=0.4\linewidth]{\texttt{tw-after1.yaml}}{lst:tw-after1} \end{cmhtcbraster} We note that, in \cref{lst:textwrap8-mod2}, that the wrapped text has \emph{obeyed} the specified value of \texttt{columns} (35) given in \cref{lst:tw-after1}. \end{example} \subsubsection{Text wrap: wrapping comments}\label{subsubsec:tw:comments} You can instruct \texttt{latexindent.pl} to apply text wrapping to comments \announce{2023-01-01}{text wrap trailing comments}; we demonstrate this with examples, see also \cref{subsubsec:ospl:tw:comments}. \index{comments!text wrap} \index{text wrap!comments} \begin{example} We use the file in \cref{lst:textwrap9} which contains a trailing comment block. \cmhlistingsfromfile{demonstrations/textwrap9.tex}{\texttt{textwrap9.tex}}{lst:textwrap9} Using the settings given in \cref{lst:wrap-comments1} and running the command \begin{commandshell} latexindent.pl textwrap9.tex -o=+-mod1.tex -l=wrap-comments1.yaml -m \end{commandshell} gives the output given in \cref{lst:textwrap9-mod1}. \begin{cmhtcbraster}[raster columns=2, raster left skip=-1.5cm, raster right skip=-0cm, raster column skip=.06\linewidth] \cmhlistingsfromfile{demonstrations/textwrap9-mod1.tex}{\texttt{textwrap9-mod1.tex}}{lst:textwrap9-mod1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/wrap-comments1.yaml}[MLB-TCB,width=0.4\linewidth]{\texttt{wrap-comments1.yaml}}{lst:wrap-comments1} \end{cmhtcbraster} We note that, in \cref{lst:textwrap9-mod1}, that the comments have been \emph{combined and wrapped} because of the annotated line specified in \cref{lst:wrap-comments1}. \end{example} \begin{example} We use the file in \cref{lst:textwrap10} which contains a trailing comment block. \cmhlistingsfromfile{demonstrations/textwrap10.tex}{\texttt{textwrap10.tex}}{lst:textwrap10} Using the settings given in \cref{lst:wrap-comments1:repeat} and running the command \begin{commandshell} latexindent.pl textwrap10.tex -o=+-mod1.tex -l=wrap-comments1.yaml -m \end{commandshell} gives the output given in \cref{lst:textwrap10-mod1}. \begin{cmhtcbraster}[raster columns=2, raster left skip=-1.5cm, raster right skip=-0cm, raster column skip=.06\linewidth] \cmhlistingsfromfile{demonstrations/textwrap10-mod1.tex}{\texttt{textwrap10-mod1.tex}}{lst:textwrap10-mod1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/wrap-comments1.yaml}[MLB-TCB,width=0.4\linewidth]{\texttt{wrap-comments1.yaml}}{lst:wrap-comments1:repeat} \end{cmhtcbraster} We note that, in \cref{lst:textwrap10-mod1}, that the comments have been \emph{combined and wrapped} because of the annotated line specified in \cref{lst:wrap-comments1:repeat}, and that the space from the leading comment has not been inherited; we will explore this further in the next example. \end{example} \begin{example} We continue to use the file in \cref{lst:textwrap10}. Using the settings given in \cref{lst:wrap-comments2} and running the command \begin{commandshell} latexindent.pl textwrap10.tex -o=+-mod2.tex -l=wrap-comments2.yaml -m \end{commandshell} gives the output given in \cref{lst:textwrap10-mod2}. \begin{cmhtcbraster}[raster columns=2, raster left skip=-1.5cm, raster right skip=-0cm, raster column skip=.06\linewidth] \cmhlistingsfromfile{demonstrations/textwrap10-mod2.tex}{\texttt{textwrap10-mod2.tex}}{lst:textwrap10-mod2} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/wrap-comments2.yaml}[MLB-TCB,width=0.4\linewidth]{\texttt{wrap-comments2.yaml}}{lst:wrap-comments2} \end{cmhtcbraster} We note that, in \cref{lst:textwrap10-mod2}, that the comments have been \emph{combined and wrapped} and that the leading space has been inherited because of the annotated lines specified in \cref{lst:wrap-comments2}. \end{example} \subsubsection{Text wrap: huge, tabstop and separator} The \announce{2021-07-23}*{huge:overflow is now default} default value of \texttt{huge} is \texttt{overflow}, which means that words will \emph{not} be broken by the text wrapping routine, implemented by the \texttt{Text::Wrap} \cite{textwrap}. There are options to change the \texttt{huge} option for the \texttt{Text::Wrap} module to either \texttt{wrap} or \texttt{die}. Before modifying the value of \texttt{huge}, please bear in mind the following warning: \index{warning!changing huge (textwrap)}% \begin{warning} \raggedright Changing the value of \texttt{huge} to anything other than \texttt{overflow} will slow down \texttt{latexindent.pl} significantly when the \texttt{-m} switch is active. Furthermore, changing \texttt{huge} means that you may have some words \emph{or commands}(!) split across lines in your .tex file, which may affect your output. I do not recommend changing this field. \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] \cmhlistingsfromfile{demonstrations/textwrap4-mod2A.tex}{\texttt{textwrap4-mod2A.tex}}{lst:textwrap4-mod2A} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/textwrap2A.yaml}[MLB-TCB]{\texttt{textwrap2A.yaml}}{lst:textwrap2A-yaml} \cmhlistingsfromfile{demonstrations/textwrap4-mod2B.tex}{\texttt{textwrap4-mod2B.tex}}{lst:textwrap4-mod2B} \cmhlistingsfromfile[style=yaml-LST]{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. \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, raster right skip=-2cm, raster column skip=.03\linewidth] \cmhlistingsfromfile[showtabs=true]{demonstrations/textwrap-ts.tex}{\texttt{textwrap-ts.tex}}{lst:textwrap-ts} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/tabstop.yaml}[MLB-TCB]{\texttt{tabstop.yaml}}{lst:tabstop} \cmhlistingsfromfile[showtabs=true]{demonstrations/textwrap-ts-mod1.tex}{\texttt{textwrap-ts-mod1.tex}}{lst:textwrap-ts-mod1} \end{cmhtcbraster} \end{example} You can specify \texttt{separator}, \texttt{break} and \texttt{unexpand} options in your settings in analogous ways to those demonstrated in \cref{lst:textwrap2B-yaml,lst:tabstop}, and they will be passed to the \texttt{Text::Wrap} module. I have not found a useful reason to do this; see \cite{textwrap} for more details. % arara: pdflatex: { files: [latexindent]} \subsection{oneSentencePerLine: modifying line breaks for sentences}\label{sec:onesentenceperline} You can instruct \texttt{latexindent.pl} to format \announce{2018-01-13}{one sentence per line} your file so that it puts one sentence per line. Thank you to \cite{mlep} for helping to shape and test this feature. The behaviour of this part of the script is controlled by the switches detailed in \cref{lst:oneSentencePerLine}, all of which we discuss next. \index{modifying linebreaks! by using one sentence per line} \index{sentences!oneSentencePerLine} \index{sentences!one sentence per line} \index{regular expressions!lowercase alph a-z} \index{regular expressions!uppercase alph A-Z}% \cmhlistingsfromfile[style=oneSentencePerLine]{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{oneSentencePerLine}}{lst:oneSentencePerLine} \subsubsection{oneSentencePerLine: overview} An overview of how the oneSentencePerLine routine feature works: \begin{enumerate} \item the default value of \texttt{manipulateSentences} is 0, which means that oneSentencePerLine will \emph{not} happen by default; \item it happens \emph{after} verbatim blocks have been found; \item it happens \emph{before} the text wrapping routine (see \cref{subsec:textwrapping}); \item it happens \emph{before} the main code blocks have been found; \item sentences to be found: \begin{enumerate} \item \emph{follow} the fields specified in \texttt{sentencesFollow} \item \emph{begin} with the fields specified in \texttt{sentencesBeginWith} \item \emph{end} with the fields specified in \texttt{sentencesEndWith} \end{enumerate} \item by default, the oneSentencePerLine routine will remove line breaks within sentences because \texttt{removeBlockLineBreaks} is set to 1; switch it to 0 if you wish to change this; \item sentences can be text wrapped according to \texttt{textWrapSentences}, and will be done either \texttt{before} or \texttt{after} the main indentation routine (see \cref{subsubsec:ospl:before:after}); \item about trailing comments within text wrap blocks: \begin{enumerate} \item multiple trailing comments will be connected at the end of the sentence; \item the number of spaces between the end of the sentence and the (possibly combined) trailing comments is determined by the spaces (if any) at the end of the sentence. \end{enumerate} \end{enumerate} We demonstrate this feature using a series of examples. \yamltitle{manipulateSentences}{0|1} This is a binary switch that details if \texttt{latexindent.pl} should perform the sentence manipulation routine; it is \emph{off} (set to \texttt{0}) by default, and you will need to turn it on (by setting it to \texttt{1}) if you want the script to modify line breaks surrounding and within sentences. \yamltitle{removeSentenceLineBreaks}{0|1} When operating upon sentences \texttt{latexindent.pl} will, by default, remove internal line breaks as \texttt{removeSentenceLineBreaks} is set to \texttt{1}. Setting this switch to \texttt{0} instructs \texttt{latexindent.pl} not to do so. \index{sentences!removing sentence line breaks} \begin{example} For example, consider \texttt{multiple-sentences.tex} shown in \cref{lst:multiple-sentences}. \cmhlistingsfromfile{demonstrations/multiple-sentences.tex}{\texttt{multiple-sentences.tex}}{lst:multiple-sentences} If we use the YAML files in \cref{lst:manipulate-sentences-yaml,lst:keep-sen-line-breaks-yaml}, and run the commands \index{switches!-l demonstration} \index{switches!-m demonstration} \begin{widepage} \begin{commandshell} latexindent.pl multiple-sentences -m -l=manipulate-sentences.yaml 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}. \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/multiple-sentences-mod1.tex}{\texttt{multiple-sentences.tex} using \cref{lst:manipulate-sentences-yaml}}{lst:multiple-sentences-mod1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/manipulate-sentences.yaml}[MLB-TCB]{\texttt{manipulate-sentences.yaml}}{lst:manipulate-sentences-yaml} \end{cmhtcbraster} \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/multiple-sentences-mod2.tex}{\texttt{multiple-sentences.tex} using \cref{lst:keep-sen-line-breaks-yaml}}{lst:multiple-sentences-mod2} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/keep-sen-line-breaks.yaml}[MLB-TCB]{\texttt{keep-sen-line-breaks.yaml}}{lst:keep-sen-line-breaks-yaml} \end{cmhtcbraster} 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 one-sentence-per-line routine will convert multiple spaces into single spaces. You can change this behaviour by changing the switch \texttt{multipleSpacesToSingle} to a value of \texttt{0}. The remainder of the settings displayed in \vref{lst:oneSentencePerLine} instruct \texttt{latexindent.pl} on how to define a sentence. From the perspective of \texttt{latexindent.pl} a sentence must: \index{sentences!follow} \index{sentences!begin with} \index{sentences!end with} \begin{itemize} \item \emph{follow} a certain character or set of characters (see \cref{lst:sentencesFollow}); by default, this is either \lstinline!\par!, a blank line, a full stop/period (.), exclamation mark (!), question mark (?) right brace (\}) or a comment on the previous line; \item \emph{begin} with a character type (see \cref{lst:sentencesBeginWith}); by default, this is only capital letters; \item \emph{end} with a character (see \cref{lst:sentencesEndWith}); by default, these are full stop/period (.), exclamation mark (!) and question mark (?). \end{itemize} In each case, you can specify the \texttt{other} field to include any pattern that you would like; you can specify anything in this field using the language of regular expressions. \index{regular expressions!lowercase alph a-z} \index{regular expressions!uppercase alph A-Z} \begin{cmhtcbraster}[raster columns=2, raster left skip=-3.5cm, raster right skip=-2cm, raster column skip=.06\linewidth] \cmhlistingsfromfile[style=sentencesFollow]{../defaultSettings.yaml}[MLB-TCB,width=.9\linewidth,before=\centering]{\texttt{sentencesFollow}}{lst:sentencesFollow} \cmhlistingsfromfile[style=sentencesBeginWith]{../defaultSettings.yaml}[MLB-TCB,width=.9\linewidth,before=\centering]{\texttt{sentencesBeginWith}}{lst:sentencesBeginWith} \end{cmhtcbraster} \cmhlistingsfromfile[style=sentencesEndWith]{../defaultSettings.yaml}[MLB-TCB,width=.9\linewidth,before=\centering]{\texttt{sentencesEndWith}}{lst:sentencesEndWith} \subsubsection{oneSentencePerLine: sentencesFollow} Let's explore a few of the switches in \texttt{sentencesFollow}. \begin{example} 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} \cmhlistingsfromfile{demonstrations/multiple-sentences-mod3.tex}{\texttt{multiple-sentences.tex} using \cref{lst:sentences-follow1-yaml}}{lst:multiple-sentences-mod3} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/sentences-follow1.yaml}[MLB-TCB]{\texttt{sentences-follow1.yaml}}{lst:sentences-follow1-yaml} \end{cmhtcbraster} 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}. \cmhlistingsfromfile{demonstrations/multiple-sentences1.tex}{\texttt{multiple-sentences1.tex}}{lst:multiple-sentences1} Upon running the following commands \index{switches!-l demonstration} \index{switches!-m demonstration} \begin{widepage} \begin{commandshell} latexindent.pl multiple-sentences1 -m -l=manipulate-sentences.yaml 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}. \cmhlistingsfromfile{demonstrations/multiple-sentences1-mod1.tex}{\texttt{multiple-sentences1.tex} using \vref{lst:manipulate-sentences-yaml}}{lst:multiple-sentences1-mod1} \begin{cmhtcbraster}[ raster force size=false, raster column 1/.style={add to width=1cm}, ] \cmhlistingsfromfile{demonstrations/multiple-sentences1-mod2.tex}{\texttt{multiple-sentences1.tex} using \cref{lst:sentences-follow2-yaml}}{lst:multiple-sentences1-mod2} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/sentences-follow2.yaml}[MLB-TCB,width=.45\textwidth]{\texttt{sentences-follow2.yaml}}{lst:sentences-follow2-yaml} \end{cmhtcbraster} Notice that in \cref{lst:multiple-sentences1-mod1} the first sentence after the \texttt{)} has not been accounted for, but that following the inclusion of \cref{lst:sentences-follow2-yaml}, the output given in \cref{lst:multiple-sentences1-mod2} demonstrates that the sentence \emph{has} been accounted for correctly. \end{example} \subsubsection{oneSentencePerLine: sentencesBeginWith} By default, \texttt{latexindent.pl} will only assume that sentences begin with the upper case letters \texttt{A-Z}; you can instruct the script to define sentences to begin with lower case letters (see \cref{lst:sentencesBeginWith}), and we can use the \texttt{other} field to define sentences to begin with other characters. \index{sentences!begin with} \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}. \cmhlistingsfromfile{demonstrations/multiple-sentences2-mod1.tex}{\texttt{multiple-sentences2.tex} using \vref{lst:manipulate-sentences-yaml}}{lst:multiple-sentences2-mod1} \index{regular expressions!numeric 0-9} \begin{cmhtcbraster}[ raster force size=false, raster column 1/.style={add to width=1cm}, ] \cmhlistingsfromfile{demonstrations/multiple-sentences2-mod2.tex}{\texttt{multiple-sentences2.tex} using \cref{lst:sentences-begin1-yaml}}{lst:multiple-sentences2-mod2} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/sentences-begin1.yaml}[MLB-TCB,width=.45\textwidth]{\texttt{sentences-begin1.yaml}}{lst:sentences-begin1-yaml} \end{cmhtcbraster} Notice that in \cref{lst:multiple-sentences2-mod1}, the first sentence has been accounted for but that the subsequent sentences have not. In \cref{lst:multiple-sentences2-mod2}, all of the sentences have been accounted for, because the \texttt{other} field in \cref{lst:sentences-begin1-yaml} has defined sentences to begin with either \lstinline!$! or any numeric digit, \texttt{0} to \texttt{9}. \end{example} \subsubsection{oneSentencePerLine: sentencesEndWith} \begin{example} Let's return to \vref{lst:multiple-sentences}; we have already seen the default way in which \texttt{latexindent.pl} will operate on the sentences in this file in \vref{lst:multiple-sentences-mod1}. We can populate the \texttt{other} field with any character that we wish; for example, using the YAML specified in \cref{lst:sentences-end1-yaml} and the command \index{sentences!end with} \index{switches!-l demonstration} \index{switches!-m demonstration} \begin{commandshell} latexindent.pl multiple-sentences -m -l=sentences-end1.yaml latexindent.pl multiple-sentences -m -l=sentences-end2.yaml \end{commandshell} then we obtain the output in \cref{lst:multiple-sentences-mod4}. \index{regular expressions!lowercase alph a-z} \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/multiple-sentences-mod4.tex}{\texttt{multiple-sentences.tex} using \cref{lst:sentences-end1-yaml}}{lst:multiple-sentences-mod4} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/sentences-end1.yaml}[MLB-TCB]{\texttt{sentences-end1.yaml}}{lst:sentences-end1-yaml} \end{cmhtcbraster} \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/multiple-sentences-mod5.tex}{\texttt{multiple-sentences.tex} using \cref{lst:sentences-end2-yaml}}{lst:multiple-sentences-mod5} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/sentences-end2.yaml}[MLB-TCB]{\texttt{sentences-end2.yaml}}{lst:sentences-end2-yaml} \end{cmhtcbraster} There is a subtle difference between the output in \cref{lst:multiple-sentences-mod4,lst:multiple-sentences-mod5}; in particular, in \cref{lst:multiple-sentences-mod4} the word \texttt{sentence} has not been defined as a sentence, because we have not instructed \texttt{latexindent.pl} to begin sentences with lower case letters. We have changed this by using the settings in \cref{lst:sentences-end2-yaml}, and the associated output in \cref{lst:multiple-sentences-mod5} reflects this. \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} 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} Notice that the full stop within the url has been interpreted correctly. This is because, within the \texttt{betterFullStop}, full stops at the end of sentences have the following properties: \begin{itemize} \item they are ignored within \texttt{e.g.} and \texttt{i.e.}; \item they can not be immediately followed by a lower case or upper case letter; \item they can not be immediately followed by a hyphen, comma, or number. \end{itemize} \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 seek to customise the \texttt{betterFullStop} routine by using the \emph{fine tuning}, detailed in \vref{lst:fineTuning}.% The \texttt{basicFullStop} routine should probably be avoided in most situations, as it 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, raster right skip=-2cm, raster force size=false, raster column 1/.style={add to width=.1\textwidth}, raster column skip=.06\linewidth] \cmhlistingsfromfile{demonstrations/url-mod2.tex}{\texttt{url.tex} using \cref{lst:alt-full-stop1-yaml}}{lst:url-mod2} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/alt-full-stop1.yaml}[MLB-TCB,width=.5\textwidth]{\texttt{alt-full-stop1.yaml}}{lst:alt-full-stop1-yaml} \end{cmhtcbraster} 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{oneSentencePerLine: sentencesDoNOTcontain} You can specify patterns that sentences do \emph{not} contain using the field \announce{2023-09-09}{oneSentencePerLine: sentencesDoNOTcontain} in \cref{lst:sentencesDoNOTcontain}. \cmhlistingsfromfile[style=sentencesDoNOTcontain]{../defaultSettings.yaml}[MLB-TCB,width=.9\linewidth,before=\centering]{\texttt{sentencesDoNOTcontain}}{lst:sentencesDoNOTcontain} If sentences run across environments then, by default, they will \emph{not} be considered a sentence by \texttt{latexindent.pl}. \announce{2023-09-09}*{updated example of oneSentencePerLine} \begin{example} For example, if we use the \texttt{.tex} file in \cref{lst:multiple-sentences4} \cmhlistingsfromfile{demonstrations/multiple-sentences4.tex}{\texttt{multiple-sentences4.tex}}{lst:multiple-sentences4} and run the command \index{switches!-l demonstration} \index{switches!-m demonstration} \begin{commandshell} latexindent.pl multiple-sentences4 -m -l=manipulate-sentences.yaml \end{commandshell} then the output is unchanged, because the default value of \texttt{sentencesDoNOTcontain} says, \emph{sentences do NOT contain} This means that, by default, \texttt{latexindent.pl} does \emph{not} consider the file in \cref{lst:multiple-sentences4} to have a sentence. \lstinline!\\begin! \end{example} \begin{example} We can customise the \texttt{sentencesDoNOTcontain} field with anything that we do \emph{not} want sentences to contain. We begin with the file in \cref{lst:sentence-dnc1}. \cmhlistingsfromfile{demonstrations/sentence-dnc1.tex}{\texttt{sentence-dnc1.tex}}{lst:sentence-dnc1} Upon running the following commands \begin{commandshell} latexindent.pl sentence-dnc1.tex -m -l=dnc1.yaml \end{commandshell} then we obtain the output given in \cref{lst:sentence-dnc1-mod1}. \begin{cmhtcbraster}[ raster left skip=-2.5cm, raster right skip=-1cm, raster force size=false, raster column 1/.style={add to width=3cm}, ] \cmhlistingsfromfile{demonstrations/sentence-dnc1-mod1.tex}{\texttt{sentence-dnc1-mod1.tex}}{lst:sentence-dnc1-mod1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/dnc1.yaml}[MLB-TCB,width=.45\textwidth]{\texttt{dnc1.yaml}}{lst:dnc1-yaml} \end{cmhtcbraster} The settings in \cref{lst:dnc1-yaml} say that sentences do \emph{not} contain \lstinline!\begin! and that they do not contain \lstinline!\cmh! \end{example} \begin{example} We can implement case insensitivity for the \texttt{sentencesDoNOTcontain} field. We begin with the file in \cref{lst:sentence-dnc2}. \cmhlistingsfromfile{demonstrations/sentence-dnc2.tex}{\texttt{sentence-dnc2.tex}}{lst:sentence-dnc2} Upon running the following commands \begin{commandshell} latexindent.pl sentence-dnc2.tex -m -l=dnc2.yaml \end{commandshell} then we obtain the output given in \cref{lst:sentence-dnc2-mod2}. \begin{cmhtcbraster}[ raster left skip=-2.5cm, raster right skip=-1cm, raster force size=false, raster column 1/.style={add to width=3cm}, ] \cmhlistingsfromfile{demonstrations/sentence-dnc2-mod2.tex}{\texttt{sentence-dnc2-mod2.tex}}{lst:sentence-dnc2-mod2} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/dnc2.yaml}[MLB-TCB,width=.45\textwidth]{\texttt{dnc2.yaml}}{lst:dnc2-yaml} \end{cmhtcbraster} The settings in \cref{lst:dnc2-yaml} say that sentences do \emph{not} contain \lstinline!\begin! and that they do not contain \emph{case insensitive} versions of \lstinline!\cmh! \end{example} \begin{example} We can turn off \texttt{sentenceDoNOTcontain} by setting it to \texttt{0} as in \cref{lst:dnc-off-yaml}. \cmhlistingsfromfile[style=yaml-LST]{demonstrations/dnc-off.yaml}[MLB-TCB,width=.45\textwidth]{\texttt{dnc-off.yaml}}{lst:dnc-off-yaml} The settings in \cref{lst:dnc-off-yaml} mean that sentences can contain any character. \end{example} \subsubsection{Features of the oneSentencePerLine routine} The sentence manipulation routine takes place \emph{after} verbatim \index{verbatim!in relation to oneSentencePerLine} environments, preamble and trailing comments have been accounted for; this means that any characters within these types of code blocks will not be part of the sentence manipulation routine. \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} \subsubsection{oneSentencePerLine: text wrapping and indenting sentences} The \texttt{oneSentencePerLine} \announce{2018-08-13}{oneSentencePerline text wrap and indent} can be instructed to perform text wrapping and indentation upon sentences. \index{sentences!text wrapping} \index{sentences!indenting}% \begin{example} Let's use the code in \cref{lst:multiple-sentences5}. \cmhlistingsfromfile{demonstrations/multiple-sentences5.tex}{\texttt{multiple-sentences5.tex}}{lst:multiple-sentences5} Referencing \cref{lst:sentence-wrap1-yaml}, and running the following command \index{switches!-l demonstration} \index{switches!-m demonstration} \begin{commandshell} latexindent.pl multiple-sentences5 -m -l=sentence-wrap1.yaml \end{commandshell} we receive the output given in \cref{lst:multiple-sentences5-mod1}. \begin{cmhtcbraster}[ raster left skip=-3.5cm, raster right skip=-2cm, raster force size=false, raster column 1/.style={add to width=.1\textwidth}, raster column skip=.06\linewidth] \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}. \cmhlistingsfromfile{demonstrations/multiple-sentences6.tex}{\texttt{multiple-sentences6.tex}}{lst:multiple-sentences6} 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}. \cmhlistingsfromfile{demonstrations/multiple-sentences6-mod1.tex}{\texttt{multiple-sentences6-mod1.tex} using \cref{lst:sentence-wrap1-yaml}}{lst:multiple-sentences6-mod1} \cmhlistingsfromfile{demonstrations/multiple-sentences6-mod2.tex}{\texttt{multiple-sentences6-mod2.tex} using \cref{lst:sentence-wrap1-yaml} and no sentence indentation}{lst:multiple-sentences6-mod2} We note that \cref{lst:multiple-sentences6-mod1} the \texttt{itemize} code block has \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}. This setting is actually an appended version of the \texttt{betterFullStop} from the \texttt{fineTuning}, detailed in \vref{lst:fineTuning}. \index{regular expressions!lowercase alph a-z} \index{regular expressions!uppercase alph A-Z} \index{regular expressions!numeric 0-9} \index{regular expressions!horizontal space \textbackslash{h}} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/itemize.yaml}[enhanced jigsaw,breakable,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} 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 text wrapping, from the value of \texttt{removeSentenceLineBreaks}. \subsubsection{oneSentencePerLine: text wrapping and indenting sentences, when before/after}\label{subsubsec:ospl:before:after} The text wrapping routine operates, by default, \texttt{before} the \announce{2023-01-01}{text wrap: before/after details} code blocks have been found, but this can be changed to \texttt{after}: \begin{itemize} \item \texttt{before} means it is likely that the columns of wrapped text may \emph{exceed} the value specified in \texttt{columns}; \item \texttt{after} means it columns of wrapped text should \emph{not} exceed the value specified in \texttt{columns}. \end{itemize} We demonstrate this in the following examples. See also \cref{subsubsec:tw:before:after}. \begin{example} Let's begin with the file in \cref{lst:multiple-sentences8}. \cmhlistingsfromfile{demonstrations/multiple-sentences8.tex}{\texttt{multiple-sentences8.tex}}{lst:multiple-sentences8} Using the settings given in \cref{lst:sentence-wrap2} and running the command \begin{commandshell} latexindent.pl multiple-sentences8 -o=+-mod1.tex -l=sentence-wrap2 -m \end{commandshell} gives the output given in \cref{lst:multiple-sentences8-mod1}. \begin{cmhtcbraster}[raster columns=2, raster left skip=-1.5cm, raster right skip=-0cm, raster column skip=.06\linewidth] \cmhlistingsfromfile{demonstrations/multiple-sentences8-mod1.tex}{\texttt{multiple-sentences8-mod1.tex}}{lst:multiple-sentences8-mod1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/sentence-wrap2.yaml}[MLB-TCB,width=0.4\linewidth]{\texttt{sentence-wrap2.yaml}}{lst:sentence-wrap2} \end{cmhtcbraster} We note that, in \cref{lst:multiple-sentences8-mod1}, that the wrapped text has \emph{exceeded} the specified value of \texttt{columns} (35) given in \cref{lst:sentence-wrap2}. We can affect this by changing \texttt{when}; we explore this next. \end{example} \begin{example} We continue working with \cref{lst:multiple-sentences8}. Using the settings given in \cref{lst:sentence-wrap3} and running the command \begin{commandshell} latexindent.pl multiple-sentences8.tex -o=+-mod2.tex -l=sentence-wrap3 -m \end{commandshell} gives the output given in \cref{lst:multiple-sentences8-mod2}. \begin{cmhtcbraster}[raster columns=2, raster left skip=-1.5cm, raster right skip=-0cm, raster column skip=.06\linewidth] \cmhlistingsfromfile{demonstrations/multiple-sentences8-mod2.tex}{\texttt{multiple-sentences8-mod2.tex}}{lst:multiple-sentences8-mod2} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/sentence-wrap3.yaml}[MLB-TCB,width=0.4\linewidth]{\texttt{sentence-wrap3.yaml}}{lst:sentence-wrap3} \end{cmhtcbraster} We note that, in \cref{lst:multiple-sentences8-mod2}, that the wrapped text has \emph{obeyed} the specified value of \texttt{columns} (35) given in \cref{lst:sentence-wrap3}. \end{example} \subsubsection{oneSentencePerLine: text wrapping sentences and comments}\label{subsubsec:ospl:tw:comments} We demonstrate the one sentence per line routine with respect to text wrapping \emph{comments}. See also \cref{subsubsec:tw:comments}. \index{comments!text wrap} \index{text wrap!comments} \index{sentences!comments} \index{sentences!text wrap} \begin{example} Let's begin with the file in \cref{lst:multiple-sentences9}. \cmhlistingsfromfile{demonstrations/multiple-sentences9.tex}{\texttt{multiple-sentences9.tex}}{lst:multiple-sentences9} Using the settings given in \cref{lst:sentence-wrap4} and running the command \begin{commandshell} latexindent.pl multiple-sentences9 -o=+-mod1.tex -l=sentence-wrap4 -m \end{commandshell} gives the output given in \cref{lst:multiple-sentences9-mod1}. \begin{cmhtcbraster}[raster columns=2, raster left skip=-1.5cm, raster right skip=-0cm, raster column skip=.06\linewidth] \cmhlistingsfromfile{demonstrations/multiple-sentences9-mod1.tex}{\texttt{multiple-sentences9-mod1.tex}}{lst:multiple-sentences9-mod1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/sentence-wrap4.yaml}[MLB-TCB,width=0.4\linewidth]{\texttt{sentence-wrap4.yaml}}{lst:sentence-wrap4} \end{cmhtcbraster} We note that, in \cref{lst:multiple-sentences9-mod1}, that the sentences have been wrapped, and so too have the comments because of the annotated line in \cref{lst:sentence-wrap4}. \end{example} % arara: pdflatex: { files: [latexindent]} \subsection{Poly-switches}\label{sec:poly-switches} Every other field in the \texttt{modifyLineBreaks} field uses poly-switches, and can take one of the following% \announce{2017-08-21}*{blank line poly-switch} integer values: \index{modifying linebreaks! using poly-switches} \index{poly-switches!definition} \index{poly-switches!values} \index{poly-switches!off by default: set to 0} \begin{description} \item[$-1$] \emph{remove mode}: line breaks before or after the \emph{<part of thing>} can be removed (assuming that \texttt{preserveBlankLines} is set to \texttt{0}); \item[0] \emph{off mode}: line breaks will not be modified for the \emph{<part of thing>} under consideration; \item[1] \emph{add mode}: a line break will be added before or after the \emph{<part of thing>} under consideration, assuming that there is not already a line break before or after the \emph{<part of thing>}; \item[2] \emph{comment then add mode}: a comment symbol will be added, followed by a line break before or after the \emph{<part of thing>} under consideration, assuming that there is not already a comment and line break before or after the \emph{<part of thing>}; \item[3] \emph{add then blank line mode}% \announce{2017-08-21}{blank line poly-switch}: a line break will be added before or after the \emph{<part of thing>} under consideration, assuming that there is not already a line break before or after the \emph{<part of thing>}, followed by a blank line; \item[4] \emph{add blank line mode}% \announce{2019-07-13}{blank line poly-switch}; a blank line will be added before or after the \emph{<part of thing>} under consideration, even if the \emph{<part of thing>} is already on its own line. \end{description} In the above, \emph{<part of thing>} refers to either the \emph{begin statement}, \emph{body} or \emph{end statement} of the code blocks detailed in \vref{tab:code-blocks}. All poly-switches are \emph{off} by default; \texttt{latexindent.pl} searches first of all for per-name settings, and then followed by global per-thing settings. \subsubsection{Poly-switches for environments}\label{sec:modifylinebreaks-environments} We start by viewing a snippet of \texttt{defaultSettings.yaml} in \cref{lst:environments-mlb}; note that it contains \emph{global} settings (immediately after the \texttt{environments} field) and that \emph{per-name} settings are also allowed -- in the case of \cref{lst:environments-mlb}, settings for \texttt{equation*} have been specified for demonstration. Note that all poly-switches are \emph{off} (set to 0) by default. \index{poly-switches!default values} \index{poly-switches!environment global example} \index{poly-switches!environment per-code block example} \cmhlistingsfromfile[style=modifylinebreaksEnv]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,MLB-TCB]{\texttt{environments}}{lst:environments-mlb} Let's begin with the simple example given in \cref{lst:env-mlb1-tex}; note that we have annotated key parts of the file using $\BeginStartsOnOwnLine$, $\BodyStartsOnOwnLine$, $\EndStartsOnOwnLine$ and $\EndFinishesWithLineBreak$, these will be related to fields specified in \cref{lst:environments-mlb}. \index{poly-switches!visualisation: $\BeginStartsOnOwnLine$, $\BodyStartsOnOwnLine$, $\EndStartsOnOwnLine$, $\EndFinishesWithLineBreak$} \begin{cmhlistings}[style=tcblatex,escapeinside={(*@}{@*)}]{\texttt{env-mlb1.tex}}{lst:env-mlb1-tex} before words(*@$\BeginStartsOnOwnLine$@*) \begin{myenv}(*@$\BodyStartsOnOwnLine$@*)body of myenv(*@$\EndStartsOnOwnLine$@*)\end{myenv}(*@$\EndFinishesWithLineBreak$@*) after words \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{cmhtcbraster} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb1.yaml}[MLB-TCB]{\texttt{env-mlb1.yaml}}{lst:env-mlb1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb2.yaml}[MLB-TCB]{\texttt{env-mlb2.yaml}}{lst:env-mlb2} \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} \begin{minipage}{.56\linewidth} \cmhlistingsfromfile{demonstrations/env-mlb-mod1.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb1}}{lst:env-mlb-mod1} \end{minipage} \hfill \begin{minipage}{.43\linewidth} \cmhlistingsfromfile{demonstrations/env-mlb-mod2.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb2}}{lst:env-mlb-mod2} \end{minipage} \end{widepage} There are a couple of points to note: \begin{itemize} \item in \cref{lst:env-mlb-mod1} a line break has been added at the point denoted by $\BeginStartsOnOwnLine$ in \cref{lst:env-mlb1-tex}; no other line breaks have been changed; \item in \cref{lst:env-mlb-mod2} a line break has been added at the point denoted by $\BodyStartsOnOwnLine$ in \cref{lst:env-mlb1-tex}; furthermore, note that the \emph{body} of \texttt{myenv} has received the appropriate (default) indentation. \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{cmhtcbraster} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb3.yaml}[MLB-TCB]{\texttt{env-mlb3.yaml}}{lst:env-mlb3} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb4.yaml}[MLB-TCB]{\texttt{env-mlb4.yaml}}{lst:env-mlb4} \end{cmhtcbraster} Upon running the commands \begin{commandshell} latexindent.pl -m env-mlb.tex -l env-mlb3.yaml latexindent.pl -m env-mlb.tex -l env-mlb4.yaml \end{commandshell} we obtain \cref{lst:env-mlb-mod3,lst:env-mlb-mod4}. \begin{widepage} \begin{minipage}{.56\linewidth} \cmhlistingsfromfile{demonstrations/env-mlb-mod3.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb3}}{lst:env-mlb-mod3} \end{minipage} \hfill \begin{minipage}{.43\linewidth} \cmhlistingsfromfile{demonstrations/env-mlb-mod4.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb4}}{lst:env-mlb-mod4} \end{minipage} \end{widepage} Note that line breaks have been added as in \cref{lst:env-mlb-mod1,lst:env-mlb-mod2}, but this time a comment symbol has been added before adding the line break; in both cases, trailing horizontal space has been stripped before doing so. \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 $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{cmhtcbraster} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb5.yaml}[MLB-TCB]{\texttt{env-mlb5.yaml}}{lst:env-mlb5} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb6.yaml}[MLB-TCB]{\texttt{env-mlb6.yaml}}{lst:env-mlb6} \end{cmhtcbraster} Upon running the commands \begin{commandshell} latexindent.pl -m env-mlb.tex -l env-mlb5.yaml latexindent.pl -m env-mlb.tex -l env-mlb6.yaml \end{commandshell} we obtain \cref{lst:env-mlb-mod5,lst:env-mlb-mod6}. \begin{widepage} \begin{minipage}{.56\linewidth} \cmhlistingsfromfile{demonstrations/env-mlb-mod5.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb5}}{lst:env-mlb-mod5} \end{minipage} \hfill \begin{minipage}{.43\linewidth} \cmhlistingsfromfile{demonstrations/env-mlb-mod6.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb6}}{lst:env-mlb-mod6} \end{minipage} \end{widepage} Note that line breaks have been added as in \cref{lst:env-mlb-mod1,lst:env-mlb-mod2}, but this time a \emph{blank line} has been added after adding the line break. \end{example} \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{cmhtcbraster} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-beg4.yaml}[MLB-TCB]{\texttt{env-beg4.yaml}}{lst:env-beg4} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-body4.yaml}[MLB-TCB]{\texttt{env-body4.yaml}}{lst:env-body4} \end{cmhtcbraster} We will demonstrate this poly-switch value using the code in \cref{lst:env-mlb1-text}. \cmhlistingsfromfile{demonstrations/env-mlb1.tex}{\texttt{env-mlb1.tex}}{lst:env-mlb1-text} Upon running the commands \index{switches!-l demonstration} \index{switches!-m demonstration} \begin{commandshell} latexindent.pl -m env-mlb1.tex -l env-beg4.yaml latexindent.pl -m env-mlb.1tex -l env-body4.yaml \end{commandshell} then we receive the respective outputs in \cref{lst:env-mlb1-beg4,lst:env-mlb1-body4}. \begin{cmhtcbraster}[raster column skip=.1\linewidth] \cmhlistingsfromfile{demonstrations/env-mlb1-beg4.tex}{\texttt{env-mlb1.tex} using \cref{lst:env-beg4}}{lst:env-mlb1-beg4} \cmhlistingsfromfile{demonstrations/env-mlb1-body4.tex}{\texttt{env-mlb1.tex} using \cref{lst:env-body4}}{lst:env-mlb1-body4} \end{cmhtcbraster} We note in particular that, by design, for this value of the poly-switches: \begin{enumerate} \item in \cref{lst:env-mlb1-beg4} a blank line has been inserted before the \lstinline!\begin! statement, even though the \lstinline!\begin! statement was already on its own line; \item in \cref{lst:env-mlb1-body4} a blank line has been inserted before the beginning of the \emph{body}, even though it already began on its own line. \end{enumerate} \end{example} \paragraph{Adding line breaks: EndStartsOnOwnLine and EndFinishesWithLineBreak} \begin{example} Let's explore \texttt{EndStartsOnOwnLine} and \texttt{EndFinishesWithLineBreak} in \cref{lst:env-mlb7,lst:env-mlb8}, and in particular, let's allow each of them in turn to take a value of $1$. \index{modifying linebreaks! at the \emph{end} of a code block} \index{poly-switches!adding line breaks: set to 1} \begin{cmhtcbraster} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb7.yaml}[MLB-TCB]{\texttt{env-mlb7.yaml}}{lst:env-mlb7} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb8.yaml}[MLB-TCB]{\texttt{env-mlb8.yaml}}{lst:env-mlb8} \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{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} \item in \cref{lst:env-mlb-mod7} a line break has been added at the point denoted by $\EndStartsOnOwnLine$ in \vref{lst:env-mlb1-tex}; no other line breaks have been changed and the \lstinline!\end{myenv}! statement has \emph{not} received indentation (as intended); \item in \cref{lst:env-mlb-mod8} a line break has been added at the point denoted by $\EndFinishesWithLineBreak$ in \vref{lst:env-mlb1-tex}. \end{itemize} \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{cmhtcbraster} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb9.yaml}[MLB-TCB]{\texttt{env-mlb9.yaml}}{lst:env-mlb9} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb10.yaml}[MLB-TCB]{\texttt{env-mlb10.yaml}}{lst:env-mlb10} \end{cmhtcbraster} Upon running the commands \begin{commandshell} latexindent.pl -m env-mlb.tex -l env-mlb9.yaml latexindent.pl -m env-mlb.tex -l env-mlb10.yaml \end{commandshell} we obtain \cref{lst:env-mlb-mod9,lst:env-mlb-mod10}. \begin{widepage} \begin{minipage}{.43\linewidth} \cmhlistingsfromfile{demonstrations/env-mlb-mod9.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb9}}{lst:env-mlb-mod9} \end{minipage} \hfill \begin{minipage}{.56\linewidth} \cmhlistingsfromfile{demonstrations/env-mlb-mod10.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb10}}{lst:env-mlb-mod10} \end{minipage} \end{widepage} Note that line breaks have been added as in \cref{lst:env-mlb-mod7,lst:env-mlb-mod8}, but this time a comment symbol has been added before adding the line break; in both cases, trailing horizontal space has been stripped before doing so. \end{example} \begin{example} Let's now change each of the \texttt{1} values in \cref{lst:env-mlb7,lst:env-mlb8} so that they are $3$ and save them into \texttt{env-mlb11.yaml} and \texttt{env-mlb12.yaml} respectively (see \cref{lst:env-mlb11,lst:env-mlb12}). \index{poly-switches!adding blank lines: set to 3}\announce{2017-08-21}{demonstration of blank line poly-switch (3)}% \begin{cmhtcbraster} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb11.yaml}[MLB-TCB]{\texttt{env-mlb11.yaml}}{lst:env-mlb11} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb12.yaml}[MLB-TCB]{\texttt{env-mlb12.yaml}}{lst:env-mlb12} \end{cmhtcbraster} Upon running the commands \begin{commandshell} latexindent.pl -m env-mlb.tex -l env-mlb11.yaml latexindent.pl -m env-mlb.tex -l env-mlb12.yaml \end{commandshell} we obtain \cref{lst:env-mlb-mod11,lst:env-mlb-mod12}. \begin{widepage} \begin{minipage}{.42\linewidth} \cmhlistingsfromfile{demonstrations/env-mlb-mod11.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb11}}{lst:env-mlb-mod11} \end{minipage} \hfill \begin{minipage}{.57\linewidth} \cmhlistingsfromfile{demonstrations/env-mlb-mod12.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb12}}{lst:env-mlb-mod12} \end{minipage} \end{widepage} Note that line breaks have been added as in \cref{lst:env-mlb-mod7,lst:env-mlb-mod8}, and that a \emph{blank line} has been added after the line break. \end{example} \begin{example} Let's now change each of the \texttt{1} values in \cref{lst:env-mlb11,lst:env-mlb12} so that they are $4$ and save them into \texttt{env-end4.yaml} and \texttt{env-end-f4.yaml} respectively (see \cref{lst:env-end4,lst:env-end-f4}). \announce{2019-07-13}{demonstration of new blank line poly-switch} \index{poly-switches!adding blank lines (again"!): set to 4}% \begin{cmhtcbraster} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-end4.yaml}[MLB-TCB]{\texttt{env-end4.yaml}}{lst:env-end4} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-end-f4.yaml}[MLB-TCB]{\texttt{env-end-f4.yaml}}{lst:env-end-f4} \end{cmhtcbraster} We will demonstrate this poly-switch value using the code from \vref{lst:env-mlb1-text}. 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 \end{commandshell} then we receive the respective outputs in \cref{lst:env-mlb1-end4,lst:env-mlb1-end-f4}. \begin{cmhtcbraster}[raster column skip=.1\linewidth] \cmhlistingsfromfile{demonstrations/env-mlb1-end4.tex}{\texttt{env-mlb1.tex} using \cref{lst:env-end4}}{lst:env-mlb1-end4} \cmhlistingsfromfile{demonstrations/env-mlb1-end-f4.tex}{\texttt{env-mlb1.tex} using \cref{lst:env-end-f4}}{lst:env-mlb1-end-f4} \end{cmhtcbraster} We note in particular that, by design, for this value of the poly-switches: \begin{enumerate} \item in \cref{lst:env-mlb1-end4} a blank line has been inserted before the \lstinline!\end! statement, even though the \lstinline!\end! statement was already on its own line; \item in \cref{lst:env-mlb1-end-f4} a blank line has been inserted after the \lstinline!\end! statement, even though it already began on its own line. \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. \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} \cmhlistingsfromfile{demonstrations/env-mlb3.tex}{\texttt{env-mlb3.tex}}{lst:mlb3} \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 \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 \texttt{BodyStartsOnOwnLine} is set to \texttt{1}. In \cref{lst:env-mlb3-mod4} you'll see that the comment has been accounted for correctly because \texttt{BodyStartsOnOwnLine} has been set to \texttt{2}, and the comment symbol has \emph{not} been moved to its own line. You're encouraged to experiment with \cref{lst:mlb3} and by setting the other poly-switches considered so far to \texttt{2} in turn. \begin{cmhtcbraster}[raster column skip=.1\linewidth] \cmhlistingsfromfile{demonstrations/env-mlb3-mod2.tex}{\texttt{env-mlb3.tex} using \vref{lst:env-mlb2}}{lst:env-mlb3-mod2} \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 \emph{per-name} basis, which would take priority over the global values; with reference to \vref{lst:environments-mlb}, an example is shown for the \texttt{equation*} environment. \paragraph{Removing line breaks (poly-switches set to $-1$)} Setting poly-switches to $-1$ tells \texttt{latexindent.pl} to remove line breaks of the \emph{<part of the thing>}, if necessary. \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$@*) \begin{myenv}(*@$\BodyStartsOnOwnLine$@*) body of myenv(*@$\EndStartsOnOwnLine$@*) \end{myenv}(*@$\EndFinishesWithLineBreak$@*) after words \end{cmhlistings} \end{minipage}% \hfill \begin{minipage}{.51\textwidth} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb13.yaml}[MLB-TCB]{\texttt{env-mlb13.yaml}}{lst:env-mlb13} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb14.yaml}[MLB-TCB]{\texttt{env-mlb14.yaml}}{lst:env-mlb14} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb15.yaml}[MLB-TCB]{\texttt{env-mlb15.yaml}}{lst:env-mlb15} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb16.yaml}[MLB-TCB]{\texttt{env-mlb16.yaml}}{lst:env-mlb16} \end{minipage} After running the commands \index{switches!-l demonstration} \index{switches!-m demonstration} \begin{commandshell} latexindent.pl -m env-mlb4.tex -l env-mlb13.yaml latexindent.pl -m env-mlb4.tex -l env-mlb14.yaml latexindent.pl -m env-mlb4.tex -l env-mlb15.yaml latexindent.pl -m env-mlb4.tex -l env-mlb16.yaml \end{commandshell} we obtain the respective output in \crefrange{lst:env-mlb4-mod13}{lst:env-mlb4-mod16}. \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/env-mlb4-mod13.tex}{\texttt{env-mlb4.tex} using \cref{lst:env-mlb13}}{lst:env-mlb4-mod13} \cmhlistingsfromfile{demonstrations/env-mlb4-mod14.tex}{\texttt{env-mlb4.tex} using \cref{lst:env-mlb14}}{lst:env-mlb4-mod14} \end{cmhtcbraster} \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/env-mlb4-mod15.tex}{\texttt{env-mlb4.tex} using \cref{lst:env-mlb15}}{lst:env-mlb4-mod15} \cmhlistingsfromfile{demonstrations/env-mlb4-mod16.tex}{\texttt{env-mlb4.tex} using \cref{lst:env-mlb16}}{lst:env-mlb4-mod16} \end{cmhtcbraster} Notice that in: \begin{itemize} \item \cref{lst:env-mlb4-mod13} the line break denoted by $\BeginStartsOnOwnLine$ in \cref{lst:mlb4} has been removed; \item \cref{lst:env-mlb4-mod14} the line break denoted by $\BodyStartsOnOwnLine$ in \cref{lst:mlb4} has been removed; \item \cref{lst:env-mlb4-mod15} the line break denoted by $\EndStartsOnOwnLine$ in \cref{lst:mlb4} has been removed; \item \cref{lst:env-mlb4-mod16} the line break denoted by $\EndFinishesWithLineBreak$ in \cref{lst:mlb4} has been removed. \end{itemize} We examined each of these cases separately for clarity of explanation, but you can combine all of the YAML settings in \crefrange{lst:env-mlb13}{lst:env-mlb16} into one file; alternatively, you could tell \texttt{latexindent.pl} to load them all by using the following command, for example \index{switches!-l demonstration} \index{switches!-m 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 \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. \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$@*) \begin{myenv} (*@$\BodyStartsOnOwnLine$@*) body of myenv (*@$\EndStartsOnOwnLine$@*) \end{myenv} (*@$\EndFinishesWithLineBreak$@*) after words \end{cmhlistings} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/removeTWS-before.yaml}[yaml-TCB]{\texttt{removeTWS-before.yaml}}{lst:removeTWS-before} \end{cmhtcbraster} The output from the following commands \index{switches!-l demonstration} \index{switches!-m demonstration} \begin{widepage} \begin{commandshell} latexindent.pl -m env-mlb5.tex -l env-mlb13,env-mlb14,env-mlb15,env-mlb16 latexindent.pl -m env-mlb5.tex -l env-mlb13,env-mlb14,env-mlb15,env-mlb16,removeTWS-before \end{commandshell} \end{widepage} is shown, respectively, in \cref{lst:env-mlb5-modAll,lst:env-mlb5-modAll-remove-WS}; note that the trailing horizontal white space has been preserved (by default) in \cref{lst:env-mlb5-modAll}, while in \cref{lst:env-mlb5-modAll-remove-WS}, it has been removed using the switch specified in \cref{lst:removeTWS-before}. \begin{widepage} \cmhlistingsfromfile[showspaces=true]{demonstrations/env-mlb5-modAll.tex}{\texttt{env-mlb5.tex} using \crefrange{lst:env-mlb4-mod13}{lst:env-mlb4-mod16}}{lst:env-mlb5-modAll} \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} \begin{cmhtcbraster} \begin{cmhlistings}[style=tcblatex,escapeinside={(*@}{@*)}]{\texttt{env-mlb6.tex}}{lst:mlb6} before words(*@$\BeginStartsOnOwnLine$@*) \begin{myenv}(*@$\BodyStartsOnOwnLine$@*) body of myenv(*@$\EndStartsOnOwnLine$@*) \end{myenv}(*@$\EndFinishesWithLineBreak$@*) after words \end{cmhlistings} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/UnpreserveBlankLines.yaml}[MLB-TCB]{\texttt{UnpreserveBlankLines.yaml}}{lst:UnpreserveBlankLines} \end{cmhtcbraster} Upon running the following commands \index{switches!-l demonstration} \index{switches!-m demonstration} \begin{widepage} \begin{commandshell} latexindent.pl -m env-mlb6.tex -l env-mlb13,env-mlb14,env-mlb15,env-mlb16 latexindent.pl -m env-mlb6.tex -l env-mlb13,env-mlb14,env-mlb15,env-mlb16,UnpreserveBlankLines \end{commandshell} \end{widepage} we receive the respective outputs in \cref{lst:env-mlb6-modAll,lst:env-mlb6-modAll-un-Preserve-Blank-Lines}. In \cref{lst:env-mlb6-modAll} we see that the multiple blank lines have each been condensed into one blank line, but that blank lines have \emph{not} been removed by the poly-switches -- this is because, by default, \texttt{preserveBlankLines} is set to \texttt{1}. By contrast, in \cref{lst:env-mlb6-modAll-un-Preserve-Blank-Lines}, we have allowed the poly-switches to remove blank lines because, in \cref{lst:UnpreserveBlankLines}, we have set \texttt{preserveBlankLines} to \texttt{0}. \begin{cmhtcbraster}[ raster left skip=-3.5cm, raster right skip=-2cm, raster force size=false, raster column 1/.style={add to width=-.2\textwidth}, raster column 2/.style={add to width=.2\textwidth}, raster column skip=.06\linewidth] \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}. \cmhlistingsfromfile{demonstrations/env-mlb7.tex}{\texttt{env-mlb7.tex}}{lst:env-mlb7-tex} Upon running the following commands \index{switches!-l demonstration} \index{switches!-m demonstration} \begin{commandshell} latexindent.pl -m env-mlb7.tex -l env-mlb12.yaml,env-mlb13.yaml latexindent.pl -m env-mlb7.tex -l env-mlb13,env-mlb14,UnpreserveBlankLines \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} \cmhlistingsfromfile{demonstrations/env-mlb7-no-preserve.tex}{\texttt{env-mlb7-no-preserve.tex}}{lst:env-mlb7-no-preserve} Notice that in: \begin{itemize} \item \cref{lst:env-mlb7-preserve} that \lstinline!\end{one}! has added a blank line, because of the value of \texttt{EndFinishesWithLineBreak} in \vref{lst:env-mlb12}, and even though the line break ahead of \lstinline!\begin{two}! should have been removed (because of \texttt{BeginStartsOnOwnLine} in \vref{lst:env-mlb13}), the blank line has been preserved by default; \item \cref{lst:env-mlb7-no-preserve}, by contrast, has had the additional line-break removed, because of the settings in \cref{lst:UnpreserveBlankLines}. \end{itemize} \end{example} \subsubsection{Poly-switches for double backslash}\label{subsec:dbs} With reference to \texttt{lookForAlignDelims} (see \vref{lst:aligndelims:basic}) \announce{2019-07-13}{poly-switch for double backslash} you can specify poly-switches to dictate the line-break behaviour of double backslashes in environments (\vref{lst:tabularafter:basic}), commands (\vref{lst:matrixafter}), or special code blocks (\vref{lst:specialafter}). \footnote{There is no longer any need for the code block to be specified within \texttt{lookForAlignDelims} for DBS poly-switches to activate. \announce{2023-01-01}*{DBS poly-switches no need to specify lookForAlignDelims}} \index{delimiters!poly-switches for double backslash} \index{modifying linebreaks! surrounding double backslash} \index{poly-switches!for double back slash (delimiters)}% Consider the code given in \cref{lst:dbs-demo}. \begin{cmhlistings}[style=tcblatex,escapeinside={(*@}{@*)}]{\texttt{tabular3.tex}}{lst:dbs-demo} \begin{tabular}{cc} 1 & 2 (*@$\ElseStartsOnOwnLine$@*)\\(*@$\ElseFinishesWithLineBreak$@*) 3 & 4 (*@$\ElseStartsOnOwnLine$@*)\\(*@$\ElseFinishesWithLineBreak$@*) \end{tabular} \end{cmhlistings} Referencing \cref{lst:dbs-demo}: \begin{itemize} \item \texttt{DBS} stands for \emph{double backslash}; \item line breaks ahead of the double backslash are annotated by $\ElseStartsOnOwnLine$, and are controlled by \texttt{DBSStartsOnOwnLine}; \item line breaks after the double backslash are annotated by $\ElseFinishesWithLineBreak$, and are controlled by \texttt{DBSFinishesWithLineBreak}. \end{itemize} Let's explore each of these in turn. \paragraph{Double backslash starts on own line} \begin{example} We explore \texttt{DBSStartsOnOwnLine} ($\ElseStartsOnOwnLine$ in \cref{lst:dbs-demo}); starting with the code in \cref{lst:dbs-demo}, together with the YAML files given in \cref{lst:DBS1} and \cref{lst:DBS2} and running the following commands \index{switches!-l demonstration} \index{switches!-m demonstration} \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} \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} \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} We note that \begin{itemize} \item \cref{lst:DBS1} specifies \texttt{DBSStartsOnOwnLine} for \emph{every} environment (that is within \texttt{lookForAlignDelims}, \vref{lst:aligndelims:advanced}); the double backslashes from \cref{lst:dbs-demo} have been moved to their own line in \cref{lst:tabular3-DBS1}; \item \cref{lst:DBS2} specifies \texttt{DBSStartsOnOwnLine} on a \emph{per-name} basis for \texttt{tabular} (that is within \texttt{lookForAlignDelims}, \vref{lst:aligndelims:advanced}); the double backslashes from \cref{lst:dbs-demo} have been moved to their own line in \cref{lst:tabular3-DBS2}, having added comment symbols before moving them. \end{itemize} \end{example} \begin{example} We can combine DBS poly-switches with, for example, the \texttt{alignContentAfterDoubleBackSlash} in \vref{sec:alignContentAfterDoubleBackSlash}. For example, starting with the file \cref{lst:tabular6}, and using the settings in \vref{lst:alignContentAfterDBS1,lst:alignContentAfterDBS2} and running \begin{widepage} \begin{commandshell} latexindent.pl -s -m -l alignContentAfterDBS1.yaml,DBS1.yaml tabular6.tex -o=+-mod1 latexindent.pl -s -m -l alignContentAfterDBS2.yaml,DBS1.yaml tabular6.tex -o=+-mod2 \end{commandshell} \end{widepage} gives the respective outputs shown in \cref{lst:tabular6-mod1,lst:tabular6-mod2}. \begin{cmhtcbraster}[raster columns=3, raster left skip=-3.5cm, raster right skip=-2cm, raster column skip=.03\linewidth] \cmhlistingsfromfile{demonstrations/tabular6.tex}{\texttt{tabular6.tex}}{lst:tabular6} \cmhlistingsfromfile{demonstrations/tabular6-mod1.tex}{\texttt{tabular6-mod1.tex}}{lst:tabular6-mod1} \cmhlistingsfromfile{demonstrations/tabular6-mod2.tex}{\texttt{tabular6-mod2.tex}}{lst:tabular6-mod2} \end{cmhtcbraster} We note that: \begin{itemize} \item in \cref{lst:tabular6-mod1} the content \emph{after} the double back slash has been aligned; \item in \cref{lst:tabular6-mod2} we see that 3 spaces have been added after the double back slash. \end{itemize} \end{example} \paragraph{Double backslash finishes with line break} \begin{example} Let's now explore \texttt{DBSFinishesWithLineBreak} ($\ElseFinishesWithLineBreak$ in \cref{lst:dbs-demo}); starting with the code in \cref{lst:dbs-demo}, together with the YAML files given in \cref{lst:DBS3} and \cref{lst:DBS4} and running the following commands \index{poly-switches!for double backslash (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} \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} \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} We note that \begin{itemize} \item \cref{lst:DBS3} specifies \texttt{DBSFinishesWithLineBreak} for \emph{every} environment (that is within \texttt{lookForAlignDelims}, \vref{lst:aligndelims:advanced}); the code following the double backslashes from \cref{lst:dbs-demo} has been moved to their own line in \cref{lst:tabular3-DBS3}; \item \cref{lst:DBS4} specifies \texttt{DBSFinishesWithLineBreak} on a \emph{per-name} basis for \texttt{tabular} (that is within \texttt{lookForAlignDelims}, \vref{lst:aligndelims:advanced}); the first double backslashes from \cref{lst:dbs-demo} have moved code following them to their own line in \cref{lst:tabular3-DBS4}, having added comment symbols before moving them; the final double backslashes have \emph{not} added a line break as they are at the end of the body within the code block. \end{itemize} \end{example} \paragraph{Double backslash poly-switches for specialBeginEnd} \begin{example} Let's explore the double backslash poly-switches for code blocks within \texttt{specialBeginEnd} code blocks (\vref{lst:specialBeginEnd}); we begin with the code within \cref{lst:special4}. \index{specialBeginEnd!double backslash poly-switch demonstration} \index{poly-switches!double backslash} \index{poly-switches!for double backslash (delimiters)} \index{specialBeginEnd!lookForAlignDelims} \index{delimiters} \index{linebreaks!summary of poly-switches} \cmhlistingsfromfile{demonstrations/special4.tex}{\texttt{special4.tex}}{lst:special4} Upon using the YAML settings in \cref{lst:DBS5}, and running the command \index{switches!-l demonstration} \index{switches!-m demonstration} \begin{commandshell} latexindent.pl -m special4.tex -l DBS5.yaml \end{commandshell} then we receive the output given in \cref{lst:special4-DBS5}. \index{delimiters!with specialBeginEnd and the -m switch} \begin{cmhtcbraster}[ raster force size=false, raster column 1/.style={add to width=-.1\textwidth}, raster column skip=.06\linewidth] \cmhlistingsfromfile{demonstrations/special4-mod5.tex}{\texttt{special4.tex} using \cref{lst:DBS5}}{lst:special4-DBS5} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/DBS5.yaml}[MLB-TCB,width=0.6\textwidth]{\texttt{DBS5.yaml}}{lst:DBS5} \end{cmhtcbraster} There are a few things to note: \begin{itemize} \item in \cref{lst:DBS5} we have specified \texttt{cmhMath} within \texttt{lookForAlignDelims}; without this, the double backslash poly-switches would be ignored for this code block; \item the \texttt{DBSFinishesWithLineBreak} poly-switch has controlled the line breaks following the double backslashes; \item the \texttt{SpecialEndStartsOnOwnLine} poly-switch has controlled the addition of a comment symbol, followed by a line break, as it is set to a value of 2. \end{itemize} \end{example} \paragraph{Double backslash poly-switches for optional and mandatory arguments} For clarity, we provide a demonstration of controlling the double backslash poly-switches for optional and mandatory arguments. \begin{example} We use with the code in \cref{lst:mycommand2}. \index{poly-switches!for double backslash (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}[ raster force size=false, raster column 1/.style={add to width=-.1\textwidth}, raster column skip=.03\linewidth] \cmhlistingsfromfile{demonstrations/mycommand2-mod6.tex}{\texttt{mycommand2.tex} using \cref{lst:DBS6}}{lst:mycommand2-DBS6} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/DBS6.yaml}[MLB-TCB,width=0.6\textwidth]{\texttt{DBS6.yaml}}{lst:DBS6} \end{cmhtcbraster} \begin{cmhtcbraster}[ raster force size=false, raster column 1/.style={add to width=-.1\textwidth}, raster column skip=.03\linewidth] \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 backslash optional square brackets} The pattern matching for the double backslash will also, optionally, allow trailing square brackets that contain a measurement of vertical spacing, for example \lstinline!\\[3pt]!. \index{poly-switches!for double backslash (delimiters)} \begin{example} For example, beginning with the code in \cref{lst:pmatrix3} \cmhlistingsfromfile{demonstrations/pmatrix3.tex}{\texttt{pmatrix3.tex}}{lst:pmatrix3} and running the following command, using \cref{lst:DBS3}, \index{switches!-l demonstration} \index{switches!-m demonstration} \begin{commandshell} latexindent.pl -m pmatrix3.tex -l DBS3.yaml \end{commandshell} 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 backslash by exploring the \emph{fine tuning} field detailed in \vref{lst:fineTuning}. \subsubsection{Poly-switches for other code blocks} Rather than repeat the examples shown for the environment code blocks (in \vref{sec:modifylinebreaks-environments}), we choose to detail the poly-switches for all other code blocks in \cref{tab:poly-switch-mapping}; note that each and every one of these poly-switches is \emph{off by default}, i.e, set to \texttt{0}. Note also that, by design, line breaks involving, \texttt{filecontents} and `comment-marked' code blocks (\vref{lst:alignmentmarkup}) can \emph{not} be modified using \texttt{latexindent.pl}. \announce{2019-05-05}*{verbatim poly-switch} However, there are two poly-switches available for \texttt{verbatim} code blocks: environments (\vref{lst:verbatimEnvironments}), commands (\vref{lst:verbatimCommands}) and \texttt{specialBeginEnd} (\vref{lst:special-verb1-yaml}). \index{specialBeginEnd!poly-switch summary} \index{verbatim!poly-switch summary} \index{poly-switches!summary of all poly-switches}% \clearpage \begin{longtable}{llll} \caption{Poly-switch mappings for all code-block types}\label{tab:poly-switch-mapping} \\ \toprule Code block & Sample & \multicolumn{2}{c}{Poly-switch mapping} \\ \midrule environment & \verb!before words!$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & BeginStartsOnOwnLine \\ & \verb!\begin{myenv}!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & BodyStartsOnOwnLine \\ & \verb!body of myenv!$\EndStartsOnOwnLine$ & $\EndStartsOnOwnLine$ & EndStartsOnOwnLine \\ & \verb!\end{myenv}!$\EndFinishesWithLineBreak$ & $\EndFinishesWithLineBreak$ & EndFinishesWithLineBreak \\ & \verb!after words! & & \\ \cmidrule{2-4} ifelsefi & \verb!before words!$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & IfStartsOnOwnLine \\ & \verb!\if...!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & BodyStartsOnOwnLine \\ & \verb!body of if/or statement!$\OrStartsOnOwnLine$ & $\OrStartsOnOwnLine$ & OrStartsOnOwnLine % \announce{2018-04-27}{new ifElseFi code block poly-switches} \\ & \verb!\or!$\OrFinishesWithLineBreak$ & $\OrFinishesWithLineBreak$ & OrFinishesWithLineBreak \\ & \verb!body of if/or statement!$\ElseStartsOnOwnLine$ & $\ElseStartsOnOwnLine$ & ElseStartsOnOwnLine \\ & \verb!\else!$\ElseFinishesWithLineBreak$ & $\ElseFinishesWithLineBreak$ & ElseFinishesWithLineBreak \\ & \verb!body of else statement!$\EndStartsOnOwnLine$ & $\EndStartsOnOwnLine$ & FiStartsOnOwnLine \\ & \verb!\fi!$\EndFinishesWithLineBreak$ & $\EndFinishesWithLineBreak$ & FiFinishesWithLineBreak \\ & \verb!after words! & & \\ \cmidrule{2-4} optionalArguments & \verb!...!$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & LSqBStartsOnOwnLine\footnote{LSqB stands for Left Square Bracket} \\ & \verb![!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & OptArgBodyStartsOnOwnLine \\ \announce{2019-07-13}{new comma-related poly-switches} & \verb!value before comma!$\ElseStartsOnOwnLine$, & $\ElseStartsOnOwnLine$ & CommaStartsOnOwnLine \\ & $\ElseFinishesWithLineBreak$ & $\ElseFinishesWithLineBreak$ & CommaFinishesWithLineBreak \\ & \verb!end of body of opt arg!$\EndStartsOnOwnLine$ & $\EndStartsOnOwnLine$ & RSqBStartsOnOwnLine \\ & \verb!]!$\EndFinishesWithLineBreak$ & $\EndFinishesWithLineBreak$ & RSqBFinishesWithLineBreak \\ & \verb!...! & & \\ \cmidrule{2-4} mandatoryArguments & \verb!...!$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & LCuBStartsOnOwnLine\footnote{LCuB stands for Left Curly Brace} \\ & \verb!{!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & MandArgBodyStartsOnOwnLine \\ \announce{2019-07-13}{new comma-related poly-switches} & \verb!value before comma!$\ElseStartsOnOwnLine$, & $\ElseStartsOnOwnLine$ & CommaStartsOnOwnLine \\ & $\ElseFinishesWithLineBreak$ & $\ElseFinishesWithLineBreak$ & CommaFinishesWithLineBreak \\ & \verb!end of body of mand arg!$\EndStartsOnOwnLine$ & $\EndStartsOnOwnLine$ & RCuBStartsOnOwnLine \\ & \verb!}!$\EndFinishesWithLineBreak$ & $\EndFinishesWithLineBreak$ & RCuBFinishesWithLineBreak \\ & \verb!...! & & \\ \cmidrule{2-4} commands & \verb!before words!$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & CommandStartsOnOwnLine \\ & \verb!\mycommand!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & CommandNameFinishesWithLineBreak \\ & $\langle$\itshape{arguments}$\rangle$ & & \\ \cmidrule{2-4} namedGroupingBracesBrackets & before words$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & NameStartsOnOwnLine \\ & myname$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & NameFinishesWithLineBreak \\ & $\langle$\itshape{braces/brackets}$\rangle$ & & \\ \cmidrule{2-4} keyEqualsValuesBraces\newline Brackets & before words$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & KeyStartsOnOwnLine \\ & key$\EqualsStartsOnOwnLine$=$\BodyStartsOnOwnLine$ & $\EqualsStartsOnOwnLine$ & EqualsStartsOnOwnLine \\ & $\langle$\itshape{braces/brackets}$\rangle$ & $\BodyStartsOnOwnLine$ & EqualsFinishesWithLineBreak \\ \cmidrule{2-4} items & before words$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & ItemStartsOnOwnLine \\ & \verb!\item!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & ItemFinishesWithLineBreak \\ & \verb!...! & & \\ \cmidrule{2-4} specialBeginEnd & before words$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & SpecialBeginStartsOnOwnLine \\ & \verb!\[!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & SpecialBodyStartsOnOwnLine \\ & \verb!body of special/middle!$\ElseStartsOnOwnLine$ & $\ElseStartsOnOwnLine$ & SpecialMiddleStartsOnOwnLine % \announce{2018-04-27}{new special code block poly-switches} \\ & \verb!\middle!$\ElseFinishesWithLineBreak$ & $\ElseFinishesWithLineBreak$ & SpecialMiddleFinishesWithLineBreak \\ & body of special/middle $\EndStartsOnOwnLine$ & $\EndStartsOnOwnLine$ & SpecialEndStartsOnOwnLine \\ & \verb!\]!$\EndFinishesWithLineBreak$ & $\EndFinishesWithLineBreak$ & SpecialEndFinishesWithLineBreak \\ & after words & & \\ \cmidrule{2-4} verbatim & before words$\BeginStartsOnOwnLine$\verb!\begin{verbatim}! & $\BeginStartsOnOwnLine$ & VerbatimBeginStartsOnOwnLine \\ \announce{2019-05-05}{verbatim poly-switches} & body of verbatim \verb!\end{verbatim}!$\EndFinishesWithLineBreak$ & $\EndFinishesWithLineBreak$ & VerbatimEndFinishesWithLineBreak \\ & after words & & \\ \bottomrule \end{longtable} \subsubsection{Partnering BodyStartsOnOwnLine with argument-based poly-switches} Some poly-switches need to be partnered together; in particular, when line breaks involving the \emph{first} argument of a code block need to be accounted for using both \texttt{BodyStartsOnOwnLine} (or its equivalent, see \vref{tab:poly-switch-mapping}) and \texttt{LCuBStartsOnOwnLine} for mandatory arguments, and \texttt{LSqBStartsOnOwnLine} for optional arguments. \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}. \cmhlistingsfromfile{demonstrations/mycommand1.tex}{\texttt{mycommand1.tex}}{lst:mycommand1} Upon running the command \index{switches!-l demonstration} \index{switches!-m demonstration} \begin{commandshell} latexindent.pl -m -l=mycom-mlb1.yaml mycommand1.tex \end{commandshell} we obtain \cref{lst:mycommand1-mlb1}; note that the \emph{second} mandatory argument beginning brace \lstinline!{! has had its leading line break removed, but that the \emph{first} brace has not. \begin{cmhtcbraster}[ raster force size=false, raster column 1/.style={add to width=-1cm}, ] \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 command \begin{commandshell} latexindent.pl -m -l=mycom-mlb2.yaml mycommand1.tex \end{commandshell} we obtain \cref{lst:mycommand1-mlb2}; both beginning braces \lstinline!{! have had their leading line breaks removed. \begin{cmhtcbraster}[ raster force size=false, raster column 1/.style={add to width=-1cm}, ] \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 command \begin{commandshell} latexindent.pl -m -l=mycom-mlb3.yaml mycommand1.tex \end{commandshell} we obtain \cref{lst:mycommand1-mlb3}. \begin{cmhtcbraster}[ raster force size=false, raster column 1/.style={add to width=-1cm}, ] \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. \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} \cmhlistingsfromfile{demonstrations/mycommand1-mlb4.tex}{\texttt{mycommand1.tex} using \cref{lst:mycom-mlb4}}{lst:mycommand1-mlb4} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycom-mlb4.yaml}[MLB-TCB,width=\linewidth]{\texttt{mycom-mlb4.yaml}}{lst:mycom-mlb4} \end{cmhtcbraster} Studying \cref{lst:mycom-mlb4}, we see that the two poly-switches are at opposition with one another: \begin{itemize} \item on the one hand, \texttt{LCuBStartsOnOwnLine} should \emph{not} start on its own line (as poly-switch is set to $-1$); \item on the other hand, \texttt{RCuBFinishesWithLineBreak} \emph{should} finish with a line break. \end{itemize} So, which should win the conflict? As demonstrated in \cref{lst:mycommand1-mlb4}, it is clear that \texttt{LCuBStartsOnOwnLine} won this conflict, and the reason is that \emph{the second argument was processed after the first} -- in general, the most recently-processed code block and associated poly-switch takes priority. \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=.05\linewidth] \cmhlistingsfromfile{demonstrations/mycommand1-mlb5.tex}{\texttt{mycommand1.tex} using \cref{lst:mycom-mlb5}}{lst:mycommand1-mlb5} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycom-mlb5.yaml}[MLB-TCB,width=\linewidth]{\texttt{mycom-mlb5.yaml}}{lst:mycom-mlb5} \end{cmhtcbraster} As previously, the most-recently-processed code block takes priority -- as before, the second (i.e, \emph{last}) argument. Exploring this further, we consider the YAML settings in \cref{lst:mycom-mlb6}, and run the command \begin{commandshell} latexindent.pl -m -l=mycom-mlb6.yaml mycommand1.tex \end{commandshell} which gives the output in \cref{lst:mycommand1-mlb6}. \begin{cmhtcbraster}[raster column skip=.05\linewidth] \cmhlistingsfromfile{demonstrations/mycommand1-mlb6.tex}{\texttt{mycommand1.tex} using \cref{lst:mycom-mlb6}}{lst:mycommand1-mlb6} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycom-mlb6.yaml}[MLB-TCB,width=\linewidth]{\texttt{mycom-mlb6.yaml}}{lst:mycom-mlb6} \end{cmhtcbraster} Note that a \lstinline!%! \emph{has} been added to the trailing first \lstinline!}!; this is because: \begin{itemize} \item while processing the \emph{first} argument, the trailing line break has been removed (\texttt{RCuBFinishesWithLineBreak} set to $-1$); \item while processing the \emph{second} argument, \texttt{latexindent.pl} finds that it does \emph{not} begin on its own line, and so because \texttt{LCuBStartsOnOwnLine} is set to $2$, it adds a comment, followed by a line break. \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} \cmhlistingsfromfile{demonstrations/nested-env.tex}{\texttt{nested-env.tex}}{lst:nested-env} Let's use the YAML settings given in \cref{lst:nested-env-mlb1-yaml}, which upon running the command \index{switches!-l demonstration} \index{switches!-m demonstration} \begin{commandshell} latexindent.pl -m -l=nested-env-mlb1.yaml nested-env.tex \end{commandshell} gives the output in \cref{lst:nested-env-mlb1}. \begin{cmhtcbraster}[raster column skip=.05\linewidth] \cmhlistingsfromfile{demonstrations/nested-env-mlb1.tex}{\texttt{nested-env.tex} using \cref{lst:nested-env-mlb1-yaml}}{lst:nested-env-mlb1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/nested-env-mlb1.yaml}[MLB-TCB,width=\linewidth]{\texttt{nested-env-mlb1.yaml}}{lst:nested-env-mlb1-yaml} \end{cmhtcbraster} In \cref{lst:nested-env-mlb1}, let's first of all note that both environments have received the appropriate (default) indentation; secondly, note that the poly-switch \texttt{EndStartsOnOwnLine} appears to have won the conflict, as \lstinline!\end{one}! has had its leading line break removed. \end{example} To understand it, let's talk about the three basic phases \label{page:phases}of \texttt{latexindent.pl}: \begin{enumerate} \item Phase 1: packing, in which code blocks are replaced with unique ids, working from \emph{the inside to the outside}, and then sequentially -- for example, in \cref{lst:nested-env}, the \texttt{two} environment is found \emph{before} the \texttt{one} environment; if the -m switch is active, then during this phase: \begin{itemize} \item line breaks at the beginning of the \texttt{body} can be added (if \texttt{BodyStartsOnOwnLine} is $1$ or $2$) or removed (if \texttt{BodyStartsOnOwnLine} is $-1$); \item line breaks at the end of the body can be added (if \texttt{EndStartsOnOwnLine} is $1$ or $2$) or removed (if \texttt{EndStartsOnOwnLine} is $-1$); \item line breaks after the end statement can be added (if \texttt{EndFinishesWithLineBreak} is $1$ or $2$). \end{itemize} \item Phase 2: indentation, in which white space is added to the begin, body, and end statements; \item Phase 3: unpacking, in which unique ids are replaced by their \emph{indented} code blocks; if the -m switch is active, then during this phase, \begin{itemize} \item line breaks before \texttt{begin} statements can be added or removed (depending upon \texttt{BeginStartsOnOwnLine}); \item line breaks after \emph{end} statements can be removed but \emph{NOT} added (see \texttt{EndFinishesWithLineBreak}). \end{itemize} \end{enumerate} With reference to \cref{lst:nested-env-mlb1}, this means that during Phase 1: \begin{itemize} \item the \texttt{two} environment is found first, and the line break ahead of the \lstinline!\end{two}! statement is removed because \texttt{EndStartsOnOwnLine} is set to $-1$. Importantly, because, \emph{at this stage}, \lstinline!\end{two}! \emph{does} finish with a line break, \texttt{EndFinishesWithLineBreak} causes no action. \item next, the \texttt{one} environment is found; the line break ahead of \lstinline!\end{one}! is removed because \texttt{EndStartsOnOwnLine} is set to $-1$. \end{itemize} The indentation is done in Phase 2; in Phase 3 \emph{there is no option to add a line break after the \lstinline!end! statements}. We can justify this by remembering that during Phase 3, the \texttt{one} environment will be found and processed first, followed by the \texttt{two} environment. If the \texttt{two} environment were to add a line break after the \lstinline!\end{two}! statement, then \texttt{latexindent.pl} would have no way of knowing how much indentation to add to the subsequent text (in this case, \lstinline!\end{one}!). \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} \cmhlistingsfromfile{demonstrations/nested-env-mlb2.tex}{\texttt{nested-env.tex} using \cref{lst:nested-env-mlb2}}{lst:nested-env-mlb2-output} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/nested-env-mlb2.yaml}[MLB-TCB,width=\linewidth]{\texttt{nested-env-mlb2.yaml}}{lst:nested-env-mlb2} \end{cmhtcbraster} During Phase 1: \begin{itemize} \item the \texttt{two} environment is found first, and the line break ahead of the \lstinline!\end{two}! statement is not changed because \texttt{EndStartsOnOwnLine} is set to $1$. Importantly, because, \emph{at this stage}, \lstinline!\end{two}! \emph{does} finish with a line break, \texttt{EndFinishesWithLineBreak} causes no action. \item next, the \texttt{one} environment is found; the line break ahead of \lstinline!\end{one}! is already present, and no action is needed. \end{itemize} The indentation is done in Phase 2, and then in Phase 3, the \texttt{one} environment is found and processed first, followed by the \texttt{two} environment. \emph{At this stage}, the \texttt{two} environment finds \texttt{EndFinishesWithLineBreak} is $-1$, so it removes the trailing line break; remember, at this point, \texttt{latexindent.pl} has completely finished with the \texttt{one} environment. \end{example} % arara: pdflatex: { files: [latexindent]} \section{The -r, -rv and -rr switches}\label{sec:replacements} \fancyhead[R]{\bfseries\thepage% \tikz[remember picture,overlay] { \node at (1,0){\includegraphics{logo-bw}}; } } You can instruct \texttt{latexindent.pl} to perform replacements/substitutions on your \announce{2019-07-13}{replacement mode switches} file by using any of the \texttt{-r}, \texttt{-rv} or \texttt{-rr} switches: \index{verbatim!rv, replacementrespectverb switch} \begin{itemize} \item the \texttt{-r} switch will perform indentation and replacements, not respecting verbatim code blocks; \item the \texttt{-rv} switch will perform indentation and replacements, and \emph{will} respect verbatim code blocks; \item the \texttt{-rr} switch will \emph{not} perform indentation, and will perform replacements not respecting verbatim code blocks. \end{itemize} We will demonstrate each of the \texttt{-r}, \texttt{-rv} and \texttt{-rr} switches, but a summary is given in \cref{tab:replacementswitches}. \begin{table}[!htb] \centering \caption{The replacement mode switches}\label{tab:replacementswitches} \begin{tabular}{rcc} \toprule switch & indentation? & respect verbatim? \\ \midrule \texttt{-r} & \faCheck & \faClose \\ \texttt{-rv} & \faCheck & \faCheck \\ \texttt{-rr} & \faClose & \faClose \\ \bottomrule \end{tabular} \end{table} The default value of the \texttt{replacements} field is shown in \cref{lst:replacements}; as with all of the other fields, you are encouraged to customise and change this as you see fit. The options in this field will \emph{only} be considered if the \texttt{-r}, \texttt{-rv} or \texttt{-rr} switches are active; when discussing YAML settings related to the replacement-mode switches, we will use the style given in \cref{lst:replacements}. \cmhlistingsfromfile[style=replacements]{../defaultSettings.yaml}[width=0.95\linewidth,before=\centering,replace-TCB]{\texttt{replacements}}{lst:replacements} The first entry within the \texttt{replacements} field is \texttt{amalgamate}, and is \emph{optional}; by default it is set to 1, so that replacements will be amalgamated from each settings file that you specify. As you'll see in the demonstrations that follow, there is no need to specify this field. You'll notice that, by default, there is only \emph{one} entry in the \texttt{replacements} field, but it can take as many entries as you would like; each one needs to begin with a \texttt{-} on its own line. \subsection{Introduction to replacements} Let's explore the action of the default settings, and then we'll demonstrate the feature with further examples. \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] \cmhlistingsfromfile{demonstrations/replace1.tex}{\texttt{replace1.tex}}{lst:replace1} \cmhlistingsfromfile{demonstrations/replace1-r1.tex}{\texttt{replace1.tex} default}{lst:replace1-r1} \end{cmhtcbraster} We note that in \cref{lst:replacements}, because \texttt{lookForThis} is set to 0, the specified replacement has \emph{not} been made, and there is no difference between \cref{lst:replace1,lst:replace1-r1}. If we \emph{do} wish to perform this replacement, then we can tweak the default settings of \vref{lst:replacements} by changing \texttt{lookForThis} to 1; we perform this action in \cref{lst:replace1-yaml}, and run the command \index{switches!-l demonstration} \index{switches!-r demonstration} \begin{commandshell} 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] \cmhlistingsfromfile{demonstrations/replace1-mod1.tex}{\texttt{replace1.tex} using \cref{lst:replace1-yaml}}{lst:replace1-mod1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/replace1.yaml}[replace-TCB]{\texttt{replace1.yaml}}{lst:replace1-yaml} \end{cmhtcbraster} 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. \subsection{The two types of replacements} There are two types of replacements: \begin{enumerate} \item \emph{string}-based replacements, which replace the string in \emph{this} with the string in \emph{that}. If you specify \texttt{this} and you do not specify \texttt{that}, then the \texttt{that} field will be assumed to be empty. \index{regular expressions!replacement switch, -r} \item \emph{regex}-based replacements, which use the \texttt{substitution} field. \end{enumerate} We will demonstrate both in the examples that follow. \texttt{latexindent.pl} chooses which type of replacement to make based on which fields have been specified; if the \texttt{this} field is specified, then it will make \emph{string}-based replacements, regardless of if \texttt{substitution} is present or not. \subsection{Examples of replacements} \begin{example} We begin with code given in \cref{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. 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} \cmhlistingsfromfile{demonstrations/colsep-mod0.tex}{\texttt{colsep.tex} using \cref{lst:colsep-yaml}}{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} \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. 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}. 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} 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}. \end{example} \begin{example} 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}. \cmhlistingsfromfile{demonstrations/displaymath.tex}{\texttt{displaymath.tex}}{lst:displaymath} We use the settings in \cref{lst:displaymath1} and run the command \index{switches!-l demonstration} \index{switches!-r demonstration} \begin{commandshell} latexindent.pl -r displaymath.tex -l=displaymath1.yaml \end{commandshell} to receive the output given in \cref{lst:displaymath-mod1}. \index{regular expressions!substitution field, equation} \begin{cmhtcbraster}[raster left skip=-3.75cm, raster right skip=-2cm,] \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} 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} \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}. \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} 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} 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}. \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} 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} \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}. \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} 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} \end{example} We note that: \begin{enumerate} \item in \cref{lst:verb1-mod1} indentation has been performed, and that the replacements specified in \cref{lst:verbatim1-yaml} have been performed, even within the verbatim code block; \item in \cref{lst:verb1-rv-mod1} indentation has been performed, but that the replacements have \emph{not} been performed within the verbatim environment, because the \texttt{rv} switch is active; \item in \cref{lst:verb1-rr-mod1} indentation has \emph{not} been performed, but that replacements have been performed, not respecting the verbatim code block. \end{enumerate} 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}. \cmhlistingsfromfile{demonstrations/amalg1.tex}{\texttt{amalg1.tex}}{lst:amalg1} 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} 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} \end{example} % arara: pdflatex: { files: [latexindent]} \section{The --lines switch}\label{sec:line-switch} \texttt{latexindent.pl} \announce{2021-09-16}{line switch demonstration} can operate on a \emph{selection} of lines of the file using the \texttt{--lines} or \texttt{-n} switch. \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}. The options for the \texttt{lines} switch are: \begin{itemize} \item line range, as in \texttt{--lines 3-7} \item single line, as in \texttt{--lines 5} \item multiple line ranges separated by commas, as in \texttt{--lines 3-5,8-10} \item negated line ranges, as in \texttt{--lines !3-5} which translates to \texttt{--lines 1-2,6-N}, where N is the number of lines in your file. \end{itemize} We demonstrate this feature, and the available variations in what follows. We will use the file in \cref{lst:myfile}. \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} 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} 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. \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} 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} 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. 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} 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. \end{example} \begin{example} 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} 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. \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} 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} 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. \end{example} \begin{example} \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} 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} \end{example} \begin{example} \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} 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} \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}. 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. 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} 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{example} % arara: pdflatex: { files: [latexindent]} \section{Fine tuning}\label{sec:finetuning} \texttt{latexindent.pl} operates by looking for the code blocks detailed in \vref{tab:code-blocks}. \announce{2019-07-13}{details of fine tuning of code blocks} The fine tuning of the details of such code blocks is controlled by the \texttt{fineTuning} field, detailed in \cref{lst:fineTuning}. This field is for those that would like to peek under the bonnet/hood and make some fine tuning to \texttt{latexindent.pl}'s operating. \index{warning!fine tuning} \index{regular expressions!fine tuning} \index{regular expressions!environments} \index{regular expressions!ifElseFi} \index{regular expressions!commands} \index{regular expressions!keyEqualsValuesBracesBrackets} \index{regular expressions!NamedGroupingBracesBrackets} \index{regular expressions!UnNamedGroupingBracesBrackets} \index{regular expressions!arguments} \index{regular expressions!modifyLineBreaks} \index{regular expressions!lowercase alph a-z} \index{regular expressions!uppercase alph A-Z} \index{regular expressions!numeric 0-9} \index{regular expressions!at least one +} \index{regular expressions!horizontal space \textbackslash{h}} \begin{warning} Making changes to the fine tuning may have significant consequences for your indentation scheme, proceed with caution! \end{warning} \begin{widepage} \cmhlistingsfromfile[style=fineTuning]{../defaultSettings.yaml}[width=.95\linewidth,before=\centering,enhanced jigsaw,breakable,yaml-TCB]{\texttt{fineTuning}}{lst:fineTuning} \end{widepage} The fields given in \cref{lst:fineTuning} are all \emph{regular expressions}. This manual is not intended to be a tutorial on regular expressions; you might like to read, for example, \cite{masteringregexp} for a detailed covering of the topic. We make the following comments with reference to \cref{lst:fineTuning}: \begin{enumerate} \item the \texttt{environments:name} field details that the \emph{name} of an environment can contain: \begin{enumerate} \item \texttt{a-z} lower case letters \item \texttt{A-Z} upper case letters \item \texttt{@} the \texttt{@} 'letter' \item \lstinline!\*! stars \item \texttt{0-9} numbers \item \lstinline!_! underscores \item \lstinline!\! backslashes \end{enumerate} \index{regular expressions!at least one +} The \texttt{+} at the end means \emph{at least one} of the above characters. \item the \texttt{ifElseFi:name} field: \begin{enumerate} \item \lstinline^@?^ means that it \emph{can possibly} begin with \lstinline^@^ \item followed by \texttt{if} \item followed by 0 or more characters from \texttt{a-z}, \texttt{A-Z} and \texttt{@} \item the \texttt{?} the end means \emph{non-greedy}, which means `stop the match as soon as possible' \end{enumerate} \item the \texttt{keyEqualsValuesBracesBrackets} contains some interesting syntax: \begin{enumerate} \item \lstinline!|! means `or' \item \lstinline^(?:(?<!\\)\{)^ the \lstinline^(?:...)^ uses a \emph{non-capturing} group -- you don't necessarily need to worry about what this means, but just know that for the \texttt{fineTuning} feature you should only ever use \emph{non}-capturing groups, and \emph{not} capturing groups, which are simply \lstinline!(...)! \item \lstinline^(?<!\\)\{)^ means a \lstinline^{^ but it can \emph{not} be immediately preceded by a \lstinline!\! \end{enumerate} \item in the \texttt{arguments:before} field \begin{enumerate} \item \lstinline^\d\h*^ means a digit (i.e. a number), followed by 0 or more horizontal spaces \item \lstinline^;?,?^ means \emph{possibly} a semi-colon, and possibly a comma \item \lstinline^\<.*?\>^ is designed for 'beamer'-type commands; the \lstinline^.*?^ means anything in between \lstinline^<...>^ \end{enumerate} \item the \texttt{modifyLineBreaks} field refers to fine tuning settings detailed in \vref{sec:modifylinebreaks}. In particular: \begin{enumerate} \item \texttt{betterFullStop} is in relation to the one sentence per line routine, detailed in \vref{sec:onesentenceperline} \item \texttt{doubleBackSlash} is in relation to the \texttt{DBSStartsOnOwnLine} and \texttt{DBSFinishesWithLineBreak} polyswitches surrounding double backslashes, see \vref{subsec:dbs} \item \texttt{comma} is in relation to the \texttt{CommaStartsOnOwnLine} and \texttt{CommaFinishesWithLineBreak} polyswitches surrounding commas in optional and mandatory arguments; see \vref{tab:poly-switch-mapping} \end{enumerate} \end{enumerate} It is not obvious from \cref{lst:fineTuning}, but each of the \texttt{follow}, \texttt{before} and \texttt{between} fields allow trailing comments, line breaks, and horizontal spaces between each character. \index{warning!capture groups} \begin{warning} For the \texttt{fineTuning} feature you should only ever use \emph{non}-capturing groups, such as \lstinline!(?:...)! and \emph{not} capturing groups, which are \lstinline!(...)! \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} 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} 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} \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} 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} 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} In particular, note that the settings in \cref{lst:fine-tuning2} specify that \texttt{NamedGroupingBracesBrackets} and \texttt{UnNamedGroupingBracesBrackets} can follow \texttt{"} and that we allow \lstinline!---! between arguments. \end{example} \begin{example} You can tweak the \texttt{fineTuning} using the \texttt{-y} switch, but to be sure to use quotes appropriately. For example, starting with the code in \cref{lst:finetuning3} and running the following command \begin{commandshell} latexindent.pl -m -y='modifyLineBreaks:oneSentencePerLine:manipulateSentences: 1, modifyLineBreaks:oneSentencePerLine:sentencesBeginWith:a-z: 1, fineTuning:modifyLineBreaks:betterFullStop: "(?:\.|;|:(?![a-z]))|(?:(?<!(?:(?: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} \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} \cmhlistingsfromfile{demonstrations/finetuning4.tex}{\texttt{finetuning4.tex}}{lst:finetuning4} 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} 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} \cmhlistingsfromfile{demonstrations/finetuning4-mod2.tex}{\texttt{finetuning4.tex} using \cref{lst:href2}}{lst:finetuning4-mod2} \end{widepage} 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 preceded 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} 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} 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} 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} \end{example} \begin{example} 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} 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} The output in \cref{lst:bib2-mod1} is not ideal, as the \texttt{=} symbol within the url field has been incorrectly used as an alignment delimiter. We address this by tweaking the \texttt{delimiterRegEx} field in \cref{lst:bibsettings2}. \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} 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 preceded} by either \texttt{v} or \texttt{spfreload}. \end{example} \begin{example} We can use the \texttt{fineTuning} settings to tweak how \texttt{latexindent.pl} finds trailing comments. \announce{2023-06-01}{fine tuning trailing comments demonstration} We begin with the file in \cref{lst:finetuning5} \cmhlistingsfromfile{demonstrations/finetuning5.tex}{\texttt{finetuning5.tex}}{lst:finetuning5} Using the settings in \cref{lst:fine-tuning3} and running the command \begin{commandshell} latexindent.pl finetuning5.tex -l=fine-tuning3.yaml \end{commandshell} gives the output in \cref{lst:finetuning5-mod1}. \begin{cmhtcbraster}[raster column skip=.01\linewidth] \cmhlistingsfromfile{demonstrations/finetuning5-mod1.tex}{\texttt{finetuning5-mod1.tex}}{lst:finetuning5-mod1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/fine-tuning3.yaml}[yaml-TCB]{\texttt{finetuning3.yaml}}{lst:fine-tuning3} \end{cmhtcbraster} The settings in \cref{lst:fine-tuning3} detail that trailing comments can \emph{not} be followed by a single space, and then the text `end'. This means that the \texttt{specialBeginEnd} routine will be able to find the pattern \lstinline!% end! as the \texttt{end} part. The trailing comments \texttt{123} and \texttt{456} are still treated as trailing comments. \end{example} \begin{example} We can use the \texttt{fineTuning} settings to tweak how \texttt{latexindent.pl} finds environments. We begin with the file in \cref{lst:finetuning6}.\announce{2023-10-13}{fineTuning environments} \cmhlistingsfromfile{demonstrations/finetuning6.tex}{\texttt{finetuning6.tex}}{lst:finetuning6} Using the settings in \cref{lst:fine-tuning4} and running the command \begin{commandshell} latexindent.pl finetuning6.tex -m -l=fine-tuning4.yaml \end{commandshell} gives the output in \cref{lst:finetuning6-mod1}. \begin{cmhtcbraster}[raster column skip=.01\linewidth, raster left skip=-3.5cm, raster force size=false, raster column 1/.style={add to width=-.1\textwidth}, raster column 2/.style={add to width=-.3\textwidth}, ] \cmhlistingsfromfile{demonstrations/finetuning6-mod1.tex}{\texttt{finetuning6-mod1.tex}}{lst:finetuning6-mod1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/fine-tuning4.yaml}[MLB-TCB]{\texttt{fine-tuning4.yaml}}{lst:fine-tuning4} \end{cmhtcbraster} By using the settings in \cref{lst:fine-tuning4} it means that the default poly-switch location of \texttt{BodyStartsOnOwnLine} for environments (denoted $\BodyStartsOnOwnLine$ in \cref{tab:poly-switch-mapping}) has been overwritten so that it is \emph{after} the \texttt{label} command. Referencing \cref{lst:fine-tuning4}, unless both \texttt{begin} and \texttt{end} are specified, then the default value of \texttt{name} will be used. \end{example} % arara: pdflatex: { files: [latexindent]} \section{Conclusions and known limitations}\label{sec:knownlimitations} There are a number of known limitations of the script, and almost certainly quite a few that are \emph{unknown}! The known issues include: \begin{description} \item[multicolumn alignment] when working with code blocks in which multicolumn commands overlap, the algorithm can fail; see \vref{lst:tabular2-mod2}. \item[textWrap after] when operating with \texttt{indentRules} (see \vref{sec:noadd-indent-rules}) may not always cooperate with one another; if you have a specific example that does not work, please report it to \cite{latexindent-home}. \item[efficiency] particularly when the \texttt{-m} switch is active, as this adds many checks and processes. The current implementation relies upon finding and storing \emph{every} code block (see the discussion on \cpageref{page:phases}); I hope that, in a future version, only \emph{nested} code blocks will need to be stored in the `packing' phase, and that this will improve the efficiency of the script. \end{description} You can run \texttt{latexindent} on any file; \announce{2019-07-13}*{ability to call latexindent on any file} if you don't specify an extension, then the extensions that you specify in \lstinline[breaklines=true]!fileExtensionPreference! (see \vref{lst:fileExtensionPreference}) will be consulted. If you find a case in which the script struggles, please feel free to report it at \cite{latexindent-home}, and in the meantime, consider using a \texttt{noIndentBlock} (see \cpageref{lst:noIndentBlock}).% I hope that this script is useful to some; if you find an example where the script does not behave as you think it should, the best way to contact me is to report an issue on \cite{latexindent-home}; otherwise, feel free to find me on the \url{http://tex.stackexchange.com/users/6621/cmhughes}. \nocite{*} \section{References} \printbibliography[heading=subbibnumbered,title={perl-related links},keyword=perl] \printbibliography[heading=subbibnumbered,title={conda-related links},keyword=conda] \index{conda} \printbibliography[heading=subbibnumbered,title={VScode-related links},keyword=vscode] \index{VSCode} \printbibliography[heading=subbibnumbered,title={Other links},keyword=other] \index{pre-commit} \index{MiKTeX} \index{contributors} \printbibliography[env=specialbib,heading=subbibnumbered,title={Contributors (in chronological order)\label{sec:contributors}},keyword=contributor] % arara: pdflatex: { files: [latexindent]} \appendix \section{Required Perl modules}\label{sec:requiredmodules} If you intend to use \texttt{latexindent.pl} and \emph{not} one of the supplied standalone executable files (\texttt{latexindent.exe} is available for Windows users without Perl, see \cref{subsubsec:latexindent:exe}), then you will need a few standard 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}. \begin{cmhlistings}[style=tcblatex,language=Perl]{\texttt{helloworld.pl}}{lst:helloworld} #!/usr/bin/perl use strict; # | use warnings; # | use Encode; # | use Getopt::Long; # | use Data::Dumper; # these modules are use List::Util qw(max); # generally part use PerlIO::encoding; # of a default perl distribution use open ':std', ':encoding(UTF-8)';# | use Text::Wrap; # | use Text::Tabs; # | use FindBin; # | use File::Copy; # | use File::Basename; # | use File::Path; # | use File::HomeDir; # <--- typically requires install via cpanm use YAML::Tiny; # <--- typically requires install via cpanm print "hello world"; exit; \end{cmhlistings} \subsection{Module installer script}\label{sec:module-installer} \announce{2018-01-13}{perl module helper script} \texttt{latexindent.pl} ships with a helper script that will install any missing \texttt{perl} modules on your system; if you run \begin{commandshell} perl latexindent-module-installer.pl \end{commandshell} or \begin{dosprompt} perl latexindent-module-installer.pl \end{dosprompt} then, once you have answered \texttt{Y}, the appropriate modules will be installed onto your distribution. \subsection{Manually installing modules}\label{sec:manual-module-instal} Manually installing the modules given in \cref{lst:helloworld} will vary depending on your operating system and \texttt{Perl} distribution. \subsubsection{Linux} \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.40.0 perlbrew switch perl-5.40.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 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} \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} \paragraph{Ubuntu: users without perl} \texttt{latexindent-linux} is a standalone executable \announce{2022-10-30}{Linux Ubuntu standalone executable} for Ubuntu Linux (and therefore does not require a Perl distribution) and caches copies of the Perl modules onto your system. It is available from \cite{latexindent-home}. \index{latexindent-linux} \index{linux} \index{TeXLive} \paragraph{Arch-based distributions} \texttt{latexindent} is included in Arch-packaged TeX Live, and can be installed by: \begin{commandshell} sudo pacman -S texlive-binextra perl-yaml-tiny perl-file-homedir \end{commandshell} To enable optional \texttt{--GCString} switch, install \texttt{perl-unicode-linebreak}: \begin{commandshell} sudo pacman -S perl-unicode-linebreak \end{commandshell} \paragraph{Alpine} If you are using Alpine, some \texttt{Perl} modules are not build-compatible with Alpine, but replacements are available through \texttt{apk}. For example, you might use the commands given in \cref{lst:alpine-install}; thanks to \cite{jun-sheaf} for providing these details. \begin{cmhlistings}[style=tcblatex,language=Bash]{\texttt{alpine-install.sh}}{lst:alpine-install} # Installing perl apk --no-cache add miniperl perl-utils # Installing incompatible latexindent perl dependencies via apk apk --no-cache add \ perl-log-dispatch \ perl-namespace-autoclean \ perl-specio \ perl-unicode-linebreak # Installing remaining latexindent perl dependencies via cpan apk --no-cache add curl wget make ls /usr/share/texmf-dist/scripts/latexindent cd /usr/local/bin && \ curl -L https://cpanmin.us/ -o cpanm && \ chmod +x cpanm cpanm -n App::cpanminus cpanm -n File::HomeDir cpanm -n Params::ValidationCompiler cpanm -n YAML::Tiny \end{cmhlistings} Users of NixOS might like to see \href{https://github.com/cmhughes/latexindent.pl/issues/222}{https://github.com/cmhughes/latexindent.pl/issues/222} for tips. \subsubsection{Mac} Users of the Macintosh operating system might like to explore the following commands, for example: \begin{commandshell} brew install perl brew install cpanm cpanm YAML::Tiny cpanm File::HomeDir \end{commandshell} Alternatively, \begin{commandshell} brew install latexindent \end{commandshell} \texttt{latexindent-macos} is a standalone executable \announce{2022-10-30}{macOS standalone executable} for macOS (and therefore does not require a Perl distribution) and caches copies of the Perl modules onto your system. It is available from \cite{latexindent-home}. \index{latexindent-macos} \index{macOS} \index{TeXLive} \subsubsection{Windows} Strawberry Perl users on Windows might use \texttt{CPAN client}. All of the modules are readily available on CPAN \cite{cpan}. \texttt{indent.log} will contain details of the location of the Perl modules on your system. \texttt{latexindent.exe} is a standalone executable for Windows (and therefore does not require a Perl distribution) and caches copies of the Perl modules onto your system; if you wish to see where they are cached, use the \texttt{trace} option, e.g \begin{dosprompt} latexindent.exe -t myfile.tex \end{dosprompt} \subsection{The GCString switch}\label{subsec:the-GCString} If you find that the \texttt{lookForAlignDelims} (as in \cref{subsec:align-at-delimiters}) does not work correctly for your language, then you may wish to use the \texttt{Unicode::GCString} module \announce{2022-03-25}{Unicode::GCString}. \index{perl!Unicode GCString module} \index{switches!--GCString demonstration} 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} Note: this switch does \emph{nothing} for \texttt{latexindent.exe} which loads the module by default. Users of \texttt{latexindent.exe} should not see any difference in behaviour whether they use this switch or not, as \texttt{latexindent.exe} loads the \texttt{Unicode::GCString} module. \section{Updating the path variable}\label{sec:updating-path} \texttt{latexindent.pl} has a few scripts (available at \cite{latexindent-home}) that can update the \texttt{path} variables. Thank you to \cite{jasjuang} for this feature. If you're on a Linux or Mac machine, then you'll want \texttt{CMakeLists.txt} from \cite{latexindent-home}. \subsection{Add to path for Linux} To add \texttt{latexindent.pl} to the path for Linux, follow these steps: \begin{enumerate} \item download \texttt{latexindent.pl} and its associated modules, \texttt{defaultSettings.yaml}, to your chosen directory from \cite{latexindent-home} ; \item within your directory, create a directory called \texttt{path-helper-files} and download \texttt{CMakeLists.txt} and \lstinline!cmake_uninstall.cmake.in! from \cite{latexindent-home}/path-helper-files to this directory; \item 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 mkdir build && cd build 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} \item download \texttt{latexindent.exe}, \texttt{defaultSettings.yaml}, \texttt{add-to-path.bat} from \cite{latexindent-home} to your chosen directory; \item open a command prompt and run the following command to see what is \emph{currently} in your \lstinline!%path%! variable; \begin{dosprompt} echo %path% \end{dosprompt} \item right click on \texttt{add-to-path.bat} and \emph{Run as administrator}; \item log out, and log back in; \item open a command prompt and run \begin{dosprompt} echo %path% \end{dosprompt} to check that the appropriate directory has been added to your \lstinline!%path%!. \end{enumerate} To \emph{remove} the directory from your \lstinline!%path%!, run \texttt{remove-from-path.bat} as administrator. \section{Batches of files}\label{sec:batches} You can \announce{2022-03-25}{batches of files details} instruct \texttt{latexindent.pl} to operate on multiple files. For example, the following calls are all valid \begin{commandshell} latexindent.pl myfile1.tex latexindent.pl myfile1.tex myfile2.tex latexindent.pl myfile*.tex \end{commandshell} We note the following features of the script in relation to the switches detailed in \cref{sec:how:to:use}. \subsection{location of indent.log} If the \texttt{-c} switch is \emph{not} active, then \texttt{indent.log} goes to the directory of the final file called. If the \texttt{-c} switch \emph{is} active, then \texttt{indent.log} goes to the specified directory. \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. More generally, if the \texttt{-o} switch does \emph{not} have a \texttt{+} symbol at the beginning, then the \texttt{-o} switch will be ignored, and is turned it off. For example \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} This behaves as expected by attempting to operate on the line numbers specified for each file. See the examples in \cref{sec:line-switch}. \subsection{interaction with check switches} 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; \item exit code 1 means that the text from \emph{at least one} of the files been file changed. \end{itemize} The interaction with \texttt{checkv} switch is as in the check switch, but with verbose output. \subsection{when a file does not exist} What happens if one of the files can not be operated upon? \begin{itemize} \item if at least one of the files does not exist and \texttt{latexindent.pl} has been called to act upon multiple files, then the exit code is 3; note that \texttt{latexindent.pl} will try to operate on each file that it is called upon, and will not exit with a fatal message in this case; \item if at least one of the files can not be read and \texttt{latexindent.pl} has been called to act upon multiple files, then the exit code is 4; note that \texttt{latexindent.pl} will try to operate on each file that it is called upon, and will not exit with a fatal message in this case; \item if \texttt{latexindent.pl} has been told to operate on multiple files, and some do not exist and some cannot be read, then the exit code will be either 3 or 4, depending upon which it scenario it encountered most recently. \end{itemize} \section{latexindent-yaml-schema.json} \texttt{latexindent.pl} \announce{2022-01-02}{latexindent-yaml-schema.json} ships with \texttt{latexindent-yaml-schema.json} which might help you when constructing your YAML files. \index{json!schema for YAML files} \subsection{VSCode demonstration} To use \texttt{latexindent-yaml-schema.json} with \texttt{VSCode}, you can use the following steps: \index{VSCode} \index{json!VSCode} \begin{enumerate} \item download \texttt{latexindent-yaml-schema.json} from the \texttt{documentation} folder of \cite{latexindent-home}, save it in whichever directory you would like, noting it for reference; \item following the instructions from \cite{vscode-yaml-demo}, for example, you should install the VSCode YAML extension \cite{vscode-yaml-extentions}; \item set up your \texttt{settings.json} file using the directory you saved the file by adapting \cref{lst:settings.json}; on my Ubuntu laptop this file lives at \texttt{/home/cmhughes/.config/Code/User/settings.json}. \end{enumerate} \begin{widepage} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/settings.json}[yaml-TCB]{\texttt{settings.json}}{lst:settings.json} \end{widepage} Alternatively, if you would prefer not to download the json file, you might be able to use an adapted version of \cref{lst:settings-alt.json}. \begin{widepage} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/settings-alt.json}[yaml-TCB]{\texttt{settings-alt.json}}{lst:settings-alt.json} \end{widepage} Finally, if your TeX distribution is up to date, then \texttt{latexindent-yaml-schema.json} \emph{should} be in the documentation folder of your installation, so an adapted version of \cref{lst:settings-alt1.json} may work. \begin{widepage} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/settings-alt1.json}[yaml-TCB]{\texttt{settings-alt1.json}}{lst:settings-alt1.json} \end{widepage} If you have details of how to implement this schema in other editors, please feel encouraged to contribute to this documentation. \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}. \index{conda} You can get a conda installation for example from \cite{conda} or from \cite{anacoda}. \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 conda install latexindent.pl -c conda-forge conda info --envs 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 Repository}. \subsection{Sample docker installation on Ubuntu} To pull the image and show \texttt{latexindent}'s help on Ubuntu: \begin{cmhlistings}[style=tcblatex,language=Bash]{\texttt{docker-install.sh}}{lst:docker-install} # setup docker if not already installed if ! command -v docker &> /dev/null; then sudo apt install docker.io -y sudo groupadd docker sudo gpasswd -a "$USER" docker sudo systemctl restart docker newgrp docker fi # download image and execute docker pull ghcr.io/cmhughes/latexindent.pl docker run ghcr.io/cmhughes/latexindent.pl -h \end{cmhlistings} Once I have run the above, on subsequent logins I run \begin{cmhlistings}[style=tcblatex,language=Bash]{\texttt{docker-install.sh}}{lst:docker-install-subsequent} newgrp docker docker run ghcr.io/cmhughes/latexindent.pl -h \end{cmhlistings} \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} \section{pre-commit} Users of \texttt{.git} may be interested \announce{2022-01-21}{pre-commit for latexindent.pl} in exploring the \texttt{pre-commit} tool \cite{pre-commithome}, which is supported by \texttt{latexindent.pl}. Thank you to \cite{tdegeusprecommit} for contributing this feature, and to \cite{holzhausprecommit} for their contribution to it. To use the \texttt{pre-commit} tool, you will need to install \texttt{pre-commit}; sample instructions for Ubuntu are given in \cref{sec:pre-commit-ubuntu}. Once installed, there are two ways to use \texttt{pre-commit}: using \texttt{CPAN} or using \texttt{conda}, detailed in \cref{sec:pre-commit-cpan} and \cref{sec:pre-commit-conda} respectively. \subsection{Sample pre-commit installation on Ubuntu}\label{sec:pre-commit-ubuntu} On Ubuntu I ran the following command: \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} ... export PATH=$PATH:/home/cmhughes/.local/bin \end{cmhlistings} \subsection{pre-commit defaults} The default values that are employed by \texttt{pre-commit} are shown in \cref{lst:.pre-commit-yaml-default}. \index{pre-commit!default} \cmhlistingsfromfile[style=yaml-LST]{../.pre-commit-hooks.yaml}[yaml-TCB]{\texttt{.pre-commit-hooks.yaml} (default)}{lst:.pre-commit-yaml-default} In particular, the decision has deliberately been made (in collaboration with \cite{holzhausprecommit}) to have the default to employ the following switches: \texttt{overwriteIfDifferent}, \texttt{silent}, \texttt{local}; this is detailed in the lines that specify \texttt{args} in \cref{lst:.pre-commit-yaml-default}. \index{pre-commit!warning} \index{warning!pre-commit} \begin{warning} Users of \texttt{pre-commit} will, by default, have the \texttt{overwriteIfDifferent} switch employed. It is assumed that such users have version control in place, and are intending to overwrite their files. \end{warning} \subsection{pre-commit using CPAN}\label{sec:pre-commit-cpan} To use \texttt{latexindent.pl} with \texttt{pre-commit}, create the file \texttt{.pre-commit-config.yaml} given in \cref{lst:.pre-commit-config.yaml-cpan} in your git-repository. \index{cpan} \index{git} \index{pre-commit!cpan} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/pre-commit-config-cpan.yaml}[yaml-TCB]{\texttt{.pre-commit-config.yaml} (cpan)}{lst:.pre-commit-config.yaml-cpan} Once created, you should then be able to run the following command: \begin{commandshell} pre-commit run --all-files \end{commandshell} A few notes about \cref{lst:.pre-commit-config.yaml-cpan}: \begin{itemize} \item the settings given in \cref{lst:.pre-commit-config.yaml-cpan} instruct \texttt{pre-commit} to use \texttt{CPAN} to get dependencies; \item this requires \texttt{pre-commit} and \texttt{perl} to be installed on your system; \item 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]}. \end{itemize} Naturally you can add options, or omit \texttt{-s} and \texttt{-w}, according to your preference. \subsection{pre-commit using conda}\label{sec:pre-commit-conda} You can also rely on \texttt{conda} (detailed in \cref{sec:app:conda}) instead of \texttt{CPAN} for all dependencies, including \texttt{latexindent.pl} itself. \index{conda} \index{git} \index{pre-commit!conda} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/pre-commit-config-conda.yaml}[yaml-TCB]{\texttt{.pre-commit-config.yaml} (conda)}{lst:.pre-commit-config.yaml-conda} Once created, you should then be able to run the following command: \begin{commandshell} pre-commit run --all-files \end{commandshell} A few notes about \cref{lst:.pre-commit-config.yaml-cpan}: \begin{itemize} \item the settings given in \cref{lst:.pre-commit-config.yaml-conda} instruct \texttt{pre-commit} to use \texttt{conda} to get dependencies; \item this requires \texttt{pre-commit} and \texttt{conda} to be installed on your system; \item 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]}. \end{itemize} \subsection{pre-commit using docker}\label{sec:pre-commit-docker} You can also rely on \texttt{docker} (detailed in \cref{sec:app:docker}) instead of \texttt{CPAN} for all dependencies, including \texttt{latexindent.pl} itself. \index{docker} \index{git} \index{pre-commit!docker} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/pre-commit-config-docker.yaml}[yaml-TCB]{\texttt{.pre-commit-config.yaml} (docker)}{lst:.pre-commit-config.yaml-docker} Once created, you should then be able to run the following command: \begin{commandshell} 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 \texttt{pre-commit} to use \texttt{docker} to get dependencies; \item this requires \texttt{pre-commit} and \texttt{docker} to be installed on your system; \item 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]}. \end{itemize} \subsection{pre-commit example using -l, -m switches} Let's consider a small example, with local \texttt{latexindent.pl} settings in \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} onlyOneBackUp: 1 modifyLineBreaks: oneSentencePerLine: manipulateSentences: 1 \end{cmhlistings} and \texttt{.pre-commit-config.yaml} as in \cref{lst:.latexindent.yaml-switches}: \cmhlistingsfromfile[style=yaml-LST]{demonstrations/pre-commit-config-demo.yaml}[yaml-TCB]{\texttt{.pre-commit-config.yaml} (demo)}{lst:.latexindent.yaml-switches} Now running \begin{commandshell} pre-commit run --all-files \end{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} \end{example} \section{indentconfig options}\label{app:indentconfig:options} This section describes the possible locations for the main configuration file, discussed in \cref{sec:indentconfig}. Thank you to \cite{nehctargl} for this contribution. \announce{2023-01-01}{indentconfig location options} The possible locations of \texttt{indentconfig.yaml} are read one after the other, and reading stops when a valid file is found in one of the paths. Before stating the list, we give summarise in \cref{tab:environment:summary}. \begin{table}[!htb] \centering \caption{indentconfig environment variable summaries} \label{tab:environment:summary} \begin{tabular}{lllll} \toprule environment variable & type & Linux & macOS & Windows \\ \midrule LATEXINDENT\_CONFIG & full path to file & \faCheck & \faCheck & \faCheck \\ XDG\_CONFIG\_HOME & directory path & \faCheck & \faClose & \faClose \\ LOCALAPPDATA & directory path & \faClose & \faClose & \faCheck \\ \bottomrule \end{tabular} \end{table} The following list shows the checked options and is sorted by their respective priority. It uses capitalized and with a dollar symbol prefixed names (e.g. \texttt{\$LATEXINDENT\_CONFIG}) to symbolize environment variables. In addition to that the variable name \texttt{\$homeDir} is used to symbolize your home directory. \begin{enumerate} \item The value of the environment variable \texttt{\$LATEXINDENT\_CONFIG} is treated as highest priority source for the path to the configuration file. \item The next options are dependent on your operating system: \begin{itemize} \item Linux: \begin{enumerate} \item The file at \texttt{\$XDG\_CONFIG\_HOME/latexindent/indentconfig.yaml} \item The file at \texttt{\$homeDir/.config/latexindent/indentconfig.yaml} \end{enumerate} \item Windows: \begin{enumerate} \item The file at \texttt{\$LOCALAPPDATA\textbackslash{}latexindent\textbackslash{}indentconfig.yaml} \item The file at \texttt{\$homeDir\textbackslash{}AppData\textbackslash{}Local\textbackslash{}latexindent\textbackslash{}indentconfig.yaml} \end{enumerate} \item Mac: \begin{enumerate} \item The file at \texttt{\$homeDir/Library/Preferences/latexindent/indentconfig.yaml} \end{enumerate} \end{itemize} \item The file at \texttt{\$homeDir/indentconfig.yaml} \item The file at \texttt{\$homeDir/.indentconfig.yaml} \end{enumerate} \subsection{Why to change the configuration location} This is mostly a question about what you prefer, some like to put all their configuration files in their home directory (see \texttt{\$homeDir} above), whilst some like to sort their configuration. And if you don't care about it, you can just continue using the same defaults. \subsection{How to change the configuration location} This depends on your preferred location, if, for example, you would like to set a custom location, you would have to change the \texttt{\$LATEXINDENT\_CONFIG} environment variable. Although the following example only covers \texttt{\$LATEXINDENT\_CONFIG}, the same process can be applied to \texttt{\$XDG\_CONFIG\_HOME} or \texttt{\$LOCALAPPDATA} because both are environment variables. You just have to change the path to your chosen configuration directory (e.g. \texttt{\$homeDir/.config} or \texttt{\$homeDir\textbackslash{}AppData\textbackslash{}Local} on Linux or Windows respectively) \subsubsection{Linux} To change \texttt{\$LATEXINDENT\_CONFIG} on Linux you can run the following command in a terminal after changing the path: \begin{widepage} \begin{commandshell} echo 'export LATEXINDENT_CONFIG="/home/cmh/latexindent-config.yaml"' >> ~/.profile \end{commandshell} \end{widepage} Context: This command adds the given line to your \texttt{.profile} file (which is commonly stored in \texttt{\$HOME/.profile}). All commands in this file a run after login, so the environment variable will be set after your next login. You can check the value of \texttt{\$LATEXINDENT\_CONFIG} by typing \begin{commandshell} echo $LATEXINDENT_CONFIG /home/cmh/latexindent-config.yaml \end{commandshell} Linux users interested in \texttt{\$XDG\_CONFIG\_HOME} can explore variations of the following commands \begin{commandshell} echo $XDG_CONFIG_HOME echo ${XDG_CONFIG_HOME:=$HOME/.config} echo $XDG_CONFIG_HOME mkdir /home/cmh/.config/latexindent touch /home/cmh/.config/latexindent/indentconfig.yaml \end{commandshell} \subsubsection{Windows} To change \texttt{\$LATEXINDENT\_CONFIG} on Windows you can run the following command in \texttt{powershell.exe} after changing the path: \begin{widepage} \begin{dosprompt} [Environment]::SetEnvironmentVariable ("LATEXINDENT_CONFIG", "\your\config\path", "User") \end{dosprompt} \end{widepage} This sets the environment variable for every user session. \subsubsection{Mac} To change \texttt{\$LATEXINDENT\_CONFIG} on macOS you can run the following command in a terminal after changing the path: \begin{commandshell} echo 'export LATEXINDENT_CONFIG="/your/config/path"' >> ~/.profile \end{commandshell} Context: This command adds the line to your \texttt{.profile} file (which is commonly stored in \texttt{\$HOME/.profile}). All commands in this file a run after login, so the environment variable will be set after your next login. \section{paths demonstration}\label{sec:appendix:paths} As detailed in \vref{subsec:indentconfig} \announce*{2024-04-28}{nested paths demonstration}, the \texttt{paths} field can be specified in any of your \texttt{YAML} files. We will use the file in \cref{lst:paths-demo} for demonstration in what follows. \cmhlistingsfromfile*{demonstrations/paths-demo.tex}{\texttt{paths-demo.tex}}{lst:paths-demo} \begin{example} Consider the settings given in \cref{lst:path1-yaml} and \cref{lst:path2-yaml}. \begin{cmhtcbraster}[raster column skip=.1\linewidth] \cmhlistingsfromfile*[style=yaml-LST]{demonstrations/path1.yaml}[yaml-TCB]{\texttt{path1.yaml}}{lst:path1-yaml} \cmhlistingsfromfile*[style=yaml-LST,showspaces=true]{demonstrations/path2.yaml}[yaml-TCB]{\texttt{path2.yaml}}{lst:path2-yaml} \end{cmhtcbraster} Upon calling \begin{commandshell} latexindent.pl -l=path1.yaml paths-demo.tex \end{commandshell} then we will receive the output given in \cref{lst:paths-demo-mod1}. \cmhlistingsfromfile*[showspaces=true]{demonstrations/paths-demo-mod1.tex}{\texttt{paths-demo-mod1.tex}}{lst:paths-demo-mod1} We note that the settings from \cref{lst:path2-yaml} have been called from \cref{lst:path1-yaml}. On inspection of \texttt{indent.log} from the above call, we see the details of this part of the process given in \cref{lst:path-test1:txt}. \cmhlistingsfromfile*{demonstrations/path-test1.txt}{\texttt{path-test1.txt}}{lst:path-test1:txt} \end{example} \begin{example} Consider the settings given in \cref{lst:path3-yaml} to \cref{lst:path5-yaml}. \begin{cmhtcbraster}[raster columns=3, raster left skip=-3.5cm, raster right skip=-2cm, raster column skip=.03\linewidth] \cmhlistingsfromfile*[style=yaml-LST]{demonstrations/path3.yaml}[yaml-TCB]{\texttt{path3.yaml}}{lst:path3-yaml} \cmhlistingsfromfile*[style=yaml-LST,showspaces=true]{demonstrations/path4.yaml}[yaml-TCB]{\texttt{path4.yaml}}{lst:path4-yaml} \cmhlistingsfromfile*[style=yaml-LST,showspaces=true]{demonstrations/path5.yaml}[yaml-TCB]{\texttt{path5.yaml}}{lst:path5-yaml} \end{cmhtcbraster} Upon calling \begin{commandshell} latexindent.pl -l=path3.yaml paths-demo.tex \end{commandshell} then we will receive the output given in \cref{lst:paths-demo-mod3}. \cmhlistingsfromfile*[showspaces=true]{demonstrations/paths-demo-mod3.tex}{\texttt{paths-demo-mod3.tex}}{lst:paths-demo-mod3} We see that \texttt{path3.yaml} calls \texttt{path4.yaml} which in turn calls \texttt{path5.yaml}. On inspection of \texttt{indent.log} from the above call, we see the details of this part of the process given in \cref{lst:path-test3:txt}. \cmhlistingsfromfile*{demonstrations/path-test3.txt}{\texttt{path-test3.txt}}{lst:path-test3:txt} \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. \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} \hfill \begin{minipage}{.6\linewidth} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/logfile-prefs1.yaml}[yaml-TCB]{\texttt{logfile-prefs1.yaml}}{lst:logfile-prefs1-yaml} \end{minipage} If we run the following command (noting that \texttt{-t} is active) \begin{commandshell} latexindent.pl -t -l=logfile-prefs1.yaml simple.tex \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} +++++ TRACE: environment found: myenv No ancestors found for myenv Storing settings for myenvenvironments indentRulesGlobal specified (0) for environments, ... Using defaultIndent for myenv Putting linebreak after replacementText for myenv looking for COMMANDS and key = {value} TRACE: Searching for commands with optional and/or mandatory arguments AND key = {value} looking for SPECIAL begin/end TRACE: Searching myenv for special begin/end (see specialBeginEnd) TRACE: Searching myenv for optional and mandatory arguments ... no arguments found ----- \end{cmhlistings} Notice that the information given about \texttt{myenv} is `framed' using \texttt{+++++} and \lstinline!-----! respectively. \end{example} \section{Encoding}\label{app:encoding} When using latexindent in different ways on different systems, the range of characters supported by its switches/flags/options (see \vref{sec:commandline}) may vary. For the Windows executable file \texttt{latexindent.exe}, its options support UTF-8 characters. For the Windows Perl script \texttt{latexindent.pl}, its option switch supports the characters supported by the encoding corresponding to the system code page. You can check the system code page by running the following command in either \texttt{cmd.exe} or \texttt{powershell.exe}: \begin{dosprompt} chcp \end{dosprompt} which may receive the following result \begin{dosprompt} Active code page: 936 \end{dosprompt} and then the characters supported by the code page can be found in \href{Microsoft's code page identifier table}{https://learn.microsoft.com/en-us/windows/win32/intl/code-page-identifiers}. For example, the characters supported by the encoding corresponding to code page 936 are: ANSI/OEM Simplified Chinese (PRC, Singapore); Chinese Simplified (GB2312). For Ubuntu Linux and macOS users, whether using the Perl script or the executable file, the options support UTF-8 characters. \section{dos2unix linebreak adjustment} \yamltitle{dos2unixlinebreaks}*{integer} If you use \texttt{latexindent.pl} on a dos-based Windows file on Linux \announce{2021-06-19}{dos2unix linebreaks} then you may find that trailing horizontal space is not removed as you hope. In such a case, you may wish to try setting \texttt{dos2unixlinebreaks} to 1 and employing, for example, the following command. \begin{commandshell} latexindent.pl -y="dos2unixlinebreaks:1" myfile.tex \end{commandshell} See \cite{bersbersbers} for further dertails. \section{Differences from Version 2.2 to 3.0}\label{app:differences} There are a few (small) changes to the interface when comparing Version 2.2 to Version 3.0. Explicitly, in previous versions you might have run, for example, \index{switches!-o demonstration} \begin{commandshell} latexindent.pl -o myfile.tex outputfile.tex \end{commandshell} whereas in Version 3.0 you would run any of the following, for example, \index{switches!-o demonstration} \begin{commandshell} latexindent.pl -o=outputfile.tex myfile.tex latexindent.pl -o outputfile.tex myfile.tex latexindent.pl myfile.tex -o outputfile.tex latexindent.pl myfile.tex -o=outputfile.tex latexindent.pl myfile.tex -outputfile=outputfile.tex latexindent.pl myfile.tex -outputfile outputfile.tex \end{commandshell} noting that the \emph{output} file is given \emph{next to} the \texttt{-o} switch. The fields given in \cref{lst:obsoleteYaml} are \emph{obsolete} from Version 3.0 onwards. \cmhlistingsfromfile[style=yaml-LST]{demonstrations/obsolete.yaml}[yaml-obsolete]{Obsolete YAML fields from Version 3.0}{lst:obsoleteYaml} There is a slight difference when specifying indentation after headings; specifically, we now write \texttt{indentAfterThisHeading} instead of \texttt{indent}. See \cref{lst:indentAfterThisHeadingOld,lst:indentAfterThisHeadingNew} \begin{minipage}{.45\textwidth} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/indentAfterThisHeadingOld.yaml}[yaml-TCB]{\texttt{indentAfterThisHeading} in Version 2.2}{lst:indentAfterThisHeadingOld} \end{minipage}% \hfill \begin{minipage}{.45\textwidth} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/indentAfterThisHeadingNew.yaml}[yaml-TCB]{\texttt{indentAfterThisHeading} in Version 3.0}{lst:indentAfterThisHeadingNew} \end{minipage}% To specify \texttt{noAdditionalIndent} for display-math environments in Version 2.2, you would write YAML as in \cref{lst:noAdditionalIndentOld}; as of Version 3.0, you would write YAML as in \cref{lst:indentAfterThisHeadingNew1} or, if you're using \texttt{-m} switch, \cref{lst:indentAfterThisHeadingNew2}. \index{specialBeginEnd!update to displaymath V3.0} \begin{minipage}{.45\textwidth} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/noAddtionalIndentOld.yaml}[yaml-TCB]{\texttt{noAdditionalIndent} in Version 2.2}{lst:noAdditionalIndentOld} \end{minipage}% \hfill \begin{minipage}{.45\textwidth} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/noAddtionalIndentNew.yaml}[yaml-TCB]{\texttt{noAdditionalIndent} for \texttt{displayMath} in Version 3.0}{lst:indentAfterThisHeadingNew1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/noAddtionalIndentNew1.yaml}[yaml-TCB]{\texttt{noAdditionalIndent} for \texttt{displayMath} in Version 3.0}{lst:indentAfterThisHeadingNew2} \end{minipage}% \mbox{}\hfill \begin{minipage}{.25\textwidth} \hrule \hfill\itshape End\\\mbox{}\hfill\mbox{}\rlap{\hfill\includegraphics{logo}} \end{minipage} \end{document}

% arara: pdflatex % arara: makeindex: {style: latexindent.ist} % arara: bibtex % arara: pdflatex if changed (toFile('latexindent.aux')) || changed (toFile('latexindent.ind')) % arara: pdflatex if changed (toFile('latexindent.aux')) % arara: pdflatex if changed (toFile('latexindent.aux')) \documentclass[10pt]{article} % This program is free software: you can redistribute it and/or modify % it under the terms of the GNU General Public License as published by % the Free Software Foundation, either version 3 of the License, or % (at your option) any later version. % % This program is distributed in the hope that it will be useful, % but WITHOUT ANY WARRANTY; without even the implied warranty of % MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the % GNU General Public License for more details. % % See . \usepackage[left=4.5cm,right=2.5cm,showframe=false, top=2cm,bottom=1.5cm,marginparsep=2cm]{geometry} % page setup \usepackage{lmodern} \usepackage{parskip} % paragraph skips \usepackage{booktabs} % beautiful tables \usepackage{listings} % nice verbatim environments \usepackage{titlesec} % customize headings \usepackage{titletoc} % customize headings \usepackage{multicol} \usepackage{changepage} % adjust width of page \usepackage{fancyhdr} % headers & footers \usepackage{fontawesome} \usepackage[sc,format=hang,font=small]{caption} % captions \usepackage[backend=bibtex,sorting=ynt]{biblatex} % bibliography \usepackage{tcolorbox} % framed environments \usepackage{tikz} \usepackage{xparse} \usepackage[charter]{mathdesign} % changes font \usepackage[expansion=false,kerning=true]{microtype} % better kerning \usepackage{enumitem} % custom lists \usepackage{longtable} \usepackage{array} \usepackage{totalcount} \usepackage{standalone} % setup gitinfo2, as in the manual, details just above begin{document} \usepackage[mark]{gitinfo2} % tikz, tcolorbox libraries \usetikzlibrary{positioning} \usetikzlibrary{decorations.pathmorphing} \usetikzlibrary{decorations,shapes} \usepackage{varioref} % the documentation library from tcolorbox loads hyperref \tcbuselibrary{breakable,xparse,documentation,hooks,raster} \hypersetup{ pdfauthor={Chris Hughes}, pdftitle={latexindent.pl package}, pdfkeywords={perl;beautify;indentation}, bookmarksnumbered, bookmarksopen, linktocpage, colorlinks=true, linkcolor=blue, citecolor=black, } \usepackage{cleveref} % create my own star style, for re-use at various points \tikzset{cmhstar/.style={star,star point ratio=2.25,fill=cmhgold,draw=orange,}} % shortcut command for displaying star in documentation \newcommand{\stardemo}[1][]{\begin{tikzpicture} \node at (10:.1cm)[very thin,cmhstar,scale=0.25,rotate=20,#1]{}; \node at (120:.1cm)[very thin,cmhstar,scale=0.15,rotate=-10,#1]{}; \node at (235:.1cm)[very thin,cmhstar,scale=0.2,rotate=-20,#1]{}; \end{tikzpicture}} % totalcount \DeclareTotalCounter{lstlisting} % customise the \tcbdocnew command \tcbset{doclang/new={{\bfseries\color{green!50!black}N\normalfont\color{black}}}} \tcbset{doclang/updated={{\bfseries\color{green!50!black}U\normalfont\color{black}}}} \tcbset{doc marginnote={width=1.6cm}} % \announce * { YYYY-MM-DD }*{ } % % NEW as of current version % \announce*{date}*[text] means *updated* as of % \announce*{date}[text] means *new* as of % % NOT new as of current version % \announce{date}*[text] means *updated* as of % \announce{date}[text] means *new* as of % \NewDocumentCommand{\announce}{ s m s m }{% \IfBooleanTF{#1}% {% \announce* % NEW in current version \tcbdocmarginnote[colframe=orange, overlay={\node at ([yshift=0mm,xshift=1mm]frame.north east) {\stardemo}; }]{% \IfBooleanTF{#3}% {% \announce*{date}*[text] means *updated* as of \tcbdocupdated{#2}% }% {% \announce*{date}[text] means *new* as of \tcbdocnew{#2}% }% }% \IfBooleanTF{#3}% {% \addcontentsline{new}{cmhtitle}{#4 (U)}% }% {% \addcontentsline{new}{cmhtitle}{#4 (N)}% }% }% {% \announce % NOT new in current version \tcbdocmarginnote[colframe=gray!50!white, doclang/new={{\color{gray}N\normalfont\color{gray}}}, doclang/updated={{\color{gray}U\normalfont\color{gray}}}, ]{% \IfBooleanTF{#3}% {% \announce{date}*[text] means *updated* as of \tcbdocupdated{#2}% }% {% \announce{date}[text] means *new* as of \tcbdocnew{#2}% }% }% }} \reversemarginpar % bibliographies \addbibresource{latex-indent} \addbibresource{contributors} \BiblatexSplitbibDefernumbersWarningOff % http://tex.stackexchange.com/questions/122135/how-to-add-a-png-icon-on-the-right-side-of-a-tcolorbox-title \newtcolorbox{warning}{parbox=false, breakable, enhanced, arc=0mm, colback=red!5, colframe=red, leftrule=12mm,% title={Warning!}, overlay={\node[anchor=north west,outer sep=2pt] at (frame.north west) {\includegraphics[width=8mm]{warning}}; } } \definecolor{harvestgold}{cmyk}{0.00, 0.05, 0.51, 0.07} %EDE275 \definecolor{cmhgold}{cmyk}{0,0.178,0.909,0.008} %FDD017 \colorlet{cmhgray}{gray!30!white} \makeatletter \tcbset{ addtolol/.style={list entry={\kvtcb@title},add to list={lol}{lstlisting}}, addtololstar/.style={list entry={\kvtcb@title},add to list={lol}{lstlistingstar}}, cmhlistings/.style={ colback=blue!5!white, colframe=white!25!black,colback=white, top=0cm, bottom=0cm, left=0mm, listing only, center title, listing engine=listings, listing options={showtabs=true,tabsize=4,showspaces=true}, boxrule=0pt, toprule=1pt,bottomrule=1pt, titlerule=1pt, colframe=white!40!black, colback=white, sharp corners, colbacktitle=white!75!black }, tex-TCB/.style={ listing only, listing engine=listings, left=0cm, boxrule=0pt, sharp corners, center title, colframe=white!40!black, colback=white, sharp corners, colbacktitle=white!75!black, toprule=1pt, bottomrule=1pt, titlerule=1pt, }, yaml-TCB/.style={ listing only, listing engine=listings, left=0cm, boxrule=0pt, sharp corners, center title, colbacktitle=white!75!blue, colframe=white!25!blue, colback=white!90!blue, toprule=2pt, titlerule=2pt, }, MLB-TCB/.style={ yaml-TCB, center title, colframe=cmhgold, colbacktitle=harvestgold, colback=white!60!cmhgold, width=0.9\linewidth, before=\centering, enhanced, overlay={\node[anchor=north east,outer sep=2pt,draw=cmhgold,very thick,double,fill=harvestgold,font =\small] at ([yshift=-3mm]frame.north east) {\texttt{-m}}; } }, replace-TCB/.style={ yaml-TCB, center title, colbacktitle=white!75!green, colframe=white!25!green, colback=white!90!green, width=0.9\linewidth, before=\centering, enhanced, overlay={\node[anchor=north east,outer sep=2pt,draw=white!25!green,very thick,circle,fill=white!75!green,font =\small] at ([yshift=-3mm]frame.north east) {\texttt{-r}}; } }, yaml-obsolete/.style={ listing only, listing engine=listings, left=0cm, boxrule=0pt, sharp corners, center title, toprule=2pt, titlerule=2pt, colframe=white!25!red, colbacktitle=white!75!red, colback=white!90!red, }, new-to-this-version/.style={ enhanced, overlay app={\node at ([yshift=0mm,xshift=0mm]frame.north east) {\stardemo[scale=1.2]}; }, addtololstar, }, } \DeclareTCBListing[use counter=lstlisting]{cmhlistings}{s O{} m m}{% cmhlistings, IfBooleanTF={#1}{new-to-this-version}{addtolol}, center title, title={\color{black}{\scshape Listing \thetcbcounter}: ~#3},label={#4}, listing engine=listings, listing options={#2}, } \DeclareDocumentEnvironment{cmhtcbraster}{O{}}{\begin{tcbraster}[ new-to-this-version/.style={ enhanced, overlay app={\node[anchor=south east] at ([yshift=-3mm,xshift=3mm]frame.north east) {\stardemo[scale=1.2]}; }, addtololstar, }, raster valign=top,raster columns=2,#1]}{\end{tcbraster}} % \cmhlistingsfromfile % * no star: not new, star: new #1 % [ listing options ] #2 % {} #3 % [] #4 % {} #5 % {<label>} #6 % % for example, % \cmhlistingsfromfile*[listing options]... is NEW % \cmhlistingsfromfile[listing options]... is not new \DeclareTCBInputListing[use counter=lstlisting]{\cmhlistingsfromfile}{s O{} m O{} m m}{% cmhlistings, listing file={#3}, listing options={style=tcblatex,showspaces=false,#2}, title={\color{black}{\scshape Listing \thetcbcounter}: ~#5},label={#6}, #4, IfBooleanTF={#1}{new-to-this-version}{addtolol}, } \makeatletter \@tempswafalse \def\@tempa{draft} \@for\next:=\@classoptionslist\do {\ifx\next\@tempa\@tempswatrue\fi} \if@tempswa % draft option is active \RenewDocumentCommand{\cmhlistingsfromfile}{s O{} s m O{} m m}{\captionof{lstlisting}{#6}\label{#7}} \renewcommand{\stardemo}[1][]{$\star$} \fi % command shell \newtcblisting{commandshell}{colback=black,colupper=white,colframe=yellow!75!black, 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$\$ }}} % dosprompt \newtcblisting{dosprompt}{ colback=black, colupper=white, colframe=yellow!75!black, listing only, listing options={ language=command.com, morekeywords={latexindent,pl}, keywordstyle=\color{blue!35!white}\bfseries, basicstyle=\small\color{white}\ttfamily }, listing engine=listings, left=0cm, every listing line={\textcolor{white}{\small\ttfamily\fontseries{b}\selectfont C:\textbackslash Users\textbackslash cmh$>$}}} \lstset{% basicstyle=\small\ttfamily,language={[LaTeX]TeX}, numberstyle=\ttfamily%\small, breaklines=true, keywordstyle=\color{blue}, % keywords commentstyle=\color{purple}, % comments tabsize=3, }% \DeclareTCBListing[use counter=lstlisting]{yaml}{O{} m O{} m}{ yaml-TCB, listing options={ style=tcblatex, numbers=none, numberstyle=\color{red}, #1, }, title={\color{black}{\scshape Listing \thetcbcounter}: ~#2},label={#4}, #3, } % reference: https://tex.stackexchange.com/questions/145504/yaml-syntax-highlighting/654987#654987 \lstdefinestyle{yaml-LST}{ style=tcblatex, numbers=none, numberstyle=\color{red}\small, basicstyle=\color{black}\ttfamily\small, string=[s]{'}{'}, stringstyle=\color{black}\ttfamily\small, comment=[l]{:}, commentstyle=\color{blue}\ttfamily\small, morecomment=[l]{-}, } \lstdefinestyle{demo}{ numbers=none, linewidth=1.25\textwidth, columns=fullflexible, } \lstdefinestyle{lineNumbersTeX}{ numbers=left, numberstyle=\color{blue}, } \lstdefinestyle{fileExtensionPreference}{ style=yaml-LST, firstnumber=47,linerange={47-51}, numbers=left, } \lstdefinestyle{logFilePreferences}{ style=yaml-LST, firstnumber=90,linerange={90-104}, numbers=left, } \lstdefinestyle{verbatimEnvironments}{ style=yaml-LST, firstnumber=108,linerange={108-111}, numbers=left, } \lstdefinestyle{verbatimCommands}{ style=yaml-LST, firstnumber=114,linerange={114-116}, numbers=left, } \lstdefinestyle{noIndentBlock}{ style=yaml-LST, firstnumber=121,linerange={121-123}, numbers=left, } \lstdefinestyle{removeTrailingWhitespace}{ style=yaml-LST, firstnumber=153,linerange={153-155}, numbers=left, } \lstdefinestyle{fileContentsEnvironments}{ style=yaml-LST, firstnumber=127,linerange={127-129}, numbers=left, } \lstdefinestyle{lookForPreamble}{ style=yaml-LST, firstnumber=135,linerange={135-140}, numbers=left, } \lstdefinestyle{lookForAlignDelims}{ style=yaml-LST, firstnumber=158,linerange={158-177}, numbers=left, } \lstdefinestyle{indentAfterItems}{ style=yaml-LST, firstnumber=242,linerange={242-249}, numbers=left, } \lstdefinestyle{itemNames}{ style=yaml-LST, firstnumber=255,linerange={255-257}, numbers=left, } \lstdefinestyle{specialBeginEnd}{ style=yaml-LST, firstnumber=261,linerange={261-275}, numbers=left, } \lstdefinestyle{indentAfterHeadings}{ style=yaml-LST, firstnumber=285,linerange={285-294}, numbers=left, } \lstdefinestyle{noAdditionalIndentGlobalEnv}{ style=yaml-LST, firstnumber=343,linerange={343-344}, numbers=left, } \lstdefinestyle{noAdditionalIndentGlobal}{ style=yaml-LST, firstnumber=343,linerange={343-355}, numbers=left, } \lstdefinestyle{indentRulesGlobalEnv}{ style=yaml-LST, firstnumber=359,linerange={359-360}, numbers=left, } \lstdefinestyle{indentRulesGlobal}{ style=yaml-LST, firstnumber=359,linerange={359-371}, numbers=left, } \lstdefinestyle{commandCodeBlocks}{ style=yaml-LST, firstnumber=374,linerange={374-389}, numbers=left, } \lstdefinestyle{modifylinebreaks}{ style=yaml-LST, firstnumber=502,linerange={502-504}, numbers=left, } \lstdefinestyle{textWrapOptions}{ style=yaml-LST, firstnumber=532,linerange={532-533}, numbers=left, } \lstdefinestyle{textWrapOptionsAll}{ style=yaml-LST, firstnumber=532,linerange={532-559}, numbers=left, } \lstdefinestyle{oneSentencePerLine}{ style=yaml-LST, firstnumber=505,linerange={505-531}, numbers=left, } \lstdefinestyle{sentencesFollow}{ style=yaml-LST, firstnumber=511,linerange={511-519}, numbers=left, } \lstdefinestyle{sentencesBeginWith}{ style=yaml-LST, firstnumber=520,linerange={520-523}, numbers=left, } \lstdefinestyle{sentencesEndWith}{ style=yaml-LST, firstnumber=524,linerange={524-529}, numbers=left, } \lstdefinestyle{sentencesDoNOTcontain}{ style=yaml-LST, firstnumber=530,linerange={530-531}, numbers=left, } \lstdefinestyle{modifylinebreaksEnv}{ style=yaml-LST, firstnumber=561,linerange={561-570}, numbers=left, } \lstdefinestyle{replacements}{ style=yaml-LST, firstnumber=622,linerange={622-627}, numbers=left, } \lstdefinestyle{fineTuning}{ style=yaml-LST, firstnumber=631,linerange={631-686}, numbers=left, } % stars around contributors \pgfdeclaredecoration{stars}{initial}{ \state{initial}[width=15pt] { \pgfmathparse{round(rnd*100)} \pgfsetfillcolor{yellow!\pgfmathresult!orange} \pgfsetstrokecolor{yellow!\pgfmathresult!red} \pgfnode{star}{center}{}{}{\pgfusepath{stroke,fill}} } \state{final} { \pgfpathmoveto{\pgfpointdecoratedpathlast} } } \newtcolorbox{stars}{% enhanced jigsaw, breakable, % allow page breaks left=0cm, top=0cm, before skip=0.2cm, boxsep=0cm, frame style={draw=none,fill=none}, % hide the default frame colback=white, overlay={ \draw[inner sep=0,minimum size=rnd*15pt+2pt] decorate[decoration={stars,segment length=2cm}] { decorate[decoration={zigzag,segment length=2cm,amplitude=0.3cm}] { ([xshift=-.5cm,yshift=0.1cm]frame.south west) -- ([xshift=-.5cm,yshift=0.4cm]frame.north west) }}; \draw[inner sep=0,minimum size=rnd*15pt+2pt] decorate[decoration={stars,segment length=2cm}] { decorate[decoration={zigzag,segment length=2cm,amplitude=0.3cm}] { ([xshift=.75cm,yshift=0.1cm]frame.south east) -- ([xshift=.75cm,yshift=0.6cm]frame.north east) }}; \node[anchor=north west,outer sep=2pt,opacity=0.25] at ([xshift=-4.25cm]frame.north west) {\resizebox{3cm}{!}{\faGithub}}; }, % paragraph skips obeyed within tcolorbox parbox=false, } \newtcolorbox[auto counter]{example}{breakable, enhanced jigsaw, before skip balanced, after skip balanced, frame hidden, % % title stuff % title={example~\thetcbcounter}, fonttitle=\bfseries\sffamily, detach title, coltitle=black, colback=white, grow to left by=6mm, % % circles and line by the side % overlay unbroken and first={% \node at ([xshift=-8mm,yshift=-4.5mm]interior.north west) {\bfseries example \thetcbcounter}; \path [fill=black] ([xshift=1mm,yshift=3mm]interior.south east) node{\hbox{\rule{1ex}{1ex}}}; }, overlay last={% \path [fill=black] ([xshift=1mm,yshift=3mm]interior.south east) node{\hbox{\rule{1ex}{1ex}}}; }, parbox=false, } % copied from /usr/local/texlive/2013/texmf-dist/tex/latex/biblatex/bbx/numeric.bbx % the only modification is the \stars and \endstars \defbibenvironment{specialbib} {\stars\list {\printtext[labelnumberwidth]{% \printfield{prefixnumber}% \printfield{labelnumber}}} {\setlength{\labelwidth}{\labelnumberwidth}% \setlength{\leftmargin}{\labelwidth}% \setlength{\labelsep}{\biblabelsep}% \addtolength{\leftmargin}{\labelsep}% \setlength{\itemsep}{\bibitemsep}% \setlength{\parsep}{\bibparsep}}% \renewcommand*{\makelabel}[1]{\hss##1}} {\endlist\endstars} {\item} \newcommand{\flagbox}[1]{% \par \makebox[30pt][l]{% \hspace{-1cm}% \ttfamily\fontseries{b}\selectfont #1 }% } \NewDocumentCommand{\yamltitle}{O{} m s m}{% \par \makebox[30pt][l]{% \hspace{-2cm}% \tcbox[colframe=black!50!white,boxrule=.5pt,sharp corners,#1]{% {\ttfamily\fontseries{b}\selectfont{\color{blue!80!white}#2}}: % \IfBooleanTF{#3} {$\langle$\itshape #4$\rangle$} {{\bfseries #4}} }} \par\nobreak% } \newcommand{\fixthis}[1] {% \marginpar{\huge \color{red} \framebox{FIX}}% \typeout{FIXTHIS: p\thepage : #1^^J}% } \newcommand*\ruleline[1]{% \par\noindent\raisebox{.8ex}{\makebox[\linewidth]{\hrulefill\hspace{1ex}\raisebox{-1.8ex}{#1}\hspace{1ex}\hrulefill}}} \newcommand{\imagetouse}{logo-bw} % custom section \titleformat% Formatting the header {\section} % command [block] % shape - Only managed to get it working with block {\normalfont\bfseries\huge} % format - Change here as needed {\centering {\scshape Section \thesection}\\} % the section {0pt} % sep {\centering \ruleline{\includegraphics{\imagetouse}}\\ % The horizontal rule \centering} % And the actual title % custom subsection \titleformat{\subsection} {\normalfont\bfseries} {\llap{\thesubsection\hskip.5cm}} {0pt} {} % custom subsubsection \titleformat{\subsubsection} {\normalfont\bfseries} {\llap{\thesubsubsection\hskip.5cm}} {0pt} {} % custom paragraph \titleformat{\paragraph} {\normalfont\bfseries} {\llap{\theparagraph\hskip.5cm}} {0pt} {} % title spacing \titlespacing\section{0pt}{12pt plus 4pt minus 2pt}{34pt plus 2pt minus 2pt} \titlespacing\subsection{0pt}{12pt plus 4pt minus 2pt}{4pt plus 2pt minus 2pt} \titlespacing\subsubsection{0pt}{12pt plus 4pt minus 2pt}{4pt plus 2pt minus 2pt} \titlespacing\paragraph{0pt}{12pt plus 4pt minus 2pt}{4pt plus 2pt minus 2pt} % list of listings \contentsuse{lstlisting}{lol} \titleclass{\lstlistingstar}{straight}[\section] \titleformat{\lstlistingstar}{}{}{}{} \titlecontents{lstlistingstar}[2em] {\addvspace{0.25pc}} {} {\llap{\stardemo}\thecontentslabel} {\titlerule*[0.5em]{$\cdot$}\contentspage} [] \titlecontents{lstlisting}[2em] {\addvspace{0.25pc}} {\thecontentslabel} {\thecontentslabel} {\titlerule*[0.5em]{$\cdot$}\contentspage} [] \AtBeginDocument{\addtocontents{lol}{\protect\begin{widepage}\protect\begin{multicols}{2}}} \preto{\printindex}{\addtocontents{lol}{\protect\end{multicols}\protect\end{widepage}}} % cleveref settings \crefname{table}{Table}{Tables} \Crefname{table}{Table}{Tables} \crefname{figure}{Figure}{Figures} \Crefname{figure}{Figure}{Figures} \crefname{section}{Section}{Sections} \Crefname{section}{Section}{Sections} \crefname{listing}{Listing}{Listings} \Crefname{listing}{Listing}{Listings} % headers and footers \fancyhf{} % delete current header and footer \fancyhead[R]{\bfseries\thepage% \tikz[remember picture,overlay] { \node at (1,0){\includegraphics{logo-bw}}; } } \fancyhead[L]{\rightmark} \fancyheadoffset[L]{3cm} \pagestyle{fancy} % renew plain style \fancypagestyle{plain}{% \fancyhf{} % clear all header and footer fields \renewcommand{\headrulewidth}{0pt} \renewcommand{\footrulewidth}{0pt}} % widepage environment \newenvironment{widepage}{\begin{adjustwidth}{-3cm}{0cm}}{\end{adjustwidth}} % symbols for the m switch \newcommand{\BeginStartsOnOwnLine}{\color{red}\spadesuit} \newcommand{\BodyStartsOnOwnLine}{\color{red}\heartsuit} \newcommand{\EndStartsOnOwnLine}{\color{red}\diamondsuit} \newcommand{\EndFinishesWithLineBreak}{\color{red}\clubsuit} \newcommand{\ElseStartsOnOwnLine}{\color{red}\bigstar} \newcommand{\ElseFinishesWithLineBreak}{\color{red}\square} \newcommand{\OrStartsOnOwnLine}{\color{red}\blacktriangle} \newcommand{\OrFinishesWithLineBreak}{\color{red}\blacktriangledown} \newcommand{\EqualsStartsOnOwnLine}{\color{red}\bullet} % table rules \setlength\heavyrulewidth{0.25ex} % gitinfo2 settings \renewcommand{\gitMark}{\gitBranch\,@\,\gitAbbrevHash{}\,\textbullet{}\,\gitAuthorDate\,\textbullet{}\faGithub\,\textbullet{}\gitRel} % setting up gitinfo2: % copy the file post-xxx-sample.txt from http://mirror.ctan.org/macros/latex/contrib/gitinfo2 % and put it in .git/hooks/post-checkout % then % cd .git/hooks % chmod g+x post-checkout % chmod +x post-checkout % cp post-checkout post-commit % cp post-checkout post-merge % cd ../.. % git checkout master % git checkout develop % ls .git % and you should see gitHeadInfo.gin % % Make sure that the 'V' is included in the below! % % RELTAG=$(git describe --tags --long --always --dirty='-*' --match 'V[0-9]*.*' 2>/dev/null) % http://tex.stackexchange.com/questions/233843/textasteriskcentered-invisible-with-garamondmathdesign % remove the definition of \textasteriskcentered for TS1 encoding \UndeclareTextCommand{\textasteriskcentered}{TS1} % reinstate a default encoding \DeclareTextSymbolDefault{\textasteriskcentered}{OT1} % suitably define the command \DeclareTextCommand{\textasteriskcentered}{OT1}{\raisebox{-.7ex}[1ex][0pt]{*}} % new features list \newcommand{\listOfNewFeatures}{\setcounter{tocdepth}{4}\@starttoc{new}} \contentsuse{cmhtitle}{new} % toc settings \titleclass{\cmhtitle}{straight}[\subsection] \titleformat{\cmhtitle}{}{}{}{} \titlecontents{cmhtitle}% <paragraph> [2cm]% <left> {\small\itshape}% <above-code> {}% <numbered-entry-format>; you could also use {\thecontentslabel. } to show the numbers {}% <numberless-entry-format> {\titlerule*[0.5em]{$\cdot$}\contentspage} % to explore in the future: % partial toc customisation % https://tex.stackexchange.com/questions/66345/how-to-remove-section-indentation-in-partial-toc-using-titletoc \setcounter{secnumdepth}{6} \setcounter{tocdepth}{4} \makeindex \newif\iftestdefaultsettings \testdefaultsettingsfalse %\testdefaultsettingstrue \begin{document} % arara: pdflatex: { files: [latexindent]} \section{Introduction} \subsection{Thanks} I first created \texttt{latexindent.pl} to help me format chapter files in a big project. After I blogged about it on the \TeX{} stack exchange \cite{cmhblog} I received some positive feedback and follow-up feature requests. A big thank you to Harish Kumar \cite{harish} who helped to develop and test the initial versions of the script. The \texttt{YAML}-based interface of \texttt{latexindent.pl} was inspired by the wonderful \texttt{arara} tool; any similarities are deliberate, and I hope that it is perceived as the compliment that it is. Thank you to Paulo Cereda and the team for releasing this awesome tool; I initially worried that I was going to have to make a GUI for \texttt{latexindent.pl}, but the release of \texttt{arara} has meant there is no need. There have been several contributors to the project so far (and hopefully more in the future!); thank you very much to the people detailed in \vref{sec:contributors} for their valued contributions, and thank you to those who report bugs and request features at \cite{latexindent-home}. \subsection{License} \texttt{latexindent.pl} is free and open source, and it always will be; it is released under the GNU General Public License v3.0. Before you start using it on any important files, bear in mind that \texttt{latexindent.pl} has the option to overwrite your \texttt{.tex} files. It will always make at least one backup (you can choose how many it makes, see \cpageref{page:onlyonebackup}) but you should still be careful when using it. The script has been tested on many files, but there are some known limitations (see \cref{sec:knownlimitations}). You, the user, are responsible for ensuring that you maintain backups of your files before running \texttt{latexindent.pl} on them. I think it is important at this stage to restate an important part of the license here: \begin{quote}\itshape This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. \end{quote} There is certainly no malicious intent in releasing this script, and I do hope that it works as you expect it to; if it does not, please first of all make sure that you have the correct settings, and then feel free to let me know at \cite{latexindent-home} with a complete minimum working example as I would like to improve the code as much as possible. \begin{warning} Before you try the script on anything important (like your thesis), test it out on the sample files in the \texttt{test-case} directory \cite{latexindent-home}. \index{warning!be sure to test before use} \end{warning} \emph{If you have used any version 2.* of \texttt{latexindent.pl}, there are a few changes to the interface; see \vref{app:differences} and the comments throughout this document for details}. \subsection{Quick start}\label{sec:quickstart} When \texttt{latexindent.pl} reads and writes files, the files are read and written in UTF-8 format by default. That is to say, the encoding format for tex and yaml files needs to be in UTF-8 format. 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 no explanation in this section, which is deliberate for a quick start. The rest of the manual is more verbose. \cmhlistingsfromfile{demonstrations/quick-start.tex}{\texttt{quick-start.tex}}{lst:quick-start} 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} latexindent.pl -l quick-start1.yaml quick-start.tex \end{commandshell} gives \cref{lst:quick-start-mod1}. \begin{cmhtcbraster} \cmhlistingsfromfile[showspaces=true]{demonstrations/quick-start-mod1.tex}{\texttt{quick-start-mod1.tex}}{lst:quick-start-mod1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/quick-start1.yaml}[yaml-TCB]{\texttt{quick-start1.yaml}}{lst:quick-start1yaml} \end{cmhtcbraster} See \cref{subsec:indentation:and:horizontal:space}. \end{example} \begin{example} Running \begin{commandshell} latexindent.pl -l quick-start2.yaml quick-start.tex \end{commandshell} gives \cref{lst:quick-start-mod2}. \begin{cmhtcbraster} \cmhlistingsfromfile[showspaces=true]{demonstrations/quick-start-mod2.tex}{\texttt{quick-start-mod2.tex}}{lst:quick-start-mod2} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/quick-start2.yaml}[yaml-TCB]{\texttt{quick-start2.yaml}}{lst:quick-start2yaml} \end{cmhtcbraster} See \cref{sec:noadd-indent-rules}. \end{example} \begin{example} 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-start-mod3.tex}{\texttt{quick-start-mod3.tex}}{lst:quick-start-mod3} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/quick-start3.yaml}[yaml-TCB]{\texttt{quick-start3.yaml}}{lst:quick-start3yaml} \end{cmhtcbraster} See \cref{sec:noadd-indent-rules}. \end{example} \begin{example} 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-start-mod4.tex}{\texttt{quick-start-mod4.tex}}{lst:quick-start-mod4} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/quick-start4.yaml}[MLB-TCB]{\texttt{quick-start4.yaml}}{lst:quick-start4yaml} \end{cmhtcbraster} Full details of text wrapping in \cref{subsec:textwrapping}. \end{example} \begin{example} 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-start-mod5.tex}{\texttt{quick-start-mod5.tex}}{lst:quick-start-mod5} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/quick-start5.yaml}[MLB-TCB]{\texttt{quick-start5.yaml}}{lst:quick-start5yaml} \end{cmhtcbraster} Full details of text wrapping in \cref{subsec:textwrapping}. \end{example} \begin{example} 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-start-mod6.tex}{\texttt{quick-start-mod6.tex}}{lst:quick-start-mod6} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/quick-start6.yaml}[MLB-TCB]{\texttt{quick-start6.yaml}}{lst:quick-start6yaml} \end{cmhtcbraster} This is an example of a \emph{poly-switch}; full details of \emph{poly-switches} are covered in \cref{sec:poly-switches}. \end{example} \begin{example} 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-start-mod7.tex}{\texttt{quick-start-mod7.tex}}{lst:quick-start-mod7} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/quick-start7.yaml}[MLB-TCB]{\texttt{quick-start7.yaml}}{lst:quick-start7yaml} \end{cmhtcbraster} Full details of \emph{poly-switches} are covered in \cref{sec:poly-switches}. \end{example} \begin{example} Running \begin{commandshell} latexindent.pl -l quick-start8.yaml quick-start.tex \end{commandshell} gives \cref{lst:quick-start-mod8}; note that the \emph{preamble} has been indented. \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/quick-start-mod8.tex}{\texttt{quick-start-mod8.tex}}{lst:quick-start-mod8} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/quick-start8.yaml}[yaml-TCB]{\texttt{quick-start8.yaml}}{lst:quick-start8yaml} \end{cmhtcbraster} See \cref{subsec:filecontents:preamble}. \end{example} \begin{example} Running \begin{commandshell} latexindent.pl -l quick-start9.yaml quick-start.tex \end{commandshell} gives \cref{lst:quick-start-mod9}. \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/quick-start-mod9.tex}{\texttt{quick-start-mod9.tex}}{lst:quick-start-mod9} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/quick-start9.yaml}[yaml-TCB]{\texttt{quick-start9.yaml}}{lst:quick-start9yaml} \end{cmhtcbraster} See \cref{sec:noadd-indent-rules}. \end{example} \subsection{Required perl modules} If you receive an error message such as that given in \cref{lst:poss-errors}, then you need to install the missing perl modules. \begin{cmhlistings}[style=tcblatex,language=Perl]{Possible error messages}{lst:poss-errors} Can't locate File/HomeDir.pm in @INC (@INC contains: /Library/Perl/5.12/darwin-thread-multi-2level /Library/Perl/5.12 /Network/Library/Perl/5.12/darwin-thread-multi-2level /Network/Library/Perl/5.12 /Library/Perl/Updates/5.12.4/darwin-thread-multi-2level /Library/Perl/Updates/5.12.4 /System/Library/Perl/5.12/darwin-thread-multi-2level /System/Library/Perl/5.12 /System/Library/Perl/Extras/5.12/darwin-thread-multi-2level /System/Library/Perl/Extras/5.12 .) at helloworld.pl line 10. BEGIN failed--compilation aborted at helloworld.pl line 10. \end{cmhlistings} \texttt{latexindent.pl} ships with a script to help with this process; if you run the following script, you should be prompted to install the appropriate modules. \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}. \subsection{About this documentation} As you read through this documentation, you will see many listings; in this version of the documentation, there are a total of \totallstlistings. This may seem a lot, but I deem it necessary in presenting the various different options of \texttt{latexindent.pl} and the associated output that they are capable of producing. The different listings are presented using different styles: \begin{widepage} \begin{minipage}{.4\linewidth} \cmhlistingsfromfile{demonstrations/demo-tex.tex}{\texttt{demo-tex.tex}}{lst:demo-tex} \end{minipage}% \hfill \begin{minipage}{.4\linewidth} This type of listing is a \texttt{.tex} file. \end{minipage}% \begin{minipage}{.4\linewidth} \cmhlistingsfromfile[style=fileExtensionPreference]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{fileExtensionPreference}}{lst:fileExtensionPreference-demo} \end{minipage}% \hfill \begin{minipage}{.4\linewidth} This type of listing is a \texttt{.yaml} file; when you see line numbers given (as here) it means that the snippet is taken directly from \texttt{defaultSettings.yaml}, discussed in detail in \vref{sec:defuseloc}. \end{minipage}% \begin{minipage}{.6\linewidth} \cmhlistingsfromfile[style=modifylinebreaks]{../defaultSettings.yaml}[MLB-TCB,width=.95\linewidth,before=\centering]{\texttt{modifyLineBreaks}}{lst:modifylinebreaks-demo} \end{minipage}% \hfill \begin{minipage}{.4\linewidth} This type of listing is a \texttt{.yaml} file, but it will only be relevant when the \texttt{-m} switch is active; see \vref{sec:modifylinebreaks} for more details. \end{minipage}% \begin{minipage}{.6\linewidth} \cmhlistingsfromfile[style=replacements]{../defaultSettings.yaml}[replace-TCB,width=.95\linewidth,before=\centering]{\texttt{replacements}}{lst:replacements-demo} \end{minipage}% \hfill \begin{minipage}{.4\linewidth} This type of listing is a \texttt{.yaml} file, but it will only be relevant when the \texttt{-r} switch is active; see \vref{sec:replacements} for more details. \end{minipage}% \end{widepage} % \begin{latexonly} You will occasionally see dates shown in the margin (for example, next to this paragraph!) \announce{2017-06-25}{announce} which detail the date of the version in which the feature was implemented; the `N' stands for `new as of the date shown' and `U' stands for `updated as of the date shown'. If you see \stardemo, it means that the feature is either new (N) or updated (U) as of the release of the current version; if you see \stardemo\, attached to a listing, then it means that listing is new (N) or updated (U) as of the current version. If you have not read this document before (and even if you have!), then you can ignore every occurrence of the \stardemo; they are simply there to highlight new and updated features. The new and updated features in this documentation (\gitRel) are on the following pages: \listOfNewFeatures% % \end{latexonly} \subsection{A word about regular expressions} \index{regular expressions!a word about} As you read this documentation, you may encounter the term \emph{regular expressions}. I've tried to write this documentation in such a way so as to allow you to engage with them or not, as you prefer. This documentation is not designed to be a guide to regular expressions, and if you'd like to read about them, I recommend \cite{masteringregexp}. % arara: pdflatex: { files: [latexindent]} \section{Demonstration: before and after} Let's give a demonstration of some before and after code -- after all, you probably won't want to try the script if you don't much like the results. You might also like to watch the video demonstration I made on youtube \cite{cmh:videodemo} As you look at \crefrange{lst:filecontentsbefore}{lst:pstricksafter}, remember that \texttt{latexindent.pl} is just following its rules, and there is nothing particular about these code snippets. All of the rules can be modified so that you can personalise your indentation scheme. In each of the samples given in \crefrange{lst:filecontentsbefore}{lst:pstricksafter} the `before' case is a `worst case scenario' with no effort to make indentation. The `after' result would be the same, regardless of the leading white space at the beginning of each line which is stripped by \texttt{latexindent.pl} (unless a \texttt{verbatim}-like environment or \texttt{noIndentBlock} is specified -- more on this in \cref{sec:defuseloc}). \begin{widepage} \centering \begin{minipage}{.45\linewidth} \cmhlistingsfromfile{demonstrations/filecontents1.tex}{\texttt{filecontents1.tex}}{lst:filecontentsbefore} \end{minipage}\hfill \begin{minipage}{.45\linewidth} \cmhlistingsfromfile{demonstrations/filecontents1-default.tex}{\texttt{filecontents1.tex} default output}{lst:filecontentsafter} \end{minipage}% \begin{minipage}{.45\linewidth} \cmhlistingsfromfile{demonstrations/tikzset.tex}{\texttt{tikzset.tex}}{lst:tikzsetbefore} \end{minipage}\hfill \begin{minipage}{.45\linewidth} \cmhlistingsfromfile{demonstrations/tikzset-default.tex}{\texttt{tikzset.tex} default output}{lst:tikzsetafter} \end{minipage}% \begin{minipage}{.45\linewidth} \cmhlistingsfromfile{demonstrations/pstricks.tex}{\texttt{pstricks.tex}}{lst:pstricksbefore} \end{minipage}\hfill \begin{minipage}{.45\linewidth} \cmhlistingsfromfile{demonstrations/pstricks-default.tex}{\texttt{pstricks.tex} default output}{lst:pstricksafter} \end{minipage}% \end{widepage} % arara: pdflatex: { files: [latexindent]} \section{How to use the script}\label{sec:how:to:use} \texttt{latexindent.pl} ships as part of the \TeX Live distribution for Linux and Mac users; \texttt{latexindent.exe} ships as part of the \TeX Live for Windows users. These files are also available from github \cite{latexindent-home} should you wish to use them without a \TeX{} distribution; in this case, you may like to read \vref{sec:updating-path} which details how the \texttt{path} variable can be updated. \index{TeXLive} In what follows, we will always refer to \texttt{latexindent.pl}, but depending on your operating system and preference, you might substitute \texttt{latexindent.exe} or simply \texttt{latexindent}. There are two ways to use \texttt{latexindent.pl}: from the command line, and using \texttt{arara}; we discuss these in \cref{sec:commandline} and \cref{sec:arara} respectively. We will discuss how to change the settings and behaviour of the script in \vref{sec:defuseloc}. \subsection{Requirements} \subsubsection{Perl users} Perl users will need a few standard Perl modules -- see \vref{sec:requiredmodules} for details; \announce{2018-01-13}{perl module installer helper script} in particular, note that a module installer helper script is shipped with \texttt{latexindent.pl}.% \subsubsection{Windows users without perl}\label{subsubsec:latexindent:exe} \texttt{latexindent.pl} ships with \texttt{latexindent.exe} for Windows users, so that you can use the script with or without a Perl distribution. \texttt{latexindent.exe} is available from \cite{latexindent-home}. MiKTeX users on Windows may like to see \cite{miktex-guide} for details of how to use \texttt{latexindent.exe} without a Perl installation. \index{MiKTeX} \index{latexindent.exe} \index{Windows} \subsubsection{Ubuntu Linux users without perl} \texttt{latexindent.pl} ships with \texttt{latexindent-linux} for Ubuntu Linux users, so that you can use the script with or without a Perl distribution. \index{latexindent-linux} \index{linux} \index{TeXLive} \texttt{latexindent-linux} is available from \cite{latexindent-home}. \announce{2022-10-30}{Linux Ubuntu standalone executable} \subsubsection{macOS users without perl} \texttt{latexindent.pl} ships with \texttt{latexindent-macos} for macOS users, so that you can use the script with or without a Perl distribution. \index{latexindent-macos} \index{macOS} \index{TeXLive} \texttt{latexindent-macOS} is available from \cite{latexindent-home}. \announce{2022-10-30}{macOS standalone executable} \subsubsection{conda users} Users of \texttt{conda} should see the details given in \cref{sec:app:conda}. \index{conda} \subsubsection{docker users} Users of \texttt{docker} should see the details given in \cref{sec:app:docker}. \index{docker} \subsection{From the command line}\label{sec:commandline} \texttt{latexindent.pl} has a number of different switches/flags/options, which can be combined in any way that you like, either in short or long form as detailed below. \texttt{latexindent.pl} produces a \texttt{.log} file, \texttt{indent.log}, every time it is run; the name of the log file can be customised, but we will refer to the log file as \texttt{indent.log} throughout this document. There is a base of information that is written to \texttt{indent.log}, but other additional information will be written depending on which of the following options are used. When using \texttt{latexindent.pl} in different ways on different systems, the range of characters supported by its switches/flags/options may vary. We discuss these in Section \cref{app:encoding}. \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}. \flagbox{-h, --help} \index{switches!-h, --help definition and details} \begin{commandshell} latexindent.pl -h latexindent.pl --help \end{commandshell} As above this will output a welcome message to the terminal, including the version number and available options. \begin{commandshell} latexindent.pl myfile.tex \end{commandshell} This will operate on \texttt{myfile.tex}, but will simply output to your terminal; \texttt{myfile.tex} will not be changed by \texttt{latexindent.pl} in any way using this command. 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 latexindent.pl myfile.tex --overwrite \end{commandshell} This \emph{will} overwrite \texttt{myfile.tex}, but it will make a copy of \texttt{myfile.tex} first. You can control the name of the extension (default is \texttt{.bak}), and how many different backups are made -- more on this in \cref{sec:defuseloc}, and in particular see \texttt{backupExtension} and \texttt{onlyOneBackUp}. Note that if \texttt{latexindent.pl} can not create the backup, then it will exit without touching your original file; an error message will be given asking you to check the permissions of the backup file. \flagbox{-wd, --overwriteIfDifferent} \index{switches!-wd, --overwriteIfDifferent definition and details} \index{backup files!overwriteIfDifferent switch, -wd} \announce{2022-03-25}{overwriteIfDifferent switch} \begin{commandshell} latexindent.pl -wd myfile.tex latexindent.pl --overwriteIfDifferent myfile.tex latexindent.pl myfile.tex --overwriteIfDifferent \end{commandshell} This \emph{will} overwrite \texttt{myfile.tex} but only \emph{if the indented text is different from the original}. If the indented text is \emph{not} different from the original, then \texttt{myfile.tex} will \emph{not} be overwritten. All other details from the \texttt{-w} switch are relevant here. If you call \texttt{latexindent.pl} with both the \texttt{-wd} and the \texttt{-w} switch, then the \texttt{-w} switch will be deactivated and the \texttt{-wd} switch takes priority. \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 latexindent.pl --outputfile=output.tex myfile.tex latexindent.pl --outputfile output.tex myfile.tex \end{commandshell} This will indent \texttt{myfile.tex} and output it to \texttt{output.tex}, overwriting it (\texttt{output.tex}) if it already exists\footnote{Users of version 2.* should note the subtle change in syntax}. Note that if \texttt{latexindent.pl} is called with both the \texttt{-w} and \texttt{-o} switches, then \texttt{-w} will be ignored and \texttt{-o} will take priority (this seems safer than the other way round). The same is true for the \texttt{-wd} switch, and the \texttt{-o} switch takes priority over it. Note that using \texttt{-o} as above is equivalent to using \begin{commandshell} latexindent.pl myfile.tex > output.tex \end{commandshell} You can call the \texttt{-o} switch with the name of the output file \emph{without} an extension; in \announce{2017-06-25}{upgrade to -o switch} this case, \texttt{latexindent.pl} will use the extension from the original file. For example, the following two calls to \texttt{latexindent.pl} are equivalent:% \begin{commandshell} latexindent.pl myfile.tex -o=output latexindent.pl myfile.tex -o=output.tex \end{commandshell} You can call the \texttt{-o} switch using a \texttt{+} symbol at the beginning; this will \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 \end{commandshell} You can call the \texttt{-o} switch using a \texttt{++} symbol at the end of the name \announce{2017-06-25}{++ in o switch} of your output file; this tells \texttt{latexindent.pl} to search successively for the name of your output file concatenated with $0, 1, \ldots$ while the name of the output file exists. For example,% \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} 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 \end{commandshell} Silent mode: no output will be given to the terminal. \flagbox{-t, --trace} \index{switches!-t, --trace definition and details} \begin{commandshell} latexindent.pl -t myfile.tex latexindent.pl myfile.tex -t \end{commandshell} \label{page:traceswitch} Tracing mode: verbose output will be given to \texttt{indent.log}. This is useful if \texttt{latexindent.pl} has made a mistake and you're trying to find out where and why. You might also be interested in learning about \texttt{latexindent.pl}'s thought process -- if so, this switch is for you, although it should be noted that, especially for large files, this does affect performance of the script. \flagbox{-tt, --ttrace} \index{switches!-tt, --ttrace definition and details} \begin{commandshell} latexindent.pl -tt myfile.tex latexindent.pl myfile.tex -tt \end{commandshell} \emph{More detailed} tracing mode: this option gives more details to \texttt{indent.log} than the standard \texttt{trace} option (note that, even more so than with \texttt{-t}, especially for large files, performance of the script will be affected). \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 latexindent.pl -l myyaml.yaml myfile.tex latexindent.pl -l first.yaml,second.yaml,third.yaml myfile.tex latexindent.pl -l=first.yaml,second.yaml,third.yaml myfile.tex latexindent.pl myfile.tex -l=first.yaml,second.yaml,third.yaml \end{commandshell} \label{page:localswitch} \texttt{latexindent.pl} will always load \texttt{defaultSettings.yaml} (rhymes with camel) and if it is called with the \texttt{-l} switch and it finds \texttt{localSettings.yaml} in the same directory as \texttt{myfile.tex}, then, if not found, it looks for \texttt{localSettings.yaml} (and friends, see \vref{sec:localsettings}) in the current working directory, then these% \announce{2021-03-14}*{-l switch: localSettings and friends} settings will be added to the indentation scheme. Information will be given in \texttt{indent.log} on the success or failure of loading \texttt{localSettings.yaml}. The \texttt{-l} flag can take an \emph{optional} parameter which details the name (or names separated by commas) of a YAML file(s) that resides in the same directory as \texttt{myfile.tex}; you can use this option if you would like to load a settings file in the current working directory that is \emph{not} called \texttt{localSettings.yaml}. \announce{2017-08-21}*{-l switch absolute paths} In fact, you can specify both \emph{relative} and \emph{absolute paths} for your YAML files; for example% \begin{commandshell} latexindent.pl -l=../../myyaml.yaml myfile.tex latexindent.pl -l=/home/cmhughes/Desktop/myyaml.yaml myfile.tex latexindent.pl -l=C:\Users\cmhughes\Desktop\myyaml.yaml myfile.tex \end{commandshell} You will find a lot of other explicit demonstrations of how to use the \texttt{-l} switch throughout this documentation, You 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. 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:' '" latexindent.pl myfile.tex -y="indentRules: one: '\t\t\t\t'" 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. Note, in particular, that multiple settings can be specified by separating them via commas. There is a further option to use a \texttt{;} to separate fields, which is demonstrated in \vref{sec:yamlswitch}. Any settings specified via this switch will be loaded \emph{after} any specified using the \texttt{-l} switch. This is discussed further in \vref{sec:loadorder}. \flagbox{-d, --onlydefault} \index{switches!-d, --onlydefault definition and details} \begin{commandshell} latexindent.pl -d myfile.tex \end{commandshell} Only \texttt{defaultSettings.yaml}: you might like to read \cref{sec:defuseloc} before using this switch. By default, \texttt{latexindent.pl} will always search for \texttt{indentconfig.yaml} or \texttt{.indentconfig.yaml} in your home directory. If you would prefer it not to do so then (instead of deleting or renaming \texttt{indentconfig.yaml} or \texttt{.indentconfig.yaml}) you can simply call the script with the \texttt{-d} switch; note that this will also tell the script to ignore \texttt{localSettings.yaml} even if it has been called with the \texttt{-l} switch; \texttt{latexindent.pl} \announce{2017-08-21}*{updated -d switch} will also ignore any settings specified from the \texttt{-y} switch.% \flagbox{-c, --cruft=<directory>} \index{switches!-c, --cruft definition and details} \begin{commandshell} latexindent.pl -c=/path/to/directory/ myfile.tex \end{commandshell} If you wish to have backup files and \texttt{indent.log} written to a directory other than the current working directory, then you can send these `cruft' files to another directory. Note the use of a trailing forward slash. % this switch was made as a result of http://tex.stackexchange.com/questions/142652/output-latexindent-auxiliary-files-to-a-different-directory If the cruft directory does not exist, \texttt{latexindent.pl} will attempt to create it. \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 latexindent.pl --logfile other.log myfile.tex latexindent.pl myfile.tex -g other.log \end{commandshell} By default, \texttt{latexindent.pl} reports information to \texttt{indent.log}, but if you wish to change the name of this file, simply call the script with your chosen name after the \texttt{-g} switch as demonstrated above. \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} \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.% \flagbox{-m, --modifylinebreaks} \index{switches!-m, --modifylinebreaks definition and details} \begin{commandshell} latexindent.pl -m myfile.tex latexindent.pl -modifylinebreaks myfile.tex \end{commandshell} One of the most exciting developments in Version~3.0 is the ability to modify line breaks; for full details see \vref{sec:modifylinebreaks} \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 have content in \texttt{myfile.tex}, then the above command will output the results of operating upon \texttt{myfile.tex}. If you wish to use this feature with your own local settings, via the \texttt{-l} switch, then you should finish your call to \texttt{latexindent.pl} with a \texttt{-} sign: \begin{commandshell} cat myfile.tex | latexindent.pl -l=mysettings.yaml - \end{commandshell} 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} Once you have finished typing your input, you can press \begin{itemize} \item \texttt{CTRL+D} on Linux \item \texttt{CTRL+Z} followed by \texttt{ENTER} on Windows \end{itemize} to signify that your input has finished. 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, replacementrespectverb switch}% \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 in \vref{sec:replacements}.% \flagbox{-rr, --onlyreplacement} \index{switches!-rr, --onlyreplacement definition and details} \begin{commandshell} latexindent.pl -rr myfile.tex latexindent.pl -onlyreplacement myfile.tex \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 examples are given in \vref{sec:replacements}.% \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.% The \texttt{exit} code \index{exit code} of \texttt{latexindent.pl} is 0 by default. If you use the \texttt{-k} switch then \begin{itemize} \item if the text after indentation matches that given in the original file, then the exit code is 0; \item if the text after indentation does \emph{not} match that given in the original file, then the exit code is 1. \end{itemize} The value of the exit code may be important to those wishing to, for example, check the status of the indentation in continuous integration tools such as GitHub Actions. Full details of the exit codes of \texttt{latexindent.pl} are given in \cref{tab:exit-codes}. A simple \texttt{diff} will be given in \texttt{indent.log}. \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}. \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}. Complete demonstrations are given in \cref{sec:line-switch}. \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 work for your language. Further details are given in \cref{subsec:the-GCString}. \subsection{From arara}\label{sec:arara} Using \texttt{latexindent.pl} from the command line is fine for some folks, but others may find it easier to use from \texttt{arara}; you can find the arara rule for \texttt{latexindent.pl} and its associated documentation at \cite{paulo}. \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] \caption{Exit codes for \texttt{latexindent.pl}} \label{tab:exit-codes} \begin{tabular}{ccl} \toprule exit code & indentation & status \\ \midrule 0 & \faCheck & success; if \texttt{-k} or \texttt{-kv} active, indented text matches original \\ 0 & \faClose & success; if \texttt{-version}, \texttt{-vversion} or \texttt{-help}, no indentation performed \\ 1 & \faCheck & success, and \texttt{-k} or \texttt{-kv} active; indented text \emph{different} from original \\ \midrule 2 & \faClose & failure, \texttt{defaultSettings.yaml} could not be read \\ 3 & \faClose & failure, myfile.tex not found \\ 4 & \faClose & failure, myfile.tex exists but cannot be read \\ 5 & \faClose & failure, \texttt{-w} active, and back-up file cannot be written \\ 6 & \faClose & failure, \texttt{-c} active, and cruft directory could not be created \\ \bottomrule \end{tabular} \end{table} % arara: pdflatex: { files: [latexindent]} \section{indentconfig.yaml, local settings and the -y switch }\label{sec:indentconfig} The behaviour of \texttt{latexindent.pl} is controlled from the settings specified in any of the YAML files that you tell it to load. By default, \texttt{latexindent.pl} will only load \texttt{defaultSettings.yaml}, but there are a few ways that you can tell it to load your own settings files. We focus our discussion on \texttt{indentconfig.yaml}, but there are other options which are detailed in \cref{app:indentconfig:options}. \announce{2023-01-01}{indentconfig location options} \subsection{indentconfig.yaml and .indentconfig.yaml}\label{subsec:indentconfig} \texttt{latexindent.pl} will always check your home directory for \texttt{indentconfig.yaml} and \texttt{.indentconfig.yaml} (unless it is called with the \texttt{-d} switch), which is a plain text file you can create that contains the \emph{absolute} paths for any settings files that you wish \texttt{latexindent.pl} to load. There is no difference between \texttt{indentconfig.yaml} and \texttt{.indentconfig.yaml}, other than the fact that \texttt{.indentconfig.yaml} is a `hidden' file; thank you to \cite{jacobo-diaz-hidden-config} for providing this feature. In what follows, we will use \texttt{indentconfig.yaml}, but it is understood that this could equally represent \texttt{.indentconfig.yaml}. If you have both files in existence then \texttt{indentconfig.yaml} takes priority. For Mac and Linux users, their home directory is \texttt{~/username} while Windows (Vista onwards) is \lstinline!C:\Users\username!\footnote{If you're not sure where to put \texttt{indentconfig.yaml}, don't worry \texttt{latexindent.pl} will tell you in the log file exactly where to put it assuming it doesn't exist already.} \Cref{lst:indentconfig} shows a sample \texttt{indentconfig.yaml} file. \cmhlistingsfromfile[style=yaml-LST]{demonstrations/indent-config.yaml}[yaml-TCB]{\texttt{indentconfig.yaml} (sample)}{lst:indentconfig} Note that the \texttt{.yaml} files you specify in \texttt{indentconfig.yaml} will be loaded in the order in which you write them. Each file doesn't have to have every switch from \texttt{defaultSettings.yaml}; in fact, I recommend that you only keep the switches that you want to \emph{change} in these settings files. To get started with your own settings file, you might like to save a copy of \texttt{defaultSettings.yaml} in another directory and call it, for example, \texttt{mysettings.yaml}. Once you have added the path to \texttt{indentconfig.yaml} you can change the switches and add more code-block names to it as you see fit -- have a look at \cref{lst:mysettings} for an example that uses four tabs for the default indent, adds the \texttt{tabbing} environment/command to the list of environments that contains alignment delimiters; you might also like to refer to the many YAML files detailed throughout the rest of this documentation. \index{indentation!defaultIndent using YAML file} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/tabbing.yaml}[yaml-TCB]{\texttt{mysettings.yaml} (example)}{lst:mysettings} You can make sure that your settings are loaded by checking \texttt{indent.log} for details -- if you have specified a path that \texttt{latexindent.pl} doesn't recognise then you'll get a warning, otherwise you'll get confirmation that \texttt{latexindent.pl} has read your settings file \footnote{Windows users may find that they have to end \texttt{.yaml} files with a blank line}. \index{warning!editing YAML files} \begin{warning} When editing \texttt{.yaml} files it is \emph{extremely} important to remember how sensitive they are to spaces. I highly recommend copying and pasting from \texttt{defaultSettings.yaml} when you create your first \texttt{whatevernameyoulike.yaml} file. If \texttt{latexindent.pl} can not read your \texttt{.yaml} file it will tell you so in \texttt{indent.log}. \end{warning} As of \announce*{2024-04-28}{paths within local YAML settings} you can specify the \texttt{paths} field from \cref{lst:indentconfig} within any of your \texttt{latexindent.yaml} and friends settings files. This can lead to creative nesting of configuration files; a demonstration is given in \vref{sec:appendix:paths}. \subsection{localSettings.yaml and friends}\label{sec:localsettings} The \texttt{-l} switch tells \texttt{latexindent.pl} to look for \texttt{localSettings.yaml} and/or friends in the \emph{same directory} as \texttt{myfile.tex}. For% \announce{2021-03-14}*{-l switch: localSettings and friends} example, if you use the following command \index{switches!-l demonstration} \begin{commandshell} latexindent.pl -l myfile.tex \end{commandshell} then \texttt{latexindent.pl} will search for and then, assuming they exist, load each of the following files in the following order: \begin{enumerate} \item localSettings.yaml \item latexindent.yaml \item .localSettings.yaml \item .latexindent.yaml \end{enumerate} These files will be assumed to be in the same directory as \texttt{myfile.tex}, or otherwise in the current working directory. You do not need to have all of the above files, usually just one will be sufficient. In what follows, whenever we refer to \texttt{localSettings.yaml} it is assumed that it can mean any of the four named options listed above. If you'd prefer to name your \texttt{localSettings.yaml} file something different, (say, \texttt{mysettings.yaml} as in \cref{lst:mysettings}) then you can call \texttt{latexindent.pl} using, for example, \begin{commandshell} latexindent.pl -l=mysettings.yaml myfile.tex \end{commandshell} Any settings file(s) specified using the \texttt{-l} switch will be read \emph{after} \texttt{defaultSettings.yaml} and, assuming they exist, any user setting files specified in \texttt{indentconfig.yaml}. Your settings file can contain any switches that you'd like to change; a sample is shown in \cref{lst:localSettings}, and you'll find plenty of further examples throughout this manual. \index{verbatim!verbatimEnvironments demonstration (-l switch)} \begin{yaml}{\texttt{localSettings.yaml} (example)}{lst:localSettings} # verbatim environments - environments specified # here will not be changed at all! verbatimEnvironments: cmhenvironment: 0 myenv: 1 \end{yaml} You can make sure that your settings file has been loaded by checking \texttt{indent.log} for details; if it can not be read then you receive a warning, otherwise you'll get confirmation that \texttt{latexindent.pl} has read your settings file. \subsection{The -y|yaml switch}\label{sec:yamlswitch} You% \announce{2017-08-21}{demonstration of the -y switch} may use the \texttt{-y} switch to load your settings; for example, if you wished to specify the settings from \cref{lst:localSettings} using the \texttt{-y} switch, then you could use the following command: \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. If you wish to specify any regex-based settings using the \texttt{-y} switch, \index{regular expressions!using -y switch} it is important not to use quotes surrounding the regex; for example, with reference to the `one sentence per line' feature (\vref{sec:onesentenceperline}) and the listings within \vref{lst:sentencesEndWith}, the following settings give the option to have sentences end with a semicolon \index{switches!-y demonstration} \begin{commandshell} latexindent.pl -m --yaml='modifyLineBreaks:oneSentencePerLine:sentencesEndWith:other:\;' \end{commandshell} Note that the \texttt{paths} settings (see \vref{sec:appendix:paths}) can \emph{not} be specified using the \texttt{-y} switch. \subsection{Settings load order}\label{sec:loadorder} \texttt{latexindent.pl} loads the settings files in the following order: \index{switches!-l in relation to other settings} \begin{enumerate} \item \texttt{defaultSettings.yaml} is always loaded, and can not be renamed; \item \texttt{anyUserSettings.yaml} and any other arbitrarily-named files specified in \texttt{indentconfig.yaml}; \item \texttt{localSettings.yaml} but only if found in the same directory as \texttt{myfile.tex} and called with \texttt{-l} switch; this file can be renamed, provided that the call to \texttt{latexindent.pl} is adjusted accordingly (see \cref{sec:localsettings}). You may specify both relative and absolute% \announce{2017-08-21}*{-l absolute paths} paths to other YAML files using the \texttt{-l} switch, separating multiple files using commas; \item any settings \announce{2017-08-21}{-y switch load order} specified in the \texttt{-y} switch.% \end{enumerate} A visual representation of this is given in \cref{fig:loadorder}. \begin{figure}[!htb] \centering \input{figure-schematic} \caption{Schematic of the load order described in \cref{sec:loadorder}; solid lines represent mandatory files, dotted lines represent optional files. \texttt{indentconfig.yaml} can contain as many files as you like. The files will be loaded in order; if you specify settings for the same field in more than one file, the most recent takes priority. } \label{fig:loadorder} \end{figure} % arara: pdflatex: { files: [latexindent]} \section{defaultSettings.yaml}\label{sec:defuseloc} \texttt{latexindent.pl} loads its settings from \texttt{defaultSettings.yaml}. The idea is to separate the behaviour of the script from the internal working -- this is very similar to the way that we separate content from form when writing our documents in \LaTeX. If you look in \texttt{defaultSettings.yaml} you'll find the switches that govern the behaviour of \texttt{latexindent.pl}. If you're not sure where \texttt{defaultSettings.yaml} resides on your computer, don't worry as \texttt{indent.log} will tell you where to find it. \texttt{defaultSettings.yaml} is commented, but here is a description of what each switch is designed to do. The default value is given in each case; whenever you see \emph{integer} in \emph{this} section, assume that it must be greater than or equal to \texttt{0} unless otherwise stated. For most of the settings in \texttt{defaultSettings.yaml} that are specified as integers, then we understand \texttt{0} to represent `off' and \texttt{1} to represent `on'. For fields that allow values other than \texttt{0} or \texttt{1}, it is hoped that the specific context and associated commentary should make it clear which values are allowed. \yamltitle{fileExtensionPreference}*{fields} \texttt{latexindent.pl} can be called to 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. \cmhlistingsfromfile[style=fileExtensionPreference]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{fileExtensionPreference}}{lst:fileExtensionPreference} Calling \texttt{latexindent.pl myfile} with the (default) settings specified in \cref{lst:fileExtensionPreference} means that the script will first look for \texttt{myfile.tex}, then \texttt{myfile.sty}, \texttt{myfile.cls}, and finally \texttt{myfile.bib} in order\footnote{Throughout this manual, listings shown with line numbers represent code taken directly from \texttt{defaultSettings.yaml}.}. \index{backup files!extension settings} \subsection{Backup and log file preferences} \yamltitle{backupExtension}*{extension name} If you call \texttt{latexindent.pl} with the \texttt{-w} switch (to overwrite \texttt{myfile.tex}) then it will create a backup file before doing any indentation; the default extension is \texttt{.bak}, so, for example, \texttt{myfile.bak0} would be created when calling \texttt{latexindent.pl myfile.tex} for the first time. By default, every time you subsequently call \texttt{latexindent.pl} with the \texttt{-w} to act upon \texttt{myfile.tex}, it will create successive back up files: \texttt{myfile.bak1}, \texttt{myfile.bak2}, etc. \yamltitle{onlyOneBackUp}*{integer} \label{page:onlyonebackup} \index{backup files!number of backup files} If you don't want a backup for every time that you call \texttt{latexindent.pl} (so you don't want \texttt{myfile.bak1}, \texttt{myfile.bak2}, etc) and you simply want \texttt{myfile.bak} (or whatever you chose \texttt{backupExtension} to be) then change \texttt{onlyOneBackUp} to \texttt{1}; the default value of \texttt{onlyOneBackUp} is \texttt{0}. \index{backup files!maximum number of backup files} \index{backup files!number of backup files} \yamltitle{maxNumberOfBackUps}*{integer} Some users may only want a finite number of backup files, say at most $3$, in which case, they can change this switch. The smallest value of \texttt{maxNumberOfBackUps} is $0$ which will \emph{not} prevent backup files being made; in this case, the behaviour will be dictated entirely by \texttt{onlyOneBackUp}. The default value of \texttt{maxNumberOfBackUps} is \texttt{0}. \yamltitle{cycleThroughBackUps}*{integer} \index{backup files!cycle through} Some users may wish to cycle through backup files, by deleting the oldest backup file and keeping only the most recent; for example, with \texttt{maxNumberOfBackUps: 4}, and \texttt{cycleThroughBackUps} set to \texttt{1} then the \texttt{copy} procedure given below would be obeyed. \begin{commandshell} copy myfile.bak1 to myfile.bak0 copy myfile.bak2 to myfile.bak1 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} \texttt{latexindent.pl} writes information to \texttt{indent.log}, some of which can be customized by changing \texttt{logFilePreferences}; see \cref{lst:logFilePreferences}. If you load your own user settings (see \vref{sec:indentconfig}) then \texttt{latexindent.pl} will detail them in \texttt{indent.log}; you can choose not to have the details logged by switching \texttt{showEveryYamlRead} to \texttt{0}. Once all of your settings have been loaded, you can see the amalgamated settings in the log file by switching \texttt{showAmalgamatedSettings} to \texttt{1}, if you wish. \cmhlistingsfromfile[style=logFilePreferences,]{../defaultSettings.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{logFilePreferences}}{lst:logFilePreferences} When \announce{2018-01-13}{showDecorationStartCodeBlockTrace feature for log file} either of the \texttt{trace} modes (see \cpageref{page:traceswitch}) are active, you will receive detailed information in \texttt{indent.log}. You can specify character strings to appear before and after the notification of a found code block using, respectively, \texttt{showDecorationStartCodeBlockTrace} and \texttt{showDecorationFinishCodeBlockTrace}. A demonstration is given in \vref{app:logfile-demo}.% The log file will end with the characters given in \texttt{endLogFileWith}, and will report the \texttt{GitHub} address of \texttt{latexindent.pl} to the log file if \texttt{showGitHubInfoFooter} is set to \texttt{1}. Note: \texttt{latexindent.pl} no longer uses the \texttt{log4perl} module to handle the creation of the logfile. \announce{2021-03-14}*{no longer using log4perl}% Some of the options \announce{2021-06-19}*{logFilePreferences updated to include Dumper options} for Perl's \texttt{Dumper} module can be specified in \cref{lst:logFilePreferences}; see \cite{dumper} and \cite{dumperdemo} for more information. These options will mostly be helpful for those calling \texttt{latexindent.pl} with the \texttt{-tt} option described in \cref{sec:commandline}.% \subsection{Verbatim code blocks} \yamltitle{verbatimEnvironments}*{fields} A field that contains a list of environments that you would like left completely alone -- no indentation will be performed on environments that you have specified in this field, see \cref{lst:verbatimEnvironments}. \index{verbatim!environments} \index{verbatim!commands} \begin{cmhtcbraster}[raster column skip=.1\linewidth] \cmhlistingsfromfile[style=verbatimEnvironments]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{verbatimEnvironments}}{lst:verbatimEnvironments} \cmhlistingsfromfile[style=verbatimCommands]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{verbatimCommands}}{lst:verbatimCommands} \end{cmhtcbraster} Note that if you put an environment in \texttt{verbatimEnvironments} and in other fields such as \texttt{lookForAlignDelims} or \texttt{noAdditionalIndent} then \texttt{latexindent.pl} will \emph{always} prioritize \texttt{verbatimEnvironments}. You can, optionally, specify \announce{2021-10-30}{verbatim name feature} the \texttt{verbatim} field using the \texttt{name} field which takes a regular expression as its argument; thank you to \cite{XuehaiPan} for contributing this feature. \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. \begin{cmhtcbraster}[raster column skip=.1\linewidth] \cmhlistingsfromfile[style=yaml-LST]{demonstrations/nameAsRegex1.yaml}[yaml-TCB]{\texttt{nameAsRegex1.yaml}}{lst:nameAsRegex1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/nameAsRegex2.yaml}[yaml-TCB]{\texttt{nameAsRegex2.yaml}}{lst:nameAsRegex2} \end{cmhtcbraster} With reference to \cref{lst:nameAsRegex2}: \begin{itemize} \item the \texttt{name} field as specified here means \emph{any word followed by the word code, optionally followed by *}; \item we have used \texttt{nameAsRegex} to identify this field, but you can use any description you like; \item the \texttt{lookForThis} field is optional, and can take the values 0 (off) or 1 (on); by default, it is assumed to be 1 (on). \end{itemize} \end{example} \yamltitle{verbatimCommands}*{fields} A field that contains a list of commands that are verbatim commands, for example \lstinline|\lstinline|; any commands populated in this field are protected from line breaking routines (only relevant if the \texttt{-m} is active, see \vref{sec:modifylinebreaks}). With reference to \cref{lst:verbatimCommands}, by default \texttt{latexindent.pl} looks for \lstinline|\verb| immediately followed by another character, and then it takes the body as anything up to the next occurrence of the character; this means that, for example, \lstinline|\verb!x+3!| is treated as a \texttt{verbatimCommands}. You can, optionally, specify \announce{2021-10-30}{verbatimCommands name feature} the \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. \begin{cmhtcbraster}[raster column skip=.1\linewidth] \cmhlistingsfromfile[style=yaml-LST]{demonstrations/nameAsRegex3.yaml}[yaml-TCB]{\texttt{nameAsRegex3.yaml}}{lst:nameAsRegex3} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/nameAsRegex4.yaml}[yaml-TCB]{\texttt{nameAsRegex4.yaml}}{lst:nameAsRegex4} \end{cmhtcbraster} With reference to \cref{lst:nameAsRegex4}: \begin{itemize} \item the \texttt{name} field as specified here means \emph{any word followed by the word inline}; \item we have used \texttt{nameAsRegex} to identify this field, but you can use any description you like; \item the \texttt{lookForThis} field is optional, and can take the values 0 (off) or 1 (on); by default, it is assumed to be 1 (on). \end{itemize} \end{example} \yamltitle{noIndentBlock}*{fields} If you have a block of code that you don't want \texttt{latexindent.pl} to touch (even if \index{verbatim!noIndentBlock} it is \emph{not} a verbatim-like environment) then you can wrap it in an environment from \texttt{noIndentBlock}; you can use any name you like for this, provided you populate it as demonstrate in \cref{lst:noIndentBlock}. \cmhlistingsfromfile[style=noIndentBlock]{../defaultSettings.yaml}[width=.4\linewidth,before=\centering,yaml-TCB]{\texttt{noIndentBlock}}{lst:noIndentBlock} Of course, you don't want to have to specify these as null environments in your code, so you use them with a comment symbol, \lstinline!%!, followed by as many spaces (possibly none) as you like; see \cref{lst:noIndentBlockdemo} for example. \cmhlistingsfromfile{demonstrations/noindentblock.tex}{\texttt{noIndentBlock.tex}}{lst:noIndentBlockdemo} Important note: it is assumed that the \texttt{noindent} block statements specified in this way appear on their own line. \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} The settings given in \cref{lst:noindent1,lst:noindent2} are equivalent: \begin{cmhtcbraster}[raster columns=3, raster left skip=-3.5cm, raster right skip=-2cm, raster column skip=.03\linewidth] \cmhlistingsfromfile[style=yaml-LST]{demonstrations/noindent1.yaml}[yaml-TCB]{\texttt{noindent1.yaml}}{lst:noindent1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/noindent2.yaml}[yaml-TCB]{\texttt{noindent2.yaml}}{lst:noindent2} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/noindent3.yaml}[yaml-TCB]{\texttt{noindent3.yaml}}{lst:noindent3} \end{cmhtcbraster} Upon running the commands \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 \cref{lst:noindent1}. In this context, we interpret \lstinline!.*?! in words as \emph{the fewest number of characters (possibly none) until the `end' field is reached}. The \texttt{lookForThis} field is optional, and can take the values 0 (off) or 1 (on); by default, it is assumed to be 1 (on). \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 \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. \begin{widepage} \begin{cmhtcbraster}[raster column skip=.1\linewidth] \cmhlistingsfromfile[style=yaml-LST]{demonstrations/nameAsRegex5.yaml}[yaml-TCB]{\texttt{nameAsRegex5.yaml}}{lst:nameAsRegex5} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/nameAsRegex6.yaml}[yaml-TCB]{\texttt{nameAsRegex6.yaml}}{lst:nameAsRegex6} \end{cmhtcbraster} \end{widepage} With reference to \cref{lst:nameAsRegex6}: \begin{itemize} \item the \texttt{name} field as specified here means \emph{any word followed by the word noindent, optionally followed by *}; \item we have used \texttt{nameAsRegex} to identify this field, but you can use any description you like; \item the \texttt{lookForThis} field is optional, and can take the values 0 (off) or 1 (on); by default, it is assumed to be 1 (on). \end{itemize} \end{example} \subsection{filecontents and preamble}\label{subsec:filecontents:preamble} \yamltitle{fileContentsEnvironments}*{field} Before \texttt{latexindent.pl} determines the difference between preamble (if any) and the main document, it first searches for any of the environments specified in \texttt{fileContentsEnvironments}, see \cref{lst:fileContentsEnvironments}. The behaviour of \texttt{latexindent.pl} on these environments is determined by their location (preamble or not), and the value \texttt{indentPreamble}, discussed next. \cmhlistingsfromfile[style=fileContentsEnvironments]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{fileContentsEnvironments}}{lst:fileContentsEnvironments} \yamltitle{indentPreamble}{0|1} The preamble of a document can sometimes contain some trickier code for \texttt{latexindent.pl} to operate upon. By default, \texttt{latexindent.pl} won't try to operate on the preamble (as \texttt{indentPreamble} is set to \texttt{0}, by default), but if you'd like \texttt{latexindent.pl} to try then change \texttt{indentPreamble} to \texttt{1}. \yamltitle{lookForPreamble}*{fields} Not all files contain preamble; for example, \texttt{sty}, \texttt{cls} and \texttt{bib} files typically do \emph{not}. Referencing \cref{lst:lookForPreamble}, if you set, for example, \texttt{.tex} to \texttt{0}, then regardless of the setting of the value of \texttt{indentPreamble}, preamble will not be assumed when operating upon \texttt{.tex} files. \cmhlistingsfromfile[style=lookForPreamble]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{lookForPreamble}{lst:lookForPreamble} \yamltitle{preambleCommandsBeforeEnvironments}{0|1} Assuming that \texttt{latexindent.pl} is asked to operate upon the preamble of a document, when this switch is set to \texttt{0} then environment code blocks will be sought first, and then command code blocks. When this switch is set to \texttt{1}, commands will be sought first. The example that first motivated this switch contained the code given in \cref{lst:motivatepreambleCommandsBeforeEnvironments}. \begin{cmhlistings}{Motivating \texttt{preambleCommandsBeforeEnvironments}}{lst:motivatepreambleCommandsBeforeEnvironments} ... preheadhook={\begin{mdframed}[style=myframedstyle]}, postfoothook=\end{mdframed}, ... \end{cmhlistings} \index{indentation!defaultIndent description} \subsection{Indentation and horizontal space}\label{subsec:indentation:and:horizontal:space} \yamltitle{defaultIndent}*{horizontal space} This is the default indentation used in the absence of other details for the code block with which we are working. The default value is \lstinline!\t! which means a tab; we will explore customisation beyond \texttt{defaultIndent} in \vref{sec:noadd-indent-rules}. If you're interested in experimenting with \texttt{latexindent.pl} then you can \emph{remove} all indentation by setting \texttt{defaultIndent: ""}. \yamltitle{removeTrailingWhitespace}*{fields}\label{yaml:removeTrailingWhitespace} Trailing white space can be removed both \emph{before} and \emph{after} processing the document, as detailed in \cref{lst:removeTrailingWhitespace}; each of the fields can take the values \texttt{0} or \texttt{1}. See \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{cmhtcbraster} \cmhlistingsfromfile[style=removeTrailingWhitespace]{../defaultSettings.yaml}[before=\centering,yaml-TCB]{removeTrailingWhitespace}{lst:removeTrailingWhitespace} \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} \texttt{latexindent.pl} will set both \texttt{beforeProcessing} and \texttt{afterProcessing} to the value you specify; see \cref{lst:removeTrailingWhitespace-alt}.% \subsection{Aligning at delimiters}\label{subsec:align-at-delimiters} \yamltitle{lookForAlignDelims}*{fields} This contains a list of code blocks that are operated upon in a special way by \texttt{latexindent.pl} (see \cref{lst:aligndelims:basic}). In fact, the fields in \texttt{lookForAlignDelims} can actually take two different forms: the \emph{basic} version is shown in \cref{lst:aligndelims:basic} and the \emph{advanced} version in \cref{lst:aligndelims:advanced}; we will discuss each in turn. \index{delimiters!advanced settings of lookForAlignDelims} \begin{yaml}[numbers=none]{\texttt{lookForAlignDelims} (basic)}[width=.8\linewidth,before=\centering]{lst:aligndelims:basic} lookForAlignDelims: tabular: 1 tabularx: 1 longtable: 1 array: 1 matrix: 1 ... \end{yaml} Specifying code blocks in this field instructs \texttt{latexindent.pl} to try and align each column by its alignment delimiters. It does have some limitations (discussed further in \cref{sec:knownlimitations}), but in many cases it will produce results such as those in \cref{lst:tabularbefore:basic,lst:tabularafter:basic}; running the command \begin{commandshell} latexindent.pl tabular1.tex \end{commandshell} gives the output given in \cref{lst:tabularafter:basic}. \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/tabular1.tex}{\texttt{tabular1.tex}}{lst:tabularbefore:basic} \cmhlistingsfromfile{demonstrations/tabular1-default.tex}{\texttt{tabular1.tex} default output}{lst:tabularafter:basic} \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 of the environment, you could wrap them in something from \texttt{noIndentBlock} (see \vref{lst:noIndentBlock}). If, for example, you wish to remove the alignment of the \lstinline!\\! within a delimiter-aligned block, then the advanced form of \texttt{lookForAlignDelims} shown in \cref{lst:aligndelims:advanced} is for you. \index{regular expressions!delimiterRegEx} \index{regular expressions!ampersand alignment} \index{delimiters!default settings of lookForAlignDelims} \index{delimiters!ampersand \&} \index{delimiters!advanced settings} \index{delimiters!lookForAlignDelims} \cmhlistingsfromfile[style=lookForAlignDelims]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{lookForAlignDelims} (advanced)}{lst:aligndelims:advanced} Note that you can use a mixture of the basic and advanced form: in \cref{lst:aligndelims:advanced} \texttt{tabular} and \texttt{tabularx} are advanced and \texttt{longtable} is basic. When using the advanced form, each field should receive at least 1 sub-field, and \emph{can} (but does not have to) receive any of the following fields: \begin{itemize} \item \texttt{delims}: binary switch (0 or 1) equivalent to simply specifying, for example, \texttt{tabular: 1} in the basic version shown in \cref{lst:aligndelims:basic}. If \texttt{delims} is set to \texttt{0} then the align at ampersand routine will not be called for this code block (default: 1); \item \texttt{alignDoubleBackSlash}: binary switch (0 or 1) to determine if \lstinline!\\! should be aligned (default: 1); \item \texttt{spacesBeforeDoubleBackSlash}: optionally,% \announce{2018-01-13}*{update to spacesBeforeDoubleBackSlash in ampersand alignment} specifies the number (integer $\geq$ 0) of spaces to be inserted before \lstinline!\\! (default: 1); %\footnote{Previously this only activated if \texttt{alignDoubleBackSlash} was set to \texttt{0}.} \item \announce{2017-06-19}{multiColumnGrouping} \texttt{multiColumnGrouping}: binary switch (0 or 1) that details if \texttt{latexindent.pl} should group columns above and below a \lstinline!\multicolumn! command (default: 0); \item \announce{2017-06-19}{alignRowsWithoutMaxDelims} \texttt{alignRowsWithoutMaxDelims}: binary switch (0 or 1) that details if rows that do not contain the maximum number of delimiters should be formatted so as to have the ampersands aligned (default: 1); \item \announce{2018-01-13}{spacesBeforeAmpersand in ampersand alignment}\texttt{spacesBeforeAmpersand}: optionally specifies the number (integer $\geq$ 0) of spaces to be placed \emph{before} ampersands (default: 1); \item \announce{2018-01-13}{spacesAfterAmpersand in ampersand alignment}\texttt{spacesAfterAmpersand}: optionally specifies the number (integer $\geq$ 0) of spaces to be placed \emph{After} ampersands (default: 1); \item \announce{2018-01-13}{justification of cells in ampersand alignment}\texttt{justification}: optionally specifies the justification of each cell as either \emph{left} or \emph{right} (default: left); \item \announce{2020-03-21}{align final double backslash}{alignFinalDoubleBackSlash} optionally specifies if the \emph{final} double backslash should be used for alignment (default: 0); \item \announce{2020-03-21}{don't measure feature}{dontMeasure} optionally specifies if user-specified cells, rows or the largest entries should \emph{not} be measured (default: 0); \item \announce{2020-03-21}{delimiter RegEx feature}{delimiterRegEx} optionally specifies the pattern matching to be used for the alignment delimiter (default: \lstinline* '(?<!\\)(&)'*); \item \announce{2020-03-21}{delimiter justification}{delimiterJustification} optionally specifies the justification for the alignment delimiters (default: left); note that this feature is only useful if you have delimiters of different lengths in the same column, discussed in \cref{sec:delimiter-reg-ex}; \item \announce{2021-12-13}{lookForChildCodeBlocks feature}{lookForChildCodeBlocks} optionally instructs \texttt{latexindent.pl} to search for child code blocks or not (default: 1), discussed in \cref{sec:lookForChildCodeBlocks}; \item \announce{2023-05-01}{alignContentAfterDoubleBackSlash feature} alignContentAfterDoubleBackSlash optionally instructs \texttt{latexindent.pl} to align content \emph{after} double back slash (default: 0), discussed in \cref{sec:alignContentAfterDoubleBackSlash}; \item \announce{2023-05-01}{spacesAfterDoubleBackSlash feature} spacesAfterDoubleBackSlash optionally specifies the number (integer $\geq$ 0) of spaces to be placed \emph{after} the double back slash \emph{when alignContentAfterDoubleBackSlash is active}; demonstrated in \cref{sec:alignContentAfterDoubleBackSlash}. \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 \texttt{alignFinalDoubleBackSlash} in \cref{lst:tabular4}; the \texttt{dontMeasure} feature will be described in \cref{sec:dontMeasure}, and \texttt{delimiterRegEx} in \cref{sec:delimiter-reg-ex}. \cmhlistingsfromfile{demonstrations/tabular2.tex}{\texttt{tabular2.tex}}{lst:tabular2} \begin{minipage}{.45\textwidth} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/tabular2.yaml}[yaml-TCB]{\texttt{tabular2.yaml}}{lst:tabular2YAML} \end{minipage}% \hfill \begin{minipage}{.48\textwidth} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/tabular3.yaml}[yaml-TCB]{\texttt{tabular3.yaml}}{lst:tabular3YAML} \end{minipage}% \begin{minipage}{.45\textwidth} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/tabular4.yaml}[yaml-TCB]{\texttt{tabular4.yaml}}{lst:tabular4YAML} \end{minipage}% \hfill \begin{minipage}{.48\textwidth} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/tabular5.yaml}[yaml-TCB]{\texttt{tabular5.yaml}}{lst:tabular5YAML} \end{minipage}% \begin{minipage}{.45\textwidth} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/tabular6.yaml}[yaml-TCB]{\texttt{tabular6.yaml}}{lst:tabular6YAML} \end{minipage}% \hfill \begin{minipage}{.48\textwidth} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/tabular7.yaml}[yaml-TCB]{\texttt{tabular7.yaml}}{lst:tabular7YAML} \end{minipage}% \begin{minipage}{.48\textwidth} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/tabular8.yaml}[yaml-TCB]{\texttt{tabular8.yaml}}{lst:tabular8YAML} \end{minipage}% 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 latexindent.pl tabular2.tex -l tabular3.yaml latexindent.pl tabular2.tex -l tabular2.yaml,tabular4.yaml latexindent.pl tabular2.tex -l tabular2.yaml,tabular5.yaml latexindent.pl tabular2.tex -l tabular2.yaml,tabular6.yaml 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}. \begin{widepage} \cmhlistingsfromfile{demonstrations/tabular2-default.tex}{\texttt{tabular2.tex} default output}{lst:tabular2-default} \cmhlistingsfromfile{demonstrations/tabular2-mod2.tex}{\texttt{tabular2.tex} using \cref{lst:tabular2YAML}}{lst:tabular2-mod2} \cmhlistingsfromfile{demonstrations/tabular2-mod3.tex}{\texttt{tabular2.tex} using \cref{lst:tabular3YAML}}{lst:tabular2-mod3} \cmhlistingsfromfile{demonstrations/tabular2-mod4.tex}{\texttt{tabular2.tex} using \cref{lst:tabular2YAML,lst:tabular4YAML}}{lst:tabular2-mod4} \cmhlistingsfromfile{demonstrations/tabular2-mod5.tex}{\texttt{tabular2.tex} using \cref{lst:tabular2YAML,lst:tabular5YAML}}{lst:tabular2-mod5} \cmhlistingsfromfile{demonstrations/tabular2-mod6.tex}{\texttt{tabular2.tex} using \cref{lst:tabular2YAML,lst:tabular6YAML}}{lst:tabular2-mod6} \cmhlistingsfromfile{demonstrations/tabular2-mod7.tex}{\texttt{tabular2.tex} using \cref{lst:tabular2YAML,lst:tabular7YAML}}{lst:tabular2-mod7} \cmhlistingsfromfile{demonstrations/tabular2-mod8.tex}{\texttt{tabular2.tex} using \cref{lst:tabular2YAML,lst:tabular8YAML}}{lst:tabular2-mod8} \end{widepage} Notice in particular: \begin{itemize} \item in both \cref{lst:tabular2-default,lst:tabular2-mod2} all rows have been aligned at the ampersand, even those that do not contain the maximum number of ampersands (3 ampersands, in this case); \item in \cref{lst:tabular2-default} the columns have been aligned at the ampersand; \item in \cref{lst:tabular2-mod2} the \lstinline!\multicolumn! command has grouped the $2$ columns beneath \emph{and} above it, because \texttt{multiColumnGrouping} is set to $1$ in \cref{lst:tabular2YAML}; \item in \cref{lst:tabular2-mod3} rows~3 and~6 have \emph{not} been aligned at the ampersand, because \texttt{alignRowsWithoutMaxDelims} has been to set to $0$ in \cref{lst:tabular3YAML}; however, the \lstinline!\\! \emph{have} still been aligned; \item in \cref{lst:tabular2-mod4} the columns beneath and above the \lstinline!\multicolumn! commands have been grouped (because \texttt{multiColumnGrouping} is set to $1$), and there are at least $4$ spaces \emph{before} each aligned ampersand because \texttt{spacesBeforeAmpersand} is set to $4$; \item in \cref{lst:tabular2-mod5} the columns beneath and above the \lstinline!\multicolumn! commands have been grouped (because \texttt{multiColumnGrouping} is set to $1$), and there are at least $4$ spaces \emph{after} each aligned ampersand because \texttt{spacesAfterAmpersand} is set to $4$; \item in \cref{lst:tabular2-mod6} the \lstinline!\\! have \emph{not} been aligned, because \texttt{alignDoubleBackSlash} is set to \texttt{0}, otherwise the output is the same as \cref{lst:tabular2-mod2}; \item in \cref{lst:tabular2-mod7} the \lstinline!\\! \emph{have} been aligned, and because \texttt{spacesBeforeDoubleBackSlash} is set to \texttt{0}, there are no spaces ahead of them; the output is otherwise the same as \cref{lst:tabular2-mod2}; \item in \cref{lst:tabular2-mod8} the cells have been \emph{right}-justified; note that cells above and below the \lstinline!\multicol! statements have still been group correctly, because of the settings in \cref{lst:tabular2YAML}. \end{itemize} \end{example} \subsubsection{lookForAlignDelims: spacesBeforeAmpersand} The \texttt{spacesBeforeAmpersand} \announce{2021-06-19}*{spacesBeforeAmpersand leading blank column upgrade} can be specified in a few different ways. The \emph{basic} form is demonstrated in \cref{lst:tabular4YAML}, but we can customise the behaviour further by specifying if we would like this value to change if it encounters a \emph{leading blank 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} \cmhlistingsfromfile{demonstrations/aligned1.tex}{\texttt{aligned1.tex}}{lst:aligned1} \cmhlistingsfromfile{demonstrations/aligned1-default.tex}{\texttt{aligned1-default.tex}}{lst:aligned1-default} \end{cmhtcbraster} The settings in \crefrange{lst:sba1}{lst:sba4} are all equivlanent; we have used the not-yet discussed \texttt{noAdditionalIndent} field (see \vref{sec:noadd-indent-rules}) which will assist in the demonstration in what follows. \begin{cmhtcbraster}[raster columns=2, ] \cmhlistingsfromfile[style=yaml-LST]{demonstrations/sba1.yaml}[yaml-TCB]{\texttt{sba1.yaml}}{lst:sba1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/sba2.yaml}[yaml-TCB]{\texttt{sba2.yaml}}{lst:sba2} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/sba3.yaml}[yaml-TCB]{\texttt{sba3.yaml}}{lst:sba3} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/sba4.yaml}[yaml-TCB]{\texttt{sba4.yaml}}{lst:sba4} \end{cmhtcbraster} Upon running the following commands \begin{commandshell} latexindent.pl aligned1.tex -l sba1.yaml latexindent.pl aligned1.tex -l sba2.yaml 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. \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/aligned1-mod1.tex}{\texttt{aligned1-mod1.tex}}{lst:aligned1-mod1} \end{cmhtcbraster} We note in particular: \begin{itemize} \item \cref{lst:sba1} demonstrates the \emph{basic} form for \texttt{lookForAlignDelims}; in this case, the default values are specified as in \vref{lst:aligndelims:advanced}; \item \cref{lst:sba2} demonstrates the \emph{advanced} form for \texttt{lookForAlignDelims} and specified \texttt{spacesBeforeAmpersand}. The default value is \texttt{1}; \item \cref{lst:sba3} demonstrates the new \emph{advanced} way to specify \texttt{spacesBeforeAmpersand}, and for us to set the \texttt{default} value that sets the number of spaces before ampersands which are \emph{not} in leading blank columns. The default value is \texttt{1}. We note that \texttt{leadingBlankColumn} has not been specified in \cref{lst:sba3}, and it will inherit the value from \texttt{default}; \item \cref{lst:sba4} demonstrates spaces to be used before amperands for \emph{leading blank columns}. We note that \emph{default} has not been specified, and it will be set to \texttt{1} by 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. \begin{cmhtcbraster} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/sba5.yaml}[yaml-TCB]{\texttt{sba5.yaml}}{lst:sba5} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/sba6.yaml}[yaml-TCB]{\texttt{sba6.yaml}}{lst:sba6} \end{cmhtcbraster} Upon running \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}. We can demonstrated this feature further using the settings in \cref{lst:sba7} which give the output in \cref{lst:aligned1-mod7}. \begin{cmhtcbraster}[raster columns=3, raster left skip=-3.75cm, raster right skip=-2cm,] \cmhlistingsfromfile{demonstrations/aligned1-mod5.tex}{\texttt{aligned1-mod5.tex}}{lst:aligned1-mod5} \cmhlistingsfromfile{demonstrations/aligned1-mod7.tex}{\texttt{aligned1.tex} using \cref{lst:sba7}}{lst:aligned1-mod7} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/sba7.yaml}[yaml-TCB]{\texttt{sba7.yaml}}{lst:sba7} \end{cmhtcbraster} \end{example} \subsubsection{lookForAlignDelims: alignFinalDoubleBackSlash} 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}. \begin{cmhtcbraster}[raster columns=3, raster left skip=-3.75cm, raster right skip=-2cm,] \cmhlistingsfromfile{demonstrations/tabular4.tex}{\texttt{tabular4.tex}}{lst:tabular4} \cmhlistingsfromfile{demonstrations/tabular4-default.tex}{\texttt{tabular4-default.tex}}{lst:tabular4-default} \cmhlistingsfromfile{demonstrations/tabular4-FDBS.tex}{\texttt{tabular4-FDBS.tex}}{lst:tabular4-FDBS} \end{cmhtcbraster} We note that in: \begin{itemize} \item \cref{lst:tabular4-default}, by default, the \emph{first} set of double back slashes in the first row of the \texttt{tabular} environment have been used for alignment; \item \cref{lst:tabular4-FDBS}, the \emph{final} set of double backslashes in the first row have been used, because we specified \texttt{alignFinalDoubleBackSlash} as 1. \end{itemize} \end{example} As of Version 3.0, the alignment routine works on mandatory and optional arguments within commands, and also within `special' code blocks (see \texttt{specialBeginEnd} on \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. \begin{cmhtcbraster} \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}!, then you can use the mark up illustrated in \cref{lst:alignmentmarkup}; the default output is shown in \cref{lst:alignmentmarkup-default}. Note that the \lstinline!%*! must be next to each other, but that there can be any number of spaces (possibly none) between the \lstinline!*! and \lstinline!\begin{tabular}!; note also that you may use any environment name that you have specified in \texttt{lookForAlignDelims}. \begin{cmhtcbraster}[raster left skip=-1.5cm,] \cmhlistingsfromfile{demonstrations/align-block.tex}{\texttt{align-block.tex}}{lst:alignmentmarkup} \cmhlistingsfromfile{demonstrations/align-block-default.tex}{\texttt{align-block.tex} default output}{lst:alignmentmarkup-default} \end{cmhtcbraster} With reference to \vref{tab:code-blocks} and the, yet undiscussed, fields of \texttt{noAdditionalIndent} and \texttt{indentRules} (see \vref{sec:noadd-indent-rules}), these comment-marked blocks are considered \texttt{environments}. \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. \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} \end{cmhtcbraster} 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} \cmhlistingsfromfile{demonstrations/tabular-DM-mod1.tex}{\texttt{tabular-DM.tex} using \cref{lst:dontMeasure1}}{lst:tabular-DM-mod1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/dontMeasure1.yaml}[yaml-TCB]{\texttt{dontMeasure1.yaml}}{lst:dontMeasure1} \end{cmhtcbraster} We note that the \emph{largest} column entries have not contributed to the measuring 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} \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/tabular-DM-mod2.tex}{\texttt{tabular-DM.tex} using \cref{lst:dontMeasure2} or \cref{lst:dontMeasure3}}{lst:tabular-DM-mod2} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/dontMeasure2.yaml}[yaml-TCB]{\texttt{dontMeasure2.yaml}}{lst:dontMeasure2} \end{cmhtcbraster} We note that in \cref{lst:dontMeasure2} we have specified entries not to be measured, one entry per line. \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, raster left skip=-3.5cm, raster right skip=-2cm, raster column skip=.03\linewidth] \cmhlistingsfromfile{demonstrations/tabular-DM-mod3.tex}{\texttt{tabular-DM.tex} using \cref{lst:dontMeasure3} or \cref{lst:dontMeasure3}}{lst:tabular-DM-mod3} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/dontMeasure3.yaml}[yaml-TCB]{\texttt{dontMeasure3.yaml}}{lst:dontMeasure3} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/dontMeasure4.yaml}[yaml-TCB]{\texttt{dontMeasure4.yaml}}{lst:dontMeasure4} \end{cmhtcbraster} We note that in: \begin{itemize} \item \cref{lst:dontMeasure3} we have specified entries not to be measured, each one has a \emph{string} in the \texttt{this} field, together with an optional specification of \texttt{applyTo} as \texttt{cell}; \item \cref{lst:dontMeasure4} we have specified entries not to be measured as a \emph{regular expression} using the \texttt{regex} field, together with an optional specification of \texttt{applyTo} as \texttt{cell} field, together with an optional specification of \texttt{applyTo} as \texttt{cell}. \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[style=yaml-LST]{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} \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/tabular-DM-mod6.tex}{\texttt{tabular-DM.tex} using \cref{lst:dontMeasure6}}{lst:tabular-DM-mod6} \cmhlistingsfromfile[style=yaml-LST]{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} The delimiter alignment \announce{2020-03-21}{delimiterRegEx feature} will, by default, align code blocks at the ampersand character. The behaviour is controlled by the \texttt{delimiterRegEx} field within \texttt{lookForAlignDelims}; the default value is \lstinline*'(?<!\\)(&)'*, which can be read as: \emph{an ampersand, as long as it is not immediately preceded by a backslash}. \index{warning!capturing parenthesis for lookForAlignDelims} \index{capturing parenthesis (regex)} \index{regular expressions!capturing parenthesis} \index{delimiters!delimiterRegEx} \index{delimiters!delimiter justification (left or right)}% \begin{warning} Important: note the `capturing' parenthesis in the \lstinline!(&)! which are necessary; 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}. \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/tabbing.tex}{\texttt{tabbing.tex}}{lst:tabbing} \cmhlistingsfromfile{demonstrations/tabbing-default.tex}{\texttt{tabbing.tex} default output}{lst:tabbing-default} \end{cmhtcbraster} 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>} \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/tabbing-mod1.tex}{\texttt{tabbing.tex} using \cref{lst:delimiterRegEx1}}{lst:tabbing-mod1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/delimiterRegEx1.yaml}[yaml-TCB]{\texttt{delimiterRegEx1.yaml}}{lst:delimiterRegEx1} \end{cmhtcbraster} We note that: \begin{itemize} \item in \cref{lst:tabbing-mod1} the code has been aligned, as intended, at both the \lstinline!\=! and \lstinline!\>!; \item in \cref{lst:delimiterRegEx1} we have heeded the warning and captured the expression using grouping parenthesis, specified a backslash using \lstinline!\\! and said that it must be followed by either \lstinline!=! or \lstinline!>!. \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>} \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/tabbing-mod2.tex}{\texttt{tabbing.tex} using \cref{lst:delimiterRegEx2}}{lst:tabbing-mod2} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/delimiterRegEx2.yaml}[yaml-TCB]{\texttt{delimiterRegEx2.yaml}}{lst:delimiterRegEx2} \end{cmhtcbraster} We note that only the \lstinline!\>! have been aligned. \end{example} \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} \cmhlistingsfromfile{demonstrations/tabbing-mod3.tex}{\texttt{tabbing.tex} using \cref{lst:delimiterRegEx3}}{lst:tabbing-mod3} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/delimiterRegEx3.yaml}[yaml-TCB]{\texttt{delimiterRegEx3.yaml}}{lst:delimiterRegEx3} \end{cmhtcbraster} \end{example} \begin{example} It is possible that delimiters specified within \texttt{delimiterRegEx} can be of different lengths. Consider the file in \cref{lst:tabbing1}, and associated YAML in \cref{lst:delimiterRegEx4}. Note that the \cref{lst:delimiterRegEx4} specifies the option for the delimiter to be either \lstinline!#! or \lstinline!\>!, \emph{which are different lengths}. Upon running the command \index{switches!-l demonstration} \index{switches!-o demonstration} \begin{commandshell} latexindent.pl tabbing1.tex -l=delimiterRegEx4.yaml -o=+-mod4 \end{commandshell} we receive the output in \cref{lst:tabbing1-mod4}. \index{regular expressions!delimiter regex at \#} \begin{cmhtcbraster}[raster columns=3, raster left skip=-3.5cm, raster right skip=-2cm, raster column skip=.03\linewidth] \cmhlistingsfromfile{demonstrations/tabbing1.tex}{\texttt{tabbing1.tex}}{lst:tabbing1} \cmhlistingsfromfile{demonstrations/tabbing1-mod4.tex}{\texttt{tabbing1-mod4.tex}}{lst:tabbing1-mod4} \cmhlistingsfromfile[style=yaml-LST]{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>} \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/tabbing1-mod5.tex}{\texttt{tabbing1-mod5.tex}}{lst:tabbing1-mod5} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/delimiterRegEx5.yaml}[yaml-TCB]{\texttt{delimiterRegEx5.yaml}}{lst:delimiterRegEx5} \end{cmhtcbraster} Note that in \cref{lst:tabbing1-mod5} the second set of delimiters have been \emph{right aligned} -- it is quite subtle! \end{example} \subsubsection{lookForAlignDelims: lookForChildCodeBlocks}\label{sec:lookForChildCodeBlocks} There \announce{2021-12-13}{lookForChildCodeBlocks demonstration} may be scenarios in which you would prefer to instruct \texttt{latexindent.pl} \emph{not} to search for child blocks; in which case setting \texttt{lookForChildCodeBlocks} to 0 may be a good way to proceed. \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} \cmhlistingsfromfile{demonstrations/tabular-DM-1-mod1.tex}{\texttt{tabular-DM-1-mod1.tex}}{lst:tabular-DM-1-mod1} \end{cmhtcbraster} 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} \cmhlistingsfromfile{demonstrations/tabular-DM-1-mod1a.tex}{\texttt{tabular-DM-1-mod1a.tex}}{lst:tabular-DM-1-mod1a} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/dontMeasure1a.yaml}[yaml-TCB]{\texttt{dontMeasure1a.yaml}}{lst:dontMeasure1a} \end{cmhtcbraster} \end{example} \subsubsection{lookForAlignDelims: alignContentAfterDoubleBackSlash}\label{sec:alignContentAfterDoubleBackSlash} You can instruct \texttt{latexindent} to align \announce{2023-05-01}{align content after double back slash} content after the double back slash. See also \vref{subsec:dbs}. \begin{example} We consider the file in \cref{lst:tabular5}, and the default output given in \cref{lst:tabular5-default}. \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/tabular5.tex}{\texttt{tabular5.tex}}{lst:tabular5} \cmhlistingsfromfile{demonstrations/tabular5-default.tex}{\texttt{tabular5-default.tex}}{lst:tabular5-default} \end{cmhtcbraster} Using the settings given in \cref{lst:alignContentAfterDBS1} and running \begin{commandshell} latexindent.pl -s tabular5.tex -l alignContentAfterDBS1 -o=+-mod1 \end{commandshell} gives the output in \cref{lst:tabular5-mod1}. \begin{cmhtcbraster}[raster columns=2, raster left skip=-2.5cm, raster column skip=.03\linewidth] \cmhlistingsfromfile{demonstrations/tabular5-mod1.tex}{\texttt{tabular5-mod1.tex}}{lst:tabular5-mod1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/alignContentAfterDBS1.yaml}[yaml-TCB]{\texttt{alignContentAfterDBS1.yaml}}{lst:alignContentAfterDBS1} \end{cmhtcbraster} \end{example} \begin{example} When using the \texttt{alignContentAfterDoubleBackSlash} feature, then you can also specify how many spaces to insert after the double backslash; the default is 1. \announce{2023-05-01}{specify number of spaces after double back slash when aligning content after double back slash} Starting from \cref{lst:tabular5} and using the the settings given in \cref{lst:alignContentAfterDBS2} \begin{commandshell} latexindent.pl -s tabular5.tex -l alignContentAfterDBS2 -o=+-mod2 \end{commandshell} gives the output in \cref{lst:tabular5-mod2}. \begin{cmhtcbraster}[raster columns=2, raster left skip=-2.5cm, raster column skip=.03\linewidth] \cmhlistingsfromfile{demonstrations/tabular5-mod2.tex}{\texttt{tabular5-mod2.tex}}{lst:tabular5-mod2} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/alignContentAfterDBS2.yaml}[yaml-TCB]{\texttt{alignContentAfterDBS2.yaml}}{lst:alignContentAfterDBS2} \end{cmhtcbraster} \end{example} \subsection{Indent after items, specials and headings} \yamltitle{indentAfterItems}*{fields} The environment names specified in \texttt{indentAfterItems} tell \texttt{latexindent.pl} to look for \lstinline!\item! commands; if these switches are set to \texttt{1} then indentation will be performed so as indent the code after each \texttt{item}. A demonstration is given in \cref{lst:itemsbefore,lst:itemsafter} \begin{cmhtcbraster}[raster columns=3, raster left skip=-3.5cm, raster right skip=-2cm, raster column skip=.03\linewidth] \cmhlistingsfromfile[style=indentAfterItems]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{indentAfterItems}}{lst:indentafteritems} \cmhlistingsfromfile{demonstrations/items1.tex}{\texttt{items1.tex}}{lst:itemsbefore} \cmhlistingsfromfile{demonstrations/items1-default.tex}{\texttt{items1.tex} default output}{lst:itemsafter} \end{cmhtcbraster} \yamltitle{itemNames}*{fields} If you have your own \texttt{item} commands (perhaps you prefer to use \texttt{myitem}, for example) then you can put populate them in \texttt{itemNames}. For example, users of the \texttt{exam} document class might like to add \texttt{parts} to \texttt{indentAfterItems} and \texttt{part} to \texttt{itemNames} to their user settings (see \vref{sec:indentconfig} for details of how to configure user settings, and \vref{lst:mysettings} \\ in particular \label{page:examsettings}.) \cmhlistingsfromfile[style=itemNames]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{itemNames}}{lst:itemNames} \yamltitle{specialBeginEnd}*{fields}\label{yaml:specialBeginEnd} The fields specified \index{specialBeginEnd!introduction} \announce{2017-08-21}*{specialBeginEnd} in \texttt{specialBeginEnd} are, in their default state, focused on math mode begin and end statements, but there is no requirement for this to be the case; \cref{lst:specialBeginEnd} shows the default settings of \texttt{specialBeginEnd}. \index{specialBeginEnd!default settings}% \cmhlistingsfromfile[style=specialBeginEnd]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{specialBeginEnd}}{lst:specialBeginEnd} The field \texttt{displayMath} represents \lstinline!\[...\]!, \texttt{inlineMath} represents \lstinline!$...$! and \texttt{displayMathTex} represents \lstinline!$$...$$!. You can, of course, rename these in your own YAML files (see \vref{sec:localsettings}); indeed, you might like to set up your own special begin and end statements. \begin{example} A demonstration of the before-and-after results are shown in \cref{lst:specialbefore,lst:specialafter}; explicitly, running the command \begin{commandshell} latexindent.pl special1.tex -o=+-default \end{commandshell} gives the output given in \cref{lst:specialafter}. \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/special1.tex}{\texttt{special1.tex} before}{lst:specialbefore} \cmhlistingsfromfile{demonstrations/special1-default.tex}{\texttt{special1.tex} default output}{lst:specialafter} \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} not to look for the pattern, by setting \texttt{lookForThis} to \texttt{0}. There are \announce{2017-08-21}{specialBeforeCommand} examples in which it is advantageous to search for \texttt{specialBeginEnd} fields \emph{before} searching for commands, and the \texttt{specialBeforeCommand} switch controls this behaviour. \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 \cref{lst:specialsLeftRight-yaml,lst:specialBeforeCommand-yaml} \index{specialBeginEnd!searching for special before commands} \begin{cmhtcbraster} \cmhlistingsfromfile[]{demonstrations/specialsLeftRight.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{specialsLeftRight.yaml}}{lst:specialsLeftRight-yaml} \cmhlistingsfromfile[]{demonstrations/specialBeforeCommand.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{specialBeforeCommand.yaml}}{lst:specialBeforeCommand-yaml} \end{cmhtcbraster} 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}. \begin{minipage}{.49\linewidth} \cmhlistingsfromfile{demonstrations/specialLR-comm-first.tex}{\texttt{specialLR.tex} using \cref{lst:specialsLeftRight-yaml}}{lst:specialLR-comm-first-tex} \end{minipage} \hfill \begin{minipage}{.49\linewidth} \cmhlistingsfromfile{demonstrations/specialLR-special-first.tex}{\texttt{specialLR.tex} using \cref{lst:specialsLeftRight-yaml,lst:specialBeforeCommand-yaml}}{lst:specialLR-special-first-tex} \end{minipage} Notice that in: \begin{itemize} \item \cref{lst:specialLR-comm-first-tex} the \lstinline!\left! has been treated as a \emph{command}, with one optional argument; \item \cref{lst:specialLR-special-first-tex} the \texttt{specialBeginEnd} pattern in \cref{lst:specialsLeftRight-yaml} has been obeyed because \cref{lst:specialBeforeCommand-yaml} specifies that the \texttt{specialBeginEnd} should be sought \emph{before} commands. \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}. \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} 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} \cmhlistingsfromfile{demonstrations/special2-mod1.tex}{\texttt{special2.tex} using \cref{lst:middle-yaml}}{lst:special2-mod1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/middle.yaml}[yaml-TCB]{\texttt{middle.yaml}}{lst:middle-yaml} \end{cmhtcbraster} \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/special2-mod2.tex}{\texttt{special2.tex} using \cref{lst:middle1-yaml}}{lst:special2-mod2} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/middle1.yaml}[yaml-TCB]{\texttt{middle1.yaml}}{lst:middle1-yaml} \end{cmhtcbraster} We note that: \begin{itemize} \item in \cref{lst:special2-mod1} the bodies of each of the \texttt{Elsif} statements have been indented appropriately; \item the \texttt{Else} statement has \emph{not} been indented appropriately in \cref{lst:special2-mod1} -- read on! \item we have specified multiple settings for the \texttt{middle} field using the syntax demonstrated in \cref{lst:middle1-yaml} so that the body of the \texttt{Else} statement has been indented appropriately in \cref{lst:special2-mod2}. \end{itemize} \end{example} You may need these fields in your own YAML files (see \vref{sec:localsettings}), if you use popular algorithm packages such as algorithms, algorithm2e or algpseudocode, etc. \begin{example} For example, let’s consider the \texttt{.tex} file in \cref{lst:specialAlgo}. \index{specialBeginEnd!middle} \index{specialBeginEnd!Algorithms example} \cmhlistingsfromfile[basicstyle=\tiny]{demonstrations/specialAlgo.tex}[enhanced jigsaw,breakable]{\texttt{specialAlgo.tex}}{lst:specialAlgo} Upon saving the YAML settings in \cref{lst:algo-yaml} and running the command \index{switches!-l demonstration} \begin{commandshell} latexindent.pl -l=algo.yaml specialAlgo.tex \end{commandshell} then we obtain the output given in \cref{lst:specialAlgo-mod1}. \begin{cmhtcbraster} \cmhlistingsfromfile[basicstyle=\tiny]{demonstrations/specialAlgo-mod1.tex}{\texttt{specialAlgo.tex} using \cref{lst:algo-yaml}}{lst:specialAlgo-mod1} \cmhlistingsfromfile[style=yaml-LST,basicstyle=\tiny,commentstyle=\color{blue}\ttfamily\tiny]{demonstrations/algo.yaml}[yaml-TCB]{\texttt{algo.yaml}}{lst:algo-yaml} \end{cmhtcbraster} \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} \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/special3-mod1.tex}{\texttt{special3.tex} and output using \cref{lst:special-verb1-yaml}}{lst:special3-mod1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/special-verb1.yaml}[yaml-TCB]{\texttt{special-verb1.yaml}}{lst:special-verb1-yaml} \end{cmhtcbraster} \end{example} We can combine the \texttt{specialBeginEnd} with the \texttt{lookForAlignDelims} feature. \begin{example} We begin with the code in \cref{lst:special-align}. \cmhlistingsfromfile{demonstrations/special-align.tex}{\texttt{special-align.tex}}{lst:special-align} Let's assume that our goal is to align the code at the \texttt{edge} and \texttt{node} text; we employ the code given in \cref{lst:edge-node1} and run the command \index{switches!-l demonstration} \index{switches!-o demonstration} \begin{commandshell} latexindent.pl special-align.tex -l edge-node1.yaml -o=+-mod1 \end{commandshell} to receive the output in \cref{lst:special-align-mod1}. \index{specialBeginEnd!combined with lookForAlignDelims} \index{specialBeginEnd!delimiterRegEx} \index{specialBeginEnd!alignment at delimiter} \index{specialBeginEnd!tikz example} \index{regular expressions!delimiter alignment for edge or node} \index{delimiters!within specialBeginEnd blocks} \index{regular expressions!numeric 0-9} \begin{cmhtcbraster}[ raster left skip=-3.5cm,] \cmhlistingsfromfile{demonstrations/special-align-mod1.tex}{\texttt{special-align.tex} using \cref{lst:edge-node1}}{lst:special-align-mod1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/edge-node1.yaml}[yaml-TCB]{\texttt{edge-node1.yaml}}{lst:edge-node1} \end{cmhtcbraster} The output in \cref{lst:special-align-mod1} is not quite ideal. We can tweak the settings within \cref{lst:edge-node1} in order to improve the output; in particular, we employ the code in \cref{lst:edge-node2} and run the command \index{switches!-l demonstration} \index{switches!-o demonstration} \index{regular expressions!uppercase alph A-Z} \begin{commandshell} latexindent.pl special-align.tex -l edge-node2.yaml -o=+-mod2 \end{commandshell} to receive the output in \cref{lst:special-align-mod2}. \index{specialBeginEnd!delimiterRegEx tweaked} \index{regular expressions!at least one +} \index{regular expressions!horizontal space \textbackslash{h}} \begin{cmhtcbraster}[ raster left skip=-3.5cm,] \cmhlistingsfromfile{demonstrations/special-align-mod2.tex}{\texttt{special-align.tex} using \cref{lst:edge-node2}}{lst:special-align-mod2} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/edge-node2.yaml}[yaml-TCB]{\texttt{edge-node2.yaml}}{lst:edge-node2} \end{cmhtcbraster} \end{example} The \texttt{lookForThis} field can be considered optional; \announce{2021-06-19}*{lookForThis optional for specialBeginEnd} by default, it is assumed to be 1, which is demonstrated in \cref{lst:edge-node2}.% Referencing \vref{lst:specialBeginEnd} we see that \announce{2023-09-23}{specialBeginEnd body field} each of the \texttt{specialBeginEnd} fields can \emph{optionally} accept the \texttt{body} field. If the \texttt{body} field is omitted, then \texttt{latexindent.pl} uses a value that means \begin{quote} anything except one of the begin statements from \texttt{specialBeginEnd}. \end{quote} In general, it is usually \emph{not} necessary to specify the \texttt{body} field, but let's detail an example just for reference. \begin{example} We begin with the example in \cref{lst:special-body} \cmhlistingsfromfile{demonstrations/special-body.tex}{\texttt{special-body.tex}}{lst:special-body} Using the settings in \cref{lst:special-body1} and running the command \begin{commandshell} latexindent.pl special-body.tex -l=special-body1.yaml \end{commandshell} gives the output in \cref{lst:special-body-mod1}. \begin{cmhtcbraster}[ raster left skip=-3.5cm,] \cmhlistingsfromfile{demonstrations/special-body-mod1.tex}{\texttt{special-body.tex} using \cref{lst:special-body1}}{lst:special-body-mod1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/special-body1.yaml}[yaml-TCB]{\texttt{special-body1.yaml}}{lst:special-body1} \end{cmhtcbraster} We note that the output in \cref{lst:special-body-mod1} is as we would expect, even \emph{without} the \texttt{body} field specified. Another option (purely for reference) that leaves the output in \cref{lst:special-body-mod1} unchanged is shown in \cref{lst:special-body2}. \cmhlistingsfromfile[style=yaml-LST]{demonstrations/special-body2.yaml}[yaml-TCB]{\texttt{special-body2.yaml}}{lst:special-body2} The \texttt{body} field in \cref{lst:special-body2} means \emph{anything except ( or )}. \end{example} \yamltitle{indentAfterHeadings}*{fields} This field enables the user to specify indentation rules that take effect after heading commands such as \lstinline!\part!, \lstinline!\chapter!, \lstinline!\section!, \lstinline!\subsection*!, or indeed any user-specified command written in this field.\footnote{There is a slight difference in interface for this field when comparing Version 2.2 to Version 3.0; see \vref{app:differences} for details.} \cmhlistingsfromfile[style=indentAfterHeadings]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{indentAfterHeadings}}{lst:indentAfterHeadings} The default settings do \emph{not} place indentation after a heading, but you can easily switch them on by changing \texttt{indentAfterThisHeading} from 0 to 1. The \texttt{level} field tells \texttt{latexindent.pl} the hierarchy of the heading structure in your document. You might, for example, like to have both \texttt{section} and \texttt{subsection} set with \texttt{level: 3} because you do not want the indentation to go too deep. You can add any of your own custom heading commands to this field, specifying the \texttt{level} as appropriate. You can also specify your own indentation in \texttt{indentRules} (see \vref{sec:noadd-indent-rules}); you will find the default \texttt{indentRules} contains \lstinline!chapter: " "! which tells \texttt{latexindent.pl} simply to use a space character after \texttt{chapter} headings (once \texttt{indent} is set to \texttt{1} for \texttt{chapter}). \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}. \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/headings1.tex}{\texttt{headings1.tex}}{lst:headings1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/headings1.yaml}[yaml-TCB]{\texttt{headings1.yaml}}{lst:headings1yaml} \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} \cmhlistingsfromfile[showtabs=true]{demonstrations/headings1-mod1.tex}{\texttt{headings1.tex} using \cref{lst:headings1yaml}}{lst:headings1-mod1} \end{minipage}% \hfill \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. \index{indentation!maximum indetation} \yamltitle{maximumIndentation}*{horizontal space} You can control the maximum indentation given to your file by \announce{2017-08-21}{maximumIndentation} specifying the \texttt{maximumIndentation} field as horizontal space (but \emph{not} including tabs). This feature uses the \texttt{Text::Tabs} module \cite{texttabs}, and is \emph{off} by default.% \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}. \begin{cmhtcbraster}[raster column skip=.1\linewidth] \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} \cmhlistingsfromfile[showspaces=true]{demonstrations/mult-nested-max-ind1.tex}{\texttt{mult-nested.tex} using \cref{lst:max-indentation1yaml}}{lst:mult-nested-max-ind1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/max-indentation1.yaml}[yaml-TCB]{\texttt{max-indentation1.yaml}}{lst:max-indentation1yaml} \end{cmhtcbraster} \end{example} Comparing the output in \cref{lst:mult-nested-default,lst:mult-nested-max-ind1} we notice that the (default) tabs of indentation have been replaced by a single space. In general, when using the \texttt{maximumIndentation} feature, any leading tabs will be replaced by equivalent spaces except, of course, those found in \texttt{verbatimEnvironments} (see \vref{lst:verbatimEnvironments}) or \texttt{noIndentBlock} (see \vref{lst:noIndentBlock}). \subsection{The code blocks known latexindent.pl}\label{subsubsec:code-blocks} As of Version 3.0, \texttt{latexindent.pl} processes documents using code blocks; each of these are shown in \cref{tab:code-blocks}. \index{regular expressions!uppercase alph A-Z} \index{regular expressions!lowercase alph a-z} \index{regular expressions!numeric 0-9} \index{regular expressions!horizontal space \textbackslash{h}} \begin{table}[!htp] \begin{widepage} \centering \caption{Code blocks known to \texttt{latexindent.pl}} \label{tab:code-blocks} \begin{tabular}{m{.3\linewidth}@{\hspace{.25cm}}m{.4\linewidth}@{\hspace{.25cm}}m{.2\linewidth}} \toprule Code block & characters allowed in name & example \\ \midrule environments & \lstinline!a-zA-Z@\*0-9_\\! & \begin{lstlisting}[,nolol=true,] \begin{myenv} body of myenv \end{myenv} \end{lstlisting} \\\cmidrule{2-3} optionalArguments & \emph{inherits} name from parent (e.g environment name) & \begin{lstlisting}[,nolol=true,] [ opt arg text ] \end{lstlisting} \\\cmidrule{2-3} mandatoryArguments & \emph{inherits} name from parent (e.g environment name) & \begin{lstlisting}[,nolol=true,] { mand arg text } \end{lstlisting} \\\cmidrule{2-3} commands & \lstinline!+a-zA-Z@\*0-9_\:! & \lstinline!\mycommand!$\langle$\itshape{arguments}$\rangle$ \\\cmidrule{2-3} keyEqualsValuesBracesBrackets & \lstinline!a-zA-Z@\*0-9_\/.\h\{\}:\#-! & \lstinline!my key/.style=!$\langle$\itshape{arguments}$\rangle$ \\\cmidrule{2-3} namedGroupingBracesBrackets & \lstinline!0-9\.a-zA-Z@\*><! & \lstinline!in!$\langle$\itshape{arguments}$\rangle$ \\\cmidrule{2-3} UnNamedGroupingBracesBrackets & \centering\emph{No name!} & \lstinline!{! or \lstinline![! or \lstinline!,! or \lstinline!\&! or \lstinline!)! or \lstinline!(! or \lstinline!$! followed by $\langle$\itshape{arguments}$\rangle$ \\\cmidrule{2-3} ifElseFi & \lstinline!@a-zA-Z! but must begin with either \newline \lstinline!\if! of \lstinline!\@if! & \begin{lstlisting}[,nolol=true,] \ifnum... ... \else ... \fi \end{lstlisting} \\\cmidrule{2-3} items & User specified, see \vref{lst:indentafteritems,lst:itemNames} & \begin{lstlisting}[,nolol=true,] \begin{enumerate} \item ... \end{enumerate} \end{lstlisting} \\\cmidrule{2-3} specialBeginEnd & User specified, see \vref{lst:specialBeginEnd} & \begin{lstlisting}[,nolol=true,] \[ ... \] \end{lstlisting} \\\cmidrule{2-3} afterHeading & User specified, see \vref{lst:indentAfterHeadings} & \begin{lstlisting}[,morekeywords={chapter},nolol=true,] \chapter{title} ... \section{title} \end{lstlisting} \\\cmidrule{2-3} filecontents & User specified, see \vref{lst:fileContentsEnvironments} & \begin{lstlisting}[,nolol=true,] \begin{filecontents} ... \end{filecontents} \end{lstlisting} \\ \bottomrule \end{tabular} \end{widepage} \end{table} We will refer to these code blocks in what follows. \announce{2019-07-13}{fine tuning of code blocks} Note that the fine tuning of the definition of the code blocks detailed in \cref{tab:code-blocks} is discussed in \vref{sec:finetuning}.% % arara: pdflatex: { files: [latexindent]} % arara: pdflatex: { files: [latexindent]} \index{indentation!no additional indent} \index{indentation!removing indentation per-code block} \index{indentation!customising indentation per-code block} \index{indentation!customising per-name} \index{indentation!no additional indent global} \subsection{noAdditionalIndent and indentRules}\label{sec:noadd-indent-rules} \texttt{latexindent.pl} operates on files by looking for code blocks, as detailed in \vref{subsubsec:code-blocks}; for each type of code block in \vref{tab:code-blocks} (which we will call a \emph{$\langle$thing$\rangle$} in what follows) it searches YAML fields for information in the following order: \begin{enumerate} \item \texttt{noAdditionalIndent} for the \emph{name} of the current \emph{$\langle$thing$\rangle$}; \item \texttt{indentRules} for the \emph{name} of the current \emph{$\langle$thing$\rangle$}; \item \texttt{noAdditionalIndentGlobal} for the \emph{type} of the current \emph{$\langle$thing$\rangle$}; \item \texttt{indentRulesGlobal} for the \emph{type} of the current \emph{$\langle$thing$\rangle$}. \end{enumerate} Using the above list, the first piece of information to be found will be used; failing that, the value of \texttt{defaultIndent} is used. If information is found in multiple fields, the first one according to the list above will be used; for example, if information is present in both \texttt{indentRules} and in \texttt{noAdditionalIndentGlobal}, then the information from \texttt{indentRules} takes priority. We now present details for the different type of code blocks known to \texttt{latexindent.pl}, as detailed in \vref{tab:code-blocks}; for reference, there follows a list of the code blocks covered. \startcontents[noAdditionalIndent] \printcontents[noAdditionalIndent]{}{0}{} % arara: pdflatex: { files: [latexindent]} \subsubsection{Environments and their arguments}\label{subsubsec:env-and-their-args} There are a few different YAML switches governing the indentation of environments; let's start with the code shown in \cref{lst:myenvtex}. \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}. \begin{minipage}{.45\textwidth} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/myenv-noAdd1.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-noAdd1.yaml}}{lst:myenv-noAdd1} \end{minipage} \hfill \begin{minipage}{.45\textwidth} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/myenv-noAdd2.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-noAdd2.yaml}}{lst:myenv-noAdd2} \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{cmhtcbraster} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/myenv-noAdd3.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-noAdd3.yaml}}{lst:myenv-noAdd3} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/myenv-noAdd4.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-noAdd4.yaml}}{lst:myenv-noAdd4} \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}. \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 \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{cmhtcbraster} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/myenv-noAdd5.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-noAdd5.yaml}}{lst:myenv-noAdd5} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/myenv-noAdd6.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-noAdd6.yaml}}{lst:myenv-noAdd6} \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 any additional indentation, and that in \cref{lst:myenv-args-noAdd6} the \emph{mandatory} argument has not received any additional indentation; in both cases, the \emph{body} has not received any additional indentation. \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/myenvironment-args-noAdd5.tex}{\texttt{myenv-args.tex} using \cref{lst:myenv-noAdd5}}{lst:myenv-args-noAdd5} \cmhlistingsfromfile{demonstrations/myenvironment-args-noAdd6.tex}{\texttt{myenv-args.tex} using \cref{lst:myenv-noAdd6}}{lst:myenv-args-noAdd6} \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}. \begin{cmhtcbraster}[raster column skip=.1\linewidth] \cmhlistingsfromfile[style=yaml-LST]{demonstrations/myenv-rules1.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-rules1.yaml}}{lst:myenv-rules1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/myenv-rules2.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-rules2.yaml}}{lst:myenv-rules2} \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} \begin{minipage}{.49\textwidth} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/myenv-rules3.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-rules3.yaml}}{lst:myenv-rules3} \end{minipage} \hfill \begin{minipage}{.49\textwidth} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/myenv-rules4.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-rules4.yaml}}{lst:myenv-rules4} \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}. \begin{widepage} \begin{minipage}{.5\textwidth} \cmhlistingsfromfile[showtabs=true,showspaces=true]{demonstrations/myenvironment-args-rules3.tex}{\texttt{myenv-args.tex} using \cref{lst:myenv-rules3}}{lst:myenv-args-rules3} \end{minipage}% \hfill \begin{minipage}{.5\textwidth} \cmhlistingsfromfile[showtabs=true,showspaces=true]{demonstrations/myenvironment-args-rules4.tex}{\texttt{myenv-args.tex} using \cref{lst:myenv-rules4}}{lst:myenv-args-rules4} \end{minipage} \end{widepage} Note that in \cref{lst:myenv-args-rules3}, the optional argument has only received a single space of indentation, while the mandatory argument has received the default (tab) indentation; the environment body has received three spaces of indentation. 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 \texttt{noAdditionalIndent} nor \texttt{indentRules}, the next place that \texttt{latexindent.pl} will look is \texttt{noAdditionalIndentGlobal}, and in particular \emph{for the environments} key (see \cref{lst:noAdditionalIndentGlobal:environments}). \cmhlistingsfromfile[style=noAdditionalIndentGlobalEnv]{../defaultSettings.yaml}[width=.7\linewidth,before=\centering,yaml-TCB]{\texttt{noAdditionalIndentGlobal}}{lst:noAdditionalIndentGlobal:environments} \begin{example} Let's say that you change the value of \texttt{environments} to \texttt{1} in \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 \cref{lst:myenv-args-no-add-global1,lst:myenv-args-no-add-global2}; in \cref{lst:myenv-args-no-add-global1} notice that \emph{both} environments receive no additional indentation but that the arguments of \texttt{myenv} still \emph{do} receive indentation. In \cref{lst:myenv-args-no-add-global2} notice that the \emph{outer} environment does not receive additional indentation, but because of the settings from \texttt{myenv-rules1.yaml} (in \vref{lst:myenv-rules1}), the \texttt{myenv} environment still \emph{does} receive indentation. \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/myenvironment-args-rules1-noAddGlobal1.tex}{\texttt{myenv-args.tex} using \cref{lst:noAdditionalIndentGlobal:environments}}{lst:myenv-args-no-add-global1} \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{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{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} \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{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 additional indentation, and in \cref{lst:myenv-args-no-add-mand} the \emph{mandatory} argument has not received any additional indentation. \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} \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{cmhtcbraster} \end{example} \yamltitle{indentRulesGlobal}*{fields} The final check that \texttt{latexindent.pl} will make is to look for \texttt{indentRulesGlobal} as detailed in \cref{lst:indentRulesGlobal:environments}. \cmhlistingsfromfile[style=indentRulesGlobalEnv]{../defaultSettings.yaml}[width=.7\linewidth,before=\centering,yaml-TCB]{\texttt{indentRulesGlobal}}{lst:indentRulesGlobal:environments} \begin{example} If you change the \texttt{environments} field to anything involving horizontal space, say \lstinline!" "!, and then run the following commands \index{switches!-l demonstration} \begin{commandshell} latexindent.pl myenv-args.tex -l env-indentRules.yaml latexindent.pl myenv-args.tex -l myenv-rules1.yaml,env-indentRules.yaml \end{commandshell} then the respective output is shown in \cref{lst:myenv-args-indent-rules-global1,lst:myenv-args-indent-rules-global2}. Note that in \cref{lst:myenv-args-indent-rules-global1}, both the environment blocks have received a single-space indentation, whereas in \cref{lst:myenv-args-indent-rules-global2} the \texttt{outer} environment has received single-space indentation (specified by \texttt{indentRulesGlobal}), but \texttt{myenv} has received \lstinline!" "!, as specified by the particular \texttt{indentRules} for \texttt{myenv} \vref{lst:myenv-rules1}. \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} \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{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{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} \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{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 two tabs worth of indentation, while the \emph{mandatory} argument has done so in \cref{lst:myenv-args-indent-rules-global4}. \begin{widepage} \begin{minipage}{.55\textwidth} \cmhlistingsfromfile[showtabs=true]{demonstrations/myenvironment-args-global-rules3.tex}{\texttt{myenv-args.tex} using \cref{lst:opt-args-indent-rules-glob}}{lst:myenv-args-indent-rules-global3} \end{minipage} \hfill \begin{minipage}{.55\textwidth} \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 \texttt{item} commands; for the purposes of this discussion, we will use the code from \vref{lst:itemsbefore}. Assuming that you've populated \texttt{itemNames} with the name of your \texttt{item}, you can put the item name into \texttt{noAdditionalIndent} as in \cref{lst:item-noAdd1}, although a more efficient approach may be to change the relevant field in \texttt{itemNames} to \texttt{0}. \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} \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 \texttt{item} has received a single space of indentation, specified by \cref{lst:item-rules1}. \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/items1-noAdd1.tex}{\texttt{items1.tex} using \cref{lst:item-noAdd1}}{lst:items1-noAdd1} \cmhlistingsfromfile[showtabs=true,showspaces=true]{demonstrations/items1-rules1.tex}{\texttt{items1.tex} using \cref{lst:item-rules1}}{lst:items1-rules1} \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 need to `reset/remove' the \texttt{item} field from \texttt{indentRules} in both cases (see the hierarchy description given on \cpageref{sec:noadd-indent-rules}) as the \texttt{item} command is a member of \texttt{indentRules} by default. \begin{cmhtcbraster} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/items-noAdditionalGlobal.yaml}[yaml-TCB]{\texttt{items-noAdditionalGlobal.yaml}}{lst:items-noAdditionalGlobal} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/items-indentRulesGlobal.yaml}[yaml-TCB]{\texttt{items-indentRulesGlobal.yaml}}{lst:items-indentRulesGlobal} \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 \vref{subsec:commands-string-between}.} \begin{cmhtcbraster}[raster column skip=.1\linewidth] \cmhlistingsfromfile{demonstrations/mycommand.tex}{\texttt{mycommand.tex}}{lst:mycommand} \cmhlistingsfromfile{demonstrations/mycommand-default.tex}{\texttt{mycommand.tex} default output}{lst:mycommand-default} \end{cmhtcbraster} As in the environment-based case (see \vref{lst:myenv-noAdd1,lst:myenv-noAdd2}) we may specify \texttt{noAdditionalIndent} either in `scalar' form, or in `field' form, as shown in \cref{lst:mycommand-noAdd1,lst:mycommand-noAdd2} \begin{cmhtcbraster} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycommand-noAdd1.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{mycommand-noAdd1.yaml}}{lst:mycommand-noAdd1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycommand-noAdd2.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{mycommand-noAdd2.yaml}}{lst:mycommand-noAdd2} \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{cmhtcbraster} \cmhlistingsfromfile{demonstrations/mycommand-noAdd1.tex}{\texttt{mycommand.tex} using \cref{lst:mycommand-noAdd1}}{lst:mycommand-output-noAdd1} \cmhlistingsfromfile{demonstrations/mycommand-noAdd2.tex}{\texttt{mycommand.tex} using \cref{lst:mycommand-noAdd2}}{lst:mycommand-output-noAdd2} \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 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{cmhtcbraster} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycommand-noAdd3.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{mycommand-noAdd3.yaml}}{lst:mycommand-noAdd3} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycommand-noAdd4.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{mycommand-noAdd4.yaml}}{lst:mycommand-noAdd4} \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{cmhtcbraster} \cmhlistingsfromfile{demonstrations/mycommand-noAdd3.tex}{\texttt{mycommand.tex} using \cref{lst:mycommand-noAdd3}}{lst:mycommand-output-noAdd3} \cmhlistingsfromfile{demonstrations/mycommand-noAdd4.tex}{\texttt{mycommand.tex} using \cref{lst:mycommand-noAdd4}}{lst:mycommand-output-noAdd4} \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 \cref{lst:mycommand-noAdd3,lst:mycommand-noAdd4}. This is because, by default, \texttt{noAdditionalIndentGlobal} for \texttt{commands} is set to \texttt{1} by default; this can be easily fixed as in \cref{lst:mycommand-noAdd5,lst:mycommand-noAdd6}.\label{page:command:noAddGlobal} \begin{cmhtcbraster} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycommand-noAdd5.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{mycommand-noAdd5.yaml}}{lst:mycommand-noAdd5} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycommand-noAdd6.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{mycommand-noAdd6.yaml}}{lst:mycommand-noAdd6} \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{cmhtcbraster} \cmhlistingsfromfile{demonstrations/mycommand-noAdd5.tex}{\texttt{mycommand.tex} using \cref{lst:mycommand-noAdd5}}{lst:mycommand-output-noAdd5} \cmhlistingsfromfile{demonstrations/mycommand-noAdd6.tex}{\texttt{mycommand.tex} using \cref{lst:mycommand-noAdd6}}{lst:mycommand-output-noAdd6} \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 \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{cmhtcbraster} \cmhlistingsfromfile{demonstrations/ifelsefi1.tex}{\texttt{ifelsefi1.tex}}{lst:ifelsefi1} \cmhlistingsfromfile{demonstrations/ifelsefi1-default.tex}{\texttt{ifelsefi1.tex} default output}{lst:ifelsefi1-default} \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, assuming that \texttt{body} was specified. Examples are shown in \cref{lst:ifnum-noAdd,lst:ifnum-indent-rules}. \begin{cmhtcbraster} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/ifnum-noAdd.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{ifnum-noAdd.yaml}}{lst:ifnum-noAdd} \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{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 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{cmhtcbraster} \cmhlistingsfromfile{demonstrations/ifelsefi1-noAdd.tex}{\texttt{ifelsefi1.tex} using \cref{lst:ifnum-noAdd}}{lst:ifelsefi1-output-noAdd} \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{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{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} \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{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 blocks have received indentation, while in \cref{lst:ifelsefi1-output-indent-rules-global} both code blocks have received a single space of indentation. \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/ifelsefi1-noAdd-glob.tex}{\texttt{ifelsefi1.tex} using \cref{lst:ifelsefi-noAdd-glob}}{lst:ifelsefi1-output-noAdd-glob} \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{cmhtcbraster} \end{example} \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 \cref{lst:displayMath-noAdd,lst:displayMath-indent-rules}. \index{specialBeginEnd!noAdditionalIndent} \index{specialBeginEnd!indentRules example} \begin{cmhtcbraster} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/displayMath-noAdd.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{displayMath-noAdd.yaml}}{lst:displayMath-noAdd} \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{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} 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{cmhtcbraster} \cmhlistingsfromfile{demonstrations/special1-noAdd.tex}{\texttt{special1.tex} using \cref{lst:displayMath-noAdd}}{lst:special1-output-noAdd} \cmhlistingsfromfile[showtabs=true]{demonstrations/special1-indent-rules.tex}{\texttt{special1.tex} using \cref{lst:displayMath-indent-rules}}{lst:special1-output-indent-rules} \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{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} \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{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 have received indentation, while in \cref{lst:special1-output-indent-rules-global} both code blocks have received a single space of indentation. \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/special1-noAdd-glob.tex}{\texttt{special1.tex} using \cref{lst:special-noAdd-glob}}{lst:special1-output-noAdd-glob} \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{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 \namecref{subsubsec-headings-no-add-indent-rules}. As discussed on \cpageref{lst:headings1}, by default \texttt{latexindent.pl} will not add indentation after headings. \cmhlistingsfromfile{demonstrations/headings2.tex}{\texttt{headings2.tex}}{lst:headings2} \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. \begin{cmhtcbraster}[raster column skip=.1\linewidth] \cmhlistingsfromfile{demonstrations/headings2-mod3.tex}{\texttt{headings2.tex} using \cref{lst:headings3yaml}}{lst:headings2-mod3} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/headings3.yaml}[yaml-TCB]{\texttt{headings3.yaml}}{lst:headings3yaml} \end{cmhtcbraster} If we specify \texttt{noAdditionalIndent} as in \cref{lst:headings4yaml} and run the command \index{switches!-l demonstration} \begin{commandshell} latexindent.pl headings2.tex -l headings4.yaml \end{commandshell} then we receive the output in \cref{lst:headings2-mod4}. Note that the arguments \emph{and} the body after the heading of \texttt{paragraph} has received no additional indentation, because we have specified \texttt{noAdditionalIndent} in scalar form. \begin{cmhtcbraster}[raster column skip=.1\linewidth] \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} of \texttt{paragraph} have \emph{all} received three tabs worth of indentation. \begin{cmhtcbraster}[raster force size=false, raster column 1/.style={add to width=1cm}, raster column 2/.style={add to width=-1cm}, ] \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}. \begin{cmhtcbraster} \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 three tabs worth of indentation. \begin{cmhtcbraster} \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} the \emph{mandatory argument} of \texttt{paragraph} has received a (default) tab's worth of indentation, while the body after the heading has received \emph{no additional indentation}. Similarly, in \cref{lst:headings2-mod9}, the \emph{argument} has received both a (default) tab plus two spaces of indentation (from the global rule specified in \cref{lst:headings9yaml}), and the remaining body after \texttt{paragraph} has received just two spaces of indentation. \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/headings2-mod8.tex}{\texttt{headings2.tex} using \cref{lst:headings8yaml}}{lst:headings2-mod8} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/headings8.yaml}[yaml-TCB]{\texttt{headings8.yaml}}{lst:headings8yaml} \end{cmhtcbraster} \begin{cmhtcbraster} \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 code blocks yet to cover; these are very similar to the \texttt{commands} code block type covered comprehensively in \vref{subsubsec:commands-arguments}, but a small discussion defining these remaining code blocks is necessary. \paragraph{keyEqualsValuesBracesBrackets} \texttt{latexindent.pl} defines this type of code block by the following criteria: \begin{itemize} \item it must immediately follow either \lstinline!{! OR \lstinline![! OR \lstinline!,! with comments and blank lines allowed. \item then it has a name made up of the characters detailed in \vref{tab:code-blocks}; \item then an $=$ symbol; \item then at least one set of curly braces or square brackets (comments and line breaks allowed throughout). \end{itemize} See the \texttt{keyEqualsValuesBracesBrackets: follow} and \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{cmhtcbraster} \cmhlistingsfromfile{demonstrations/pgfkeys1.tex}{\texttt{pgfkeys1.tex}}{lst:pgfkeysbefore} \cmhlistingsfromfile[showtabs=true]{demonstrations/pgfkeys1-default.tex}{\texttt{pgfkeys1.tex} default output}{lst:pgfkeys1:default} \end{cmhtcbraster} In \cref{lst:pgfkeys1:default}, note that the maximum indentation is three tabs, and these come from: \begin{itemize} \item the \lstinline!\pgfkeys! command's mandatory argument; \item the \lstinline!start coordinate/.initial! key's mandatory argument; \item the \lstinline!start coordinate/.initial! key's body, which is defined as any lines following the name of the key that include its arguments. This is the part controlled by the \emph{body} field for \texttt{noAdditionalIndent} and friends from \cpageref{sec:noadd-indent-rules}. \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} \item it must immediately follow either \emph{horizontal space} OR \emph{one or more line breaks} OR \lstinline!{! OR \lstinline![! OR \lstinline!$! OR \lstinline!)! OR \lstinline!(! \item the name may contain the characters detailed in \vref{tab:code-blocks}; \item then at least one set of curly braces or square brackets (comments and line breaks allowed throughout). \end{itemize} See the \texttt{NamedGroupingBracesBrackets: follow} and \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{cmhtcbraster} \cmhlistingsfromfile{demonstrations/child1.tex}{\texttt{child1.tex}}{lst:child1} \cmhlistingsfromfile[showtabs=true]{demonstrations/child1-default.tex}{\texttt{child1.tex} default output}{lst:child1:default} \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 verify this by using the \texttt{-tt} option and checking \texttt{indent.log}! }. Referencing \cref{lst:child1:default}, note that the maximum indentation is two tabs, and these come from: \begin{itemize} \item the \lstinline!child!'s mandatory argument; \item the \lstinline!child!'s body, which is defined as any lines following the name of the \texttt{namedGroupingBracesBrackets} that include its arguments. This is the part controlled by the \emph{body} field for \texttt{noAdditionalIndent} and friends from \cpageref{sec:noadd-indent-rules}. \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: \begin{itemize} \item it must immediately follow either \lstinline!{! OR \lstinline![! OR \lstinline!,! OR \lstinline!&! OR \lstinline!)! OR \lstinline!(! OR \lstinline!$!; \item then at least one set of curly braces or square brackets (comments and line breaks allowed throughout). \end{itemize} 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{cmhtcbraster} \cmhlistingsfromfile{demonstrations/psforeach1.tex}{\texttt{psforeach1.tex}}{lst:psforeach1} \cmhlistingsfromfile[showtabs=true]{demonstrations/psforeach1-default.tex}{\texttt{psforeach1.tex} default output}{lst:psforeach:default} \end{cmhtcbraster} Referencing \cref{lst:psforeach:default}, there are \emph{three} sets of unnamed braces. Note also that the maximum value of indentation is three tabs, and these come from: \begin{itemize} \item the \lstinline!\psforeach! command's mandatory argument; \item the \emph{first} un-named braces mandatory argument; \item the \emph{first} un-named braces \emph{body}, which we define as any lines following the first opening \lstinline!{! or \lstinline![! that defined the code block. This is the part controlled by the \emph{body} field for \texttt{noAdditionalIndent} and friends from \cpageref{sec:noadd-indent-rules}. \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}. \paragraph{filecontents} code blocks behave just as \texttt{environments}, except that neither arguments nor items are sought. \subsubsection{Summary} \index{indentation!summary} Having considered all of the different types of code blocks, the functions of the fields given in \cref{lst:noAdditionalIndentGlobal,lst:indentRulesGlobal} should now make sense. \index{specialBeginEnd!noAdditionalIndentGlobal} \index{specialBeginEnd!indentRulesGlobal} \begin{widepage} \begin{minipage}{.47\linewidth} \cmhlistingsfromfile[style=noAdditionalIndentGlobal]{../defaultSettings.yaml}[before=\centering,yaml-TCB]{\texttt{noAdditionalIndentGlobal}}{lst:noAdditionalIndentGlobal} \end{minipage}% \hfill \begin{minipage}{.47\linewidth} \cmhlistingsfromfile[style=indentRulesGlobal]{../defaultSettings.yaml}[before=\centering,yaml-TCB]{\texttt{indentRulesGlobal}}{lst:indentRulesGlobal} \end{minipage}% \end{widepage} % arara: pdflatex: { files: [latexindent]} \subsection{Commands and the strings between their arguments}\label{subsec:commands-string-between} The \texttt{command} code blocks will always look for optional (square bracketed) and mandatory (curly braced) arguments which can contain comments, line breaks and `beamer' commands \lstinline!<.*?>! between them. There are switches that can allow them to contain other strings, which we discuss next. \yamltitle{commandCodeBlocks}*{fields} The \texttt{commandCodeBlocks} field \announce{2018-04-27}*{commandCodeBlocks} contains a few switches detailed in \cref{lst:commandCodeBlocks}.% \cmhlistingsfromfile[style=commandCodeBlocks]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{commandCodeBlocks}}{lst:commandCodeBlocks} \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{cmhtcbraster} \cmhlistingsfromfile{demonstrations/pstricks1.tex}{\texttt{pstricks1.tex}}{lst:pstricks1} \cmhlistingsfromfile{demonstrations/pstricks1-default.tex}{\texttt{pstricks1} default output}{lst:pstricks1-default} \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)$. By default, because \texttt{roundParenthesesAllowed} is set to $1$ in \cref{lst:commandCodeBlocks}, then \texttt{latexindent.pl} will allow round parenthesis between optional and mandatory arguments. In the case of the code in \cref{lst:pstricks1}, \texttt{latexindent.pl} finds \emph{all} the arguments of \lstinline!defFunction!, both before and after \lstinline!(u,v)!. The default output from running \texttt{latexindent.pl} on \cref{lst:pstricks1} actually leaves it unchanged (see \cref{lst:pstricks1-default}); note in particular, this is because of \texttt{noAdditionalIndentGlobal} as discussed on \cpageref{page:command:noAddGlobal}. 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] \cmhlistingsfromfile{demonstrations/pstricks1-nrp.tex}{\texttt{pstricks1.tex} using \cref{lst:noRoundParentheses}}{lst:pstricks1-nrp} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/noRoundParentheses.yaml}[yaml-TCB]{\texttt{noRoundParentheses.yaml}}{lst:noRoundParentheses} \end{cmhtcbraster} Notice the difference between \cref{lst:pstricks1-default} and \cref{lst:pstricks1-nrp}; in particular, in \cref{lst:pstricks1-nrp}, because round parentheses are \emph{not} allowed, \texttt{latexindent.pl} finds that the \lstinline!\defFunction! command finishes at the first opening round parenthesis. As such, the remaining braced, mandatory, arguments are found to be \texttt{UnNamedGroupingBracesBrackets} (see \vref{tab:code-blocks}) which, by default, assume indentation for their body, and hence the tabbed indentation in \cref{lst:pstricks1-nrp}. \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] \cmhlistingsfromfile[showspaces=true]{demonstrations/pstricks1-indent-rules.tex}{\texttt{pstricks1.tex} using \cref{lst:defFunction}}{lst:pstricks1-indent-rules} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/defFunction.yaml}[yaml-TCB]{\texttt{defFunction.yaml}}{lst:defFunction} \end{cmhtcbraster} Notice in \cref{lst:pstricks1-indent-rules} that the \emph{body} of the \lstinline!defFunction! command i.e, the subsequent lines containing arguments after the command name, have received the single space of indentation specified by \cref{lst:defFunction}. \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{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} to, node, ++ \end{quote} are all allowed to appear between arguments; importantly, you are encouraged to add further names to this field as necessary. This means that when \texttt{latexindent.pl} processes \cref{lst:tikz-node1}, it consumes: \begin{itemize} \item the optional argument \lstinline![thin]! \item the round-bracketed argument \lstinline!(c)! because \texttt{roundParenthesesAllowed} is $1$ by default \item the string \lstinline!to! (specified in \texttt{stringsAllowedBetweenArguments}) \item the optional argument \lstinline![in=110,out=-90]! \item the string \lstinline!++! (specified in \texttt{stringsAllowedBetweenArguments}) \item the round-bracketed argument \lstinline!(0,-0.5cm)! because \texttt{roundParenthesesAllowed} is $1$ by default \item the string \lstinline!node! (specified in \texttt{stringsAllowedBetweenArguments}) \item the 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] \cmhlistingsfromfile[showspaces=true]{demonstrations/tikz-node1-draw.tex}{\texttt{tikz-node1.tex} using \cref{lst:draw}}{lst:tikz-node1-draw} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/draw.yaml}[yaml-TCB]{\texttt{draw.yaml}}{lst:draw} \end{cmhtcbraster} Notice that each line after the \lstinline!\draw! command (its `body') in \cref{lst:tikz-node1-draw} has been given the appropriate two-spaces worth of indentation specified in \cref{lst:draw}. 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] \cmhlistingsfromfile{demonstrations/tikz-node1-no-strings.tex}{\texttt{tikz-node1.tex} using \cref{lst:no-strings}}{lst:tikz-node1-no-strings} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/no-strings.yaml}[yaml-TCB]{\texttt{no-strings.yaml}}{lst:no-strings} \end{cmhtcbraster} In this case, \texttt{latexindent.pl} sees that: \begin{itemize} \item the \lstinline!\draw! command finishes after the \lstinline!(c)!, as \texttt{stringsAllowedBetweenArguments} has been set to $0$ so there are no strings allowed between arguments; \item it finds a \texttt{namedGroupingBracesBrackets} called \texttt{to} (see \vref{tab:code-blocks}) \emph{with} argument \lstinline![in=110,out=-90]! \item it finds another \texttt{namedGroupingBracesBrackets} but this time called \texttt{node} with argument \lstinline![below,align=left,scale=0.5]! \end{itemize} \end{example} Referencing \vref{lst:commandCodeBlocks}, \announce{2018-04-27}*{amalgamate feature in commandCodeBlocks}, we see that the first field in the \texttt{stringsAllowedBetweenArguments} is \texttt{amalgamate} and is set to \texttt{1} by default. This is for users who wish to specify their settings in multiple YAML files. For example, by using the settings in either \cref{lst:amalgamate-demo} or\cref{lst:amalgamate-demo1} is equivalent to using the settings in \cref{lst:amalgamate-demo2}.% \begin{cmhtcbraster}[raster columns=3, raster left skip=-3.5cm, raster right skip=-2cm, raster column skip=.03\linewidth] \cmhlistingsfromfile[style=yaml-LST]{demonstrations/amalgamate-demo.yaml}[yaml-TCB]{\texttt{amalgamate-demo.yaml}}{lst:amalgamate-demo} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/amalgamate-demo1.yaml}[yaml-TCB]{\texttt{amalgamate-demo1.yaml}}{lst:amalgamate-demo1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/amalgamate-demo2.yaml}[yaml-TCB]{\texttt{amalgamate-demo2.yaml}}{lst:amalgamate-demo2} \end{cmhtcbraster} We specify \texttt{amalgamate} to be set to \texttt{0} and in which case any settings loaded prior to those specified, including the default, will be overwritten. For example, using the settings in \cref{lst:amalgamate-demo3} means that only the strings specified in that field will be used. \cmhlistingsfromfile[style=yaml-LST]{demonstrations/amalgamate-demo3.yaml}[yaml-TCB]{\texttt{amalgamate-demo3.yaml}}{lst:amalgamate-demo3} It is important to note that the \texttt{amalgamate} field, if used, must be in the first field, and specified using the syntax given in \cref{lst:amalgamate-demo1,lst:amalgamate-demo2,lst:amalgamate-demo3}. \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}. \begin{cmhtcbraster}[raster column skip=.1\linewidth] \cmhlistingsfromfile{demonstrations/for-each.tex}{\texttt{for-each.tex}}{lst:for-each} \cmhlistingsfromfile{demonstrations/for-each-default.tex}{\texttt{for-each} default output}{lst:for-each-default} \end{cmhtcbraster} 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] \cmhlistingsfromfile{demonstrations/for-each-mod1.tex}{\texttt{for-each.tex} using \cref{lst:foreach}}{lst:for-each-mod1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/foreach.yaml}[yaml-TCB]{\texttt{foreach.yaml}}{lst:foreach} \end{cmhtcbraster} You might like to compare the output given in \cref{lst:for-each-default} and \cref{lst:for-each-mod1}. Note,in particular, in \cref{lst:for-each-default} that the \texttt{foreach} command has not included any of the subsequent strings, and that the braces have been treated as a \texttt{namedGroupingBracesBrackets}. In \cref{lst:for-each-mod1} the \texttt{foreach} command has been allowed to have \lstinline!\x/\y! and \texttt{in} between arguments because of the settings given in \cref{lst:foreach}. \end{example} \yamltitle{commandNameSpecial}*{fields} There are some special command names \announce{2018-04-27}*{commandNameSpecial} that do not fit within the names recognised by \texttt{latexindent.pl}, the first one of which is \lstinline!\@ifnextchar[!. From the perspective of \texttt{latexindent.pl}, the whole of the text \lstinline!\@ifnextchar[! is a command, because it is immediately followed by sets of mandatory arguments. However, without the \texttt{commandNameSpecial} field, \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}. \begin{cmhtcbraster}[raster column skip=.1\linewidth] \cmhlistingsfromfile{demonstrations/ifnextchar.tex}{\texttt{ifnextchar.tex}}{lst:ifnextchar} \cmhlistingsfromfile{demonstrations/ifnextchar-default.tex}{\texttt{ifnextchar.tex} default output}{lst:ifnextchar-default} \end{cmhtcbraster} Notice that in \cref{lst:ifnextchar-default} the \texttt{parbox} command has been able to indent its body, because \texttt{latexindent.pl} has successfully found the command \lstinline!\@ifnextchar! first; the pattern-matching of \texttt{latexindent.pl} starts from \emph{the inner most <thing> and works outwards}, discussed in more detail on \cpageref{page:phases}. For demonstration, we can compare this output with that given in \cref{lst:ifnextchar-off} in which the settings from \cref{lst:no-ifnextchar} have dictated that no special command names, including the \lstinline!\@ifnextchar[! command, should not be searched for specially; as such, the \texttt{parbox} command has been \emph{unable} to indent its body successfully, because the \lstinline!\@ifnextchar[! command has not been found. \begin{cmhtcbraster}[raster column skip=.1\linewidth] \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, which we state again here: \index{warning!amalgamate field} \begin{warning} It is important to note that the \texttt{amalgamate} field, if used, in either \texttt{commandNameSpecial} or \texttt{stringsAllowedBetweenArguments} must be in the first field, and specified using the syntax given in \cref{lst:amalgamate-demo1,lst:amalgamate-demo2,lst:amalgamate-demo3}. \end{warning} % arara: pdflatex: { files: [latexindent]} \renewcommand{\imagetouse}{logo} \section{The -m (modifylinebreaks) switch}\label{sec:modifylinebreaks} \fancyhead[R]{\bfseries\thepage% \tikz[remember picture,overlay] { \node at (1,0){\includegraphics{logo}}; }} All features described in this section will only be relevant if the \texttt{-m} switch is used. \startcontents[the-m-switch] \printcontents[the-m-switch]{}{0}{} \yamltitle{modifylinebreaks}*{fields} \makebox[0pt][r]{% \raisebox{-\totalheight}[0pt][0pt]{% \tikz\node[opacity=1] at (0,0) {\includegraphics[width=4cm]{logo}};}}% As of Version 3.0, \texttt{latexindent.pl} has the \texttt{-m} switch, which permits \texttt{latexindent.pl} to modify line breaks, according to the specifications in the \texttt{modifyLineBreaks} field. \emph{The settings in this field will only be considered if the \texttt{-m} switch has been used}. A snippet of the default settings of this field is shown in \cref{lst:modifylinebreaks}. \cmhlistingsfromfile[style=modifylinebreaks]{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{modifyLineBreaks}}{lst:modifylinebreaks} Having read the previous paragraph, it should sound reasonable that, if you call \texttt{latexindent.pl} using the \texttt{-m} switch, then you give it permission to modify line breaks in your file, but let's be clear: \index{warning!the m switch} \begin{warning} If you call \texttt{latexindent.pl} with the \texttt{-m} switch, then you are giving it permission to modify line breaks. By default, the only thing that will happen is that multiple blank lines will be condensed into one blank line; many other settings are possible, discussed next. \end{warning} \yamltitle{preserveBlankLines}{0|1} This field is directly related to \emph{poly-switches}, discussed in \cref{sec:poly-switches}. By default, it is set to \texttt{1}, which means that blank lines will be \emph{protected} from removal; however, regardless of this setting, multiple blank lines can be condensed if \texttt{condenseMultipleBlankLinesInto} is greater than \texttt{0}, discussed next. \yamltitle{condenseMultipleBlankLinesInto}*{positive integer} Assuming that this switch takes an integer value greater than \texttt{0}, \texttt{latexindent.pl} will condense multiple blank lines into the number of blank lines illustrated by this switch. \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! \begin{cmhtcbraster} \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 of V3.16; I hope that the interface is simpler, and most importantly, the results are better}. The complete settings for this feature are given in \cref{lst:textWrapOptionsAll}. \cmhlistingsfromfile[style=textWrapOptionsAll]{../defaultSettings.yaml}[MLB-TCB,width=.95\linewidth,before=\centering]{\texttt{textWrapOptions}}{lst:textWrapOptionsAll} \subsubsection{Text wrap: overview} An overview of how the text wrapping feature works: \begin{enumerate} \item the default value of \texttt{columns} is 0, which means that text wrapping will \emph{not} happen by default; \item it happens \emph{after} verbatim blocks have been found; \item it happens \emph{after} the oneSentencePerLine routine (see \cref{sec:onesentenceperline}); \item it can happen \emph{before} or \emph{after} \announce{2023-01-01}{text wrap: before/after} all of the other code blocks are found and does \emph{not} operate on a per-code-block basis; when using \texttt{before} this means that, including indentation, you may receive a column width wider than that which you specify in \texttt{columns}, and in which case you probably wish to explore \texttt{after} in \cref{subsubsec:tw:before:after}; \item code blocks to be text wrapped will: \begin{enumerate} \item \emph{follow} the fields specified in \texttt{blocksFollow} \item \emph{begin} with the fields specified in \texttt{blocksBeginWith} \item \emph{end} before the fields specified in \texttt{blocksEndBefore} \end{enumerate} \item setting \texttt{columns} to a value $>0$ will text wrap blocks by first removing line breaks, and then wrapping according to the specified value of \texttt{columns}; \item setting \texttt{columns} to $-1$ will \emph{only} remove line breaks within the text wrap block; \item by default, the text wrapping routine will remove line breaks within text blocks because \texttt{removeBlockLineBreaks} is set to 1; switch it to 0 if you wish to change this; \item about trailing comments within text wrap blocks: \begin{enumerate} \item trailing comments that do \emph{not} have leading space instruct the text wrap routine to connect the lines \emph{without} space (see \cref{lst:tw-tc2}); \item multiple trailing comments will be connected at the end of the text wrap block (see \cref{lst:tw-tc4}); \item the number of spaces between the end of the text wrap block and the (possibly combined) trailing comments is determined by the spaces (if any) at the end of the text wrap block (see \cref{lst:tw-tc5}); \end{enumerate} \item trailing comments can receive text wrapping \announce{2023-01-01}{text wrap trailing comments}; examples are shown in \cref{subsubsec:tw:comments} and \cref{subsubsec:ospl:tw:comments}. \end{enumerate} We demonstrate this feature using a series of examples. \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} \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} 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[style=yaml-LST]{demonstrations/textwrap1.yaml}[MLB-TCB]{\texttt{textwrap1.yaml}}{lst:textwrap1-yaml} \end{cmhtcbraster} \end{example} \begin{example} If we set \texttt{columns} to $-1$ then \texttt{latexindent.pl} remove line breaks within the text wrap block, and will \emph{not} perform text wrapping. We can use this to undo text wrapping. \index{text wrap!setting columns to -1} Starting from the file in \cref{lst:textwrap1-mod1} and using the settings in \cref{lst:textwrap1A-yaml} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/textwrap1A.yaml}[MLB-TCB]{\texttt{textwrap1A.yaml}}{lst:textwrap1A-yaml} 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} \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} 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[showspaces=true]{demonstrations/textwrap1-mod1B.tex}{\texttt{textwrap1-mod1B.tex}}{lst:textwrap1-mod1B} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/textwrap1B.yaml}[MLB-TCB]{\texttt{textwrap1B.yaml}}{lst:textwrap1B-yaml} \end{cmhtcbraster} We note that in \cref{lst:textwrap1-mod1B} the multiple spaces have \emph{not} been condensed into single spaces. \end{example} \subsubsection{Text wrap: \texttt{blocksFollow} examples} We examine the \texttt{blocksFollow} field of \cref{lst:textWrapOptionsAll}. \index{text wrap!blocksFollow} \begin{example} 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} 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} 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} \cmhlistingsfromfile{demonstrations/tw-headings1-mod2.tex}{\texttt{tw-headings1-mod2.tex}}{lst:tw-headings1-mod2} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/bf-no-headings.yaml}[MLB-TCB]{\texttt{bf-no-headings.yaml}}{lst:bf-no-headings-yaml} \end{cmhtcbraster} \end{example} \begin{example} 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} 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} 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/tw-comments1-mod2.tex}{\texttt{tw-comments1-mod2.tex}}{lst:tw-comments1-mod2} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/bf-no-comments.yaml}[MLB-TCB]{\texttt{bf-no-comments.yaml}}{lst:bf-no-comments-yaml} \end{cmhtcbraster} \end{example} Referencing \vref{lst:textWrapOptionsAll} the \texttt{blocksFollow} fields \texttt{par}, \texttt{blankline}, \texttt{verbatim} and \texttt{filecontents} fields operate in analogous ways to those demonstrated in the above. The \texttt{other} field of the \texttt{blocksFollow} can either be \texttt{0} (turned off) or set as a regular expression. The default value is set to \lstinline!\\\]|\\item(?:\h|\[)! which can be translated to \emph{backslash followed by a square bracket} or \emph{backslash item followed by horizontal space or a square 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} \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} 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} 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/tw-disp-math1-mod2.tex}{\texttt{tw-disp-math1-mod2.tex}}{lst:tw-disp-math1-mod2} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/bf-no-disp-math.yaml}[MLB-TCB]{\texttt{bf-no-disp-math.yaml}}{lst:bf-no-disp-math-yaml} \end{cmhtcbraster} Naturally, you should feel encouraged to customise this as you see fit. \end{example} The \texttt{blocksFollow} field \emph{deliberately} does not default to allowing text wrapping to occur after \texttt{begin environment} statements. You are encouraged to customize the \texttt{other} field to accommodate the environments that you would like to 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} \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} 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} 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=.01\linewidth, raster left skip=-1.5cm, raster force size=false, raster column 1/.style={add to width=-.1\textwidth}, raster column 2/.style={add to width=.1\textwidth}, ] \cmhlistingsfromfile{demonstrations/tw-bf-myenv1-mod2.tex}{\texttt{tw-bf-myenv1-mod2.tex}}{lst:tw-bf-myenv1-mod2} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/tw-bf-myenv.yaml}[MLB-TCB,width=0.6\linewidth]{\texttt{tw-bf-myenv.yaml}}{lst:tw-bf-myenv-yaml} \end{cmhtcbraster} \end{example} \subsubsection{Text wrap: \texttt{blocksBeginWith} examples} We examine the \texttt{blocksBeginWith} field of \cref{lst:textWrapOptionsAll} with a 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}. 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} occurred. \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/tw-0-9-mod2.tex}{\texttt{tw-0-9-mod2.tex}}{lst:tw-0-9-mod2} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/bb-0-9.yaml}[MLB-TCB]{\texttt{bb-0-9.yaml.yaml}}{lst:bb-0-9-yaml} \end{cmhtcbraster} \end{example} \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} 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} occurred. \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-announce1-mod2.tex}{\texttt{tw-bb-announce1-mod2.tex}}{lst:tw-bb-announce1-mod2} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/tw-bb-announce.yaml}[MLB-TCB]{\texttt{tw-bb-announce.yaml}}{lst:tw-bb-announce-yaml} \end{cmhtcbraster} \end{example} \subsubsection{Text wrap: \texttt{blocksEndBefore} examples} We examine the \texttt{blocksEndBefore} field of \cref{lst:textWrapOptionsAll} with a 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} \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} 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} 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[style=yaml-LST]{demonstrations/tw-be-equation.yaml}[MLB-TCB]{\texttt{tw-be-equation.yaml}}{lst:tw-be-equation-yaml} \begin{widepage} \cmhlistingsfromfile{demonstrations/tw-be-equation-mod2.tex}{\texttt{tw-be-equation-mod2.tex}}{lst:tw-be-equation-mod2} \end{widepage} Naturally, you should feel encouraged to customise this as you see fit. \end{example} \subsubsection{Text wrap: trailing comments and spaces} We explore the behaviour of the text wrap routine in relation to trailing comments using 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. 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} \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. 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. \end{example} \begin{example} The file in \cref{lst:tw-tc3} contains multiple trailing comments. 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} \end{example} \begin{example} The file in \cref{lst:tw-tc4} contains multiple trailing comments. 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} \end{example} \begin{example} The file in \cref{lst:tw-tc5} contains multiple trailing comments. 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. \end{example} \begin{example} The file in \cref{lst:tw-tc6} contains multiple trailing comments. 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. \end{example} \subsubsection{Text wrap: when before/after}\label{subsubsec:tw:before:after} The text wrapping routine operates, by default, \texttt{before} the \announce{2023-01-01}{text wrap: before/after details} code blocks have been found, but this can be changed to \texttt{after}: \begin{itemize} \item \texttt{before} means it is likely that the columns of wrapped text may \emph{exceed} the value specified in \texttt{columns}; \item \texttt{after} means it columns of wrapped text should \emph{not} exceed the value specified in \texttt{columns}. \end{itemize} We demonstrate this in the following examples. See also \cref{subsubsec:ospl:before:after}. \begin{example} Let's begin with the file in \cref{lst:textwrap8}. \cmhlistingsfromfile{demonstrations/textwrap8.tex}{\texttt{textwrap8.tex}}{lst:textwrap8} Using the settings given in \cref{lst:tw-before1} and running the command \begin{commandshell} latexindent.pl textwrap8.tex -o=+-mod1.tex -l=tw-before1.yaml -m \end{commandshell} gives the output given in \cref{lst:textwrap8-mod1}. \begin{cmhtcbraster}[raster columns=2, raster left skip=-1.5cm, raster right skip=-0cm, raster column skip=.06\linewidth] \cmhlistingsfromfile{demonstrations/textwrap8-mod1.tex}{\texttt{textwrap8-mod1.tex}}{lst:textwrap8-mod1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/tw-before1.yaml}[MLB-TCB,width=0.4\linewidth]{\texttt{tw-before1.yaml}}{lst:tw-before1} \end{cmhtcbraster} We note that, in \cref{lst:textwrap8-mod1}, that the wrapped text has \emph{exceeded} the specified value of \texttt{columns} (35) given in \cref{lst:tw-before1}. We can affect this by changing \texttt{when}; we explore this next. \end{example} \begin{example} We continue working with \cref{lst:textwrap8}. Using the settings given in \cref{lst:tw-after1} and running the command \begin{commandshell} latexindent.pl textwrap8.tex -o=+-mod2.tex -l=tw-after1.yaml -m \end{commandshell} gives the output given in \cref{lst:textwrap8-mod2}. \begin{cmhtcbraster}[raster columns=2, raster left skip=-1.5cm, raster right skip=-0cm, raster column skip=.06\linewidth] \cmhlistingsfromfile{demonstrations/textwrap8-mod2.tex}{\texttt{textwrap8-mod2.tex}}{lst:textwrap8-mod2} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/tw-after1.yaml}[MLB-TCB,width=0.4\linewidth]{\texttt{tw-after1.yaml}}{lst:tw-after1} \end{cmhtcbraster} We note that, in \cref{lst:textwrap8-mod2}, that the wrapped text has \emph{obeyed} the specified value of \texttt{columns} (35) given in \cref{lst:tw-after1}. \end{example} \subsubsection{Text wrap: wrapping comments}\label{subsubsec:tw:comments} You can instruct \texttt{latexindent.pl} to apply text wrapping to comments \announce{2023-01-01}{text wrap trailing comments}; we demonstrate this with examples, see also \cref{subsubsec:ospl:tw:comments}. \index{comments!text wrap} \index{text wrap!comments} \begin{example} We use the file in \cref{lst:textwrap9} which contains a trailing comment block. \cmhlistingsfromfile{demonstrations/textwrap9.tex}{\texttt{textwrap9.tex}}{lst:textwrap9} Using the settings given in \cref{lst:wrap-comments1} and running the command \begin{commandshell} latexindent.pl textwrap9.tex -o=+-mod1.tex -l=wrap-comments1.yaml -m \end{commandshell} gives the output given in \cref{lst:textwrap9-mod1}. \begin{cmhtcbraster}[raster columns=2, raster left skip=-1.5cm, raster right skip=-0cm, raster column skip=.06\linewidth] \cmhlistingsfromfile{demonstrations/textwrap9-mod1.tex}{\texttt{textwrap9-mod1.tex}}{lst:textwrap9-mod1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/wrap-comments1.yaml}[MLB-TCB,width=0.4\linewidth]{\texttt{wrap-comments1.yaml}}{lst:wrap-comments1} \end{cmhtcbraster} We note that, in \cref{lst:textwrap9-mod1}, that the comments have been \emph{combined and wrapped} because of the annotated line specified in \cref{lst:wrap-comments1}. \end{example} \begin{example} We use the file in \cref{lst:textwrap10} which contains a trailing comment block. \cmhlistingsfromfile{demonstrations/textwrap10.tex}{\texttt{textwrap10.tex}}{lst:textwrap10} Using the settings given in \cref{lst:wrap-comments1:repeat} and running the command \begin{commandshell} latexindent.pl textwrap10.tex -o=+-mod1.tex -l=wrap-comments1.yaml -m \end{commandshell} gives the output given in \cref{lst:textwrap10-mod1}. \begin{cmhtcbraster}[raster columns=2, raster left skip=-1.5cm, raster right skip=-0cm, raster column skip=.06\linewidth] \cmhlistingsfromfile{demonstrations/textwrap10-mod1.tex}{\texttt{textwrap10-mod1.tex}}{lst:textwrap10-mod1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/wrap-comments1.yaml}[MLB-TCB,width=0.4\linewidth]{\texttt{wrap-comments1.yaml}}{lst:wrap-comments1:repeat} \end{cmhtcbraster} We note that, in \cref{lst:textwrap10-mod1}, that the comments have been \emph{combined and wrapped} because of the annotated line specified in \cref{lst:wrap-comments1:repeat}, and that the space from the leading comment has not been inherited; we will explore this further in the next example. \end{example} \begin{example} We continue to use the file in \cref{lst:textwrap10}. Using the settings given in \cref{lst:wrap-comments2} and running the command \begin{commandshell} latexindent.pl textwrap10.tex -o=+-mod2.tex -l=wrap-comments2.yaml -m \end{commandshell} gives the output given in \cref{lst:textwrap10-mod2}. \begin{cmhtcbraster}[raster columns=2, raster left skip=-1.5cm, raster right skip=-0cm, raster column skip=.06\linewidth] \cmhlistingsfromfile{demonstrations/textwrap10-mod2.tex}{\texttt{textwrap10-mod2.tex}}{lst:textwrap10-mod2} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/wrap-comments2.yaml}[MLB-TCB,width=0.4\linewidth]{\texttt{wrap-comments2.yaml}}{lst:wrap-comments2} \end{cmhtcbraster} We note that, in \cref{lst:textwrap10-mod2}, that the comments have been \emph{combined and wrapped} and that the leading space has been inherited because of the annotated lines specified in \cref{lst:wrap-comments2}. \end{example} \subsubsection{Text wrap: huge, tabstop and separator} The \announce{2021-07-23}*{huge:overflow is now default} default value of \texttt{huge} is \texttt{overflow}, which means that words will \emph{not} be broken by the text wrapping routine, implemented by the \texttt{Text::Wrap} \cite{textwrap}. There are options to change the \texttt{huge} option for the \texttt{Text::Wrap} module to either \texttt{wrap} or \texttt{die}. Before modifying the value of \texttt{huge}, please bear in mind the following warning: \index{warning!changing huge (textwrap)}% \begin{warning} \raggedright Changing the value of \texttt{huge} to anything other than \texttt{overflow} will slow down \texttt{latexindent.pl} significantly when the \texttt{-m} switch is active. Furthermore, changing \texttt{huge} means that you may have some words \emph{or commands}(!) split across lines in your .tex file, which may affect your output. I do not recommend changing this field. \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] \cmhlistingsfromfile{demonstrations/textwrap4-mod2A.tex}{\texttt{textwrap4-mod2A.tex}}{lst:textwrap4-mod2A} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/textwrap2A.yaml}[MLB-TCB]{\texttt{textwrap2A.yaml}}{lst:textwrap2A-yaml} \cmhlistingsfromfile{demonstrations/textwrap4-mod2B.tex}{\texttt{textwrap4-mod2B.tex}}{lst:textwrap4-mod2B} \cmhlistingsfromfile[style=yaml-LST]{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. \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, raster right skip=-2cm, raster column skip=.03\linewidth] \cmhlistingsfromfile[showtabs=true]{demonstrations/textwrap-ts.tex}{\texttt{textwrap-ts.tex}}{lst:textwrap-ts} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/tabstop.yaml}[MLB-TCB]{\texttt{tabstop.yaml}}{lst:tabstop} \cmhlistingsfromfile[showtabs=true]{demonstrations/textwrap-ts-mod1.tex}{\texttt{textwrap-ts-mod1.tex}}{lst:textwrap-ts-mod1} \end{cmhtcbraster} \end{example} You can specify \texttt{separator}, \texttt{break} and \texttt{unexpand} options in your settings in analogous ways to those demonstrated in \cref{lst:textwrap2B-yaml,lst:tabstop}, and they will be passed to the \texttt{Text::Wrap} module. I have not found a useful reason to do this; see \cite{textwrap} for more details. % arara: pdflatex: { files: [latexindent]} \subsection{oneSentencePerLine: modifying line breaks for sentences}\label{sec:onesentenceperline} You can instruct \texttt{latexindent.pl} to format \announce{2018-01-13}{one sentence per line} your file so that it puts one sentence per line. Thank you to \cite{mlep} for helping to shape and test this feature. The behaviour of this part of the script is controlled by the switches detailed in \cref{lst:oneSentencePerLine}, all of which we discuss next. \index{modifying linebreaks! by using one sentence per line} \index{sentences!oneSentencePerLine} \index{sentences!one sentence per line} \index{regular expressions!lowercase alph a-z} \index{regular expressions!uppercase alph A-Z}% \cmhlistingsfromfile[style=oneSentencePerLine]{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{oneSentencePerLine}}{lst:oneSentencePerLine} \subsubsection{oneSentencePerLine: overview} An overview of how the oneSentencePerLine routine feature works: \begin{enumerate} \item the default value of \texttt{manipulateSentences} is 0, which means that oneSentencePerLine will \emph{not} happen by default; \item it happens \emph{after} verbatim blocks have been found; \item it happens \emph{before} the text wrapping routine (see \cref{subsec:textwrapping}); \item it happens \emph{before} the main code blocks have been found; \item sentences to be found: \begin{enumerate} \item \emph{follow} the fields specified in \texttt{sentencesFollow} \item \emph{begin} with the fields specified in \texttt{sentencesBeginWith} \item \emph{end} with the fields specified in \texttt{sentencesEndWith} \end{enumerate} \item by default, the oneSentencePerLine routine will remove line breaks within sentences because \texttt{removeBlockLineBreaks} is set to 1; switch it to 0 if you wish to change this; \item sentences can be text wrapped according to \texttt{textWrapSentences}, and will be done either \texttt{before} or \texttt{after} the main indentation routine (see \cref{subsubsec:ospl:before:after}); \item about trailing comments within text wrap blocks: \begin{enumerate} \item multiple trailing comments will be connected at the end of the sentence; \item the number of spaces between the end of the sentence and the (possibly combined) trailing comments is determined by the spaces (if any) at the end of the sentence. \end{enumerate} \end{enumerate} We demonstrate this feature using a series of examples. \yamltitle{manipulateSentences}{0|1} This is a binary switch that details if \texttt{latexindent.pl} should perform the sentence manipulation routine; it is \emph{off} (set to \texttt{0}) by default, and you will need to turn it on (by setting it to \texttt{1}) if you want the script to modify line breaks surrounding and within sentences. \yamltitle{removeSentenceLineBreaks}{0|1} When operating upon sentences \texttt{latexindent.pl} will, by default, remove internal line breaks as \texttt{removeSentenceLineBreaks} is set to \texttt{1}. Setting this switch to \texttt{0} instructs \texttt{latexindent.pl} not to do so. \index{sentences!removing sentence line breaks} \begin{example} For example, consider \texttt{multiple-sentences.tex} shown in \cref{lst:multiple-sentences}. \cmhlistingsfromfile{demonstrations/multiple-sentences.tex}{\texttt{multiple-sentences.tex}}{lst:multiple-sentences} If we use the YAML files in \cref{lst:manipulate-sentences-yaml,lst:keep-sen-line-breaks-yaml}, and run the commands \index{switches!-l demonstration} \index{switches!-m demonstration} \begin{widepage} \begin{commandshell} latexindent.pl multiple-sentences -m -l=manipulate-sentences.yaml 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}. \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/multiple-sentences-mod1.tex}{\texttt{multiple-sentences.tex} using \cref{lst:manipulate-sentences-yaml}}{lst:multiple-sentences-mod1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/manipulate-sentences.yaml}[MLB-TCB]{\texttt{manipulate-sentences.yaml}}{lst:manipulate-sentences-yaml} \end{cmhtcbraster} \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/multiple-sentences-mod2.tex}{\texttt{multiple-sentences.tex} using \cref{lst:keep-sen-line-breaks-yaml}}{lst:multiple-sentences-mod2} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/keep-sen-line-breaks.yaml}[MLB-TCB]{\texttt{keep-sen-line-breaks.yaml}}{lst:keep-sen-line-breaks-yaml} \end{cmhtcbraster} 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 one-sentence-per-line routine will convert multiple spaces into single spaces. You can change this behaviour by changing the switch \texttt{multipleSpacesToSingle} to a value of \texttt{0}. The remainder of the settings displayed in \vref{lst:oneSentencePerLine} instruct \texttt{latexindent.pl} on how to define a sentence. From the perspective of \texttt{latexindent.pl} a sentence must: \index{sentences!follow} \index{sentences!begin with} \index{sentences!end with} \begin{itemize} \item \emph{follow} a certain character or set of characters (see \cref{lst:sentencesFollow}); by default, this is either \lstinline!\par!, a blank line, a full stop/period (.), exclamation mark (!), question mark (?) right brace (\}) or a comment on the previous line; \item \emph{begin} with a character type (see \cref{lst:sentencesBeginWith}); by default, this is only capital letters; \item \emph{end} with a character (see \cref{lst:sentencesEndWith}); by default, these are full stop/period (.), exclamation mark (!) and question mark (?). \end{itemize} In each case, you can specify the \texttt{other} field to include any pattern that you would like; you can specify anything in this field using the language of regular expressions. \index{regular expressions!lowercase alph a-z} \index{regular expressions!uppercase alph A-Z} \begin{cmhtcbraster}[raster columns=2, raster left skip=-3.5cm, raster right skip=-2cm, raster column skip=.06\linewidth] \cmhlistingsfromfile[style=sentencesFollow]{../defaultSettings.yaml}[MLB-TCB,width=.9\linewidth,before=\centering]{\texttt{sentencesFollow}}{lst:sentencesFollow} \cmhlistingsfromfile[style=sentencesBeginWith]{../defaultSettings.yaml}[MLB-TCB,width=.9\linewidth,before=\centering]{\texttt{sentencesBeginWith}}{lst:sentencesBeginWith} \end{cmhtcbraster} \cmhlistingsfromfile[style=sentencesEndWith]{../defaultSettings.yaml}[MLB-TCB,width=.9\linewidth,before=\centering]{\texttt{sentencesEndWith}}{lst:sentencesEndWith} \subsubsection{oneSentencePerLine: sentencesFollow} Let's explore a few of the switches in \texttt{sentencesFollow}. \begin{example} 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} \cmhlistingsfromfile{demonstrations/multiple-sentences-mod3.tex}{\texttt{multiple-sentences.tex} using \cref{lst:sentences-follow1-yaml}}{lst:multiple-sentences-mod3} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/sentences-follow1.yaml}[MLB-TCB]{\texttt{sentences-follow1.yaml}}{lst:sentences-follow1-yaml} \end{cmhtcbraster} 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}. \cmhlistingsfromfile{demonstrations/multiple-sentences1.tex}{\texttt{multiple-sentences1.tex}}{lst:multiple-sentences1} Upon running the following commands \index{switches!-l demonstration} \index{switches!-m demonstration} \begin{widepage} \begin{commandshell} latexindent.pl multiple-sentences1 -m -l=manipulate-sentences.yaml 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}. \cmhlistingsfromfile{demonstrations/multiple-sentences1-mod1.tex}{\texttt{multiple-sentences1.tex} using \vref{lst:manipulate-sentences-yaml}}{lst:multiple-sentences1-mod1} \begin{cmhtcbraster}[ raster force size=false, raster column 1/.style={add to width=1cm}, ] \cmhlistingsfromfile{demonstrations/multiple-sentences1-mod2.tex}{\texttt{multiple-sentences1.tex} using \cref{lst:sentences-follow2-yaml}}{lst:multiple-sentences1-mod2} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/sentences-follow2.yaml}[MLB-TCB,width=.45\textwidth]{\texttt{sentences-follow2.yaml}}{lst:sentences-follow2-yaml} \end{cmhtcbraster} Notice that in \cref{lst:multiple-sentences1-mod1} the first sentence after the \texttt{)} has not been accounted for, but that following the inclusion of \cref{lst:sentences-follow2-yaml}, the output given in \cref{lst:multiple-sentences1-mod2} demonstrates that the sentence \emph{has} been accounted for correctly. \end{example} \subsubsection{oneSentencePerLine: sentencesBeginWith} By default, \texttt{latexindent.pl} will only assume that sentences begin with the upper case letters \texttt{A-Z}; you can instruct the script to define sentences to begin with lower case letters (see \cref{lst:sentencesBeginWith}), and we can use the \texttt{other} field to define sentences to begin with other characters. \index{sentences!begin with} \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}. \cmhlistingsfromfile{demonstrations/multiple-sentences2-mod1.tex}{\texttt{multiple-sentences2.tex} using \vref{lst:manipulate-sentences-yaml}}{lst:multiple-sentences2-mod1} \index{regular expressions!numeric 0-9} \begin{cmhtcbraster}[ raster force size=false, raster column 1/.style={add to width=1cm}, ] \cmhlistingsfromfile{demonstrations/multiple-sentences2-mod2.tex}{\texttt{multiple-sentences2.tex} using \cref{lst:sentences-begin1-yaml}}{lst:multiple-sentences2-mod2} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/sentences-begin1.yaml}[MLB-TCB,width=.45\textwidth]{\texttt{sentences-begin1.yaml}}{lst:sentences-begin1-yaml} \end{cmhtcbraster} Notice that in \cref{lst:multiple-sentences2-mod1}, the first sentence has been accounted for but that the subsequent sentences have not. In \cref{lst:multiple-sentences2-mod2}, all of the sentences have been accounted for, because the \texttt{other} field in \cref{lst:sentences-begin1-yaml} has defined sentences to begin with either \lstinline!$! or any numeric digit, \texttt{0} to \texttt{9}. \end{example} \subsubsection{oneSentencePerLine: sentencesEndWith} \begin{example} Let's return to \vref{lst:multiple-sentences}; we have already seen the default way in which \texttt{latexindent.pl} will operate on the sentences in this file in \vref{lst:multiple-sentences-mod1}. We can populate the \texttt{other} field with any character that we wish; for example, using the YAML specified in \cref{lst:sentences-end1-yaml} and the command \index{sentences!end with} \index{switches!-l demonstration} \index{switches!-m demonstration} \begin{commandshell} latexindent.pl multiple-sentences -m -l=sentences-end1.yaml latexindent.pl multiple-sentences -m -l=sentences-end2.yaml \end{commandshell} then we obtain the output in \cref{lst:multiple-sentences-mod4}. \index{regular expressions!lowercase alph a-z} \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/multiple-sentences-mod4.tex}{\texttt{multiple-sentences.tex} using \cref{lst:sentences-end1-yaml}}{lst:multiple-sentences-mod4} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/sentences-end1.yaml}[MLB-TCB]{\texttt{sentences-end1.yaml}}{lst:sentences-end1-yaml} \end{cmhtcbraster} \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/multiple-sentences-mod5.tex}{\texttt{multiple-sentences.tex} using \cref{lst:sentences-end2-yaml}}{lst:multiple-sentences-mod5} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/sentences-end2.yaml}[MLB-TCB]{\texttt{sentences-end2.yaml}}{lst:sentences-end2-yaml} \end{cmhtcbraster} There is a subtle difference between the output in \cref{lst:multiple-sentences-mod4,lst:multiple-sentences-mod5}; in particular, in \cref{lst:multiple-sentences-mod4} the word \texttt{sentence} has not been defined as a sentence, because we have not instructed \texttt{latexindent.pl} to begin sentences with lower case letters. We have changed this by using the settings in \cref{lst:sentences-end2-yaml}, and the associated output in \cref{lst:multiple-sentences-mod5} reflects this. \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} 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} Notice that the full stop within the url has been interpreted correctly. This is because, within the \texttt{betterFullStop}, full stops at the end of sentences have the following properties: \begin{itemize} \item they are ignored within \texttt{e.g.} and \texttt{i.e.}; \item they can not be immediately followed by a lower case or upper case letter; \item they can not be immediately followed by a hyphen, comma, or number. \end{itemize} \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 seek to customise the \texttt{betterFullStop} routine by using the \emph{fine tuning}, detailed in \vref{lst:fineTuning}.% The \texttt{basicFullStop} routine should probably be avoided in most situations, as it 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, raster right skip=-2cm, raster force size=false, raster column 1/.style={add to width=.1\textwidth}, raster column skip=.06\linewidth] \cmhlistingsfromfile{demonstrations/url-mod2.tex}{\texttt{url.tex} using \cref{lst:alt-full-stop1-yaml}}{lst:url-mod2} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/alt-full-stop1.yaml}[MLB-TCB,width=.5\textwidth]{\texttt{alt-full-stop1.yaml}}{lst:alt-full-stop1-yaml} \end{cmhtcbraster} 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{oneSentencePerLine: sentencesDoNOTcontain} You can specify patterns that sentences do \emph{not} contain using the field \announce{2023-09-09}{oneSentencePerLine: sentencesDoNOTcontain} in \cref{lst:sentencesDoNOTcontain}. \cmhlistingsfromfile[style=sentencesDoNOTcontain]{../defaultSettings.yaml}[MLB-TCB,width=.9\linewidth,before=\centering]{\texttt{sentencesDoNOTcontain}}{lst:sentencesDoNOTcontain} If sentences run across environments then, by default, they will \emph{not} be considered a sentence by \texttt{latexindent.pl}. \announce{2023-09-09}*{updated example of oneSentencePerLine} \begin{example} For example, if we use the \texttt{.tex} file in \cref{lst:multiple-sentences4} \cmhlistingsfromfile{demonstrations/multiple-sentences4.tex}{\texttt{multiple-sentences4.tex}}{lst:multiple-sentences4} and run the command \index{switches!-l demonstration} \index{switches!-m demonstration} \begin{commandshell} latexindent.pl multiple-sentences4 -m -l=manipulate-sentences.yaml \end{commandshell} then the output is unchanged, because the default value of \texttt{sentencesDoNOTcontain} says, \emph{sentences do NOT contain} This means that, by default, \texttt{latexindent.pl} does \emph{not} consider the file in \cref{lst:multiple-sentences4} to have a sentence. \lstinline!\\begin! \end{example} \begin{example} We can customise the \texttt{sentencesDoNOTcontain} field with anything that we do \emph{not} want sentences to contain. We begin with the file in \cref{lst:sentence-dnc1}. \cmhlistingsfromfile{demonstrations/sentence-dnc1.tex}{\texttt{sentence-dnc1.tex}}{lst:sentence-dnc1} Upon running the following commands \begin{commandshell} latexindent.pl sentence-dnc1.tex -m -l=dnc1.yaml \end{commandshell} then we obtain the output given in \cref{lst:sentence-dnc1-mod1}. \begin{cmhtcbraster}[ raster left skip=-2.5cm, raster right skip=-1cm, raster force size=false, raster column 1/.style={add to width=3cm}, ] \cmhlistingsfromfile{demonstrations/sentence-dnc1-mod1.tex}{\texttt{sentence-dnc1-mod1.tex}}{lst:sentence-dnc1-mod1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/dnc1.yaml}[MLB-TCB,width=.45\textwidth]{\texttt{dnc1.yaml}}{lst:dnc1-yaml} \end{cmhtcbraster} The settings in \cref{lst:dnc1-yaml} say that sentences do \emph{not} contain \lstinline!\begin! and that they do not contain \lstinline!\cmh! \end{example} \begin{example} We can implement case insensitivity for the \texttt{sentencesDoNOTcontain} field. We begin with the file in \cref{lst:sentence-dnc2}. \cmhlistingsfromfile{demonstrations/sentence-dnc2.tex}{\texttt{sentence-dnc2.tex}}{lst:sentence-dnc2} Upon running the following commands \begin{commandshell} latexindent.pl sentence-dnc2.tex -m -l=dnc2.yaml \end{commandshell} then we obtain the output given in \cref{lst:sentence-dnc2-mod2}. \begin{cmhtcbraster}[ raster left skip=-2.5cm, raster right skip=-1cm, raster force size=false, raster column 1/.style={add to width=3cm}, ] \cmhlistingsfromfile{demonstrations/sentence-dnc2-mod2.tex}{\texttt{sentence-dnc2-mod2.tex}}{lst:sentence-dnc2-mod2} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/dnc2.yaml}[MLB-TCB,width=.45\textwidth]{\texttt{dnc2.yaml}}{lst:dnc2-yaml} \end{cmhtcbraster} The settings in \cref{lst:dnc2-yaml} say that sentences do \emph{not} contain \lstinline!\begin! and that they do not contain \emph{case insensitive} versions of \lstinline!\cmh! \end{example} \begin{example} We can turn off \texttt{sentenceDoNOTcontain} by setting it to \texttt{0} as in \cref{lst:dnc-off-yaml}. \cmhlistingsfromfile[style=yaml-LST]{demonstrations/dnc-off.yaml}[MLB-TCB,width=.45\textwidth]{\texttt{dnc-off.yaml}}{lst:dnc-off-yaml} The settings in \cref{lst:dnc-off-yaml} mean that sentences can contain any character. \end{example} \subsubsection{Features of the oneSentencePerLine routine} The sentence manipulation routine takes place \emph{after} verbatim \index{verbatim!in relation to oneSentencePerLine} environments, preamble and trailing comments have been accounted for; this means that any characters within these types of code blocks will not be part of the sentence manipulation routine. \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} \subsubsection{oneSentencePerLine: text wrapping and indenting sentences} The \texttt{oneSentencePerLine} \announce{2018-08-13}{oneSentencePerline text wrap and indent} can be instructed to perform text wrapping and indentation upon sentences. \index{sentences!text wrapping} \index{sentences!indenting}% \begin{example} Let's use the code in \cref{lst:multiple-sentences5}. \cmhlistingsfromfile{demonstrations/multiple-sentences5.tex}{\texttt{multiple-sentences5.tex}}{lst:multiple-sentences5} Referencing \cref{lst:sentence-wrap1-yaml}, and running the following command \index{switches!-l demonstration} \index{switches!-m demonstration} \begin{commandshell} latexindent.pl multiple-sentences5 -m -l=sentence-wrap1.yaml \end{commandshell} we receive the output given in \cref{lst:multiple-sentences5-mod1}. \begin{cmhtcbraster}[ raster left skip=-3.5cm, raster right skip=-2cm, raster force size=false, raster column 1/.style={add to width=.1\textwidth}, raster column skip=.06\linewidth] \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}. \cmhlistingsfromfile{demonstrations/multiple-sentences6.tex}{\texttt{multiple-sentences6.tex}}{lst:multiple-sentences6} 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}. \cmhlistingsfromfile{demonstrations/multiple-sentences6-mod1.tex}{\texttt{multiple-sentences6-mod1.tex} using \cref{lst:sentence-wrap1-yaml}}{lst:multiple-sentences6-mod1} \cmhlistingsfromfile{demonstrations/multiple-sentences6-mod2.tex}{\texttt{multiple-sentences6-mod2.tex} using \cref{lst:sentence-wrap1-yaml} and no sentence indentation}{lst:multiple-sentences6-mod2} We note that \cref{lst:multiple-sentences6-mod1} the \texttt{itemize} code block has \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}. This setting is actually an appended version of the \texttt{betterFullStop} from the \texttt{fineTuning}, detailed in \vref{lst:fineTuning}. \index{regular expressions!lowercase alph a-z} \index{regular expressions!uppercase alph A-Z} \index{regular expressions!numeric 0-9} \index{regular expressions!horizontal space \textbackslash{h}} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/itemize.yaml}[enhanced jigsaw,breakable,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} 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 text wrapping, from the value of \texttt{removeSentenceLineBreaks}. \subsubsection{oneSentencePerLine: text wrapping and indenting sentences, when before/after}\label{subsubsec:ospl:before:after} The text wrapping routine operates, by default, \texttt{before} the \announce{2023-01-01}{text wrap: before/after details} code blocks have been found, but this can be changed to \texttt{after}: \begin{itemize} \item \texttt{before} means it is likely that the columns of wrapped text may \emph{exceed} the value specified in \texttt{columns}; \item \texttt{after} means it columns of wrapped text should \emph{not} exceed the value specified in \texttt{columns}. \end{itemize} We demonstrate this in the following examples. See also \cref{subsubsec:tw:before:after}. \begin{example} Let's begin with the file in \cref{lst:multiple-sentences8}. \cmhlistingsfromfile{demonstrations/multiple-sentences8.tex}{\texttt{multiple-sentences8.tex}}{lst:multiple-sentences8} Using the settings given in \cref{lst:sentence-wrap2} and running the command \begin{commandshell} latexindent.pl multiple-sentences8 -o=+-mod1.tex -l=sentence-wrap2 -m \end{commandshell} gives the output given in \cref{lst:multiple-sentences8-mod1}. \begin{cmhtcbraster}[raster columns=2, raster left skip=-1.5cm, raster right skip=-0cm, raster column skip=.06\linewidth] \cmhlistingsfromfile{demonstrations/multiple-sentences8-mod1.tex}{\texttt{multiple-sentences8-mod1.tex}}{lst:multiple-sentences8-mod1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/sentence-wrap2.yaml}[MLB-TCB,width=0.4\linewidth]{\texttt{sentence-wrap2.yaml}}{lst:sentence-wrap2} \end{cmhtcbraster} We note that, in \cref{lst:multiple-sentences8-mod1}, that the wrapped text has \emph{exceeded} the specified value of \texttt{columns} (35) given in \cref{lst:sentence-wrap2}. We can affect this by changing \texttt{when}; we explore this next. \end{example} \begin{example} We continue working with \cref{lst:multiple-sentences8}. Using the settings given in \cref{lst:sentence-wrap3} and running the command \begin{commandshell} latexindent.pl multiple-sentences8.tex -o=+-mod2.tex -l=sentence-wrap3 -m \end{commandshell} gives the output given in \cref{lst:multiple-sentences8-mod2}. \begin{cmhtcbraster}[raster columns=2, raster left skip=-1.5cm, raster right skip=-0cm, raster column skip=.06\linewidth] \cmhlistingsfromfile{demonstrations/multiple-sentences8-mod2.tex}{\texttt{multiple-sentences8-mod2.tex}}{lst:multiple-sentences8-mod2} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/sentence-wrap3.yaml}[MLB-TCB,width=0.4\linewidth]{\texttt{sentence-wrap3.yaml}}{lst:sentence-wrap3} \end{cmhtcbraster} We note that, in \cref{lst:multiple-sentences8-mod2}, that the wrapped text has \emph{obeyed} the specified value of \texttt{columns} (35) given in \cref{lst:sentence-wrap3}. \end{example} \subsubsection{oneSentencePerLine: text wrapping sentences and comments}\label{subsubsec:ospl:tw:comments} We demonstrate the one sentence per line routine with respect to text wrapping \emph{comments}. See also \cref{subsubsec:tw:comments}. \index{comments!text wrap} \index{text wrap!comments} \index{sentences!comments} \index{sentences!text wrap} \begin{example} Let's begin with the file in \cref{lst:multiple-sentences9}. \cmhlistingsfromfile{demonstrations/multiple-sentences9.tex}{\texttt{multiple-sentences9.tex}}{lst:multiple-sentences9} Using the settings given in \cref{lst:sentence-wrap4} and running the command \begin{commandshell} latexindent.pl multiple-sentences9 -o=+-mod1.tex -l=sentence-wrap4 -m \end{commandshell} gives the output given in \cref{lst:multiple-sentences9-mod1}. \begin{cmhtcbraster}[raster columns=2, raster left skip=-1.5cm, raster right skip=-0cm, raster column skip=.06\linewidth] \cmhlistingsfromfile{demonstrations/multiple-sentences9-mod1.tex}{\texttt{multiple-sentences9-mod1.tex}}{lst:multiple-sentences9-mod1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/sentence-wrap4.yaml}[MLB-TCB,width=0.4\linewidth]{\texttt{sentence-wrap4.yaml}}{lst:sentence-wrap4} \end{cmhtcbraster} We note that, in \cref{lst:multiple-sentences9-mod1}, that the sentences have been wrapped, and so too have the comments because of the annotated line in \cref{lst:sentence-wrap4}. \end{example} % arara: pdflatex: { files: [latexindent]} \subsection{Poly-switches}\label{sec:poly-switches} Every other field in the \texttt{modifyLineBreaks} field uses poly-switches, and can take one of the following% \announce{2017-08-21}*{blank line poly-switch} integer values: \index{modifying linebreaks! using poly-switches} \index{poly-switches!definition} \index{poly-switches!values} \index{poly-switches!off by default: set to 0} \begin{description} \item[$-1$] \emph{remove mode}: line breaks before or after the \emph{<part of thing>} can be removed (assuming that \texttt{preserveBlankLines} is set to \texttt{0}); \item[0] \emph{off mode}: line breaks will not be modified for the \emph{<part of thing>} under consideration; \item[1] \emph{add mode}: a line break will be added before or after the \emph{<part of thing>} under consideration, assuming that there is not already a line break before or after the \emph{<part of thing>}; \item[2] \emph{comment then add mode}: a comment symbol will be added, followed by a line break before or after the \emph{<part of thing>} under consideration, assuming that there is not already a comment and line break before or after the \emph{<part of thing>}; \item[3] \emph{add then blank line mode}% \announce{2017-08-21}{blank line poly-switch}: a line break will be added before or after the \emph{<part of thing>} under consideration, assuming that there is not already a line break before or after the \emph{<part of thing>}, followed by a blank line; \item[4] \emph{add blank line mode}% \announce{2019-07-13}{blank line poly-switch}; a blank line will be added before or after the \emph{<part of thing>} under consideration, even if the \emph{<part of thing>} is already on its own line. \end{description} In the above, \emph{<part of thing>} refers to either the \emph{begin statement}, \emph{body} or \emph{end statement} of the code blocks detailed in \vref{tab:code-blocks}. All poly-switches are \emph{off} by default; \texttt{latexindent.pl} searches first of all for per-name settings, and then followed by global per-thing settings. \subsubsection{Poly-switches for environments}\label{sec:modifylinebreaks-environments} We start by viewing a snippet of \texttt{defaultSettings.yaml} in \cref{lst:environments-mlb}; note that it contains \emph{global} settings (immediately after the \texttt{environments} field) and that \emph{per-name} settings are also allowed -- in the case of \cref{lst:environments-mlb}, settings for \texttt{equation*} have been specified for demonstration. Note that all poly-switches are \emph{off} (set to 0) by default. \index{poly-switches!default values} \index{poly-switches!environment global example} \index{poly-switches!environment per-code block example} \cmhlistingsfromfile[style=modifylinebreaksEnv]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,MLB-TCB]{\texttt{environments}}{lst:environments-mlb} Let's begin with the simple example given in \cref{lst:env-mlb1-tex}; note that we have annotated key parts of the file using $\BeginStartsOnOwnLine$, $\BodyStartsOnOwnLine$, $\EndStartsOnOwnLine$ and $\EndFinishesWithLineBreak$, these will be related to fields specified in \cref{lst:environments-mlb}. \index{poly-switches!visualisation: $\BeginStartsOnOwnLine$, $\BodyStartsOnOwnLine$, $\EndStartsOnOwnLine$, $\EndFinishesWithLineBreak$} \begin{cmhlistings}[style=tcblatex,escapeinside={(*@}{@*)}]{\texttt{env-mlb1.tex}}{lst:env-mlb1-tex} before words(*@$\BeginStartsOnOwnLine$@*) \begin{myenv}(*@$\BodyStartsOnOwnLine$@*)body of myenv(*@$\EndStartsOnOwnLine$@*)\end{myenv}(*@$\EndFinishesWithLineBreak$@*) after words \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{cmhtcbraster} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb1.yaml}[MLB-TCB]{\texttt{env-mlb1.yaml}}{lst:env-mlb1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb2.yaml}[MLB-TCB]{\texttt{env-mlb2.yaml}}{lst:env-mlb2} \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} \begin{minipage}{.56\linewidth} \cmhlistingsfromfile{demonstrations/env-mlb-mod1.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb1}}{lst:env-mlb-mod1} \end{minipage} \hfill \begin{minipage}{.43\linewidth} \cmhlistingsfromfile{demonstrations/env-mlb-mod2.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb2}}{lst:env-mlb-mod2} \end{minipage} \end{widepage} There are a couple of points to note: \begin{itemize} \item in \cref{lst:env-mlb-mod1} a line break has been added at the point denoted by $\BeginStartsOnOwnLine$ in \cref{lst:env-mlb1-tex}; no other line breaks have been changed; \item in \cref{lst:env-mlb-mod2} a line break has been added at the point denoted by $\BodyStartsOnOwnLine$ in \cref{lst:env-mlb1-tex}; furthermore, note that the \emph{body} of \texttt{myenv} has received the appropriate (default) indentation. \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{cmhtcbraster} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb3.yaml}[MLB-TCB]{\texttt{env-mlb3.yaml}}{lst:env-mlb3} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb4.yaml}[MLB-TCB]{\texttt{env-mlb4.yaml}}{lst:env-mlb4} \end{cmhtcbraster} Upon running the commands \begin{commandshell} latexindent.pl -m env-mlb.tex -l env-mlb3.yaml latexindent.pl -m env-mlb.tex -l env-mlb4.yaml \end{commandshell} we obtain \cref{lst:env-mlb-mod3,lst:env-mlb-mod4}. \begin{widepage} \begin{minipage}{.56\linewidth} \cmhlistingsfromfile{demonstrations/env-mlb-mod3.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb3}}{lst:env-mlb-mod3} \end{minipage} \hfill \begin{minipage}{.43\linewidth} \cmhlistingsfromfile{demonstrations/env-mlb-mod4.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb4}}{lst:env-mlb-mod4} \end{minipage} \end{widepage} Note that line breaks have been added as in \cref{lst:env-mlb-mod1,lst:env-mlb-mod2}, but this time a comment symbol has been added before adding the line break; in both cases, trailing horizontal space has been stripped before doing so. \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 $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{cmhtcbraster} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb5.yaml}[MLB-TCB]{\texttt{env-mlb5.yaml}}{lst:env-mlb5} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb6.yaml}[MLB-TCB]{\texttt{env-mlb6.yaml}}{lst:env-mlb6} \end{cmhtcbraster} Upon running the commands \begin{commandshell} latexindent.pl -m env-mlb.tex -l env-mlb5.yaml latexindent.pl -m env-mlb.tex -l env-mlb6.yaml \end{commandshell} we obtain \cref{lst:env-mlb-mod5,lst:env-mlb-mod6}. \begin{widepage} \begin{minipage}{.56\linewidth} \cmhlistingsfromfile{demonstrations/env-mlb-mod5.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb5}}{lst:env-mlb-mod5} \end{minipage} \hfill \begin{minipage}{.43\linewidth} \cmhlistingsfromfile{demonstrations/env-mlb-mod6.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb6}}{lst:env-mlb-mod6} \end{minipage} \end{widepage} Note that line breaks have been added as in \cref{lst:env-mlb-mod1,lst:env-mlb-mod2}, but this time a \emph{blank line} has been added after adding the line break. \end{example} \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{cmhtcbraster} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-beg4.yaml}[MLB-TCB]{\texttt{env-beg4.yaml}}{lst:env-beg4} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-body4.yaml}[MLB-TCB]{\texttt{env-body4.yaml}}{lst:env-body4} \end{cmhtcbraster} We will demonstrate this poly-switch value using the code in \cref{lst:env-mlb1-text}. \cmhlistingsfromfile{demonstrations/env-mlb1.tex}{\texttt{env-mlb1.tex}}{lst:env-mlb1-text} Upon running the commands \index{switches!-l demonstration} \index{switches!-m demonstration} \begin{commandshell} latexindent.pl -m env-mlb1.tex -l env-beg4.yaml latexindent.pl -m env-mlb.1tex -l env-body4.yaml \end{commandshell} then we receive the respective outputs in \cref{lst:env-mlb1-beg4,lst:env-mlb1-body4}. \begin{cmhtcbraster}[raster column skip=.1\linewidth] \cmhlistingsfromfile{demonstrations/env-mlb1-beg4.tex}{\texttt{env-mlb1.tex} using \cref{lst:env-beg4}}{lst:env-mlb1-beg4} \cmhlistingsfromfile{demonstrations/env-mlb1-body4.tex}{\texttt{env-mlb1.tex} using \cref{lst:env-body4}}{lst:env-mlb1-body4} \end{cmhtcbraster} We note in particular that, by design, for this value of the poly-switches: \begin{enumerate} \item in \cref{lst:env-mlb1-beg4} a blank line has been inserted before the \lstinline!\begin! statement, even though the \lstinline!\begin! statement was already on its own line; \item in \cref{lst:env-mlb1-body4} a blank line has been inserted before the beginning of the \emph{body}, even though it already began on its own line. \end{enumerate} \end{example} \paragraph{Adding line breaks: EndStartsOnOwnLine and EndFinishesWithLineBreak} \begin{example} Let's explore \texttt{EndStartsOnOwnLine} and \texttt{EndFinishesWithLineBreak} in \cref{lst:env-mlb7,lst:env-mlb8}, and in particular, let's allow each of them in turn to take a value of $1$. \index{modifying linebreaks! at the \emph{end} of a code block} \index{poly-switches!adding line breaks: set to 1} \begin{cmhtcbraster} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb7.yaml}[MLB-TCB]{\texttt{env-mlb7.yaml}}{lst:env-mlb7} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb8.yaml}[MLB-TCB]{\texttt{env-mlb8.yaml}}{lst:env-mlb8} \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{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} \item in \cref{lst:env-mlb-mod7} a line break has been added at the point denoted by $\EndStartsOnOwnLine$ in \vref{lst:env-mlb1-tex}; no other line breaks have been changed and the \lstinline!\end{myenv}! statement has \emph{not} received indentation (as intended); \item in \cref{lst:env-mlb-mod8} a line break has been added at the point denoted by $\EndFinishesWithLineBreak$ in \vref{lst:env-mlb1-tex}. \end{itemize} \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{cmhtcbraster} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb9.yaml}[MLB-TCB]{\texttt{env-mlb9.yaml}}{lst:env-mlb9} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb10.yaml}[MLB-TCB]{\texttt{env-mlb10.yaml}}{lst:env-mlb10} \end{cmhtcbraster} Upon running the commands \begin{commandshell} latexindent.pl -m env-mlb.tex -l env-mlb9.yaml latexindent.pl -m env-mlb.tex -l env-mlb10.yaml \end{commandshell} we obtain \cref{lst:env-mlb-mod9,lst:env-mlb-mod10}. \begin{widepage} \begin{minipage}{.43\linewidth} \cmhlistingsfromfile{demonstrations/env-mlb-mod9.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb9}}{lst:env-mlb-mod9} \end{minipage} \hfill \begin{minipage}{.56\linewidth} \cmhlistingsfromfile{demonstrations/env-mlb-mod10.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb10}}{lst:env-mlb-mod10} \end{minipage} \end{widepage} Note that line breaks have been added as in \cref{lst:env-mlb-mod7,lst:env-mlb-mod8}, but this time a comment symbol has been added before adding the line break; in both cases, trailing horizontal space has been stripped before doing so. \end{example} \begin{example} Let's now change each of the \texttt{1} values in \cref{lst:env-mlb7,lst:env-mlb8} so that they are $3$ and save them into \texttt{env-mlb11.yaml} and \texttt{env-mlb12.yaml} respectively (see \cref{lst:env-mlb11,lst:env-mlb12}). \index{poly-switches!adding blank lines: set to 3}\announce{2017-08-21}{demonstration of blank line poly-switch (3)}% \begin{cmhtcbraster} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb11.yaml}[MLB-TCB]{\texttt{env-mlb11.yaml}}{lst:env-mlb11} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb12.yaml}[MLB-TCB]{\texttt{env-mlb12.yaml}}{lst:env-mlb12} \end{cmhtcbraster} Upon running the commands \begin{commandshell} latexindent.pl -m env-mlb.tex -l env-mlb11.yaml latexindent.pl -m env-mlb.tex -l env-mlb12.yaml \end{commandshell} we obtain \cref{lst:env-mlb-mod11,lst:env-mlb-mod12}. \begin{widepage} \begin{minipage}{.42\linewidth} \cmhlistingsfromfile{demonstrations/env-mlb-mod11.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb11}}{lst:env-mlb-mod11} \end{minipage} \hfill \begin{minipage}{.57\linewidth} \cmhlistingsfromfile{demonstrations/env-mlb-mod12.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb12}}{lst:env-mlb-mod12} \end{minipage} \end{widepage} Note that line breaks have been added as in \cref{lst:env-mlb-mod7,lst:env-mlb-mod8}, and that a \emph{blank line} has been added after the line break. \end{example} \begin{example} Let's now change each of the \texttt{1} values in \cref{lst:env-mlb11,lst:env-mlb12} so that they are $4$ and save them into \texttt{env-end4.yaml} and \texttt{env-end-f4.yaml} respectively (see \cref{lst:env-end4,lst:env-end-f4}). \announce{2019-07-13}{demonstration of new blank line poly-switch} \index{poly-switches!adding blank lines (again"!): set to 4}% \begin{cmhtcbraster} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-end4.yaml}[MLB-TCB]{\texttt{env-end4.yaml}}{lst:env-end4} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-end-f4.yaml}[MLB-TCB]{\texttt{env-end-f4.yaml}}{lst:env-end-f4} \end{cmhtcbraster} We will demonstrate this poly-switch value using the code from \vref{lst:env-mlb1-text}. 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 \end{commandshell} then we receive the respective outputs in \cref{lst:env-mlb1-end4,lst:env-mlb1-end-f4}. \begin{cmhtcbraster}[raster column skip=.1\linewidth] \cmhlistingsfromfile{demonstrations/env-mlb1-end4.tex}{\texttt{env-mlb1.tex} using \cref{lst:env-end4}}{lst:env-mlb1-end4} \cmhlistingsfromfile{demonstrations/env-mlb1-end-f4.tex}{\texttt{env-mlb1.tex} using \cref{lst:env-end-f4}}{lst:env-mlb1-end-f4} \end{cmhtcbraster} We note in particular that, by design, for this value of the poly-switches: \begin{enumerate} \item in \cref{lst:env-mlb1-end4} a blank line has been inserted before the \lstinline!\end! statement, even though the \lstinline!\end! statement was already on its own line; \item in \cref{lst:env-mlb1-end-f4} a blank line has been inserted after the \lstinline!\end! statement, even though it already began on its own line. \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. \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} \cmhlistingsfromfile{demonstrations/env-mlb3.tex}{\texttt{env-mlb3.tex}}{lst:mlb3} \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 \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 \texttt{BodyStartsOnOwnLine} is set to \texttt{1}. In \cref{lst:env-mlb3-mod4} you'll see that the comment has been accounted for correctly because \texttt{BodyStartsOnOwnLine} has been set to \texttt{2}, and the comment symbol has \emph{not} been moved to its own line. You're encouraged to experiment with \cref{lst:mlb3} and by setting the other poly-switches considered so far to \texttt{2} in turn. \begin{cmhtcbraster}[raster column skip=.1\linewidth] \cmhlistingsfromfile{demonstrations/env-mlb3-mod2.tex}{\texttt{env-mlb3.tex} using \vref{lst:env-mlb2}}{lst:env-mlb3-mod2} \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 \emph{per-name} basis, which would take priority over the global values; with reference to \vref{lst:environments-mlb}, an example is shown for the \texttt{equation*} environment. \paragraph{Removing line breaks (poly-switches set to $-1$)} Setting poly-switches to $-1$ tells \texttt{latexindent.pl} to remove line breaks of the \emph{<part of the thing>}, if necessary. \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$@*) \begin{myenv}(*@$\BodyStartsOnOwnLine$@*) body of myenv(*@$\EndStartsOnOwnLine$@*) \end{myenv}(*@$\EndFinishesWithLineBreak$@*) after words \end{cmhlistings} \end{minipage}% \hfill \begin{minipage}{.51\textwidth} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb13.yaml}[MLB-TCB]{\texttt{env-mlb13.yaml}}{lst:env-mlb13} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb14.yaml}[MLB-TCB]{\texttt{env-mlb14.yaml}}{lst:env-mlb14} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb15.yaml}[MLB-TCB]{\texttt{env-mlb15.yaml}}{lst:env-mlb15} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb16.yaml}[MLB-TCB]{\texttt{env-mlb16.yaml}}{lst:env-mlb16} \end{minipage} After running the commands \index{switches!-l demonstration} \index{switches!-m demonstration} \begin{commandshell} latexindent.pl -m env-mlb4.tex -l env-mlb13.yaml latexindent.pl -m env-mlb4.tex -l env-mlb14.yaml latexindent.pl -m env-mlb4.tex -l env-mlb15.yaml latexindent.pl -m env-mlb4.tex -l env-mlb16.yaml \end{commandshell} we obtain the respective output in \crefrange{lst:env-mlb4-mod13}{lst:env-mlb4-mod16}. \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/env-mlb4-mod13.tex}{\texttt{env-mlb4.tex} using \cref{lst:env-mlb13}}{lst:env-mlb4-mod13} \cmhlistingsfromfile{demonstrations/env-mlb4-mod14.tex}{\texttt{env-mlb4.tex} using \cref{lst:env-mlb14}}{lst:env-mlb4-mod14} \end{cmhtcbraster} \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/env-mlb4-mod15.tex}{\texttt{env-mlb4.tex} using \cref{lst:env-mlb15}}{lst:env-mlb4-mod15} \cmhlistingsfromfile{demonstrations/env-mlb4-mod16.tex}{\texttt{env-mlb4.tex} using \cref{lst:env-mlb16}}{lst:env-mlb4-mod16} \end{cmhtcbraster} Notice that in: \begin{itemize} \item \cref{lst:env-mlb4-mod13} the line break denoted by $\BeginStartsOnOwnLine$ in \cref{lst:mlb4} has been removed; \item \cref{lst:env-mlb4-mod14} the line break denoted by $\BodyStartsOnOwnLine$ in \cref{lst:mlb4} has been removed; \item \cref{lst:env-mlb4-mod15} the line break denoted by $\EndStartsOnOwnLine$ in \cref{lst:mlb4} has been removed; \item \cref{lst:env-mlb4-mod16} the line break denoted by $\EndFinishesWithLineBreak$ in \cref{lst:mlb4} has been removed. \end{itemize} We examined each of these cases separately for clarity of explanation, but you can combine all of the YAML settings in \crefrange{lst:env-mlb13}{lst:env-mlb16} into one file; alternatively, you could tell \texttt{latexindent.pl} to load them all by using the following command, for example \index{switches!-l demonstration} \index{switches!-m 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 \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. \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$@*) \begin{myenv} (*@$\BodyStartsOnOwnLine$@*) body of myenv (*@$\EndStartsOnOwnLine$@*) \end{myenv} (*@$\EndFinishesWithLineBreak$@*) after words \end{cmhlistings} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/removeTWS-before.yaml}[yaml-TCB]{\texttt{removeTWS-before.yaml}}{lst:removeTWS-before} \end{cmhtcbraster} The output from the following commands \index{switches!-l demonstration} \index{switches!-m demonstration} \begin{widepage} \begin{commandshell} latexindent.pl -m env-mlb5.tex -l env-mlb13,env-mlb14,env-mlb15,env-mlb16 latexindent.pl -m env-mlb5.tex -l env-mlb13,env-mlb14,env-mlb15,env-mlb16,removeTWS-before \end{commandshell} \end{widepage} is shown, respectively, in \cref{lst:env-mlb5-modAll,lst:env-mlb5-modAll-remove-WS}; note that the trailing horizontal white space has been preserved (by default) in \cref{lst:env-mlb5-modAll}, while in \cref{lst:env-mlb5-modAll-remove-WS}, it has been removed using the switch specified in \cref{lst:removeTWS-before}. \begin{widepage} \cmhlistingsfromfile[showspaces=true]{demonstrations/env-mlb5-modAll.tex}{\texttt{env-mlb5.tex} using \crefrange{lst:env-mlb4-mod13}{lst:env-mlb4-mod16}}{lst:env-mlb5-modAll} \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} \begin{cmhtcbraster} \begin{cmhlistings}[style=tcblatex,escapeinside={(*@}{@*)}]{\texttt{env-mlb6.tex}}{lst:mlb6} before words(*@$\BeginStartsOnOwnLine$@*) \begin{myenv}(*@$\BodyStartsOnOwnLine$@*) body of myenv(*@$\EndStartsOnOwnLine$@*) \end{myenv}(*@$\EndFinishesWithLineBreak$@*) after words \end{cmhlistings} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/UnpreserveBlankLines.yaml}[MLB-TCB]{\texttt{UnpreserveBlankLines.yaml}}{lst:UnpreserveBlankLines} \end{cmhtcbraster} Upon running the following commands \index{switches!-l demonstration} \index{switches!-m demonstration} \begin{widepage} \begin{commandshell} latexindent.pl -m env-mlb6.tex -l env-mlb13,env-mlb14,env-mlb15,env-mlb16 latexindent.pl -m env-mlb6.tex -l env-mlb13,env-mlb14,env-mlb15,env-mlb16,UnpreserveBlankLines \end{commandshell} \end{widepage} we receive the respective outputs in \cref{lst:env-mlb6-modAll,lst:env-mlb6-modAll-un-Preserve-Blank-Lines}. In \cref{lst:env-mlb6-modAll} we see that the multiple blank lines have each been condensed into one blank line, but that blank lines have \emph{not} been removed by the poly-switches -- this is because, by default, \texttt{preserveBlankLines} is set to \texttt{1}. By contrast, in \cref{lst:env-mlb6-modAll-un-Preserve-Blank-Lines}, we have allowed the poly-switches to remove blank lines because, in \cref{lst:UnpreserveBlankLines}, we have set \texttt{preserveBlankLines} to \texttt{0}. \begin{cmhtcbraster}[ raster left skip=-3.5cm, raster right skip=-2cm, raster force size=false, raster column 1/.style={add to width=-.2\textwidth}, raster column 2/.style={add to width=.2\textwidth}, raster column skip=.06\linewidth] \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}. \cmhlistingsfromfile{demonstrations/env-mlb7.tex}{\texttt{env-mlb7.tex}}{lst:env-mlb7-tex} Upon running the following commands \index{switches!-l demonstration} \index{switches!-m demonstration} \begin{commandshell} latexindent.pl -m env-mlb7.tex -l env-mlb12.yaml,env-mlb13.yaml latexindent.pl -m env-mlb7.tex -l env-mlb13,env-mlb14,UnpreserveBlankLines \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} \cmhlistingsfromfile{demonstrations/env-mlb7-no-preserve.tex}{\texttt{env-mlb7-no-preserve.tex}}{lst:env-mlb7-no-preserve} Notice that in: \begin{itemize} \item \cref{lst:env-mlb7-preserve} that \lstinline!\end{one}! has added a blank line, because of the value of \texttt{EndFinishesWithLineBreak} in \vref{lst:env-mlb12}, and even though the line break ahead of \lstinline!\begin{two}! should have been removed (because of \texttt{BeginStartsOnOwnLine} in \vref{lst:env-mlb13}), the blank line has been preserved by default; \item \cref{lst:env-mlb7-no-preserve}, by contrast, has had the additional line-break removed, because of the settings in \cref{lst:UnpreserveBlankLines}. \end{itemize} \end{example} \subsubsection{Poly-switches for double backslash}\label{subsec:dbs} With reference to \texttt{lookForAlignDelims} (see \vref{lst:aligndelims:basic}) \announce{2019-07-13}{poly-switch for double backslash} you can specify poly-switches to dictate the line-break behaviour of double backslashes in environments (\vref{lst:tabularafter:basic}), commands (\vref{lst:matrixafter}), or special code blocks (\vref{lst:specialafter}). \footnote{There is no longer any need for the code block to be specified within \texttt{lookForAlignDelims} for DBS poly-switches to activate. \announce{2023-01-01}*{DBS poly-switches no need to specify lookForAlignDelims}} \index{delimiters!poly-switches for double backslash} \index{modifying linebreaks! surrounding double backslash} \index{poly-switches!for double back slash (delimiters)}% Consider the code given in \cref{lst:dbs-demo}. \begin{cmhlistings}[style=tcblatex,escapeinside={(*@}{@*)}]{\texttt{tabular3.tex}}{lst:dbs-demo} \begin{tabular}{cc} 1 & 2 (*@$\ElseStartsOnOwnLine$@*)\\(*@$\ElseFinishesWithLineBreak$@*) 3 & 4 (*@$\ElseStartsOnOwnLine$@*)\\(*@$\ElseFinishesWithLineBreak$@*) \end{tabular} \end{cmhlistings} Referencing \cref{lst:dbs-demo}: \begin{itemize} \item \texttt{DBS} stands for \emph{double backslash}; \item line breaks ahead of the double backslash are annotated by $\ElseStartsOnOwnLine$, and are controlled by \texttt{DBSStartsOnOwnLine}; \item line breaks after the double backslash are annotated by $\ElseFinishesWithLineBreak$, and are controlled by \texttt{DBSFinishesWithLineBreak}. \end{itemize} Let's explore each of these in turn. \paragraph{Double backslash starts on own line} \begin{example} We explore \texttt{DBSStartsOnOwnLine} ($\ElseStartsOnOwnLine$ in \cref{lst:dbs-demo}); starting with the code in \cref{lst:dbs-demo}, together with the YAML files given in \cref{lst:DBS1} and \cref{lst:DBS2} and running the following commands \index{switches!-l demonstration} \index{switches!-m demonstration} \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} \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} \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} We note that \begin{itemize} \item \cref{lst:DBS1} specifies \texttt{DBSStartsOnOwnLine} for \emph{every} environment (that is within \texttt{lookForAlignDelims}, \vref{lst:aligndelims:advanced}); the double backslashes from \cref{lst:dbs-demo} have been moved to their own line in \cref{lst:tabular3-DBS1}; \item \cref{lst:DBS2} specifies \texttt{DBSStartsOnOwnLine} on a \emph{per-name} basis for \texttt{tabular} (that is within \texttt{lookForAlignDelims}, \vref{lst:aligndelims:advanced}); the double backslashes from \cref{lst:dbs-demo} have been moved to their own line in \cref{lst:tabular3-DBS2}, having added comment symbols before moving them. \end{itemize} \end{example} \begin{example} We can combine DBS poly-switches with, for example, the \texttt{alignContentAfterDoubleBackSlash} in \vref{sec:alignContentAfterDoubleBackSlash}. For example, starting with the file \cref{lst:tabular6}, and using the settings in \vref{lst:alignContentAfterDBS1,lst:alignContentAfterDBS2} and running \begin{widepage} \begin{commandshell} latexindent.pl -s -m -l alignContentAfterDBS1.yaml,DBS1.yaml tabular6.tex -o=+-mod1 latexindent.pl -s -m -l alignContentAfterDBS2.yaml,DBS1.yaml tabular6.tex -o=+-mod2 \end{commandshell} \end{widepage} gives the respective outputs shown in \cref{lst:tabular6-mod1,lst:tabular6-mod2}. \begin{cmhtcbraster}[raster columns=3, raster left skip=-3.5cm, raster right skip=-2cm, raster column skip=.03\linewidth] \cmhlistingsfromfile{demonstrations/tabular6.tex}{\texttt{tabular6.tex}}{lst:tabular6} \cmhlistingsfromfile{demonstrations/tabular6-mod1.tex}{\texttt{tabular6-mod1.tex}}{lst:tabular6-mod1} \cmhlistingsfromfile{demonstrations/tabular6-mod2.tex}{\texttt{tabular6-mod2.tex}}{lst:tabular6-mod2} \end{cmhtcbraster} We note that: \begin{itemize} \item in \cref{lst:tabular6-mod1} the content \emph{after} the double back slash has been aligned; \item in \cref{lst:tabular6-mod2} we see that 3 spaces have been added after the double back slash. \end{itemize} \end{example} \paragraph{Double backslash finishes with line break} \begin{example} Let's now explore \texttt{DBSFinishesWithLineBreak} ($\ElseFinishesWithLineBreak$ in \cref{lst:dbs-demo}); starting with the code in \cref{lst:dbs-demo}, together with the YAML files given in \cref{lst:DBS3} and \cref{lst:DBS4} and running the following commands \index{poly-switches!for double backslash (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} \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} \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} We note that \begin{itemize} \item \cref{lst:DBS3} specifies \texttt{DBSFinishesWithLineBreak} for \emph{every} environment (that is within \texttt{lookForAlignDelims}, \vref{lst:aligndelims:advanced}); the code following the double backslashes from \cref{lst:dbs-demo} has been moved to their own line in \cref{lst:tabular3-DBS3}; \item \cref{lst:DBS4} specifies \texttt{DBSFinishesWithLineBreak} on a \emph{per-name} basis for \texttt{tabular} (that is within \texttt{lookForAlignDelims}, \vref{lst:aligndelims:advanced}); the first double backslashes from \cref{lst:dbs-demo} have moved code following them to their own line in \cref{lst:tabular3-DBS4}, having added comment symbols before moving them; the final double backslashes have \emph{not} added a line break as they are at the end of the body within the code block. \end{itemize} \end{example} \paragraph{Double backslash poly-switches for specialBeginEnd} \begin{example} Let's explore the double backslash poly-switches for code blocks within \texttt{specialBeginEnd} code blocks (\vref{lst:specialBeginEnd}); we begin with the code within \cref{lst:special4}. \index{specialBeginEnd!double backslash poly-switch demonstration} \index{poly-switches!double backslash} \index{poly-switches!for double backslash (delimiters)} \index{specialBeginEnd!lookForAlignDelims} \index{delimiters} \index{linebreaks!summary of poly-switches} \cmhlistingsfromfile{demonstrations/special4.tex}{\texttt{special4.tex}}{lst:special4} Upon using the YAML settings in \cref{lst:DBS5}, and running the command \index{switches!-l demonstration} \index{switches!-m demonstration} \begin{commandshell} latexindent.pl -m special4.tex -l DBS5.yaml \end{commandshell} then we receive the output given in \cref{lst:special4-DBS5}. \index{delimiters!with specialBeginEnd and the -m switch} \begin{cmhtcbraster}[ raster force size=false, raster column 1/.style={add to width=-.1\textwidth}, raster column skip=.06\linewidth] \cmhlistingsfromfile{demonstrations/special4-mod5.tex}{\texttt{special4.tex} using \cref{lst:DBS5}}{lst:special4-DBS5} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/DBS5.yaml}[MLB-TCB,width=0.6\textwidth]{\texttt{DBS5.yaml}}{lst:DBS5} \end{cmhtcbraster} There are a few things to note: \begin{itemize} \item in \cref{lst:DBS5} we have specified \texttt{cmhMath} within \texttt{lookForAlignDelims}; without this, the double backslash poly-switches would be ignored for this code block; \item the \texttt{DBSFinishesWithLineBreak} poly-switch has controlled the line breaks following the double backslashes; \item the \texttt{SpecialEndStartsOnOwnLine} poly-switch has controlled the addition of a comment symbol, followed by a line break, as it is set to a value of 2. \end{itemize} \end{example} \paragraph{Double backslash poly-switches for optional and mandatory arguments} For clarity, we provide a demonstration of controlling the double backslash poly-switches for optional and mandatory arguments. \begin{example} We use with the code in \cref{lst:mycommand2}. \index{poly-switches!for double backslash (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}[ raster force size=false, raster column 1/.style={add to width=-.1\textwidth}, raster column skip=.03\linewidth] \cmhlistingsfromfile{demonstrations/mycommand2-mod6.tex}{\texttt{mycommand2.tex} using \cref{lst:DBS6}}{lst:mycommand2-DBS6} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/DBS6.yaml}[MLB-TCB,width=0.6\textwidth]{\texttt{DBS6.yaml}}{lst:DBS6} \end{cmhtcbraster} \begin{cmhtcbraster}[ raster force size=false, raster column 1/.style={add to width=-.1\textwidth}, raster column skip=.03\linewidth] \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 backslash optional square brackets} The pattern matching for the double backslash will also, optionally, allow trailing square brackets that contain a measurement of vertical spacing, for example \lstinline!\\[3pt]!. \index{poly-switches!for double backslash (delimiters)} \begin{example} For example, beginning with the code in \cref{lst:pmatrix3} \cmhlistingsfromfile{demonstrations/pmatrix3.tex}{\texttt{pmatrix3.tex}}{lst:pmatrix3} and running the following command, using \cref{lst:DBS3}, \index{switches!-l demonstration} \index{switches!-m demonstration} \begin{commandshell} latexindent.pl -m pmatrix3.tex -l DBS3.yaml \end{commandshell} 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 backslash by exploring the \emph{fine tuning} field detailed in \vref{lst:fineTuning}. \subsubsection{Poly-switches for other code blocks} Rather than repeat the examples shown for the environment code blocks (in \vref{sec:modifylinebreaks-environments}), we choose to detail the poly-switches for all other code blocks in \cref{tab:poly-switch-mapping}; note that each and every one of these poly-switches is \emph{off by default}, i.e, set to \texttt{0}. Note also that, by design, line breaks involving, \texttt{filecontents} and `comment-marked' code blocks (\vref{lst:alignmentmarkup}) can \emph{not} be modified using \texttt{latexindent.pl}. \announce{2019-05-05}*{verbatim poly-switch} However, there are two poly-switches available for \texttt{verbatim} code blocks: environments (\vref{lst:verbatimEnvironments}), commands (\vref{lst:verbatimCommands}) and \texttt{specialBeginEnd} (\vref{lst:special-verb1-yaml}). \index{specialBeginEnd!poly-switch summary} \index{verbatim!poly-switch summary} \index{poly-switches!summary of all poly-switches}% \clearpage \begin{longtable}{llll} \caption{Poly-switch mappings for all code-block types}\label{tab:poly-switch-mapping} \\ \toprule Code block & Sample & \multicolumn{2}{c}{Poly-switch mapping} \\ \midrule environment & \verb!before words!$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & BeginStartsOnOwnLine \\ & \verb!\begin{myenv}!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & BodyStartsOnOwnLine \\ & \verb!body of myenv!$\EndStartsOnOwnLine$ & $\EndStartsOnOwnLine$ & EndStartsOnOwnLine \\ & \verb!\end{myenv}!$\EndFinishesWithLineBreak$ & $\EndFinishesWithLineBreak$ & EndFinishesWithLineBreak \\ & \verb!after words! & & \\ \cmidrule{2-4} ifelsefi & \verb!before words!$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & IfStartsOnOwnLine \\ & \verb!\if...!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & BodyStartsOnOwnLine \\ & \verb!body of if/or statement!$\OrStartsOnOwnLine$ & $\OrStartsOnOwnLine$ & OrStartsOnOwnLine % \announce{2018-04-27}{new ifElseFi code block poly-switches} \\ & \verb!\or!$\OrFinishesWithLineBreak$ & $\OrFinishesWithLineBreak$ & OrFinishesWithLineBreak \\ & \verb!body of if/or statement!$\ElseStartsOnOwnLine$ & $\ElseStartsOnOwnLine$ & ElseStartsOnOwnLine \\ & \verb!\else!$\ElseFinishesWithLineBreak$ & $\ElseFinishesWithLineBreak$ & ElseFinishesWithLineBreak \\ & \verb!body of else statement!$\EndStartsOnOwnLine$ & $\EndStartsOnOwnLine$ & FiStartsOnOwnLine \\ & \verb!\fi!$\EndFinishesWithLineBreak$ & $\EndFinishesWithLineBreak$ & FiFinishesWithLineBreak \\ & \verb!after words! & & \\ \cmidrule{2-4} optionalArguments & \verb!...!$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & LSqBStartsOnOwnLine\footnote{LSqB stands for Left Square Bracket} \\ & \verb![!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & OptArgBodyStartsOnOwnLine \\ \announce{2019-07-13}{new comma-related poly-switches} & \verb!value before comma!$\ElseStartsOnOwnLine$, & $\ElseStartsOnOwnLine$ & CommaStartsOnOwnLine \\ & $\ElseFinishesWithLineBreak$ & $\ElseFinishesWithLineBreak$ & CommaFinishesWithLineBreak \\ & \verb!end of body of opt arg!$\EndStartsOnOwnLine$ & $\EndStartsOnOwnLine$ & RSqBStartsOnOwnLine \\ & \verb!]!$\EndFinishesWithLineBreak$ & $\EndFinishesWithLineBreak$ & RSqBFinishesWithLineBreak \\ & \verb!...! & & \\ \cmidrule{2-4} mandatoryArguments & \verb!...!$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & LCuBStartsOnOwnLine\footnote{LCuB stands for Left Curly Brace} \\ & \verb!{!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & MandArgBodyStartsOnOwnLine \\ \announce{2019-07-13}{new comma-related poly-switches} & \verb!value before comma!$\ElseStartsOnOwnLine$, & $\ElseStartsOnOwnLine$ & CommaStartsOnOwnLine \\ & $\ElseFinishesWithLineBreak$ & $\ElseFinishesWithLineBreak$ & CommaFinishesWithLineBreak \\ & \verb!end of body of mand arg!$\EndStartsOnOwnLine$ & $\EndStartsOnOwnLine$ & RCuBStartsOnOwnLine \\ & \verb!}!$\EndFinishesWithLineBreak$ & $\EndFinishesWithLineBreak$ & RCuBFinishesWithLineBreak \\ & \verb!...! & & \\ \cmidrule{2-4} commands & \verb!before words!$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & CommandStartsOnOwnLine \\ & \verb!\mycommand!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & CommandNameFinishesWithLineBreak \\ & $\langle$\itshape{arguments}$\rangle$ & & \\ \cmidrule{2-4} namedGroupingBracesBrackets & before words$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & NameStartsOnOwnLine \\ & myname$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & NameFinishesWithLineBreak \\ & $\langle$\itshape{braces/brackets}$\rangle$ & & \\ \cmidrule{2-4} keyEqualsValuesBraces\newline Brackets & before words$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & KeyStartsOnOwnLine \\ & key$\EqualsStartsOnOwnLine$=$\BodyStartsOnOwnLine$ & $\EqualsStartsOnOwnLine$ & EqualsStartsOnOwnLine \\ & $\langle$\itshape{braces/brackets}$\rangle$ & $\BodyStartsOnOwnLine$ & EqualsFinishesWithLineBreak \\ \cmidrule{2-4} items & before words$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & ItemStartsOnOwnLine \\ & \verb!\item!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & ItemFinishesWithLineBreak \\ & \verb!...! & & \\ \cmidrule{2-4} specialBeginEnd & before words$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & SpecialBeginStartsOnOwnLine \\ & \verb!\[!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & SpecialBodyStartsOnOwnLine \\ & \verb!body of special/middle!$\ElseStartsOnOwnLine$ & $\ElseStartsOnOwnLine$ & SpecialMiddleStartsOnOwnLine % \announce{2018-04-27}{new special code block poly-switches} \\ & \verb!\middle!$\ElseFinishesWithLineBreak$ & $\ElseFinishesWithLineBreak$ & SpecialMiddleFinishesWithLineBreak \\ & body of special/middle $\EndStartsOnOwnLine$ & $\EndStartsOnOwnLine$ & SpecialEndStartsOnOwnLine \\ & \verb!\]!$\EndFinishesWithLineBreak$ & $\EndFinishesWithLineBreak$ & SpecialEndFinishesWithLineBreak \\ & after words & & \\ \cmidrule{2-4} verbatim & before words$\BeginStartsOnOwnLine$\verb!\begin{verbatim}! & $\BeginStartsOnOwnLine$ & VerbatimBeginStartsOnOwnLine \\ \announce{2019-05-05}{verbatim poly-switches} & body of verbatim \verb!\end{verbatim}!$\EndFinishesWithLineBreak$ & $\EndFinishesWithLineBreak$ & VerbatimEndFinishesWithLineBreak \\ & after words & & \\ \bottomrule \end{longtable} \subsubsection{Partnering BodyStartsOnOwnLine with argument-based poly-switches} Some poly-switches need to be partnered together; in particular, when line breaks involving the \emph{first} argument of a code block need to be accounted for using both \texttt{BodyStartsOnOwnLine} (or its equivalent, see \vref{tab:poly-switch-mapping}) and \texttt{LCuBStartsOnOwnLine} for mandatory arguments, and \texttt{LSqBStartsOnOwnLine} for optional arguments. \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}. \cmhlistingsfromfile{demonstrations/mycommand1.tex}{\texttt{mycommand1.tex}}{lst:mycommand1} Upon running the command \index{switches!-l demonstration} \index{switches!-m demonstration} \begin{commandshell} latexindent.pl -m -l=mycom-mlb1.yaml mycommand1.tex \end{commandshell} we obtain \cref{lst:mycommand1-mlb1}; note that the \emph{second} mandatory argument beginning brace \lstinline!{! has had its leading line break removed, but that the \emph{first} brace has not. \begin{cmhtcbraster}[ raster force size=false, raster column 1/.style={add to width=-1cm}, ] \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 command \begin{commandshell} latexindent.pl -m -l=mycom-mlb2.yaml mycommand1.tex \end{commandshell} we obtain \cref{lst:mycommand1-mlb2}; both beginning braces \lstinline!{! have had their leading line breaks removed. \begin{cmhtcbraster}[ raster force size=false, raster column 1/.style={add to width=-1cm}, ] \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 command \begin{commandshell} latexindent.pl -m -l=mycom-mlb3.yaml mycommand1.tex \end{commandshell} we obtain \cref{lst:mycommand1-mlb3}. \begin{cmhtcbraster}[ raster force size=false, raster column 1/.style={add to width=-1cm}, ] \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. \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} \cmhlistingsfromfile{demonstrations/mycommand1-mlb4.tex}{\texttt{mycommand1.tex} using \cref{lst:mycom-mlb4}}{lst:mycommand1-mlb4} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycom-mlb4.yaml}[MLB-TCB,width=\linewidth]{\texttt{mycom-mlb4.yaml}}{lst:mycom-mlb4} \end{cmhtcbraster} Studying \cref{lst:mycom-mlb4}, we see that the two poly-switches are at opposition with one another: \begin{itemize} \item on the one hand, \texttt{LCuBStartsOnOwnLine} should \emph{not} start on its own line (as poly-switch is set to $-1$); \item on the other hand, \texttt{RCuBFinishesWithLineBreak} \emph{should} finish with a line break. \end{itemize} So, which should win the conflict? As demonstrated in \cref{lst:mycommand1-mlb4}, it is clear that \texttt{LCuBStartsOnOwnLine} won this conflict, and the reason is that \emph{the second argument was processed after the first} -- in general, the most recently-processed code block and associated poly-switch takes priority. \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=.05\linewidth] \cmhlistingsfromfile{demonstrations/mycommand1-mlb5.tex}{\texttt{mycommand1.tex} using \cref{lst:mycom-mlb5}}{lst:mycommand1-mlb5} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycom-mlb5.yaml}[MLB-TCB,width=\linewidth]{\texttt{mycom-mlb5.yaml}}{lst:mycom-mlb5} \end{cmhtcbraster} As previously, the most-recently-processed code block takes priority -- as before, the second (i.e, \emph{last}) argument. Exploring this further, we consider the YAML settings in \cref{lst:mycom-mlb6}, and run the command \begin{commandshell} latexindent.pl -m -l=mycom-mlb6.yaml mycommand1.tex \end{commandshell} which gives the output in \cref{lst:mycommand1-mlb6}. \begin{cmhtcbraster}[raster column skip=.05\linewidth] \cmhlistingsfromfile{demonstrations/mycommand1-mlb6.tex}{\texttt{mycommand1.tex} using \cref{lst:mycom-mlb6}}{lst:mycommand1-mlb6} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycom-mlb6.yaml}[MLB-TCB,width=\linewidth]{\texttt{mycom-mlb6.yaml}}{lst:mycom-mlb6} \end{cmhtcbraster} Note that a \lstinline!%! \emph{has} been added to the trailing first \lstinline!}!; this is because: \begin{itemize} \item while processing the \emph{first} argument, the trailing line break has been removed (\texttt{RCuBFinishesWithLineBreak} set to $-1$); \item while processing the \emph{second} argument, \texttt{latexindent.pl} finds that it does \emph{not} begin on its own line, and so because \texttt{LCuBStartsOnOwnLine} is set to $2$, it adds a comment, followed by a line break. \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} \cmhlistingsfromfile{demonstrations/nested-env.tex}{\texttt{nested-env.tex}}{lst:nested-env} Let's use the YAML settings given in \cref{lst:nested-env-mlb1-yaml}, which upon running the command \index{switches!-l demonstration} \index{switches!-m demonstration} \begin{commandshell} latexindent.pl -m -l=nested-env-mlb1.yaml nested-env.tex \end{commandshell} gives the output in \cref{lst:nested-env-mlb1}. \begin{cmhtcbraster}[raster column skip=.05\linewidth] \cmhlistingsfromfile{demonstrations/nested-env-mlb1.tex}{\texttt{nested-env.tex} using \cref{lst:nested-env-mlb1-yaml}}{lst:nested-env-mlb1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/nested-env-mlb1.yaml}[MLB-TCB,width=\linewidth]{\texttt{nested-env-mlb1.yaml}}{lst:nested-env-mlb1-yaml} \end{cmhtcbraster} In \cref{lst:nested-env-mlb1}, let's first of all note that both environments have received the appropriate (default) indentation; secondly, note that the poly-switch \texttt{EndStartsOnOwnLine} appears to have won the conflict, as \lstinline!\end{one}! has had its leading line break removed. \end{example} To understand it, let's talk about the three basic phases \label{page:phases}of \texttt{latexindent.pl}: \begin{enumerate} \item Phase 1: packing, in which code blocks are replaced with unique ids, working from \emph{the inside to the outside}, and then sequentially -- for example, in \cref{lst:nested-env}, the \texttt{two} environment is found \emph{before} the \texttt{one} environment; if the -m switch is active, then during this phase: \begin{itemize} \item line breaks at the beginning of the \texttt{body} can be added (if \texttt{BodyStartsOnOwnLine} is $1$ or $2$) or removed (if \texttt{BodyStartsOnOwnLine} is $-1$); \item line breaks at the end of the body can be added (if \texttt{EndStartsOnOwnLine} is $1$ or $2$) or removed (if \texttt{EndStartsOnOwnLine} is $-1$); \item line breaks after the end statement can be added (if \texttt{EndFinishesWithLineBreak} is $1$ or $2$). \end{itemize} \item Phase 2: indentation, in which white space is added to the begin, body, and end statements; \item Phase 3: unpacking, in which unique ids are replaced by their \emph{indented} code blocks; if the -m switch is active, then during this phase, \begin{itemize} \item line breaks before \texttt{begin} statements can be added or removed (depending upon \texttt{BeginStartsOnOwnLine}); \item line breaks after \emph{end} statements can be removed but \emph{NOT} added (see \texttt{EndFinishesWithLineBreak}). \end{itemize} \end{enumerate} With reference to \cref{lst:nested-env-mlb1}, this means that during Phase 1: \begin{itemize} \item the \texttt{two} environment is found first, and the line break ahead of the \lstinline!\end{two}! statement is removed because \texttt{EndStartsOnOwnLine} is set to $-1$. Importantly, because, \emph{at this stage}, \lstinline!\end{two}! \emph{does} finish with a line break, \texttt{EndFinishesWithLineBreak} causes no action. \item next, the \texttt{one} environment is found; the line break ahead of \lstinline!\end{one}! is removed because \texttt{EndStartsOnOwnLine} is set to $-1$. \end{itemize} The indentation is done in Phase 2; in Phase 3 \emph{there is no option to add a line break after the \lstinline!end! statements}. We can justify this by remembering that during Phase 3, the \texttt{one} environment will be found and processed first, followed by the \texttt{two} environment. If the \texttt{two} environment were to add a line break after the \lstinline!\end{two}! statement, then \texttt{latexindent.pl} would have no way of knowing how much indentation to add to the subsequent text (in this case, \lstinline!\end{one}!). \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} \cmhlistingsfromfile{demonstrations/nested-env-mlb2.tex}{\texttt{nested-env.tex} using \cref{lst:nested-env-mlb2}}{lst:nested-env-mlb2-output} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/nested-env-mlb2.yaml}[MLB-TCB,width=\linewidth]{\texttt{nested-env-mlb2.yaml}}{lst:nested-env-mlb2} \end{cmhtcbraster} During Phase 1: \begin{itemize} \item the \texttt{two} environment is found first, and the line break ahead of the \lstinline!\end{two}! statement is not changed because \texttt{EndStartsOnOwnLine} is set to $1$. Importantly, because, \emph{at this stage}, \lstinline!\end{two}! \emph{does} finish with a line break, \texttt{EndFinishesWithLineBreak} causes no action. \item next, the \texttt{one} environment is found; the line break ahead of \lstinline!\end{one}! is already present, and no action is needed. \end{itemize} The indentation is done in Phase 2, and then in Phase 3, the \texttt{one} environment is found and processed first, followed by the \texttt{two} environment. \emph{At this stage}, the \texttt{two} environment finds \texttt{EndFinishesWithLineBreak} is $-1$, so it removes the trailing line break; remember, at this point, \texttt{latexindent.pl} has completely finished with the \texttt{one} environment. \end{example} % arara: pdflatex: { files: [latexindent]} \section{The -r, -rv and -rr switches}\label{sec:replacements} \fancyhead[R]{\bfseries\thepage% \tikz[remember picture,overlay] { \node at (1,0){\includegraphics{logo-bw}}; } } You can instruct \texttt{latexindent.pl} to perform replacements/substitutions on your \announce{2019-07-13}{replacement mode switches} file by using any of the \texttt{-r}, \texttt{-rv} or \texttt{-rr} switches: \index{verbatim!rv, replacementrespectverb switch} \begin{itemize} \item the \texttt{-r} switch will perform indentation and replacements, not respecting verbatim code blocks; \item the \texttt{-rv} switch will perform indentation and replacements, and \emph{will} respect verbatim code blocks; \item the \texttt{-rr} switch will \emph{not} perform indentation, and will perform replacements not respecting verbatim code blocks. \end{itemize} We will demonstrate each of the \texttt{-r}, \texttt{-rv} and \texttt{-rr} switches, but a summary is given in \cref{tab:replacementswitches}. \begin{table}[!htb] \centering \caption{The replacement mode switches}\label{tab:replacementswitches} \begin{tabular}{rcc} \toprule switch & indentation? & respect verbatim? \\ \midrule \texttt{-r} & \faCheck & \faClose \\ \texttt{-rv} & \faCheck & \faCheck \\ \texttt{-rr} & \faClose & \faClose \\ \bottomrule \end{tabular} \end{table} The default value of the \texttt{replacements} field is shown in \cref{lst:replacements}; as with all of the other fields, you are encouraged to customise and change this as you see fit. The options in this field will \emph{only} be considered if the \texttt{-r}, \texttt{-rv} or \texttt{-rr} switches are active; when discussing YAML settings related to the replacement-mode switches, we will use the style given in \cref{lst:replacements}. \cmhlistingsfromfile[style=replacements]{../defaultSettings.yaml}[width=0.95\linewidth,before=\centering,replace-TCB]{\texttt{replacements}}{lst:replacements} The first entry within the \texttt{replacements} field is \texttt{amalgamate}, and is \emph{optional}; by default it is set to 1, so that replacements will be amalgamated from each settings file that you specify. As you'll see in the demonstrations that follow, there is no need to specify this field. You'll notice that, by default, there is only \emph{one} entry in the \texttt{replacements} field, but it can take as many entries as you would like; each one needs to begin with a \texttt{-} on its own line. \subsection{Introduction to replacements} Let's explore the action of the default settings, and then we'll demonstrate the feature with further examples. \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] \cmhlistingsfromfile{demonstrations/replace1.tex}{\texttt{replace1.tex}}{lst:replace1} \cmhlistingsfromfile{demonstrations/replace1-r1.tex}{\texttt{replace1.tex} default}{lst:replace1-r1} \end{cmhtcbraster} We note that in \cref{lst:replacements}, because \texttt{lookForThis} is set to 0, the specified replacement has \emph{not} been made, and there is no difference between \cref{lst:replace1,lst:replace1-r1}. If we \emph{do} wish to perform this replacement, then we can tweak the default settings of \vref{lst:replacements} by changing \texttt{lookForThis} to 1; we perform this action in \cref{lst:replace1-yaml}, and run the command \index{switches!-l demonstration} \index{switches!-r demonstration} \begin{commandshell} 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] \cmhlistingsfromfile{demonstrations/replace1-mod1.tex}{\texttt{replace1.tex} using \cref{lst:replace1-yaml}}{lst:replace1-mod1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/replace1.yaml}[replace-TCB]{\texttt{replace1.yaml}}{lst:replace1-yaml} \end{cmhtcbraster} 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. \subsection{The two types of replacements} There are two types of replacements: \begin{enumerate} \item \emph{string}-based replacements, which replace the string in \emph{this} with the string in \emph{that}. If you specify \texttt{this} and you do not specify \texttt{that}, then the \texttt{that} field will be assumed to be empty. \index{regular expressions!replacement switch, -r} \item \emph{regex}-based replacements, which use the \texttt{substitution} field. \end{enumerate} We will demonstrate both in the examples that follow. \texttt{latexindent.pl} chooses which type of replacement to make based on which fields have been specified; if the \texttt{this} field is specified, then it will make \emph{string}-based replacements, regardless of if \texttt{substitution} is present or not. \subsection{Examples of replacements} \begin{example} We begin with code given in \cref{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. 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} \cmhlistingsfromfile{demonstrations/colsep-mod0.tex}{\texttt{colsep.tex} using \cref{lst:colsep-yaml}}{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} \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. 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}. 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} 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}. \end{example} \begin{example} 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}. \cmhlistingsfromfile{demonstrations/displaymath.tex}{\texttt{displaymath.tex}}{lst:displaymath} We use the settings in \cref{lst:displaymath1} and run the command \index{switches!-l demonstration} \index{switches!-r demonstration} \begin{commandshell} latexindent.pl -r displaymath.tex -l=displaymath1.yaml \end{commandshell} to receive the output given in \cref{lst:displaymath-mod1}. \index{regular expressions!substitution field, equation} \begin{cmhtcbraster}[raster left skip=-3.75cm, raster right skip=-2cm,] \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} 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} \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}. \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} 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} 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}. \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} 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} \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}. \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} 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} \end{example} We note that: \begin{enumerate} \item in \cref{lst:verb1-mod1} indentation has been performed, and that the replacements specified in \cref{lst:verbatim1-yaml} have been performed, even within the verbatim code block; \item in \cref{lst:verb1-rv-mod1} indentation has been performed, but that the replacements have \emph{not} been performed within the verbatim environment, because the \texttt{rv} switch is active; \item in \cref{lst:verb1-rr-mod1} indentation has \emph{not} been performed, but that replacements have been performed, not respecting the verbatim code block. \end{enumerate} 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}. \cmhlistingsfromfile{demonstrations/amalg1.tex}{\texttt{amalg1.tex}}{lst:amalg1} 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} 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} \end{example} % arara: pdflatex: { files: [latexindent]} \section{The --lines switch}\label{sec:line-switch} \texttt{latexindent.pl} \announce{2021-09-16}{line switch demonstration} can operate on a \emph{selection} of lines of the file using the \texttt{--lines} or \texttt{-n} switch. \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}. The options for the \texttt{lines} switch are: \begin{itemize} \item line range, as in \texttt{--lines 3-7} \item single line, as in \texttt{--lines 5} \item multiple line ranges separated by commas, as in \texttt{--lines 3-5,8-10} \item negated line ranges, as in \texttt{--lines !3-5} which translates to \texttt{--lines 1-2,6-N}, where N is the number of lines in your file. \end{itemize} We demonstrate this feature, and the available variations in what follows. We will use the file in \cref{lst:myfile}. \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} 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} 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. \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} 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} 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. 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} 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. \end{example} \begin{example} 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} 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. \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} 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} 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. \end{example} \begin{example} \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} 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} \end{example} \begin{example} \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} 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} \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}. 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. 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} 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{example} % arara: pdflatex: { files: [latexindent]} \section{Fine tuning}\label{sec:finetuning} \texttt{latexindent.pl} operates by looking for the code blocks detailed in \vref{tab:code-blocks}. \announce{2019-07-13}{details of fine tuning of code blocks} The fine tuning of the details of such code blocks is controlled by the \texttt{fineTuning} field, detailed in \cref{lst:fineTuning}. This field is for those that would like to peek under the bonnet/hood and make some fine tuning to \texttt{latexindent.pl}'s operating. \index{warning!fine tuning} \index{regular expressions!fine tuning} \index{regular expressions!environments} \index{regular expressions!ifElseFi} \index{regular expressions!commands} \index{regular expressions!keyEqualsValuesBracesBrackets} \index{regular expressions!NamedGroupingBracesBrackets} \index{regular expressions!UnNamedGroupingBracesBrackets} \index{regular expressions!arguments} \index{regular expressions!modifyLineBreaks} \index{regular expressions!lowercase alph a-z} \index{regular expressions!uppercase alph A-Z} \index{regular expressions!numeric 0-9} \index{regular expressions!at least one +} \index{regular expressions!horizontal space \textbackslash{h}} \begin{warning} Making changes to the fine tuning may have significant consequences for your indentation scheme, proceed with caution! \end{warning} \begin{widepage} \cmhlistingsfromfile[style=fineTuning]{../defaultSettings.yaml}[width=.95\linewidth,before=\centering,enhanced jigsaw,breakable,yaml-TCB]{\texttt{fineTuning}}{lst:fineTuning} \end{widepage} The fields given in \cref{lst:fineTuning} are all \emph{regular expressions}. This manual is not intended to be a tutorial on regular expressions; you might like to read, for example, \cite{masteringregexp} for a detailed covering of the topic. We make the following comments with reference to \cref{lst:fineTuning}: \begin{enumerate} \item the \texttt{environments:name} field details that the \emph{name} of an environment can contain: \begin{enumerate} \item \texttt{a-z} lower case letters \item \texttt{A-Z} upper case letters \item \texttt{@} the \texttt{@} 'letter' \item \lstinline!\*! stars \item \texttt{0-9} numbers \item \lstinline!_! underscores \item \lstinline!\! backslashes \end{enumerate} \index{regular expressions!at least one +} The \texttt{+} at the end means \emph{at least one} of the above characters. \item the \texttt{ifElseFi:name} field: \begin{enumerate} \item \lstinline^@?^ means that it \emph{can possibly} begin with \lstinline^@^ \item followed by \texttt{if} \item followed by 0 or more characters from \texttt{a-z}, \texttt{A-Z} and \texttt{@} \item the \texttt{?} the end means \emph{non-greedy}, which means `stop the match as soon as possible' \end{enumerate} \item the \texttt{keyEqualsValuesBracesBrackets} contains some interesting syntax: \begin{enumerate} \item \lstinline!|! means `or' \item \lstinline^(?:(?<!\\)\{)^ the \lstinline^(?:...)^ uses a \emph{non-capturing} group -- you don't necessarily need to worry about what this means, but just know that for the \texttt{fineTuning} feature you should only ever use \emph{non}-capturing groups, and \emph{not} capturing groups, which are simply \lstinline!(...)! \item \lstinline^(?<!\\)\{)^ means a \lstinline^{^ but it can \emph{not} be immediately preceded by a \lstinline!\! \end{enumerate} \item in the \texttt{arguments:before} field \begin{enumerate} \item \lstinline^\d\h*^ means a digit (i.e. a number), followed by 0 or more horizontal spaces \item \lstinline^;?,?^ means \emph{possibly} a semi-colon, and possibly a comma \item \lstinline^\<.*?\>^ is designed for 'beamer'-type commands; the \lstinline^.*?^ means anything in between \lstinline^<...>^ \end{enumerate} \item the \texttt{modifyLineBreaks} field refers to fine tuning settings detailed in \vref{sec:modifylinebreaks}. In particular: \begin{enumerate} \item \texttt{betterFullStop} is in relation to the one sentence per line routine, detailed in \vref{sec:onesentenceperline} \item \texttt{doubleBackSlash} is in relation to the \texttt{DBSStartsOnOwnLine} and \texttt{DBSFinishesWithLineBreak} polyswitches surrounding double backslashes, see \vref{subsec:dbs} \item \texttt{comma} is in relation to the \texttt{CommaStartsOnOwnLine} and \texttt{CommaFinishesWithLineBreak} polyswitches surrounding commas in optional and mandatory arguments; see \vref{tab:poly-switch-mapping} \end{enumerate} \end{enumerate} It is not obvious from \cref{lst:fineTuning}, but each of the \texttt{follow}, \texttt{before} and \texttt{between} fields allow trailing comments, line breaks, and horizontal spaces between each character. \index{warning!capture groups} \begin{warning} For the \texttt{fineTuning} feature you should only ever use \emph{non}-capturing groups, such as \lstinline!(?:...)! and \emph{not} capturing groups, which are \lstinline!(...)! \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} 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} 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} \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} 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} 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} In particular, note that the settings in \cref{lst:fine-tuning2} specify that \texttt{NamedGroupingBracesBrackets} and \texttt{UnNamedGroupingBracesBrackets} can follow \texttt{"} and that we allow \lstinline!---! between arguments. \end{example} \begin{example} You can tweak the \texttt{fineTuning} using the \texttt{-y} switch, but to be sure to use quotes appropriately. For example, starting with the code in \cref{lst:finetuning3} and running the following command \begin{commandshell} latexindent.pl -m -y='modifyLineBreaks:oneSentencePerLine:manipulateSentences: 1, modifyLineBreaks:oneSentencePerLine:sentencesBeginWith:a-z: 1, fineTuning:modifyLineBreaks:betterFullStop: "(?:\.|;|:(?![a-z]))|(?:(?<!(?:(?: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} \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} \cmhlistingsfromfile{demonstrations/finetuning4.tex}{\texttt{finetuning4.tex}}{lst:finetuning4} 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} 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} \cmhlistingsfromfile{demonstrations/finetuning4-mod2.tex}{\texttt{finetuning4.tex} using \cref{lst:href2}}{lst:finetuning4-mod2} \end{widepage} 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 preceded 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} 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} 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} 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} \end{example} \begin{example} 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} 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} The output in \cref{lst:bib2-mod1} is not ideal, as the \texttt{=} symbol within the url field has been incorrectly used as an alignment delimiter. We address this by tweaking the \texttt{delimiterRegEx} field in \cref{lst:bibsettings2}. \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} 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 preceded} by either \texttt{v} or \texttt{spfreload}. \end{example} \begin{example} We can use the \texttt{fineTuning} settings to tweak how \texttt{latexindent.pl} finds trailing comments. \announce{2023-06-01}{fine tuning trailing comments demonstration} We begin with the file in \cref{lst:finetuning5} \cmhlistingsfromfile{demonstrations/finetuning5.tex}{\texttt{finetuning5.tex}}{lst:finetuning5} Using the settings in \cref{lst:fine-tuning3} and running the command \begin{commandshell} latexindent.pl finetuning5.tex -l=fine-tuning3.yaml \end{commandshell} gives the output in \cref{lst:finetuning5-mod1}. \begin{cmhtcbraster}[raster column skip=.01\linewidth] \cmhlistingsfromfile{demonstrations/finetuning5-mod1.tex}{\texttt{finetuning5-mod1.tex}}{lst:finetuning5-mod1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/fine-tuning3.yaml}[yaml-TCB]{\texttt{finetuning3.yaml}}{lst:fine-tuning3} \end{cmhtcbraster} The settings in \cref{lst:fine-tuning3} detail that trailing comments can \emph{not} be followed by a single space, and then the text `end'. This means that the \texttt{specialBeginEnd} routine will be able to find the pattern \lstinline!% end! as the \texttt{end} part. The trailing comments \texttt{123} and \texttt{456} are still treated as trailing comments. \end{example} \begin{example} We can use the \texttt{fineTuning} settings to tweak how \texttt{latexindent.pl} finds environments. We begin with the file in \cref{lst:finetuning6}.\announce{2023-10-13}{fineTuning environments} \cmhlistingsfromfile{demonstrations/finetuning6.tex}{\texttt{finetuning6.tex}}{lst:finetuning6} Using the settings in \cref{lst:fine-tuning4} and running the command \begin{commandshell} latexindent.pl finetuning6.tex -m -l=fine-tuning4.yaml \end{commandshell} gives the output in \cref{lst:finetuning6-mod1}. \begin{cmhtcbraster}[raster column skip=.01\linewidth, raster left skip=-3.5cm, raster force size=false, raster column 1/.style={add to width=-.1\textwidth}, raster column 2/.style={add to width=-.3\textwidth}, ] \cmhlistingsfromfile{demonstrations/finetuning6-mod1.tex}{\texttt{finetuning6-mod1.tex}}{lst:finetuning6-mod1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/fine-tuning4.yaml}[MLB-TCB]{\texttt{fine-tuning4.yaml}}{lst:fine-tuning4} \end{cmhtcbraster} By using the settings in \cref{lst:fine-tuning4} it means that the default poly-switch location of \texttt{BodyStartsOnOwnLine} for environments (denoted $\BodyStartsOnOwnLine$ in \cref{tab:poly-switch-mapping}) has been overwritten so that it is \emph{after} the \texttt{label} command. Referencing \cref{lst:fine-tuning4}, unless both \texttt{begin} and \texttt{end} are specified, then the default value of \texttt{name} will be used. \end{example} % arara: pdflatex: { files: [latexindent]} \section{Conclusions and known limitations}\label{sec:knownlimitations} There are a number of known limitations of the script, and almost certainly quite a few that are \emph{unknown}! The known issues include: \begin{description} \item[multicolumn alignment] when working with code blocks in which multicolumn commands overlap, the algorithm can fail; see \vref{lst:tabular2-mod2}. \item[textWrap after] when operating with \texttt{indentRules} (see \vref{sec:noadd-indent-rules}) may not always cooperate with one another; if you have a specific example that does not work, please report it to \cite{latexindent-home}. \item[efficiency] particularly when the \texttt{-m} switch is active, as this adds many checks and processes. The current implementation relies upon finding and storing \emph{every} code block (see the discussion on \cpageref{page:phases}); I hope that, in a future version, only \emph{nested} code blocks will need to be stored in the `packing' phase, and that this will improve the efficiency of the script. \end{description} You can run \texttt{latexindent} on any file; \announce{2019-07-13}*{ability to call latexindent on any file} if you don't specify an extension, then the extensions that you specify in \lstinline[breaklines=true]!fileExtensionPreference! (see \vref{lst:fileExtensionPreference}) will be consulted. If you find a case in which the script struggles, please feel free to report it at \cite{latexindent-home}, and in the meantime, consider using a \texttt{noIndentBlock} (see \cpageref{lst:noIndentBlock}).% I hope that this script is useful to some; if you find an example where the script does not behave as you think it should, the best way to contact me is to report an issue on \cite{latexindent-home}; otherwise, feel free to find me on the \url{http://tex.stackexchange.com/users/6621/cmhughes}. \nocite{*} \section{References} \printbibliography[heading=subbibnumbered,title={perl-related links},keyword=perl] \printbibliography[heading=subbibnumbered,title={conda-related links},keyword=conda] \index{conda} \printbibliography[heading=subbibnumbered,title={VScode-related links},keyword=vscode] \index{VSCode} \printbibliography[heading=subbibnumbered,title={Other links},keyword=other] \index{pre-commit} \index{MiKTeX} \index{contributors} \printbibliography[env=specialbib,heading=subbibnumbered,title={Contributors (in chronological order)\label{sec:contributors}},keyword=contributor] % arara: pdflatex: { files: [latexindent]} \appendix \section{Required Perl modules}\label{sec:requiredmodules} If you intend to use \texttt{latexindent.pl} and \emph{not} one of the supplied standalone executable files (\texttt{latexindent.exe} is available for Windows users without Perl, see \cref{subsubsec:latexindent:exe}), then you will need a few standard 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}. \begin{cmhlistings}[style=tcblatex,language=Perl]{\texttt{helloworld.pl}}{lst:helloworld} #!/usr/bin/perl use strict; # | use warnings; # | use Encode; # | use Getopt::Long; # | use Data::Dumper; # these modules are use List::Util qw(max); # generally part use PerlIO::encoding; # of a default perl distribution use open ':std', ':encoding(UTF-8)';# | use Text::Wrap; # | use Text::Tabs; # | use FindBin; # | use File::Copy; # | use File::Basename; # | use File::Path; # | use File::HomeDir; # <--- typically requires install via cpanm use YAML::Tiny; # <--- typically requires install via cpanm print "hello world"; exit; \end{cmhlistings} \subsection{Module installer script}\label{sec:module-installer} \announce{2018-01-13}{perl module helper script} \texttt{latexindent.pl} ships with a helper script that will install any missing \texttt{perl} modules on your system; if you run \begin{commandshell} perl latexindent-module-installer.pl \end{commandshell} or \begin{dosprompt} perl latexindent-module-installer.pl \end{dosprompt} then, once you have answered \texttt{Y}, the appropriate modules will be installed onto your distribution. \subsection{Manually installing modules}\label{sec:manual-module-instal} Manually installing the modules given in \cref{lst:helloworld} will vary depending on your operating system and \texttt{Perl} distribution. \subsubsection{Linux} \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.40.0 perlbrew switch perl-5.40.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 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} \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} \paragraph{Ubuntu: users without perl} \texttt{latexindent-linux} is a standalone executable \announce{2022-10-30}{Linux Ubuntu standalone executable} for Ubuntu Linux (and therefore does not require a Perl distribution) and caches copies of the Perl modules onto your system. It is available from \cite{latexindent-home}. \index{latexindent-linux} \index{linux} \index{TeXLive} \paragraph{Arch-based distributions} \texttt{latexindent} is included in Arch-packaged TeX Live, and can be installed by: \begin{commandshell} sudo pacman -S texlive-binextra perl-yaml-tiny perl-file-homedir \end{commandshell} To enable optional \texttt{--GCString} switch, install \texttt{perl-unicode-linebreak}: \begin{commandshell} sudo pacman -S perl-unicode-linebreak \end{commandshell} \paragraph{Alpine} If you are using Alpine, some \texttt{Perl} modules are not build-compatible with Alpine, but replacements are available through \texttt{apk}. For example, you might use the commands given in \cref{lst:alpine-install}; thanks to \cite{jun-sheaf} for providing these details. \begin{cmhlistings}[style=tcblatex,language=Bash]{\texttt{alpine-install.sh}}{lst:alpine-install} # Installing perl apk --no-cache add miniperl perl-utils # Installing incompatible latexindent perl dependencies via apk apk --no-cache add \ perl-log-dispatch \ perl-namespace-autoclean \ perl-specio \ perl-unicode-linebreak # Installing remaining latexindent perl dependencies via cpan apk --no-cache add curl wget make ls /usr/share/texmf-dist/scripts/latexindent cd /usr/local/bin && \ curl -L https://cpanmin.us/ -o cpanm && \ chmod +x cpanm cpanm -n App::cpanminus cpanm -n File::HomeDir cpanm -n Params::ValidationCompiler cpanm -n YAML::Tiny \end{cmhlistings} Users of NixOS might like to see \href{https://github.com/cmhughes/latexindent.pl/issues/222}{https://github.com/cmhughes/latexindent.pl/issues/222} for tips. \subsubsection{Mac} Users of the Macintosh operating system might like to explore the following commands, for example: \begin{commandshell} brew install perl brew install cpanm cpanm YAML::Tiny cpanm File::HomeDir \end{commandshell} Alternatively, \begin{commandshell} brew install latexindent \end{commandshell} \texttt{latexindent-macos} is a standalone executable \announce{2022-10-30}{macOS standalone executable} for macOS (and therefore does not require a Perl distribution) and caches copies of the Perl modules onto your system. It is available from \cite{latexindent-home}. \index{latexindent-macos} \index{macOS} \index{TeXLive} \subsubsection{Windows} Strawberry Perl users on Windows might use \texttt{CPAN client}. All of the modules are readily available on CPAN \cite{cpan}. \texttt{indent.log} will contain details of the location of the Perl modules on your system. \texttt{latexindent.exe} is a standalone executable for Windows (and therefore does not require a Perl distribution) and caches copies of the Perl modules onto your system; if you wish to see where they are cached, use the \texttt{trace} option, e.g \begin{dosprompt} latexindent.exe -t myfile.tex \end{dosprompt} \subsection{The GCString switch}\label{subsec:the-GCString} If you find that the \texttt{lookForAlignDelims} (as in \cref{subsec:align-at-delimiters}) does not work correctly for your language, then you may wish to use the \texttt{Unicode::GCString} module \announce{2022-03-25}{Unicode::GCString}. \index{perl!Unicode GCString module} \index{switches!--GCString demonstration} 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} Note: this switch does \emph{nothing} for \texttt{latexindent.exe} which loads the module by default. Users of \texttt{latexindent.exe} should not see any difference in behaviour whether they use this switch or not, as \texttt{latexindent.exe} loads the \texttt{Unicode::GCString} module. \section{Updating the path variable}\label{sec:updating-path} \texttt{latexindent.pl} has a few scripts (available at \cite{latexindent-home}) that can update the \texttt{path} variables. Thank you to \cite{jasjuang} for this feature. If you're on a Linux or Mac machine, then you'll want \texttt{CMakeLists.txt} from \cite{latexindent-home}. \subsection{Add to path for Linux} To add \texttt{latexindent.pl} to the path for Linux, follow these steps: \begin{enumerate} \item download \texttt{latexindent.pl} and its associated modules, \texttt{defaultSettings.yaml}, to your chosen directory from \cite{latexindent-home} ; \item within your directory, create a directory called \texttt{path-helper-files} and download \texttt{CMakeLists.txt} and \lstinline!cmake_uninstall.cmake.in! from \cite{latexindent-home}/path-helper-files to this directory; \item 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 mkdir build && cd build 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} \item download \texttt{latexindent.exe}, \texttt{defaultSettings.yaml}, \texttt{add-to-path.bat} from \cite{latexindent-home} to your chosen directory; \item open a command prompt and run the following command to see what is \emph{currently} in your \lstinline!%path%! variable; \begin{dosprompt} echo %path% \end{dosprompt} \item right click on \texttt{add-to-path.bat} and \emph{Run as administrator}; \item log out, and log back in; \item open a command prompt and run \begin{dosprompt} echo %path% \end{dosprompt} to check that the appropriate directory has been added to your \lstinline!%path%!. \end{enumerate} To \emph{remove} the directory from your \lstinline!%path%!, run \texttt{remove-from-path.bat} as administrator. \section{Batches of files}\label{sec:batches} You can \announce{2022-03-25}{batches of files details} instruct \texttt{latexindent.pl} to operate on multiple files. For example, the following calls are all valid \begin{commandshell} latexindent.pl myfile1.tex latexindent.pl myfile1.tex myfile2.tex latexindent.pl myfile*.tex \end{commandshell} We note the following features of the script in relation to the switches detailed in \cref{sec:how:to:use}. \subsection{location of indent.log} If the \texttt{-c} switch is \emph{not} active, then \texttt{indent.log} goes to the directory of the final file called. If the \texttt{-c} switch \emph{is} active, then \texttt{indent.log} goes to the specified directory. \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. More generally, if the \texttt{-o} switch does \emph{not} have a \texttt{+} symbol at the beginning, then the \texttt{-o} switch will be ignored, and is turned it off. For example \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} This behaves as expected by attempting to operate on the line numbers specified for each file. See the examples in \cref{sec:line-switch}. \subsection{interaction with check switches} 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; \item exit code 1 means that the text from \emph{at least one} of the files been file changed. \end{itemize} The interaction with \texttt{checkv} switch is as in the check switch, but with verbose output. \subsection{when a file does not exist} What happens if one of the files can not be operated upon? \begin{itemize} \item if at least one of the files does not exist and \texttt{latexindent.pl} has been called to act upon multiple files, then the exit code is 3; note that \texttt{latexindent.pl} will try to operate on each file that it is called upon, and will not exit with a fatal message in this case; \item if at least one of the files can not be read and \texttt{latexindent.pl} has been called to act upon multiple files, then the exit code is 4; note that \texttt{latexindent.pl} will try to operate on each file that it is called upon, and will not exit with a fatal message in this case; \item if \texttt{latexindent.pl} has been told to operate on multiple files, and some do not exist and some cannot be read, then the exit code will be either 3 or 4, depending upon which it scenario it encountered most recently. \end{itemize} \section{latexindent-yaml-schema.json} \texttt{latexindent.pl} \announce{2022-01-02}{latexindent-yaml-schema.json} ships with \texttt{latexindent-yaml-schema.json} which might help you when constructing your YAML files. \index{json!schema for YAML files} \subsection{VSCode demonstration} To use \texttt{latexindent-yaml-schema.json} with \texttt{VSCode}, you can use the following steps: \index{VSCode} \index{json!VSCode} \begin{enumerate} \item download \texttt{latexindent-yaml-schema.json} from the \texttt{documentation} folder of \cite{latexindent-home}, save it in whichever directory you would like, noting it for reference; \item following the instructions from \cite{vscode-yaml-demo}, for example, you should install the VSCode YAML extension \cite{vscode-yaml-extentions}; \item set up your \texttt{settings.json} file using the directory you saved the file by adapting \cref{lst:settings.json}; on my Ubuntu laptop this file lives at \texttt{/home/cmhughes/.config/Code/User/settings.json}. \end{enumerate} \begin{widepage} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/settings.json}[yaml-TCB]{\texttt{settings.json}}{lst:settings.json} \end{widepage} Alternatively, if you would prefer not to download the json file, you might be able to use an adapted version of \cref{lst:settings-alt.json}. \begin{widepage} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/settings-alt.json}[yaml-TCB]{\texttt{settings-alt.json}}{lst:settings-alt.json} \end{widepage} Finally, if your TeX distribution is up to date, then \texttt{latexindent-yaml-schema.json} \emph{should} be in the documentation folder of your installation, so an adapted version of \cref{lst:settings-alt1.json} may work. \begin{widepage} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/settings-alt1.json}[yaml-TCB]{\texttt{settings-alt1.json}}{lst:settings-alt1.json} \end{widepage} If you have details of how to implement this schema in other editors, please feel encouraged to contribute to this documentation. \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}. \index{conda} You can get a conda installation for example from \cite{conda} or from \cite{anacoda}. \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 conda install latexindent.pl -c conda-forge conda info --envs 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 Repository}. \subsection{Sample docker installation on Ubuntu} To pull the image and show \texttt{latexindent}'s help on Ubuntu: \begin{cmhlistings}[style=tcblatex,language=Bash]{\texttt{docker-install.sh}}{lst:docker-install} # setup docker if not already installed if ! command -v docker &> /dev/null; then sudo apt install docker.io -y sudo groupadd docker sudo gpasswd -a "$USER" docker sudo systemctl restart docker newgrp docker fi # download image and execute docker pull ghcr.io/cmhughes/latexindent.pl docker run ghcr.io/cmhughes/latexindent.pl -h \end{cmhlistings} Once I have run the above, on subsequent logins I run \begin{cmhlistings}[style=tcblatex,language=Bash]{\texttt{docker-install.sh}}{lst:docker-install-subsequent} newgrp docker docker run ghcr.io/cmhughes/latexindent.pl -h \end{cmhlistings} \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} \section{pre-commit} Users of \texttt{.git} may be interested \announce{2022-01-21}{pre-commit for latexindent.pl} in exploring the \texttt{pre-commit} tool \cite{pre-commithome}, which is supported by \texttt{latexindent.pl}. Thank you to \cite{tdegeusprecommit} for contributing this feature, and to \cite{holzhausprecommit} for their contribution to it. To use the \texttt{pre-commit} tool, you will need to install \texttt{pre-commit}; sample instructions for Ubuntu are given in \cref{sec:pre-commit-ubuntu}. Once installed, there are two ways to use \texttt{pre-commit}: using \texttt{CPAN} or using \texttt{conda}, detailed in \cref{sec:pre-commit-cpan} and \cref{sec:pre-commit-conda} respectively. \subsection{Sample pre-commit installation on Ubuntu}\label{sec:pre-commit-ubuntu} On Ubuntu I ran the following command: \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} ... export PATH=$PATH:/home/cmhughes/.local/bin \end{cmhlistings} \subsection{pre-commit defaults} The default values that are employed by \texttt{pre-commit} are shown in \cref{lst:.pre-commit-yaml-default}. \index{pre-commit!default} \cmhlistingsfromfile[style=yaml-LST]{../.pre-commit-hooks.yaml}[yaml-TCB]{\texttt{.pre-commit-hooks.yaml} (default)}{lst:.pre-commit-yaml-default} In particular, the decision has deliberately been made (in collaboration with \cite{holzhausprecommit}) to have the default to employ the following switches: \texttt{overwriteIfDifferent}, \texttt{silent}, \texttt{local}; this is detailed in the lines that specify \texttt{args} in \cref{lst:.pre-commit-yaml-default}. \index{pre-commit!warning} \index{warning!pre-commit} \begin{warning} Users of \texttt{pre-commit} will, by default, have the \texttt{overwriteIfDifferent} switch employed. It is assumed that such users have version control in place, and are intending to overwrite their files. \end{warning} \subsection{pre-commit using CPAN}\label{sec:pre-commit-cpan} To use \texttt{latexindent.pl} with \texttt{pre-commit}, create the file \texttt{.pre-commit-config.yaml} given in \cref{lst:.pre-commit-config.yaml-cpan} in your git-repository. \index{cpan} \index{git} \index{pre-commit!cpan} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/pre-commit-config-cpan.yaml}[yaml-TCB]{\texttt{.pre-commit-config.yaml} (cpan)}{lst:.pre-commit-config.yaml-cpan} Once created, you should then be able to run the following command: \begin{commandshell} pre-commit run --all-files \end{commandshell} A few notes about \cref{lst:.pre-commit-config.yaml-cpan}: \begin{itemize} \item the settings given in \cref{lst:.pre-commit-config.yaml-cpan} instruct \texttt{pre-commit} to use \texttt{CPAN} to get dependencies; \item this requires \texttt{pre-commit} and \texttt{perl} to be installed on your system; \item 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]}. \end{itemize} Naturally you can add options, or omit \texttt{-s} and \texttt{-w}, according to your preference. \subsection{pre-commit using conda}\label{sec:pre-commit-conda} You can also rely on \texttt{conda} (detailed in \cref{sec:app:conda}) instead of \texttt{CPAN} for all dependencies, including \texttt{latexindent.pl} itself. \index{conda} \index{git} \index{pre-commit!conda} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/pre-commit-config-conda.yaml}[yaml-TCB]{\texttt{.pre-commit-config.yaml} (conda)}{lst:.pre-commit-config.yaml-conda} Once created, you should then be able to run the following command: \begin{commandshell} pre-commit run --all-files \end{commandshell} A few notes about \cref{lst:.pre-commit-config.yaml-cpan}: \begin{itemize} \item the settings given in \cref{lst:.pre-commit-config.yaml-conda} instruct \texttt{pre-commit} to use \texttt{conda} to get dependencies; \item this requires \texttt{pre-commit} and \texttt{conda} to be installed on your system; \item 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]}. \end{itemize} \subsection{pre-commit using docker}\label{sec:pre-commit-docker} You can also rely on \texttt{docker} (detailed in \cref{sec:app:docker}) instead of \texttt{CPAN} for all dependencies, including \texttt{latexindent.pl} itself. \index{docker} \index{git} \index{pre-commit!docker} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/pre-commit-config-docker.yaml}[yaml-TCB]{\texttt{.pre-commit-config.yaml} (docker)}{lst:.pre-commit-config.yaml-docker} Once created, you should then be able to run the following command: \begin{commandshell} 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 \texttt{pre-commit} to use \texttt{docker} to get dependencies; \item this requires \texttt{pre-commit} and \texttt{docker} to be installed on your system; \item 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]}. \end{itemize} \subsection{pre-commit example using -l, -m switches} Let's consider a small example, with local \texttt{latexindent.pl} settings in \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} onlyOneBackUp: 1 modifyLineBreaks: oneSentencePerLine: manipulateSentences: 1 \end{cmhlistings} and \texttt{.pre-commit-config.yaml} as in \cref{lst:.latexindent.yaml-switches}: \cmhlistingsfromfile[style=yaml-LST]{demonstrations/pre-commit-config-demo.yaml}[yaml-TCB]{\texttt{.pre-commit-config.yaml} (demo)}{lst:.latexindent.yaml-switches} Now running \begin{commandshell} pre-commit run --all-files \end{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} \end{example} \section{indentconfig options}\label{app:indentconfig:options} This section describes the possible locations for the main configuration file, discussed in \cref{sec:indentconfig}. Thank you to \cite{nehctargl} for this contribution. \announce{2023-01-01}{indentconfig location options} The possible locations of \texttt{indentconfig.yaml} are read one after the other, and reading stops when a valid file is found in one of the paths. Before stating the list, we give summarise in \cref{tab:environment:summary}. \begin{table}[!htb] \centering \caption{indentconfig environment variable summaries} \label{tab:environment:summary} \begin{tabular}{lllll} \toprule environment variable & type & Linux & macOS & Windows \\ \midrule LATEXINDENT\_CONFIG & full path to file & \faCheck & \faCheck & \faCheck \\ XDG\_CONFIG\_HOME & directory path & \faCheck & \faClose & \faClose \\ LOCALAPPDATA & directory path & \faClose & \faClose & \faCheck \\ \bottomrule \end{tabular} \end{table} The following list shows the checked options and is sorted by their respective priority. It uses capitalized and with a dollar symbol prefixed names (e.g. \texttt{\$LATEXINDENT\_CONFIG}) to symbolize environment variables. In addition to that the variable name \texttt{\$homeDir} is used to symbolize your home directory. \begin{enumerate} \item The value of the environment variable \texttt{\$LATEXINDENT\_CONFIG} is treated as highest priority source for the path to the configuration file. \item The next options are dependent on your operating system: \begin{itemize} \item Linux: \begin{enumerate} \item The file at \texttt{\$XDG\_CONFIG\_HOME/latexindent/indentconfig.yaml} \item The file at \texttt{\$homeDir/.config/latexindent/indentconfig.yaml} \end{enumerate} \item Windows: \begin{enumerate} \item The file at \texttt{\$LOCALAPPDATA\textbackslash{}latexindent\textbackslash{}indentconfig.yaml} \item The file at \texttt{\$homeDir\textbackslash{}AppData\textbackslash{}Local\textbackslash{}latexindent\textbackslash{}indentconfig.yaml} \end{enumerate} \item Mac: \begin{enumerate} \item The file at \texttt{\$homeDir/Library/Preferences/latexindent/indentconfig.yaml} \end{enumerate} \end{itemize} \item The file at \texttt{\$homeDir/indentconfig.yaml} \item The file at \texttt{\$homeDir/.indentconfig.yaml} \end{enumerate} \subsection{Why to change the configuration location} This is mostly a question about what you prefer, some like to put all their configuration files in their home directory (see \texttt{\$homeDir} above), whilst some like to sort their configuration. And if you don't care about it, you can just continue using the same defaults. \subsection{How to change the configuration location} This depends on your preferred location, if, for example, you would like to set a custom location, you would have to change the \texttt{\$LATEXINDENT\_CONFIG} environment variable. Although the following example only covers \texttt{\$LATEXINDENT\_CONFIG}, the same process can be applied to \texttt{\$XDG\_CONFIG\_HOME} or \texttt{\$LOCALAPPDATA} because both are environment variables. You just have to change the path to your chosen configuration directory (e.g. \texttt{\$homeDir/.config} or \texttt{\$homeDir\textbackslash{}AppData\textbackslash{}Local} on Linux or Windows respectively) \subsubsection{Linux} To change \texttt{\$LATEXINDENT\_CONFIG} on Linux you can run the following command in a terminal after changing the path: \begin{widepage} \begin{commandshell} echo 'export LATEXINDENT_CONFIG="/home/cmh/latexindent-config.yaml"' >> ~/.profile \end{commandshell} \end{widepage} Context: This command adds the given line to your \texttt{.profile} file (which is commonly stored in \texttt{\$HOME/.profile}). All commands in this file a run after login, so the environment variable will be set after your next login. You can check the value of \texttt{\$LATEXINDENT\_CONFIG} by typing \begin{commandshell} echo $LATEXINDENT_CONFIG /home/cmh/latexindent-config.yaml \end{commandshell} Linux users interested in \texttt{\$XDG\_CONFIG\_HOME} can explore variations of the following commands \begin{commandshell} echo $XDG_CONFIG_HOME echo ${XDG_CONFIG_HOME:=$HOME/.config} echo $XDG_CONFIG_HOME mkdir /home/cmh/.config/latexindent touch /home/cmh/.config/latexindent/indentconfig.yaml \end{commandshell} \subsubsection{Windows} To change \texttt{\$LATEXINDENT\_CONFIG} on Windows you can run the following command in \texttt{powershell.exe} after changing the path: \begin{widepage} \begin{dosprompt} [Environment]::SetEnvironmentVariable ("LATEXINDENT_CONFIG", "\your\config\path", "User") \end{dosprompt} \end{widepage} This sets the environment variable for every user session. \subsubsection{Mac} To change \texttt{\$LATEXINDENT\_CONFIG} on macOS you can run the following command in a terminal after changing the path: \begin{commandshell} echo 'export LATEXINDENT_CONFIG="/your/config/path"' >> ~/.profile \end{commandshell} Context: This command adds the line to your \texttt{.profile} file (which is commonly stored in \texttt{\$HOME/.profile}). All commands in this file a run after login, so the environment variable will be set after your next login. \section{paths demonstration}\label{sec:appendix:paths} As detailed in \vref{subsec:indentconfig} \announce*{2024-04-28}{nested paths demonstration}, the \texttt{paths} field can be specified in any of your \texttt{YAML} files. We will use the file in \cref{lst:paths-demo} for demonstration in what follows. \cmhlistingsfromfile*{demonstrations/paths-demo.tex}{\texttt{paths-demo.tex}}{lst:paths-demo} \begin{example} Consider the settings given in \cref{lst:path1-yaml} and \cref{lst:path2-yaml}. \begin{cmhtcbraster}[raster column skip=.1\linewidth] \cmhlistingsfromfile*[style=yaml-LST]{demonstrations/path1.yaml}[yaml-TCB]{\texttt{path1.yaml}}{lst:path1-yaml} \cmhlistingsfromfile*[style=yaml-LST,showspaces=true]{demonstrations/path2.yaml}[yaml-TCB]{\texttt{path2.yaml}}{lst:path2-yaml} \end{cmhtcbraster} Upon calling \begin{commandshell} latexindent.pl -l=path1.yaml paths-demo.tex \end{commandshell} then we will receive the output given in \cref{lst:paths-demo-mod1}. \cmhlistingsfromfile*[showspaces=true]{demonstrations/paths-demo-mod1.tex}{\texttt{paths-demo-mod1.tex}}{lst:paths-demo-mod1} We note that the settings from \cref{lst:path2-yaml} have been called from \cref{lst:path1-yaml}. On inspection of \texttt{indent.log} from the above call, we see the details of this part of the process given in \cref{lst:path-test1:txt}. \cmhlistingsfromfile*{demonstrations/path-test1.txt}{\texttt{path-test1.txt}}{lst:path-test1:txt} \end{example} \begin{example} Consider the settings given in \cref{lst:path3-yaml} to \cref{lst:path5-yaml}. \begin{cmhtcbraster}[raster columns=3, raster left skip=-3.5cm, raster right skip=-2cm, raster column skip=.03\linewidth] \cmhlistingsfromfile*[style=yaml-LST]{demonstrations/path3.yaml}[yaml-TCB]{\texttt{path3.yaml}}{lst:path3-yaml} \cmhlistingsfromfile*[style=yaml-LST,showspaces=true]{demonstrations/path4.yaml}[yaml-TCB]{\texttt{path4.yaml}}{lst:path4-yaml} \cmhlistingsfromfile*[style=yaml-LST,showspaces=true]{demonstrations/path5.yaml}[yaml-TCB]{\texttt{path5.yaml}}{lst:path5-yaml} \end{cmhtcbraster} Upon calling \begin{commandshell} latexindent.pl -l=path3.yaml paths-demo.tex \end{commandshell} then we will receive the output given in \cref{lst:paths-demo-mod3}. \cmhlistingsfromfile*[showspaces=true]{demonstrations/paths-demo-mod3.tex}{\texttt{paths-demo-mod3.tex}}{lst:paths-demo-mod3} We see that \texttt{path3.yaml} calls \texttt{path4.yaml} which in turn calls \texttt{path5.yaml}. On inspection of \texttt{indent.log} from the above call, we see the details of this part of the process given in \cref{lst:path-test3:txt}. \cmhlistingsfromfile*{demonstrations/path-test3.txt}{\texttt{path-test3.txt}}{lst:path-test3:txt} \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. \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} \hfill \begin{minipage}{.6\linewidth} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/logfile-prefs1.yaml}[yaml-TCB]{\texttt{logfile-prefs1.yaml}}{lst:logfile-prefs1-yaml} \end{minipage} If we run the following command (noting that \texttt{-t} is active) \begin{commandshell} latexindent.pl -t -l=logfile-prefs1.yaml simple.tex \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} +++++ TRACE: environment found: myenv No ancestors found for myenv Storing settings for myenvenvironments indentRulesGlobal specified (0) for environments, ... Using defaultIndent for myenv Putting linebreak after replacementText for myenv looking for COMMANDS and key = {value} TRACE: Searching for commands with optional and/or mandatory arguments AND key = {value} looking for SPECIAL begin/end TRACE: Searching myenv for special begin/end (see specialBeginEnd) TRACE: Searching myenv for optional and mandatory arguments ... no arguments found ----- \end{cmhlistings} Notice that the information given about \texttt{myenv} is `framed' using \texttt{+++++} and \lstinline!-----! respectively. \end{example} \section{Encoding}\label{app:encoding} When using latexindent in different ways on different systems, the range of characters supported by its switches/flags/options (see \vref{sec:commandline}) may vary. For the Windows executable file \texttt{latexindent.exe}, its options support UTF-8 characters. For the Windows Perl script \texttt{latexindent.pl}, its option switch supports the characters supported by the encoding corresponding to the system code page. You can check the system code page by running the following command in either \texttt{cmd.exe} or \texttt{powershell.exe}: \begin{dosprompt} chcp \end{dosprompt} which may receive the following result \begin{dosprompt} Active code page: 936 \end{dosprompt} and then the characters supported by the code page can be found in \href{Microsoft's code page identifier table}{https://learn.microsoft.com/en-us/windows/win32/intl/code-page-identifiers}. For example, the characters supported by the encoding corresponding to code page 936 are: ANSI/OEM Simplified Chinese (PRC, Singapore); Chinese Simplified (GB2312). For Ubuntu Linux and macOS users, whether using the Perl script or the executable file, the options support UTF-8 characters. \section{dos2unix linebreak adjustment} \yamltitle{dos2unixlinebreaks}*{integer} If you use \texttt{latexindent.pl} on a dos-based Windows file on Linux \announce{2021-06-19}{dos2unix linebreaks} then you may find that trailing horizontal space is not removed as you hope. In such a case, you may wish to try setting \texttt{dos2unixlinebreaks} to 1 and employing, for example, the following command. \begin{commandshell} latexindent.pl -y="dos2unixlinebreaks:1" myfile.tex \end{commandshell} See \cite{bersbersbers} for further dertails. \section{Differences from Version 2.2 to 3.0}\label{app:differences} There are a few (small) changes to the interface when comparing Version 2.2 to Version 3.0. Explicitly, in previous versions you might have run, for example, \index{switches!-o demonstration} \begin{commandshell} latexindent.pl -o myfile.tex outputfile.tex \end{commandshell} whereas in Version 3.0 you would run any of the following, for example, \index{switches!-o demonstration} \begin{commandshell} latexindent.pl -o=outputfile.tex myfile.tex latexindent.pl -o outputfile.tex myfile.tex latexindent.pl myfile.tex -o outputfile.tex latexindent.pl myfile.tex -o=outputfile.tex latexindent.pl myfile.tex -outputfile=outputfile.tex latexindent.pl myfile.tex -outputfile outputfile.tex \end{commandshell} noting that the \emph{output} file is given \emph{next to} the \texttt{-o} switch. The fields given in \cref{lst:obsoleteYaml} are \emph{obsolete} from Version 3.0 onwards. \cmhlistingsfromfile[style=yaml-LST]{demonstrations/obsolete.yaml}[yaml-obsolete]{Obsolete YAML fields from Version 3.0}{lst:obsoleteYaml} There is a slight difference when specifying indentation after headings; specifically, we now write \texttt{indentAfterThisHeading} instead of \texttt{indent}. See \cref{lst:indentAfterThisHeadingOld,lst:indentAfterThisHeadingNew} \begin{minipage}{.45\textwidth} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/indentAfterThisHeadingOld.yaml}[yaml-TCB]{\texttt{indentAfterThisHeading} in Version 2.2}{lst:indentAfterThisHeadingOld} \end{minipage}% \hfill \begin{minipage}{.45\textwidth} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/indentAfterThisHeadingNew.yaml}[yaml-TCB]{\texttt{indentAfterThisHeading} in Version 3.0}{lst:indentAfterThisHeadingNew} \end{minipage}% To specify \texttt{noAdditionalIndent} for display-math environments in Version 2.2, you would write YAML as in \cref{lst:noAdditionalIndentOld}; as of Version 3.0, you would write YAML as in \cref{lst:indentAfterThisHeadingNew1} or, if you're using \texttt{-m} switch, \cref{lst:indentAfterThisHeadingNew2}. \index{specialBeginEnd!update to displaymath V3.0} \begin{minipage}{.45\textwidth} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/noAddtionalIndentOld.yaml}[yaml-TCB]{\texttt{noAdditionalIndent} in Version 2.2}{lst:noAdditionalIndentOld} \end{minipage}% \hfill \begin{minipage}{.45\textwidth} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/noAddtionalIndentNew.yaml}[yaml-TCB]{\texttt{noAdditionalIndent} for \texttt{displayMath} in Version 3.0}{lst:indentAfterThisHeadingNew1} \cmhlistingsfromfile[style=yaml-LST]{demonstrations/noAddtionalIndentNew1.yaml}[yaml-TCB]{\texttt{noAdditionalIndent} for \texttt{displayMath} in Version 3.0}{lst:indentAfterThisHeadingNew2} \end{minipage}% \mbox{}\hfill \begin{minipage}{.25\textwidth} \hrule \hfill\itshape End\\\mbox{}\hfill\mbox{}\rlap{\hfill\includegraphics{logo}} \end{minipage} \end{document}