diff options
author | Karl Berry <karl@freefriends.org> | 2021-09-16 20:17:39 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2021-09-16 20:17:39 +0000 |
commit | fd4d90b5caf562a8d951bb4a3b78a1aa74930017 (patch) | |
tree | 0149dcc8db072610a3563e4de0d64059b7d3a4e1 /Master/texmf-dist/doc/support/latexindent | |
parent | d1b9b9a5605416852eda15bb968ab490d42b47cf (diff) |
latexindent (16sep21)
git-svn-id: svn://tug.org/texlive/trunk@60522 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/support/latexindent')
15 files changed, 389 insertions, 65 deletions
diff --git a/Master/texmf-dist/doc/support/latexindent/README b/Master/texmf-dist/doc/support/latexindent/README index 04fd1c5b5fc..85200ba048b 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.11, 2021-07-31 + latexindent.pl, version 3.12, 2021-09-16 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 bbeefb5fd13..617abe1bdc4 100644 --- a/Master/texmf-dist/doc/support/latexindent/appendices.tex +++ b/Master/texmf-dist/doc/support/latexindent/appendices.tex @@ -46,14 +46,15 @@ perl latexindent-module-installer.pl then, once you have answered \texttt{Y}, the appropriate modules will be installed onto your distribution. - \subsection{Manually installed modules}\label{sec:manual-module-instal} + \subsection{Manually installing modules}\label{sec:manual-module-instal} Manually installing the modules given in \cref{lst:helloworld} will vary depending on your operating system and \texttt{Perl} distribution. \subsubsection{Linux} - Linux users may be interested in exploring Perlbrew \cite{perlbrew}; an example - installation would be: - \begin{commandshell} + \paragraph{perlbrew} + Linux users may be interested in exploring Perlbrew \cite{perlbrew}; an example + installation would be: + \begin{commandshell} sudo apt-get install perlbrew perlbrew init perlbrew install perl-5.28.1 @@ -65,25 +66,38 @@ cpanm File::HomeDir cpanm Unicode::GCString \end{commandshell} - For other distributions, the Ubuntu/Debian approach may work as follows - \begin{commandshell} + \paragraph{Ubuntu/Debian} + For other distributions, the Ubuntu/Debian approach may work as follows + \begin{commandshell} sudo apt install perl sudo cpan -i App::cpanminus sudo cpanm YAML::Tiny sudo cpanm File::HomeDir sudo cpanm Unicode::GCString \end{commandshell} - or else by running, for example, - \begin{commandshell} + or else by running, for example, + \begin{commandshell} sudo perl -MCPAN -e'install "File::HomeDir"' \end{commandshell} - If you are using Alpine, some \texttt{Perl} modules are not build-compatible with Alpine, - but replacements are available through \texttt{apk}. For example, you might use the - commands given in \cref{lst:alpine-install}; thanks to \cite{jun-sheaf} for providing - these details. + \paragraph{Ubuntu: using the texlive from apt-get} + Ubuntu users that install texlive using \texttt{apt-get} as in the following + \begin{commandshell} +sudo apt install texlive +sudo apt install texlive-latex-recommended +\end{commandshell} + may need the following additional command to work with \texttt{latexindent.pl} + \begin{commandshell} +sudo apt install texlive-extra-utils +\end{commandshell} + + \paragraph{Alpine} + If you are using Alpine, some \texttt{Perl} modules are not build-compatible with Alpine, + but replacements are available through \texttt{apk}. For example, you might use the + commands given in \cref{lst:alpine-install}; thanks to \cite{jun-sheaf} for providing + these details. - \begin{cmhlistings}[style=tcblatex,language=Bash]{\texttt{alpine-install.sh}}{lst:alpine-install} + \begin{cmhlistings}[style=tcblatex,language=Bash]{\texttt{alpine-install.sh}}{lst:alpine-install} # Installing perl apk --no-cache add miniperl perl-utils @@ -107,9 +121,9 @@ cpanm -n YAML::Tiny cpanm -n Unicode::GCString \end{cmhlistings} - Users of NixOS might like to see - \href{https://github.com/cmhughes/latexindent.pl/issues/222}{https://github.com/cmhughes/latexindent.pl/issues/222} - for tips. + Users of NixOS might like to see + \href{https://github.com/cmhughes/latexindent.pl/issues/222}{https://github.com/cmhughes/latexindent.pl/issues/222} + for tips. \subsubsection{Mac} Users of the Macintosh operating system might like to explore the following commands, for example: diff --git a/Master/texmf-dist/doc/support/latexindent/cmhlistings.tex b/Master/texmf-dist/doc/support/latexindent/cmhlistings.tex index 1f058616d6d..6b8506c3447 100644 --- a/Master/texmf-dist/doc/support/latexindent/cmhlistings.tex +++ b/Master/texmf-dist/doc/support/latexindent/cmhlistings.tex @@ -4,6 +4,13 @@ ^^I:caption: #2^^J ^^I:name: #3^^J } +\newcommand{\cmhlistingsfromfilelines}[4]{ +.. literalinclude:: #1^^J +^^I:class: .#4^^J +^^I:caption: #2^^J +^^I:name: #3^^J +^^I:linenos:^^J +} \newcommand{\cmhlistingsfromfilefour}[6]{ .. literalinclude:: #3^^J ^^I:class: .#6^^J @@ -14,7 +21,7 @@ ^^I:lineno-start: #1^^J } \newcommand{\cmhlabel}[1]{ -.. _#1:^^J +.. \_#1:^^J } \newcommand{\warning}[1]{ .. warning::^^J diff --git a/Master/texmf-dist/doc/support/latexindent/latexindent.pdf b/Master/texmf-dist/doc/support/latexindent/latexindent.pdf Binary files differindex dfb37e0b765..12ad2f551c1 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 9379dddcb06..a97d778742c 100644 --- a/Master/texmf-dist/doc/support/latexindent/latexindent.tex +++ b/Master/texmf-dist/doc/support/latexindent/latexindent.tex @@ -27,7 +27,6 @@ \usepackage{multicol} \usepackage{changepage} % adjust width of page \usepackage{fancyhdr} % headers & footers -\usepackage{wrapfig} \usepackage{fontawesome} \usepackage[sc,format=hang,font=small]{caption} % captions \usepackage[backend=bibtex]{biblatex} % bibliography @@ -42,7 +41,7 @@ \usepackage{totalcount} \usepackage{standalone} % setup gitinfo2, as in the manual, details just above begin{document} -\usepackage[mark,grumpy]{gitinfo2} +\usepackage[mark]{gitinfo2} % tikz, tcolorbox libraries \usetikzlibrary{positioning} \usetikzlibrary{decorations.pathmorphing} @@ -163,6 +162,21 @@ sharp corners, colbacktitle=white!75!black }, + tex-TCB/.style={ + listing only, + listing engine=listings, + left=0cm, + boxrule=0pt, + sharp corners, + center title, + colframe=white!40!black, + colback=white, + sharp corners, + colbacktitle=white!75!black, + toprule=1pt, + bottomrule=1pt, + titlerule=1pt, + }, yaml-TCB/.style={ listing only, listing engine=listings, @@ -326,6 +340,11 @@ columns=fullflexible, } +\lstdefinestyle{lineNumbersTeX}{ + numbers=left, + numberstyle=\color{blue}, +} + \lstdefinestyle{fileExtensionPreference}{ style=yaml-LST, firstnumber=44,linerange={44-48}, @@ -767,9 +786,14 @@ {}% <numberless-entry-format> {\titlerule*[0.5em]{$\cdot$}\contentspage} +% to explore in the future: +% partial toc customisation +% https://tex.stackexchange.com/questions/66345/how-to-remove-section-indentation-in-partial-toc-using-titletoc + \setcounter{secnumdepth}{6} \setcounter{tocdepth}{4} \makeindex + \begin{document} \renewcommand*{\thefootnote}{\arabic{footnote}} \input{title.tex} @@ -801,6 +825,7 @@ \input{subsec-poly-switches} \stopcontents[the-m-switch] \input{sec-replacements} + \input{sec-the-line-switch} \input{sec-fine-tuning} \input{sec-conclusions-know-limitations} \input{references} 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 85738608b9f..b649f54f9cc 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 @@ -375,7 +375,7 @@ lookForAlignDelims: 0); \item \announce{2020-03-21}{delimiter RegEx feature}{delimiterRegEx} optionally specifies the pattern matching to be used for the alignment delimeter (default: - \lstinline3 '(?<!\\)(&)'3); + \lstinline* '(?<!\\)(&)'*); \item \announce{2020-03-21}{delimiter justification}{delimiterJustification} optionally specifies the justification for the alignment delimeters (default: left); note that this feature is only useful if you have delimiters of different lengths in the same column, @@ -749,7 +749,7 @@ latexindent.pl tabular-DM.tex -l=dontMeasure6.yaml \announce{2020-03-21}{delimiterRegEx feature} will, by default, align code blocks at the ampersand character. The behaviour is controlled by the \texttt{delimiterRegEx} field within \texttt{lookForAlignDelims}; the default value is - \lstinline3'(?<!\\)(&)'3, which can be read as: \emph{an ampersand, as long as it is not + \lstinline*'(?<!\\)(&)'*, which can be read as: \emph{an ampersand, as long as it is not immediately preceeded by a backslash}. \index{warning!capturing parenthesis for lookForAlignDelims} \index{capturing parenthesis (regex)} @@ -1098,7 +1098,7 @@ latexindent.pl special-align.tex -l edge-node2.yaml -o=+-mod2 \texttt{indentRules} (see \vref{sec:noadd-indent-rules}); you will find the default \texttt{indentRules} contains \lstinline!chapter: " "! which tells \texttt{latexindent.pl} simply to use a space - character after \texttt{\chapter} headings (once \texttt{indent} is set to \texttt{1} for + character after \texttt{chapter} headings (once \texttt{indent} is set to \texttt{1} for \texttt{chapter}). For example, assuming that you have the code in \cref{lst:headings1yaml} saved into @@ -1185,10 +1185,11 @@ latexindent.pl mult-nested.tex -l=max-indentation1 \begin{table}[!htp] \begin{widepage} \centering - \caption{Code blocks known to \texttt{latexindent.pl}}\label{tab:code-blocks} + \caption{Code blocks known to \texttt{latexindent.pl}} + \label{tab:code-blocks} \begin{tabular}{m{.3\linewidth}@{\hspace{.25cm}}m{.4\linewidth}@{\hspace{.25cm}}m{.2\linewidth}} \toprule - Code block & characters allowed in name & example \\ + Code block & characters allowed in name & example \\ \midrule environments & \lstinline!a-zA-Z@\*0-9_\\! & \begin{lstlisting}[,nolol=true,] @@ -1211,10 +1212,10 @@ mand arg text } \end{lstlisting} \\\cmidrule{2-3} - commands & \lstinline!+a-zA-Z@\*0-9_\:! & \lstinline!\mycommand!$\langle$\itshape{arguments}$\rangle$ \\\cmidrule{2-3} - keyEqualsValuesBracesBrackets & \lstinline!a-zA-Z@\*0-9_\/.\h\{\}:\#-! & \lstinline!my key/.style=!$\langle$\itshape{arguments}$\rangle$ \\\cmidrule{2-3} - namedGroupingBracesBrackets & \lstinline!0-9\.a-zA-Z@\*><! & \lstinline!in!$\langle$\itshape{arguments}$\rangle$ \\\cmidrule{2-3} - UnNamedGroupingBracesBrackets & \centering\emph{No name!} & \lstinline!{! or \lstinline![! or \lstinline!,! or \lstinline!&! or \lstinline!)! or \lstinline!(! or \lstinline!$! followed by $\langle$\itshape{arguments}$\rangle$ \\\cmidrule{2-3} + commands & \lstinline!+a-zA-Z@\*0-9_\:! & \lstinline!\mycommand!$\langle$\itshape{arguments}$\rangle$ \\\cmidrule{2-3} + keyEqualsValuesBracesBrackets & \lstinline!a-zA-Z@\*0-9_\/.\h\{\}:\#-! & \lstinline!my key/.style=!$\langle$\itshape{arguments}$\rangle$ \\\cmidrule{2-3} + namedGroupingBracesBrackets & \lstinline!0-9\.a-zA-Z@\*><! & \lstinline!in!$\langle$\itshape{arguments}$\rangle$ \\\cmidrule{2-3} + UnNamedGroupingBracesBrackets & \centering\emph{No name!} & \lstinline!{! or \lstinline![! or \lstinline!,! or \lstinline!\&! or \lstinline!)! or \lstinline!(! or \lstinline!$! followed by $\langle$\itshape{arguments}$\rangle$ \\\cmidrule{2-3} ifElseFi & \lstinline!@a-zA-Z! but must begin with either \newline \lstinline!\if! of \lstinline!\@if! & \begin{lstlisting}[,nolol=true,] \ifnum... @@ -1222,31 +1223,31 @@ mand arg text \else ... \fi - \end{lstlisting} \\\cmidrule{2-3} + \end{lstlisting} \\\cmidrule{2-3} items & User specified, see \vref{lst:indentafteritems,lst:itemNames} & \begin{lstlisting}[,nolol=true,] \begin{enumerate} \item ... \end{enumerate} - \end{lstlisting} \\\cmidrule{2-3} + \end{lstlisting} \\\cmidrule{2-3} specialBeginEnd & User specified, see \vref{lst:specialBeginEnd} & \begin{lstlisting}[,nolol=true,] \[ ... \] - \end{lstlisting} \\\cmidrule{2-3} + \end{lstlisting} \\\cmidrule{2-3} afterHeading & User specified, see \vref{lst:indentAfterHeadings} & \begin{lstlisting}[,morekeywords={chapter},nolol=true,] \chapter{title} ... \section{title} - \end{lstlisting} \\\cmidrule{2-3} + \end{lstlisting} \\\cmidrule{2-3} filecontents & User specified, see \vref{lst:fileContentsEnvironments} & \begin{lstlisting}[,nolol=true,] \begin{filecontents} ... \end{filecontents} - \end{lstlisting} \\ + \end{lstlisting} \\ \bottomrule \end{tabular} \end{widepage} 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 42553e037a4..c2974189284 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 @@ -415,7 +415,84 @@ latexindent.pl -onlyreplacement myfile.tex and \emph{only} perform replacements/substitutions by using the \texttt{-rr} switch; full details and examples are given in \vref{sec:replacements}. +\flagbox{-k, --check} + \index{switches!-k, --check definition and details} + \begin{commandshell} +latexindent.pl -k myfile.tex +latexindent.pl -check myfile.tex +\end{commandshell} + You can% + \announce*{2021-09-16}{-k,-check switch} instruct + \texttt{latexindent.pl} to check if the text after indentation matches that given in the + original file. + + The \texttt{exit} code + \index{exit code} of \texttt{latexindent.pl} is 0 by default. If + you use the \texttt{-k} switch then + \begin{itemize} + \item if the text after indentation matches that given in the original file, then the exit code + is 0; + \item if the text after indentation does \emph{not} match that given in the original file, then + the exit code is 1. + \end{itemize} + + The value of the exit code may be important to those wishing to, for example, check the + status of the indentation in continuous integration tools such as GitHub Actions. Full + details of the exit codes of \texttt{latexindent.pl} are given in \cref{tab:exit-codes}. + + A simple \texttt{diff} will be given in \texttt{indent.log}. + +\flagbox{-kv, --checkv} + \index{switches!-kv, --checkv definition and details} + \begin{commandshell} +latexindent.pl -kv myfile.tex +latexindent.pl -checkv myfile.tex +\end{commandshell} + \announce*{2021-09-16}{-kv, -checkv: check verbose switch} The \texttt{check verbose} switch is + exactly the same as the \texttt{-k} switch, except that it is \emph{verbose}, and it will + output the (simple) diff to the terminal, as well as to \texttt{indent.log}. + +\flagbox{-n, --lines=MIN-MAX} + \index{switches!-n, --lines definition and details} + \begin{commandshell} +latexindent.pl -n 5-8 myfile.tex +latexindent.pl -lines 5-8 myfile.tex +\end{commandshell} + \announce*{2021-09-16}{-n, -lines switch} The \texttt{lines} switch instructs + \texttt{latexindent.pl} to operate only on specific line ranges within + \texttt{myfile.tex}. + + Complete demonstrations are given in \cref{sec:line-switch}. + \subsection{From arara}\label{sec:arara} Using \texttt{latexindent.pl} from the command line is fine for some folks, but others may find it easier to use from \texttt{arara}; you can find the arara rule for \texttt{latexindent.pl} and its associated documentation at \cite{paulo}. + +\subsection{Summary of exit codes} + \index{exit code!summary} + Assuming that you call \texttt{latexindent.pl} on \texttt{myfile.tex} + \begin{commandshell} +latexindent.pl myfile.tex +\end{commandshell} + then \texttt{latexindent.pl} can exit with the exit codes given in \cref{tab:exit-codes}. + + \begin{table}[!htb] + \caption{Exit codes for \texttt{latexindent.pl}} + \label{tab:exit-codes} + \begin{tabular}{ccl} + \toprule + exit code & indentation & status \\ + \midrule + 0 & \faCheck & success; if \texttt{-k} or \texttt{-kv} active, indented text matches original \\ + 0 & \faClose & success; if \texttt{-version} or \texttt{-help}, no indentation performed \\ + 1 & \faCheck & success, and \texttt{-k} or \texttt{-kv} active; indented text \emph{different} from original \\ + \midrule + 2 & \faClose & failure, \texttt{defaultSettings.yaml} could not be read \\ + 3 & \faClose & failure, myfile.tex not found \\ + 4 & \faClose & failure, myfile.tex exists but cannot be read \\ + 5 & \faClose & failure, \texttt{-w} active, and back-up file cannot be written \\ + 6 & \faClose & failure, \texttt{-c} active, and cruft directory does not exist \\ + \bottomrule + \end{tabular} + \end{table} diff --git a/Master/texmf-dist/doc/support/latexindent/sec-the-line-switch.tex b/Master/texmf-dist/doc/support/latexindent/sec-the-line-switch.tex new file mode 100644 index 00000000000..0c06daec2d0 --- /dev/null +++ b/Master/texmf-dist/doc/support/latexindent/sec-the-line-switch.tex @@ -0,0 +1,187 @@ +% arara: pdflatex: {shell: yes, files: [latexindent]} +\section{The --lines switch}\label{sec:line-switch} + \texttt{latexindent.pl} + \announce*{2021-09-16}{line switch demonstration} can + operate on a \emph{selection} of lines of the file using the \texttt{--lines} or + \texttt{-n} switch. + + \index{switches!-lines demonstration} + + The basic syntax is \texttt{--lines MIN-MAX}, so for example + \begin{commandshell} +latexindent.pl --lines 3-7 myfile.tex +latexindent.pl -n 3-7 myfile.tex +\end{commandshell} + will only operate upon lines 3 to 7 in \texttt{myfile.tex}. All of the other lines will + \emph{not} be operated upon by \texttt{latexindent.pl}. + + The options for the \texttt{lines} switch are: + \begin{itemize} + \item line range, as in \texttt{--lines 3-7} + \item single line, as in \texttt{--lines 5} + \item multiple line ranges separated by commas, as in \texttt{--lines 3-5,8-10} + \item negated line ranges, as in \texttt{--lines !3-5} which translates to \texttt{--lines + 1-2,6-N}, where N is the number of lines in your file. + \end{itemize} + + We demonstrate this feature, and the available variations in what follows. We will use + the file in \cref{lst:myfile}. + + \cmhlistingsfromfile*[style=lineNumbersTeX]*{demonstrations/myfile.tex}[tex-TCB]{\texttt{myfile.tex}}{lst:myfile} + + \begin{example} + We demonstrate the basic usage using the command + \begin{commandshell} +latexindent.pl --lines 3-7 myfile.tex -o=+-mod1 +\end{commandshell} + which instructs \texttt{latexindent.pl} to only operate on lines 3 to 7; the output is given in \cref{lst:myfile-mod1}. + + \cmhlistingsfromfile*[style=lineNumbersTeX]*{demonstrations/myfile-mod1.tex}[tex-TCB]{\texttt{myfile-mod1.tex}}{lst:myfile-mod1} + + The following two calls to \texttt{latexindent.pl} are equivalent + \begin{commandshell} +latexindent.pl --lines 3-7 myfile.tex -o=+-mod1 +latexindent.pl --lines 7-3 myfile.tex -o=+-mod1 +\end{commandshell} + as \texttt{latexindent.pl} performs a check to put the lowest number first. + \end{example} + + \begin{example} + You can call the \texttt{lines} switch with only \emph{one number} and + in which case only that line will be operated upon. For example + \begin{commandshell} +latexindent.pl --lines 5 myfile.tex -o=+-mod2 +\end{commandshell} + instructs \texttt{latexindent.pl} to only operate on line 5; the output is given in \cref{lst:myfile-mod2}. + + \cmhlistingsfromfile*[style=lineNumbersTeX]*{demonstrations/myfile-mod2.tex}[tex-TCB]{\texttt{myfile-mod2.tex}}{lst:myfile-mod2} + + The following two calls are equivalent: + \begin{commandshell} +latexindent.pl --lines 5 myfile.tex +latexindent.pl --lines 5-5 myfile.tex +\end{commandshell} + \end{example} + + \begin{example} + If you specify a value outside of the line range of the file then \texttt{latexindent.pl} will ignore the + \texttt{lines} argument, detail as such in the log file, and proceed to operate on the entire file. + + For example, in the following call + \begin{commandshell} +latexindent.pl --lines 11-13 myfile.tex + \end{commandshell} + \texttt{latexindent.pl} will ignore the \texttt{lines} argument, and \emph{operate on the entire file} because \cref{lst:myfile} only has 12 lines. + + Similarly, in the call + \begin{commandshell} +latexindent.pl --lines -1-3 myfile.tex + \end{commandshell} + \texttt{latexindent.pl} will ignore the \texttt{lines} argument, and \emph{operate on the entire file} because we assume that negatively numbered + lines in a file do not exist. + \end{example} + + \begin{example} + You can specify \emph{multiple line ranges} as in the following + \begin{commandshell} +latexindent.pl --lines 3-5,8-10 myfile.tex -o=+-mod3 +\end{commandshell} + which instructs \texttt{latexindent.pl} to operate upon lines 3 to 5 and lines 8 to 10; the output is given in \cref{lst:myfile-mod3}. + + \cmhlistingsfromfile*[style=lineNumbersTeX]*{demonstrations/myfile-mod3.tex}[tex-TCB]{\texttt{myfile-mod3.tex}}{lst:myfile-mod3} + + The following calls to \texttt{latexindent.pl} are all equivalent + \begin{commandshell} +latexindent.pl --lines 3-5,8-10 myfile.tex +latexindent.pl --lines 8-10,3-5 myfile.tex +latexindent.pl --lines 10-8,3-5 myfile.tex +latexindent.pl --lines 10-8,5-3 myfile.tex +\end{commandshell} + as \texttt{latexindent.pl} performs a check to put the lowest line ranges first, and within each line range, it puts + the lowest number first. + \end{example} + + \begin{example} + There's no limit to the number of line ranges that you can specify, they just need to be separated by commas. For example + \begin{commandshell} +latexindent.pl --lines 1-2,4-5,9-10,12 myfile.tex -o=+-mod4 +\end{commandshell} + has four line ranges: lines 1 to 2, lines 4 to 5, lines 9 to 10 and line 12. The output is given in \cref{lst:myfile-mod4}. + + \cmhlistingsfromfile*[style=lineNumbersTeX]*{demonstrations/myfile-mod4.tex}[tex-TCB]{\texttt{myfile-mod4.tex}}{lst:myfile-mod4} + + As previously, the ordering does not matter, and the following calls to \texttt{latexindent.pl} are all equivalent + \begin{commandshell} +latexindent.pl --lines 1-2,4-5,9-10,12 myfile.tex +latexindent.pl --lines 2-1,4-5,9-10,12 myfile.tex +latexindent.pl --lines 4-5,1-2,9-10,12 myfile.tex +latexindent.pl --lines 12,4-5,1-2,9-10 myfile.tex +\end{commandshell} + as \texttt{latexindent.pl} performs a check to put the lowest line ranges first, and within each line range, it puts + the lowest number first. + \end{example} + + \begin{example} + \index{switches!-lines demonstration, negation} + You can specify \emph{negated line ranges} by using \texttt{!} as in + \begin{commandshell} +latexindent.pl --lines !5-7 myfile.tex -o=+-mod5 +\end{commandshell} + which instructs \texttt{latexindent.pl} to operate upon all of the lines \emph{except} lines 5 to 7. + + In other words, \texttt{latexindent.pl} \emph{will} operate on lines 1 to 4, and 8 to 12, so the following + two calls are equivalent: + \begin{commandshell} +latexindent.pl --lines !5-7 myfile.tex +latexindent.pl --lines 1-4,8-12 myfile.tex +\end{commandshell} + The output is given in \cref{lst:myfile-mod5}. + + \cmhlistingsfromfile*[style=lineNumbersTeX]*{demonstrations/myfile-mod5.tex}[tex-TCB]{\texttt{myfile-mod5.tex}}{lst:myfile-mod5} + + \end{example} + + \begin{example} + \index{switches!-lines demonstration, negation} + You can specify \emph{multiple negated line ranges} such as + \begin{commandshell} +latexindent.pl --lines !5-7,!9-10 myfile.tex -o=+-mod6 + \end{commandshell} + which is equivalent to: + \begin{commandshell} +latexindent.pl --lines 1-4,8,11-12 myfile.tex -o=+-mod6 + \end{commandshell} + The output is given in \cref{lst:myfile-mod6}. + + \cmhlistingsfromfile*[style=lineNumbersTeX]*{demonstrations/myfile-mod6.tex}[tex-TCB]{\texttt{myfile-mod6.tex}}{lst:myfile-mod6} + \end{example} + + \begin{example} + If you specify a line range with anything other than an integer, then + \texttt{latexindent.pl} will ignore the \texttt{lines} argument, and \emph{operate on the entire file}. + + Sample calls that result in the \texttt{lines} argument being ignored include the following: + \begin{commandshell} +latexindent.pl --lines 1-x myfile.tex +latexindent.pl --lines !y-3 myfile.tex + \end{commandshell} + \end{example} + + \begin{example} + We can, of course, use the \texttt{lines} switch in combination with other switches. + + For example, let's use with the file in \cref{lst:myfile1}. + + \cmhlistingsfromfile*[style=lineNumbersTeX]*{demonstrations/myfile1.tex}[tex-TCB]{\texttt{myfile1.tex}}{lst:myfile1} + + We can demonstrate interaction with the \texttt{-m} switch (see \vref{sec:modifylinebreaks}); in particular, + if we use \vref{lst:mlb2}, \vref{lst:env-mlb7} and \vref{lst:env-mlb8} and run + \begin{widepage} + \begin{commandshell} +latexindent.pl --lines 6 myfile1.tex -o=+-mod1 -m -l env-mlb2,env-mlb7,env-mlb8 -o=+-mod1 + \end{commandshell} + \end{widepage} + then we receive the output in \cref{lst:myfile1-mod1}. + + \cmhlistingsfromfile*[style=lineNumbersTeX]*{demonstrations/myfile1-mod1.tex}[tex-TCB]{\texttt{myfile1-mod1.tex}}{lst:myfile1-mod1} + \end{example} 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 8a824987f6f..1388a84932c 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 @@ -12,9 +12,6 @@ \printcontents[the-m-switch]{}{0}{} \yamltitle{modifylinebreaks}*{fields} - \begin{wrapfigure}[7]{r}[0pt]{8cm} - \cmhlistingsfromfile[style=modifylinebreaks]*{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{modifyLineBreaks}}{lst:modifylinebreaks} - \end{wrapfigure} \makebox[0pt][r]{% \raisebox{-\totalheight}[0pt][0pt]{% \tikz\node[opacity=1] at (0,0) @@ -25,6 +22,8 @@ if the \texttt{-m} switch has been used}. A snippet of the default settings of this field is shown in \cref{lst:modifylinebreaks}. + \cmhlistingsfromfile[style=modifylinebreaks]*{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{modifyLineBreaks}}{lst:modifylinebreaks} + Having read the previous paragraph, it should sound reasonable that, if you call \texttt{latexindent.pl} using the \texttt{-m} switch, then you give it permission to modify line breaks in your file, but let's be clear: diff --git a/Master/texmf-dist/doc/support/latexindent/subsec-combine-text-wrap-para-line-breaks.tex b/Master/texmf-dist/doc/support/latexindent/subsec-combine-text-wrap-para-line-breaks.tex index 2c05d60dda6..80ec2b42e1e 100644 --- a/Master/texmf-dist/doc/support/latexindent/subsec-combine-text-wrap-para-line-breaks.tex +++ b/Master/texmf-dist/doc/support/latexindent/subsec-combine-text-wrap-para-line-breaks.tex @@ -42,12 +42,12 @@ latexindent.pl -m textwrap7.tex -l=textwrap12.yaml -o=+-mod12 \index{text wrap!recommended starting point} I% - \announce*{2021-07-31}{textWrapOptions new feature: beforeFindingChildCodeBlocks} think it likely that most users will wish to employ the + \announce{2021-07-31}{textWrapOptions new feature: beforeFindingChildCodeBlocks} think it likely that most users will wish to employ the \texttt{beforeFindingChildCodeBlocks} option for the text wrap routine. To motivate its use, we begin with the file in \cref{lst:textwrap-bfccb}. - \cmhlistingsfromfile*{demonstrations/textwrap-bfccb.tex}{\texttt{textwrap-bfccb.tex}}{lst:textwrap-bfccb} + \cmhlistingsfromfile{demonstrations/textwrap-bfccb.tex}{\texttt{textwrap-bfccb.tex}}{lst:textwrap-bfccb} Using the settings in \cref{lst:textwrap12-yaml} and running \begin{commandshell} @@ -55,7 +55,7 @@ latexindent.pl -m textwrap-bfccb.tex -l=textwrap12.yaml -o=+-mod12 \end{commandshell} gives the output in \cref{lst:textwrap-bfccb-mod12} - \cmhlistingsfromfile*{demonstrations/textwrap-bfccb-mod12.tex}{\texttt{textwrap-bfccb-mod12.tex}}{lst:textwrap-bfccb-mod12} + \cmhlistingsfromfile{demonstrations/textwrap-bfccb-mod12.tex}{\texttt{textwrap-bfccb-mod12.tex}}{lst:textwrap-bfccb-mod12} Note that we have added a `ruler' to \cref{lst:textwrap-bfccb-mod12} to assist with measuring. @@ -83,9 +83,9 @@ latexindent.pl -m textwrap-bfccb.tex -l=textwrap13.yaml -o=+-mod13 \end{commandshell} we receive the output in \cref{lst:textwrap-bfccb-mod13}. - \cmhlistingsfromfile*{demonstrations/textwrap13.yaml}[MLB-TCB,width=\linewidth]{\texttt{textwrap13.yaml} (tweaked quick start)}{lst:textwrap13-yaml} + \cmhlistingsfromfile{demonstrations/textwrap13.yaml}[MLB-TCB,width=\linewidth]{\texttt{textwrap13.yaml} (tweaked quick start)}{lst:textwrap13-yaml} - \cmhlistingsfromfile*{demonstrations/textwrap-bfccb-mod13.tex}{\texttt{textwrap-bfccb-mod13.tex}}{lst:textwrap-bfccb-mod13} + \cmhlistingsfromfile{demonstrations/textwrap-bfccb-mod13.tex}{\texttt{textwrap-bfccb-mod13.tex}}{lst:textwrap-bfccb-mod13} This output is different from \cref{lst:textwrap-bfccb-mod12}, but is still not ideal, as the \texttt{test} command has indented its mandatory argument. We can employ @@ -98,8 +98,8 @@ latexindent.pl -m textwrap-bfccb.tex -l=textwrap14.yaml -o=+-mod14 \begin{widepage} \begin{cmhtcbraster} - \cmhlistingsfromfile*{demonstrations/textwrap-bfccb-mod14.tex}{\texttt{textwrap-bfccb-mod14.tex}}{lst:textwrap-bfccb-mod14} - \cmhlistingsfromfile*{demonstrations/textwrap14.yaml}[MLB-TCB]{\texttt{textwrap14.yaml}}{lst:textwrap14-yaml} + \cmhlistingsfromfile{demonstrations/textwrap-bfccb-mod14.tex}{\texttt{textwrap-bfccb-mod14.tex}}{lst:textwrap-bfccb-mod14} + \cmhlistingsfromfile{demonstrations/textwrap14.yaml}[MLB-TCB]{\texttt{textwrap14.yaml}}{lst:textwrap14-yaml} \end{cmhtcbraster} \end{widepage} @@ -109,4 +109,4 @@ latexindent.pl -m textwrap-bfccb.tex -l=textwrap14.yaml -o=+-mod14 output in \cref{lst:textwrap-bfccb-mod14}, then we would need to employ an exception, which we demonstrate in \cref{lst:textwrap15-yaml}. - \cmhlistingsfromfile*{demonstrations/textwrap15.yaml}[MLB-TCB]{\texttt{textwrap15.yaml}}{lst:textwrap15-yaml} + \cmhlistingsfromfile{demonstrations/textwrap15.yaml}[MLB-TCB]{\texttt{textwrap15.yaml}}{lst:textwrap15-yaml} diff --git a/Master/texmf-dist/doc/support/latexindent/subsec-remove-para-line-breaks.tex b/Master/texmf-dist/doc/support/latexindent/subsec-remove-para-line-breaks.tex index f5531cbba48..2b9de853b14 100644 --- a/Master/texmf-dist/doc/support/latexindent/subsec-remove-para-line-breaks.tex +++ b/Master/texmf-dist/doc/support/latexindent/subsec-remove-para-line-breaks.tex @@ -127,11 +127,18 @@ latexindent.pl -m shortlines-envs.tex -o shortlines-envs3.tex -l remove-para3.ya \texttt{namedGroupingBracesBrackets}, \texttt{UnNamedGroupingBracesBrackets} are controlled by the \texttt{optionalArguments} and the \texttt{mandatoryArguments}. - The only special case is the \texttt{masterDocument} field; this is designed for + The only special case is the \texttt{mainDocument} field; this is designed for `chapter'-type files that may contain paragraphs that are not within any other code-blocks. For example, consider the file in \cref{lst:shortlines-md}, with the YAML settings in \cref{lst:remove-para4-yaml}. + Note: + \announce*{2021-09-16}*{removeParagraphLineBreaks: masterDocument now mainDocument} + \texttt{mainDocument} replaces \texttt{masterDocument} which was used in previous verions + of \texttt{latexindent.pl}. The field \texttt{masterDocument} is still supported, but it + is anticipated to be removed in a future version, so I recommend using + \texttt{mainDocument} instead. + \begin{cmhtcbraster} \cmhlistingsfromfile{demonstrations/shortlines-md.tex}{\texttt{shortlines-md.tex}}{lst:shortlines-md} \cmhlistingsfromfile{demonstrations/remove-para4.yaml}[MLB-TCB]{\texttt{remove-para4.yaml}}{lst:remove-para4-yaml} diff --git a/Master/texmf-dist/doc/support/latexindent/subsec-text-wrap-summary.tex b/Master/texmf-dist/doc/support/latexindent/subsec-text-wrap-summary.tex index 89379eabbc2..b6066e2cc91 100644 --- a/Master/texmf-dist/doc/support/latexindent/subsec-text-wrap-summary.tex +++ b/Master/texmf-dist/doc/support/latexindent/subsec-text-wrap-summary.tex @@ -1,7 +1,7 @@ % arara: pdflatex: {shell: yes, files: [latexindent]} \subsection{Summary of text wrapping} I consider% - \announce*{2021-07-31}{text wrap quick start} + \announce{2021-07-31}{text wrap quick start} the most useful starting point for text wrapping to be given in \cref{subsec:textwrapping-quick-start} and \cref{subsubsec:text-wrap-remove-para-bfccb}. diff --git a/Master/texmf-dist/doc/support/latexindent/subsec-text-wrap.tex b/Master/texmf-dist/doc/support/latexindent/subsec-text-wrap.tex index 2e721cae1a5..781aeccf73c 100644 --- a/Master/texmf-dist/doc/support/latexindent/subsec-text-wrap.tex +++ b/Master/texmf-dist/doc/support/latexindent/subsec-text-wrap.tex @@ -10,7 +10,7 @@ Of all the available text wrapping options, I consider \cref{lst:textwrap-qs-yaml} to be among the most helpful starting points. - \cmhlistingsfromfile*{demonstrations/textwrap-qs.yaml}[MLB-TCB,width=1\linewidth]{\texttt{textwrap-qs.yaml}}{lst:textwrap-qs-yaml} + \cmhlistingsfromfile{demonstrations/textwrap-qs.yaml}[MLB-TCB,width=1\linewidth]{\texttt{textwrap-qs.yaml}}{lst:textwrap-qs-yaml} \index{text wrap!quick start} @@ -182,15 +182,22 @@ latexindent.pl -m textwrap-ts.tex -o=+-mod1 -l tabstop.yaml The code blocks detailed in \cref{lst:textWrapOptionsAll} are with direct reference to those detailed in \vref{tab:code-blocks}. - The only special case is the \texttt{masterDocument} field; this is designed for + The only special case is the \texttt{mainDocument} field; this is designed for `chapter'-type files that may contain paragraphs that are not within any other code-blocks. The same notation is used between this feature and the \texttt{removeParagraphLineBreaks} described in \vref{lst:removeParagraphLineBreaks}; in fact, the two features can even be combined (this is detailed in \vref{subsec:removeparagraphlinebreaks:and:textwrap}). + Note: + \announce*{2021-09-16}*{textWrapOptions: masterDocument now mainDocument} + \texttt{mainDocument} replaces \texttt{masterDocument} which was used in previous verions + of \texttt{latexindent.pl}. The field \texttt{masterDocument} is still supported, but it + is anticipated to be removed in a future version, so I recommend using + \texttt{mainDocument} instead. + Let's explore these switches with reference to the code given in \cref{lst:textwrap5}; - the text outside of the environment is considered part of the \texttt{masterDocument}. + the text outside of the environment is considered part of the \texttt{mainDocument}. \begin{widepage} \cmhlistingsfromfile{demonstrations/textwrap5.tex}{\texttt{textwrap5.tex}}{lst:textwrap5} @@ -221,8 +228,8 @@ latexindent.pl -m textwrap-ts.tex -o=+-mod1 -l tabstop.yaml will operate upon \emph{all} code blocks; \item in \cref{lst:textwrap4-yaml} we have \emph{not} specified \texttt{all}, and instead, have specified that text wrapping should be applied to each of \texttt{environments} and - \texttt{masterDocument}; - \item in \cref{lst:textwrap5-yaml} we have specified text wrapping for \texttt{masterDocument} + \texttt{mainDocument}; + \item in \cref{lst:textwrap5-yaml} we have specified text wrapping for \texttt{mainDocument} and on a \emph{per-name} basis for \texttt{environments} code blocks. \end{itemize} @@ -303,7 +310,7 @@ latexindent.pl -s textwrap6.tex -l=textwrap8.yaml -m \item in \cref{lst:textwrap6-mod7} the text wrapping routine has not been applied to \texttt{myenv} because it has been switched off (per-name) in \cref{lst:textwrap7-yaml}; \item in \cref{lst:textwrap6-mod8} the text wrapping routine has not been applied to - \texttt{masterDocument} because of the settings in \cref{lst:textwrap8-yaml}. + \texttt{mainDocument} because of the settings in \cref{lst:textwrap8-yaml}. \end{itemize} The \texttt{columns} field has a variety of different ways that it can be specified; @@ -338,12 +345,12 @@ latexindent.pl -s textwrap6.tex -l=textwrap11.yaml -m Notice that: \begin{itemize} - \item in \cref{lst:textwrap6-mod9} the text for the \texttt{masterDocument} has been wrapped + \item in \cref{lst:textwrap6-mod9} the text for the \texttt{mainDocument} has been wrapped using \texttt{30} columns, while \texttt{environments} has been wrapped using \texttt{50} columns; \item in \cref{lst:textwrap6-mod11} the text for \texttt{myenv} has been wrapped using \texttt{50} columns, the text for \texttt{another} has been wrapped using \texttt{15} - columns, and \texttt{masterDocument} has been wrapped using \texttt{30} columns. + columns, and \texttt{mainDocument} has been wrapped using \texttt{30} columns. \end{itemize} If you don't specify a \texttt{default} value on per-code-block basis, then the \texttt{default} value from \texttt{columns} will be inherited; if you don't specify a 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 ebd37ac4f03..262ffe878a5 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 @@ -172,13 +172,13 @@ latexindent.pl myenv-args.tex -l myenv-rules4.yaml has received three spaces of indentation. \yamltitle{noAdditionalIndentGlobal}*{fields} - \begin{wrapfigure}[6]{r}[0pt]{7cm} - \cmhlistingsfromfile[style=noAdditionalIndentGlobalEnv]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{noAdditionalIndentGlobal}}{lst:noAdditionalIndentGlobal:environments} - \end{wrapfigure} Assuming that your environment name is not found within neither \texttt{noAdditionalIndent} nor \texttt{indentRules}, the next place that \texttt{latexindent.pl} will look is \texttt{noAdditionalIndentGlobal}, and in particular \emph{for the environments} key (see \cref{lst:noAdditionalIndentGlobal:environments}). + + \cmhlistingsfromfile[style=noAdditionalIndentGlobalEnv]*{../defaultSettings.yaml}[width=.5\linewidth,before=\centering,yaml-TCB]{\texttt{noAdditionalIndentGlobal}}{lst:noAdditionalIndentGlobal:environments} + Let's say that you change the value of \texttt{environments} to \texttt{1} in \cref{lst:noAdditionalIndentGlobal:environments}, and that you run \index{switches!-l demonstration} @@ -240,12 +240,12 @@ latexindent.pl myenv-args.tex -local mand-args-no-add-glob.yaml \end{minipage} \yamltitle{indentRulesGlobal}*{fields} - \begin{wrapfigure}[4]{r}[0pt]{7cm} - \cmhlistingsfromfile[style=indentRulesGlobalEnv]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{indentRulesGlobal}}{lst:indentRulesGlobal:environments} - \end{wrapfigure} The final check that \texttt{latexindent.pl} will make is to look for - \texttt{indentRulesGlobal} as detailed in \cref{lst:indentRulesGlobal:environments}; if - you change the \texttt{environments} field to anything involving horizontal space, say + \texttt{indentRulesGlobal} as detailed in \cref{lst:indentRulesGlobal:environments}. + + \cmhlistingsfromfile[style=indentRulesGlobalEnv]*{../defaultSettings.yaml}[width=.5\linewidth,before=\centering,yaml-TCB]{\texttt{indentRulesGlobal}}{lst:indentRulesGlobal:environments} + + If you change the \texttt{environments} field to anything involving horizontal space, say \lstinline!" "!, and then run the following commands \index{switches!-l demonstration} diff --git a/Master/texmf-dist/doc/support/latexindent/title.tex b/Master/texmf-dist/doc/support/latexindent/title.tex index 39b50dc0443..66f334fcb5a 100644 --- a/Master/texmf-dist/doc/support/latexindent/title.tex +++ b/Master/texmf-dist/doc/support/latexindent/title.tex @@ -8,14 +8,14 @@ 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.11 + \centering\ttfamily\bfseries latexindent.pl\\[1cm] Version 3.12 \end{tcolorbox} } \author{Chris Hughes \thanks{and contributors! See \vref{sec:contributors}. For all communication, please visit \cite{latexindent-home}.}} -\date{2021-07-31} +\date{2021-09-16} \maketitle \begin{adjustwidth}{1cm}{1cm} \small |