summaryrefslogtreecommitdiff
path: root/support/latexindent/documentation/sec-default-user-local.tex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2021-06-20 03:01:22 +0000
committerNorbert Preining <norbert@preining.info>2021-06-20 03:01:22 +0000
commit0b024adf546cd484554e4de5bd1a9919a4fdd03d (patch)
treef688c8afa79d522868966c9c91e09088f28b5248 /support/latexindent/documentation/sec-default-user-local.tex
parentdaa6873fe1d06863ffc2980970295b39071f02ba (diff)
CTAN sync 202106200301
Diffstat (limited to 'support/latexindent/documentation/sec-default-user-local.tex')
-rw-r--r--support/latexindent/documentation/sec-default-user-local.tex245
1 files changed, 197 insertions, 48 deletions
diff --git a/support/latexindent/documentation/sec-default-user-local.tex b/support/latexindent/documentation/sec-default-user-local.tex
index 2e5afbcdae..426c0c9b78 100644
--- a/support/latexindent/documentation/sec-default-user-local.tex
+++ b/support/latexindent/documentation/sec-default-user-local.tex
@@ -33,6 +33,7 @@ latexindent.pl myfile
\index{backup files!extension settings}
+\subsection{Backup and log file preferences}
\yamltitle{backupExtension}*{extension name}
If you call \texttt{latexindent.pl} with the \texttt{-w} switch (to overwrite
@@ -89,7 +90,7 @@ copy myfile.bak4 to myfile.bak3
amalgamated settings in the log file by switching \texttt{showAmalgamatedSettings} to
\texttt{1}, if you wish.
- \cmhlistingsfromfile[style=logFilePreferences,]*{../defaultSettings.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{logFilePreferences}}{lst:logFilePreferences}
+ \cmhlistingsfromfile*[style=logFilePreferences,]*{../defaultSettings.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{logFilePreferences}}{lst:logFilePreferences}
When%
\announce{2018-01-13}{showDecorationStartCodeBlockTrace feature for log file} either of the
@@ -105,8 +106,16 @@ copy myfile.bak4 to myfile.bak3
Note: \texttt{latexindent.pl} no longer uses the \texttt{log4perl} module to handle
the creation of the logfile.%
- \announce*{2021-03-14}*{no longer using log4perl}
+ \announce{2021-03-14}*{no longer using log4perl}
+ Some of the options%
+ \announce*{2021-06-19}*{logFilePreferences updated to include Dumper options}for Perl's \texttt{Dumper} module can
+ be specified in \cref{lst:logFilePreferences}; see \cite{dumper} and
+ \cite{dumperdemo} for more information. These options will mostly be helpful for
+ those calling \texttt{latexindent.pl} with the \texttt{-tt} option described
+ in \cref{sec:commandline}.
+
+\subsection{Verbatim code blocks}
\yamltitle{verbatimEnvironments}*{fields}
A field that contains a list of environments that you would like left completely alone --
@@ -142,41 +151,58 @@ copy myfile.bak4 to myfile.bak3
you use them with a comment symbol, \lstinline!%!, followed by as many spaces
(possibly none) as you like; see \cref{lst:noIndentBlockdemo} for example.
- \begin{cmhlistings}[style=demo,escapeinside={(*@}{@*)}]{\texttt{noIndentBlock} demonstration}{lst:noIndentBlockdemo}
-%(*@@*) \begin{noindent}
- this code
- won't
- be touched
- by
- latexindent.pl!
-%(*@@*)\end{noindent}
- \end{cmhlistings}
+ \cmhlistingsfromfile{demonstrations/noindentblock.tex}{\texttt{noIndentBlock.tex}}{lst:noIndentBlockdemo}
Important note: it is assumed that the \texttt{noindent} block statements appear on
their own line.
-\yamltitle{removeTrailingWhitespace}*{fields}\label{yaml:removeTrailingWhitespace}
+ The%
+ \announce*{2021-06-19}{noIndentBlock specified as regex} \texttt{noIndentBlock}
+ fields can also be specified in terms of \texttt{begin} and
+ \texttt{end} fields. We begin with the file given in \cref{lst:noIndentBlock1}
- Trailing white space can be removed both \emph{before} and
- \emph{after} processing the document, as detailed in \cref{lst:removeTrailingWhitespace};
- each of the fields can take the values \texttt{0} or
- \texttt{1}. See \vref{lst:removeTWS-before,lst:env-mlb5-modAll,lst:env-mlb5-modAll-remove-WS} for before and after results. Thanks
- to \cite{vosskuhle} for providing this feature.
+ \cmhlistingsfromfile*{demonstrations/noindentblock1.tex}{\texttt{noIndentBlock1.tex}}{lst:noIndentBlock1}
- \begin{minipage}{.4\textwidth}
- \cmhlistingsfromfile[style=removeTrailingWhitespace]*{../defaultSettings.yaml}[before=\centering,yaml-TCB]{removeTrailingWhitespace}{lst:removeTrailingWhitespace}
- \end{minipage}%
- \hfill
- \begin{minipage}{.5\textwidth}
- \begin{yaml}[numbers=none]{removeTrailingWhitespace (alt)}[before=\centering]{lst:removeTrailingWhitespace-alt}
-removeTrailingWhitespace: 1
-\end{yaml}
- \end{minipage}%
+ The settings given in \cref{lst:noindent1,lst:noindent2} are equivalent
- You can specify \texttt{removeTrailingWhitespace} simply as \texttt{0} or
- \texttt{1}, if you wish; in this case,%
- \announce{2017-06-28}{removeTrailingWhitespace} \texttt{latexindent.pl} will set both \texttt{beforeProcessing} and
- \texttt{afterProcessing} to the value you specify; see \cref{lst:removeTrailingWhitespace-alt}.
+ \begin{cmhtcbraster}[raster columns=3,
+ raster left skip=-3.5cm,
+ raster right skip=-2cm,
+ raster column skip=.03\linewidth]
+ \cmhlistingsfromfile*{demonstrations/noindent1.yaml}[yaml-TCB]{\texttt{noindent1.yaml}}{lst:noindent1}
+ \cmhlistingsfromfile*{demonstrations/noindent2.yaml}[yaml-TCB]{\texttt{noindent2.yaml}}{lst:noindent2}
+ \cmhlistingsfromfile*{demonstrations/noindent3.yaml}[yaml-TCB]{\texttt{noindent3.yaml}}{lst:noindent3}
+ \end{cmhtcbraster}
+
+ Upon running the commands
+ \begin{commandshell}
+latexindent.pl -l noindent1.yaml noindent1
+latexindent.pl -l noindent2.yaml noindent1
+\end{commandshell}
+ then we receive the output given in \cref{lst:noIndentBlock1-mod1}.
+
+ \cmhlistingsfromfile*{demonstrations/noindentblock1-mod1.tex}{\texttt{noIndentBlock1.tex} using \cref{lst:noindent1} or \cref{lst:noindent2}}{lst:noIndentBlock1-mod1}
+
+ The \texttt{begin}, \texttt{body} and \texttt{end} fields
+ for \texttt{noIndentBlock} are all \emph{regular expressions}. If the
+ \texttt{body} field is not specified, then it takes a default value of
+ \lstinline!.*?! which is written explicitly in \cref{lst:noindent1}.
+
+ The \texttt{lookForThis} field is optional, and can take the values 0 (off) or 1 (on);
+ by default, it is assumed to be 1 (on).
+
+ Using \cref{lst:noindent3} demonstrates setting \texttt{lookForThis} to 0 (off);
+ running the command
+ \begin{commandshell}
+latexindent.pl -l noindent3.yaml noindent1
+\end{commandshell}
+ gives the output in \cref{lst:noIndentBlock1-mod3}.
+
+ \cmhlistingsfromfile*{demonstrations/noindentblock1-mod3.tex}{\texttt{noIndentBlock1.tex} using \cref{lst:noindent3}}{lst:noIndentBlock1-mod3}
+
+ We will demonstrate this feature later in the documentation in \cref{lst:href3}.
+
+\subsection{filecontents and preamble}
\yamltitle{fileContentsEnvironments}*{field}
Before \texttt{latexindent.pl} determines the difference between preamble (if any) and
@@ -221,18 +247,43 @@ postfoothook=\end{mdframed},
\index{indentation!defaultIndent description}
+\subsection{Indentation and horizontal space}
\yamltitle{defaultIndent}*{horizontal space}
- This is the default indentation (\lstinline!\t! means a tab, and is the default
- value) used in the absence of other details for the command or environment we are working
- with; see \texttt{indentRules} in \vref{sec:noadd-indent-rules} for more details.
+ This is the default indentation used in the absence of other details for the code block
+ with which we are working. The default value is \lstinline!\t! which means a tab;
+ we will explore customisation beyond \texttt{defaultIndent} in \vref{sec:noadd-indent-rules}.
If you're interested in experimenting with \texttt{latexindent.pl} then you can
\emph{remove} all indentation by setting \texttt{defaultIndent: ""}.
+\yamltitle{removeTrailingWhitespace}*{fields}\label{yaml:removeTrailingWhitespace}
+
+ Trailing white space can be removed both \emph{before} and
+ \emph{after} processing the document, as detailed in \cref{lst:removeTrailingWhitespace};
+ each of the fields can take the values \texttt{0} or
+ \texttt{1}. See \vref{lst:removeTWS-before,lst:env-mlb5-modAll,lst:env-mlb5-modAll-remove-WS} for before and after results. Thanks
+ to \cite{vosskuhle} for providing this feature.
+
+ \begin{minipage}{.4\textwidth}
+ \cmhlistingsfromfile[style=removeTrailingWhitespace]*{../defaultSettings.yaml}[before=\centering,yaml-TCB]{removeTrailingWhitespace}{lst:removeTrailingWhitespace}
+ \end{minipage}%
+ \hfill
+ \begin{minipage}{.5\textwidth}
+ \begin{yaml}[numbers=none]{removeTrailingWhitespace (alt)}[before=\centering]{lst:removeTrailingWhitespace-alt}
+removeTrailingWhitespace: 1
+\end{yaml}
+ \end{minipage}%
+
+ You can specify \texttt{removeTrailingWhitespace} simply as \texttt{0} or
+ \texttt{1}, if you wish; in this case,%
+ \announce{2017-06-28}{removeTrailingWhitespace} \texttt{latexindent.pl} will set both \texttt{beforeProcessing} and
+ \texttt{afterProcessing} to the value you specify; see \cref{lst:removeTrailingWhitespace-alt}.
+
+\subsection{Aligning at delimiters}
\yamltitle{lookForAlignDelims}*{fields}
- This contains a list of environments and/or commands that are operated upon in a special
- way by \texttt{latexindent.pl} (see \cref{lst:aligndelims:basic}). In fact, the fields in \texttt{lookForAlignDelims} can
- actually take two different forms: the \emph{basic} version is shown in
+ This contains a list of code blocks that are operated upon in a special way by
+ \texttt{latexindent.pl} (see \cref{lst:aligndelims:basic}). In fact, the fields in \texttt{lookForAlignDelims} can actually take
+ two different forms: the \emph{basic} version is shown in
\cref{lst:aligndelims:basic} and the \emph{advanced} version in
\cref{lst:aligndelims:advanced}; we will discuss each in turn.
\index{delimiters!advanced settings of lookForAlignDelims}
@@ -247,10 +298,9 @@ lookForAlignDelims:
...
\end{yaml}
- 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
+ Specifying code blocks in this field instructs \texttt{latexindent.pl} to try and align
+ each column by its alignment delimiters. It does have some limitations (discussed further
+ in \cref{sec:knownlimitations}), but in many cases it will produce results such as those in
\cref{lst:tabularbefore:basic,lst:tabularafter:basic}.
If you find that \texttt{latexindent.pl} does not perform satisfactorily on such
@@ -291,7 +341,8 @@ lookForAlignDelims:
should be aligned (default: 1);
\item \texttt{spacesBeforeDoubleBackSlash}: optionally,%
\announce{2018-01-13}*{update to spacesBeforeDoubleBackSlash in ampersand alignment} specifies the number (integer $\geq$ 0) of spaces
- to be inserted before \lstinline!\\! (default: 1). \footnote{Previously this only activated if \texttt{alignDoubleBackSlash} was set to \texttt{0}.}
+ to be inserted before \lstinline!\\! (default: 1);
+ %\footnote{Previously this only activated if \texttt{alignDoubleBackSlash} was set to \texttt{0}.}
\item \announce{2017-06-19}{multiColumnGrouping} \texttt{multiColumnGrouping}: binary switch (0 or 1) that details if
\texttt{latexindent.pl} should group columns
above and below a \lstinline!\multicolumn! command (default: 0);
@@ -407,12 +458,104 @@ latexindent.pl tabular2.tex -l tabular2.yaml,tabular8.yaml
output is the same as \cref{lst:tabular2-mod2};
\item in \cref{lst:tabular2-mod7} the \lstinline!\\! \emph{have} been
aligned, and because \texttt{spacesBeforeDoubleBackSlash} is set to \texttt{0}, there are
- no spaces ahead of them; the output is otherwise the same as \cref{lst:tabular2-mod2}.
+ no spaces ahead of them; the output is otherwise the same as \cref{lst:tabular2-mod2};
\item in \cref{lst:tabular2-mod8} the cells have been \emph{right}-justified; note
that cells above and below the \lstinline!\multicol! statements have still been group
correctly, because of the settings in \cref{lst:tabular2YAML}.
\end{itemize}
+\subsubsection{lookForAlignDelims: spacesBeforeAmpersand}
+ The \texttt{spacesBeforeAmpersand}%
+ \announce*{2021-06-19}*{spacesBeforeAmpersand leading blank column upgrade} can be specified in a few different
+ ways. The \emph{basic} form is demonstrated in \cref{lst:tabular4YAML}, but we
+ can customise the behaviour further by specifying if we would like this value to change
+ if it encounters a \emph{leading blank column}; that is, when the first column contains only
+ zero-width entries. We refer to this as the \emph{advanced} form.
+
+ We demonstrate this feature in relation to \cref{lst:aligned1}; upon running the
+ following command
+ \begin{commandshell}
+latexindent.pl aligned1.tex -o=+-default
+\end{commandshell}
+ then we receive the default output given in \cref{lst:aligned1-default}.
+
+ \begin{cmhtcbraster}
+ \cmhlistingsfromfile*{demonstrations/aligned1.tex}{\texttt{aligned1.tex}}{lst:aligned1}
+ \cmhlistingsfromfile*{demonstrations/aligned1-default.tex}{\texttt{aligned1-default.tex}}{lst:aligned1-default}
+ \end{cmhtcbraster}
+
+ The settings in \crefrange{lst:sba1}{lst:sba4} are all equivlanent; we have used the not-yet
+ discussed \texttt{noAdditionalIndent} field (see \vref{sec:noadd-indent-rules}) which will assist
+ in the demonstration in what follows.
+ \begin{cmhtcbraster}[raster columns=2, ]
+ \cmhlistingsfromfile*{demonstrations/sba1.yaml}[yaml-TCB]{\texttt{sba1.yaml}}{lst:sba1}
+ \cmhlistingsfromfile*{demonstrations/sba2.yaml}[yaml-TCB]{\texttt{sba2.yaml}}{lst:sba2}
+ \cmhlistingsfromfile*{demonstrations/sba3.yaml}[yaml-TCB]{\texttt{sba3.yaml}}{lst:sba3}
+ \cmhlistingsfromfile*{demonstrations/sba4.yaml}[yaml-TCB]{\texttt{sba4.yaml}}{lst:sba4}
+ \end{cmhtcbraster}
+ Upon running the following commands
+ \begin{commandshell}
+latexindent.pl aligned1.tex -l sba1.yaml
+latexindent.pl aligned1.tex -l sba2.yaml
+latexindent.pl aligned1.tex -l sba3.yaml
+latexindent.pl aligned1.tex -l sba4.yaml
+\end{commandshell}
+ then we receive the (same) output given in \cref{lst:aligned1-mod1}; we note that there is
+ \emph{one space} before each ampersand.
+
+ \begin{cmhtcbraster}
+ \cmhlistingsfromfile*{demonstrations/aligned1-mod1.tex}{\texttt{aligned1-mod1.tex}}{lst:aligned1-mod1}
+ \end{cmhtcbraster}
+
+ We note in particular:
+ \begin{itemize}
+ \item \cref{lst:sba1} demonstrates the \emph{basic} form for
+ \texttt{lookForAlignDelims}; in this case,
+ the default values are specified as in \vref{lst:aligndelims:advanced};
+ \item \cref{lst:sba2} demonstrates the \emph{advanced} form for
+ \texttt{lookForAlignDelims}
+ and specified \texttt{spacesBeforeAmpersand}. The default value is \texttt{1};
+ \item \cref{lst:sba3} demonstrates the new \emph{advanced} way to specify
+ \texttt{spacesBeforeAmpersand}, and
+ for us to set the \texttt{default} value that sets the number of spaces before
+ ampersands which are \emph{not} in leading blank columns. The default
+ value is \texttt{1}.
+
+ We note that \texttt{leadingBlankColumn} has not been specified in \cref{lst:sba3},
+ and it will inherit the value from \texttt{default};
+ \item \cref{lst:sba4} demonstrates spaces to be used before amperands for
+ \emph{leading blank columns}.
+ We note that \emph{default} has not been specified, and it will be set to
+ \texttt{1} by default.
+ \end{itemize}
+ We can customise the space before the ampersand in the \emph{leading blank column} of
+ \cref{lst:aligned1-mod1} by using either of \cref{lst:sba5,lst:sba6}, which are equivalent.
+
+ \begin{cmhtcbraster}
+ \cmhlistingsfromfile*{demonstrations/sba5.yaml}[yaml-TCB]{\texttt{sba5.yaml}}{lst:sba5}
+ \cmhlistingsfromfile*{demonstrations/sba6.yaml}[yaml-TCB]{\texttt{sba6.yaml}}{lst:sba6}
+ \end{cmhtcbraster}
+
+ Upon running
+ \begin{commandshell}
+latexindent.pl aligned1.tex -l sba5.yaml
+latexindent.pl aligned1.tex -l sba6.yaml
+\end{commandshell}
+ then we receive the (same) output given in \cref{lst:aligned1-mod5}. We note that the
+ space before the ampersand in the \emph{leading blank column} has been set to
+ \texttt{0} by \cref{lst:sba6}.
+
+ We can demonstrated this feature further using the settings in \cref{lst:sba7}
+ which give the output in \cref{lst:aligned1-mod7}.
+
+ \begin{cmhtcbraster}[raster columns=3,
+ raster left skip=-3.75cm,
+ raster right skip=-2cm,]
+ \cmhlistingsfromfile*{demonstrations/aligned1-mod5.tex}{\texttt{aligned1-mod5.tex}}{lst:aligned1-mod5}
+ \cmhlistingsfromfile*{demonstrations/aligned1-mod7.tex}{\texttt{aligned1.tex} using \cref{lst:sba7}}{lst:aligned1-mod7}
+ \cmhlistingsfromfile*{demonstrations/sba7.yaml}[yaml-TCB]{\texttt{sba7.yaml}}{lst:sba7}
+ \end{cmhtcbraster}
+\subsubsection{lookForAlignDelims: alignFinalDoubleBackSlash}
We explore%
\announce{2020-03-21}{alignFinalDoubleBackSlash demonstration} the
\texttt{alignFinalDoubleBackSlash} feature by using the file in \cref{lst:tabular4}. Upon
@@ -479,7 +622,7 @@ latexindent.pl matrix1.tex
(see \vref{sec:noadd-indent-rules}), these comment-marked blocks are
considered \texttt{environments}.
-\subsection{lookForAlignDelims: the dontMeasure feature}\label{sec:dontMeasure}
+\subsubsection{lookForAlignDelims: the dontMeasure feature}\label{sec:dontMeasure}
The%
\announce{2020-03-21}{don't measure feature} \texttt{lookForAlignDelims}
field can, optionally, receive the \texttt{dontMeasure} option which can be specified
@@ -586,7 +729,7 @@ latexindent.pl tabular-DM.tex -l=dontMeasure6.yaml
\cmhlistingsfromfile{demonstrations/dontMeasure6.yaml}[yaml-TCB]{\texttt{dontMeasure6.yaml}}{lst:dontMeasure6}
\end{cmhtcbraster}
-\subsection{lookForAlignDelims: the delimiterRegEx and delimiterJustification feature}\label{sec:delimiter-reg-ex}
+\subsubsection{lookForAlignDelims: the delimiterRegEx and delimiterJustification feature}\label{sec:delimiter-reg-ex}
The delimiter alignment%
\announce{2020-03-21}{delimiterRegEx feature} will, by
default, align code blocks at the ampersand character. The behaviour is controlled by the
@@ -707,6 +850,7 @@ latexindent.pl tabbing1.tex -l=delimiterRegEx5.yaml -o=+-mod5
Note that in \cref{lst:tabbing1-mod5} the second set of delimiters have been
\emph{right aligned} -- it is quite subtle!
+\subsection{Indent after items, specials and headings}
\yamltitle{indentAfterItems}*{fields}
The environment names specified in \texttt{indentAfterItems} tell \texttt{latexindent.pl}
to look for \lstinline!\item! commands; if these switches are set to
@@ -906,10 +1050,15 @@ latexindent.pl special-align.tex -l edge-node2.yaml -o=+-mod2
\index{regular expressions!horizontal space \textbackslash{h}}
\begin{cmhtcbraster}[ raster left skip=-3.5cm,]
- \cmhlistingsfromfile{demonstrations/edge-node2.yaml}[yaml-TCB]{\texttt{edge-node2.yaml}}{lst:edge-node2}
+ \cmhlistingsfromfile*{demonstrations/edge-node2.yaml}[yaml-TCB]{\texttt{edge-node2.yaml}}{lst:edge-node2}
\cmhlistingsfromfile{demonstrations/special-align-mod2.tex}{\texttt{special-align.tex} using \cref{lst:edge-node2}}{lst:special-align-mod2}
\end{cmhtcbraster}
+ The \texttt{lookForThis} field can be considered
+ optional;%
+ \announce*{2021-06-19}*{lookForThis optional for specialBeginEnd} by default, it is
+ assumed to be 1, which is demonstrated in \cref{lst:edge-node2}.
+
\yamltitle{indentAfterHeadings}*{fields}
This field enables the user to specify indentation rules that take effect after heading
commands such as \lstinline!\part!, \lstinline!\chapter!,
@@ -1065,19 +1214,19 @@ mand arg text
\[
...
\]
- \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}