diff options
Diffstat (limited to 'Master/texmf-dist/doc/support')
27 files changed, 1440 insertions, 685 deletions
diff --git a/Master/texmf-dist/doc/support/latexindent/README b/Master/texmf-dist/doc/support/latexindent/README index 70999521516..86781a6af1c 100644 --- a/Master/texmf-dist/doc/support/latexindent/README +++ b/Master/texmf-dist/doc/support/latexindent/README @@ -1,5 +1,5 @@ %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - latexindent.pl, version 3.6, 2019-05-05 + latexindent.pl, version 3.7, 2019-07-13 PERL script to indent code within environments, and align delimited environments in .tex files. diff --git a/Master/texmf-dist/doc/support/latexindent/appendices.tex b/Master/texmf-dist/doc/support/latexindent/appendices.tex index bc04c6c1a0b..59037a5b24a 100644 --- a/Master/texmf-dist/doc/support/latexindent/appendices.tex +++ b/Master/texmf-dist/doc/support/latexindent/appendices.tex @@ -37,7 +37,7 @@ exit; install any missing \texttt{perl} modules on your system; if you run \begin{commandshell} perl latexindent-module-installer.pl - \end{commandshell} +\end{commandshell} or \begin{dosprompt} perl latexindent-module-installer.pl @@ -51,7 +51,7 @@ perl latexindent-module-installer.pl might visit the software center, or else run \begin{commandshell} sudo perl -MCPAN -e 'install "File::HomeDir"' - \end{commandshell} +\end{commandshell} Linux users may be interested in exploring Perlbrew \cite{perlbrew}; possible installation and setup options follow for Ubuntu (other distributions will need slightly @@ -69,6 +69,19 @@ cpanm Log::Log4perl cpanm Log::Dispatch \end{commandshell} + 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 +cpanm Unicode::GCString +cpanm Log::Log4perl +cpanm Log::Dispatch +\end{commandshell} + Strawberry Perl users on Windows might use \texttt{CPAN client}. All of the modules are readily available on CPAN \cite{cpan}. @@ -97,7 +110,7 @@ latexindent.exe -t myfile.tex \item run \begin{commandshell} ls /usr/local/bin - \end{commandshell} +\end{commandshell} to see what is \emph{currently} in there; \item run the following commands \begin{commandshell} @@ -110,14 +123,14 @@ sudo make install \item run \begin{commandshell} ls /usr/local/bin - \end{commandshell} +\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} +\end{commandshell} \subsection{Add to path for Windows} To add \texttt{latexindent.exe} to the path for Windows, follow these steps: \begin{enumerate} @@ -156,7 +169,7 @@ echo %path% 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} +\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} @@ -183,7 +196,7 @@ TRACE: Searching myenv for optional and mandatory arguments 3.0. Explicitly, in previous versions you might have run, for example, \begin{commandshell} latexindent.pl -o myfile.tex outputfile.tex - \end{commandshell} +\end{commandshell} whereas in Version 3.0 you would run any of the following, for example, \begin{commandshell} latexindent.pl -o=outputfile.tex myfile.tex @@ -192,7 +205,7 @@ 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} +\end{commandshell} noting that the \emph{output} file is given \emph{next to} the \texttt{-o} switch. @@ -223,7 +236,7 @@ latexindent.pl myfile.tex -outputfile outputfile.tex \begin{minipage}{.45\textwidth} \cmhlistingsfromfile{demonstrations/noAddtionalIndentNew.yaml}[yaml-TCB]{\texttt{noAdditionalIndent} for \texttt{displayMath} in Version 3.0}{lst:indentAfterThisHeadingNew1} - \cmhlistingsfromfile{demonstrations/noAddtionalIndentNew1.yaml}[yaml-TCB]{\texttt{noAdditionalIndent} for \texttt{displayMath} in Version 3.0}{lst:indentAfterThisHeadingNew2} + \cmhlistingsfromfile{demonstrations/noAddtionalIndentNew1.yaml}[yaml-TCB]{\texttt{noAdditionalIndent} for \texttt{displayMath} in Version 3.0}{lst:indentAfterThisHeadingNew2} \end{minipage}% \mbox{}\hfill \begin{minipage}{.25\textwidth} diff --git a/Master/texmf-dist/doc/support/latexindent/cmhlistings.tex b/Master/texmf-dist/doc/support/latexindent/cmhlistings.tex index 85aff0881cd..1f058616d6d 100644 --- a/Master/texmf-dist/doc/support/latexindent/cmhlistings.tex +++ b/Master/texmf-dist/doc/support/latexindent/cmhlistings.tex @@ -20,4 +20,9 @@ .. warning::^^J #1^^J .. endwarning::^^J -}{} +} +\newcommand{\example}[1]{ +.. proof:example::^^J +#1^^J +.. endproof:example::^^J +} diff --git a/Master/texmf-dist/doc/support/latexindent/latexindent.pdf b/Master/texmf-dist/doc/support/latexindent/latexindent.pdf Binary files differindex e26105457e2..12a226e99de 100644 --- a/Master/texmf-dist/doc/support/latexindent/latexindent.pdf +++ b/Master/texmf-dist/doc/support/latexindent/latexindent.pdf diff --git a/Master/texmf-dist/doc/support/latexindent/latexindent.tex b/Master/texmf-dist/doc/support/latexindent/latexindent.tex index 71ebc1d3ce4..775bd6a7d9d 100644 --- a/Master/texmf-dist/doc/support/latexindent/latexindent.tex +++ b/Master/texmf-dist/doc/support/latexindent/latexindent.tex @@ -47,7 +47,7 @@ \usetikzlibrary{decorations.pathmorphing} \usetikzlibrary{decorations,shapes} \usepackage{varioref} % the documentation library from tcolorbox loads hyperref -\tcbuselibrary{breakable,minted,xparse,documentation,hooks} +\tcbuselibrary{breakable,minted,xparse,documentation,hooks,raster} \hypersetup{ pdfauthor={Chris Hughes}, pdftitle={latexindent.pl package}, @@ -122,6 +122,8 @@ \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}}, @@ -152,16 +154,13 @@ listing engine=listings, left=0cm, boxrule=0pt, - %leftrule=3pt, sharp corners, center title, - %colbacktitle=white!75!black, colbacktitle=white!75!blue, colframe=white!25!blue, colback=white!90!blue, toprule=2pt, titlerule=2pt, - %bottomrule=1pt, }, MLB-TCB/.style={ yaml-TCB, @@ -171,16 +170,25 @@ colback=white!60!cmhgold, width=0.9\linewidth, before=\centering, - %bottomrule=1pt, 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, - %leftrule=3pt, sharp corners, center title, toprule=2pt, @@ -196,15 +204,23 @@ }, } -\newtcblisting[use counter=lstlisting]{cmhlistings}[3][]{% +\DeclareTCBListing[use counter=lstlisting]{cmhlistings}{s O{} m m}{% cmhlistings, - addtolol, + IfBooleanTF={#1}{new-to-this-version}{addtolol}, center title, - title={\color{black}{\scshape Listing \thetcbcounter}: ~#2},label={#3}, + title={\color{black}{\scshape Listing \thetcbcounter}: ~#3},label={#4}, listing engine=listings, - listing options={#1}, + 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 % [ listing/minted options ] @@ -298,163 +314,175 @@ \lstdefinestyle{fileExtensionPreference}{ style=yaml-LST, - firstnumber=38,linerange={38-42}, + firstnumber=41,linerange={41-45}, numbers=left, } \lstdefinestyle{logFilePreferences}{ style=yaml-LST, - firstnumber=79,linerange={79-89}, + firstnumber=85,linerange={85-95}, numbers=left, } \lstdefinestyle{verbatimEnvironments}{ style=yaml-LST, - firstnumber=93,linerange={93-96}, + firstnumber=99,linerange={99-102}, numbers=left, } \lstdefinestyle{verbatimCommands}{ style=yaml-LST, - firstnumber=99,linerange={99-101}, + firstnumber=105,linerange={105-107}, numbers=left, } \lstdefinestyle{noIndentBlock}{ style=yaml-LST, - firstnumber=107,linerange={107-109}, + firstnumber=112,linerange={112-114}, numbers=left, } \lstdefinestyle{removeTrailingWhitespace}{ style=yaml-LST, - firstnumber=112,linerange={112-114}, + firstnumber=117,linerange={117-119}, numbers=left, } \lstdefinestyle{fileContentsEnvironments}{ style=yaml-LST, - firstnumber=118,linerange={118-120}, + firstnumber=123,linerange={123-125}, numbers=left, } \lstdefinestyle{lookForPreamble}{ style=yaml-LST, - firstnumber=126,linerange={126-130}, + firstnumber=131,linerange={131-135}, numbers=left, } \lstdefinestyle{indentAfterItems}{ style=yaml-LST, - firstnumber=182,linerange={182-186}, + firstnumber=187,linerange={187-191}, numbers=left, } \lstdefinestyle{itemNames}{ style=yaml-LST, - firstnumber=192,linerange={192-194}, + firstnumber=197,linerange={197-199}, numbers=left, } \lstdefinestyle{specialBeginEnd}{ style=yaml-LST, - firstnumber=198,linerange={198-211}, + firstnumber=203,linerange={203-216}, numbers=left, } \lstdefinestyle{indentAfterHeadings}{ style=yaml-LST, - firstnumber=221,linerange={221-230}, + firstnumber=226,linerange={226-235}, numbers=left, } \lstdefinestyle{noAdditionalIndentGlobalEnv}{ style=yaml-LST, - firstnumber=279,linerange={279-280}, + firstnumber=284,linerange={284-285}, numbers=left, } \lstdefinestyle{noAdditionalIndentGlobal}{ style=yaml-LST, - firstnumber=279,linerange={279-291}, + firstnumber=284,linerange={284-296}, numbers=left, } \lstdefinestyle{indentRulesGlobalEnv}{ style=yaml-LST, - firstnumber=295,linerange={295-296}, + firstnumber=300,linerange={300-301}, numbers=left, } \lstdefinestyle{indentRulesGlobal}{ style=yaml-LST, - firstnumber=295,linerange={295-307}, + firstnumber=300,linerange={300-312}, numbers=left, } \lstdefinestyle{commandCodeBlocks}{ style=yaml-LST, - firstnumber=310,linerange={310-324}, + firstnumber=315,linerange={315-329}, numbers=left, } \lstdefinestyle{modifylinebreaks}{ style=yaml-LST, - firstnumber=394,linerange={394-396}, + firstnumber=441,linerange={441-443}, numbers=left, } \lstdefinestyle{textWrapOptions}{ style=yaml-LST, - firstnumber=421,linerange={421-422}, + firstnumber=468,linerange={468-469}, numbers=left, } \lstdefinestyle{textWrapOptionsAll}{ style=yaml-LST, - firstnumber=421,linerange={421-437}, + firstnumber=468,linerange={468-484}, numbers=left, } \lstdefinestyle{removeParagraphLineBreaks}{ style=yaml-LST, - firstnumber=438,linerange={438-452}, + firstnumber=485,linerange={485-499}, numbers=left, } \lstdefinestyle{paragraphsStopAt}{ style=yaml-LST, - firstnumber=453,linerange={453-462}, + firstnumber=500,linerange={500-509}, numbers=left, } \lstdefinestyle{oneSentencePerLine}{ style=yaml-LST, - firstnumber=397,linerange={397-420}, + firstnumber=444,linerange={444-467}, numbers=left, } \lstdefinestyle{sentencesFollow}{ style=yaml-LST, - firstnumber=402,linerange={402-410}, + firstnumber=449,linerange={449-457}, numbers=left, } \lstdefinestyle{sentencesBeginWith}{ style=yaml-LST, - firstnumber=411,linerange={411-414}, + firstnumber=458,linerange={458-461}, numbers=left, } \lstdefinestyle{sentencesEndWith}{ style=yaml-LST, - firstnumber=415,linerange={415-420}, + firstnumber=462,linerange={462-467}, numbers=left, } \lstdefinestyle{modifylinebreaksEnv}{ style=yaml-LST, - firstnumber=463,linerange={463-472}, + firstnumber=510,linerange={510-519}, + numbers=left, +} + +\lstdefinestyle{replacements}{ + style=yaml-LST, + firstnumber=571,linerange={571-579}, + numbers=left, +} + +\lstdefinestyle{fineTuning}{ + style=yaml-LST, + firstnumber=582,linerange={582-603}, numbers=left, } @@ -499,6 +527,34 @@ parbox=false, } +\newtcolorbox[auto counter]{example}{breakable, + enhanced jigsaw, + before skip=6pt,after skip=6pt, + frame hidden, + title={\llap{Example~\thetcbcounter\hspace{3mm}}}, + fonttitle=\bfseries, + coltitle=black, + attach title to upper, + grow to left by=5mm, + top=3mm, + overlay unbroken={% + \draw[thick,cmhgray] ([xshift=3mm]interior.north east)--([xshift=3mm]interior.south east); + \path [fill=cmhgray] ([xshift=3mm]interior.north east) circle (.5mm); + \path [fill=cmhgray] ([xshift=3mm]interior.south east) circle (1mm); + }, + overlay first={% + \draw[thick,cmhgray] ([xshift=3mm]interior.north east)--([xshift=3mm]interior.south east); + \path [fill=cmhgray] ([xshift=3mm]interior.north east) circle (.5mm); + %\path [draw=cmhgray,fill=white] ([xshift=3mm]interior.south east) circle (.5mm); + }, + overlay last={% + \draw[thick,cmhgray] ([xshift=3mm]interior.north east)--([xshift=3mm]interior.south east); + %\path [fill=white,draw=cmhgray] ([xshift=3mm]interior.north east) circle (.5mm); + \path [fill=cmhgray] ([xshift=3mm]interior.south east) circle (1mm); + }, + 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} @@ -550,6 +606,21 @@ {\llap{\thesection\hskip.5cm}} {0pt} {} + +\newcommand*\ruleline[1]{% + \par\noindent\raisebox{.8ex}{\makebox[\linewidth]{\hrulefill\hspace{1ex}\raisebox{-1.8ex}{#1}\hspace{1ex}\hrulefill}}} + +\newcommand{\imagetouse}{logo-bw} + +\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} @@ -563,9 +634,9 @@ {0pt} {} -\titlespacing\section{0pt}{12pt plus 4pt minus 2pt}{-5pt plus 2pt minus 2pt} -\titlespacing\subsection{0pt}{12pt plus 4pt minus 2pt}{-6pt plus 2pt minus 2pt} -\titlespacing\subsubsection{0pt}{12pt plus 4pt minus 2pt}{-6pt plus 2pt minus 2pt} +\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} % list of listings \contentsuse{lstlisting}{lol} @@ -677,26 +748,30 @@ \input{title.tex} \tableofcontents {\small\lstlistoflistings} -\input{sec-introduction} -\input{sec-demonstration} -\input{sec-how-to-use} -\input{sec-indent-config-and-settings.tex} -\input{sec-default-user-local} -\input{subsec-noAdditionalIndent-indentRules} -\input{subsubsec-environments-and-their-arguments} -\input{subsubsec-environments-with-items} -\input{subsubsec-commands-with-arguments} -\input{subsubsec-ifelsefi} -\input{subsubsec-special} -\input{subsubsec-headings} -\input{subsubsec-no-add-remaining-code-blocks} -\stopcontents[noAdditionalIndent] -\input{subsec-commands-and-their-options} -\input{sec-the-m-switch} -\stopcontents[the-m-switch] -\input{subsec-partnering-poly-switches} -\input{subsec-conflicting-poly-switches} -\input{sec-conclusions-know-limitations} -\input{references} -\input{appendices} +% start sections on new page +\newcommand{\sectionbreak}{\clearpage\thispagestyle{plain}} + \input{sec-introduction} + \input{sec-demonstration} + \input{sec-how-to-use} + \input{sec-indent-config-and-settings.tex} + \input{sec-default-user-local} + \input{subsec-noAdditionalIndent-indentRules} + \input{subsubsec-environments-and-their-arguments} + \input{subsubsec-environments-with-items} + \input{subsubsec-commands-with-arguments} + \input{subsubsec-ifelsefi} + \input{subsubsec-special} + \input{subsubsec-headings} + \input{subsubsec-no-add-remaining-code-blocks} + \stopcontents[noAdditionalIndent] + \input{subsec-commands-and-their-options} + \input{sec-the-m-switch} + \stopcontents[the-m-switch] + \input{subsec-partnering-poly-switches} + \input{subsec-conflicting-poly-switches} + \input{sec-replacements} + \input{sec-fine-tuning} + \input{sec-conclusions-know-limitations} + \input{references} + \input{appendices} \end{document} diff --git a/Master/texmf-dist/doc/support/latexindent/logo.tex b/Master/texmf-dist/doc/support/latexindent/logo.tex index e2db1161204..5bc31e0a4f3 100644 --- a/Master/texmf-dist/doc/support/latexindent/logo.tex +++ b/Master/texmf-dist/doc/support/latexindent/logo.tex @@ -24,10 +24,10 @@ \pagecolor{white} \begin{tikzpicture}[logo/.style={draw=blue,circle,fill=none,fill opacity=0.75}] \matrix{% - \node[logo,dash pattern=on .5pt off 1.0pt,thick,draw=purple!75!white]{}; & \node[logo,draw=burntorange]{}; \\ + \node[logo,dash pattern=on .5pt off 1.0pt,thick,draw=purple!75!white]{}; & \node[logo,draw=burntorange]{}; \\ \node[logo,fill,draw=bakeoffgreen,fill=bakeoffblue]{}; & \node[logo,double,draw=cmhgold,fill=harvestgold]{};\\}; - \begin{scope}[on background layer] - %\node [yshift=0.01em,xshift=0.07em] {\resizebox{1cm}{!}{\color{gray!50!white}\faGithub}}; - \node {\resizebox{1cm}{!}{\color{gray!25!white}\faGithub}}; - \end{scope} + \begin{scope}[on background layer] + %\node [yshift=0.01em,xshift=0.07em] {\resizebox{1cm}{!}{\color{gray!50!white}\faGithub}}; + \node {\resizebox{1cm}{!}{\color{gray!25!white}\faGithub}}; + \end{scope} \end{tikzpicture} diff --git a/Master/texmf-dist/doc/support/latexindent/sec-conclusions-know-limitations.tex b/Master/texmf-dist/doc/support/latexindent/sec-conclusions-know-limitations.tex index 0128adb8a38..1e865c9c843 100644 --- a/Master/texmf-dist/doc/support/latexindent/sec-conclusions-know-limitations.tex +++ b/Master/texmf-dist/doc/support/latexindent/sec-conclusions-know-limitations.tex @@ -17,8 +17,8 @@ future. There are other limitations to do with the multicolumn alignment routine (see - \vref{lst:tabular2-mod2}); in particular, when working with codeblocks in which multicolumn - commands overlap, the algorithm can fail. + \vref{lst:tabular2-mod2}); in particular, when working with code blocks in which + multicolumn commands overlap, the algorithm can fail. Another limitation is to do with efficiency, particularly when the \texttt{-m} switch is active, as this adds many checks and processes. The current implementation @@ -27,9 +27,10 @@ \emph{nested} code blocks will need to be stored in the `packing' phase, and that this will improve the efficiency of the script. - You can run \texttt{latexindent} on \texttt{.sty}, \texttt{.cls} and - any file types that you specify in \lstinline[breaklines=true]!fileExtensionPreference! (see \vref{lst:fileExtensionPreference}); - if you find a case in which the script struggles, please feel free to report it at + 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:noIndentBlockdemo}). I hope that this script is useful to some; if you find an example where the script does diff --git a/Master/texmf-dist/doc/support/latexindent/sec-default-user-local.tex b/Master/texmf-dist/doc/support/latexindent/sec-default-user-local.tex index 761d1ea5473..2a657fae8a6 100644 --- a/Master/texmf-dist/doc/support/latexindent/sec-default-user-local.tex +++ b/Master/texmf-dist/doc/support/latexindent/sec-default-user-local.tex @@ -38,7 +38,7 @@ latexindent.pl myfile 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 + \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 @@ -64,15 +64,15 @@ latexindent.pl myfile \yamltitle{cycleThroughBackUps}*{integer} Some users may wish to cycle through backup files, by deleting the oldest backup file and keeping only the most recent; for example, with \texttt{maxNumberOfBackUps: 4}, and - \texttt{cycleThroughBackUps} set to \texttt{1} then the - \texttt{copy} procedure given below would be obeyed. + \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} +\end{commandshell} The default value of \texttt{cycleThroughBackUps} is \texttt{0}. \yamltitle{logFilePreferences}*{fields} @@ -87,7 +87,7 @@ copy myfile.bak4 to myfile.bak3 \cmhlistingsfromfile[style=logFilePreferences,]*{../defaultSettings.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{logFilePreferences}}{lst:logFilePreferences} - When%%%% + 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 @@ -111,15 +111,12 @@ copy myfile.bak4 to myfile.bak3 no indentation will be performed on environments that you have specified in this field, see \cref{lst:verbatimEnvironments}. - \begin{minipage}{.45\textwidth} + \begin{cmhtcbraster}[raster column skip=.1\linewidth] \cmhlistingsfromfile[style=verbatimEnvironments]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{verbatimEnvironments}}{lst:verbatimEnvironments} - \end{minipage}% - \hfill - \begin{minipage}{.45\textwidth} \cmhlistingsfromfile[style=verbatimCommands]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{verbatimCommands}}{lst:verbatimCommands} - \end{minipage}% + \end{cmhtcbraster} - Note that if you put an environment in \texttt{verbatimEnvironments} and in other fields such + 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}. @@ -243,7 +240,7 @@ lookForAlignDelims: \cref{lst:aligndelims:basic} and the \emph{advanced} version in \cref{lst:aligndelims:advanced}; we will discuss each in turn. - The environments specified in this field will be operated on in a special way by + The environments specified in this field will be operated on in a special way by \texttt{latexindent.pl}. In particular, it will try and align each column by its alignment tabs. It does have some limitations (discussed further in \cref{sec:knownlimitations}), but in many cases it will produce results such as those in @@ -255,13 +252,10 @@ lookForAlignDelims: \emph{specific} instances of the environment, you could wrap them in something from \texttt{noIndentBlock} (see \vref{lst:noIndentBlock}). - \begin{minipage}{.45\textwidth} + \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/tabular1.tex}{\texttt{tabular1.tex}}{lst:tabularbefore:basic} - \end{minipage}% - \hfill - \begin{minipage}{.45\textwidth} \cmhlistingsfromfile{demonstrations/tabular1-default.tex}{\texttt{tabular1.tex} default output}{lst:tabularafter:basic} - \end{minipage}% + \end{cmhtcbraster} If, for example, you wish to remove the alignment of the \lstinline!\\! within a delimiter-aligned block, then the advanced form of \texttt{lookForAlignDelims} shown in @@ -343,7 +337,7 @@ 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} +\end{commandshell} we obtain the respective outputs given in \crefrange{lst:tabular2-default}{lst:tabular2-mod8}. \begin{widepage} @@ -397,17 +391,14 @@ latexindent.pl tabular2.tex -l tabular2.yaml,tabular8.yaml you run the command \begin{commandshell} latexindent.pl matrix1.tex - \end{commandshell} +\end{commandshell} then the before-and-after results shown in \cref{lst:matrixbefore,lst:matrixafter} are achievable by default. - \begin{minipage}{.45\textwidth} + \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/matrix1.tex}{\texttt{matrix1.tex}}{lst:matrixbefore} - \end{minipage}% - \hfill - \begin{minipage}{.45\textwidth} \cmhlistingsfromfile{demonstrations/matrix1-default.tex}{\texttt{matrix1.tex} default output}{lst:matrixafter} - \end{minipage}% + \end{cmhtcbraster} 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 @@ -418,13 +409,10 @@ latexindent.pl matrix1.tex \lstinline!*! and \lstinline!\begin{tabular}!; note also that you may use any environment name that you have specified in \texttt{lookForAlignDelims}. - \begin{minipage}{.45\textwidth} + \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/align-block.tex}{\texttt{align-block.tex}}{lst:alignmentmarkup} - \end{minipage}% - \hfill - \begin{minipage}{.45\textwidth} \cmhlistingsfromfile{demonstrations/align-block-default.tex}{\texttt{align-block.tex} default output}{lst:alignmentmarkup-default} - \end{minipage}% + \end{cmhtcbraster} With reference to \vref{tab:code-blocks} and the, yet undiscussed, fields of \texttt{noAdditionalIndent} and \texttt{indentRules} @@ -432,21 +420,19 @@ latexindent.pl matrix1.tex considered \texttt{environments}. \yamltitle{indentAfterItems}*{fields} - \begin{wrapfigure}[5]{r}[0pt]{7cm} - \cmhlistingsfromfile[style=indentAfterItems]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{indentAfterItems}}{lst:indentafteritems} - \end{wrapfigure} - The environment names specified in \texttt{indentAfterItems} tell \texttt{latexindent.pl} + The environment names specified in \texttt{indentAfterItems} tell \texttt{latexindent.pl} to look for \lstinline!\item! commands; if these switches are set to \texttt{1} then indentation will be performed so as indent the code after each \texttt{item}. A demonstration is given in \cref{lst:itemsbefore,lst:itemsafter} - \begin{minipage}{.45\textwidth} + \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} - \end{minipage}% - \hfill - \begin{minipage}{.45\textwidth} \cmhlistingsfromfile{demonstrations/items1-default.tex}{\texttt{items1.tex} default output}{lst:itemsafter} - \end{minipage} + \end{cmhtcbraster} \yamltitle{itemNames}*{fields} \begin{wrapfigure}[5]{r}[0pt]{5cm} @@ -461,7 +447,7 @@ latexindent.pl matrix1.tex \vref{lst:mysettings} \\ in particular \label{page:examsettings}.) \yamltitle{specialBeginEnd}*{fields}\label{yaml:specialBeginEnd} - The fields specified%%%% + The fields specified% \announce{2017-08-21}*{specialBeginEnd} in \texttt{specialBeginEnd} are, in their default state, focused on math mode begin and end statements, but there is no requirement for this to be the case; \cref{lst:specialBeginEnd} @@ -477,20 +463,17 @@ latexindent.pl matrix1.tex A demonstration of the before-and-after results are shown in \cref{lst:specialbefore,lst:specialafter}. - \begin{minipage}{.45\textwidth} + \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/special1.tex}{\texttt{special1.tex} before}{lst:specialbefore} - \end{minipage}% - \hfill - \begin{minipage}{.45\textwidth} \cmhlistingsfromfile{demonstrations/special1-default.tex}{\texttt{special1.tex} default output}{lst:specialafter} - \end{minipage} + \end{cmhtcbraster} 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%%%% + 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. @@ -500,20 +483,17 @@ latexindent.pl matrix1.tex Now consider the YAML files shown in \cref{lst:specialsLeftRight-yaml,lst:specialBeforeCommand-yaml} - \begin{minipage}{.49\linewidth} + \begin{cmhtcbraster} \cmhlistingsfromfile[]*{demonstrations/specialsLeftRight.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{specialsLeftRight.yaml}}{lst:specialsLeftRight-yaml} - \end{minipage} - \hfill - \begin{minipage}{.49\linewidth} \cmhlistingsfromfile[]*{demonstrations/specialBeforeCommand.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{specialBeforeCommand.yaml}}{lst:specialBeforeCommand-yaml} - \end{minipage} + \end{cmhtcbraster} Upon running the following commands \begin{widepage} \begin{commandshell} latexindent.pl specialLR.tex -l=specialsLeftRight.yaml latexindent.pl specialLR.tex -l=specialsLeftRight.yaml,specialBeforeCommand.yaml - \end{commandshell} +\end{commandshell} \end{widepage} we receive the respective outputs in \cref{lst:specialLR-comm-first-tex,lst:specialLR-special-first-tex}. @@ -534,7 +514,7 @@ latexindent.pl specialLR.tex -l=specialsLeftRight.yaml,specialBeforeCommand.yaml \texttt{specialBeginEnd} should be sought \emph{before} commands. \end{itemize} - You can,optionally, specify%%%% + You can,optionally, specify% \announce{2018-04-27}{update to specialBeginEnd} the \texttt{middle} field for anything that you specify in \texttt{specialBeginEnd}. For example, let's consider the \texttt{.tex} file in \cref{lst:special2}. @@ -545,24 +525,18 @@ latexindent.pl specialLR.tex -l=specialsLeftRight.yaml,specialBeforeCommand.yaml \begin{commandshell} latexindent.pl special2.tex -l=middle latexindent.pl special2.tex -l=middle1 - \end{commandshell} +\end{commandshell} then we obtain the output given in \cref{lst:special2-mod1,lst:special2-mod2}. - \begin{minipage}{.4\linewidth} + \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/middle.yaml}[yaml-TCB]{\texttt{middle.yaml}}{lst:middle-yaml} - \end{minipage} - \hfill - \begin{minipage}{.5\linewidth} \cmhlistingsfromfile{demonstrations/special2-mod1.tex}{\texttt{special2.tex} using \cref{lst:middle-yaml}}{lst:special2-mod1} - \end{minipage} + \end{cmhtcbraster} - \begin{minipage}{.4\linewidth} + \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/middle1.yaml}[yaml-TCB]{\texttt{middle1.yaml}}{lst:middle1-yaml} - \end{minipage} - \hfill - \begin{minipage}{.5\linewidth} \cmhlistingsfromfile{demonstrations/special2-mod2.tex}{\texttt{special2.tex} using \cref{lst:middle1-yaml}}{lst:special2-mod2} - \end{minipage} + \end{cmhtcbraster} We note that: \begin{itemize} @@ -576,25 +550,22 @@ latexindent.pl special2.tex -l=middle1 \cref{lst:special2-mod2}. \end{itemize} - You may%% + You may% \announce{2018-08-13}{specialBeginEnd verbatim} specify fields in \texttt{specialBeginEnd} to be treated as verbatim code blocks by changing \texttt{lookForThis} to be \texttt{verbatim}. - For example, beginning with the code in \cref{lst:special3-mod1} and the YAML in + For example, beginning with the code in \cref{lst:special3-mod1} and the YAML in \cref{lst:special-verb1-yaml}, and running \begin{commandshell} latexindent.pl special3.tex -l=special-verb1 - \end{commandshell} +\end{commandshell} then the output in \cref{lst:special3-mod1} is unchanged. - \begin{minipage}{.4\linewidth} + \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/special-verb1.yaml}[yaml-TCB]{\texttt{special-verb1.yaml}}{lst:special-verb1-yaml} - \end{minipage} - \hfill - \begin{minipage}{.5\linewidth} \cmhlistingsfromfile{demonstrations/special3-mod1.tex}{\texttt{special3.tex} and output using \cref{lst:special-verb1-yaml}}{lst:special3-mod1} - \end{minipage} + \end{cmhtcbraster} \yamltitle{indentAfterHeadings}*{fields} \begin{wrapfigure}[17]{r}[0pt]{8cm} @@ -624,13 +595,10 @@ latexindent.pl special3.tex -l=special-verb1 \texttt{headings1.yaml}, and that you have the text from \cref{lst:headings1} saved into \texttt{headings1.tex}. - \begin{minipage}{.45\textwidth} + \begin{cmhtcbraster} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/headings1.yaml}[yaml-TCB]{\texttt{headings1.yaml}}{lst:headings1yaml} - \end{minipage}% - \hfill - \begin{minipage}{.45\textwidth} \cmhlistingsfromfile{demonstrations/headings1.tex}{\texttt{headings1.tex}}{lst:headings1} - \end{minipage} + \end{cmhtcbraster} If you run the command \begin{commandshell} @@ -657,7 +625,7 @@ latexindent.pl headings1.tex -l=headings1.yaml \yamltitle{maximumIndentation}*{horizontal space} You can control the maximum indentation given to your file - by%%%% + 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 @@ -666,28 +634,22 @@ latexindent.pl headings1.tex -l=headings1.yaml For example, consider the example shown in \cref{lst:mult-nested} together with the default output shown in \cref{lst:mult-nested-default}. - \begin{minipage}{.45\textwidth} + \begin{cmhtcbraster}[raster column skip=.1\linewidth] \cmhlistingsfromfile{demonstrations/mult-nested.tex}{\texttt{mult-nested.tex}}{lst:mult-nested} - \end{minipage}% - \hfill - \begin{minipage}{.45\textwidth} \cmhlistingsfromfile[showtabs=true]{demonstrations/mult-nested-default.tex}{\texttt{mult-nested.tex} default output}{lst:mult-nested-default} - \end{minipage} + \end{cmhtcbraster} Now say that, for example, you have the \texttt{max-indentation1.yaml} from \cref{lst:max-indentation1yaml} and that you run the following command: \begin{commandshell} latexindent.pl mult-nested.tex -l=max-indentation1 - \end{commandshell} +\end{commandshell} You should receive the output shown in \cref{lst:mult-nested-max-ind1}. - \begin{minipage}{.45\textwidth} + \begin{cmhtcbraster} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/max-indentation1.yaml}[yaml-TCB]{\texttt{max-indentation1.yaml}}{lst:max-indentation1yaml} - \end{minipage}% - \hfill - \begin{minipage}{.45\textwidth} \cmhlistingsfromfile[showspaces=true]{demonstrations/mult-nested-max-ind1.tex}{\texttt{mult-nested.tex} using \cref{lst:max-indentation1yaml}}{lst:mult-nested-max-ind1} - \end{minipage} + \end{cmhtcbraster} 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. @@ -770,4 +732,6 @@ mand arg text \end{widepage} \end{table} - We will refer to these code blocks in what follows. + 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}. diff --git a/Master/texmf-dist/doc/support/latexindent/sec-demonstration.tex b/Master/texmf-dist/doc/support/latexindent/sec-demonstration.tex index 9049a5dfd8e..18459edcda4 100644 --- a/Master/texmf-dist/doc/support/latexindent/sec-demonstration.tex +++ b/Master/texmf-dist/doc/support/latexindent/sec-demonstration.tex @@ -6,7 +6,7 @@ As you look at \crefrange{lst:filecontentsbefore}{lst:pstricksafter}, remember that \texttt{latexindent.pl} is just following its rules, and there is nothing particular about these code snippets. All of - the rules can be modified so that you can personalize your indentation scheme. + 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, diff --git a/Master/texmf-dist/doc/support/latexindent/sec-fine-tuning.tex b/Master/texmf-dist/doc/support/latexindent/sec-fine-tuning.tex new file mode 100644 index 00000000000..9a2cbbb5c81 --- /dev/null +++ b/Master/texmf-dist/doc/support/latexindent/sec-fine-tuning.tex @@ -0,0 +1,109 @@ +% arara: pdflatex: {shell: yes, 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. + + \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=0.95\linewidth,before=\centering,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} + 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 back slashes, 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. + + 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 + \begin{commandshell} +latexindent.pl finetuning1.tex -l=fine-tuning1.yaml +\end{commandshell} + and the associated (desired) output is given in \cref{lst:finetuning1-mod1}. + + \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} diff --git a/Master/texmf-dist/doc/support/latexindent/sec-how-to-use.tex b/Master/texmf-dist/doc/support/latexindent/sec-how-to-use.tex index 6a5aa290ca0..bdae2b428e4 100644 --- a/Master/texmf-dist/doc/support/latexindent/sec-how-to-use.tex +++ b/Master/texmf-dist/doc/support/latexindent/sec-how-to-use.tex @@ -27,42 +27,41 @@ \subsection{From the command line}\label{sec:commandline} \texttt{latexindent.pl} has a number of different switches/flags/options, which can be combined in any way that you like, either in short or long form as detailed below. - \texttt{latexindent.pl} produces a \texttt{.log} file, - \texttt{indent.log}, every time it is run; the name of the log file can be customized, - but we will refer to the log file as \texttt{indent.log} throughout this document. - There is a base of information that is written to \texttt{indent.log}, but other - additional information will be written depending on which of the following options are - used. + \texttt{latexindent.pl} produces a \texttt{.log} file, \texttt{indent.log}, + every time it is run; the name of the log file can be 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. \flagbox{-v, --version} \announce{2017-06-25}{version} \begin{commandshell} latexindent.pl -v - \end{commandshell} +\end{commandshell} This will output only the version number to the terminal. \flagbox{-h, --help} \begin{commandshell} latexindent.pl -h - \end{commandshell} +\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} +\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. + \texttt{myfile.tex} will not be changed by \texttt{latexindent.pl} in any way using + this command. \flagbox{-w, --overwrite} \begin{commandshell} latexindent.pl -w myfile.tex latexindent.pl --overwrite myfile.tex latexindent.pl myfile.tex --overwrite - \end{commandshell} +\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 @@ -80,7 +79,7 @@ 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} +\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 @@ -105,7 +104,7 @@ 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%%% + 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: @@ -115,7 +114,7 @@ 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%%% + 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 @@ -154,7 +153,7 @@ latexindent.pl myfile.tex -o=+out++.tex \begin{commandshell} latexindent.pl -s myfile.tex latexindent.pl myfile.tex -s - \end{commandshell} +\end{commandshell} Silent mode: no output will be given to the terminal. @@ -162,7 +161,7 @@ latexindent.pl myfile.tex -s \begin{commandshell} latexindent.pl -t myfile.tex latexindent.pl myfile.tex -t - \end{commandshell} +\end{commandshell} \label{page:traceswitch} Tracing mode: verbose output will be given to \texttt{indent.log}. This is useful if @@ -175,7 +174,7 @@ latexindent.pl myfile.tex -t \begin{commandshell} latexindent.pl -tt myfile.tex latexindent.pl myfile.tex -tt - \end{commandshell} +\end{commandshell} \emph{More detailed} tracing mode: this option gives more details to \texttt{indent.log} @@ -191,7 +190,7 @@ 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} +\end{commandshell} \label{page:localswitch} \texttt{latexindent.pl} will always load \texttt{defaultSettings.yaml} (rhymes with camel) @@ -204,7 +203,7 @@ latexindent.pl myfile.tex -l=first.yaml,second.yaml,third.yaml 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}.%%% + 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 @@ -212,31 +211,31 @@ latexindent.pl myfile.tex -l=first.yaml,second.yaml,third.yaml 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} +\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 latexindent.pl -l=myyaml.yaml+ myfile.tex - \end{commandshell} +\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} +\end{commandshell} Note that the following is \emph{not} allowed: \begin{commandshell} latexindent.pl -l+myyaml.yaml myfile.tex - \end{commandshell} +\end{commandshell} and \begin{commandshell} latexindent.pl -l + myyaml.yaml myfile.tex - \end{commandshell} +\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. @@ -245,7 +244,7 @@ latexindent.pl -l + myyaml.yaml myfile.tex \announce{2017-06-25}{no extension for -l switch} \begin{commandshell} latexindent.pl -l=localSettings,myyaml myfile.tex - \end{commandshell} +\end{commandshell} \flagbox{-y, --yaml=yaml settings} \begin{commandshell} latexindent.pl myfile.tex -y="defaultIndent: ' '" @@ -253,7 +252,7 @@ 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} +\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; @@ -268,11 +267,11 @@ latexindent.pl myfile.tex -y='modifyLineBreaks:environments:one:EndStartsOnOwnLi \flagbox{-d, --onlydefault} \begin{commandshell} latexindent.pl -d myfile.tex - \end{commandshell} +\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 + \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 @@ -283,7 +282,7 @@ latexindent.pl -d myfile.tex \flagbox{-c, --cruft=<directory>} \begin{commandshell} latexindent.pl -c=/path/to/directory/ myfile.tex - \end{commandshell} +\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 @@ -295,7 +294,7 @@ 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} +\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 @@ -305,8 +304,8 @@ latexindent.pl myfile.tex -g other.log \begin{commandshell} latexindent.pl -sl myfile.tex latexindent.pl -screenlog myfile.tex - \end{commandshell} - Using this%%%% +\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. @@ -315,7 +314,7 @@ latexindent.pl -screenlog myfile.tex \begin{commandshell} latexindent.pl -m myfile.tex latexindent.pl -modifylinebreaks myfile.tex - \end{commandshell} +\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} @@ -324,26 +323,26 @@ latexindent.pl -modifylinebreaks myfile.tex example \begin{commandshell} latexindent.pl myfile - \end{commandshell} +\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 - \end{commandshell} +\end{commandshell} \texttt{latexindent.pl} will% \announce{2018-01-13}{STDIN allowed} allow input from STDIN, which means that you can pipe output from other commands directly into the script. For example assuming that you have content in \texttt{myfile.tex}, then the above command will output the results of operating upon \texttt{myfile.tex} - Similarly, if you%%%% + 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} +\end{commandshell} Once you have finished typing your input, you can press \begin{itemize} @@ -352,6 +351,39 @@ latexindent.pl \end{itemize} to signify that your input has finished. Thanks to \cite{xu-cheng} for an update to this feature. +\flagbox{-r, --replacement} + \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}. + +\flagbox{-rv, --replacementrespectverb} + \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} + \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}. \subsection{From arara}\label{sec:arara} Using \texttt{latexindent.pl} from the command line is fine for some folks, but others diff --git a/Master/texmf-dist/doc/support/latexindent/sec-indent-config-and-settings.tex b/Master/texmf-dist/doc/support/latexindent/sec-indent-config-and-settings.tex index f69fda83dee..cb551194c0e 100644 --- a/Master/texmf-dist/doc/support/latexindent/sec-indent-config-and-settings.tex +++ b/Master/texmf-dist/doc/support/latexindent/sec-indent-config-and-settings.tex @@ -64,7 +64,7 @@ lookForAlignDelims: \end{yaml} You can make sure that your settings are loaded by checking \texttt{indent.log} for - details -- if you have specified a path that \texttt{latexindent.pl} doesn't recognize + 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}. @@ -118,29 +118,38 @@ verbatimEnvironments: file. \subsection{The -y|yaml switch}\label{sec:yamlswitch} - You%%%% + You% \announce{2017-08-21}{demonstration of the -y switch} may use the \texttt{-y} switch to load your settings; for example, if you wished to specify the settings from \cref{lst:localSettings} using the \texttt{-y} switch, then you could use the following command: \begin{commandshell} latexindent.pl -y="verbatimEnvironments:cmhenvironment:0;myenv:1" myfile.tex - \end{commandshell} +\end{commandshell} Note the use of \texttt{;} to specify another field within \texttt{verbatimEnvironments}. This is shorthand, and equivalent, to using the following command: \begin{commandshell} latexindent.pl -y="verbatimEnvironments:cmhenvironment:0,verbatimEnvironments:myenv:1" myfile.tex - \end{commandshell} +\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, \begin{commandshell} latexindent.pl -l=mysettings.yaml -y="verbatimEnvironments:cmhenvironment:0;myenv:1" myfile.tex - \end{commandshell} +\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, + 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 + \begin{commandshell} +latexindent.pl -m --yaml='modifyLineBreaks:oneSentencePerLine:sentencesEndWith:other:\;' +\end{commandshell} + \subsection{Settings load order}\label{sec:loadorder} \texttt{latexindent.pl} loads the settings files in the following order: \begin{enumerate} @@ -150,11 +159,11 @@ latexindent.pl -l=mysettings.yaml -y="verbatimEnvironments:cmhenvironment:0;myen \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%% + 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 + \item any settings% + \announce{2017-08-21}{-y switch load order} specified in the \texttt{-y} switch. \end{enumerate} A visual representation of this is given in \cref{fig:loadorder}. diff --git a/Master/texmf-dist/doc/support/latexindent/sec-introduction.tex b/Master/texmf-dist/doc/support/latexindent/sec-introduction.tex index c869b84596e..c6fafd92696 100644 --- a/Master/texmf-dist/doc/support/latexindent/sec-introduction.tex +++ b/Master/texmf-dist/doc/support/latexindent/sec-introduction.tex @@ -86,9 +86,19 @@ for more details. \end{minipage}% + \begin{minipage}{.55\textwidth} + \cmhlistingsfromfile*[style=replacements]*{../defaultSettings.yaml}[replace-TCB,width=.85\linewidth,before=\centering]{\texttt{replacements}}{lst:replacements-demo} + \end{minipage}% + \hfill + \begin{minipage}{.4\textwidth} + This type of listing is a \texttt{.yaml} file, but it will only + be relevant when the \texttt{-r} switch is active; see \vref{sec:replacements} + for more details. + \end{minipage}% + % \begin{latexonly} You will occasionally see dates shown in the margin (for example, next to this - paragraph!)%%% + 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 @@ -104,7 +114,7 @@ If you'd like to get started with \texttt{latexindent.pl} then simply type \begin{commandshell} latexindent.pl myfile.tex - \end{commandshell} +\end{commandshell} from the command line. If you receive an error message such as that given in \cref{lst:poss-errors}, then you need to install the missing perl modules. \begin{cmhlistings}[style=tcblatex,language=Perl]{Possible error messages}{lst:poss-errors} @@ -115,6 +125,6 @@ BEGIN failed--compilation aborted at helloworld.pl line 10. following script, you should be prompted to install the appropriate modules. \begin{commandshell} perl latexindent-module-installer.pl - \end{commandshell} +\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}. diff --git a/Master/texmf-dist/doc/support/latexindent/sec-replacements.tex b/Master/texmf-dist/doc/support/latexindent/sec-replacements.tex new file mode 100644 index 00000000000..6bc7223d4d1 --- /dev/null +++ b/Master/texmf-dist/doc/support/latexindent/sec-replacements.tex @@ -0,0 +1,372 @@ +% arara: pdflatex: {shell: yes, 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: + \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. With reference to \cref{lst:replacements}, the default action will + replace every instance of the text \texttt{latexindent.pl} with \texttt{pl.latexindent}. + + Beginning with the code in \cref{lst:replace1} and running the command + \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} + + If we don't wish to perform this replacement, then we can tweak the default settings of + \vref{lst:replacements} by changing \texttt{lookForThis} to 0; we perform this action + in \cref{lst:replace1-yaml}, and run the command + \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. + + 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. + \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 + \begin{commandshell} +latexindent.pl -r colsep.tex -l=colsep.yaml +\end{commandshell} + then we achieve the output in \cref{lst:colsep-mod0}. + \begin{cmhtcbraster}[raster column skip=.01\linewidth] + \cmhlistingsfromfile*{demonstrations/colsep-mod0.tex}{\texttt{colsep.tex} using \cref{lst:colsep}}{lst:colsep-mod0} + \cmhlistingsfromfile*[style=yaml-LST]*{demonstrations/colsep.yaml}[replace-TCB]{\texttt{colsep.yaml}}{lst:colsep-yaml} + \end{cmhtcbraster} + Note that in \cref{lst:colsep-yaml}, we have specified \emph{two} separate fields, each with their own `\emph{this}' field; + furthermore, for both of the separate fields, we have not specified `\texttt{that}', so the \texttt{that} field + is assumed to be blank by \texttt{latexindent.pl}; + + We can make the YAML in \cref{lst:colsep-yaml} more concise by exploring the \texttt{substitution} field. Using + the settings in \cref{lst:colsep1} and running the command + \begin{commandshell} +latexindent.pl -r colsep.tex -l=colsep1.yaml +\end{commandshell} + then we achieve the output in \cref{lst:colsep-mod1}. + \begin{cmhtcbraster}[raster column skip=.01\linewidth, + raster force size=false, + raster column 1/.style={add to width=-.1\textwidth}] + \cmhlistingsfromfile*{demonstrations/colsep-mod1.tex}{\texttt{colsep.tex} using \cref{lst:colsep1}}{lst:colsep-mod1} + \cmhlistingsfromfile*[style=yaml-LST]*{demonstrations/colsep1.yaml}[replace-TCB,width=0.6\textwidth]{\texttt{colsep1.yaml}}{lst:colsep1} + \end{cmhtcbraster} + + The code given in \cref{lst:colsep1} is an example of a \emph{regular expression}, which we may abbreviate to \emph{regex} + in what follows. This manual is not intended to be + a tutorial on regular expressions; you might like to read, for example, \cite{masteringregexp} for a detailed + covering of the topic. With reference to \cref{lst:colsep1}, we do note the following: + \begin{itemize} + \item the general form of the \texttt{substitution} field is \lstinline!s/regex/replacement/modifiers!. You can + place any regular expression you like within this; + \item we have `escaped' the backslash by using \lstinline!\\! + \item we have used \lstinline!\d+! to represent \emph{at least} one digit + \item the \texttt{s} \emph{modifier} (in the \texttt{sg} at the end of the line) instructs \texttt{latexindent.pl} to + treat your file as one single line; + \item the \texttt{g} \emph{modifier} (in the \texttt{sg} at the end of the line) instructs \texttt{latexindent.pl} to + make the substitution \emph{globally} throughout your file; you might try removing + the \texttt{g} modifier from \cref{lst:colsep1} and observing the + difference in output. + \end{itemize} + You might like to see \href{https://perldoc.perl.org/perlre.html#Modifiers}{https://perldoc.perl.org/perlre.html\#Modifiers} + for details of modifiers; in general, I recommend starting with the \texttt{sg} modifiers for this feature. + \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 + \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 + \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, + \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 + \begin{commandshell} +latexindent.pl -r displaymath.tex -l=displaymath1.yaml +\end{commandshell} + to receive the output given in \cref{lst:displaymath-mod1}. + + \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 + \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 + \begin{commandshell} +latexindent.pl -r phrase.tex -l=hspace.yaml +\end{commandshell} + which gives the output in \cref{lst:phrase-mod1}. + + \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 + \begin{commandshell} +latexindent.pl -r references.tex -l=reference.yaml +\end{commandshell} + which gives the output in \cref{lst:references-mod1}. + + \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, + \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, + \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} diff --git a/Master/texmf-dist/doc/support/latexindent/sec-the-m-switch.tex b/Master/texmf-dist/doc/support/latexindent/sec-the-m-switch.tex index 0e959b2cf77..ec3a86871dd 100644 --- a/Master/texmf-dist/doc/support/latexindent/sec-the-m-switch.tex +++ b/Master/texmf-dist/doc/support/latexindent/sec-the-m-switch.tex @@ -1,9 +1,10 @@ % arara: pdflatex: {shell: yes, files: [latexindent]} -\fancyhead[R]{\bfseries\thepage% - \tikz[remember picture,overlay] { - \node at (1,0){\includegraphics{logo}}; - }} +\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. @@ -87,13 +88,10 @@ latexindent.pl -m textwrap1.tex -o textwrap1-mod1.tex -l textwrap1.yaml \end{commandshell} we obtain the output in \cref{lst:textwrap1-mod1}. - \begin{minipage}{.45\linewidth} + \begin{cmhtcbraster}[raster column skip=.1\linewidth] \cmhlistingsfromfile{demonstrations/textwrap1-mod1.tex}{\texttt{textwrap1-mod1.tex}}{lst:textwrap1-mod1} - \end{minipage} - \hfill - \begin{minipage}{.45\linewidth} \cmhlistingsfromfile{demonstrations/textwrap1.yaml}[MLB-TCB]{\texttt{textwrap1.yaml}}{lst:textwrap1-yaml} - \end{minipage} + \end{cmhtcbraster} The text wrapping routine is performed \emph{after} verbatim environments have been stored, so verbatim environments and verbatim commands are exempt from the @@ -128,7 +126,7 @@ latexindent.pl -m textwrap3.tex -o textwrap3-mod1.tex -l textwrap1.yaml The text wrapping routine of \texttt{latexindent.pl} is performed by the \texttt{Text::Wrap} module, which provides a \texttt{separator} feature to separate lines with characters other than a new line (see - \cite{textwrap}). By default, the separator is empty which means that a new + \cite{textwrap}). By default, the separator is empty which means that a new line token will be used, but you can change it as you see fit. For example starting with the file in \cref{lst:textwrap4} @@ -141,13 +139,10 @@ latexindent.pl -m textwrap4.tex -o textwrap4-mod2.tex -l textwrap2.yaml \end{commandshell} then we obtain the output in \cref{lst:textwrap4-mod2}. - \begin{minipage}{.45\linewidth} + \begin{cmhtcbraster}[raster column skip=.1\linewidth] \cmhlistingsfromfile{demonstrations/textwrap4-mod2.tex}{\texttt{textwrap4-mod2.tex}}{lst:textwrap4-mod2} - \end{minipage} - \hfill - \begin{minipage}{.45\linewidth} \cmhlistingsfromfile{demonstrations/textwrap2.yaml}[MLB-TCB]{\texttt{textwrap2.yaml}}{lst:textwrap2-yaml} - \end{minipage} + \end{cmhtcbraster} \subsubsection{text wrapping on a per-code-block basis} By default, if the value of \texttt{columns} is greater than 0 and the @@ -179,20 +174,17 @@ latexindent.pl -m textwrap4.tex -o textwrap4-mod2.tex -l textwrap2.yaml \cmhlistingsfromfile{demonstrations/textwrap5.tex}{\texttt{textwrap5.tex}}{lst:textwrap5} \end{widepage} - With reference to this codeblock, the settings given in \cref{lst:textwrap3-yaml,lst:textwrap4-yaml,lst:textwrap5-yaml} each + With reference to this code block, the settings given in \cref{lst:textwrap3-yaml,lst:textwrap4-yaml,lst:textwrap5-yaml} each give the same output. - \begin{adjustwidth}{-3.5cm}{-2.5cm} - \begin{minipage}{.33\linewidth} - \cmhlistingsfromfile{demonstrations/textwrap3.yaml}[MLB-TCB]{\texttt{textwrap3.yaml}}{lst:textwrap3-yaml} - \end{minipage}% - \begin{minipage}{.33\linewidth} - \cmhlistingsfromfile{demonstrations/textwrap4.yaml}[MLB-TCB]{\texttt{textwrap4.yaml}}{lst:textwrap4-yaml} - \end{minipage}% - \begin{minipage}{.33\linewidth} - \cmhlistingsfromfile{demonstrations/textwrap5.yaml}[MLB-TCB]{\texttt{textwrap5.yaml}}{lst:textwrap5-yaml} - \end{minipage} - \end{adjustwidth} + \begin{cmhtcbraster}[raster columns=3, + raster left skip=-3.5cm, + raster right skip=-2cm, + raster column skip=.03\linewidth] + \cmhlistingsfromfile{demonstrations/textwrap3.yaml}[MLB-TCB]{\texttt{textwrap3.yaml}}{lst:textwrap3-yaml} + \cmhlistingsfromfile{demonstrations/textwrap4.yaml}[MLB-TCB]{\texttt{textwrap4.yaml}}{lst:textwrap4-yaml} + \cmhlistingsfromfile{demonstrations/textwrap5.yaml}[MLB-TCB]{\texttt{textwrap5.yaml}}{lst:textwrap5-yaml} + \end{cmhtcbraster} Let's explore the similarities and differences in the equivalent (with respect to \cref{lst:textwrap5}) syntax specified in \cref{lst:textwrap3-yaml,lst:textwrap4-yaml,lst:textwrap5-yaml}: @@ -214,7 +206,7 @@ latexindent.pl -m textwrap4.tex -o textwrap4-mod2.tex -l textwrap2.yaml latexindent.pl -s textwrap5.tex -l=textwrap3.yaml -m latexindent.pl -s textwrap5.tex -l=textwrap4.yaml -m latexindent.pl -s textwrap5.tex -l=textwrap5.yaml -m - \end{commandshell} +\end{commandshell} we obtain the output shown in \cref{lst:textwrap5-mod3}. \cmhlistingsfromfile{demonstrations/textwrap5-mod3.tex}{\texttt{textwrap5-mod3.tex}}{lst:textwrap5-mod3} @@ -229,7 +221,7 @@ latexindent.pl -s textwrap5.tex -l=textwrap5.yaml -m In particular, upon running \begin{commandshell} latexindent.pl -s textwrap6.tex -l=textwrap5.yaml -m - \end{commandshell} +\end{commandshell} we obtain the output given in \cref{lst:textwrap6-mod5}. \begin{widepage} @@ -261,7 +253,7 @@ latexindent.pl -s textwrap6.tex -l=textwrap5.yaml -m latexindent.pl -s textwrap6.tex -l=textwrap6.yaml -m latexindent.pl -s textwrap6.tex -l=textwrap7.yaml -m latexindent.pl -s textwrap6.tex -l=textwrap8.yaml -m - \end{commandshell} +\end{commandshell} we receive the respective output given in \crefrange{lst:textwrap6-mod6}{lst:textwrap6-mod8}. \begin{widepage} \cmhlistingsfromfile{demonstrations/textwrap6-mod6.tex}{\texttt{textwrap6.tex} using \cref{lst:textwrap6-yaml}}{lst:textwrap6-mod6} @@ -288,24 +280,21 @@ latexindent.pl -s textwrap6.tex -l=textwrap8.yaml -m \texttt{0}) and a positive integer (see \vref{lst:textwrap6}, for example). We explore further options in \crefrange{lst:textwrap9-yaml}{lst:textwrap11-yaml}. - \begin{adjustwidth}{-3.5cm}{-2.5cm} - \begin{minipage}{.33\linewidth} - \cmhlistingsfromfile{demonstrations/textwrap9.yaml}[MLB-TCB]{\texttt{textwrap9.yaml}}{lst:textwrap9-yaml} - \end{minipage}% - \begin{minipage}{.33\linewidth} - \cmhlistingsfromfile{demonstrations/textwrap10.yaml}[MLB-TCB]{\texttt{textwrap10.yaml}}{lst:textwrap10-yaml} - \end{minipage}% - \begin{minipage}{.33\linewidth} - \cmhlistingsfromfile{demonstrations/textwrap11.yaml}[MLB-TCB]{\texttt{textwrap11.yaml}}{lst:textwrap11-yaml} - \end{minipage} - \end{adjustwidth} + \begin{cmhtcbraster}[raster columns=3, + raster left skip=-3.5cm, + raster right skip=-2cm, + raster column skip=.03\linewidth] + \cmhlistingsfromfile{demonstrations/textwrap9.yaml}[MLB-TCB]{\texttt{textwrap9.yaml}}{lst:textwrap9-yaml} + \cmhlistingsfromfile{demonstrations/textwrap10.yaml}[MLB-TCB]{\texttt{textwrap10.yaml}}{lst:textwrap10-yaml} + \cmhlistingsfromfile{demonstrations/textwrap11.yaml}[MLB-TCB]{\texttt{textwrap11.yaml}}{lst:textwrap11-yaml} + \end{cmhtcbraster} \Cref{lst:textwrap9-yaml} and \cref{lst:textwrap10-yaml} are equivalent. Upon running the commands \begin{commandshell} latexindent.pl -s textwrap6.tex -l=textwrap9.yaml -m latexindent.pl -s textwrap6.tex -l=textwrap11.yaml -m - \end{commandshell} +\end{commandshell} we receive the respective output given in \cref{lst:textwrap6-mod9,lst:textwrap6-mod11}. \begin{widepage} @@ -330,12 +319,12 @@ latexindent.pl -s textwrap6.tex -l=textwrap11.yaml -m \texttt{80} will be used. \texttt{alignAtAmpersandTakesPriority} is set to \texttt{1} by default; assuming - that text wrapping is occuring on a per-code-block basis, and the current + that text wrapping is occurring on a per-code-block basis, and the current environment/code block is specified within \vref{lst:aligndelims:basic} then text wrapping will be disabled for this code block. If you wish to specify \texttt{afterHeading} commands (see - \vref{lst:indentAfterHeadings}) on a per-name basis, then you need to append the name with + \vref{lst:indentAfterHeadings}) on a per-name basis, then you need to append the name with \texttt{:heading}, for example, you might use \texttt{section:heading}. \subsubsection{Summary of text wrapping} @@ -357,7 +346,7 @@ latexindent.pl -s textwrap6.tex -l=textwrap11.yaml -m \subsection{oneSentencePerLine: modifying line breaks for sentences}\label{sec:onesentenceperline} You can instruct \texttt{latexindent.pl} to - format%%%%%% + 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 @@ -373,9 +362,9 @@ latexindent.pl -s textwrap6.tex -l=textwrap11.yaml -m \yamltitle{removeSentenceLineBreaks}{0|1} When operating upon sentences \texttt{latexindent.pl} will, by default, remove - internal linebreaks as \texttt{removeSentenceLineBreaks} is set to \texttt{1}. - Setting this switch to \texttt{0} instructs \texttt{latexindent.pl} - not to do so. + 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. For example, consider \texttt{multiple-sentences.tex} shown in \cref{lst:multiple-sentences}. @@ -386,32 +375,26 @@ latexindent.pl -s textwrap6.tex -l=textwrap11.yaml -m \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{commandshell} \end{widepage} then we obtain the respective output given in \cref{lst:multiple-sentences-mod1,lst:multiple-sentences-mod2}. - \begin{minipage}{.5\linewidth} + \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/multiple-sentences-mod1.tex}{\texttt{multiple-sentences.tex} using \cref{lst:manipulate-sentences-yaml}}{lst:multiple-sentences-mod1} - \end{minipage} - \hfill - \begin{minipage}{.5\linewidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/manipulate-sentences.yaml}[MLB-TCB]{\texttt{manipulate-sentences.yaml}}{lst:manipulate-sentences-yaml} - \end{minipage} + \end{cmhtcbraster} - \begin{minipage}{.5\linewidth} + \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/multiple-sentences-mod2.tex}{\texttt{multiple-sentences.tex} using \cref{lst:keep-sen-line-breaks-yaml}}{lst:multiple-sentences-mod2} - \end{minipage} - \hfill - \begin{minipage}{.5\linewidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/keep-sen-line-breaks.yaml}[MLB-TCB]{\texttt{keep-sen-line-breaks.yaml}}{lst:keep-sen-line-breaks-yaml} - \end{minipage} + \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}. The remainder of the settings displayed in \vref{lst:oneSentencePerLine} instruct - \texttt{latexindent.pl} on how to define a sentence. From the perpesctive of + \texttt{latexindent.pl} on how to define a sentence. From the perspective of \texttt{latexindent.pl} a sentence must: \begin{itemize} \item \emph{follow} a certain character or set of characters (see @@ -427,19 +410,14 @@ latexindent.pl multiple-sentences -m -l=keep-sen-line-breaks.yaml pattern that you would like; you can specify anything in this field using the language of regular expressions. - \begin{adjustwidth}{-3.5cm}{-2.5cm} - \begin{minipage}{.36\linewidth} - \cmhlistingsfromfile[style=sentencesFollow]*{../defaultSettings.yaml}[MLB-TCB,width=.9\linewidth,before=\centering]{\texttt{sentencesFollow}}{lst:sentencesFollow} - \end{minipage} - \hfill - \begin{minipage}{.31\linewidth} - \cmhlistingsfromfile[style=sentencesBeginWith]*{../defaultSettings.yaml}[MLB-TCB,width=.9\linewidth,before=\centering]{\texttt{sentencesBeginWith}}{lst:sentencesBeginWith} - \end{minipage} - \hfill - \begin{minipage}{.31\linewidth} - \cmhlistingsfromfile[style=sentencesEndWith]*{../defaultSettings.yaml}[MLB-TCB,width=.9\linewidth,before=\centering]{\texttt{sentencesEndWith}}{lst:sentencesEndWith} - \end{minipage} - \end{adjustwidth} + \begin{cmhtcbraster}[raster columns=3, + raster left skip=-3.5cm, + raster right skip=-2cm, + raster column skip=.06\linewidth] + \cmhlistingsfromfile[style=sentencesFollow]*{../defaultSettings.yaml}[MLB-TCB,width=.9\linewidth,before=\centering]{\texttt{sentencesFollow}}{lst:sentencesFollow} + \cmhlistingsfromfile[style=sentencesBeginWith]*{../defaultSettings.yaml}[MLB-TCB,width=.9\linewidth,before=\centering]{\texttt{sentencesBeginWith}}{lst:sentencesBeginWith} + \cmhlistingsfromfile[style=sentencesEndWith]*{../defaultSettings.yaml}[MLB-TCB,width=.9\linewidth,before=\centering]{\texttt{sentencesEndWith}}{lst:sentencesEndWith} + \end{cmhtcbraster} \subsubsection{sentencesFollow} Let's explore a few of the switches in \texttt{sentencesFollow}; let's start with @@ -450,13 +428,10 @@ latexindent.pl multiple-sentences -m -l=sentences-follow1.yaml \end{commandshell} we obtain the output given in \cref{lst:multiple-sentences-mod3}. - \begin{minipage}{.5\linewidth} + \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/multiple-sentences-mod3.tex}{\texttt{multiple-sentences.tex} using \cref{lst:sentences-follow1-yaml}}{lst:multiple-sentences-mod3} - \end{minipage} - \hfill - \begin{minipage}{.5\linewidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/sentences-follow1.yaml}[MLB-TCB]{\texttt{sentences-follow1.yaml}}{lst:sentences-follow1-yaml} - \end{minipage} + \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 @@ -472,18 +447,18 @@ latexindent.pl multiple-sentences -m -l=sentences-follow1.yaml \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{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{minipage}{.55\linewidth} + \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} - \end{minipage} - \hfill - \begin{minipage}{.45\linewidth} - \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/sentences-follow2.yaml}[MLB-TCB]{\texttt{sentences-follow2.yaml}}{lst:sentences-follow2-yaml} - \end{minipage} + \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 @@ -504,18 +479,18 @@ latexindent.pl multiple-sentences1 -m -l=manipulate-sentences.yaml,sentences-fol \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{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} - \begin{minipage}{.55\linewidth} + \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} - \end{minipage} - \hfill - \begin{minipage}{.45\linewidth} - \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/sentences-begin1.yaml}[MLB-TCB]{\texttt{sentences-begin1.yaml}}{lst:sentences-begin1-yaml} - \end{minipage} + \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 @@ -535,21 +510,15 @@ latexindent.pl multiple-sentences -m -l=sentences-end2.yaml \end{commandshell} then we obtain the output in \cref{lst:multiple-sentences-mod4}. - \begin{minipage}{.5\linewidth} + \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/multiple-sentences-mod4.tex}{\texttt{multiple-sentences.tex} using \cref{lst:sentences-end1-yaml}}{lst:multiple-sentences-mod4} - \end{minipage} - \hfill - \begin{minipage}{.5\linewidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/sentences-end1.yaml}[MLB-TCB]{\texttt{sentences-end1.yaml}}{lst:sentences-end1-yaml} - \end{minipage} + \end{cmhtcbraster} - \begin{minipage}{.5\linewidth} + \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/multiple-sentences-mod5.tex}{\texttt{multiple-sentences.tex} using \cref{lst:sentences-end2-yaml}}{lst:multiple-sentences-mod5} - \end{minipage} - \hfill - \begin{minipage}{.5\linewidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/sentences-end2.yaml}[MLB-TCB]{\texttt{sentences-end2.yaml}}{lst:sentences-end2-yaml} - \end{minipage} + \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 @@ -584,27 +553,31 @@ latexindent.pl url -m -l=manipulate-sentences.yaml \end{itemize} If you find that the \texttt{betterFullStop} does not work for your purposes, then you can switch it off by setting it to \texttt{0}, and you can - experiment with the \texttt{other} field. + 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 accomodate the specifications above. For example, using the following command + it does not accommodate the specifications above. For example, using the following + command \begin{commandshell} latexindent.pl url -m -l=alt-full-stop1.yaml \end{commandshell} and the YAML in \cref{lst:alt-full-stop1-yaml} gives the output in \cref{lst:url-mod2}. - \begin{adjustwidth}{-3.5cm}{-1.5cm} - \begin{minipage}{.6\linewidth} - \cmhlistingsfromfile{demonstrations/url-mod2.tex}{\texttt{url.tex} using \cref{lst:alt-full-stop1-yaml}}{lst:url-mod2} - \end{minipage} - \hfill - \begin{minipage}{.4\linewidth} - \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/alt-full-stop1.yaml}[MLB-TCB]{\texttt{alt-full-stop1.yaml}}{lst:alt-full-stop1-yaml} - \end{minipage} - \end{adjustwidth} + \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 accomodated correctly because of + 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}. \subsubsection{Features of the oneSentencePerLine routine} @@ -617,7 +590,7 @@ latexindent.pl url -m -l=alt-full-stop1.yaml \cref{lst:multiple-sentences3}, and run the command \begin{commandshell} latexindent.pl multiple-sentences3 -m -l=manipulate-sentences.yaml - \end{commandshell} +\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} @@ -627,30 +600,27 @@ latexindent.pl multiple-sentences3 -m -l=manipulate-sentences.yaml \begin{commandshell} latexindent.pl multiple-sentences4 -m -l=manipulate-sentences.yaml latexindent.pl multiple-sentences4 -m -l=keep-sen-line-breaks.yaml - \end{commandshell} +\end{commandshell} then we obtain the output in \cref{lst:multiple-sentences4-mod1,lst:multiple-sentences4-mod2}. \cmhlistingsfromfile{demonstrations/multiple-sentences4.tex}{\texttt{multiple-sentences4.tex}}{lst:multiple-sentences4} \begin{widepage} \cmhlistingsfromfile{demonstrations/multiple-sentences4-mod1.tex}{\texttt{multiple-sentences4.tex} using \vref{lst:manipulate-sentences-yaml}}{lst:multiple-sentences4-mod1} \end{widepage} \cmhlistingsfromfile{demonstrations/multiple-sentences4-mod2.tex}{\texttt{multiple-sentences4.tex} using \vref{lst:keep-sen-line-breaks-yaml}}{lst:multiple-sentences4-mod2} - Once you've read \cref{sec:poly-switches}, you will know that you can accomodate the + Once you've read \cref{sec:poly-switches}, you will know that you can accommodate the removal of internal sentence line breaks by using the YAML in \cref{lst:item-rules2-yaml} and the command \begin{commandshell} latexindent.pl multiple-sentences4 -m -l=item-rules2.yaml - \end{commandshell} +\end{commandshell} the output of which is shown in \cref{lst:multiple-sentences4-mod3}. - \begin{minipage}{.5\linewidth} + \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/multiple-sentences4-mod3.tex}{\texttt{multiple-sentences4.tex} using \cref{lst:item-rules2-yaml}}{lst:multiple-sentences4-mod3} - \end{minipage} - \hfill - \begin{minipage}{.5\linewidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/item-rules2.yaml}[MLB-TCB]{\texttt{item-rules2.yaml}}{lst:item-rules2-yaml} - \end{minipage} + \end{cmhtcbraster} \subsubsection{text wrapping and indenting sentences} - The \texttt{oneSentencePerLine}%%% + The \texttt{oneSentencePerLine}% \announce{2018-08-13}{oneSentencePerline text wrap and indent} can be instructed to perform text wrapping and indentation upon sentences. @@ -664,19 +634,18 @@ latexindent.pl multiple-sentences5 -m -l=sentence-wrap1.yaml \end{commandshell} we receive the output given in \cref{lst:multiple-sentences5-mod1}. - \begin{widepage} - \begin{minipage}{.55\linewidth} - \cmhlistingsfromfile{demonstrations/multiple-sentences5-mod1.tex}{\texttt{multiple-sentences5.tex} using \cref{lst:sentence-wrap1-yaml}}{lst:multiple-sentences5-mod1} - \end{minipage}% - \hfill - \begin{minipage}{.45\linewidth} - \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/sentence-wrap1.yaml}[MLB-TCB]{\texttt{sentence-wrap1.yaml}}{lst:sentence-wrap1-yaml} - \end{minipage} - \end{widepage} + \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} If you wish to specify the \texttt{columns} field on a per-code-block basis for sentences, then you would use \texttt{sentence}; explicitly, starting with - \vref{lst:textwrap9-yaml}, for example, you would replace/append + \vref{lst:textwrap9-yaml}, for example, you would replace/append \texttt{environments} with, for example, \texttt{sentence: 50}. The indentation of sentences requires that sentences are stored as code blocks. This @@ -752,13 +721,10 @@ latexindent.pl multiple-sentences6 -m -l=sentence-wrap1.yaml,itemize.yaml Let's start with the \texttt{.tex} file in \cref{lst:shortlines}, together with the YAML settings in \cref{lst:remove-para1-yaml}. - \begin{minipage}{.45\linewidth} + \begin{cmhtcbraster} \cmhlistingsfromfile[showspaces=true]{demonstrations/shortlines.tex}{\texttt{shortlines.tex}}{lst:shortlines} - \end{minipage} - \hfill - \begin{minipage}{.49\linewidth} \cmhlistingsfromfile{demonstrations/remove-para1.yaml}[MLB-TCB]{\texttt{remove-para1.yaml}}{lst:remove-para1-yaml} - \end{minipage} + \end{cmhtcbraster} Upon running the command \begin{commandshell} @@ -774,7 +740,7 @@ latexindent.pl -m shortlines.tex -o shortlines1.tex -l remove-para1.yaml \vref{lst:removeTWS-before} and running, for example, \begin{commandshell} latexindent.pl -m shortlines.tex -o shortlines1-tws.tex -l remove-para1.yaml,removeTWS-before.yaml - \end{commandshell} +\end{commandshell} in which case the output is as in \cref{lst:shortlines1-tws}; notice that the double spaces present in \cref{lst:shortlines1} have been addressed. @@ -784,13 +750,10 @@ latexindent.pl -m shortlines.tex -o shortlines1-tws.tex -l remove-para1.yaml,rem \texttt{all} switch applies to \emph{all} code block types. So, for example, let's consider the files in \cref{lst:shortlines-mand,lst:shortlines-opt} - \begin{minipage}{.45\linewidth} + \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/shortlines-mand.tex}{\texttt{shortlines-mand.tex}}{lst:shortlines-mand} - \end{minipage} - \hfill - \begin{minipage}{.45\linewidth} \cmhlistingsfromfile{demonstrations/shortlines-opt.tex}{\texttt{shortlines-opt.tex}}{lst:shortlines-opt} - \end{minipage} + \end{cmhtcbraster} Upon running the commands \begin{widepage} @@ -837,7 +800,7 @@ latexindent.pl -m shortlines-envs.tex -o shortlines-envs3.tex -l remove-para3.ya \cmhlistingsfromfile{demonstrations/shortlines-envs2.tex}{\texttt{shortlines-envs2.tex}}{lst:shortlines-envs2} \cmhlistingsfromfile{demonstrations/shortlines-envs3.tex}{\texttt{shortlines-envs3.tex}}{lst:shortlines-envs3} - The remaining code-block types can be customized in analogous ways, although note that + The remaining code-block types can be customised in analogous ways, although note that \texttt{commands}, \texttt{keyEqualsValuesBracesBrackets}, \texttt{namedGroupingBracesBrackets}, \texttt{UnNamedGroupingBracesBrackets} are controlled by the \texttt{optionalArguments} and the \texttt{mandatoryArguments}. @@ -847,13 +810,10 @@ latexindent.pl -m shortlines-envs.tex -o shortlines-envs3.tex -l remove-para3.ya code-blocks. For example, consider the file in \cref{lst:shortlines-md}, with the YAML settings in \cref{lst:remove-para4-yaml}. - \begin{minipage}{.45\linewidth} + \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/shortlines-md.tex}{\texttt{shortlines-md.tex}}{lst:shortlines-md} - \end{minipage} - \hfill - \begin{minipage}{.49\linewidth} \cmhlistingsfromfile{demonstrations/remove-para4.yaml}[MLB-TCB]{\texttt{remove-para4.yaml}}{lst:remove-para4-yaml} - \end{minipage} + \end{cmhtcbraster} Upon running the following command \begin{widepage} @@ -863,7 +823,7 @@ latexindent.pl -m shortlines-md.tex -o shortlines-md4.tex -l remove-para4.yaml \end{widepage} then we obtain the output in \cref{lst:shortlines-md4}. \cmhlistingsfromfile{demonstrations/shortlines-md4.tex}{\texttt{shortlines-md4.tex}}{lst:shortlines-md4} - Note%%%%% + Note% \announce{2018-08-13}*{updates to all in removeParagraphLineBreaks} that the \texttt{all} field can take the same exceptions detailed in \cref{lst:textwrap6-yaml}{lst:textwrap8-yaml}. @@ -903,7 +863,7 @@ latexindent.pl -m shortlines-md.tex -o shortlines-md4.tex -l remove-para4.yaml latexindent.pl -m sl-stop.tex -o sl-stop4.tex -l remove-para4.yaml latexindent.pl -m sl-stop.tex -o sl-stop4-command.tex -l=remove-para4.yaml,stop-command.yaml latexindent.pl -m sl-stop.tex -o sl-stop4-comment.tex -l=remove-para4.yaml,stop-comment.yaml - \end{commandshell} +\end{commandshell} \end{widepage} we obtain the respective outputs in \crefrange{lst:sl-stop4}{lst:sl-stop4-comment}; notice in particular that: @@ -931,7 +891,7 @@ latexindent.pl -m sl-stop.tex -o sl-stop4-comment.tex -l=remove-para4.yaml,stop- \subsection{Combining removeParagraphLineBreaks and textWrapOptions}\label{subsec:removeparagraphlinebreaks:and:textwrap} - The%%%%% + The% \announce{2018-08-13}{combine text wrap and remove paragraph line breaks} text wrapping routine (\vref{subsec:textwrapping}) and remove paragraph line breaks routine (\vref{subsec:removeparagraphlinebreaks}) can be combined. @@ -953,25 +913,22 @@ latexindent.pl -m sl-stop.tex -o sl-stop4-comment.tex -l=remove-para4.yaml,stop- Explicitly, using the settings in \cref{lst:textwrap12-yaml} and running the command \begin{commandshell} latexindent.pl -m textwrap7.tex -l=textwrap12.yaml -o=+-mod12 - \end{commandshell} +\end{commandshell} we obtain the output in \cref{lst:textwrap7-mod12}. - \begin{minipage}{.45\linewidth} + \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/textwrap7-mod12.tex}{\texttt{textwrap7-mod12.tex}}{lst:textwrap7-mod12} - \end{minipage} - \hfill - \begin{minipage}{.49\linewidth} \cmhlistingsfromfile{demonstrations/textwrap12.yaml}[MLB-TCB]{\texttt{textwrap12.yaml}}{lst:textwrap12-yaml} - \end{minipage} + \end{cmhtcbraster} - In \cref{lst:textwrap7-mod12} the paragraph linebreaks have first been removed from - \cref{lst:textwrap7}, and then the text wrapping routine has been applied. It is + In \cref{lst:textwrap7-mod12} the paragraph line breaks have first been removed from + \cref{lst:textwrap7}, and then the text wrapping routine has been applied. It is envisaged that variants of \cref{lst:textwrap12-yaml} will be among the most useful settings for these two features. \subsection{Poly-switches}\label{sec:poly-switches} Every other field in the \texttt{modifyLineBreaks} field uses poly-switches, and can - take one of \emph{five}%%%%%% + take one of \emph{five}% \announce{2017-08-21}*{blank line poly-switch} integer values: \begin{itemize}[font=\bfseries] \item[$-1$] \emph{remove mode}: line breaks before or after the @@ -989,7 +946,11 @@ latexindent.pl -m textwrap7.tex -l=textwrap12.yaml -o=+-mod12 \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. + 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{itemize} In the above, \emph{<part of thing>} refers to either the \emph{begin statement}, \emph{body} or \emph{end statement} @@ -1002,8 +963,9 @@ latexindent.pl -m textwrap7.tex -l=textwrap12.yaml -o=+-mod12 \cref{lst:environments-mlb}; note that it contains \emph{global} settings (immediately after the \texttt{environments} field) and that \emph{per-name} settings are also allowed -- in the case of - \cref{lst:environments-mlb}, settings for \texttt{equation*} have been - specified. Note that all poly-switches are \emph{off} by default. + \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. \cmhlistingsfromfile[style=modifylinebreaksEnv]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,MLB-TCB]{\texttt{environments}}{lst:environments-mlb} @@ -1070,7 +1032,7 @@ latexindent.pl -m env-mlb.tex -l env-mlb2.yaml \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/env-mlb4.yaml}[MLB-TCB]{\texttt{env-mlb4.yaml}}{lst:env-mlb4} \end{minipage} - Upon running commands analogous to the above, we obtain \cref{lst:env-mlb-mod3,lst:env-mlb-mod4}. + Upon running commands analogous to the above, we obtain \cref{lst:env-mlb-mod3,lst:env-mlb-mod4}. \begin{widepage} \begin{minipage}{.56\linewidth} @@ -1086,9 +1048,9 @@ latexindent.pl -m env-mlb.tex -l env-mlb2.yaml comment symbol has been added before adding the line break; in both cases, trailing horizontal space has been stripped before doing so. - Let's%%%%%% - \announce{2017-08-21}{demonstration of blank line poly-switch (3)} now change each - of the \texttt{1} values in \cref{lst:env-mlb1,lst:env-mlb2} so that they are + Let's% + \announce{2017-08-21}{demonstration of blank line poly-switch (3)} now change each of + the \texttt{1} values in \cref{lst:env-mlb1,lst:env-mlb2} so that they are $3$ and save them into \texttt{env-mlb5.yaml} and \texttt{env-mlb6.yaml} respectively (see \cref{lst:env-mlb5,lst:env-mlb6}). @@ -1100,7 +1062,7 @@ latexindent.pl -m env-mlb.tex -l env-mlb2.yaml \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/env-mlb6.yaml}[MLB-TCB]{\texttt{env-mlb6.yaml}}{lst:env-mlb6} \end{minipage} - Upon running commands analogous to the above, we obtain \cref{lst:env-mlb-mod5,lst:env-mlb-mod6}. + Upon running commands analogous to the above, we obtain \cref{lst:env-mlb-mod5,lst:env-mlb-mod6}. \begin{widepage} \begin{minipage}{.56\linewidth} @@ -1115,6 +1077,46 @@ latexindent.pl -m env-mlb.tex -l env-mlb2.yaml 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. + Let's now change% + \announce*{2019-07-13}{demonstration of new blank line poly-switch} each of + the \texttt{1} values in \cref{lst:env-mlb5,lst:env-mlb6} so that they are + $4$ and save them into \texttt{env-beg4.yaml} and + \texttt{env-body4.yaml} respectively (see \cref{lst:env-beg4,lst:env-body4}). + + \begin{minipage}{.45\textwidth} + \cmhlistingsfromfile*[style=yaml-LST]*{demonstrations/env-beg4.yaml}[MLB-TCB]{\texttt{env-beg4.yaml}}{lst:env-beg4} + \end{minipage} + \hfill + \begin{minipage}{.45\textwidth} + \cmhlistingsfromfile*[style=yaml-LST]*{demonstrations/env-body4.yaml}[MLB-TCB]{\texttt{env-body4.yaml}}{lst:env-body4} + \end{minipage} + + 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 + \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} + \subsubsection{Adding line breaks using EndStartsOnOwnLine and EndFinishesWithLineBreak} Let's explore \texttt{EndStartsOnOwnLine} and \texttt{EndFinishesWithLineBreak} in \cref{lst:env-mlb7,lst:env-mlb8}, and in particular, let's allow each of them in turn to take @@ -1168,7 +1170,7 @@ latexindent.pl -m env-mlb.tex -l env-mlb8.yaml \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/env-mlb10.yaml}[MLB-TCB]{\texttt{env-mlb10.yaml}}{lst:env-mlb10} \end{minipage} - Upon running commands analogous to the above, we obtain \cref{lst:env-mlb-mod9,lst:env-mlb-mod10}. + Upon running commands analogous to the above, we obtain \cref{lst:env-mlb-mod9,lst:env-mlb-mod10}. \begin{widepage} \begin{minipage}{.43\linewidth} @@ -1184,7 +1186,7 @@ latexindent.pl -m env-mlb.tex -l env-mlb8.yaml comment symbol has been added before adding the line break; in both cases, trailing horizontal space has been stripped before doing so. - Let's%%%%%% + Let's% \announce{2017-08-21}{demonstration of blank line poly-switch (3)} now change each of the \texttt{1} values in \cref{lst:env-mlb7,lst:env-mlb8} so that they are $3$ and save them into \texttt{env-mlb11.yaml} and @@ -1198,7 +1200,7 @@ latexindent.pl -m env-mlb.tex -l env-mlb8.yaml \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/env-mlb12.yaml}[MLB-TCB]{\texttt{env-mlb12.yaml}}{lst:env-mlb12} \end{minipage} - Upon running commands analogous to the above, we obtain \cref{lst:env-mlb-mod11,lst:env-mlb-mod12}. + Upon running commands analogous to the above, we obtain \cref{lst:env-mlb-mod11,lst:env-mlb-mod12}. \begin{widepage} \begin{minipage}{.42\linewidth} @@ -1213,11 +1215,50 @@ latexindent.pl -m env-mlb.tex -l env-mlb8.yaml Note that line breaks have been added as in \cref{lst:env-mlb-mod7,lst:env-mlb-mod8}, and that a \emph{blank line} has been added after the line break. -\subsubsection{poly-switches only add line breaks when necessary} + Let's now change% + \announce*{2019-07-13}{demonstration of new blank line poly-switch} each of + the \texttt{1} values in \cref{lst:env-mlb11,lst:env-mlb12} so that they are + $4$ and save them into \texttt{env-end4.yaml} and + \texttt{env-end-f4.yaml} respectively (see \cref{lst:env-end4,lst:env-end-f4}). + + \begin{minipage}{.45\textwidth} + \cmhlistingsfromfile*[style=yaml-LST]*{demonstrations/env-end4.yaml}[MLB-TCB]{\texttt{env-end4.yaml}}{lst:env-end4} + \end{minipage} + \hfill + \begin{minipage}{.5\textwidth} + \cmhlistingsfromfile*[style=yaml-LST]*{demonstrations/env-end-f4.yaml}[MLB-TCB]{\texttt{env-end-f4.yaml}}{lst:env-end-f4} + \end{minipage} + + We will demonstrate this poly-switch value using the code from + \vref{lst:env-mlb1-text}. + + Upon running the commands + \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} + +\subsubsection{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$), - it will only do so if necessary. For example, if you process the file in - \vref{lst:mlb2} using any of the YAML files presented so far in this section, + using a poly-switch value of $1$ (or $2$ + or $3$), it will only do so if necessary. For example, if you + process the file in \vref{lst:mlb2} using poly-switch values of 1, 2, or 3, it will be left unchanged. \begin{minipage}{.45\linewidth} @@ -1228,37 +1269,39 @@ latexindent.pl -m env-mlb.tex -l env-mlb8.yaml \cmhlistingsfromfile{demonstrations/env-mlb3.tex}{\texttt{env-mlb3.tex}}{lst:mlb3} \end{minipage} - In contrast, the output from processing the file in \cref{lst:mlb3} will vary - depending on the poly-switches used; in \cref{lst:env-mlb3-mod2} you'll see that the - comment symbol after the \lstinline!\begin{myenv}! has been moved to the next line, as - \texttt{BodyStartsOnOwnLine} is set to \texttt{1}. In + 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}. + + 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 + because \texttt{BodyStartsOnOwnLine} has been set to \texttt{2}, and + the comment symbol has \emph{not} been moved to its own line. You're encouraged to experiment with \cref{lst:mlb3} and by setting the other poly-switches considered so far to \texttt{2} in turn. - \begin{minipage}{.45\linewidth} + \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} - \end{minipage} - \hfill - \begin{minipage}{.45\linewidth} \cmhlistingsfromfile{demonstrations/env-mlb3-mod4.tex}{\texttt{env-mlb3.tex} using \vref{lst:env-mlb4}}{lst:env-mlb3-mod4} - \end{minipage} + \end{cmhtcbraster} 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. + poly-switches in the \texttt{environments} field; each switch can also be + specified on a \emph{per-name} basis, which would take priority over the + global values; with reference to \vref{lst:environments-mlb}, an example is shown for + the \texttt{equation*} environment. \subsubsection{Removing line breaks (poly-switches set to $-1$)} - Setting poly-switches to $-1$ tells \texttt{latexindent.pl} to - remove line breaks of the \emph{<part of the thing>}, if necessary. We will consider the - example code given in \cref{lst:mlb4}, noting in particular the positions of - the line break highlighters, $\BeginStartsOnOwnLine$, $\BodyStartsOnOwnLine$, - $\EndStartsOnOwnLine$ and $\EndFinishesWithLineBreak$, together with the associated - YAML files in \crefrange{lst:env-mlb13}{lst:env-mlb16}. + Setting poly-switches to $-1$ tells \texttt{latexindent.pl} + to remove line breaks of the \emph{<part of the thing>}, if necessary. We will consider + the example code given in \cref{lst:mlb4}, noting in particular the + positions of the line break highlighters, $\BeginStartsOnOwnLine$, + $\BodyStartsOnOwnLine$, $\EndStartsOnOwnLine$ and $\EndFinishesWithLineBreak$, + together with the associated YAML files in \crefrange{lst:env-mlb13}{lst:env-mlb16}. \begin{minipage}{.45\linewidth} \begin{cmhlistings}[style=tcblatex,escapeinside={(*@}{@*)}]{\texttt{env-mlb4.tex}}{lst:mlb4} @@ -1333,10 +1376,10 @@ latexindent.pl -m env-mlb4.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,e \texttt{removeTrailingWhitespace}, and that it has two (binary) switches to determine if horizontal space should be removed \texttt{beforeProcessing} and \texttt{afterProcessing}. The \texttt{beforeProcessing} is particularly relevant - when considering the \texttt{-m} switch; let's consider the file shown in - \cref{lst:mlb5}, which highlights trailing spaces. + when considering the \texttt{-m} switch; let's consider the file shown + in \cref{lst:mlb5}, which highlights trailing spaces. - \begin{minipage}{.45\linewidth} + \begin{cmhtcbraster} \begin{cmhlistings}[style=tcblatex,showspaces=true,escapeinside={(*@}{@*)}]{\texttt{env-mlb5.tex}}{lst:mlb5} before words (*@$\BeginStartsOnOwnLine$@*) \begin{myenv} (*@$\BodyStartsOnOwnLine$@*) @@ -1344,11 +1387,8 @@ body of myenv (*@$\EndStartsOnOwnLine$@*) \end{myenv} (*@$\EndFinishesWithLineBreak$@*) after words \end{cmhlistings} - \end{minipage} - \hfill - \begin{minipage}{.45\linewidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/removeTWS-before.yaml}[yaml-TCB]{\texttt{removeTWS-before.yaml}}{lst:removeTWS-before} - \end{minipage} + \end{cmhtcbraster} The output from the following commands \begin{widepage} @@ -1357,9 +1397,9 @@ latexindent.pl -m env-mlb5.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,e latexindent.pl -m env-mlb5.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,env-mlb16.yaml,removeTWS-before.yaml \end{commandshell} \end{widepage} - is shown, respectively, in \cref{lst:env-mlb5-modAll,lst:env-mlb5-modAll-remove-WS}; note that the trailing horizontal - white space has been preserved (by default) in \cref{lst:env-mlb5-modAll}, while in - \cref{lst:env-mlb5-modAll-remove-WS}, it has been removed using the switch specified in + 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} @@ -1371,7 +1411,7 @@ latexindent.pl -m env-mlb5.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,e \subsubsection{poly-switch line break removal and blank lines} Now let's consider the file in \cref{lst:mlb6}, which contains blank lines. - \begin{minipage}{.45\linewidth} + \begin{cmhtcbraster} \begin{cmhlistings}[style=tcblatex,escapeinside={(*@}{@*)}]{\texttt{env-mlb6.tex}}{lst:mlb6} before words(*@$\BeginStartsOnOwnLine$@*) @@ -1386,11 +1426,8 @@ body of myenv(*@$\EndStartsOnOwnLine$@*) after words \end{cmhlistings} - \end{minipage}% - \hfill - \begin{minipage}{.45\linewidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/UnpreserveBlankLines.yaml}[MLB-TCB]{\texttt{UnpreserveBlankLines.yaml}}{lst:UnpreserveBlankLines} - \end{minipage} + \end{cmhtcbraster} Upon running the following commands \begin{widepage} @@ -1400,22 +1437,23 @@ latexindent.pl -m env-mlb6.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,e \end{commandshell} \end{widepage} we receive the respective outputs in \cref{lst:env-mlb6-modAll,lst:env-mlb6-modAll-un-Preserve-Blank-Lines}. In - \cref{lst:env-mlb6-modAll} we see that the multiple blank lines have each been condensed - into one blank line, but that blank lines have \emph{not} been removed - by the poly-switches -- this is because, by default, \texttt{preserveBlankLines} is set - to \texttt{1}. By contrast, in \cref{lst:env-mlb6-modAll-un-Preserve-Blank-Lines}, we have - allowed the poly-switches to remove blank lines because, in \cref{lst:UnpreserveBlankLines}, - we have set \texttt{preserveBlankLines} to \texttt{0}. - - \begin{widepage} - \begin{minipage}{.30\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} - \end{minipage} - \hfill - \begin{minipage}{.65\linewidth} - \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{minipage} - \end{widepage} + \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} 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}. @@ -1426,7 +1464,7 @@ latexindent.pl -m env-mlb6.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,e \begin{commandshell} latexindent.pl -m env-mlb7.tex -l env-mlb12.yaml,env-mlb13.yaml latexindent.pl -m env-mlb7.tex -l env-mlb13.yaml,env-mlb14.yaml,UnpreserveBlankLines.yaml - \end{commandshell} +\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} @@ -1443,80 +1481,266 @@ latexindent.pl -m env-mlb7.tex -l env-mlb13.yaml,env-mlb14.yaml,UnpreserveBlankL because of the settings in \cref{lst:UnpreserveBlankLines}. \end{itemize} +\subsection{Poly-switches for double back slash}\label{subsec:dbs} + With reference to \texttt{lookForAlignDelims} (see \vref{lst:aligndelims:basic})% + \announce*{2019-07-13}{poly-switch for double back slash} you can + specify poly-switches to dictate the line-break behaviour of double back slashes in + environments (\vref{lst:tabularafter:basic}), commands (\vref{lst:matrixafter}), or + special code blocks (\vref{lst:specialafter}). Note that for these poly-switches to + take effect, the name of the code block must necessarily be specified within + \texttt{lookForAlignDelims} (\vref{lst:aligndelims:basic}); we will demonstrate this in what follows. + + 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 back slash}; + \item line breaks ahead of the double back slash are annotated by $\ElseStartsOnOwnLine$, + and are controlled by \texttt{DBSStartsOnOwnLine}; + \item line breaks after the double back slash are annotated by $\ElseFinishesWithLineBreak$, and + are controlled by \texttt{DBSFinishesWithLineBreak}. + \end{itemize} + + Let's explore each of these in turn. + +\subsubsection{Double back slash starts on own line} + 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 + \begin{commandshell} +latexindent.pl -m tabular3.tex -l DBS1.yaml +latexindent.pl -m tabular3.tex -l DBS2.yaml +\end{commandshell} + then we receive the respective output given in \cref{lst:tabular3-DBS1} and + \cref{lst:tabular3-DBS2}. + + \begin{cmhtcbraster}[raster column skip=.01\linewidth] + \cmhlistingsfromfile*{demonstrations/tabular3-mod1.tex}{\texttt{tabular3.tex} using \cref{lst:DBS1}}{lst:tabular3-DBS1} + \cmhlistingsfromfile*[style=yaml-LST]*{demonstrations/DBS1.yaml}[MLB-TCB]{\texttt{DBS1.yaml}}{lst:DBS1} + \end{cmhtcbraster} + + \begin{cmhtcbraster}[raster column skip=.01\linewidth] + \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{yaml:lookforaligndelims}); + the double back slashes 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{yaml:lookforaligndelims}); + the double back slashes from \cref{lst:dbs-demo} have been moved to their own + line in \cref{lst:tabular3-DBS2}, having added comment symbols before moving them. + \end{itemize} + +\subsubsection{Double back slash finishes with line break} + 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 + \begin{commandshell} +latexindent.pl -m tabular3.tex -l DBS3.yaml +latexindent.pl -m tabular3.tex -l DBS4.yaml +\end{commandshell} + then we receive the respective output given in \cref{lst:tabular3-DBS3} and + \cref{lst:tabular3-DBS4}. + + \begin{cmhtcbraster}[raster column skip=.01\linewidth] + \cmhlistingsfromfile*{demonstrations/tabular3-mod3.tex}{\texttt{tabular3.tex} using \cref{lst:DBS3}}{lst:tabular3-DBS3} + \cmhlistingsfromfile*[style=yaml-LST]*{demonstrations/DBS3.yaml}[MLB-TCB]{\texttt{DBS3.yaml}}{lst:DBS3} + \end{cmhtcbraster} + + \begin{cmhtcbraster}[raster column skip=.01\linewidth] + \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{yaml:lookforaligndelims}); + the code following the double back slashes 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{yaml:lookforaligndelims}); + the first double back slashes from \cref{lst:dbs-demo} have moved code following + them to their own line in \cref{lst:tabular3-DBS4}, having added comment symbols + before moving them; the final double back slashes have \emph{not} added + a line break as they are at the end of the body within the code block. + \end{itemize} + +\subsubsection{Double back slash poly switches for specialBeginEnd} + Let's explore the double back slash poly-switches for code blocks within + \texttt{specialBeginEnd} code blocks (\vref{lst:specialBeginEnd}); we begin with + the code within \cref{lst:special4}. + + \cmhlistingsfromfile*{demonstrations/special4.tex}{\texttt{special4.tex}}{lst:special4} + + Upon using the YAML settings in \cref{lst:DBS5}, and running the command + \begin{commandshell} +latexindent.pl -m special4.tex -l DBS5.yaml +\end{commandshell} + then we receive the output given in \cref{lst:special4-DBS5}. + + \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 back slash poly-switches would be + ignored for this code block; + \item the \texttt{DBSFinishesWithLineBreak} poly-switch has controlled the line breaks following the + double back slashes; + \item the \texttt{SpecialEndStartsOnOwnLine} poly-switch has controlled the addition of a comment + symbol, followed by a line break, as it is set to a value of 2. + \end{itemize} + +\subsubsection{Double back slash poly switches for optional and mandatory arguments} + For clarity, we provide a demonstration of controlling the double back slash + poly-switches for optional and mandatory arguments. We begin with the code in + \cref{lst:mycommand2}. + + \cmhlistingsfromfile*{demonstrations/mycommand2.tex}{\texttt{mycommand2.tex}}{lst:mycommand2} + + Upon using the YAML settings in \cref{lst:DBS6,lst:DBS7}, and running the command + \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} + +\subsubsection{Double back slash optional square brackets} + The pattern matching for the double back slash will also, optionally, allow trailing + square brackets that contain a measurement of vertical spacing, for example + \lstinline!\\[3pt]!. + + 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}, + \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} + + You can customise the pattern for the double back slash by exploring the + \emph{fine tuning} field detailed in \vref{lst:fineTuning}. + \subsection{Poly-switches for other code blocks} Rather than repeat the examples shown for the environment code blocks (in \vref{sec:modifylinebreaks-environments}), we choose to detail the poly-switches for all other code blocks in \cref{tab:poly-switch-mapping}; note that each and every one of these poly-switches is \emph{off by default}, i.e, set to \texttt{0}. - Note also that, by design, line breaks involving, - \texttt{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}). + 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}). - \clearpage + \clearpage \begin{longtable}{llll} - \caption{Poly-switch mappings for all code-block types}\label{tab:poly-switch-mapping} \\ + \caption{Poly-switch mappings for all code-block types}\label{tab:poly-switch-mapping} \\ \toprule - Code block & Sample & \multicolumn{2}{c}{Poly-switch mapping} \\ + 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! & & \\ + 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 polyswitches} \\ - & \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! & & \\ + 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 \\ - & \verb!body of opt arg!$\EndStartsOnOwnLine$ & $\EndStartsOnOwnLine$ & RSqBStartsOnOwnLine \\ - & \verb!]!$\EndFinishesWithLineBreak$ & $\EndFinishesWithLineBreak$ & RSqBFinishesWithLineBreak \\ - & \verb!...! & & \\ + 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 \\ - & \verb!body of mand arg!$\EndStartsOnOwnLine$ & $\EndStartsOnOwnLine$ & RCuBStartsOnOwnLine \\ - & \verb!}!$\EndFinishesWithLineBreak$ & $\EndFinishesWithLineBreak$ & RCuBFinishesWithLineBreak \\ - & \verb!...! & & \\ + 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$ & & \\ + commands & \verb!before words!$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & CommandStartsOnOwnLine \\ + & \verb!\mycommand!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & CommandNameFinishesWithLineBreak \\ + & $\langle$\itshape{arguments}$\rangle$ & & \\ \cmidrule{2-4} - namedGroupingBraces Brackets & before words$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & NameStartsOnOwnLine \\ - & myname$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & NameFinishesWithLineBreak \\ - & $\langle$\itshape{braces/brackets}$\rangle$ & & \\ + namedGroupingBraces Brackets & 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 \\ + 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!...! & & \\ + 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 polyswitches} \\ - & \verb!\middle!$\ElseFinishesWithLineBreak$ & $\ElseFinishesWithLineBreak$ & SpecialMiddleFinishesWithLineBreak \\ - & body of special/middle $\EndStartsOnOwnLine$ & $\EndStartsOnOwnLine$ & SpecialEndStartsOnOwnLine \\ - & \verb!\]!$\EndFinishesWithLineBreak$ & $\EndFinishesWithLineBreak$ & SpecialEndFinishesWithLineBreak \\ - & after words & & \\ + 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 & & \\ + 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} diff --git a/Master/texmf-dist/doc/support/latexindent/subsec-commands-and-their-options.tex b/Master/texmf-dist/doc/support/latexindent/subsec-commands-and-their-options.tex index a6caa007060..a1184bf3a59 100644 --- a/Master/texmf-dist/doc/support/latexindent/subsec-commands-and-their-options.tex +++ b/Master/texmf-dist/doc/support/latexindent/subsec-commands-and-their-options.tex @@ -7,7 +7,7 @@ \yamltitle{commandCodeBlocks}*{fields} - The \texttt{commandCodeBlocks} field%%%% + The \texttt{commandCodeBlocks} field% \announce{2018-04-27}*{commandCodeBlocks} contains a few switches detailed in \cref{lst:commandCodeBlocks}. @@ -43,16 +43,13 @@ Upon using the YAML settings in \cref{lst:noRoundParentheses}, and running the command \begin{commandshell} latexindent.pl pstricks1.tex -l noRoundParentheses.yaml - \end{commandshell} +\end{commandshell} we obtain the output given in \cref{lst:pstricks1-nrp}. - \begin{minipage}{.45\textwidth} + \begin{cmhtcbraster}[raster column skip=.1\linewidth] \cmhlistingsfromfile{demonstrations/pstricks1-nrp.tex}{\texttt{pstricks1.tex} using \cref{lst:noRoundParentheses}}{lst:pstricks1-nrp} - \end{minipage} - \hfill - \begin{minipage}{.45\textwidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/noRoundParentheses.yaml}[yaml-TCB]{\texttt{noRoundParentheses.yaml}}{lst:noRoundParentheses} - \end{minipage} + \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 @@ -65,16 +62,13 @@ latexindent.pl pstricks1.tex -l noRoundParentheses.yaml Let's explore this using the YAML given in \cref{lst:defFunction} and run the command \begin{commandshell} latexindent.pl pstricks1.tex -l defFunction.yaml - \end{commandshell} +\end{commandshell} then the output is as in \cref{lst:pstricks1-indent-rules}. - \begin{minipage}{.45\textwidth} + \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} - \end{minipage} - \hfill - \begin{minipage}{.45\textwidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/defFunction.yaml}[yaml-TCB]{\texttt{defFunction.yaml}}{lst:defFunction} - \end{minipage} + \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 @@ -121,13 +115,10 @@ latexindent.pl tikz-node1.tex -l draw.yaml \end{commandshell} we receive the output given in \cref{lst:tikz-node1-draw}. - \begin{minipage}{.45\textwidth} + \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} - \end{minipage} - \hfill - \begin{minipage}{.45\textwidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/draw.yaml}[yaml-TCB]{\texttt{draw.yaml}}{lst:draw} - \end{minipage} + \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 @@ -140,13 +131,10 @@ latexindent.pl tikz-node1.tex -l no-strings.yaml \end{commandshell} given in \cref{lst:tikz-node1-no-strings}. - \begin{minipage}{.45\textwidth} + \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} - \end{minipage} - \hfill - \begin{minipage}{.49\textwidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/no-strings.yaml}[yaml-TCB]{\texttt{no-strings.yaml}}{lst:no-strings} - \end{minipage} + \end{cmhtcbraster} In this case, \texttt{latexindent.pl} sees that: \begin{itemize} @@ -166,19 +154,15 @@ latexindent.pl tikz-node1.tex -l no-strings.yaml the settings in either \cref{lst:amalgamate-demo} or\cref{lst:amalgamate-demo1} is equivalent to using the settings in \cref{lst:amalgamate-demo2}. - \begin{adjustwidth}{-3.5cm}{-1.5cm} - \begin{minipage}{.32\linewidth} - \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/amalgamate-demo.yaml}[yaml-TCB]{\texttt{amalgamate-demo.yaml}}{lst:amalgamate-demo} - \end{minipage}% - \hfill - \begin{minipage}{.32\linewidth} - \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/amalgamate-demo1.yaml}[yaml-TCB]{\texttt{amalgamate-demo1.yaml}}{lst:amalgamate-demo1} - \end{minipage}% - \hfill - \begin{minipage}{.32\linewidth} - \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/amalgamate-demo2.yaml}[yaml-TCB]{\texttt{amalgamate-demo2.yaml}}{lst:amalgamate-demo2} - \end{minipage} - \end{adjustwidth} + \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 @@ -192,13 +176,10 @@ latexindent.pl tikz-node1.tex -l no-strings.yaml We may explore this feature further with the code in \cref{lst:for-each}, whose default output is given in \cref{lst:for-each-default}. - \begin{minipage}{.45\textwidth} + \begin{cmhtcbraster}[raster column skip=.1\linewidth] \cmhlistingsfromfile{demonstrations/for-each.tex}{\texttt{for-each.tex}}{lst:for-each} - \end{minipage} - \hfill - \begin{minipage}{.45\textwidth} \cmhlistingsfromfile{demonstrations/for-each-default.tex}{\texttt{for-each} default output}{lst:for-each-default} - \end{minipage} + \end{cmhtcbraster} Let's compare this with the output from using the YAML settings in \cref{lst:foreach}, and running the command @@ -207,13 +188,10 @@ latexindent.pl for-each.tex -l foreach.yaml \end{commandshell} given in \cref{lst:for-each-mod1}. - \begin{minipage}{.45\textwidth} + \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} - \end{minipage} - \hfill - \begin{minipage}{.49\textwidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/foreach.yaml}[yaml-TCB]{\texttt{foreach.yaml}}{lst:foreach} - \end{minipage} + \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 @@ -225,7 +203,7 @@ latexindent.pl for-each.tex -l foreach.yaml \yamltitle{commandNameSpecial}*{fields} There are some special command names% - \announce{2018-04-27}*{commandNameSpecial} that do not fit within the names recognized by + \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, @@ -236,13 +214,10 @@ latexindent.pl for-each.tex -l foreach.yaml For example, consider the sample file in \cref{lst:ifnextchar}, which has default output in \cref{lst:ifnextchar-default}. - \begin{minipage}{.45\textwidth} + \begin{cmhtcbraster}[raster column skip=.1\linewidth] \cmhlistingsfromfile{demonstrations/ifnextchar.tex}{\texttt{ifnextchar.tex}}{lst:ifnextchar} - \end{minipage} - \hfill - \begin{minipage}{.45\textwidth} \cmhlistingsfromfile{demonstrations/ifnextchar-default.tex}{\texttt{ifnextchar.tex} default output}{lst:ifnextchar-default} - \end{minipage} + \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 @@ -256,13 +231,10 @@ latexindent.pl for-each.tex -l foreach.yaml to indent its body successfully, because the \lstinline!\@ifnextchar[! command has not been found. - \begin{minipage}{.45\textwidth} + \begin{cmhtcbraster}[raster column skip=.1\linewidth] \cmhlistingsfromfile{demonstrations/ifnextchar-off.tex}{\texttt{ifnextchar.tex} using \cref{lst:no-ifnextchar}}{lst:ifnextchar-off} - \end{minipage} - \hfill - \begin{minipage}{.45\textwidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/no-ifnextchar.yaml}[yaml-TCB]{\texttt{no-ifnextchar.yaml}}{lst:no-ifnextchar} - \end{minipage} + \end{cmhtcbraster} 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 diff --git a/Master/texmf-dist/doc/support/latexindent/subsec-conflicting-poly-switches.tex b/Master/texmf-dist/doc/support/latexindent/subsec-conflicting-poly-switches.tex index 2a5d0bcd340..25ebe3efaa2 100644 --- a/Master/texmf-dist/doc/support/latexindent/subsec-conflicting-poly-switches.tex +++ b/Master/texmf-dist/doc/support/latexindent/subsec-conflicting-poly-switches.tex @@ -8,13 +8,10 @@ latexindent.pl -m -l=mycom-mlb4.yaml mycommand1.tex \end{commandshell} is given in \cref{lst:mycom-mlb4}. - \begin{minipage}{.4\linewidth} + \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/mycommand1-mlb4.tex}{\texttt{mycommand1.tex} using \cref{lst:mycom-mlb4}}{lst:mycommand1-mlb4} - \end{minipage} - \hfill - \begin{minipage}{.55\linewidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/mycom-mlb4.yaml}[MLB-TCB,width=\linewidth]{\texttt{mycom-mlb4.yaml}}{lst:mycom-mlb4} - \end{minipage} + \end{cmhtcbraster} Studying \cref{lst:mycom-mlb4}, we see that the two poly-switches are at opposition with one another: @@ -35,26 +32,20 @@ latexindent.pl -m -l=mycom-mlb5.yaml mycommand1.tex \end{commandshell} we obtain the output given in \cref{lst:mycommand1-mlb5}. - \begin{minipage}{.4\linewidth} + \begin{cmhtcbraster}[raster column skip=.1\linewidth] \cmhlistingsfromfile{demonstrations/mycommand1-mlb5.tex}{\texttt{mycommand1.tex} using \cref{lst:mycom-mlb5}}{lst:mycommand1-mlb5} - \end{minipage} - \hfill - \begin{minipage}{.55\linewidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/mycom-mlb5.yaml}[MLB-TCB,width=\linewidth]{\texttt{mycom-mlb5.yaml}}{lst:mycom-mlb5} - \end{minipage} + \end{cmhtcbraster} As previously, the most-recently-processed code block takes priority -- as before, the second (i.e, \emph{last}) argument. Exploring this further, we consider the YAML settings in \cref{lst:mycom-mlb6}, which give associated output in \cref{lst:mycommand1-mlb6}. - \begin{minipage}{.4\linewidth} + \begin{cmhtcbraster}[raster column skip=.1\linewidth] \cmhlistingsfromfile{demonstrations/mycommand1-mlb6.tex}{\texttt{mycommand1.tex} using \cref{lst:mycom-mlb6}}{lst:mycommand1-mlb6} - \end{minipage} - \hfill - \begin{minipage}{.55\linewidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/mycom-mlb6.yaml}[MLB-TCB,width=\linewidth]{\texttt{mycom-mlb6.yaml}}{lst:mycom-mlb6} - \end{minipage} + \end{cmhtcbraster} Note that a \lstinline!%! \emph{has} been added to the trailing first \lstinline!}!; this is because: @@ -78,16 +69,13 @@ latexindent.pl -m -l=mycom-mlb5.yaml mycommand1.tex command \begin{commandshell} latexindent.pl -m -l=nested-env-mlb1.yaml nested-env.tex - \end{commandshell} +\end{commandshell} gives the output in \cref{lst:nested-env-mlb1}. - \begin{minipage}{.45\linewidth} + \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} - \end{minipage} - \hfill - \begin{minipage}{.55\linewidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/nested-env-mlb1.yaml}[MLB-TCB,width=\linewidth]{\texttt{nested-env-mlb1.yaml}}{lst:nested-env-mlb1-yaml} - \end{minipage} + \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 @@ -146,16 +134,13 @@ latexindent.pl -m -l=nested-env-mlb1.yaml nested-env.tex running the command \begin{commandshell} latexindent.pl -m -l=nested-env-mlb2.yaml nested-env.tex - \end{commandshell} +\end{commandshell} we obtain the output given in \cref{lst:nested-env-mlb2-output}. - \begin{minipage}{.45\linewidth} + \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/nested-env-mlb2.tex}{\texttt{nested-env.tex} using \cref{lst:nested-env-mlb2}}{lst:nested-env-mlb2-output} - \end{minipage} - \hfill - \begin{minipage}{.55\linewidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/nested-env-mlb2.yaml}[MLB-TCB,width=\linewidth]{\texttt{nested-env-mlb2.yaml}}{lst:nested-env-mlb2} - \end{minipage} + \end{cmhtcbraster} During Phase 1: \begin{itemize} diff --git a/Master/texmf-dist/doc/support/latexindent/subsec-noAdditionalIndent-indentRules.tex b/Master/texmf-dist/doc/support/latexindent/subsec-noAdditionalIndent-indentRules.tex index 8f0a737a353..53fd835392f 100644 --- a/Master/texmf-dist/doc/support/latexindent/subsec-noAdditionalIndent-indentRules.tex +++ b/Master/texmf-dist/doc/support/latexindent/subsec-noAdditionalIndent-indentRules.tex @@ -3,7 +3,7 @@ \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 + 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$}; diff --git a/Master/texmf-dist/doc/support/latexindent/subsec-partnering-poly-switches.tex b/Master/texmf-dist/doc/support/latexindent/subsec-partnering-poly-switches.tex index 05734f54bea..03337669efb 100644 --- a/Master/texmf-dist/doc/support/latexindent/subsec-partnering-poly-switches.tex +++ b/Master/texmf-dist/doc/support/latexindent/subsec-partnering-poly-switches.tex @@ -19,33 +19,33 @@ latexindent.pl -m -l=mycom-mlb1.yaml mycommand1.tex beginning brace \lstinline!{! has had its leading line break removed, but that the \emph{first} brace has not. - \begin{minipage}{.4\linewidth} + \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} - \end{minipage} - \hfill - \begin{minipage}{.55\linewidth} - \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/mycom-mlb1.yaml}[MLB-TCB,width=\linewidth]{\texttt{mycom-mlb1.yaml}}{lst:mycom-mlb1} - \end{minipage} + \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/mycom-mlb1.yaml}[MLB-TCB,width=.6\textwidth]{\texttt{mycom-mlb1.yaml}}{lst:mycom-mlb1} + \end{cmhtcbraster} Now let's change the YAML file so that it is as in \cref{lst:mycom-mlb2}; upon running the analogous command to that given above, we obtain \cref{lst:mycommand1-mlb2}; both beginning braces \lstinline!{! have had their leading line breaks removed. - \begin{minipage}{.4\linewidth} + \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} - \end{minipage} - \hfill - \begin{minipage}{.55\linewidth} - \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/mycom-mlb2.yaml}[MLB-TCB,width=\linewidth]{\texttt{mycom-mlb2.yaml}}{lst:mycom-mlb2} - \end{minipage} + \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/mycom-mlb2.yaml}[MLB-TCB,width=.6\textwidth]{\texttt{mycom-mlb2.yaml}}{lst:mycom-mlb2} + \end{cmhtcbraster} Now let's change the YAML file so that it is as in \cref{lst:mycom-mlb3}; upon running the analogous command to that given above, we obtain \cref{lst:mycommand1-mlb3}. - \begin{minipage}{.4\linewidth} + \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} - \end{minipage} - \hfill - \begin{minipage}{.55\linewidth} - \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/mycom-mlb3.yaml}[MLB-TCB,width=\linewidth]{\texttt{mycom-mlb3.yaml}}{lst:mycom-mlb3} - \end{minipage} + \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/mycom-mlb3.yaml}[MLB-TCB,width=.6\textwidth]{\texttt{mycom-mlb3.yaml}}{lst:mycom-mlb3} + \end{cmhtcbraster} diff --git a/Master/texmf-dist/doc/support/latexindent/subsubsec-commands-with-arguments.tex b/Master/texmf-dist/doc/support/latexindent/subsubsec-commands-with-arguments.tex index 6e6b0074c1e..84bff810a1e 100644 --- a/Master/texmf-dist/doc/support/latexindent/subsubsec-commands-with-arguments.tex +++ b/Master/texmf-dist/doc/support/latexindent/subsubsec-commands-with-arguments.tex @@ -5,13 +5,10 @@ \cref{lst:mycommand-default}. \footnote{The command code blocks have quite a few subtleties, described in \vref{subsec:commands-string-between}.} - \begin{minipage}{.45\textwidth} + \begin{cmhtcbraster}[raster column skip=.1\linewidth] \cmhlistingsfromfile{demonstrations/mycommand.tex}{\texttt{mycommand.tex}}{lst:mycommand} - \end{minipage}% - \hfill - \begin{minipage}{.45\textwidth} \cmhlistingsfromfile{demonstrations/mycommand-default.tex}{\texttt{mycommand.tex} default output}{lst:mycommand-default} - \end{minipage} + \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 diff --git a/Master/texmf-dist/doc/support/latexindent/subsubsec-environments-and-their-arguments.tex b/Master/texmf-dist/doc/support/latexindent/subsubsec-environments-and-their-arguments.tex index 9a137aa622f..a37e3eb0edb 100644 --- a/Master/texmf-dist/doc/support/latexindent/subsubsec-environments-and-their-arguments.tex +++ b/Master/texmf-dist/doc/support/latexindent/subsubsec-environments-and-their-arguments.tex @@ -47,7 +47,11 @@ latexindent.pl myenv.tex -l myenv-noAdd4.yaml \cmhlistingsfromfile{demonstrations/myenvironment-simple-noAdd-body4.tex}{\texttt{myenv.tex output} (using either \cref{lst:myenv-noAdd3} or \cref{lst:myenv-noAdd4})}{lst:myenv-output-4} Let's now allow \texttt{myenv} to have some optional and mandatory arguments, as - in \cref{lst:myenv-args}. \cmhlistingsfromfile{demonstrations/myenvironment-args.tex}{\texttt{myenv-args.tex}}{lst:myenv-args} Upon running + in \cref{lst:myenv-args}. + + \cmhlistingsfromfile{demonstrations/myenvironment-args.tex}{\texttt{myenv-args.tex}}{lst:myenv-args} + + Upon running \begin{commandshell} latexindent.pl -l=myenv-noAdd1.yaml myenv-args.tex \end{commandshell} @@ -92,13 +96,10 @@ latexindent.pl myenv.tex -l myenv-noAdd6.yaml We may also specify indentation rules for environment code blocks using the \texttt{indentRules} field; see, for example, \cref{lst:myenv-rules1,lst:myenv-rules2}. - \begin{minipage}{.45\textwidth} + \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} - \end{minipage} - \hfill - \begin{minipage}{.45\textwidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/myenv-rules2.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-rules2.yaml}}{lst:myenv-rules2} - \end{minipage} + \end{cmhtcbraster} On applying either of the following commands, \begin{commandshell} @@ -206,8 +207,8 @@ latexindent.pl myenv-args.tex -l myenv-rules1.yaml,env-noAdditionalGlobal.yaml we may run the commands \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 +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 @@ -232,8 +233,8 @@ latexindent.pl myenv-args.tex -local mand-args-no-add-glob.yaml \lstinline!" "!, and then run the following commands \begin{commandshell} -latexindent.pl myenv-args.tex -l env-indentRules.yaml -latexindent.pl myenv-args.tex -l myenv-rules1.yaml,env-indentRules.yaml +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 @@ -263,8 +264,8 @@ latexindent.pl myenv-args.tex -l myenv-rules1.yaml,env-indentRules.yaml Upon running the following commands \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 +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 diff --git a/Master/texmf-dist/doc/support/latexindent/subsubsec-environments-with-items.tex b/Master/texmf-dist/doc/support/latexindent/subsubsec-environments-with-items.tex index c5b71a71e38..4cc53e654f3 100644 --- a/Master/texmf-dist/doc/support/latexindent/subsubsec-environments-with-items.tex +++ b/Master/texmf-dist/doc/support/latexindent/subsubsec-environments-with-items.tex @@ -11,13 +11,10 @@ the indentation that your \texttt{item} receives using \texttt{indentRules}, as in \cref{lst:item-rules1} - \begin{minipage}{.45\textwidth} + \begin{cmhtcbraster}[raster column skip=.1\linewidth] \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/item-noAdd1.yaml}[yaml-TCB]{\texttt{item-noAdd1.yaml}}{lst:item-noAdd1} - \end{minipage}% - \hfill - \begin{minipage}{.45\textwidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/item-rules1.yaml}[yaml-TCB]{\texttt{item-rules1.yaml}}{lst:item-rules1} - \end{minipage} + \end{cmhtcbraster} Upon running the following commands \begin{commandshell} diff --git a/Master/texmf-dist/doc/support/latexindent/subsubsec-headings.tex b/Master/texmf-dist/doc/support/latexindent/subsubsec-headings.tex index a8a344e41c1..088ece973dd 100644 --- a/Master/texmf-dist/doc/support/latexindent/subsubsec-headings.tex +++ b/Master/texmf-dist/doc/support/latexindent/subsubsec-headings.tex @@ -9,35 +9,29 @@ On using the YAML file in \cref{lst:headings3yaml} by running the command \begin{commandshell} latexindent.pl headings2.tex -l headings3.yaml - \end{commandshell} +\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{minipage}{.45\textwidth} + \begin{cmhtcbraster}[raster column skip=.1\linewidth] \cmhlistingsfromfile{demonstrations/headings2-mod3.tex}{\texttt{headings2.tex} using \cref{lst:headings3yaml}}{lst:headings2-mod3} - \end{minipage}% - \hfill - \begin{minipage}{.45\textwidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/headings3.yaml}[yaml-TCB]{\texttt{headings3.yaml}}{lst:headings3yaml} - \end{minipage} + \end{cmhtcbraster} If we specify \texttt{noAdditionalIndent} as in \cref{lst:headings4yaml} and run the command \begin{commandshell} latexindent.pl headings2.tex -l headings4.yaml - \end{commandshell} +\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{minipage}{.45\textwidth} + \begin{cmhtcbraster}[raster column skip=.1\linewidth] \cmhlistingsfromfile{demonstrations/headings2-mod4.tex}{\texttt{headings2.tex} using \cref{lst:headings4yaml}}{lst:headings2-mod4} - \end{minipage}% - \hfill - \begin{minipage}{.45\textwidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/headings4.yaml}[yaml-TCB]{\texttt{headings4.yaml}}{lst:headings4yaml} - \end{minipage} + \end{cmhtcbraster} 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 @@ -45,37 +39,31 @@ latexindent.pl headings2.tex -l headings4.yaml \emph{after the heading} of \texttt{paragraph} have \emph{all} received three tabs worth of indentation. - \begin{minipage}{.55\textwidth} + \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} - \end{minipage}% - \hfill - \begin{minipage}{.42\textwidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/headings5.yaml}[yaml-TCB]{\texttt{headings5.yaml}}{lst:headings5yaml} - \end{minipage} + \end{cmhtcbraster} We may, instead, specify \texttt{noAdditionalIndent} in `field' form, as in \cref{lst:headings6yaml} which gives the output in \cref{lst:headings2-mod6}. - \begin{minipage}{.45\textwidth} + \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/headings2-mod6.tex}{\texttt{headings2.tex} using \cref{lst:headings6yaml}}{lst:headings2-mod6} - \end{minipage}% - \hfill - \begin{minipage}{.45\textwidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/headings6.yaml}[yaml-TCB]{\texttt{headings6.yaml}}{lst:headings6yaml} - \end{minipage} + \end{cmhtcbraster} Analogously, we may specify \texttt{indentRules} as in \cref{lst:headings7yaml} which gives the output in \cref{lst:headings2-mod7}; note that mandatory argument text has only received a single space of indentation, while the body after the heading has received three tabs worth of indentation. - \begin{minipage}{.45\textwidth} + \begin{cmhtcbraster} \cmhlistingsfromfile[showtabs=true]{demonstrations/headings2-mod7.tex}{\texttt{headings2.tex} using \cref{lst:headings7yaml}}{lst:headings2-mod7} - \end{minipage}% - \hfill - \begin{minipage}{.45\textwidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/headings7.yaml}[yaml-TCB]{\texttt{headings7.yaml}}{lst:headings7yaml} - \end{minipage} + \end{cmhtcbraster} 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}. @@ -86,18 +74,12 @@ latexindent.pl headings2.tex -l headings4.yaml (from the global rule specified in \cref{lst:headings9yaml}), and the remaining body after \texttt{paragraph} has received just two spaces of indentation. - \begin{minipage}{.45\textwidth} + \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/headings2-mod8.tex}{\texttt{headings2.tex} using \cref{lst:headings8yaml}}{lst:headings2-mod8} - \end{minipage}% - \hfill - \begin{minipage}{.45\textwidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/headings8.yaml}[yaml-TCB]{\texttt{headings8.yaml}}{lst:headings8yaml} - \end{minipage} + \end{cmhtcbraster} - \begin{minipage}{.45\textwidth} + \begin{cmhtcbraster} \cmhlistingsfromfile[showspaces=true,showtabs=true]{demonstrations/headings2-mod9.tex}{\texttt{headings2.tex} using \cref{lst:headings9yaml}}{lst:headings2-mod9} - \end{minipage}% - \hfill - \begin{minipage}{.45\textwidth} \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/headings9.yaml}[yaml-TCB]{\texttt{headings9.yaml}}{lst:headings9yaml} - \end{minipage} + \end{cmhtcbraster} diff --git a/Master/texmf-dist/doc/support/latexindent/subsubsec-ifelsefi.tex b/Master/texmf-dist/doc/support/latexindent/subsubsec-ifelsefi.tex index 8be17304247..c7171bc7525 100644 --- a/Master/texmf-dist/doc/support/latexindent/subsubsec-ifelsefi.tex +++ b/Master/texmf-dist/doc/support/latexindent/subsubsec-ifelsefi.tex @@ -60,7 +60,7 @@ latexindent.pl ifelsefi1.tex -l ifnum-indent-rules.yaml latexindent.pl ifelsefi1.tex -local ifelsefi-noAdd-glob.yaml latexindent.pl ifelsefi1.tex -l ifelsefi-indent-rules-global.yaml \end{commandshell} - we receive the outputs in \cref{lst:ifelsefi1-output-noAdd-glob,lst:ifelsefi1-output-indent-rules-global}; notice that in \cref{lst:ifelsefi1-output-noAdd-glob} + 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. @@ -73,15 +73,12 @@ latexindent.pl ifelsefi1.tex -l ifelsefi-indent-rules-global.yaml \end{minipage} We can further explore the treatment of \texttt{ifElseFi} code - blocks%%%% + blocks% \announce{2018-04-27}*{updates to ifElseFi code blocks} in \cref{lst:ifelsefi2}, and the associated default output given in \cref{lst:ifelsefi2-default}; note, in particular, that the bodies of each of the `or statements' have been indented. - \begin{minipage}{.45\textwidth} + \begin{cmhtcbraster}[raster column skip=.1\linewidth] \cmhlistingsfromfile{demonstrations/ifelsefi2.tex}{\texttt{ifelsefi2.tex}}{lst:ifelsefi2} - \end{minipage}% - \hfill - \begin{minipage}{.54\textwidth} \cmhlistingsfromfile{demonstrations/ifelsefi2-default.tex}{\texttt{ifelsefi2.tex} default output}{lst:ifelsefi2-default} - \end{minipage} + \end{cmhtcbraster} diff --git a/Master/texmf-dist/doc/support/latexindent/subsubsec-no-add-remaining-code-blocks.tex b/Master/texmf-dist/doc/support/latexindent/subsubsec-no-add-remaining-code-blocks.tex index e9f6c36ebb6..a91b4b0c98f 100644 --- a/Master/texmf-dist/doc/support/latexindent/subsubsec-no-add-remaining-code-blocks.tex +++ b/Master/texmf-dist/doc/support/latexindent/subsubsec-no-add-remaining-code-blocks.tex @@ -9,12 +9,15 @@ \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; + \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} An example is shown in \cref{lst:pgfkeysbefore}, with the default output given in \cref{lst:pgfkeys1:default}. @@ -43,11 +46,15 @@ \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!(!; + \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} + A simple example is given in \cref{lst:child1}, with default output in \cref{lst:child1:default}. @@ -81,6 +88,8 @@ \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} An example is shown in \cref{lst:psforeach1} with default output give in \cref{lst:psforeach:default}. diff --git a/Master/texmf-dist/doc/support/latexindent/subsubsec-special.tex b/Master/texmf-dist/doc/support/latexindent/subsubsec-special.tex index d93f8926e12..378c4d1413b 100644 --- a/Master/texmf-dist/doc/support/latexindent/subsubsec-special.tex +++ b/Master/texmf-dist/doc/support/latexindent/subsubsec-special.tex @@ -50,7 +50,7 @@ latexindent.pl special1.tex -l displayMath-indent-rules.yaml latexindent.pl special1.tex -local special-noAdd-glob.yaml latexindent.pl special1.tex -l special-indent-rules-global.yaml \end{commandshell} - we receive the outputs in \cref{lst:special1-output-noAdd-glob,lst:special1-output-indent-rules-global}; notice that in \cref{lst:special1-output-noAdd-glob} + 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. diff --git a/Master/texmf-dist/doc/support/latexindent/title.tex b/Master/texmf-dist/doc/support/latexindent/title.tex index 22959c788e4..4e0ae04a2b6 100644 --- a/Master/texmf-dist/doc/support/latexindent/title.tex +++ b/Master/texmf-dist/doc/support/latexindent/title.tex @@ -8,7 +8,7 @@ sharp corners, enhanced, overlay={\node[anchor=north east,outer sep=2pt] at ([xshift=3cm,yshift=4mm]frame.north east) {\includegraphics[width=3cm]{logo}}; }] - \centering\ttfamily\bfseries latexindent.pl\\[1cm] Version 3.6 + \centering\ttfamily\bfseries latexindent.pl\\[1cm] Version 3.7 \end{tcolorbox} } \author{Chris Hughes \thanks{and contributors! @@ -21,6 +21,7 @@ \texttt{latexindent.pl} is a \texttt{Perl} script that indents \texttt{.tex} (and other) files according to an indentation scheme that the user can modify to suit their taste. Environments, including those with alignment delimiters (such as \texttt{tabular}), and commands, including those that can split braces and brackets across lines, are \emph{usually} handled correctly by the script. Options for \texttt{verbatim}-like environments and commands, together with indentation after headings (such as \lstinline!chapter!, \lstinline!section!, etc) are also available. - The script also has the ability to modifiy line breaks, and add comment symbols. - All user options are customisable via the switches in the YAML interface; you can find a quick start guide in \vref{sec:quickstart}. + The script also has the ability to modify line breaks, and to add comment symbols and blank lines; furthermore, it permits string or + regex-based substitutions. + All user options are customisable via the switches and the YAML interface; you can find a quick start guide in \vref{sec:quickstart}. \end{adjustwidth} |