summaryrefslogtreecommitdiff
path: root/support/latexindent/documentation
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2021-09-17 03:00:43 +0000
committerNorbert Preining <norbert@preining.info>2021-09-17 03:00:43 +0000
commitaefe346b16163823efeac108a7da42e91e53e5c7 (patch)
treed843b77551dc58ce9e491261306253162af117f5 /support/latexindent/documentation
parente7ce6275948b3b197682f44f64fdb1daf672109c (diff)
CTAN sync 202109170300
Diffstat (limited to 'support/latexindent/documentation')
-rw-r--r--support/latexindent/documentation/appendices.tex46
-rw-r--r--support/latexindent/documentation/cmhlistings.tex9
-rw-r--r--support/latexindent/documentation/latexindent.pdfbin949988 -> 1001116 bytes
-rw-r--r--support/latexindent/documentation/latexindent.tex29
-rw-r--r--support/latexindent/documentation/sec-default-user-local.tex29
-rw-r--r--support/latexindent/documentation/sec-how-to-use.tex77
-rw-r--r--support/latexindent/documentation/sec-the-line-switch.tex187
-rw-r--r--support/latexindent/documentation/sec-the-m-switch.tex5
-rw-r--r--support/latexindent/documentation/subsec-combine-text-wrap-para-line-breaks.tex16
-rw-r--r--support/latexindent/documentation/subsec-remove-para-line-breaks.tex9
-rw-r--r--support/latexindent/documentation/subsec-text-wrap-summary.tex2
-rw-r--r--support/latexindent/documentation/subsec-text-wrap.tex23
-rw-r--r--support/latexindent/documentation/subsubsec-environments-and-their-arguments.tex16
-rw-r--r--support/latexindent/documentation/title.tex4
14 files changed, 388 insertions, 64 deletions
diff --git a/support/latexindent/documentation/appendices.tex b/support/latexindent/documentation/appendices.tex
index bbeefb5fd1..617abe1bdc 100644
--- a/support/latexindent/documentation/appendices.tex
+++ b/support/latexindent/documentation/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/support/latexindent/documentation/cmhlistings.tex b/support/latexindent/documentation/cmhlistings.tex
index 1f058616d6..6b8506c344 100644
--- a/support/latexindent/documentation/cmhlistings.tex
+++ b/support/latexindent/documentation/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/support/latexindent/documentation/latexindent.pdf b/support/latexindent/documentation/latexindent.pdf
index dfb37e0b76..12ad2f551c 100644
--- a/support/latexindent/documentation/latexindent.pdf
+++ b/support/latexindent/documentation/latexindent.pdf
Binary files differ
diff --git a/support/latexindent/documentation/latexindent.tex b/support/latexindent/documentation/latexindent.tex
index 9379dddcb0..a97d778742 100644
--- a/support/latexindent/documentation/latexindent.tex
+++ b/support/latexindent/documentation/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/support/latexindent/documentation/sec-default-user-local.tex b/support/latexindent/documentation/sec-default-user-local.tex
index 85738608b9..b649f54f9c 100644
--- a/support/latexindent/documentation/sec-default-user-local.tex
+++ b/support/latexindent/documentation/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/support/latexindent/documentation/sec-how-to-use.tex b/support/latexindent/documentation/sec-how-to-use.tex
index 42553e037a..c297418928 100644
--- a/support/latexindent/documentation/sec-how-to-use.tex
+++ b/support/latexindent/documentation/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/support/latexindent/documentation/sec-the-line-switch.tex b/support/latexindent/documentation/sec-the-line-switch.tex
new file mode 100644
index 0000000000..0c06daec2d
--- /dev/null
+++ b/support/latexindent/documentation/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/support/latexindent/documentation/sec-the-m-switch.tex b/support/latexindent/documentation/sec-the-m-switch.tex
index 8a824987f6..1388a84932 100644
--- a/support/latexindent/documentation/sec-the-m-switch.tex
+++ b/support/latexindent/documentation/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/support/latexindent/documentation/subsec-combine-text-wrap-para-line-breaks.tex b/support/latexindent/documentation/subsec-combine-text-wrap-para-line-breaks.tex
index 2c05d60dda..80ec2b42e1 100644
--- a/support/latexindent/documentation/subsec-combine-text-wrap-para-line-breaks.tex
+++ b/support/latexindent/documentation/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/support/latexindent/documentation/subsec-remove-para-line-breaks.tex b/support/latexindent/documentation/subsec-remove-para-line-breaks.tex
index f5531cbba4..2b9de853b1 100644
--- a/support/latexindent/documentation/subsec-remove-para-line-breaks.tex
+++ b/support/latexindent/documentation/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/support/latexindent/documentation/subsec-text-wrap-summary.tex b/support/latexindent/documentation/subsec-text-wrap-summary.tex
index 89379eabbc..b6066e2cc9 100644
--- a/support/latexindent/documentation/subsec-text-wrap-summary.tex
+++ b/support/latexindent/documentation/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/support/latexindent/documentation/subsec-text-wrap.tex b/support/latexindent/documentation/subsec-text-wrap.tex
index 2e721cae1a..781aeccf73 100644
--- a/support/latexindent/documentation/subsec-text-wrap.tex
+++ b/support/latexindent/documentation/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/support/latexindent/documentation/subsubsec-environments-and-their-arguments.tex b/support/latexindent/documentation/subsubsec-environments-and-their-arguments.tex
index ebd37ac4f0..262ffe878a 100644
--- a/support/latexindent/documentation/subsubsec-environments-and-their-arguments.tex
+++ b/support/latexindent/documentation/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/support/latexindent/documentation/title.tex b/support/latexindent/documentation/title.tex
index 39b50dc044..66f334fcb5 100644
--- a/support/latexindent/documentation/title.tex
+++ b/support/latexindent/documentation/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