summaryrefslogtreecommitdiff
path: root/support/latexindent/documentation
diff options
context:
space:
mode:
Diffstat (limited to 'support/latexindent/documentation')
-rw-r--r--support/latexindent/documentation/latexindent-yaml-schema.json183
-rw-r--r--support/latexindent/documentation/latexindent.pdfbin1089386 -> 1060430 bytes
-rw-r--r--support/latexindent/documentation/latexindent.tex53
-rw-r--r--support/latexindent/documentation/sec-appendices.tex59
-rw-r--r--support/latexindent/documentation/sec-conclusions-know-limitations.tex9
-rw-r--r--support/latexindent/documentation/sec-default-user-local.tex358
-rw-r--r--support/latexindent/documentation/sec-fine-tuning.tex112
-rw-r--r--support/latexindent/documentation/sec-how-to-use.tex110
-rw-r--r--support/latexindent/documentation/sec-indent-config-and-settings.tex47
-rw-r--r--support/latexindent/documentation/sec-introduction.tex24
-rw-r--r--support/latexindent/documentation/sec-replacements.tex154
-rw-r--r--support/latexindent/documentation/sec-the-line-switch.tex55
-rw-r--r--support/latexindent/documentation/sec-the-m-switch.tex20
-rw-r--r--support/latexindent/documentation/subsec-combine-text-wrap-para-line-breaks.tex19
-rw-r--r--support/latexindent/documentation/subsec-commands-and-their-options.tex56
-rw-r--r--support/latexindent/documentation/subsec-one-sentence-per-line.tex114
-rw-r--r--support/latexindent/documentation/subsec-poly-switches.tex232
-rw-r--r--support/latexindent/documentation/subsec-remove-para-line-breaks.tex224
-rw-r--r--support/latexindent/documentation/subsec-text-wrap-summary.tex26
-rw-r--r--support/latexindent/documentation/subsec-text-wrap.tex645
-rw-r--r--support/latexindent/documentation/subsubsec-commands-with-arguments.tex11
-rw-r--r--support/latexindent/documentation/subsubsec-environments-and-their-arguments.tex34
-rw-r--r--support/latexindent/documentation/subsubsec-environments-with-items.tex6
-rw-r--r--support/latexindent/documentation/subsubsec-headings.tex5
-rw-r--r--support/latexindent/documentation/subsubsec-ifelsefi.tex15
-rw-r--r--support/latexindent/documentation/subsubsec-no-add-remaining-code-blocks.tex25
-rw-r--r--support/latexindent/documentation/subsubsec-special.tex9
-rw-r--r--support/latexindent/documentation/test-default-settings.tex5
-rw-r--r--support/latexindent/documentation/title.tex4
29 files changed, 1000 insertions, 1614 deletions
diff --git a/support/latexindent/documentation/latexindent-yaml-schema.json b/support/latexindent/documentation/latexindent-yaml-schema.json
index 013c7c7656..34c9354f75 100644
--- a/support/latexindent/documentation/latexindent-yaml-schema.json
+++ b/support/latexindent/documentation/latexindent-yaml-schema.json
@@ -2,7 +2,7 @@
"$schema": "http://json-schema.org/schema",
"$id": "latexindent-yaml-schema.json",
"title": "latexindent.pl YAML schema",
- "description": "latexindent.pl YAML schema helper, V3.15 2022-01-21",
+ "description": "latexindent.pl YAML schema helper, V3.16 2022-03-13",
"type": "object",
"properties": {
"fileExtensionPreference": {
@@ -672,9 +672,9 @@
"type":"object",
"properties": {
"columns": {
- "description": "integer > 0 sets the number of columns for the text wrap routine",
+ "description": "integer > 0 sets the number of columns for the text wrap routine, or if -1 then text wrap blocks simply have line breaks removed",
"type": "integer",
- "minimum": 0
+ "minimum": -1
},
"huge": {
"description": "WARNING: I don't recommend changing this from overflow",
@@ -684,177 +684,22 @@
"description": "can be any string, but I haven't found a good use case to change this from ''",
"type": "string"
},
- "perCodeBlockBasis": {
- "description": "0/1, binary switch to determine if text wrap should operate on a per-code-block basis or not",
- "type": "integer",
- "enum": [0,1]
- },
- "beforeFindingChildCodeBlocks": {
- "description": "0/1, binary switch to determine if text wrap should operate *before* finding code-blocks or not",
- "type": "integer",
- "enum": [0,1]
- },
- "all": {
- "description": "0/1, binary switch to determine if text wrap should operate on *all* code blocks or not",
- "type": "integer",
- "enum": [0,1]
- },
- "alignAtAmpersandTakesPriority": {
- "description": "0/1, binary switch to determine if align at ampersand (lookForAlignDelims) takes priority over text wrap routine or not",
- "type": "integer",
- "enum": [0,1]
- },
- "environments": {
- "description": "can either be 0/1 (for all environments or not) or otherwise list of environments",
- "type": ["integer","object"]
- },
- "ifElseFi": {
- "description": "can either be 0/1 (for all ifElseFi or not) or otherwise list of ifElseFi",
- "type": ["integer","object"]
- },
- "optionalArguments": {
- "description": "can either be 0/1 (for all optionalArguments or not) or otherwise list of optionalArguments",
- "type": ["integer","object"]
- },
- "mandatoryArguments": {
- "description": "can either be 0/1 (for all mandatoryArguments or not) or otherwise list of mandatoryArguments",
- "type": ["integer","object"]
- },
- "items": {
- "description": "can either be 0/1 (for all items or not) or otherwise list of items",
- "type": ["integer","object"]
- },
- "specialBeginEnd": {
- "description": "can either be 0/1 (for all specialBeginEnd or not) or otherwise list of specialBeginEnd",
- "type": ["integer","object"]
- },
- "afterHeading": {
- "description": "can either be 0/1 (for all afterHeading or not) or otherwise list of headings",
- "type": ["integer","object"]
- },
- "preamble": {
- "description": "0/1, binary switch to determine if text wrap to operate on preamble or not",
- "type": ["integer","object"]
- },
- "filecontents": {
- "description": "can either be 0/1 (for all filecontents or not) or otherwise list of filecontents",
- "type": ["integer","object"]
- },
- "mainDocument": {
- "description": "0/1, binary switch to determine if text wrap to operate on mainDocument or not",
- "type": ["integer","object"]
- }
- }
- },
- "removeParagraphLineBreaks":{
- "description": "options for the remove paragraph line breaks routine",
- "type":"object",
- "properties": {
- "all": {
- "description": "0/1, binary switch to determine if remove paragraph line breaks should operate on *all* code blocks or not",
+ "multipleSpacesToSingle": {
+ "description": "0/1, binary switch to determine if text wrap should convert multiple spaces to single space",
"type": "integer",
"enum": [0,1]
},
- "beforeTextWrap": {
- "description": "0/1, binary switch to determine if remove paragraph line breaks should operate *before* text wrap routine",
- "type": "integer",
- "enum": [0,1]
- },
- "alignAtAmpersandTakesPriority": {
- "description": "0/1, binary switch to determine if align at ampersand (lookForAlignDelims) takes priority over remove paragraph line break routine or not",
- "type": "integer",
- "enum": [0,1]
- },
- "environments": {
- "description": "can either be 0/1 (for all environments or not) or otherwise list of environments",
- "type": ["integer","object"]
- },
- "ifElseFi": {
- "description": "can either be 0/1 (for all ifElseFi or not) or otherwise list of ifElseFi",
- "type": ["integer","object"]
- },
- "optionalArguments": {
- "description": "can either be 0/1 (for all optionalArguments or not) or otherwise list of optionalArguments",
- "type": ["integer","object"]
- },
- "mandatoryArguments": {
- "description": "can either be 0/1 (for all mandatoryArguments or not) or otherwise list of mandatoryArguments",
- "type": ["integer","object"]
+ "blocksFollow": {
+ "description": "field containing switches that text wrap blocks *follow*",
+ "type": ["object"]
},
- "items": {
- "description": "can either be 0/1 (for all items or not) or otherwise list of items",
- "type": ["integer","object"]
+ "blocksBeginWith": {
+ "description": "field containing switches that text wrap blocks *begin with*",
+ "type": ["object"]
},
- "specialBeginEnd": {
- "description": "can either be 0/1 (for all specialBeginEnd or not) or otherwise list of specialBeginEnd",
- "type": ["integer","object"]
- },
- "afterHeading": {
- "description": "can either be 0/1 (for all afterHeading or not) or otherwise list of headings",
- "type": ["integer","object"]
- },
- "preamble": {
- "description": "0/1, binary switch to determine if text wrap to operate on preamble or not",
- "type": ["integer","object"]
- },
- "filecontents": {
- "description": "can either be 0/1 (for all filecontents or not) or otherwise list of filecontents",
- "type": ["integer","object"]
- },
- "mainDocument": {
- "description": "0/1, binary switch to determine if text wrap to operate on mainDocument or not",
- "type": ["integer","object"]
- },
- "paragraphsStopAt": {
- "description": "list of binary switches to determine the points at which paragraphs stop",
- "type": "object",
- "properties": {
- "environments": {
- "description": "0/1, binary switch to determine if paragraphStopsAt stops at environments",
- "type": "integer",
- "enum": [0,1]
- },
- "verbatim": {
- "description": "0/1, binary switch to determine if paragraphStopsAt stops at verbatim",
- "type": "integer",
- "enum": [0,1]
- },
- "commands": {
- "description": "0/1, binary switch to determine if paragraphStopsAt stops at commands",
- "type": "integer",
- "enum": [0,1]
- },
- "ifElseFi": {
- "description": "0/1, binary switch to determine if paragraphStopsAt stops at ifElseFi",
- "type": "integer",
- "enum": [0,1]
- },
- "items": {
- "description": "0/1, binary switch to determine if paragraphStopsAt stops at items",
- "type": "integer",
- "enum": [0,1]
- },
- "specialBeginEnd": {
- "description": "0/1, binary switch to determine if paragraphStopsAt stops at specialBeginEnd",
- "type": "integer",
- "enum": [0,1]
- },
- "heading": {
- "description": "0/1, binary switch to determine if paragraphStopsAt stops at heading",
- "type": "integer",
- "enum": [0,1]
- },
- "filecontents": {
- "description": "0/1, binary switch to determine if paragraphStopsAt stops at filecontents",
- "type": "integer",
- "enum": [0,1]
- },
- "comments": {
- "description": "0/1, binary switch to determine if paragraphStopsAt stops at comments",
- "type": "integer",
- "enum": [0,1]
- }
- }
+ "blocksEndBefore": {
+ "description": "field containing switches that text wrap blocks *end before*",
+ "type": ["object"]
}
}
},
diff --git a/support/latexindent/documentation/latexindent.pdf b/support/latexindent/documentation/latexindent.pdf
index 78f618b377..a6623c6b94 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 0ccca1d0ea..95fa9d694a 100644
--- a/support/latexindent/documentation/latexindent.tex
+++ b/support/latexindent/documentation/latexindent.tex
@@ -402,127 +402,115 @@
\lstdefinestyle{indentAfterItems}{
style=yaml-LST,
- firstnumber=229,linerange={229-233},
+ firstnumber=233,linerange={233-237},
numbers=left,
}
\lstdefinestyle{itemNames}{
style=yaml-LST,
- firstnumber=239,linerange={239-241},
+ firstnumber=243,linerange={243-245},
numbers=left,
}
\lstdefinestyle{specialBeginEnd}{
style=yaml-LST,
- firstnumber=245,linerange={245-258},
+ firstnumber=249,linerange={249-262},
numbers=left,
}
\lstdefinestyle{indentAfterHeadings}{
style=yaml-LST,
- firstnumber=268,linerange={268-277},
+ firstnumber=272,linerange={272-281},
numbers=left,
}
\lstdefinestyle{noAdditionalIndentGlobalEnv}{
style=yaml-LST,
- firstnumber=326,linerange={326-327},
+ firstnumber=330,linerange={330-331},
numbers=left,
}
\lstdefinestyle{noAdditionalIndentGlobal}{
style=yaml-LST,
- firstnumber=326,linerange={326-338},
+ firstnumber=330,linerange={330-342},
numbers=left,
}
\lstdefinestyle{indentRulesGlobalEnv}{
style=yaml-LST,
- firstnumber=342,linerange={342-343},
+ firstnumber=346,linerange={346-347},
numbers=left,
}
\lstdefinestyle{indentRulesGlobal}{
style=yaml-LST,
- firstnumber=342,linerange={342-354},
+ firstnumber=346,linerange={346-358},
numbers=left,
}
\lstdefinestyle{commandCodeBlocks}{
style=yaml-LST,
- firstnumber=357,linerange={357-372},
+ firstnumber=361,linerange={361-376},
numbers=left,
}
\lstdefinestyle{modifylinebreaks}{
style=yaml-LST,
- firstnumber=487,linerange={487-489},
+ firstnumber=491,linerange={491-493},
numbers=left,
}
\lstdefinestyle{textWrapOptions}{
style=yaml-LST,
- firstnumber=514,linerange={514-515},
+ firstnumber=518,linerange={518-519},
numbers=left,
}
\lstdefinestyle{textWrapOptionsAll}{
style=yaml-LST,
- firstnumber=514,linerange={514-532},
- numbers=left,
-}
-
-\lstdefinestyle{removeParagraphLineBreaks}{
- style=yaml-LST,
- firstnumber=533,linerange={533-547},
- numbers=left,
-}
-
-\lstdefinestyle{paragraphsStopAt}{
- style=yaml-LST,
- firstnumber=548,linerange={548-557},
+ firstnumber=518,linerange={518-540},
numbers=left,
}
\lstdefinestyle{oneSentencePerLine}{
style=yaml-LST,
- firstnumber=490,linerange={490-513},
+ firstnumber=494,linerange={494-517},
numbers=left,
}
\lstdefinestyle{sentencesFollow}{
style=yaml-LST,
- firstnumber=495,linerange={495-503},
+ firstnumber=499,linerange={499-507},
numbers=left,
}
\lstdefinestyle{sentencesBeginWith}{
style=yaml-LST,
- firstnumber=504,linerange={504-507},
+ firstnumber=508,linerange={508-511},
numbers=left,
}
\lstdefinestyle{sentencesEndWith}{
style=yaml-LST,
- firstnumber=508,linerange={508-513},
+ firstnumber=512,linerange={512-517},
numbers=left,
}
\lstdefinestyle{modifylinebreaksEnv}{
style=yaml-LST,
- firstnumber=558,linerange={558-567},
+ firstnumber=542,linerange={542-551},
numbers=left,
}
\lstdefinestyle{replacements}{
style=yaml-LST,
- firstnumber=619,linerange={619-627},
+ firstnumber=603,linerange={603-611},
numbers=left,
}
\lstdefinestyle{fineTuning}{
style=yaml-LST,
- firstnumber=630,linerange={630-655},
+ firstnumber=614,linerange={614-639},
numbers=left,
}
@@ -825,9 +813,6 @@
\input{subsec-commands-and-their-options}
\input{sec-the-m-switch}
\input{subsec-text-wrap}
- \input{subsec-remove-para-line-breaks}
- \input{subsec-combine-text-wrap-para-line-breaks}
- \input{subsec-text-wrap-summary}
\input{subsec-one-sentence-per-line}
\input{subsec-poly-switches}
\stopcontents[the-m-switch]
diff --git a/support/latexindent/documentation/sec-appendices.tex b/support/latexindent/documentation/sec-appendices.tex
index b797f2ebcc..64f49180e9 100644
--- a/support/latexindent/documentation/sec-appendices.tex
+++ b/support/latexindent/documentation/sec-appendices.tex
@@ -170,8 +170,8 @@ ls /usr/local/bin
to see what is \emph{currently} in there;
\item run the following commands
\begin{commandshell}
-sudo apt-get install cmake
-sudo apt-get update && sudo apt-get install build-essential
+sudo apt-get update
+sudo apt-get install --no-install-recommends cmake make # or any other generator
mkdir build && cd build
cmake ../path-helper-files
sudo make install
@@ -218,9 +218,7 @@ echo %path%
\subsection{VSCode demonstration}
To use \texttt{latexindent-yaml-schema.json} with \texttt{VSCode}, you can use the
- following steps:
- \index{VSCode}
- \index{json!VSCode}
+ following steps: \index{VSCode} \index{json!VSCode}
\begin{enumerate}
\item download \texttt{latexindent-yaml-schema.json} from the \texttt{documentation} folder of
\cite{latexindent-home}, save it in whichever directory you would like, noting it for
@@ -281,11 +279,10 @@ conda run latexindent.pl -vv
\section{pre-commit}
- Users of \texttt{.git} may be interested
- \announce*{2022-01-21}{pre-commit for latexindent.pl} in
- exploring the \texttt{pre-commit} tool \cite{pre-commithome}, which is supported by
- \texttt{latexindent.pl}. Thank you to \cite{tdegeusprecommit} for contributing this
- feature.
+ Users of \texttt{.git} may be interested \announce*{2022-01-21}{pre-commit for
+ latexindent.pl} in exploring the \texttt{pre-commit} tool \cite{pre-commithome}, which is
+ supported by \texttt{latexindent.pl}. Thank you to \cite{tdegeusprecommit} for
+ contributing this feature.
To use the \texttt{pre-commit} tool, you will need to install \texttt{pre-commit}; sample
instructions for Ubuntu are given in \cref{sec:pre-commit-ubuntu}. Once installed, there
@@ -308,17 +305,9 @@ export PATH=$PATH:/home/cmhughes/.local/bin
To use \texttt{latexindent.pl} with \texttt{pre-commit}, create the file
\texttt{.pre-commit-config.yaml} given in \cref{lst:.pre-commit-config.yaml-cpan} in your
- git-repository.
- \index{cpan}
- \index{git}
- \index{pre-commit!cpan}
- \begin{cmhlistings}*[style=tcblatex]{\texttt{.pre-commit-config.yaml} (cpan)}{lst:.pre-commit-config.yaml-cpan}
-- repo: https://github.com/cmhughes/latexindent.pl
- rev: V3.15
- hooks:
- - id: latexindent
- args: [-s]
-\end{cmhlistings}
+ git-repository. \index{cpan} \index{git} \index{pre-commit!cpan}
+
+ \cmhlistingsfromfile{demonstrations/pre-commit-config-cpan.yaml}[yaml-TCB]{\texttt{.pre-commit-config.yaml} (cpan)}{lst:.pre-commit-config.yaml-cpan}
Once created, you should then be able to run the following command:
\begin{commandshell}
pre-commit run --all-files
@@ -345,17 +334,9 @@ latexindent.pl -s myfile.tex
You can also rely on \texttt{conda} (detailed in \cref{sec:app:conda}) instead of
\texttt{CPAN} for all dependencies, including \texttt{latexindent.pl} itself.
- \index{conda}
- \index{git}
- \index{pre-commit!conda}
-
- \begin{cmhlistings}*[style=tcblatex]{\texttt{.pre-commit-config.yaml} (conda)}{lst:.pre-commit-config.yaml-conda}
-- repo: https://github.com/cmhughes/latexindent.pl
- rev: V3.15
- hooks:
- - id: latexindent-conda
- args: [-s]
-\end{cmhlistings}
+ \index{conda} \index{git} \index{pre-commit!conda}
+
+ \cmhlistingsfromfile{demonstrations/pre-commit-config-conda.yaml}[yaml-TCB]{\texttt{.pre-commit-config.yaml} (conda)}{lst:.pre-commit-config.yaml-conda}
Once created, you should then be able to run the following command:
\begin{commandshell}
pre-commit run --all-files
@@ -390,14 +371,8 @@ modifyLineBreaks:
\end{cmhlistings}
and \texttt{.pre-commit-config.yaml} as in \cref{lst:.latexindent.yaml-switches}:
- \begin{cmhlistings}*[style=tcblatex]{\texttt{.pre-commit-config.yaml}}{lst:.latexindent.yaml-switches}
-repos:
-- repo: https://github.com/cmhughes/latexindent.pl
- rev: V3.15
- hooks:
- - id: latexindent
- args: [-l, -m, -s, -w]
-\end{cmhlistings}
+
+ \cmhlistingsfromfile{demonstrations/pre-commit-config-demo.yaml}[yaml-TCB]{\texttt{.pre-commit-config.yaml} (demo)}{lst:.latexindent.yaml-switches}
Now running
\begin{commandshell}
pre-commit run --all-files
@@ -527,8 +502,8 @@ latexindent.pl myfile.tex -outputfile outputfile.tex
To specify \texttt{noAdditionalIndent} for display-math environments in Version 2.2, you
would write YAML as in \cref{lst:noAdditionalIndentOld}; as of Version 3.0, you would
write YAML as in \cref{lst:indentAfterThisHeadingNew1} or, if you're using \texttt{-m}
- switch, \cref{lst:indentAfterThisHeadingNew2}.
- \index{specialBeginEnd!update to displaymath V3.0}
+ switch, \cref{lst:indentAfterThisHeadingNew2}. \index{specialBeginEnd!update to
+ displaymath V3.0}
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile{demonstrations/noAddtionalIndentOld.yaml}[yaml-TCB]{\texttt{noAdditionalIndent} in Version 2.2}{lst:noAdditionalIndentOld}
diff --git a/support/latexindent/documentation/sec-conclusions-know-limitations.tex b/support/latexindent/documentation/sec-conclusions-know-limitations.tex
index fe31bde794..5afdddb6cc 100644
--- a/support/latexindent/documentation/sec-conclusions-know-limitations.tex
+++ b/support/latexindent/documentation/sec-conclusions-know-limitations.tex
@@ -14,13 +14,12 @@
will need to be stored in the `packing' phase, and that this will improve the efficiency
of the script.
- You can run \texttt{latexindent} on any file;%
- \announce{2019-07-13}*{ability to call latexindent on any file} if you don't specify an
- extension, then the extensions that you specify in
- \lstinline[breaklines=true]!fileExtensionPreference! (see
+ You can run \texttt{latexindent} on any file; \announce{2019-07-13}*{ability to call
+ latexindent on any file} if you don't specify an extension, then the extensions that you
+ specify in \lstinline[breaklines=true]!fileExtensionPreference! (see
\vref{lst:fileExtensionPreference}) will be consulted. If you find a case in which the
script struggles, please feel free to report it at \cite{latexindent-home}, and in the
- meantime, consider using a \texttt{noIndentBlock} (see \cpageref{lst:noIndentBlock}).
+ meantime, consider using a \texttt{noIndentBlock} (see \cpageref{lst:noIndentBlock}).%
I hope that this script is useful to some; if you find an example where the script does
not behave as you think it should, the best way to contact me is to report an issue on
diff --git a/support/latexindent/documentation/sec-default-user-local.tex b/support/latexindent/documentation/sec-default-user-local.tex
index 6be0bbe3f5..94fbdce46c 100644
--- a/support/latexindent/documentation/sec-default-user-local.tex
+++ b/support/latexindent/documentation/sec-default-user-local.tex
@@ -34,7 +34,7 @@ latexindent.pl myfile
\cref{lst:fileExtensionPreference} means that the script will first look for
\texttt{myfile.tex}, then \texttt{myfile.sty}, \texttt{myfile.cls}, and finally
\texttt{myfile.bib} in order\footnote{Throughout this manual, listings shown with line
- numbers represent code taken directly from \texttt{defaultSettings.yaml}.}.
+ numbers represent code taken directly from \texttt{defaultSettings.yaml}.}.
\index{backup files!extension settings}
@@ -95,37 +95,33 @@ copy myfile.bak4 to myfile.bak3
\cmhlistingsfromfile[style=logFilePreferences,]{../defaultSettings.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{logFilePreferences}}{lst:logFilePreferences}
- When%
- \announce{2018-01-13}{showDecorationStartCodeBlockTrace feature for log file} either of
- the \texttt{trace} modes (see \cpageref{page:traceswitch}) are active, you will receive
- detailed information in \texttt{indent.log}. You can specify character strings to appear
- before and after the notification of a found code block using, respectively,
+ When \announce{2018-01-13}{showDecorationStartCodeBlockTrace feature for log file} either
+ of the \texttt{trace} modes (see \cpageref{page:traceswitch}) are active, you will
+ receive detailed information in \texttt{indent.log}. You can specify character strings to
+ appear before and after the notification of a found code block using, respectively,
\texttt{showDecorationStartCodeBlockTrace} and
\texttt{showDecorationFinishCodeBlockTrace}. A demonstration is given in
- \vref{app:logfile-demo}.
+ \vref{app:logfile-demo}.%
The log file will end with the characters given in \texttt{endLogFileWith}, and will
report the \texttt{GitHub} address of \texttt{latexindent.pl} to the log file if
\texttt{showGitHubInfoFooter} is set to \texttt{1}.
Note: \texttt{latexindent.pl} no longer uses the \texttt{log4perl} module to handle the
- creation of the logfile.%
- \announce{2021-03-14}*{no longer using log4perl}
+ creation of the logfile. \announce{2021-03-14}*{no longer using log4perl}%
- Some of the options%
- \announce{2021-06-19}*{logFilePreferences updated to include Dumper options} for Perl's
- \texttt{Dumper} module can be specified in \cref{lst:logFilePreferences}; see
- \cite{dumper} and \cite{dumperdemo} for more information. These options will mostly be
- helpful for those calling \texttt{latexindent.pl} with the \texttt{-tt} option described
- in \cref{sec:commandline}.
+ Some of the options \announce{2021-06-19}*{logFilePreferences updated to include Dumper
+ options} for Perl's \texttt{Dumper} module can be specified in
+ \cref{lst:logFilePreferences}; see \cite{dumper} and \cite{dumperdemo} for more
+ information. These options will mostly be helpful for those calling
+ \texttt{latexindent.pl} with the \texttt{-tt} option described in \cref{sec:commandline}.%
\subsection{Verbatim code blocks}
\yamltitle{verbatimEnvironments}*{fields}
A field that contains a list of environments that you would like left completely alone --
no indentation will be performed on environments that you have specified in this field,
- see \cref{lst:verbatimEnvironments}.
- \index{verbatim!environments}
+ see \cref{lst:verbatimEnvironments}. \index{verbatim!environments}
\index{verbatim!commands}
\begin{cmhtcbraster}[raster column skip=.1\linewidth]
@@ -137,8 +133,7 @@ copy myfile.bak4 to myfile.bak3
such as \texttt{lookForAlignDelims} or \texttt{noAdditionalIndent} then
\texttt{latexindent.pl} will \emph{always} prioritize \texttt{verbatimEnvironments}.
- You can, optionally, specify
- \announce{2021-10-30}{verbatim name feature} the
+ You can, optionally, specify \announce{2021-10-30}{verbatim name feature} the
\texttt{verbatim} field using the \texttt{name} field which takes a regular expression as
its argument; thank you to \cite{XuehaiPan} for contributing this feature.
@@ -154,7 +149,7 @@ copy myfile.bak4 to myfile.bak3
With reference to \cref{lst:nameAsRegex2}:
\begin{itemize}
\item the \texttt{name} field as specified here means \emph{any word followed by the word code,
- optionally followed by *};
+ optionally followed by *};
\item we have used \texttt{nameAsRegex} to identify this field, but you can use any description
you like;
\item the \texttt{lookForThis} field is optional, and can take the values 0 (off) or 1 (on); by
@@ -168,13 +163,11 @@ copy myfile.bak4 to myfile.bak3
\vref{sec:modifylinebreaks}).
With reference to \cref{lst:verbatimCommands}, by default \texttt{latexindent.pl} looks
- for
- \lstinline|\verb| immediately followed by another character, and then it takes the
+ for \lstinline|\verb| immediately followed by another character, and then it takes the
body as anything up to the next occurrence of the character; this means that, for
example, \lstinline|\verb!x+3!| is treated as a \texttt{verbatimCommands}.
- You can, optionally, specify
- \announce{2021-10-30}{verbatimCommands name feature} the
+ You can, optionally, specify \announce{2021-10-30}{verbatimCommands name feature} the
\texttt{verbatimCommands} field using the \texttt{name} field which takes a regular
expression as its argument; thank you to \cite{XuehaiPan} for contributing this feature.
@@ -190,7 +183,7 @@ copy myfile.bak4 to myfile.bak3
With reference to \cref{lst:nameAsRegex4}:
\begin{itemize}
\item the \texttt{name} field as specified here means \emph{any word followed by the word
- inline};
+ inline};
\item we have used \texttt{nameAsRegex} to identify this field, but you can use any description
you like;
\item the \texttt{lookForThis} field is optional, and can take the values 0 (off) or 1 (on); by
@@ -214,10 +207,9 @@ copy myfile.bak4 to myfile.bak3
Important note: it is assumed that the \texttt{noindent} block statements specified in
this way appear on their own line.
- 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 use the code in \cref{lst:noIndentBlock1} to demonstrate this
- feature.
+ 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 use the code
+ in \cref{lst:noIndentBlock1} to demonstrate this feature.%
\cmhlistingsfromfile{demonstrations/noindentblock1.tex}{\texttt{noIndentBlock1.tex}}{lst:noIndentBlock1}
@@ -243,10 +235,9 @@ latexindent.pl -l noindent2.yaml noindent1
The \texttt{begin}, \texttt{body} and \texttt{end} fields for \texttt{noIndentBlock} are
all \emph{regular expressions}. If the \texttt{body} field is not specified, then it
- takes a default value of
- \lstinline!.*?! which is written explicitly in \cref{lst:noindent1}. In this
- context, we interpret \lstinline!.*?! in words as \emph{the fewest number of characters
- (possibly none) until the `end' field is reached}.
+ takes a default value of \lstinline!.*?! which is written explicitly in
+ \cref{lst:noindent1}. In this context, we interpret \lstinline!.*?! in words as \emph{the
+ fewest number of characters (possibly none) until the `end' field is reached}.
The \texttt{lookForThis} field is optional, and can take the values 0 (off) or 1 (on); by
default, it is assumed to be 1 (on).
@@ -262,8 +253,7 @@ latexindent.pl -l noindent3.yaml noindent1
We will demonstrate this feature later in the documentation in \cref{lst:href3}.
- You can, optionally, specify
- \announce{2021-10-30}{noIndentBlock name feature} the
+ You can, optionally, specify \announce{2021-10-30}{noIndentBlock name feature} the
\texttt{noIndentBlock} field using the \texttt{name} field which takes a regular
expression as its argument; thank you to \cite{XuehaiPan} for contributing this feature.
@@ -281,7 +271,7 @@ latexindent.pl -l noindent3.yaml noindent1
With reference to \cref{lst:nameAsRegex6}:
\begin{itemize}
\item the \texttt{name} field as specified here means \emph{any word followed by the word
- noindent, optionally followed by *};
+ noindent, optionally followed by *};
\item we have used \texttt{nameAsRegex} to identify this field, but you can use any description
you like;
\item the \texttt{lookForThis} field is optional, and can take the values 0 (off) or 1 (on); by
@@ -359,10 +349,10 @@ removeTrailingWhitespace: 1
\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}.
+ 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}
@@ -370,8 +360,8 @@ removeTrailingWhitespace: 1
\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}
+ \cref{lst:aligndelims:advanced}; we will discuss each in turn. \index{delimiters!advanced
+ settings of lookForAlignDelims}
\begin{yaml}[numbers=none]{\texttt{lookForAlignDelims} (basic)}[width=.8\linewidth,before=\centering]{lst:aligndelims:basic}
lookForAlignDelims:
@@ -401,12 +391,9 @@ lookForAlignDelims:
If, for example, you wish to remove the alignment of the \lstinline!\\! within a
delimiter-aligned block, then the advanced form of \texttt{lookForAlignDelims} shown in
- \cref{lst:aligndelims:advanced} is for you.
- \index{regular expressions!delimiterRegEx}
- \index{regular expressions!ampersand alignment}
- \index{delimiters!default settings of lookForAlignDelims}
- \index{delimiters!ampersand \&}
- \index{delimiters!advanced settings}
+ \cref{lst:aligndelims:advanced} is for you. \index{regular expressions!delimiterRegEx}
+ \index{regular expressions!ampersand alignment} \index{delimiters!default settings of
+ lookForAlignDelims} \index{delimiters!ampersand \&} \index{delimiters!advanced settings}
\index{delimiters!lookForAlignDelims}
\cmhlistingsfromfile[style=lookForAlignDelims]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{lookForAlignDelims} (advanced)}{lst:aligndelims:advanced}
@@ -434,11 +421,14 @@ lookForAlignDelims:
\item \announce{2017-06-19}{alignRowsWithoutMaxDelims} \texttt{alignRowsWithoutMaxDelims}:
binary switch (0 or 1) that details if rows that do not contain the maximum number of
delimeters should be formatted so as to have the ampersands aligned (default: 1);
- \item \announce{2018-01-13}{spacesBeforeAmpersand in ampersand alignment}\texttt{spacesBeforeAmpersand}: optionally specifies the number (integer $\geq$
+ \item \announce{2018-01-13}{spacesBeforeAmpersand in ampersand
+ alignment}\texttt{spacesBeforeAmpersand}: optionally specifies the number (integer $\geq$
0) of spaces to be placed \emph{before} ampersands (default: 1);
- \item \announce{2018-01-13}{spacesAfterAmpersand in ampersand alignment}\texttt{spacesAfterAmpersand}: optionally specifies the number (integer $\geq$
+ \item \announce{2018-01-13}{spacesAfterAmpersand in ampersand
+ alignment}\texttt{spacesAfterAmpersand}: optionally specifies the number (integer $\geq$
0) of spaces to be placed \emph{After} ampersands (default: 1);
- \item \announce{2018-01-13}{justification of cells in ampersand alignment}\texttt{justification}: optionally specifies the justification of each cell as
+ \item \announce{2018-01-13}{justification of cells in ampersand
+ alignment}\texttt{justification}: optionally specifies the justification of each cell as
either \emph{left} or \emph{right} (default: left);
\item \announce{2020-03-21}{align final double back slash}{alignFinalDoubleBackSlash}
optionally specifies if the \emph{final} double back slash should be used for alignment
@@ -494,9 +484,8 @@ lookForAlignDelims:
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/tabular8.yaml}[yaml-TCB]{\texttt{tabular8.yaml}}{lst:tabular8YAML}
\end{minipage}%
- On running the commands
- \index{delimiters!spacing demonstration}
- \index{switches!-l demonstration}
+ On running the commands \index{delimiters!spacing demonstration} \index{switches!-l
+ demonstration}
\begin{commandshell}
latexindent.pl tabular2.tex
latexindent.pl tabular2.tex -l tabular2.yaml
@@ -553,13 +542,12 @@ latexindent.pl tabular2.tex -l tabular2.yaml,tabular8.yaml
\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.
+ 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
@@ -645,13 +633,10 @@ latexindent.pl aligned1.tex -l sba6.yaml
\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
+ We explore \announce{2020-03-21}{alignFinalDoubleBackSlash demonstration} the
\texttt{alignFinalDoubleBackSlash} feature by using the file in \cref{lst:tabular4}. Upon
- running the following commands
- \index{delimiters!double backslash demonstration}
- \index{switches!-y demonstration}
- \index{switches!-o demonstration}
+ running the following commands \index{delimiters!double backslash demonstration}
+ \index{switches!-y demonstration} \index{switches!-o demonstration}%
\begin{commandshell}
latexindent.pl tabular4.tex -o=+-default
latexindent.pl tabular4.tex -o=+-FDBS -y="lookForAlignDelims:tabular:alignFinalDoubleBackSlash:1"
@@ -679,9 +664,8 @@ latexindent.pl tabular4.tex -o=+-FDBS -y="lookForAlignDelims:tabular:alignFinalD
As of Version 3.0, the alignment routine works on mandatory and optional arguments within
commands, and also within `special' code blocks (see \texttt{specialBeginEnd} on
\cpageref{yaml:specialBeginEnd}); for example, assuming that you have a command called
- \lstinline!\matrix! and that it is populated within \texttt{lookForAlignDelims}
- (which it is, by default), and that
- you run the command
+ \lstinline!\matrix! and that it is populated within \texttt{lookForAlignDelims} (which it
+ is, by default), and that you run the command
\begin{commandshell}
latexindent.pl matrix1.tex
\end{commandshell}
@@ -693,14 +677,12 @@ latexindent.pl matrix1.tex
\cmhlistingsfromfile{demonstrations/matrix1-default.tex}{\texttt{matrix1.tex} default output}{lst:matrixafter}
\end{cmhtcbraster}
- If you have blocks of code that you wish to align at the \& character that are
- \emph{not} wrapped in, for example, \lstinline!\begin{tabular}! \ldots
- \lstinline!\end{tabular}!, then you can use the mark up illustrated in
- \cref{lst:alignmentmarkup}; the default output is shown in
- \cref{lst:alignmentmarkup-default}. Note
- that the \lstinline!%*! must be next to each other, but that there can be any number of
- spaces (possibly none) between the
- \lstinline!*! and \lstinline!\begin{tabular}!; note also that you may use any
+ If you have blocks of code that you wish to align at the \& character that are \emph{not}
+ wrapped in, for example, \lstinline!\begin{tabular}! \ldots \lstinline!\end{tabular}!,
+ then you can use the mark up illustrated in \cref{lst:alignmentmarkup}; the default
+ output is shown in \cref{lst:alignmentmarkup-default}. Note that the \lstinline!%*! must
+ be next to each other, but that there can be any number of spaces (possibly none) between
+ the \lstinline!*! and \lstinline!\begin{tabular}!; note also that you may use any
environment name that you have specified in \texttt{lookForAlignDelims}.
\begin{cmhtcbraster}[raster left skip=-1.5cm,]
@@ -713,13 +695,11 @@ latexindent.pl matrix1.tex
these comment-marked blocks are considered \texttt{environments}.
\subsubsection{lookForAlignDelims: the dontMeasure feature}\label{sec:dontMeasure}
- The%
- \announce{2020-03-21}{don't measure feature}
- \texttt{lookForAlignDelims} field can, optionally, receive the \texttt{dontMeasure}
- option which can be specified in a few different ways. We will explore this feature in
- relation to the code given in \cref{lst:tabular-DM}; the default output is shown in
- \cref{lst:tabular-DM-default}.
- \index{delimiters!dontMeasure feature}
+ The \announce{2020-03-21}{don't measure feature} \texttt{lookForAlignDelims} field can,
+ optionally, receive the \texttt{dontMeasure} option which can be specified in a few
+ different ways. We will explore this feature in relation to the code given in
+ \cref{lst:tabular-DM}; the default output is shown in \cref{lst:tabular-DM-default}.
+ \index{delimiters!dontMeasure feature}%
\begin{cmhtcbraster}[raster left skip=-1.5cm,]
\cmhlistingsfromfile{demonstrations/tabular-DM.tex}{\texttt{tabular-DM.tex}}{lst:tabular-DM}
@@ -728,8 +708,7 @@ latexindent.pl matrix1.tex
The \texttt{dontMeasure} field can be specified as \texttt{largest}, and in which case,
the largest element will not be measured; with reference to the YAML file given in
- \cref{lst:dontMeasure1}, we can run the command
- \index{switches!-l demonstration}
+ \cref{lst:dontMeasure1}, we can run the command \index{switches!-l demonstration}
\begin{commandshell}
latexindent.pl tabular-DM.tex -l=dontMeasure1.yaml
\end{commandshell}
@@ -744,13 +723,13 @@ latexindent.pl tabular-DM.tex -l=dontMeasure1.yaml
routine.
The \texttt{dontMeasure} field can also be specified in the form demonstrated in
- \cref{lst:dontMeasure2}. On running the following commands,
- \index{switches!-l demonstration}
+ \cref{lst:dontMeasure2}. On running the following commands, \index{switches!-l
+ demonstration}
\begin{commandshell}
latexindent.pl tabular-DM.tex -l=dontMeasure2.yaml
\end{commandshell}
- we receive the output in \cref{lst:tabular-DM-mod2}.
- \index{regular expressions!dontMeasure feature, cell}
+ we receive the output in \cref{lst:tabular-DM-mod2}. \index{regular
+ expressions!dontMeasure feature, cell}
\begin{cmhtcbraster}
\cmhlistingsfromfile{demonstrations/tabular-DM-mod2.tex}{\texttt{tabular-DM.tex} using \cref{lst:dontMeasure2} or \cref{lst:dontMeasure3}}{lst:tabular-DM-mod2}
@@ -767,8 +746,8 @@ latexindent.pl tabular-DM.tex -l=dontMeasure2.yaml
latexindent.pl tabular-DM.tex -l=dontMeasure3.yaml
latexindent.pl tabular-DM.tex -l=dontMeasure4.yaml
\end{commandshell}
- we receive the output given in \cref{lst:tabular-DM-mod3}
- \index{regular expressions!lowercase alph a-z}
+ we receive the output given in \cref{lst:tabular-DM-mod3} \index{regular
+ expressions!lowercase alph a-z}
\begin{cmhtcbraster}[raster columns=3,
raster left skip=-3.5cm,
raster right skip=-2cm,
@@ -792,8 +771,7 @@ latexindent.pl tabular-DM.tex -l=dontMeasure4.yaml
to be specified.
We may also specify the \texttt{applyTo} field as \texttt{row}, a demonstration of which
- is given in \cref{lst:dontMeasure5}; upon running
- \index{switches!-l demonstration}
+ is given in \cref{lst:dontMeasure5}; upon running \index{switches!-l demonstration}
\begin{commandshell}
latexindent.pl tabular-DM.tex -l=dontMeasure5.yaml
\end{commandshell}
@@ -805,14 +783,12 @@ latexindent.pl tabular-DM.tex -l=dontMeasure5.yaml
Finally, the \texttt{applyTo} field can be specified as \texttt{row}, together with a
\texttt{regex} expression. For example, for the settings given in
- \cref{lst:dontMeasure6}, upon running
- \index{switches!-l demonstration}
+ \cref{lst:dontMeasure6}, upon running \index{switches!-l demonstration}
\begin{commandshell}
latexindent.pl tabular-DM.tex -l=dontMeasure6.yaml
\end{commandshell}
- we receive the output in \cref{lst:tabular-DM-mod6}.
- \index{regular expressions!dontMeasure feature, row}
- \index{regular expressions!lowercase alph a-z}
+ we receive the output in \cref{lst:tabular-DM-mod6}. \index{regular
+ expressions!dontMeasure feature, row} \index{regular expressions!lowercase alph a-z}
\begin{cmhtcbraster}
\cmhlistingsfromfile{demonstrations/tabular-DM-mod6.tex}{\texttt{tabular-DM.tex} using \cref{lst:dontMeasure6}}{lst:tabular-DM-mod6}
@@ -821,17 +797,14 @@ latexindent.pl tabular-DM.tex -l=dontMeasure6.yaml
\subsubsection{lookForAlignDelims: the delimiterRegEx and delimiterJustification feature}\label{sec:delimiter-reg-ex}
- The delimiter alignment%
- \announce{2020-03-21}{delimiterRegEx feature} will, by default, align code blocks at the
- ampersand character. The behaviour is controlled by the \texttt{delimiterRegEx} field
- within \texttt{lookForAlignDelims}; the default value is
+ The delimiter alignment \announce{2020-03-21}{delimiterRegEx feature} will, by default,
+ align code blocks at the ampersand character. The behaviour is controlled by the
+ \texttt{delimiterRegEx} field within \texttt{lookForAlignDelims}; the default value is
\lstinline*'(?<!\\)(&)'*, which can be read as: \emph{an ampersand, as long as it is not
- immediately preceeded by a backslash}.
- \index{warning!capturing parenthesis for lookForAlignDelims}
- \index{capturing parenthesis (regex)}
- \index{regular expressions!capturing parenthesis}
- \index{delimiters!delimiterRegEx}
- \index{delimiters!delimiter justification (left or right)}
+ immediately preceeded by a backslash}. \index{warning!capturing parenthesis for
+ lookForAlignDelims} \index{capturing parenthesis (regex)} \index{regular
+ expressions!capturing parenthesis} \index{delimiters!delimiterRegEx}
+ \index{delimiters!delimiter justification (left or right)}%
\begin{warning}
Important: note the `capturing' parenthesis in the \lstinline!(&)! which are necessary;
@@ -847,15 +820,14 @@ latexindent.pl tabular-DM.tex -l=dontMeasure6.yaml
\cmhlistingsfromfile{demonstrations/tabbing-default.tex}{\texttt{tabbing.tex} default output}{lst:tabbing-default}
\end{cmhtcbraster}
- Let's say that we wish to align the code at either the \lstinline!\=! or
- \lstinline!\>!. We employ the settings given in \cref{lst:delimiterRegEx1} and
- run the command
+ Let's say that we wish to align the code at either the \lstinline!\=! or \lstinline!\>!.
+ We employ the settings given in \cref{lst:delimiterRegEx1} and run the command
\index{switches!-l demonstration}
\begin{commandshell}
latexindent.pl tabbing.tex -l=delimiterRegEx1.yaml
\end{commandshell}
- to receive the output given in \cref{lst:tabbing-mod1}.
- \index{regular expressions!delimiter regex at \textbackslash= or \textbackslash>}
+ to receive the output given in \cref{lst:tabbing-mod1}. \index{regular
+ expressions!delimiter regex at \textbackslash= or \textbackslash>}
\begin{cmhtcbraster}
\cmhlistingsfromfile{demonstrations/tabbing-mod1.tex}{\texttt{tabbing.tex} using \cref{lst:delimiterRegEx1}}{lst:tabbing-mod1}
@@ -875,8 +847,8 @@ latexindent.pl tabbing.tex -l=delimiterRegEx1.yaml
\begin{commandshell}
latexindent.pl tabbing.tex -l=delimiterRegEx2.yaml
\end{commandshell}
- to receive the output given in \cref{lst:tabbing-mod2}.
- \index{regular expressions!delimiter regex at only \textbackslash>}
+ to receive the output given in \cref{lst:tabbing-mod2}. \index{regular
+ expressions!delimiter regex at only \textbackslash>}
\begin{cmhtcbraster}
\cmhlistingsfromfile{demonstrations/tabbing-mod2.tex}{\texttt{tabbing.tex} using \cref{lst:delimiterRegEx2}}{lst:tabbing-mod2}
@@ -887,8 +859,8 @@ latexindent.pl tabbing.tex -l=delimiterRegEx2.yaml
Of course, the other lookForAlignDelims options can be used alongside the
\texttt{delimiterRegEx}; regardless of the type of delimiter being used (ampersand or
anything else), the fields from \vref{lst:aligndelims:advanced} remain the same; for
- example, using the settings in \cref{lst:delimiterRegEx3}, and running
- \index{switches!-l demonstration}
+ example, using the settings in \cref{lst:delimiterRegEx3}, and running \index{switches!-l
+ demonstration}
\begin{commandshell}
latexindent.pl tabbing.tex -l=delimiterRegEx3.yaml
\end{commandshell}
@@ -902,16 +874,14 @@ latexindent.pl tabbing.tex -l=delimiterRegEx3.yaml
It is possible that delimiters specified within \texttt{delimiterRegEx} can be of
different lengths. Consider the file in \cref{lst:tabbing1}, and associated YAML in
\cref{lst:delimiterRegEx4}. Note that the \cref{lst:delimiterRegEx4} specifies the option
- for the delimiter to be either
- \lstinline!#! or
- \lstinline!\>!, \emph{which are different lengths}. Upon running the command
- \index{switches!-l demonstration}
- \index{switches!-o demonstration}
+ for the delimiter to be either \lstinline!#! or \lstinline!\>!, \emph{which are different
+ lengths}. Upon running the command \index{switches!-l demonstration} \index{switches!-o
+ demonstration}
\begin{commandshell}
latexindent.pl tabbing1.tex -l=delimiterRegEx4.yaml -o=+-mod4
\end{commandshell}
- we receive the output in \cref{lst:tabbing1-mod4}.
- \index{regular expressions!delimiter regex at \#}
+ we receive the output in \cref{lst:tabbing1-mod4}. \index{regular expressions!delimiter
+ regex at \#}
\begin{cmhtcbraster}[raster columns=3,
raster left skip=-3.5cm,
@@ -925,14 +895,12 @@ latexindent.pl tabbing1.tex -l=delimiterRegEx4.yaml -o=+-mod4
You can set the \emph{delimiter} justification as either \texttt{left} (default) or
\texttt{right}, which will only have effect when delimiters in the same column have
different lengths. Using the settings in \cref{lst:delimiterRegEx5} and running the
- command
- \index{switches!-l demonstration}
- \index{switches!-o demonstration}
+ command \index{switches!-l demonstration} \index{switches!-o demonstration}
\begin{commandshell}
latexindent.pl tabbing1.tex -l=delimiterRegEx5.yaml -o=+-mod5
\end{commandshell}
- gives the output in \cref{lst:tabbing1-mod5}.
- \index{regular expressions!delimiter regex at \# or \textbackslash>}
+ gives the output in \cref{lst:tabbing1-mod5}. \index{regular expressions!delimiter regex
+ at \# or \textbackslash>}
\begin{cmhtcbraster}
\cmhlistingsfromfile{demonstrations/tabbing1-mod5.tex}{\texttt{tabbing1-mod5.tex}}{lst:tabbing1-mod5}
@@ -940,11 +908,10 @@ latexindent.pl tabbing1.tex -l=delimiterRegEx5.yaml -o=+-mod5
\end{cmhtcbraster}
Note that in \cref{lst:tabbing1-mod5} the second set of delimiters have been \emph{right
- aligned} -- it is quite subtle!
+ aligned} -- it is quite subtle!
\subsubsection{lookForAlignDelims: lookForChildCodeBlocks}\label{sec:lookForChildCodeBlocks}
- There
- \announce{2021-12-13}{lookForChildCodeBlocks demonstration} may be scenarios in
+ There \announce{2021-12-13}{lookForChildCodeBlocks demonstration} may be scenarios in
which you would prefer to instruct \texttt{latexindent.pl} \emph{not} to search for child
blocks; in which case setting \texttt{lookForChildCodeBlocks} to 0 may be a good way to
proceed.
@@ -999,19 +966,16 @@ latexindent.pl tabular-DM-1.tex -l=dontMeasure1a.yaml -o=+-mod1a
\cmhlistingsfromfile[style=itemNames]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{itemNames}}{lst:itemNames}
\yamltitle{specialBeginEnd}*{fields}\label{yaml:specialBeginEnd}
- The fields specified
- \index{specialBeginEnd!introduction}%
+ The fields specified \index{specialBeginEnd!introduction}
\announce{2017-08-21}*{specialBeginEnd} in \texttt{specialBeginEnd} are, in their default
state, focused on math mode begin and end statements, but there is no requirement for
this to be the case; \cref{lst:specialBeginEnd} shows the default settings of
- \texttt{specialBeginEnd}.
- \index{specialBeginEnd!default settings}
+ \texttt{specialBeginEnd}. \index{specialBeginEnd!default settings}%
\cmhlistingsfromfile[style=specialBeginEnd]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{specialBeginEnd}}{lst:specialBeginEnd}
The field \texttt{displayMath} represents \lstinline!\[...\]!, \texttt{inlineMath}
- represents
- \lstinline!$...$! and \texttt{displayMathTex} represents \lstinline!$$...$$!.
+ represents \lstinline!$...$! and \texttt{displayMathTex} represents \lstinline!$$...$$!.
You can, of course, rename these in your own YAML files (see \vref{sec:localsettings});
indeed, you might like to set up your own special begin and end statements.
@@ -1027,12 +991,10 @@ latexindent.pl tabular-DM-1.tex -l=dontMeasure1a.yaml -o=+-mod1a
\texttt{latexindent.pl} will look for this pattern; you can tell \texttt{latexindent.pl}
not to look for the pattern, by setting \texttt{lookForThis} to \texttt{0}.
- There are%
- \announce{2017-08-21}{specialBeforeCommand}
- examples in which it is advantageous to search for \texttt{specialBeginEnd} fields
- \emph{before} searching for commands, and the \texttt{specialBeforeCommand} switch
- controls this behaviour. For example, consider the file shown in
- \cref{lst:specialLRbefore}.
+ There are \announce{2017-08-21}{specialBeforeCommand} examples in which it is
+ advantageous to search for \texttt{specialBeginEnd} fields \emph{before} searching for
+ commands, and the \texttt{specialBeforeCommand} switch controls this behaviour. For
+ example, consider the file shown in \cref{lst:specialLRbefore}.%
\cmhlistingsfromfile{demonstrations/specialLR.tex}{\texttt{specialLR.tex}}{lst:specialLRbefore}
@@ -1045,8 +1007,7 @@ latexindent.pl tabular-DM-1.tex -l=dontMeasure1a.yaml -o=+-mod1a
\cmhlistingsfromfile[]{demonstrations/specialBeforeCommand.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{specialBeforeCommand.yaml}}{lst:specialBeforeCommand-yaml}
\end{cmhtcbraster}
- Upon running the following commands
- \index{switches!-l demonstration}
+ Upon running the following commands \index{switches!-l demonstration}
\begin{widepage}
\begin{commandshell}
latexindent.pl specialLR.tex -l=specialsLeftRight.yaml
@@ -1074,18 +1035,15 @@ latexindent.pl specialLR.tex -l=specialsLeftRight.yaml,specialBeforeCommand.yaml
\texttt{specialBeginEnd} should be sought \emph{before} commands.
\end{itemize}
- You can,optionally, specify%
- \announce{2018-04-27}{update to specialBeginEnd} the \texttt{middle} field for anything that you specify in
- \texttt{specialBeginEnd}. For example, let's consider the \texttt{.tex} file in
- \cref{lst:special2}.
- \index{specialBeginEnd!middle}
- \index{specialBeginEnd!IfElsFi example}
+ You can,optionally, specify \announce{2018-04-27}{update to specialBeginEnd} the
+ \texttt{middle} field for anything that you specify in \texttt{specialBeginEnd}. For
+ example, let's consider the \texttt{.tex} file in \cref{lst:special2}.
+ \index{specialBeginEnd!middle} \index{specialBeginEnd!IfElsFi example}%
\cmhlistingsfromfile{demonstrations/special2.tex}{\texttt{special2.tex}}{lst:special2}
Upon saving the YAML settings in \cref{lst:middle-yaml,lst:middle1-yaml} and running the
- commands
- \index{switches!-l demonstration}
+ commands \index{switches!-l demonstration}
\begin{commandshell}
latexindent.pl special2.tex -l=middle
latexindent.pl special2.tex -l=middle1
@@ -1113,15 +1071,12 @@ latexindent.pl special2.tex -l=middle1
has been indented appropriately in \cref{lst:special2-mod2}.
\end{itemize}
- You may%
- \announce{2018-08-13}{specialBeginEnd verbatim}
- specify fields in \texttt{specialBeginEnd} to be treated as verbatim code blocks by
- changing \texttt{lookForThis} to be \texttt{verbatim}.
- \index{verbatim!specialBeginEnd}
+ You may \announce{2018-08-13}{specialBeginEnd verbatim} specify fields in
+ \texttt{specialBeginEnd} to be treated as verbatim code blocks by changing
+ \texttt{lookForThis} to be \texttt{verbatim}. \index{verbatim!specialBeginEnd}%
For example, beginning with the code in \cref{lst:special3-mod1} and the YAML in
- \cref{lst:special-verb1-yaml}, and running
- \index{switches!-l demonstration}
+ \cref{lst:special-verb1-yaml}, and running \index{switches!-l demonstration}
\begin{commandshell}
latexindent.pl special3.tex -l=special-verb1
\end{commandshell}
@@ -1140,19 +1095,15 @@ latexindent.pl special3.tex -l=special-verb1
Let's assume that our goal is to align the code at the \texttt{edge} and \texttt{node}
text; we employ the code given in \cref{lst:edge-node1} and run the command
- \index{switches!-l demonstration}
- \index{switches!-o demonstration}
+ \index{switches!-l demonstration} \index{switches!-o demonstration}
\begin{commandshell}
latexindent.pl special-align.tex -l edge-node1.yaml -o=+-mod1
\end{commandshell}
- to receive the output in \cref{lst:special-align-mod1}.
- \index{specialBeginEnd!combined with lookForAlignDelims}
- \index{specialBeginEnd!delimiterRegEx}
- \index{specialBeginEnd!alignment at delimiter}
- \index{specialBeginEnd!tikz example}
- \index{regular expressions!delimiter alignment for edge or node}
- \index{delimiters!within specialBeginEnd blocks}
- \index{regular expressions!numeric 0-9}
+ to receive the output in \cref{lst:special-align-mod1}. \index{specialBeginEnd!combined
+ with lookForAlignDelims} \index{specialBeginEnd!delimiterRegEx}
+ \index{specialBeginEnd!alignment at delimiter} \index{specialBeginEnd!tikz example}
+ \index{regular expressions!delimiter alignment for edge or node} \index{delimiters!within
+ specialBeginEnd blocks} \index{regular expressions!numeric 0-9}
\begin{cmhtcbraster}[ raster left skip=-3.5cm,]
\cmhlistingsfromfile{demonstrations/edge-node1.yaml}[yaml-TCB]{\texttt{edge-node1.yaml}}{lst:edge-node1}
@@ -1161,16 +1112,13 @@ latexindent.pl special-align.tex -l edge-node1.yaml -o=+-mod1
The output in \cref{lst:special-align-mod1} is not quite ideal. We can tweak the settings
within \cref{lst:edge-node1} in order to improve the output; in particular, we employ the
- code in \cref{lst:edge-node2} and run the command
- \index{switches!-l demonstration}
- \index{switches!-o demonstration}
- \index{regular expressions!uppercase alph A-Z}
+ code in \cref{lst:edge-node2} and run the command \index{switches!-l demonstration}
+ \index{switches!-o demonstration} \index{regular expressions!uppercase alph A-Z}
\begin{commandshell}
latexindent.pl special-align.tex -l edge-node2.yaml -o=+-mod2
\end{commandshell}
to receive the output in \cref{lst:special-align-mod2}.
- \index{specialBeginEnd!delimiterRegEx tweaked}
- \index{regular expressions!at least one +}
+ \index{specialBeginEnd!delimiterRegEx tweaked} \index{regular expressions!at least one +}
\index{regular expressions!horizontal space \textbackslash{h}}
\begin{cmhtcbraster}[ raster left skip=-3.5cm,]
@@ -1178,17 +1126,16 @@ latexindent.pl special-align.tex -l edge-node2.yaml -o=+-mod2
\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}.
+ 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!,
- \lstinline!\section!, \lstinline!\subsection*!, or indeed any user-specified command
- written in this field.\footnote{There is a slight difference in interface for this field
- when comparing Version 2.2 to Version 3.0; see \vref{app:differences} for details.}
+ commands such as \lstinline!\part!, \lstinline!\chapter!, \lstinline!\section!,
+ \lstinline!\subsection*!, or indeed any user-specified command written in this
+ field.\footnote{There is a slight difference in interface for this field when comparing
+ Version 2.2 to Version 3.0; see \vref{app:differences} for details.}
\cmhlistingsfromfile[style=indentAfterHeadings]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{indentAfterHeadings}}{lst:indentAfterHeadings}
@@ -1202,10 +1149,9 @@ latexindent.pl special-align.tex -l edge-node2.yaml -o=+-mod2
You can add any of your own custom heading commands to this field, specifying the
\texttt{level} as appropriate. You can also specify your own indentation in
\texttt{indentRules} (see \vref{sec:noadd-indent-rules}); you will find the default
- \texttt{indentRules} contains
- \lstinline!chapter: " "! which tells \texttt{latexindent.pl} simply to use a space
- character after \texttt{chapter} headings (once \texttt{indent} is set to \texttt{1} for
- \texttt{chapter}).
+ \texttt{indentRules} contains \lstinline!chapter: " "! which tells
+ \texttt{latexindent.pl} simply to use a space character after \texttt{chapter} headings
+ (once \texttt{indent} is set to \texttt{1} for \texttt{chapter}).
For example, assuming that you have the code in \cref{lst:headings1yaml} saved into
\texttt{headings1.yaml}, and that you have the text from \cref{lst:headings1} saved into
@@ -1216,8 +1162,7 @@ latexindent.pl special-align.tex -l edge-node2.yaml -o=+-mod2
\cmhlistingsfromfile{demonstrations/headings1.tex}{\texttt{headings1.tex}}{lst:headings1}
\end{cmhtcbraster}
- If you run the command
- \index{switches!-l demonstration}
+ If you run the command \index{switches!-l demonstration}
\begin{commandshell}
latexindent.pl headings1.tex -l=headings1.yaml
\end{commandshell}
@@ -1232,8 +1177,8 @@ latexindent.pl headings1.tex -l=headings1.yaml
\end{minipage}
Now say that you modify the \texttt{YAML} from \cref{lst:headings1yaml} so that the
- \texttt{paragraph} \texttt{level} is \texttt{1}; after running
- \index{switches!-l demonstration}
+ \texttt{paragraph} \texttt{level} is \texttt{1}; after running \index{switches!-l
+ demonstration}
\begin{commandshell}
latexindent.pl headings1.tex -l=headings1.yaml
\end{commandshell}
@@ -1243,12 +1188,10 @@ latexindent.pl headings1.tex -l=headings1.yaml
\index{indentation!maximum indetation}
\yamltitle{maximumIndentation}*{horizontal space}
- You can control the maximum indentation given to your file
- by%
- \announce{2017-08-21}{maximumIndentation} specifying
- the \texttt{maximumIndentation} field as horizontal space (but \emph{not} including
- tabs). This feature uses the \texttt{Text::Tabs} module \cite{texttabs}, and is
- \emph{off} by default.
+ You can control the maximum indentation given to your file by
+ \announce{2017-08-21}{maximumIndentation} specifying the \texttt{maximumIndentation}
+ field as horizontal space (but \emph{not} including tabs). This feature uses the
+ \texttt{Text::Tabs} module \cite{texttabs}, and is \emph{off} by default.%
For example, consider the example shown in \cref{lst:mult-nested} together with the
default output shown in \cref{lst:mult-nested-default}.
@@ -1282,10 +1225,8 @@ latexindent.pl mult-nested.tex -l=max-indentation1
\subsection{The code blocks known latexindent.pl}\label{subsubsec:code-blocks}
As of Version 3.0, \texttt{latexindent.pl} processes documents using code blocks; each of
- these are shown in \cref{tab:code-blocks}.
- \index{regular expressions!uppercase alph A-Z}
- \index{regular expressions!lowercase alph a-z}
- \index{regular expressions!numeric 0-9}
+ these are shown in \cref{tab:code-blocks}. \index{regular expressions!uppercase alph A-Z}
+ \index{regular expressions!lowercase alph a-z} \index{regular expressions!numeric 0-9}
\index{regular expressions!horizontal space \textbackslash{h}}
\begin{table}[!htp]
@@ -1359,7 +1300,6 @@ mand arg text
\end{widepage}
\end{table}
- We will refer to these code blocks in what follows.%
- \announce{2019-07-13}{fine tuning of code blocks} Note that the fine tuning of the
- definition of the code blocks detailed in \cref{tab:code-blocks} is discussed in
- \vref{sec:finetuning}.
+ We will refer to these code blocks in what follows. \announce{2019-07-13}{fine tuning of
+ code blocks} Note that the fine tuning of the definition of the code blocks detailed in
+ \cref{tab:code-blocks} is discussed in \vref{sec:finetuning}.%
diff --git a/support/latexindent/documentation/sec-fine-tuning.tex b/support/latexindent/documentation/sec-fine-tuning.tex
index 0a0739adc8..352040cc7f 100644
--- a/support/latexindent/documentation/sec-fine-tuning.tex
+++ b/support/latexindent/documentation/sec-fine-tuning.tex
@@ -7,22 +7,16 @@
\cref{lst:fineTuning}.
This field is for those that would like to peek under the bonnet/hood and make some fine
- tuning to \texttt{latexindent.pl}'s operating.
- \index{warning!fine tuning}
- \index{regular expressions!fine tuning}
- \index{regular expressions!environments}
- \index{regular expressions!ifElseFi}
- \index{regular expressions!commands}
- \index{regular expressions!keyEqualsValuesBracesBrackets}
- \index{regular expressions!NamedGroupingBracesBrackets}
- \index{regular expressions!UnNamedGroupingBracesBrackets}
- \index{regular expressions!arguments}
- \index{regular expressions!modifyLineBreaks}
- \index{regular expressions!lowercase alph a-z}
- \index{regular expressions!uppercase alph A-Z}
- \index{regular expressions!numeric 0-9}
- \index{regular expressions!at least one +}
- \index{regular expressions!horizontal space \textbackslash{h}}
+ tuning to \texttt{latexindent.pl}'s operating. \index{warning!fine tuning} \index{regular
+ expressions!fine tuning} \index{regular expressions!environments} \index{regular
+ expressions!ifElseFi} \index{regular expressions!commands} \index{regular
+ expressions!keyEqualsValuesBracesBrackets} \index{regular
+ expressions!NamedGroupingBracesBrackets} \index{regular
+ expressions!UnNamedGroupingBracesBrackets} \index{regular expressions!arguments}
+ \index{regular expressions!modifyLineBreaks} \index{regular expressions!lowercase alph
+ a-z} \index{regular expressions!uppercase alph A-Z} \index{regular expressions!numeric
+ 0-9} \index{regular expressions!at least one +} \index{regular expressions!horizontal
+ space \textbackslash{h}}
\begin{warning}
Making changes to the fine tuning may have significant consequences for your indentation
@@ -64,18 +58,15 @@
\item the \texttt{keyEqualsValuesBracesBrackets} contains some interesting syntax:
\begin{enumerate}
\item \lstinline!|! means `or'
- \item \lstinline^(?:(?<!\\)\{)^ the \lstinline^(?:...)^ uses a \emph{non-capturing} group --
- you don't necessarily need to worry about what this means, but just know that for the
- \texttt{fineTuning} feature you should only ever use \emph{non}-capturing groups, and
- \emph{not} capturing groups, which are simply
+ \item \lstinline^(?:(?<!\\)\{)^ the \lstinline^(?:...)^ uses a \emph{non-capturing} group -- you don't necessarily need to worry about what this
+ means, but just know that for the \texttt{fineTuning} feature you should only ever use
+ \emph{non}-capturing groups, and \emph{not} capturing groups, which are simply
\lstinline!(...)!
- \item \lstinline^(?<!\\)\{)^ means a \lstinline^{^ but it can \emph{not}
- be immediately preceded by a \lstinline!\!
+ \item \lstinline^(?<!\\)\{)^ means a \lstinline^{^ but it can \emph{not} be immediately preceded by a \lstinline!\!
\end{enumerate}
\item in the \texttt{arguments:before} field
\begin{enumerate}
- \item \lstinline^\d\h*^ means a digit (i.e. a number), followed by 0 or more horizontal
- spaces
+ \item \lstinline^\d\h*^ means a digit (i.e. a number), followed by 0 or more horizontal spaces
\item \lstinline^;?,?^ means \emph{possibly} a semi-colon, and possibly a comma
\item \lstinline^\<.*?\>^ is designed for 'beamer'-type commands; the
\lstinline^.*?^ means anything in between \lstinline^<...>^
@@ -117,10 +108,10 @@ latexindent.pl finetuning1.tex
\cmhlistingsfromfile{demonstrations/finetuning1-default.tex}{\texttt{finetuning1.tex} default}{lst:finetuning1-default}
\end{cmhtcbraster}
- It's clear from \cref{lst:finetuning1-default} that the indentation scheme has not worked as
- expected. We can \emph{fine tune} the indentation scheme by employing the settings
- given in \cref{lst:fine-tuning1} and running the command
- \index{switches!-l demonstration}
+ It's clear from \cref{lst:finetuning1-default} that the indentation scheme has not worked
+ as expected. We can \emph{fine tune} the indentation scheme by employing the settings
+ given in \cref{lst:fine-tuning1} and running the command \index{switches!-l
+ demonstration}
\begin{commandshell}
latexindent.pl finetuning1.tex -l=fine-tuning1.yaml
\end{commandshell}
@@ -134,8 +125,8 @@ latexindent.pl finetuning1.tex -l=fine-tuning1.yaml
\end{example}
\begin{example}
- Let's have another demonstration; consider the file given in \cref{lst:finetuning2}, together with its
- default output using the command
+ Let's have another demonstration; consider the file given in \cref{lst:finetuning2},
+ together with its default output using the command
\begin{commandshell}
latexindent.pl finetuning2.tex
\end{commandshell}
@@ -148,10 +139,10 @@ latexindent.pl finetuning2.tex
\cmhlistingsfromfile{demonstrations/finetuning2-default.tex}{\texttt{finetuning2.tex} default}{lst:finetuning2-default}
\end{cmhtcbraster}
- It's clear from \cref{lst:finetuning2-default} that the indentation scheme has not worked as
- expected. We can \emph{fine tune} the indentation scheme by employing the settings
- given in \cref{lst:fine-tuning2} and running the command
- \index{switches!-l demonstration}
+ It's clear from \cref{lst:finetuning2-default} that the indentation scheme has not worked
+ as expected. We can \emph{fine tune} the indentation scheme by employing the settings
+ given in \cref{lst:fine-tuning2} and running the command \index{switches!-l
+ demonstration}
\begin{commandshell}
latexindent.pl finetuning2.tex -l=fine-tuning2.yaml
\end{commandshell}
@@ -164,13 +155,15 @@ latexindent.pl finetuning2.tex -l=fine-tuning2.yaml
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/fine-tuning2.yaml}[yaml-TCB]{\texttt{finetuning2.yaml}}{lst:fine-tuning2}
\end{cmhtcbraster}
- In particular, note that the settings in \cref{lst:fine-tuning2} specify that \texttt{NamedGroupingBracesBrackets}
- and \texttt{UnNamedGroupingBracesBrackets} can follow \texttt{"} and that we allow \lstinline!---! between arguments.
+ In particular, note that the settings in \cref{lst:fine-tuning2} specify that
+ \texttt{NamedGroupingBracesBrackets} and \texttt{UnNamedGroupingBracesBrackets} can
+ follow \texttt{"} and that we allow \lstinline!---! between arguments.
\end{example}
\begin{example}
- You can tweak the \texttt{fineTuning} using the \texttt{-y} switch, but to be sure to use quotes appropriately.
- For example, starting with the code in \cref{lst:finetuning3} and running the following command
+ You can tweak the \texttt{fineTuning} using the \texttt{-y} switch, but to be sure to use
+ quotes appropriately. For example, starting with the code in \cref{lst:finetuning3} and
+ running the following command
\begin{commandshell}
latexindent.pl -m -y='modifyLineBreaks:oneSentencePerLine:manipulateSentences: 1, modifyLineBreaks:oneSentencePerLine:sentencesBeginWith:a-z: 1, fineTuning:modifyLineBreaks:betterFullStop: "(?:\.|;|:(?![a-z]))|(?:(?<!(?:(?:e\.g)|(?:i\.e)|(?:etc))))\.(?!(?:[a-z]|[A-Z]|\-|~|\,|[0-9]))"' issue-243.tex -o=+-mod1
\end{commandshell}
@@ -181,8 +174,8 @@ latexindent.pl -m -y='modifyLineBreaks:oneSentencePerLine:manipulateSentences: 1
\end{example}
\begin{example}
- We can tweak the \texttt{fineTuning} for how trailing comments are classified. For motivation, let's consider
- the code given in \cref{lst:finetuning4}
+ We can tweak the \texttt{fineTuning} for how trailing comments are classified. For
+ motivation, let's consider the code given in \cref{lst:finetuning4}
\cmhlistingsfromfile{demonstrations/finetuning4.tex}{\texttt{finetuning4.tex}}{lst:finetuning4}
@@ -220,30 +213,27 @@ latexindent.pl -m finetuning4.tex -o=+-mod2 -l=href2
desirable.
\end{itemize}
- Another approach to this situation, which does not use \texttt{fineTuning}, is to use \texttt{noIndentBlock}
- which we discussed in \vref{lst:noIndentBlock};
- using the settings in \cref{lst:href3} and running the command
+ Another approach to this situation, which does not use \texttt{fineTuning}, is to use
+ \texttt{noIndentBlock} which we discussed in \vref{lst:noIndentBlock}; using the settings
+ in \cref{lst:href3} and running the command
\begin{commandshell}
latexindent.pl -m finetuning4.tex -o=+-mod3 -l=href3
\end{commandshell}
- then we receive the same output given in \cref{lst:finetuning4-mod2}; see also \texttt{paragraphsStopAt}
- in \vref{lst:paragraphsStopAt}.
+ then we receive the same output given in \cref{lst:finetuning4-mod2}.
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/href3.yaml}[MLB-TCB]{\texttt{href3.yaml}}{lst:href3}
- With reference to the \texttt{body} field in \cref{lst:href3}, we note that the \texttt{body} field can
- be interpreted as: the fewest number of zero or more characters that are not right braces. This
- is an example of character class.
- \index{regular expressions!character class demonstration}
+ With reference to the \texttt{body} field in \cref{lst:href3}, we note that the
+ \texttt{body} field can be interpreted as: the fewest number of zero or more characters
+ that are not right braces. This is an example of character class. \index{regular
+ expressions!character class demonstration}
\end{example}
\begin{example}
- We can use the \texttt{fineTuning} field to assist in the formatting of bibliography files.
- \index{bibliography files}
- \index{regular expressions!delimiterRegEx}
- \index{regular expressions!capturing parenthesis}
- \index{regular expressions!ampersand alignment}
- \index{delimiters!delimiterRegEx}
+ We can use the \texttt{fineTuning} field to assist in the formatting of bibliography
+ files. \index{bibliography files} \index{regular expressions!delimiterRegEx}
+ \index{regular expressions!capturing parenthesis} \index{regular expressions!ampersand
+ alignment} \index{delimiters!delimiterRegEx}
Starting with the file in \cref{lst:bib1} and running the command
\begin{commandshell}
@@ -258,8 +248,8 @@ latexindent.pl bib1.tex -o=+-mod1
\end{cmhtcbraster}
\end{widepage}
- Let's assume that we would like to format the output so as to align the \texttt{=} symbols.
- Using the settings in \cref{lst:bibsettings1} and running the command
+ Let's assume that we would like to format the output so as to align the \texttt{=}
+ symbols. Using the settings in \cref{lst:bibsettings1} and running the command
\begin{commandshell}
latexindent.pl bib1.bib -l bibsettings1.yaml -o=+-mod2
\end{commandshell}
@@ -286,7 +276,8 @@ latexindent.pl bib1.bib -l bibsettings1.yaml -o=+-mod2
\end{example}
\begin{example}
- We can build upon \cref{lst:bibsettings1} for slightly more complicated bibliography files.
+ We can build upon \cref{lst:bibsettings1} for slightly more complicated bibliography
+ files.
Starting with the file in \cref{lst:bib2} and running the command
\begin{commandshell}
@@ -314,6 +305,7 @@ latexindent.pl bib2.bib -l bibsettings1.yaml,bibsettings2.yaml -o=+-mod2
\cmhlistingsfromfile{demonstrations/bib2-mod2.bib}{\texttt{bib2-mod2.bib}}{lst:bib2-mod2}
- With reference to \cref{lst:bibsettings2} we note that the \texttt{delimiterRegEx} has been adjusted so that \texttt{=} symbols are used as the delimiter,
- but only when they are \emph{not preceeded} by either \texttt{v} or \texttt{spfreload}.
+ With reference to \cref{lst:bibsettings2} we note that the \texttt{delimiterRegEx} has
+ been adjusted so that \texttt{=} symbols are used as the delimiter, but only when they
+ are \emph{not preceeded} by either \texttt{v} or \texttt{spfreload}.
\end{example}
diff --git a/support/latexindent/documentation/sec-how-to-use.tex b/support/latexindent/documentation/sec-how-to-use.tex
index f5c7907729..944a38292c 100644
--- a/support/latexindent/documentation/sec-how-to-use.tex
+++ b/support/latexindent/documentation/sec-how-to-use.tex
@@ -25,8 +25,7 @@
\texttt{latexindent.pl}.
MiKTeX users on Windows may like to see \cite{miktex-guide} for details of how to use
- \texttt{latexindent.exe} without a Perl installation.
- \index{MiKTeX}
+ \texttt{latexindent.exe} without a Perl installation. \index{MiKTeX}
\index{latexindent.exe}
\subsection{From the command line}\label{sec:commandline}
@@ -105,7 +104,7 @@ latexindent.pl --outputfile output.tex myfile.tex
This will indent \texttt{myfile.tex} and output it to \texttt{output.tex}, overwriting it
(\texttt{output.tex}) if it already exists\footnote{Users of version 2.* should note the
- subtle change in syntax}. Note that if \texttt{latexindent.pl} is called with both the
+ subtle change in syntax}. Note that if \texttt{latexindent.pl} is called with both the
\texttt{-w} and \texttt{-o} switches, then \texttt{-w} will be ignored and \texttt{-o}
will take priority (this seems safer than the other way round).
@@ -115,31 +114,27 @@ latexindent.pl myfile.tex > output.tex
\end{commandshell}
You can call the \texttt{-o} switch with the name of the output file \emph{without} an
- extension; in%
- \announce{2017-06-25}{upgrade to -o switch}
- this case, \texttt{latexindent.pl} will use the extension from the original file. For
- example, the following two calls to \texttt{latexindent.pl} are equivalent:
+ extension; in \announce{2017-06-25}{upgrade to -o switch} this case,
+ \texttt{latexindent.pl} will use the extension from the original file. For example, the
+ following two calls to \texttt{latexindent.pl} are equivalent:%
\begin{commandshell}
latexindent.pl myfile.tex -o=output
latexindent.pl myfile.tex -o=output.tex
\end{commandshell}
- You can call the \texttt{-o} switch using a \texttt{+} symbol at the beginning; this
- will%
- \announce{2017-06-25}{+ sign in o switch}
- concatenate the name of the input file and the text given to the \texttt{-o} switch. For
- example, the following two calls to \texttt{latexindent.pl} are equivalent:
+ You can call the \texttt{-o} switch using a \texttt{+} symbol at the beginning; this will
+ \announce{2017-06-25}{+ sign in o switch} concatenate the name of the input file and the
+ text given to the \texttt{-o} switch. For example, the following two calls to
+ \texttt{latexindent.pl} are equivalent:%
\begin{commandshell}
latexindent.pl myfile.tex -o=+new
latexindent.pl myfile.tex -o=myfilenew.tex
\end{commandshell}
- You can call the \texttt{-o} switch using a \texttt{++} symbol at the end of the
- name%
- \announce{2017-06-25}{++ in o switch} of your output
- file; this tells \texttt{latexindent.pl} to search successively for the name of your
- output file concatenated with $0, 1, \ldots$ while the name of the output file exists.
- For example,
+ You can call the \texttt{-o} switch using a \texttt{++} symbol at the end of the name
+ \announce{2017-06-25}{++ in o switch} of your output file; this tells
+ \texttt{latexindent.pl} to search successively for the name of your output file
+ concatenated with $0, 1, \ldots$ while the name of the output file exists. For example,%
\begin{commandshell}
latexindent.pl myfile.tex -o=output++
\end{commandshell}
@@ -168,9 +163,8 @@ latexindent.pl myfile.tex -o=+out++.tex
\end{commandshell}
See \vref{app:differences} for details of how the interface has changed from Version 2.2
- to Version 3.0 for this flag.
-\flagbox{-s, --silent}
- \index{switches!-s, --silent definition and details}
+ to Version 3.0 for this flag. \flagbox{-s, --silent} \index{switches!-s, --silent
+ definition and details}
\begin{commandshell}
latexindent.pl -s myfile.tex
latexindent.pl myfile.tex -s
@@ -223,17 +217,15 @@ latexindent.pl myfile.tex -l=first.yaml,second.yaml,third.yaml
\vref{sec:localsettings}) in the current working directory, then
these%
\announce{2021-03-14}*{-l switch: localSettings and
- friends} settings will be added to the indentation scheme. Information will be given in
+ friends} settings will be added to the indentation scheme. Information will be given in
\texttt{indent.log} on the success or failure of loading \texttt{localSettings.yaml}.
The \texttt{-l} flag can take an \emph{optional} parameter which details the name (or
names separated by commas) of a YAML file(s) that resides in the same directory as
\texttt{myfile.tex}; you can use this option if you would like to load a settings file in
- the current working directory that is \emph{not} called
- \texttt{localSettings.yaml}.%
- \announce{2017-08-21}*{-l
- switch absolute paths} In fact, you can specify both \emph{relative} and \emph{absolute
- paths} for your YAML files; for example
+ the current working directory that is \emph{not} called \texttt{localSettings.yaml}.
+ \announce{2017-08-21}*{-l switch absolute paths} In fact, you can specify both
+ \emph{relative} and \emph{absolute paths} for your YAML files; for example%
\begin{commandshell}
latexindent.pl -l=../../myyaml.yaml myfile.tex
latexindent.pl -l=/home/cmhughes/Desktop/myyaml.yaml myfile.tex
@@ -267,9 +259,8 @@ latexindent.pl -l + myyaml.yaml myfile.tex
ignored. If you wish to use spaces between any of the YAML settings, then you must wrap
the entire list of YAML files in quotes, as demonstrated above.
- You may also choose to omit the \texttt{yaml} extension, such
- as%
- \announce{2017-06-25}{no extension for -l switch}
+ You may also choose to omit the \texttt{yaml} extension, such as \announce{2017-06-25}{no
+ extension for -l switch}%
\begin{commandshell}
latexindent.pl -l=localSettings,myyaml myfile.tex
\end{commandshell}
@@ -292,9 +283,8 @@ latexindent.pl myfile.tex -y='modifyLineBreaks:environments:one:EndStartsOnOwnLi
demonstrated in \vref{sec:yamlswitch}.
Any settings specified via this switch will be loaded \emph{after} any specified using
- the \texttt{-l} switch. This is discussed further in \vref{sec:loadorder}.
-\flagbox{-d, --onlydefault}
- \index{switches!-d, --onlydefault definition and details}
+ the \texttt{-l} switch. This is discussed further in \vref{sec:loadorder}. \flagbox{-d,
+ --onlydefault} \index{switches!-d, --onlydefault definition and details}
\begin{commandshell}
latexindent.pl -d myfile.tex
\end{commandshell}
@@ -306,8 +296,8 @@ latexindent.pl -d myfile.tex
\texttt{indentconfig.yaml} or \texttt{.indentconfig.yaml}) you can simply call the script
with the \texttt{-d} switch; note that this will also tell the script to ignore
\texttt{localSettings.yaml} even if it has been called with the \texttt{-l} switch;
- \texttt{latexindent.pl}%
- \announce{2017-08-21}*{updated -d switch} will also ignore any settings specified from the \texttt{-y} switch.
+ \texttt{latexindent.pl} \announce{2017-08-21}*{updated -d switch} will also ignore any
+ settings specified from the \texttt{-y} switch.%
\flagbox{-c, --cruft=<directory>}
\index{switches!-c, --cruft definition and details}
@@ -345,9 +335,9 @@ latexindent.pl -g /dev/null myfile.tex
latexindent.pl -sl myfile.tex
latexindent.pl -screenlog myfile.tex
\end{commandshell}
- Using this%
- \announce{2018-01-13}{screenlog switch created} option tells \texttt{latexindent.pl} to output the log file to the screen, as
- well as to your chosen log file.
+ Using this \announce{2018-01-13}{screenlog switch created} option tells
+ \texttt{latexindent.pl} to output the log file to the screen, as well as to your chosen
+ log file.%
\flagbox{-m, --modifylinebreaks}
\index{switches!-m, --modifylinebreaks definition and details}
@@ -365,8 +355,7 @@ latexindent.pl -modifylinebreaks myfile.tex
latexindent.pl myfile
\end{commandshell}
and in which case, you can specify the order in which extensions are searched for; see
- \vref{lst:fileExtensionPreference} for full details.
-\flagbox{STDIN}
+ \vref{lst:fileExtensionPreference} for full details. \flagbox{STDIN}
\begin{commandshell}
cat myfile.tex | latexindent.pl
cat myfile.tex | latexindent.pl -
@@ -383,9 +372,9 @@ cat myfile.tex | latexindent.pl -
cat myfile.tex | latexindent.pl -l=mysettings.yaml -
\end{commandshell}
- Similarly, if you%
- \announce{2018-01-13}*{no options/filename updated} simply type \texttt{latexindent.pl} at the command line, then
- it will expect (STDIN) input from the command line.
+ Similarly, if you \announce{2018-01-13}*{no options/filename updated} simply type
+ \texttt{latexindent.pl} at the command line, then it will expect (STDIN) input from the
+ command line.%
\begin{commandshell}
latexindent.pl
\end{commandshell}
@@ -403,12 +392,10 @@ latexindent.pl
latexindent.pl -r myfile.tex
latexindent.pl -replacement myfile.tex
\end{commandshell}
- You can%
- \announce{2019-07-13}{replacement mode switch}
- call \texttt{latexindent.pl} with the \texttt{-r} switch to instruct it to perform
- replacements/substitutions on your file; full details and examples are given in
- \vref{sec:replacements}.
- \index{verbatim!rv, replacementrespectverb switch}
+ You can \announce{2019-07-13}{replacement mode switch} call \texttt{latexindent.pl} with
+ the \texttt{-r} switch to instruct it to perform replacements/substitutions on your file;
+ full details and examples are given in \vref{sec:replacements}. \index{verbatim!rv,
+ replacementrespectverb switch}%
\flagbox{-rv, --replacementrespectverb}
\index{switches!-rv, --replacementrespectverb definition and details}
@@ -416,10 +403,10 @@ latexindent.pl -replacement myfile.tex
latexindent.pl -rv myfile.tex
latexindent.pl -replacementrespectverb myfile.tex
\end{commandshell}
- You can%
- \announce{2019-07-13}{replacement mode switch, respecting verbatim} instruct \texttt{latexindent.pl} to perform
- replacements/substitutions by using the \texttt{-rv} switch, but will \emph{respect
- verbatim code blocks}; full details and examples are given in \vref{sec:replacements}.
+ You can \announce{2019-07-13}{replacement mode switch, respecting verbatim} instruct
+ \texttt{latexindent.pl} to perform replacements/substitutions by using the \texttt{-rv}
+ switch, but will \emph{respect verbatim code blocks}; full details and examples are given
+ in \vref{sec:replacements}.%
\flagbox{-rr, --onlyreplacement}
\index{switches!-rr, --onlyreplacement definition and details}
@@ -427,10 +414,10 @@ latexindent.pl -replacementrespectverb myfile.tex
latexindent.pl -rr myfile.tex
latexindent.pl -onlyreplacement myfile.tex
\end{commandshell}
- You can%
- \announce{2019-07-13}{replacement (only) mode switch} instruct \texttt{latexindent.pl} to skip all of its other indentation operations
- and \emph{only} perform replacements/substitutions by using the \texttt{-rr} switch; full
- details and examples are given in \vref{sec:replacements}.
+ You can \announce{2019-07-13}{replacement (only) mode switch} instruct
+ \texttt{latexindent.pl} to skip all of its other indentation operations and \emph{only}
+ perform replacements/substitutions by using the \texttt{-rr} switch; full details and
+ examples are given in \vref{sec:replacements}.%
\flagbox{-k, --check}
\index{switches!-k, --check definition and details}
@@ -438,13 +425,10 @@ latexindent.pl -onlyreplacement myfile.tex
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.
+ 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
+ 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
diff --git a/support/latexindent/documentation/sec-indent-config-and-settings.tex b/support/latexindent/documentation/sec-indent-config-and-settings.tex
index 9c7eed4f95..b25cc70b7b 100644
--- a/support/latexindent/documentation/sec-indent-config-and-settings.tex
+++ b/support/latexindent/documentation/sec-indent-config-and-settings.tex
@@ -20,8 +20,8 @@
For Mac and Linux users, their home directory is \texttt{~/username} while Windows (Vista
onwards) is \lstinline!C:\Users\username!\footnote{If you're not sure where to put
- \texttt{indentconfig.yaml}, don't worry \texttt{latexindent.pl} will tell you in the log
- file exactly where to put it assuming it doesn't exist already.} \Cref{lst:indentconfig}
+ \texttt{indentconfig.yaml}, don't worry \texttt{latexindent.pl} will tell you in the log
+ file exactly where to put it assuming it doesn't exist already.} \Cref{lst:indentconfig}
shows a sample \texttt{indentconfig.yaml} file.
\begin{yaml}{\texttt{indentconfig.yaml} (sample)}{lst:indentconfig}
@@ -51,8 +51,8 @@ paths:
at \cref{lst:mysettings} for an example that uses four tabs for the default indent, adds
the \texttt{tabbing} environment/command to the list of environments that contains
alignment delimiters; you might also like to refer to the many YAML files detailed
- throughout the rest of this documentation.
- \index{indentation!defaultIndent using YAML file}
+ throughout the rest of this documentation. \index{indentation!defaultIndent using YAML
+ file}
\begin{yaml}{\texttt{mysettings.yaml} (example)}{lst:mysettings}
# Default value of indentation
@@ -68,8 +68,7 @@ lookForAlignDelims:
details -- if you have specified a path that \texttt{latexindent.pl} doesn't recognise
then you'll get a warning, otherwise you'll get confirmation that \texttt{latexindent.pl}
has read your settings file \footnote{Windows users may find that they have to end
- \texttt{.yaml} files with a blank line}.
- \index{warning!editing YAML files}
+ \texttt{.yaml} files with a blank line}. \index{warning!editing YAML files}
\begin{warning}
When editing \texttt{.yaml} files it is \emph{extremely} important to remember how
@@ -81,12 +80,11 @@ lookForAlignDelims:
\texttt{indent.log}.
\end{warning}
- If you find that%
- \announce{2021-06-19}{encoding option for indentconfig.yaml} \texttt{latexindent.pl} does not read your YAML file, then it
- might be as a result of the default commandline encoding not being UTF-8; normally this
- will only occcur for Windows users. In this case, you might like to explore the
- \texttt{encoding} option for \texttt{indentconfig.yaml} as demonstrated in
- \cref{lst:indentconfig-encoding}.
+ If you find that \announce{2021-06-19}{encoding option for indentconfig.yaml}
+ \texttt{latexindent.pl} does not read your YAML file, then it might be as a result of the
+ default commandline encoding not being UTF-8; normally this will only occcur for Windows
+ users. In this case, you might like to explore the \texttt{encoding} option for
+ \texttt{indentconfig.yaml} as demonstrated in \cref{lst:indentconfig-encoding}.%
\cmhlistingsfromfile{demonstrations/encoding.yaml}[yaml-TCB]{The \texttt{encoding} option for \texttt{indentconfig.yaml}}{lst:indentconfig-encoding}
@@ -98,7 +96,7 @@ lookForAlignDelims:
\texttt{localSettings.yaml} and/or friends in the \emph{same directory} as
\texttt{myfile.tex}. For%
\announce{2021-03-14}*{-l
- switch: localSettings and friends} example, if you use the following command
+ switch: localSettings and friends} example, if you use the following command
\index{switches!-l demonstration}
\begin{commandshell}
latexindent.pl -l myfile.tex
@@ -130,8 +128,7 @@ latexindent.pl -l=mysettings.yaml myfile.tex
Your settings file can contain any switches that you'd like to change; a sample is shown
in \cref{lst:localSettings}, and you'll find plenty of further examples throughout this
- manual.
- \index{verbatim!verbatimEnvironments demonstration (-l switch)}
+ manual. \index{verbatim!verbatimEnvironments demonstration (-l switch)}
\begin{yaml}{\texttt{localSettings.yaml} (example)}{lst:localSettings}
# verbatim environments - environments specified
@@ -156,15 +153,14 @@ verbatimEnvironments:
latexindent.pl -y="verbatimEnvironments:cmhenvironment:0;myenv:1" myfile.tex
\end{commandshell}
Note the use of \texttt{;} to specify another field within \texttt{verbatimEnvironments}.
- This is shorthand, and equivalent, to using the following command:
- \index{switches!-y demonstration}
+ This is shorthand, and equivalent, to using the following command: \index{switches!-y
+ demonstration}
\begin{commandshell}
latexindent.pl -y="verbatimEnvironments:cmhenvironment:0,verbatimEnvironments:myenv:1" myfile.tex
\end{commandshell}
You may, of course, specify settings using the \texttt{-y} switch as well as, for
- example, settings loaded using the \texttt{-l} switch; for example,
- \index{switches!-l demonstration}
- \index{switches!-y demonstration}
+ example, settings loaded using the \texttt{-l} switch; for example, \index{switches!-l
+ demonstration} \index{switches!-y demonstration}
\begin{commandshell}
latexindent.pl -l=mysettings.yaml -y="verbatimEnvironments:cmhenvironment:0;myenv:1" myfile.tex
\end{commandshell}
@@ -195,9 +191,8 @@ latexindent.pl -m --yaml='modifyLineBreaks:oneSentencePerLine:sentencesEndWith:o
specify both relative and absolute%
\announce{2017-08-21}*{-l absolute paths} paths to other YAML files using the \texttt{-l}
switch, separating multiple files using commas;
- \item any settings%
- \announce{2017-08-21}{-y switch load order}
- specified in the \texttt{-y} switch.
+ \item any settings \announce{2017-08-21}{-y switch load order} specified in the \texttt{-y}
+ switch.%
\end{enumerate}
A visual representation of this is given in \cref{fig:loadorder}.
@@ -205,8 +200,8 @@ latexindent.pl -m --yaml='modifyLineBreaks:oneSentencePerLine:sentencesEndWith:o
\centering
\input{figure-schematic}
\caption{Schematic of the load order described in \cref{sec:loadorder}; solid lines represent
- mandatory files, dotted lines represent optional files. \texttt{indentconfig.yaml} can
- contain as many files as you like. The files will be loaded in order; if you specify
- settings for the same field in more than one file, the most recent takes priority. }
+ mandatory files, dotted lines represent optional files. \texttt{indentconfig.yaml} can
+ contain as many files as you like. The files will be loaded in order; if you specify
+ settings for the same field in more than one file, the most recent takes priority. }
\label{fig:loadorder}
\end{figure}
diff --git a/support/latexindent/documentation/sec-introduction.tex b/support/latexindent/documentation/sec-introduction.tex
index 22fbd3cd66..8812e106b9 100644
--- a/support/latexindent/documentation/sec-introduction.tex
+++ b/support/latexindent/documentation/sec-introduction.tex
@@ -48,8 +48,8 @@
\end{warning}
\emph{If you have used any version 2.* of \texttt{latexindent.pl}, there
- are a few changes to the interface; see \vref{app:differences} and the comments
- throughout this document for details}.
+ are a few changes to the interface; see \vref{app:differences} and the comments
+ throughout this document for details}.
\subsection{About this documentation}
As you read through this documentation, you will see many listings; in this version of
@@ -99,17 +99,15 @@
% \begin{latexonly}
You will occasionally see dates shown in the margin (for example, next to this
- paragraph!)%
- \announce{2017-06-25}{announce} which detail
- the date of the version in which the feature was implemented; the `N' stands for `new as
- of the date shown' and `U' stands for `updated as of the date shown'. If you see
- \stardemo, it means that the feature is either new (N) or updated (U) as of the release
- of the current version; if you see \stardemo\, attached to a listing, then it means that
- listing is new (N) or updated (U) as of the current version. If you have not read this
- document before (and even if you have!), then you can ignore every occurrence of the
- \stardemo; they are simply there to highlight new and updated features. The new and
- updated features in this documentation (\gitRel) are on the following pages:
- \listOfNewFeatures % \end{latexonly}
+ paragraph!) \announce{2017-06-25}{announce} which detail the date of the version in which
+ the feature was implemented; the `N' stands for `new as of the date shown' and `U' stands
+ for `updated as of the date shown'. If you see \stardemo, it means that the feature is
+ either new (N) or updated (U) as of the release of the current version; if you see
+ \stardemo\, attached to a listing, then it means that listing is new (N) or updated (U)
+ as of the current version. If you have not read this document before (and even if you
+ have!), then you can ignore every occurrence of the \stardemo; they are simply there to
+ highlight new and updated features. The new and updated features in this documentation
+ (\gitRel) are on the following pages: \listOfNewFeatures% % \end{latexonly}
\subsection{Quick start}\label{sec:quickstart}
If you'd like to get started with \texttt{latexindent.pl} then simply type
diff --git a/support/latexindent/documentation/sec-replacements.tex b/support/latexindent/documentation/sec-replacements.tex
index a36c4199cf..5491df6072 100644
--- a/support/latexindent/documentation/sec-replacements.tex
+++ b/support/latexindent/documentation/sec-replacements.tex
@@ -1,20 +1,19 @@
% arara: pdflatex: { files: [latexindent]}
\section{The -r, -rv and -rr switches}\label{sec:replacements}
\fancyhead[R]{\bfseries\thepage%
- \tikz[remember picture,overlay] {
- \node at (1,0){\includegraphics{logo-bw}}; }
+ \tikz[remember picture,overlay] {
+ \node at (1,0){\includegraphics{logo-bw}}; }
}
You can instruct \texttt{latexindent.pl} to perform replacements/substitutions on your
\announce{2019-07-13}{replacement mode switches} file by using any of the \texttt{-r},
- \texttt{-rv} or \texttt{-rr} switches:
- \index{verbatim!rv, replacementrespectverb switch}
+ \texttt{-rv} or \texttt{-rr} switches: \index{verbatim!rv, replacementrespectverb switch}
\begin{itemize}
\item the \texttt{-r} switch will perform indentation and replacements, not respecting verbatim
code blocks;
\item the \texttt{-rv} switch will perform indentation and replacements, and \emph{will}
respect verbatim code blocks;
- \item the \texttt{-rr} switch will \emph{not} perform indentation, and will perform
+ \item the \texttt{-rr} switch will \emph{not} perform indentation, and will perform
replacements not respecting verbatim code blocks.
\end{itemize}
@@ -57,8 +56,8 @@
with further examples. With reference to \cref{lst:replacements}, the default action will
replace every instance of the text \texttt{latexindent.pl} with \texttt{pl.latexindent}.
- Beginning with the code in \cref{lst:replace1} and running the command
- \index{switches!-r demonstration}
+ Beginning with the code in \cref{lst:replace1} and running the command \index{switches!-r
+ demonstration}
\begin{commandshell}
latexindent.pl -r replace1.tex
\end{commandshell}
@@ -71,8 +70,7 @@ latexindent.pl -r replace1.tex
If we don't wish to perform this replacement, then we can tweak the default settings of
\vref{lst:replacements} by changing \texttt{lookForThis} to 0; we perform this action in
- \cref{lst:replace1-yaml}, and run the command
- \index{switches!-l demonstration}
+ \cref{lst:replace1-yaml}, and run the command \index{switches!-l demonstration}
\index{switches!-r demonstration}
\begin{commandshell}
latexindent.pl -r replace1.tex -l=replace1.yaml
@@ -113,12 +111,11 @@ latexindent.pl -r replace1.tex -l=replace1.yaml
\cmhlistingsfromfile{demonstrations/colsep.tex}{\texttt{colsep.tex}}{lst:colsep}
- Let's assume that our goal is to remove both of the \texttt{arraycolsep} statements; we can achieve this in
- a few different ways.
+ Let's assume that our goal is to remove both of the \texttt{arraycolsep} statements; we
+ can achieve this in a few different ways.
- Using the YAML in \cref{lst:colsep-yaml}, and running the command
- \index{switches!-l demonstration}
- \index{switches!-r demonstration}
+ Using the YAML in \cref{lst:colsep-yaml}, and running the command \index{switches!-l
+ demonstration} \index{switches!-r demonstration}
\begin{commandshell}
latexindent.pl -r colsep.tex -l=colsep.yaml
\end{commandshell}
@@ -131,16 +128,14 @@ latexindent.pl -r colsep.tex -l=colsep.yaml
furthermore, for both of the separate fields, we have not specified `\texttt{that}', so the \texttt{that} field
is assumed to be blank by \texttt{latexindent.pl};
- We can make the YAML in \cref{lst:colsep-yaml} more concise by exploring the \texttt{substitution} field. Using
- the settings in \cref{lst:colsep1} and running the command
- \index{switches!-l demonstration}
- \index{switches!-r demonstration}
+ We can make the YAML in \cref{lst:colsep-yaml} more concise by exploring the
+ \texttt{substitution} field. Using the settings in \cref{lst:colsep1} and running the
+ command \index{switches!-l demonstration} \index{switches!-r demonstration}
\begin{commandshell}
latexindent.pl -r colsep.tex -l=colsep1.yaml
\end{commandshell}
- then we achieve the output in \cref{lst:colsep-mod1}.
- \index{regular expressions!substitution field, arraycolsep}
- \index{regular expressions!at least one +}
+ then we achieve the output in \cref{lst:colsep-mod1}. \index{regular
+ expressions!substitution field, arraycolsep} \index{regular expressions!at least one +}
\begin{cmhtcbraster}[raster column skip=.01\linewidth,
raster force size=false,
raster column 1/.style={add to width=-.1\textwidth}]
@@ -148,10 +143,11 @@ latexindent.pl -r colsep.tex -l=colsep1.yaml
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/colsep1.yaml}[replace-TCB,width=0.6\textwidth]{\texttt{colsep1.yaml}}{lst:colsep1}
\end{cmhtcbraster}
- The code given in \cref{lst:colsep1} is an example of a \emph{regular expression}, which we may abbreviate to \emph{regex}
- in what follows. This manual is not intended to be
- a tutorial on regular expressions; you might like to read, for example, \cite{masteringregexp} for a detailed
- covering of the topic. With reference to \cref{lst:colsep1}, we do note the following:
+ The code given in \cref{lst:colsep1} is an example of a \emph{regular expression}, which
+ we may abbreviate to \emph{regex} in what follows. This manual is not intended to be a
+ tutorial on regular expressions; you might like to read, for example,
+ \cite{masteringregexp} for a detailed covering of the topic. With reference to
+ \cref{lst:colsep1}, we do note the following:
\begin{itemize}
\item the general form of the \texttt{substitution} field is
\lstinline!s/regex/replacement/modifiers!. You can place any regular expression you like
@@ -172,9 +168,8 @@ latexindent.pl -r colsep.tex -l=colsep1.yaml
\begin{example}
We'll keep working with the file in \vref{lst:colsep} for this example.
- Using the YAML in \cref{lst:multi-line}, and running the command
- \index{switches!-l demonstration}
- \index{switches!-r demonstration}
+ Using the YAML in \cref{lst:multi-line}, and running the command \index{switches!-l
+ demonstration} \index{switches!-r demonstration}
\begin{commandshell}
latexindent.pl -r colsep.tex -l=multi-line.yaml
\end{commandshell}
@@ -187,13 +182,13 @@ latexindent.pl -r colsep.tex -l=multi-line.yaml
YAML style \lstinline!|-!. See, for example, \href{https://stackoverflow.com/questions/3790454/in-yaml-how-do-i-break-a-string-over-multiple-lines}{https://stackoverflow.com/questions/3790454/in-yaml-how-do-i-break-a-string-over-multiple-lines}
for further options, all of which can be used in your YAML file.
- This is a natural point to explore the \texttt{when} field, specified in \vref{lst:replacements}. This field can take two values: \emph{before}
- and \emph{after}, which respectively instruct \texttt{latexindent.pl} to perform the replacements \emph{before} indentation or \emph{after} it.
- The default value is \texttt{before}.
+ This is a natural point to explore the \texttt{when} field, specified in
+ \vref{lst:replacements}. This field can take two values: \emph{before} and \emph{after},
+ which respectively instruct \texttt{latexindent.pl} to perform the replacements
+ \emph{before} indentation or \emph{after} it. The default value is \texttt{before}.
- Using the YAML in \cref{lst:multi-line1}, and running the command
- \index{switches!-l demonstration}
- \index{switches!-r demonstration}
+ Using the YAML in \cref{lst:multi-line1}, and running the command \index{switches!-l
+ demonstration} \index{switches!-r demonstration}
\begin{commandshell}
latexindent.pl -r colsep.tex -l=multi-line1.yaml
\end{commandshell}
@@ -207,31 +202,32 @@ latexindent.pl -r colsep.tex -l=multi-line1.yaml
indentation, the string as written in \cref{lst:multi-line1} is no longer part of the file, and has therefore not been replaced.
As a final note on this example, if you use the \texttt{-rr} switch, as follows,
- \index{switches!-l demonstration}
- \index{switches!-rr demonstration}
+ \index{switches!-l demonstration} \index{switches!-rr demonstration}
\begin{commandshell}
latexindent.pl -rr colsep.tex -l=multi-line1.yaml
\end{commandshell}
- then the \texttt{when} field is ignored, no indentation is done, and the output is as in \cref{lst:colsep-mod2}.
+ then the \texttt{when} field is ignored, no indentation is done, and the output is as in
+ \cref{lst:colsep-mod2}.
\end{example}
\begin{example}
An important part of the substitution routine is in \emph{capture groups}.
- Assuming that we start with
- the code in \cref{lst:displaymath}, let's assume that our goal is to replace each occurrence of \lstinline!$$...$$!
- with \lstinline!\begin{equation*}...\end{equation*}!. This example is partly motivated by \href{https://tex.stackexchange.com/questions/242150/good-looking-latex-code}{tex stackexchange question 242150}.
+ Assuming that we start with the code in \cref{lst:displaymath}, let's assume that our
+ goal is to replace each occurrence of \lstinline!$$...$$! with
+ \lstinline!\begin{equation*}...\end{equation*}!. This example is partly motivated by
+ \href{https://tex.stackexchange.com/questions/242150/good-looking-latex-code}{tex
+ stackexchange question 242150}.
\cmhlistingsfromfile{demonstrations/displaymath.tex}{\texttt{displaymath.tex}}{lst:displaymath}
- We use the settings in \cref{lst:displaymath1} and run the command
- \index{switches!-l demonstration}
- \index{switches!-r demonstration}
+ We use the settings in \cref{lst:displaymath1} and run the command \index{switches!-l
+ demonstration} \index{switches!-r demonstration}
\begin{commandshell}
latexindent.pl -r displaymath.tex -l=displaymath1.yaml
\end{commandshell}
- to receive the output given in \cref{lst:displaymath-mod1}.
- \index{regular expressions!substitution field, equation}
+ to receive the output given in \cref{lst:displaymath-mod1}. \index{regular
+ expressions!substitution field, equation}
\begin{cmhtcbraster}[raster left skip=-3.75cm,
raster right skip=-2cm,]
@@ -250,11 +246,11 @@ latexindent.pl -r displaymath.tex -l=displaymath1.yaml
See \href{https://perldoc.perl.org/perlre.html#Capture-groups}{https://perldoc.perl.org/perlre.html\#Capture-groups} for a discussion
of capture groups.
- The features of the replacement switches can, of course, be combined with others from the toolkit of \texttt{latexindent.pl}. For example,
- we can combine the poly-switches of \vref{sec:poly-switches}, which we do in \cref{lst:equation}; upon running the command
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \index{switches!-r demonstration}
+ The features of the replacement switches can, of course, be combined with others from the
+ toolkit of \texttt{latexindent.pl}. For example, we can combine the poly-switches of
+ \vref{sec:poly-switches}, which we do in \cref{lst:equation}; upon running the command
+ \index{switches!-l demonstration} \index{switches!-m demonstration} \index{switches!-r
+ demonstration}
\begin{commandshell}
latexindent.pl -r -m displaymath.tex -l=displaymath1.yaml,equation.yaml
\end{commandshell}
@@ -270,28 +266,28 @@ latexindent.pl -r -m displaymath.tex -l=displaymath1.yaml,equation.yaml
\end{example}
\begin{example}
- This example is motivated by \href{https://tex.stackexchange.com/questions/490086/bring-several-lines-together-to-fill-blank-spaces-in-texmaker}{tex stackexchange question 490086}.
- We begin with the code in \cref{lst:phrase}.
+ This example is motivated by
+ \href{https://tex.stackexchange.com/questions/490086/bring-several-lines-together-to-fill-blank-spaces-in-texmaker}{tex
+ stackexchange question 490086}. We begin with the code in \cref{lst:phrase}.
\cmhlistingsfromfile{demonstrations/phrase.tex}{\texttt{phrase.tex}}{lst:phrase}
- Our goal is to make the spacing uniform between the phrases. To achieve this, we employ the settings in \cref{lst:hspace},
- and run the command
- \index{switches!-l demonstration}
+ Our goal is to make the spacing uniform between the phrases. To achieve this, we employ
+ the settings in \cref{lst:hspace}, and run the command \index{switches!-l demonstration}
\index{switches!-r demonstration}
\begin{commandshell}
latexindent.pl -r phrase.tex -l=hspace.yaml
\end{commandshell}
- which gives the output in \cref{lst:phrase-mod1}.
- \index{regular expressions!at least one +}
- \index{regular expressions!horizontal space \textbackslash{h}}
+ which gives the output in \cref{lst:phrase-mod1}. \index{regular expressions!at least one
+ +} \index{regular expressions!horizontal space \textbackslash{h}}
\begin{cmhtcbraster}
\cmhlistingsfromfile{demonstrations/phrase-mod1.tex}{\texttt{phrase.tex} using \cref{lst:hspace}}{lst:phrase-mod1}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/hspace.yaml}[replace-TCB]{\texttt{hspace.yaml}}{lst:hspace}
\end{cmhtcbraster}
- The \lstinline!\h+! setting in \cref{lst:hspace} say to replace \emph{at least one horizontal space} with a single space.
+ The \lstinline!\h+! setting in \cref{lst:hspace} say to replace \emph{at least one
+ horizontal space} with a single space.
\end{example}
\begin{example}
@@ -299,40 +295,37 @@ latexindent.pl -r phrase.tex -l=hspace.yaml
\cmhlistingsfromfile{demonstrations/references.tex}{\texttt{references.tex}}{lst:references}
- Our goal is to change each reference so that both the text and the reference are contained within one hyperlink. We
- achieve this by employing \cref{lst:reference} and running the command
- \index{switches!-l demonstration}
- \index{switches!-r demonstration}
+ Our goal is to change each reference so that both the text and the reference are
+ contained within one hyperlink. We achieve this by employing \cref{lst:reference} and
+ running the command \index{switches!-l demonstration} \index{switches!-r demonstration}
\begin{commandshell}
latexindent.pl -r references.tex -l=reference.yaml
\end{commandshell}
- which gives the output in \cref{lst:references-mod1}.
- \index{regular expressions!horizontal space \textbackslash{h}}
+ which gives the output in \cref{lst:references-mod1}. \index{regular
+ expressions!horizontal space \textbackslash{h}}
\cmhlistingsfromfile{demonstrations/references-mod1.tex}{\texttt{references.tex} using \cref{lst:reference}}{lst:references-mod1}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/reference.yaml}[replace-TCB]{\texttt{reference.yaml}}{lst:reference}
- Referencing \cref{lst:reference}, the \lstinline!|! means \emph{or}, we have used \emph{capture groups}, together with an example
- of an \emph{optional} pattern, \lstinline!(?:eq)?!.
+ Referencing \cref{lst:reference}, the \lstinline!|! means \emph{or}, we have used
+ \emph{capture groups}, together with an example of an \emph{optional} pattern,
+ \lstinline!(?:eq)?!.
\end{example}
\begin{example}
- Let's explore the three replacement mode switches (see \vref{tab:replacementswitches}) in the context of
- an example that contains a verbatim code block, \cref{lst:verb1}; we will use the settings in \cref{lst:verbatim1-yaml}.
+ Let's explore the three replacement mode switches (see \vref{tab:replacementswitches}) in
+ the context of an example that contains a verbatim code block, \cref{lst:verb1}; we will
+ use the settings in \cref{lst:verbatim1-yaml}.
\begin{cmhtcbraster}
\cmhlistingsfromfile{demonstrations/verb1.tex}{\texttt{verb1.tex}}{lst:verb1}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/verbatim1.yaml}[replace-TCB]{\texttt{verbatim1.yaml}}{lst:verbatim1-yaml}
\end{cmhtcbraster}
- Upon running the following commands,
- \index{verbatim!comparison with -r and -rr switches}
- \index{switches!-l demonstration}
- \index{switches!-o demonstration}
- \index{switches!-r demonstration}
- \index{switches!-rv demonstration}
- \index{switches!-rr demonstration}
+ Upon running the following commands, \index{verbatim!comparison with -r and -rr switches}
+ \index{switches!-l demonstration} \index{switches!-o demonstration} \index{switches!-r
+ demonstration} \index{switches!-rv demonstration} \index{switches!-rr demonstration}
\begin{commandshell}
latexindent.pl -r verb1.tex -l=verbatim1.yaml -o=+mod1
latexindent.pl -rv verb1.tex -l=verbatim1.yaml -o=+-rv-mod1
@@ -363,8 +356,8 @@ latexindent.pl -rr verb1.tex -l=verbatim1.yaml -o=+-rr-mod1
See the summary within \vref{tab:replacementswitches}.
\begin{example}
- Let's explore the \texttt{amalgamate} field from \vref{lst:replacements} in the context of the file specified
- in \cref{lst:amalg1}.
+ Let's explore the \texttt{amalgamate} field from \vref{lst:replacements} in the context
+ of the file specified in \cref{lst:amalg1}.
\cmhlistingsfromfile{demonstrations/amalg1.tex}{\texttt{amalg1.tex}}{lst:amalg1}
@@ -378,9 +371,8 @@ latexindent.pl -rr verb1.tex -l=verbatim1.yaml -o=+-rr-mod1
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/amalg3-yaml.yaml}[replace-TCB]{\texttt{amalg3-yaml.yaml}}{lst:amalg3-yaml}
\end{cmhtcbraster}
- Upon running the following commands,
- \index{switches!-l demonstration}
- \index{switches!-r demonstration}
+ Upon running the following commands, \index{switches!-l demonstration} \index{switches!-r
+ demonstration}
\begin{commandshell}
latexindent.pl -r amalg1.tex -l=amalg1-yaml
latexindent.pl -r amalg1.tex -l=amalg1-yaml,amalg2-yaml
diff --git a/support/latexindent/documentation/sec-the-line-switch.tex b/support/latexindent/documentation/sec-the-line-switch.tex
index 2fdab46512..6c2d097e89 100644
--- a/support/latexindent/documentation/sec-the-line-switch.tex
+++ b/support/latexindent/documentation/sec-the-line-switch.tex
@@ -21,7 +21,7 @@ latexindent.pl -n 3-7 myfile.tex
\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.
+ 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
@@ -34,7 +34,8 @@ latexindent.pl -n 3-7 myfile.tex
\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}.
+ 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}
@@ -47,12 +48,13 @@ latexindent.pl --lines 7-3 myfile.tex -o=+-mod1
\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
+ 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}.
+ 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}
@@ -64,8 +66,9 @@ latexindent.pl --lines 5-5 myfile.tex
\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.
+ 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}
@@ -86,7 +89,8 @@ latexindent.pl --lines -1-3 myfile.tex
\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}.
+ 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}
@@ -97,28 +101,31 @@ 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.
+ 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
+ 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}.
+ 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
+ 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.
+ 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}
@@ -127,10 +134,11 @@ latexindent.pl --lines 12,4-5,1-2,9-10 myfile.tex
\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.
+ 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:
+ 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
@@ -158,9 +166,11 @@ latexindent.pl --lines 1-4,8,11-12 myfile.tex -o=+-mod6
\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}.
+ \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:
+ 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
@@ -174,8 +184,9 @@ latexindent.pl --lines !y-3 myfile.tex
\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
+ 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
diff --git a/support/latexindent/documentation/sec-the-m-switch.tex b/support/latexindent/documentation/sec-the-m-switch.tex
index 0d16cc43db..1f18d2f76c 100644
--- a/support/latexindent/documentation/sec-the-m-switch.tex
+++ b/support/latexindent/documentation/sec-the-m-switch.tex
@@ -2,9 +2,9 @@
\renewcommand{\imagetouse}{logo}
\section{The -m (modifylinebreaks) switch}\label{sec:modifylinebreaks}
\fancyhead[R]{\bfseries\thepage%
- \tikz[remember picture,overlay] {
- \node at (1,0){\includegraphics{logo}};
- }}
+ \tikz[remember picture,overlay] {
+ \node at (1,0){\includegraphics{logo}};
+ }}
All features described in this section will only be relevant if the \texttt{-m} switch is
used.
@@ -13,21 +13,20 @@
\yamltitle{modifylinebreaks}*{fields}
\makebox[0pt][r]{%
- \raisebox{-\totalheight}[0pt][0pt]{%
- \tikz\node[opacity=1] at (0,0)
- {\includegraphics[width=4cm]{logo}};}}%
+ \raisebox{-\totalheight}[0pt][0pt]{%
+ \tikz\node[opacity=1] at (0,0)
+ {\includegraphics[width=4cm]{logo}};}}%
As of Version 3.0, \texttt{latexindent.pl} has the \texttt{-m} switch, which permits
\texttt{latexindent.pl} to modify line breaks, according to the specifications in the
\texttt{modifyLineBreaks} field. \emph{The settings in this field will only be considered
- if the \texttt{-m} switch has been used}. A snippet of the default settings of this field
+ if the \texttt{-m} switch has been used}. A snippet of the default settings of this field
is shown in \cref{lst:modifylinebreaks}.
\cmhlistingsfromfile[style=modifylinebreaks]{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{modifyLineBreaks}}{lst:modifylinebreaks}
Having read the previous paragraph, it should sound reasonable that, if you call
\texttt{latexindent.pl} using the \texttt{-m} switch, then you give it permission to
- modify line breaks in your file, but let's be clear:
- \index{warning!the m switch}
+ modify line breaks in your file, but let's be clear: \index{warning!the m switch}
\begin{warning}
If you call \texttt{latexindent.pl} with the \texttt{-m} switch, then you are giving it
@@ -47,8 +46,7 @@
Assuming that this switch takes an integer value greater than \texttt{0},
\texttt{latexindent.pl} will condense multiple blank lines into the number of blank lines
illustrated by this switch. As an example, \cref{lst:mlb-bl} shows a sample file with
- blank lines; upon running
- \index{switches!-m demonstration}
+ blank lines; upon running \index{switches!-m demonstration}
\begin{commandshell}
latexindent.pl myfile.tex -m -o=+-mod1
\end{commandshell}
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 94aab37b32..e84c92f8c6 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
@@ -1,9 +1,9 @@
% arara: pdflatex: { files: [latexindent]}
\subsection{Combining removeParagraphLineBreaks and textWrapOptions}\label{subsec:removeparagraphlinebreaks:and:textwrap}
- The%
- \announce{2018-08-13}{combine text wrap and remove paragraph line breaks} text wrapping routine (\vref{subsec:textwrapping}) and remove
- paragraph line breaks routine (\vref{subsec:removeparagraphlinebreaks}) can be combined.
+ The \announce{2018-08-13}{combine text wrap and remove paragraph line breaks} text
+ wrapping routine (\vref{subsec:textwrapping}) and remove paragraph line breaks routine
+ (\vref{subsec:removeparagraphlinebreaks}) can be combined.%
We motivate this feature with the code given in \cref{lst:textwrap7}.
@@ -19,9 +19,8 @@
behaviour can be achieved by employing the \texttt{beforeTextWrap} switch.
Explicitly, using the settings in \cref{lst:textwrap12-yaml} and running the command
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \index{switches!-o demonstration}
+ \index{switches!-l demonstration} \index{switches!-m demonstration} \index{switches!-o
+ demonstration}
\begin{commandshell}
latexindent.pl -m textwrap7.tex -l=textwrap12.yaml -o=+-mod12
\end{commandshell}
@@ -41,9 +40,9 @@ 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
- \texttt{beforeFindingChildCodeBlocks} option for the text wrap routine.
+ I \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}.
@@ -73,7 +72,7 @@ latexindent.pl -m textwrap-bfccb.tex -l=textwrap12.yaml -o=+-mod12
\end{itemize}
We can instruct \texttt{latexindent.pl} to perform text wrapping \emph{before searching
- for child code blocks} by using the \texttt{beforeFindingChildCodeBlocks} field.
+ for child code blocks} by using the \texttt{beforeFindingChildCodeBlocks} field.
We save the \emph{quick-start} settings from \cref{lst:textwrap-qs-yaml} into
\cref{lst:textwrap13-yaml} and change the value of \texttt{columns} for demonstration.
diff --git a/support/latexindent/documentation/subsec-commands-and-their-options.tex b/support/latexindent/documentation/subsec-commands-and-their-options.tex
index cb2d099994..7ed4d4eaeb 100644
--- a/support/latexindent/documentation/subsec-commands-and-their-options.tex
+++ b/support/latexindent/documentation/subsec-commands-and-their-options.tex
@@ -6,9 +6,8 @@
\yamltitle{commandCodeBlocks}*{fields}
- The \texttt{commandCodeBlocks} field%
- \announce{2018-04-27}*{commandCodeBlocks} contains a few switches detailed in
- \cref{lst:commandCodeBlocks}.
+ The \texttt{commandCodeBlocks} field \announce{2018-04-27}*{commandCodeBlocks} contains a
+ few switches detailed in \cref{lst:commandCodeBlocks}.%
\cmhlistingsfromfile[style=commandCodeBlocks]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{commandCodeBlocks}}{lst:commandCodeBlocks}
@@ -54,12 +53,11 @@ latexindent.pl pstricks1.tex -l noRoundParentheses.yaml
Notice the difference between \cref{lst:pstricks1-default} and \cref{lst:pstricks1-nrp};
in particular, in \cref{lst:pstricks1-nrp}, because round parentheses are \emph{not}
- allowed, \texttt{latexindent.pl} finds that the
- \lstinline!\defFunction! command finishes at the first opening round parenthesis. As
- such, the remaining braced, mandatory, arguments are found to be
- \texttt{UnNamedGroupingBracesBrackets} (see \vref{tab:code-blocks}) which, by default,
- assume indentation for their body, and hence the tabbed indentation in
- \cref{lst:pstricks1-nrp}.
+ allowed, \texttt{latexindent.pl} finds that the \lstinline!\defFunction! command finishes
+ at the first opening round parenthesis. As such, the remaining braced, mandatory,
+ arguments are found to be \texttt{UnNamedGroupingBracesBrackets} (see
+ \vref{tab:code-blocks}) which, by default, assume indentation for their body, and hence
+ the tabbed indentation in \cref{lst:pstricks1-nrp}.
Let's explore this using the YAML given in \cref{lst:defFunction} and run the command
\index{switches!-l demonstration}
@@ -128,8 +126,7 @@ latexindent.pl tikz-node1.tex -l draw.yaml
specified in \cref{lst:draw}.
Let's compare this with the output from using the YAML settings in \cref{lst:no-strings},
- and running the command
- \index{switches!-l demonstration}
+ and running the command \index{switches!-l demonstration}
\begin{commandshell}
latexindent.pl tikz-node1.tex -l no-strings.yaml
\end{commandshell}
@@ -151,13 +148,13 @@ latexindent.pl tikz-node1.tex -l no-strings.yaml
with argument \lstinline![below,align=left,scale=0.5]!
\end{itemize}
- Referencing \vref{lst:commandCodeBlocks},%
- \announce{2018-04-27}*{amalgamate feature in commandCodeBlocks}, we see that the first
- field in the \texttt{stringsAllowedBetweenArguments} is \texttt{amalgamate} and is set to
- \texttt{1} by default. This is for users who wish to specify their settings in multiple
- YAML files. For example, by using the settings in either \cref{lst:amalgamate-demo}
+ Referencing \vref{lst:commandCodeBlocks}, \announce{2018-04-27}*{amalgamate feature in
+ commandCodeBlocks}, we see that the first field in the
+ \texttt{stringsAllowedBetweenArguments} is \texttt{amalgamate} and is set to \texttt{1}
+ by default. This is for users who wish to specify their settings in multiple YAML files.
+ For example, by using the settings in either \cref{lst:amalgamate-demo}
or\cref{lst:amalgamate-demo1} is equivalent to using the settings in
- \cref{lst:amalgamate-demo2}.
+ \cref{lst:amalgamate-demo2}.%
\begin{cmhtcbraster}[raster columns=3,
raster left skip=-3.5cm,
@@ -188,8 +185,7 @@ latexindent.pl tikz-node1.tex -l no-strings.yaml
\end{cmhtcbraster}
Let's compare this with the output from using the YAML settings in \cref{lst:foreach},
- and running the command
- \index{switches!-l demonstration}
+ and running the command \index{switches!-l demonstration}
\begin{commandshell}
latexindent.pl for-each.tex -l foreach.yaml
\end{commandshell}
@@ -205,18 +201,17 @@ latexindent.pl for-each.tex -l foreach.yaml
\texttt{foreach} command has not included any of the subsequent strings, and that the
braces have been treated as a \texttt{namedGroupingBracesBrackets}. In
\cref{lst:for-each-mod1} the \texttt{foreach} command has been allowed to have
- \lstinline!\x/\y! and \texttt{in} between arguments because of the settings given
- in \cref{lst:foreach}.
+ \lstinline!\x/\y! and \texttt{in} between arguments because of the settings given in
+ \cref{lst:foreach}.
\yamltitle{commandNameSpecial}*{fields}
- There are some special command names%
- \announce{2018-04-27}*{commandNameSpecial} that do not fit within the names recognised by
- \texttt{latexindent.pl}, the first one of which is \lstinline!\@ifnextchar[!. From the
- perspective of \texttt{latexindent.pl}, the whole of the text \lstinline!\@ifnextchar[!
- is a command, because it is immediately followed by sets of mandatory arguments. However,
- without the \texttt{commandNameSpecial} field, \texttt{latexindent.pl} would not be able
- to label it as such, because the \lstinline![! is, necessarily, not matched by a closing
- \lstinline!]!.
+ There are some special command names \announce{2018-04-27}*{commandNameSpecial} that do
+ not fit within the names recognised by \texttt{latexindent.pl}, the first one of which is
+ \lstinline!\@ifnextchar[!. From the perspective of \texttt{latexindent.pl}, the whole of
+ the text \lstinline!\@ifnextchar[! is a command, because it is immediately followed by
+ sets of mandatory arguments. However, without the \texttt{commandNameSpecial} field,
+ \texttt{latexindent.pl} would not be able to label it as such, because the \lstinline![!
+ is, necessarily, not matched by a closing \lstinline!]!.%
For example, consider the sample file in \cref{lst:ifnextchar}, which has default output
in \cref{lst:ifnextchar-default}.
@@ -246,8 +241,7 @@ latexindent.pl for-each.tex -l foreach.yaml
The \texttt{amalgamate} field can be used for \texttt{commandNameSpecial}, just as for
\texttt{stringsAllowedBetweenArguments}. The same condition holds as stated previously,
- which we state again here:
- \index{warning!amalgamate field}
+ which we state again here: \index{warning!amalgamate field}
\begin{warning}
It is important to note that the \texttt{amalgamate} field, if used, in either
diff --git a/support/latexindent/documentation/subsec-one-sentence-per-line.tex b/support/latexindent/documentation/subsec-one-sentence-per-line.tex
index 1b6fbcf4b1..37a57e8f1a 100644
--- a/support/latexindent/documentation/subsec-one-sentence-per-line.tex
+++ b/support/latexindent/documentation/subsec-one-sentence-per-line.tex
@@ -1,16 +1,14 @@
% arara: pdflatex: { files: [latexindent]}
\subsection{oneSentencePerLine: modifying line breaks for sentences}\label{sec:onesentenceperline}
- You can instruct \texttt{latexindent.pl} to format%
- \announce{2018-01-13}{one sentence per line} your file so that it puts one sentence per
- line. Thank you to \cite{mlep} for helping to shape and test this feature. The behaviour
- of this part of the script is controlled by the switches detailed in
- \cref{lst:oneSentencePerLine}, all of which we discuss next.
- \index{modifying linebreaks! by using one sentence per line}
- \index{sentences!oneSentencePerLine}
- \index{sentences!one sentence per line}
- \index{regular expressions!lowercase alph a-z}
- \index{regular expressions!uppercase alph A-Z}
+ You can instruct \texttt{latexindent.pl} to format \announce{2018-01-13}{one sentence per
+ line} your file so that it puts one sentence per line. Thank you to \cite{mlep} for
+ helping to shape and test this feature. The behaviour of this part of the script is
+ controlled by the switches detailed in \cref{lst:oneSentencePerLine}, all of which we
+ discuss next. \index{modifying linebreaks! by using one sentence per line}
+ \index{sentences!oneSentencePerLine} \index{sentences!one sentence per line}
+ \index{regular expressions!lowercase alph a-z} \index{regular expressions!uppercase alph
+ A-Z}%
\cmhlistingsfromfile[style=oneSentencePerLine]{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{oneSentencePerLine}}{lst:oneSentencePerLine}
@@ -33,8 +31,7 @@
If we use the YAML files in
\cref{lst:manipulate-sentences-yaml,lst:keep-sen-line-breaks-yaml}, and run the commands
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
+ \index{switches!-l demonstration} \index{switches!-m demonstration}
\begin{widepage}
\begin{commandshell}
latexindent.pl multiple-sentences -m -l=manipulate-sentences.yaml
@@ -60,10 +57,8 @@ latexindent.pl multiple-sentences -m -l=keep-sen-line-breaks.yaml
The remainder of the settings displayed in \vref{lst:oneSentencePerLine} instruct
\texttt{latexindent.pl} on how to define a sentence. From the perspective of
- \texttt{latexindent.pl} a sentence must:
- \index{sentences!follow}
- \index{sentences!begin with}
- \index{sentences!end with}
+ \texttt{latexindent.pl} a sentence must: \index{sentences!follow} \index{sentences!begin
+ with} \index{sentences!end with}
\begin{itemize}
\item \emph{follow} a certain character or set of characters (see
\cref{lst:sentencesFollow}); by default, this is either \lstinline!\par!, a
@@ -92,10 +87,8 @@ latexindent.pl multiple-sentences -m -l=keep-sen-line-breaks.yaml
\subsubsection{sentencesFollow}
Let's explore a few of the switches in \texttt{sentencesFollow}; let's start with
\vref{lst:multiple-sentences}, and use the YAML settings given in
- \cref{lst:sentences-follow1-yaml}. Using the command
- \index{sentences!follow}
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
+ \cref{lst:sentences-follow1-yaml}. Using the command \index{sentences!follow}
+ \index{switches!-l demonstration} \index{switches!-m demonstration}
\begin{commandshell}
latexindent.pl multiple-sentences -m -l=sentences-follow1.yaml
\end{commandshell}
@@ -115,9 +108,8 @@ latexindent.pl multiple-sentences -m -l=sentences-follow1.yaml
\cmhlistingsfromfile{demonstrations/multiple-sentences1.tex}{\texttt{multiple-sentences1.tex}}{lst:multiple-sentences1}
- Upon running the following commands
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
+ Upon running the following commands \index{switches!-l demonstration} \index{switches!-m
+ demonstration}
\begin{widepage}
\begin{commandshell}
latexindent.pl multiple-sentences1 -m -l=manipulate-sentences.yaml
@@ -146,14 +138,12 @@ latexindent.pl multiple-sentences1 -m -l=manipulate-sentences.yaml,sentences-fol
By default, \texttt{latexindent.pl} will only assume that sentences begin with the upper
case letters \texttt{A-Z}; you can instruct the script to define sentences to begin with
lower case letters (see \cref{lst:sentencesBeginWith}), and we can use the \texttt{other}
- field to define sentences to begin with other characters.
- \index{sentences!begin with}
+ field to define sentences to begin with other characters. \index{sentences!begin with}
\cmhlistingsfromfile{demonstrations/multiple-sentences2.tex}{\texttt{multiple-sentences2.tex}}{lst:multiple-sentences2}
- Upon running the following commands
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
+ Upon running the following commands \index{switches!-l demonstration} \index{switches!-m
+ demonstration}
\begin{widepage}
\begin{commandshell}
latexindent.pl multiple-sentences2 -m -l=manipulate-sentences.yaml
@@ -184,16 +174,14 @@ latexindent.pl multiple-sentences2 -m -l=manipulate-sentences.yaml,sentences-beg
which \texttt{latexindent.pl} will operate on the sentences in this file in
\vref{lst:multiple-sentences-mod1}. We can populate the \texttt{other} field with any
character that we wish; for example, using the YAML specified in
- \cref{lst:sentences-end1-yaml} and the command
- \index{sentences!end with}
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
+ \cref{lst:sentences-end1-yaml} and the command \index{sentences!end with}
+ \index{switches!-l demonstration} \index{switches!-m demonstration}
\begin{commandshell}
latexindent.pl multiple-sentences -m -l=sentences-end1.yaml
latexindent.pl multiple-sentences -m -l=sentences-end2.yaml
\end{commandshell}
- then we obtain the output in \cref{lst:multiple-sentences-mod4}.
- \index{regular expressions!lowercase alph a-z}
+ then we obtain the output in \cref{lst:multiple-sentences-mod4}. \index{regular
+ expressions!lowercase alph a-z}
\begin{cmhtcbraster}
\cmhlistingsfromfile{demonstrations/multiple-sentences-mod4.tex}{\texttt{multiple-sentences.tex} using \cref{lst:sentences-end1-yaml}}{lst:multiple-sentences-mod4}
@@ -221,9 +209,8 @@ latexindent.pl multiple-sentences -m -l=sentences-end2.yaml
\cmhlistingsfromfile{demonstrations/url.tex}{\texttt{url.tex}}{lst:url}
- Upon running the following commands
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
+ Upon running the following commands \index{switches!-l demonstration} \index{switches!-m
+ demonstration}
\begin{commandshell}
latexindent.pl url -m -l=manipulate-sentences.yaml
\end{commandshell}
@@ -247,8 +234,7 @@ latexindent.pl url -m -l=manipulate-sentences.yaml
The \texttt{basicFullStop} routine should probably be avoided in most situations, as it
does not accommodate the specifications above. For example, using the following command
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
+ \index{switches!-l demonstration} \index{switches!-m demonstration}
\begin{commandshell}
latexindent.pl url -m -l=alt-full-stop1.yaml
\end{commandshell}
@@ -267,15 +253,13 @@ latexindent.pl url -m -l=alt-full-stop1.yaml
the non-default settings in \cref{lst:alt-full-stop1-yaml}.
\subsubsection{Features of the oneSentencePerLine routine}
- The sentence manipulation routine takes place \emph{after} verbatim
- \index{verbatim!in relation to oneSentencePerLine} environments, preamble and trailing comments have been
+ The sentence manipulation routine takes place \emph{after} verbatim \index{verbatim!in
+ relation to oneSentencePerLine} environments, preamble and trailing comments have been
accounted for; this means that any characters within these types of code blocks will not
be part of the sentence manipulation routine.
For example, if we begin with the \texttt{.tex} file in \cref{lst:multiple-sentences3},
- and run the command
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
+ and run the command \index{switches!-l demonstration} \index{switches!-m demonstration}
\begin{commandshell}
latexindent.pl multiple-sentences3 -m -l=manipulate-sentences.yaml
\end{commandshell}
@@ -285,8 +269,7 @@ latexindent.pl multiple-sentences3 -m -l=manipulate-sentences.yaml
Furthermore, if sentences run across environments then, by default, the line breaks
internal to the sentence will be removed. For example, if we use the \texttt{.tex} file
- in \cref{lst:multiple-sentences4} and run the commands
- \index{switches!-l demonstration}
+ in \cref{lst:multiple-sentences4} and run the commands \index{switches!-l demonstration}
\index{switches!-m demonstration}
\begin{commandshell}
latexindent.pl multiple-sentences4 -m -l=manipulate-sentences.yaml
@@ -302,9 +285,7 @@ latexindent.pl multiple-sentences4 -m -l=keep-sen-line-breaks.yaml
Once you've read \cref{sec:poly-switches}, you will know that you can accommodate the
removal of internal sentence line breaks by using the YAML in \cref{lst:item-rules2-yaml}
- and the command
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
+ and the command \index{switches!-l demonstration} \index{switches!-m demonstration}
\begin{commandshell}
latexindent.pl multiple-sentences4 -m -l=item-rules2.yaml
\end{commandshell}
@@ -316,19 +297,16 @@ latexindent.pl multiple-sentences4 -m -l=item-rules2.yaml
\end{cmhtcbraster}
\subsubsection{Text wrapping and indenting sentences}
- The \texttt{oneSentencePerLine}%
- \announce{2018-08-13}{oneSentencePerline text wrap and indent} can be instructed to
- perform text wrapping and indentation upon sentences.
- \index{sentences!text wrapping}
- \index{sentences!indenting}
+ The \texttt{oneSentencePerLine} \announce{2018-08-13}{oneSentencePerline text wrap and
+ indent} can be instructed to perform text wrapping and indentation upon sentences.
+ \index{sentences!text wrapping} \index{sentences!indenting}%
Let's use the code in \cref{lst:multiple-sentences5}.
\cmhlistingsfromfile{demonstrations/multiple-sentences5.tex}{\texttt{multiple-sentences5.tex}}{lst:multiple-sentences5}
Referencing \cref{lst:sentence-wrap1-yaml}, and running the following command
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
+ \index{switches!-l demonstration} \index{switches!-m demonstration}
\begin{commandshell}
latexindent.pl multiple-sentences5 -m -l=sentence-wrap1.yaml
\end{commandshell}
@@ -343,11 +321,6 @@ latexindent.pl multiple-sentences5 -m -l=sentence-wrap1.yaml
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/sentence-wrap1.yaml}[MLB-TCB,width=0.5\textwidth]{\texttt{sentence-wrap1.yaml}}{lst:sentence-wrap1-yaml}
\end{cmhtcbraster}
- If you wish to specify the \texttt{columns} field on a per-code-block basis for
- sentences, then you would use \texttt{sentence}; explicitly, starting with
- \vref{lst:textwrap9-yaml}, for example, you would replace/append \texttt{environments}
- with, for example, \texttt{sentence: 50}.
-
If you specify \texttt{textWrapSentences} as 1, but do \emph{not} specify a value for
\texttt{columns} then the text wrapping will \emph{not} operate on sentences, and you
will see a warning in \texttt{indent.log}.
@@ -359,10 +332,8 @@ latexindent.pl multiple-sentences5 -m -l=sentence-wrap1.yaml
\cmhlistingsfromfile{demonstrations/multiple-sentences6.tex}{\texttt{multiple-sentences6.tex}}{lst:multiple-sentences6}
By default, \texttt{latexindent.pl} will find the full-stop within the first
- \texttt{item}, which means that, upon running the following commands
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \index{switches!-y demonstration}
+ \texttt{item}, which means that, upon running the following commands \index{switches!-l
+ demonstration} \index{switches!-m demonstration} \index{switches!-y demonstration}
\begin{commandshell}
latexindent.pl multiple-sentences6 -m -l=sentence-wrap1.yaml
latexindent.pl multiple-sentences6 -m -l=sentence-wrap1.yaml -y="modifyLineBreaks:oneSentencePerLine:sentenceIndent:''"
@@ -382,17 +353,14 @@ latexindent.pl multiple-sentences6 -m -l=sentence-wrap1.yaml -y="modifyLineBreak
We can tweak the settings in \vref{lst:sentencesEndWith} to ensure that full stops are
not followed by \texttt{item} commands, and that the end of sentences contains
\lstinline!\end{itemize}! as in \cref{lst:itemize-yaml} (if you intend to use this,
- ensure that you remove the line breaks from the \texttt{other} field).
- \index{regular expressions!lowercase alph a-z}
- \index{regular expressions!uppercase alph A-Z}
- \index{regular expressions!numeric 0-9}
- \index{regular expressions!horizontal space \textbackslash{h}}
+ ensure that you remove the line breaks from the \texttt{other} field). \index{regular
+ expressions!lowercase alph a-z} \index{regular expressions!uppercase alph A-Z}
+ \index{regular expressions!numeric 0-9} \index{regular expressions!horizontal space
+ \textbackslash{h}}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/itemized.yaml}[MLB-TCB]{\texttt{itemize.yaml}}{lst:itemize-yaml}
- Upon running
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
+ Upon running \index{switches!-l demonstration} \index{switches!-m demonstration}
\begin{commandshell}
latexindent.pl multiple-sentences6 -m -l=sentence-wrap1.yaml,itemize.yaml
\end{commandshell}
diff --git a/support/latexindent/documentation/subsec-poly-switches.tex b/support/latexindent/documentation/subsec-poly-switches.tex
index 42b077453f..9ac53f6648 100644
--- a/support/latexindent/documentation/subsec-poly-switches.tex
+++ b/support/latexindent/documentation/subsec-poly-switches.tex
@@ -40,18 +40,17 @@
after the \texttt{environments} field) and that \emph{per-name} settings are also allowed
-- in the case of \cref{lst:environments-mlb}, settings for \texttt{equation*} have been
specified for demonstration. Note that all poly-switches are \emph{off} (set to 0) by
- default.
- \index{poly-switches!default values}
- \index{poly-switches!environment global example}
- \index{poly-switches!environment per-code block example}
+ default. \index{poly-switches!default values} \index{poly-switches!environment global
+ example} \index{poly-switches!environment per-code block example}
\cmhlistingsfromfile[style=modifylinebreaksEnv]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,MLB-TCB]{\texttt{environments}}{lst:environments-mlb}
Let's begin with the simple example given in \cref{lst:env-mlb1-tex}; note that we have
annotated key parts of the file using $\BeginStartsOnOwnLine$, $\BodyStartsOnOwnLine$,
$\EndStartsOnOwnLine$ and $\EndFinishesWithLineBreak$, these will be related to fields
- specified in \cref{lst:environments-mlb}.
- \index{poly-switches!visualisation: $\BeginStartsOnOwnLine$, $\BodyStartsOnOwnLine$, $\EndStartsOnOwnLine$, $\EndFinishesWithLineBreak$}
+ specified in \cref{lst:environments-mlb}. \index{poly-switches!visualisation:
+ $\BeginStartsOnOwnLine$, $\BodyStartsOnOwnLine$, $\EndStartsOnOwnLine$,
+ $\EndFinishesWithLineBreak$}
\begin{cmhlistings}[style=tcblatex,escapeinside={(*@}{@*)}]{\texttt{env-mlb1.tex}}{lst:env-mlb1-tex}
before words(*@$\BeginStartsOnOwnLine$@*) \begin{myenv}(*@$\BodyStartsOnOwnLine$@*)body of myenv(*@$\EndStartsOnOwnLine$@*)\end{myenv}(*@$\EndFinishesWithLineBreak$@*) after words
@@ -60,9 +59,8 @@ before words(*@$\BeginStartsOnOwnLine$@*) \begin{myenv}(*@$\BodyStartsOnOwnLine$
\paragraph{Adding line breaks: BeginStartsOnOwnLine and BodyStartsOnOwnLine}
Let's explore \texttt{BeginStartsOnOwnLine} and \texttt{BodyStartsOnOwnLine} in
\cref{lst:env-mlb1,lst:env-mlb2}, and in particular, let's allow each of them in turn to
- take a value of $1$.
- \index{modifying linebreaks! at the \emph{beginning} of a code block}
- \index{poly-switches!adding line breaks: set to 1}
+ take a value of $1$. \index{modifying linebreaks! at the \emph{beginning} of a code
+ block} \index{poly-switches!adding line breaks: set to 1}
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb1.yaml}[MLB-TCB]{\texttt{env-mlb1.yaml}}{lst:env-mlb1}
@@ -72,8 +70,7 @@ before words(*@$\BeginStartsOnOwnLine$@*) \begin{myenv}(*@$\BodyStartsOnOwnLine$
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb2.yaml}[MLB-TCB]{\texttt{env-mlb2.yaml}}{lst:env-mlb2}
\end{minipage}
- After running the following commands,
- \index{switches!-l demonstration}
+ After running the following commands, \index{switches!-l demonstration}
\index{switches!-m demonstration}
\begin{commandshell}
latexindent.pl -m env-mlb.tex -l env-mlb1.yaml
@@ -103,8 +100,8 @@ latexindent.pl -m env-mlb.tex -l env-mlb2.yaml
Let's now change each of the \texttt{1} values in \cref{lst:env-mlb1,lst:env-mlb2} so
that they are $2$ and save them into \texttt{env-mlb3.yaml} and \texttt{env-mlb4.yaml}
- respectively (see \cref{lst:env-mlb3,lst:env-mlb4}).
- \index{poly-switches!adding comments and then line breaks: set to 2}
+ respectively (see \cref{lst:env-mlb3,lst:env-mlb4}). \index{poly-switches!adding comments
+ and then line breaks: set to 2}
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb3.yaml}[MLB-TCB]{\texttt{env-mlb3.yaml}}{lst:env-mlb3}
@@ -131,12 +128,10 @@ latexindent.pl -m env-mlb.tex -l env-mlb2.yaml
this time a comment symbol has been added before adding the line break; in both cases,
trailing horizontal space has been stripped before doing so.
- Let's%
- \announce{2017-08-21}{demonstration of blank line poly-switch (3)} now change each of the \texttt{1} values in
- \cref{lst:env-mlb1,lst:env-mlb2} so that they are $3$ and save them into
- \texttt{env-mlb5.yaml} and \texttt{env-mlb6.yaml} respectively (see
- \cref{lst:env-mlb5,lst:env-mlb6}).
- \index{poly-switches!adding blank lines: set to 3}
+ Let's \announce{2017-08-21}{demonstration of blank line poly-switch (3)} now change each
+ of the \texttt{1} values in \cref{lst:env-mlb1,lst:env-mlb2} so that they are $3$ and
+ save them into \texttt{env-mlb5.yaml} and \texttt{env-mlb6.yaml} respectively (see
+ \cref{lst:env-mlb5,lst:env-mlb6}). \index{poly-switches!adding blank lines: set to 3}%
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb5.yaml}[MLB-TCB]{\texttt{env-mlb5.yaml}}{lst:env-mlb5}
@@ -162,12 +157,11 @@ latexindent.pl -m env-mlb.tex -l env-mlb2.yaml
Note that line breaks have been added as in \cref{lst:env-mlb-mod1,lst:env-mlb-mod2}, but
this time a \emph{blank line} has been added after adding the line break.
- Let's now change%
- \announce{2019-07-13}{demonstration of new blank line poly-switch} each of the \texttt{1} values in
- \cref{lst:env-mlb5,lst:env-mlb6} so that they are $4$ and save them into
- \texttt{env-beg4.yaml} and \texttt{env-body4.yaml} respectively (see
- \cref{lst:env-beg4,lst:env-body4}).
- \index{poly-switches!adding blank lines (again"!): set to 4}
+ Let's now change \announce{2019-07-13}{demonstration of new blank line poly-switch} each
+ of the \texttt{1} values in \cref{lst:env-mlb5,lst:env-mlb6} so that they are $4$ and
+ save them into \texttt{env-beg4.yaml} and \texttt{env-body4.yaml} respectively (see
+ \cref{lst:env-beg4,lst:env-body4}). \index{poly-switches!adding blank lines (again"!):
+ set to 4}%
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-beg4.yaml}[MLB-TCB]{\texttt{env-beg4.yaml}}{lst:env-beg4}
@@ -181,9 +175,8 @@ latexindent.pl -m env-mlb.tex -l env-mlb2.yaml
\cmhlistingsfromfile{demonstrations/env-mlb1.tex}{\texttt{env-mlb1.tex}}{lst:env-mlb1-text}
- Upon running the commands
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
+ Upon running the commands \index{switches!-l demonstration} \index{switches!-m
+ demonstration}
\begin{commandshell}
latexindent.pl -m env-mlb1.tex -l env-beg4.yaml
latexindent.pl -m env-mlb.1tex -l env-body4.yaml
@@ -198,9 +191,8 @@ latexindent.pl -m env-mlb.1tex -l env-body4.yaml
We note in particular that, by design, for this value of the poly-switches:
\begin{enumerate}
- \item in \cref{lst:env-mlb1-beg4} a blank line has been inserted before the
- \lstinline!\begin! statement, even though the \lstinline!\begin!
- statement was already on its own line;
+ \item in \cref{lst:env-mlb1-beg4} a blank line has been inserted before the \lstinline!\begin!
+ statement, even though the \lstinline!\begin! statement was already on its own line;
\item in \cref{lst:env-mlb1-body4} a blank line has been inserted before the beginning of the
\emph{body}, even though it already began on its own line.
\end{enumerate}
@@ -208,8 +200,7 @@ latexindent.pl -m env-mlb.1tex -l env-body4.yaml
\paragraph{Adding line breaks using EndStartsOnOwnLine and EndFinishesWithLineBreak}
Let's explore \texttt{EndStartsOnOwnLine} and \texttt{EndFinishesWithLineBreak} in
\cref{lst:env-mlb7,lst:env-mlb8}, and in particular, let's allow each of them in turn to
- take a value of $1$.
- \index{modifying linebreaks! at the \emph{end} of a code block}
+ take a value of $1$. \index{modifying linebreaks! at the \emph{end} of a code block}
\index{poly-switches!adding line breaks: set to 1}
\begin{minipage}{.49\textwidth}
@@ -220,8 +211,7 @@ latexindent.pl -m env-mlb.1tex -l env-body4.yaml
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb8.yaml}[MLB-TCB]{\texttt{env-mlb8.yaml}}{lst:env-mlb8}
\end{minipage}
- After running the following commands,
- \index{switches!-l demonstration}
+ After running the following commands, \index{switches!-l demonstration}
\index{switches!-m demonstration}
\begin{commandshell}
latexindent.pl -m env-mlb.tex -l env-mlb7.yaml
@@ -251,8 +241,8 @@ latexindent.pl -m env-mlb.tex -l env-mlb8.yaml
Let's now change each of the \texttt{1} values in \cref{lst:env-mlb7,lst:env-mlb8} so
that they are $2$ and save them into \texttt{env-mlb9.yaml} and \texttt{env-mlb10.yaml}
- respectively (see \cref{lst:env-mlb9,lst:env-mlb10}).
- \index{poly-switches!adding comments and then line breaks: set to 2}
+ respectively (see \cref{lst:env-mlb9,lst:env-mlb10}). \index{poly-switches!adding
+ comments and then line breaks: set to 2}
\begin{minipage}{.49\textwidth}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb9.yaml}[MLB-TCB]{\texttt{env-mlb9.yaml}}{lst:env-mlb9}
@@ -279,12 +269,10 @@ latexindent.pl -m env-mlb.tex -l env-mlb8.yaml
this time a comment symbol has been added before adding the line break; in both cases,
trailing horizontal space has been stripped before doing so.
- Let's%
- \announce{2017-08-21}{demonstration of blank line poly-switch (3)} now change each of the \texttt{1} values in
- \cref{lst:env-mlb7,lst:env-mlb8} so that they are $3$ and save them into
- \texttt{env-mlb11.yaml} and \texttt{env-mlb12.yaml} respectively (see
- \cref{lst:env-mlb11,lst:env-mlb12}).
- \index{poly-switches!adding blank lines: set to 3}
+ Let's \announce{2017-08-21}{demonstration of blank line poly-switch (3)} now change each
+ of the \texttt{1} values in \cref{lst:env-mlb7,lst:env-mlb8} so that they are $3$ and
+ save them into \texttt{env-mlb11.yaml} and \texttt{env-mlb12.yaml} respectively (see
+ \cref{lst:env-mlb11,lst:env-mlb12}). \index{poly-switches!adding blank lines: set to 3}%
\begin{minipage}{.49\textwidth}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb11.yaml}[MLB-TCB]{\texttt{env-mlb11.yaml}}{lst:env-mlb11}
@@ -310,12 +298,11 @@ latexindent.pl -m env-mlb.tex -l env-mlb8.yaml
Note that line breaks have been added as in \cref{lst:env-mlb-mod7,lst:env-mlb-mod8}, and
that a \emph{blank line} has been added after the line break.
- Let's now change%
- \announce{2019-07-13}{demonstration of new blank line poly-switch} each of the \texttt{1} values in
- \cref{lst:env-mlb11,lst:env-mlb12} so that they are $4$ and save them into
- \texttt{env-end4.yaml} and \texttt{env-end-f4.yaml} respectively (see
- \cref{lst:env-end4,lst:env-end-f4}).
- \index{poly-switches!adding blank lines (again"!): set to 4}
+ Let's now change \announce{2019-07-13}{demonstration of new blank line poly-switch} each
+ of the \texttt{1} values in \cref{lst:env-mlb11,lst:env-mlb12} so that they are $4$ and
+ save them into \texttt{env-end4.yaml} and \texttt{env-end-f4.yaml} respectively (see
+ \cref{lst:env-end4,lst:env-end-f4}). \index{poly-switches!adding blank lines (again"!):
+ set to 4}%
\begin{minipage}{.45\textwidth}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-end4.yaml}[MLB-TCB]{\texttt{env-end4.yaml}}{lst:env-end4}
@@ -327,9 +314,8 @@ latexindent.pl -m env-mlb.tex -l env-mlb8.yaml
We will demonstrate this poly-switch value using the code from \vref{lst:env-mlb1-text}.
- Upon running the commands
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
+ Upon running the commands \index{switches!-l demonstration} \index{switches!-m
+ demonstration}
\begin{commandshell}
latexindent.pl -m env-mlb1.tex -l env-end4.yaml
latexindent.pl -m env-mlb.1tex -l env-end-f4.yaml
@@ -344,11 +330,10 @@ latexindent.pl -m env-mlb.1tex -l env-end-f4.yaml
We note in particular that, by design, for this value of the poly-switches:
\begin{enumerate}
- \item in \cref{lst:env-mlb1-end4} a blank line has been inserted before the
- \lstinline!\end! statement, even though the \lstinline!\end!
- statement was already on its own line;
- \item in \cref{lst:env-mlb1-end-f4} a blank line has been inserted after the
- \lstinline!\end! statement, even though it already began on its own line.
+ \item in \cref{lst:env-mlb1-end4} a blank line has been inserted before the \lstinline!\end!
+ statement, even though the \lstinline!\end! statement was already on its own line;
+ \item in \cref{lst:env-mlb1-end-f4} a blank line has been inserted after the \lstinline!\end!
+ statement, even though it already began on its own line.
\end{enumerate}
\paragraph{poly-switches 1, 2, and 3 only add line breaks when necessary}
@@ -396,8 +381,8 @@ latexindent.pl -m env-mlb.1tex -l env-end-f4.yaml
\cref{lst:mlb4}, noting in particular the positions of the line break highlighters,
$\BeginStartsOnOwnLine$, $\BodyStartsOnOwnLine$, $\EndStartsOnOwnLine$ and
$\EndFinishesWithLineBreak$, together with the associated YAML files in
- \crefrange{lst:env-mlb13}{lst:env-mlb16}.
- \index{poly-switches!removing line breaks: set to -1}
+ \crefrange{lst:env-mlb13}{lst:env-mlb16}. \index{poly-switches!removing line breaks: set
+ to -1}
\begin{minipage}{.45\linewidth}
\begin{cmhlistings}[style=tcblatex,escapeinside={(*@}{@*)}]{\texttt{env-mlb4.tex}}{lst:mlb4}
@@ -419,9 +404,8 @@ after words
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb16.yaml}[MLB-TCB]{\texttt{env-mlb16.yaml}}{lst:env-mlb16}
\end{minipage}
- After running the commands
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
+ After running the commands \index{switches!-l demonstration} \index{switches!-m
+ demonstration}
\begin{commandshell}
latexindent.pl -m env-mlb4.tex -l env-mlb13.yaml
latexindent.pl -m env-mlb4.tex -l env-mlb14.yaml
@@ -490,8 +474,7 @@ after words
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/removeTWS-before.yaml}[yaml-TCB]{\texttt{removeTWS-before.yaml}}{lst:removeTWS-before}
\end{cmhtcbraster}
- The output from the following commands
- \index{switches!-l demonstration}
+ The output from the following commands \index{switches!-l demonstration}
\index{switches!-m demonstration}
\begin{widepage}
\begin{commandshell}
@@ -532,9 +515,8 @@ after words
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/UnpreserveBlankLines.yaml}[MLB-TCB]{\texttt{UnpreserveBlankLines.yaml}}{lst:UnpreserveBlankLines}
\end{cmhtcbraster}
- Upon running the following commands
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
+ Upon running the following commands \index{switches!-l demonstration} \index{switches!-m
+ demonstration}
\begin{widepage}
\begin{commandshell}
latexindent.pl -m env-mlb6.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,env-mlb16.yaml
@@ -565,9 +547,8 @@ latexindent.pl -m env-mlb6.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,e
\cmhlistingsfromfile{demonstrations/env-mlb7.tex}{\texttt{env-mlb7.tex}}{lst:env-mlb7-tex}
- Upon running the following commands
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
+ Upon running the following commands \index{switches!-l demonstration} \index{switches!-m
+ demonstration}
\begin{commandshell}
latexindent.pl -m env-mlb7.tex -l env-mlb12.yaml,env-mlb13.yaml
latexindent.pl -m env-mlb7.tex -l env-mlb13.yaml,env-mlb14.yaml,UnpreserveBlankLines.yaml
@@ -589,17 +570,15 @@ latexindent.pl -m env-mlb7.tex -l env-mlb13.yaml,env-mlb14.yaml,UnpreserveBlankL
\end{itemize}
\subsubsection{Poly-switches for double back slash}\label{subsec:dbs}
- With reference to \texttt{lookForAlignDelims} (see
- \vref{lst:aligndelims:basic})%
+ With reference to \texttt{lookForAlignDelims} (see \vref{lst:aligndelims:basic})
\announce{2019-07-13}{poly-switch for double back slash} you can specify poly-switches to
dictate the line-break behaviour of double back slashes in environments
(\vref{lst:tabularafter:basic}), commands (\vref{lst:matrixafter}), or special code
blocks (\vref{lst:specialafter}). Note that for these poly-switches to take effect, the
name of the code block must necessarily be specified within \texttt{lookForAlignDelims}
(\vref{lst:aligndelims:basic}); we will demonstrate this in what follows.
- \index{delimiters!poly-switches for double back slash}
- \index{modifying linebreaks! surrounding double back slash}
- \index{poly-switches!for double back slash (delimiters)}
+ \index{delimiters!poly-switches for double back slash} \index{modifying linebreaks!
+ surrounding double back slash} \index{poly-switches!for double back slash (delimiters)}%
Consider the code given in \cref{lst:dbs-demo}.
\begin{cmhlistings}[style=tcblatex,escapeinside={(*@}{@*)}]{\texttt{tabular3.tex}}{lst:dbs-demo}
@@ -621,9 +600,8 @@ latexindent.pl -m env-mlb7.tex -l env-mlb13.yaml,env-mlb14.yaml,UnpreserveBlankL
\paragraph{Double back slash starts on own line}
We explore \texttt{DBSStartsOnOwnLine} ($\ElseStartsOnOwnLine$ in \cref{lst:dbs-demo});
starting with the code in \cref{lst:dbs-demo}, together with the YAML files given in
- \cref{lst:DBS1} and \cref{lst:DBS2} and running the following commands
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
+ \cref{lst:DBS1} and \cref{lst:DBS2} and running the following commands \index{switches!-l
+ demonstration} \index{switches!-m demonstration}
\begin{commandshell}
latexindent.pl -m tabular3.tex -l DBS1.yaml
latexindent.pl -m tabular3.tex -l DBS2.yaml
@@ -659,10 +637,8 @@ latexindent.pl -m tabular3.tex -l DBS2.yaml
Let's now explore \texttt{DBSFinishesWithLineBreak} ($\ElseFinishesWithLineBreak$ in
\cref{lst:dbs-demo}); starting with the code in \cref{lst:dbs-demo}, together with the
YAML files given in \cref{lst:DBS3} and \cref{lst:DBS4} and running the following
- commands
- \index{poly-switches!for double back slash (delimiters)}
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
+ commands \index{poly-switches!for double back slash (delimiters)} \index{switches!-l
+ demonstration} \index{switches!-m demonstration}
\begin{commandshell}
latexindent.pl -m tabular3.tex -l DBS3.yaml
latexindent.pl -m tabular3.tex -l DBS4.yaml
@@ -699,24 +675,20 @@ latexindent.pl -m tabular3.tex -l DBS4.yaml
\paragraph{Double back slash poly-switches for specialBeginEnd}
Let's explore the double back slash poly-switches for code blocks within
\texttt{specialBeginEnd} code blocks (\vref{lst:specialBeginEnd}); we begin with the code
- within \cref{lst:special4}.
- \index{specialBeginEnd!double backslash poly-switch demonstration}
- \index{poly-switches!double backslash}
- \index{poly-switches!for double back slash (delimiters)}
- \index{specialBeginEnd!lookForAlignDelims}
- \index{delimiters}
+ within \cref{lst:special4}. \index{specialBeginEnd!double backslash poly-switch
+ demonstration} \index{poly-switches!double backslash} \index{poly-switches!for double
+ back slash (delimiters)} \index{specialBeginEnd!lookForAlignDelims} \index{delimiters}
\index{linebreaks!summary of poly-switches}
\cmhlistingsfromfile{demonstrations/special4.tex}{\texttt{special4.tex}}{lst:special4}
Upon using the YAML settings in \cref{lst:DBS5}, and running the command
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
+ \index{switches!-l demonstration} \index{switches!-m demonstration}
\begin{commandshell}
latexindent.pl -m special4.tex -l DBS5.yaml
\end{commandshell}
- then we receive the output given in \cref{lst:special4-DBS5}.
- \index{delimiters!with specialBeginEnd and the -m switch}
+ then we receive the output given in \cref{lst:special4-DBS5}. \index{delimiters!with
+ specialBeginEnd and the -m switch}
\begin{cmhtcbraster}[
raster force size=false,
@@ -739,14 +711,12 @@ latexindent.pl -m special4.tex -l DBS5.yaml
\paragraph{Double back slash poly-switches for optional and mandatory arguments}
For clarity, we provide a demonstration of controlling the double back slash
poly-switches for optional and mandatory arguments. We begin with the code in
- \cref{lst:mycommand2}.
- \index{poly-switches!for double back slash (delimiters)}
+ \cref{lst:mycommand2}. \index{poly-switches!for double back slash (delimiters)}
\cmhlistingsfromfile{demonstrations/mycommand2.tex}{\texttt{mycommand2.tex}}{lst:mycommand2}
Upon using the YAML settings in \cref{lst:DBS6,lst:DBS7}, and running the command
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
+ \index{switches!-l demonstration} \index{switches!-m demonstration}
\begin{commandshell}
latexindent.pl -m mycommand2.tex -l DBS6.yaml
latexindent.pl -m mycommand2.tex -l DBS7.yaml
@@ -772,16 +742,14 @@ latexindent.pl -m mycommand2.tex -l DBS7.yaml
\paragraph{Double back slash optional square brackets}
The pattern matching for the double back slash will also, optionally, allow trailing
square brackets that contain a measurement of vertical spacing, for example
- \lstinline!\\[3pt]!.
- \index{poly-switches!for double back slash (delimiters)}
+ \lstinline!\\[3pt]!. \index{poly-switches!for double back slash (delimiters)}
For example, beginning with the code in \cref{lst:pmatrix3}
\cmhlistingsfromfile{demonstrations/pmatrix3.tex}{\texttt{pmatrix3.tex}}{lst:pmatrix3}
- and running the following command, using \cref{lst:DBS3},
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
+ and running the following command, using \cref{lst:DBS3}, \index{switches!-l
+ demonstration} \index{switches!-m demonstration}
\begin{commandshell}
latexindent.pl -m pmatrix3.tex -l DBS3.yaml
\end{commandshell}
@@ -790,7 +758,7 @@ latexindent.pl -m pmatrix3.tex -l DBS3.yaml
\cmhlistingsfromfile{demonstrations/pmatrix3-mod3.tex}{\texttt{pmatrix3.tex} using \cref{lst:DBS3}}{lst:pmatrix3-DBS3}
You can customise the pattern for the double back slash by exploring the \emph{fine
- tuning} field detailed in \vref{lst:fineTuning}.
+ tuning} field detailed in \vref{lst:fineTuning}.
\subsubsection{Poly-switches for other code blocks}
Rather than repeat the examples shown for the environment code blocks (in
@@ -800,14 +768,12 @@ latexindent.pl -m pmatrix3.tex -l DBS3.yaml
Note also that, by design, line breaks involving, \texttt{filecontents} and
`comment-marked' code blocks (\vref{lst:alignmentmarkup}) can \emph{not} be modified
- using \texttt{latexindent.pl}.%
- \announce{2019-05-05}*{verbatim poly-switch} However, there are two poly-switches
- available for \texttt{verbatim} code blocks: environments
+ using \texttt{latexindent.pl}. \announce{2019-05-05}*{verbatim poly-switch} However,
+ there are two poly-switches available for \texttt{verbatim} code blocks: environments
(\vref{lst:verbatimEnvironments}), commands (\vref{lst:verbatimCommands}) and
\texttt{specialBeginEnd} (\vref{lst:special-verb1-yaml}).
- \index{specialBeginEnd!poly-switch summary}
- \index{verbatim!poly-switch summary}
- \index{poly-switches!summary of all poly-switches}
+ \index{specialBeginEnd!poly-switch summary} \index{verbatim!poly-switch summary}
+ \index{poly-switches!summary of all poly-switches}%
\clearpage
\begin{longtable}{llll}
@@ -883,8 +849,7 @@ latexindent.pl -m pmatrix3.tex -l DBS3.yaml
involving the \emph{first} argument of a code block need to be accounted for using both
\texttt{BodyStartsOnOwnLine} (or its equivalent, see \vref{tab:poly-switch-mapping}) and
\texttt{LCuBStartsOnOwnLine} for mandatory arguments, and \texttt{LSqBStartsOnOwnLine}
- for optional arguments.
- \index{poly-switches!conflicting partnering}
+ for optional arguments. \index{poly-switches!conflicting partnering}
Let's begin with the code in \cref{lst:mycommand1} and the YAML settings in
\cref{lst:mycom-mlb1}; with reference to \vref{tab:poly-switch-mapping}, the key
@@ -892,9 +857,8 @@ latexindent.pl -m pmatrix3.tex -l DBS3.yaml
\cmhlistingsfromfile{demonstrations/mycommand1.tex}{\texttt{mycommand1.tex}}{lst:mycommand1}
- Upon running the command
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
+ Upon running the command \index{switches!-l demonstration} \index{switches!-m
+ demonstration}
\begin{commandshell}
latexindent.pl -m -l=mycom-mlb1.yaml mycommand1.tex
\end{commandshell}
@@ -936,10 +900,8 @@ latexindent.pl -m -l=mycom-mlb1.yaml mycommand1.tex
\subsubsection{Conflicting poly-switches: sequential code blocks}
It is very easy to have conflicting poly-switches; if we use the example from
\vref{lst:mycommand1}, and consider the YAML settings given in \cref{lst:mycom-mlb4}. The
- output from running
- \index{poly-switches!conflicting switches}
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
+ output from running \index{poly-switches!conflicting switches} \index{switches!-l
+ demonstration} \index{switches!-m demonstration}
\begin{commandshell}
latexindent.pl -m -l=mycom-mlb4.yaml mycommand1.tex
\end{commandshell}
@@ -964,9 +926,8 @@ latexindent.pl -m -l=mycom-mlb4.yaml mycommand1.tex
recently-processed code block and associated poly-switch takes priority.
We can explore this further by considering the YAML settings in \cref{lst:mycom-mlb5};
- upon running the command
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
+ upon running the command \index{switches!-l demonstration} \index{switches!-m
+ demonstration}
\begin{commandshell}
latexindent.pl -m -l=mycom-mlb5.yaml mycommand1.tex
\end{commandshell}
@@ -986,8 +947,8 @@ latexindent.pl -m -l=mycom-mlb5.yaml mycommand1.tex
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycom-mlb6.yaml}[MLB-TCB,width=\linewidth]{\texttt{mycom-mlb6.yaml}}{lst:mycom-mlb6}
\end{cmhtcbraster}
- Note that a \lstinline!%! \emph{has} been added to the trailing first
- \lstinline!}!; this is because:
+ Note that a \lstinline!%! \emph{has} been added to the trailing first \lstinline!}!; this
+ is because:
\begin{itemize}
\item while processing the \emph{first} argument, the trailing line break has been removed
(\texttt{RCuBFinishesWithLineBreak} set to $-1$);
@@ -1004,9 +965,7 @@ latexindent.pl -m -l=mycom-mlb5.yaml mycommand1.tex
\cmhlistingsfromfile{demonstrations/nested-env.tex}{\texttt{nested-env.tex}}{lst:nested-env}
Let's use the YAML settings given in \cref{lst:nested-env-mlb1-yaml}, which upon running
- the command
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
+ the command \index{switches!-l demonstration} \index{switches!-m demonstration}
\begin{commandshell}
latexindent.pl -m -l=nested-env-mlb1.yaml nested-env.tex
\end{commandshell}
@@ -1054,15 +1013,13 @@ latexindent.pl -m -l=nested-env-mlb1.yaml nested-env.tex
\begin{itemize}
\item the \texttt{two} environment is found first, and the line break ahead of the
\lstinline!\end{two}! statement is removed because \texttt{EndStartsOnOwnLine} is set to
- $-1$. Importantly, because, \emph{at this stage},
- \lstinline!\end{two}! \emph{does} finish with a line break,
- \texttt{EndFinishesWithLineBreak} causes no action.
+ $-1$. Importantly, because, \emph{at this stage}, \lstinline!\end{two}! \emph{does}
+ finish with a line break, \texttt{EndFinishesWithLineBreak} causes no action.
\item next, the \texttt{one} environment is found; the line break ahead of
- \lstinline!\end{one}! is removed because \texttt{EndStartsOnOwnLine} is set to
- $-1$.
+ \lstinline!\end{one}! is removed because \texttt{EndStartsOnOwnLine} is set to $-1$.
\end{itemize}
The indentation is done in Phase 2; in Phase 3 \emph{there is no option to add a line
- break after the \lstinline!end! statements}. We can justify this by remembering that
+ break after the \lstinline!end! statements}. We can justify this by remembering that
during Phase 3, the \texttt{one} environment will be found and processed first, followed
by the \texttt{two} environment. If the \texttt{two} environment were to add a line break
after the
@@ -1071,9 +1028,7 @@ latexindent.pl -m -l=nested-env-mlb1.yaml nested-env.tex
\lstinline!\end{one}!).
We can explore this further using the poly-switches in \cref{lst:nested-env-mlb2}; upon
- running the command
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
+ running the command \index{switches!-l demonstration} \index{switches!-m demonstration}
\begin{commandshell}
latexindent.pl -m -l=nested-env-mlb2.yaml nested-env.tex
\end{commandshell}
@@ -1087,15 +1042,14 @@ latexindent.pl -m -l=nested-env-mlb2.yaml nested-env.tex
During Phase 1:
\begin{itemize}
\item the \texttt{two} environment is found first, and the line break ahead of the
- \lstinline!\end{two}! statement is not changed because \texttt{EndStartsOnOwnLine} is
- set to $1$. Importantly, because, \emph{at this stage},
- \lstinline!\end{two}! \emph{does} finish with a line break,
- \texttt{EndFinishesWithLineBreak} causes no action.
+ \lstinline!\end{two}! statement is not changed because \texttt{EndStartsOnOwnLine} is set
+ to $1$. Importantly, because, \emph{at this stage}, \lstinline!\end{two}! \emph{does}
+ finish with a line break, \texttt{EndFinishesWithLineBreak} causes no action.
\item next, the \texttt{one} environment is found; the line break ahead of
\lstinline!\end{one}! is already present, and no action is needed.
\end{itemize}
The indentation is done in Phase 2, and then in Phase 3, the \texttt{one} environment is
found and processed first, followed by the \texttt{two} environment. \emph{At this
- stage}, the \texttt{two} environment finds \texttt{EndFinishesWithLineBreak} is $-1$, so
+ stage}, the \texttt{two} environment finds \texttt{EndFinishesWithLineBreak} is $-1$, so
it removes the trailing line break; remember, at this point, \texttt{latexindent.pl} has
completely finished with the \texttt{one} environment.
diff --git a/support/latexindent/documentation/subsec-remove-para-line-breaks.tex b/support/latexindent/documentation/subsec-remove-para-line-breaks.tex
deleted file mode 100644
index b4572468f9..0000000000
--- a/support/latexindent/documentation/subsec-remove-para-line-breaks.tex
+++ /dev/null
@@ -1,224 +0,0 @@
-% arara: pdflatex: { files: [latexindent]}
-\subsection{removeParagraphLineBreaks: modifying line breaks for paragraphs}\label{subsec:removeparagraphlinebreaks} When the \texttt{-m} switch is active
- \texttt{latexindent.pl} has the ability to remove line
- breaks%
- \announce{2017-05-27}{removeParagraphLineBreaks}
- from within paragraphs; the behaviour is controlled by the
- \texttt{removeParagraphLineBreaks} field, detailed in
- \cref{lst:removeParagraphLineBreaks}. Thank you to \cite{jowens} for shaping and
- assisting with the testing of this feature.
-\yamltitle{removeParagraphLineBreaks}*{fields}
- This feature is considered complimentary to the \texttt{oneSentencePerLine} feature
- described in \vref{sec:onesentenceperline}.
- \index{specialBeginEnd!removeParagraphLineBreaks}
-
- \cmhlistingsfromfile[style=removeParagraphLineBreaks]{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{removeParagraphLineBreaks}}{lst:removeParagraphLineBreaks}
-
- This routine can be turned on \emph{globally} for \emph{every} code block type known to
- \texttt{latexindent.pl} (see \vref{tab:code-blocks}) by using the \texttt{all} switch; by
- default, this switch is \emph{off}. Assuming that the \texttt{all} switch is off, then
- the routine can be controlled on a per-code-block-type basis, and within that, on a
- per-name basis. We will consider examples of each of these in turn, but before we do,
- let's specify what \texttt{latexindent.pl} considers as a paragraph:
- \begin{itemize}
- \item it must begin on its own line with either an alphabetic or numeric character, and not
- with any of the code-block types detailed in \vref{tab:code-blocks};
- \item it can include line breaks, but finishes when it meets either a blank line, a
- \lstinline!\par! command, or any of the user-specified settings in the
- \texttt{paragraphsStopAt} field, detailed in \vref{lst:paragraphsStopAt}.
- \end{itemize}
-
- Let's start with the \texttt{.tex} file in \cref{lst:shortlines}, together with the YAML
- settings in \cref{lst:remove-para1-yaml}.
-
- \begin{cmhtcbraster}
- \cmhlistingsfromfile[showspaces=true]{demonstrations/shortlines.tex}{\texttt{shortlines.tex}}{lst:shortlines}
- \cmhlistingsfromfile{demonstrations/remove-para1.yaml}[MLB-TCB]{\texttt{remove-para1.yaml}}{lst:remove-para1-yaml}
- \end{cmhtcbraster}
-
- Upon running the command
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \index{switches!-o demonstration}
- \begin{commandshell}
-latexindent.pl -m shortlines.tex -o shortlines1.tex -l remove-para1.yaml
-\end{commandshell}
- then we obtain the output given in \cref{lst:shortlines1}.
-
- \cmhlistingsfromfile[showspaces=true]{demonstrations/shortlines1.tex}{\texttt{shortlines1.tex}}{lst:shortlines1}
-
- Keen readers may notice that some trailing white space must be present in the file in
- \cref{lst:shortlines} which has crept in to the output in \cref{lst:shortlines1}. This
- can be fixed using the YAML file in \vref{lst:removeTWS-before} and running, for example,
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \index{switches!-o demonstration}
- \begin{commandshell}
-latexindent.pl -m shortlines.tex -o shortlines1-tws.tex -l remove-para1.yaml,removeTWS-before.yaml
-\end{commandshell}
- in which case the output is as in \cref{lst:shortlines1-tws}; notice that the double
- spaces present in \cref{lst:shortlines1} have been addressed.
-
- \cmhlistingsfromfile[showspaces=true]{demonstrations/shortlines1-tws.tex}{\texttt{shortlines1-tws.tex}}{lst:shortlines1-tws}
-
- Keeping with the settings in \cref{lst:remove-para1-yaml}, we note that the \texttt{all}
- switch applies to \emph{all} code block types. So, for example, let's consider the files
- in \cref{lst:shortlines-mand,lst:shortlines-opt}
-
- \begin{cmhtcbraster}
- \cmhlistingsfromfile{demonstrations/shortlines-mand.tex}{\texttt{shortlines-mand.tex}}{lst:shortlines-mand}
- \cmhlistingsfromfile{demonstrations/shortlines-opt.tex}{\texttt{shortlines-opt.tex}}{lst:shortlines-opt}
- \end{cmhtcbraster}
-
- Upon running the commands
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \index{switches!-o demonstration}
- \begin{widepage}
- \begin{commandshell}
-latexindent.pl -m shortlines-mand.tex -o shortlines-mand1.tex -l remove-para1.yaml
-latexindent.pl -m shortlines-opt.tex -o shortlines-opt1.tex -l remove-para1.yaml
-\end{commandshell}
- \end{widepage}
-
- then we obtain the respective output given in
- \cref{lst:shortlines-mand1,lst:shortlines-opt1}.
-
- \cmhlistingsfromfile{demonstrations/shortlines-mand1.tex}{\texttt{shortlines-mand1.tex}}{lst:shortlines-mand1}
- \cmhlistingsfromfile{demonstrations/shortlines-opt1.tex}{\texttt{shortlines-opt1.tex}}{lst:shortlines-opt1}
-
- Assuming that we turn \emph{off} the \texttt{all} switch (by setting it to \texttt{0}),
- then we can control the behaviour of \texttt{removeParagraphLineBreaks} either on a
- per-code-block-type basis, or on a per-name basis.
-
- For example, let's use the code in \cref{lst:shortlines-envs}, and consider the settings
- in \cref{lst:remove-para2-yaml,lst:remove-para3-yaml}; note that in
- \cref{lst:remove-para2-yaml} we specify that \emph{every} environment should receive
- treatment from the routine, while in \cref{lst:remove-para3-yaml} we specify that
- \emph{only} the \texttt{one} environment should receive the treatment.
-
- \begin{minipage}{.45\linewidth}
- \cmhlistingsfromfile{demonstrations/shortlines-envs.tex}{\texttt{shortlines-envs.tex}}{lst:shortlines-envs}
- \end{minipage}
- \hfill
- \begin{minipage}{.49\linewidth}
- \cmhlistingsfromfile{demonstrations/remove-para2.yaml}[MLB-TCB]{\texttt{remove-para2.yaml}}{lst:remove-para2-yaml}
- \cmhlistingsfromfile{demonstrations/remove-para3.yaml}[MLB-TCB]{\texttt{remove-para3.yaml}}{lst:remove-para3-yaml}
- \end{minipage}
-
- Upon running the commands
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \index{switches!-o demonstration}
- \begin{widepage}
- \begin{commandshell}
-latexindent.pl -m shortlines-envs.tex -o shortlines-envs2.tex -l remove-para2.yaml
-latexindent.pl -m shortlines-envs.tex -o shortlines-envs3.tex -l remove-para3.yaml
-\end{commandshell}
- \end{widepage}
- then we obtain the respective output given in
- \cref{lst:shortlines-envs2,lst:shortlines-envs3}.
-
- \cmhlistingsfromfile{demonstrations/shortlines-envs2.tex}{\texttt{shortlines-envs2.tex}}{lst:shortlines-envs2}
- \cmhlistingsfromfile{demonstrations/shortlines-envs3.tex}{\texttt{shortlines-envs3.tex}}{lst:shortlines-envs3}
-
- The remaining code-block types can be customised in analogous ways, although note that
- \texttt{commands}, \texttt{keyEqualsValuesBracesBrackets},
- \texttt{namedGroupingBracesBrackets}, \texttt{UnNamedGroupingBracesBrackets} are
- controlled by the \texttt{optionalArguments} and the \texttt{mandatoryArguments}.
-
- 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}
- \end{cmhtcbraster}
-
- Upon running the following command
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \index{switches!-o demonstration}
- \begin{widepage}
- \begin{commandshell}
-latexindent.pl -m shortlines-md.tex -o shortlines-md4.tex -l remove-para4.yaml
-\end{commandshell}
- \end{widepage}
- then we obtain the output in \cref{lst:shortlines-md4}.
- \cmhlistingsfromfile{demonstrations/shortlines-md4.tex}{\texttt{shortlines-md4.tex}}{lst:shortlines-md4}
-
- Note%
- \announce{2018-08-13}*{updates to all in removeParagraphLineBreaks} that the \texttt{all} field can take the same exceptions
- detailed in \crefrange{lst:textwrap6-yaml}{lst:textwrap8-yaml}.
-
-\yamltitle{paragraphsStopAt}*{fields}
- The paragraph line break routine considers blank lines and the
- \lstinline|\par| command to be the end of a paragraph;
- \announce{2017-05-27}{paragraphsStopAt} you can fine tune the behaviour of the routine
- further by using the \texttt{paragraphsStopAt} fields, shown in
- \cref{lst:paragraphsStopAt}.
- \index{specialBeginEnd!paragraphsStopAt}
- \index{verbatim!in relation to paragraphsStopAt}
-
- \cmhlistingsfromfile[style=paragraphsStopAt]{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{paragraphsStopAt}}{lst:paragraphsStopAt}
-
- The fields specified in \texttt{paragraphsStopAt} tell \texttt{latexindent.pl} to stop
- the current paragraph when it reaches a line that \emph{begins} with any of the
- code-block types specified as \texttt{1} in \cref{lst:paragraphsStopAt}. By default,
- you'll see that the paragraph line break routine will stop when it reaches an environment
- or verbatim code block at the beginning of a line. It is \emph{not} possible to specify
- these fields on a per-name basis.
-
- Let's use the \texttt{.tex} file in \cref{lst:sl-stop}; we will, in turn, consider the
- settings in \cref{lst:stop-command-yaml,lst:stop-comment-yaml}.
-
- \begin{minipage}{.45\linewidth}
- \cmhlistingsfromfile{demonstrations/sl-stop.tex}{\texttt{sl-stop.tex}}{lst:sl-stop}
- \end{minipage}
- \hfill
- \begin{minipage}{.49\linewidth}
- \cmhlistingsfromfile{demonstrations/stop-command.yaml}[MLB-TCB]{\texttt{stop-command.yaml}}{lst:stop-command-yaml}
-
- \cmhlistingsfromfile{demonstrations/stop-comment.yaml}[MLB-TCB]{\texttt{stop-comment.yaml}}{lst:stop-comment-yaml}
- \end{minipage}
-
- Upon using the settings from \vref{lst:remove-para4-yaml} and running the commands
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \index{switches!-o demonstration}
- \begin{widepage}
- \begin{commandshell}
-latexindent.pl -m sl-stop.tex -o sl-stop4.tex -l remove-para4.yaml
-latexindent.pl -m sl-stop.tex -o sl-stop4-command.tex -l=remove-para4.yaml,stop-command.yaml
-latexindent.pl -m sl-stop.tex -o sl-stop4-comment.tex -l=remove-para4.yaml,stop-comment.yaml
-\end{commandshell}
- \end{widepage}
- we obtain the respective outputs in \crefrange{lst:sl-stop4}{lst:sl-stop4-comment};
- notice in particular that:
- \begin{itemize}
- \item in \cref{lst:sl-stop4} the paragraph line break routine has included commands and
- comments;
- \item in \cref{lst:sl-stop4-command} the paragraph line break routine has \emph{stopped} at the
- \texttt{emph} command, because in \cref{lst:stop-command-yaml} we have specified
- \texttt{commands} to be \texttt{1}, and \texttt{emph} is at the beginning of a line;
- \item in \cref{lst:sl-stop4-comment} the paragraph line break routine has \emph{stopped} at the
- comments, because in \cref{lst:stop-comment-yaml} we have specified \texttt{comments} to
- be \texttt{1}, and the comment is at the beginning of a line.
- \end{itemize}
- In all outputs in \crefrange{lst:sl-stop4}{lst:sl-stop4-comment} we notice that the
- paragraph line break routine has stopped at \lstinline!\begin{myenv}! because, by
- default, \texttt{environments} is set to \texttt{1} in \vref{lst:paragraphsStopAt}.
-
- \cmhlistingsfromfile{demonstrations/sl-stop4.tex}{\texttt{sl-stop4.tex}}{lst:sl-stop4}
- \cmhlistingsfromfile{demonstrations/sl-stop4-command.tex}{\texttt{sl-stop4-command.tex}}{lst:sl-stop4-command}
- \cmhlistingsfromfile{demonstrations/sl-stop4-comment.tex}{\texttt{sl-stop4-comment.tex}}{lst:sl-stop4-comment}
-
diff --git a/support/latexindent/documentation/subsec-text-wrap-summary.tex b/support/latexindent/documentation/subsec-text-wrap-summary.tex
deleted file mode 100644
index 99b9975a2a..0000000000
--- a/support/latexindent/documentation/subsec-text-wrap-summary.tex
+++ /dev/null
@@ -1,26 +0,0 @@
-% arara: pdflatex: { files: [latexindent]}
-\subsection{Summary of text wrapping}
- I consider%
- \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}.
-
- Starting from \cref{lst:textwrap-qs-yaml}, it is likely that you will have to experiment
- with making adjustments (such as that given in \cref{lst:textwrap14-yaml}) depending on
- your preference.
-
- It is important to note the following:
- \index{verbatim!within summary of text wrapping}
- \begin{itemize}
- \item verbatim code blocks of all types will \emph{not} be affected by the text wrapping
- routine. See the demonstration in \vref{lst:textwrap2-mod1}, together with environments:
- \vref{lst:verbatimEnvironments}, commands: \vref{lst:verbatimCommands},
- \texttt{noIndentBlock}: \cref{lst:noIndentBlock}, \texttt{specialBeginEnd}:
- \vref{lst:special3-mod1};
- \item comments will \emph{not} be affected by the text wrapping routine (see
- \vref{lst:textwrap3-mod1});
- \item it is possible to wrap text on a per-code-block and a per-name basis;
- \announce{2018-08-13}*{updates to textWrapOptions}
- \item indentation is performed \emph{after} the text wrapping routine; as such, indented code
- will likely exceed any maximum value set in the \texttt{columns} field.
- \end{itemize}
diff --git a/support/latexindent/documentation/subsec-text-wrap.tex b/support/latexindent/documentation/subsec-text-wrap.tex
index 64eea3f1ab..2b4c96539e 100644
--- a/support/latexindent/documentation/subsec-text-wrap.tex
+++ b/support/latexindent/documentation/subsec-text-wrap.tex
@@ -1,131 +1,372 @@
% arara: pdflatex: { files: [latexindent]}
\subsection{Text Wrapping}\label{subsec:textwrapping}
- There are \emph{many} different configuration options for the text wrapping routine of
- \texttt{latexindent.pl}, perhaps \emph{too} many. The following sections are
- comprehensive, but quite long; in an attempt to to be brief, you might begin with the
- settings given in \cref{subsec:textwrapping-quick-start}.
+ \announce*{2022-03-13}{text wrap overhaul}\emph{The text wrapping routine has been over-hauled as
+ of V3.16; I hope that the interface is simpler, and most importantly, the results are
+ better}.
+
+ The complete settings for this feature are given in \cref{lst:textWrapOptionsAll}.
+
+ \cmhlistingsfromfile*[style=textWrapOptionsAll]{../defaultSettings.yaml}[MLB-TCB,width=.95\linewidth,before=\centering]{\texttt{textWrapOptions}}{lst:textWrapOptionsAll}
+
+\subsubsection{Text wrap: overview}
+ An overview of how the text wrapping feature works:
+ \begin{enumerate}
+ \item the default value of \texttt{columns} is 0, which means that text wrapping will
+ \emph{not} happen by default;
+ \item it happens \emph{after} verbatim blocks have been found;
+ \item it happens \emph{after} the oneSentencePerLine routine (see
+ \cref{sec:onesentenceperline});
+ \item it happens \emph{before} all of the other code blocks are found and does \emph{not}
+ operate on a per-code-block basis;
+ \item code blocks to be text wrapped will:
+ \begin{enumerate}
+ \item \emph{follow} the fields specified in \texttt{blocksFollow}
+ \item \emph{begin} with the fields specified in \texttt{blocksBeginWith}
+ \item \emph{end} before the fields specified in \texttt{blocksEndBefore}
+ \end{enumerate}
+ \item setting \texttt{columns} to a value $>0$ will text wrap blocks by first removing line
+ breaks, and then wrapping according to the specified value of \texttt{columns};
+ \item setting \texttt{columns} to $-1$ will \emph{only} remove line breaks within the text wrap
+ block.
+ \end{enumerate}
+
+ We demonstrate this feature using a series of examples.
+
+\subsubsection{Text wrap: simple examples}\label{subsec:textwrapping-quick-start}
+
+ \begin{example}
+ Let's use the sample text given in \cref{lst:textwrap1}. \index{text wrap!quick start}
+
+ \cmhlistingsfromfile*{demonstrations/textwrap1.tex}{\texttt{textwrap1.tex}}{lst:textwrap1}
+
+ We will change the value of \texttt{columns} in \cref{lst:textwrap1-yaml} and then run
+ the command
+ \begin{commandshell}
+latexindent.pl -m -l textwrap1.yaml textwrap1.tex
+\end{commandshell}
+ then we receive the output given in \cref{lst:textwrap1-mod1}.
-\subsubsection{Text wrap quick start}\label{subsec:textwrapping-quick-start}
+ \begin{cmhtcbraster}[raster column skip=.1\linewidth]
+ \cmhlistingsfromfile*{demonstrations/textwrap1-mod1.tex}{\texttt{textwrap1-mod1.tex}}{lst:textwrap1-mod1}
+ \cmhlistingsfromfile*{demonstrations/textwrap1.yaml}[MLB-TCB]{\texttt{textwrap1.yaml}}{lst:textwrap1-yaml}
+ \end{cmhtcbraster}
+ \end{example}
- Of all the available text wrapping options, I consider \cref{lst:textwrap-qs-yaml} to be
- among the most helpful starting points.
+ \begin{example}
+ If we set \texttt{columns} to $-1$ then \texttt{latexindent.pl} remove line breaks within
+ the text wrap block, and will \emph{not} perform text wrapping. We can use this to undo
+ text wrapping. \index{text wrap!setting columns to -1}
- \cmhlistingsfromfile{demonstrations/textwrap-qs.yaml}[MLB-TCB,width=1\linewidth]{\texttt{textwrap-qs.yaml}}{lst:textwrap-qs-yaml}
+ Starting from the file in \cref{lst:textwrap1-mod1} and using the settings in
+ \cref{lst:textwrap1A-yaml}
- \index{text wrap!quick start}
+ \cmhlistingsfromfile*{demonstrations/textwrap1A.yaml}[MLB-TCB]{\texttt{textwrap1A.yaml}}{lst:textwrap1A-yaml}
- You can read about \texttt{perCodeBlockBasis} in \cref{subsec:text-wrap-per-code-block}
- and \texttt{removeParagraphLineBreaks} in \cref{subsec:removeparagraphlinebreaks}.
+ and running
+ \begin{commandshell}
+latexindent.pl -m -l textwrap1A.yaml textwrap1-mod1.tex
+\end{commandshell}
+ gives the output in \cref{lst:textwrap1-mod1A}.
- If the settings in \cref{lst:textwrap-qs-yaml} do not give your desired output, take a
- look at the demonstration in \cref{subsubsec:text-wrap-remove-para-bfccb}, in particular
- \cref{lst:textwrap-bfccb-mod14}.
+ \cmhlistingsfromfile*{demonstrations/textwrap1-mod1A.tex}{\texttt{textwrap1-mod1A.tex}}{lst:textwrap1-mod1A}
+ \end{example}
-\subsubsection{textWrapOptions: modifying line breaks by text wrapping}
+ \begin{example}
+ By default, the text wrapping routine will convert multiple spaces into single spaces.
+ You can change this behaviour by flicking the switch \texttt{multipleSpacesToSingle}
+ which we have done in \cref{lst:textwrap1B-yaml}
- When the \texttt{-m} switch is active \texttt{latexindent.pl} has the ability to wrap
- text using the options%
- \announce{2017-05-27}{textWrapOptions} specified in the \texttt{textWrapOptions} field,
- see \cref{lst:textWrapOptions}.
+ Using the settings in \cref{lst:textwrap1B-yaml} and running
+ \begin{commandshell}
+latexindent.pl -m -l textwrap1B.yaml textwrap1-mod1.tex
+\end{commandshell}
+ gives the output in \cref{lst:textwrap1-mod1B}.
+ \begin{cmhtcbraster}[raster column skip=.1\linewidth]
+ \cmhlistingsfromfile*{demonstrations/textwrap1B.yaml}[MLB-TCB]{\texttt{textwrap1B.yaml}}{lst:textwrap1B-yaml}
+ \cmhlistingsfromfile*[showspaces=true]{demonstrations/textwrap1-mod1B.tex}{\texttt{textwrap1-mod1B.tex}}{lst:textwrap1-mod1B}
+ \end{cmhtcbraster}
+ We note that in \cref{lst:textwrap1-mod1B} the multiple spaces have \emph{not} been condensed into single spaces.
+ \end{example}
+
+\subsubsection{Text wrap: \texttt{blocksFollow} examples}
+ We examine the \texttt{blocksFollow} field of \cref{lst:textWrapOptionsAll}. \index{text
+ wrap!blocksFollow}
+
+ \begin{example}[label={example:tw:headings}]
+ Let's use the sample text given in \cref{lst:tw-headings1}. \index{text
+ wrap!blocksFollow!headings}
+
+ \cmhlistingsfromfile*{demonstrations/tw-headings1.tex}{\texttt{tw-headings1.tex}}{lst:tw-headings1}
+
+ We note that \cref{lst:tw-headings1} contains the heading commands \texttt{section} and
+ \texttt{subsection}. Upon running the command
+ \begin{commandshell}
+latexindent.pl -m -l textwrap1.yaml tw-headings1.tex
+\end{commandshell}
+ then we receive the output given in \cref{lst:tw-headings1-mod1}.
+
+ \cmhlistingsfromfile*{demonstrations/tw-headings1-mod1.tex}{\texttt{tw-headings1-mod1.tex}}{lst:tw-headings1-mod1}
+
+ We reference \vref{lst:textWrapOptionsAll} and also \vref{lst:indentAfterHeadings}:
+ \begin{itemize}
+ \item in \cref{lst:textWrapOptionsAll} the \texttt{headings} field is set to \texttt{1}, which
+ instructs \texttt{latexindent.pl} to read the fields from \vref{lst:indentAfterHeadings},
+ \emph{regardless of the value of indentAfterThisHeading or level};
+ \item the default is to assume that the heading command can, optionally, be followed by a
+ \texttt{label} command.
+ \end{itemize}
+ If you find scenarios in which the default value of \texttt{headings} does not work, then you
+ can explore the \texttt{other} field.
+
+ We can turn off \texttt{headings} as in \cref{lst:bf-no-headings-yaml} and then run
+ \begin{commandshell}
+latexindent.pl -m -l textwrap1.yaml,bf-no-headings.yaml tw-headings1.tex
+\end{commandshell}
+ gives the output in \cref{lst:tw-headings1-mod2}, in which text wrapping has been
+ instructed \emph{not to happen} following headings.
+ \begin{cmhtcbraster}[raster column skip=.1\linewidth,
+ raster left skip=-3.5cm,
+ raster right skip=-2cm,
+ ]
+ \cmhlistingsfromfile*{demonstrations/bf-no-headings.yaml}[MLB-TCB]{\texttt{bf-no-headings.yaml}}{lst:bf-no-headings-yaml}
+ \cmhlistingsfromfile*{demonstrations/tw-headings1-mod2.tex}{\texttt{tw-headings1-mod2.tex}}{lst:tw-headings1-mod2}
+ \end{cmhtcbraster}
+ \end{example}
+
+ \begin{example}[label={example:tw:comments}]
+ Let's use the sample text given in \cref{lst:tw-comments1}. \index{text wrap!blocksFollow!comments}
+
+ \cmhlistingsfromfile*{demonstrations/tw-comments1.tex}{\texttt{tw-comments1.tex}}{lst:tw-comments1}
+
+ We note that \cref{lst:tw-comments1} contains trailing comments. Upon running the command
+ \begin{commandshell}
+latexindent.pl -m -l textwrap1.yaml tw-comments1.tex
+\end{commandshell}
+ then we receive the output given in \cref{lst:tw-comments1-mod1}.
- \index{modifying linebreaks! by text wrapping, globally}
+ \cmhlistingsfromfile*{demonstrations/tw-comments1-mod1.tex}{\texttt{tw-comments1-mod1.tex}}{lst:tw-comments1-mod1}
- \cmhlistingsfromfile[style=textWrapOptions]{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{textWrapOptions}}{lst:textWrapOptions}
+ With reference to \vref{lst:textWrapOptionsAll} the \texttt{commentOnPreviousLine} field
+ is set to \texttt{1}, which instructs \texttt{latexindent.pl} to find text wrap blocks
+ after a comment on its own line.
- The value of \texttt{columns} specifies the column at which the text should be wrapped.
+ We can turn off \texttt{comments} as in \cref{lst:bf-no-comments-yaml} and then run
+ \begin{commandshell}
+latexindent.pl -m -l textwrap1.yaml,bf-no-comments.yaml tw-comments1.tex
+\end{commandshell}
+ gives the output in \cref{lst:tw-comments1-mod2}, in which text wrapping has been
+ instructed \emph{not to happen} following comments on their own line.
+ \begin{cmhtcbraster}[raster column skip=.1\linewidth,
+ raster left skip=-3.5cm,
+ raster right skip=-2cm,
+ ]
+ \cmhlistingsfromfile*{demonstrations/bf-no-comments.yaml}[MLB-TCB]{\texttt{bf-no-comments.yaml}}{lst:bf-no-comments-yaml}
+ \cmhlistingsfromfile*{demonstrations/tw-comments1-mod2.tex}{\texttt{tw-comments1-mod2.tex}}{lst:tw-comments1-mod2}
+ \end{cmhtcbraster}
+ \end{example}
+
+ Referencing \vref{lst:textWrapOptionsAll} the \texttt{blocksFollow} fields \texttt{par},
+ \texttt{blankline}, \texttt{verbatim} and \texttt{filecontents} fields operate in
+ analogous ways to those demonstrated in the above.
+
+ The \texttt{other} field of the \texttt{blocksFollow} can either be \texttt{0} (turned
+ off) or set as a regular expression. The default value is set to
+ \lstinline!\\\]|\\item(?:\h|\[)! which can be translated to \emph{backslash followed by a
+ square bracket} or \emph{backslash item followed by horizontal space or a square
+ bracket}, or in other words, \emph{end of display math} or an item command.
+
+ \begin{example}
+ Let's use the sample text given in \cref{lst:tw-disp-math1}. \index{text
+ wrap!blocksFollow!other} \index{regular expressions!text wrap!blocksFollow}
+
+ \cmhlistingsfromfile*{demonstrations/tw-disp-math1.tex}{\texttt{tw-disp-math1.tex}}{lst:tw-disp-math1}
+
+ We note that \cref{lst:tw-disp-math1} contains display math. Upon running the command
+ \begin{commandshell}
+latexindent.pl -m -l textwrap1.yaml tw-disp-math1.tex
+\end{commandshell}
+ then we receive the output given in \cref{lst:tw-disp-math1-mod1}.
- By default, the value of \texttt{columns} is \texttt{0}, so \texttt{latexindent.pl} will
- \emph{not} wrap text; if you change it to a value of \texttt{2} or more, then text will
- be wrapped after the character in the specified column.
+ \cmhlistingsfromfile*{demonstrations/tw-disp-math1-mod1.tex}{\texttt{tw-disp-math1-mod1.tex}}{lst:tw-disp-math1-mod1}
- By default, the text wrapping routine will operate \emph{before} the code blocks have
- been searched for; text wrapping on a \emph{per-code-block} basis is discussed in
- \cref{subsec:text-wrap-per-code-block}.
+ With reference to \vref{lst:textWrapOptionsAll} the \texttt{other} field is set to
+ \lstinline!\\\]!, which instructs \texttt{latexindent.pl} to find text wrap blocks after
+ the end of display math.
- We consider the file give in \cref{lst:textwrap1} for demonstration.
+ We can turn off this switch as in \cref{lst:bf-no-disp-math-yaml} and then run
+ \begin{widepage}
+ \begin{commandshell}
+latexindent.pl -m -l textwrap1.yaml,bf-no-disp-math.yaml tw-disp-math1.tex
+\end{commandshell}
+ \end{widepage}
+ gives the output in \cref{lst:tw-disp-math1-mod2}, in which text wrapping has been
+ instructed \emph{not to happen} following display math.
+ \begin{cmhtcbraster}[raster column skip=.1\linewidth]
+ \cmhlistingsfromfile*{demonstrations/bf-no-disp-math.yaml}[MLB-TCB]{\texttt{bf-no-disp-math.yaml}}{lst:bf-no-disp-math-yaml}
+ \cmhlistingsfromfile*{demonstrations/tw-disp-math1-mod2.tex}{\texttt{tw-disp-math1-mod2.tex}}{lst:tw-disp-math1-mod2}
+ \end{cmhtcbraster}
+
+ Naturally, you should feel encouraged to customise this as you see fit.
+ \end{example}
+
+ The \texttt{blocksFollow} field \emph{deliberately} does not default to allowing text
+ wrapping to occur after \texttt{begin environment} statements. You are encouraged to
+ customize the \texttt{other} field to accomodate the environments that you would like to
+ text wrap individually, as in the next example.
+
+ \begin{example}
+ Let's use the sample text given in \cref{lst:tw-bf-myenv1}. \index{text
+ wrap!blocksFollow!other} \index{regular expressions!text wrap!blocksFollow}
+
+ \cmhlistingsfromfile*{demonstrations/tw-bf-myenv1.tex}{\texttt{tw-bf-myenv1.tex}}{lst:tw-bf-myenv1}
+
+ We note that \cref{lst:tw-bf-myenv1} contains \texttt{myenv} environment. Upon running
+ the command
+ \begin{commandshell}
+latexindent.pl -m -l textwrap1.yaml tw-bf-myenv1.tex
+\end{commandshell}
+ then we receive the output given in \cref{lst:tw-bf-myenv1-mod1}.
- \begin{widepage}
- \cmhlistingsfromfile{demonstrations/textwrap1.tex}{\texttt{textwrap1.tex}}{lst:textwrap1}
- \end{widepage}
+ \cmhlistingsfromfile*{demonstrations/tw-bf-myenv1-mod1.tex}{\texttt{tw-bf-myenv1-mod1.tex}}{lst:tw-bf-myenv1-mod1}
- Using the file \texttt{textwrap1.yaml} in \cref{lst:textwrap1-yaml}, and running the
- command
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \index{switches!-o demonstration}
- \begin{commandshell}
-latexindent.pl -m textwrap1.tex -o textwrap1-mod1.tex -l textwrap1.yaml
+ We note that we have \emph{not} received much text wrapping. We can turn do better by
+ employing \cref{lst:tw-bf-myenv-yaml} and then run
+ \begin{commandshell}
+latexindent.pl -m -l textwrap1.yaml,tw-bf-myenv.yaml tw-bf-myenv1.tex
+\end{commandshell}
+ which gives the output in \cref{lst:tw-bf-myenv1-mod2}, in which text wrapping has been
+ implemented across the file.
+ \begin{cmhtcbraster}[raster column skip=.1\linewidth,
+ raster left skip=-3.5cm,
+ raster right skip=-2cm,
+ ]
+ \cmhlistingsfromfile*{demonstrations/tw-bf-myenv.yaml}[MLB-TCB]{\texttt{tw-bf-myenv.yaml}}{lst:tw-bf-myenv-yaml}
+ \cmhlistingsfromfile*{demonstrations/tw-bf-myenv1-mod2.tex}{\texttt{tw-bf-myenv1-mod2.tex}}{lst:tw-bf-myenv1-mod2}
+ \end{cmhtcbraster}
+
+ \end{example}
+
+\subsubsection{Text wrap: \texttt{blocksBeginWith} examples}
+ We examine the \texttt{blocksBeginWith} field of \cref{lst:textWrapOptionsAll} with a
+ series of examples. \index{text wrap!blocksBeginWith}
+
+ \begin{example}
+ By default, text wrap blocks can begin with the characters \texttt{a-z} and \texttt{A-Z}.
+
+ If we start with the file given in \cref{lst:tw-0-9}
+ \cmhlistingsfromfile*{demonstrations/tw-0-9.tex}{\texttt{tw-0-9.tex}}{lst:tw-0-9}
+ and run the command
+ \begin{commandshell}
+latexindent.pl -m -l textwrap1.yaml tw-0-9.tex
+\end{commandshell}
+ then we receive the output given in \cref{lst:tw-0-9-mod1} in which text wrapping has
+ \emph{not} occured.
+ \cmhlistingsfromfile*{demonstrations/tw-0-9-mod1.tex}{\texttt{tw-0-9-mod1.tex}}{lst:tw-0-9-mod1}
+
+ We can allow paragraphs to begin with \texttt{0-9} characters by using the settings in
+ \cref{lst:bb-0-9-yaml} and running
+ \begin{commandshell}
+latexindent.pl -m -l textwrap1.yaml,bb-0-9-yaml tw-0-9.tex
+\end{commandshell}
+ gives the output in \cref{lst:tw-0-9-mod2}, in which text wrapping \emph{has} happened.
+ \begin{cmhtcbraster}[raster column skip=.1\linewidth,]
+ \cmhlistingsfromfile*{demonstrations/bb-0-9.yaml}[MLB-TCB]{\texttt{bb-0-9.yaml.yaml}}{lst:bb-0-9-yaml}
+ \cmhlistingsfromfile*{demonstrations/tw-0-9-mod2.tex}{\texttt{tw-0-9-mod2.tex}}{lst:tw-0-9-mod2}
+ \end{cmhtcbraster}
+ \end{example}
+
+ \begin{example}
+ Let's now use the file given in \cref{lst:tw-bb-announce1}
+ \cmhlistingsfromfile*{demonstrations/tw-bb-announce1.tex}{\texttt{tw-bb-announce1.tex}}{lst:tw-bb-announce1}
+ and run the command
+ \begin{commandshell}
+latexindent.pl -m -l textwrap1.yaml tw-bb-announce1.tex
\end{commandshell}
- we obtain the output in \cref{lst:textwrap1-mod1}.
+ then we receive the output given in \cref{lst:tw-bb-announce1-mod1} in which text
+ wrapping has \emph{not} occured.
- \begin{cmhtcbraster}[raster column skip=.1\linewidth]
- \cmhlistingsfromfile{demonstrations/textwrap1-mod1.tex}{\texttt{textwrap1-mod1.tex}}{lst:textwrap1-mod1}
- \cmhlistingsfromfile{demonstrations/textwrap1.yaml}[MLB-TCB]{\texttt{textwrap1.yaml}}{lst:textwrap1-yaml}
- \end{cmhtcbraster}
+ \cmhlistingsfromfile*{demonstrations/tw-bb-announce1-mod1.tex}{\texttt{tw-bb-announce1-mod1.tex}}{lst:tw-bb-announce1-mod1}
- The text wrapping routine is performed \emph{after} verbatim environments
- \index{verbatim!in relation to textWrapOptions} have been stored, so verbatim
- environments and verbatim commands are exempt from the routine. For example, using the
- file in \cref{lst:textwrap2},
- \begin{widepage}
- \cmhlistingsfromfile{demonstrations/textwrap2.tex}{\texttt{textwrap2.tex}}{lst:textwrap2}
- \end{widepage}
- and running the following command and continuing to use \texttt{textwrap1.yaml} from
- \cref{lst:textwrap1-yaml},
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \index{switches!-o demonstration}
- \begin{commandshell}
-latexindent.pl -m textwrap2.tex -o textwrap2-mod1.tex -l textwrap1.yaml
+ We can allow \lstinline!\announce! to be at the beginning of paragraphs by using the
+ settings in \cref{lst:tw-bb-announce-yaml} and running
+ \begin{widepage}
+ \begin{commandshell}
+latexindent.pl -m -l textwrap1.yaml,tw-bb-announce.yaml tw-bb-announce1.tex
\end{commandshell}
- then the output is as in \cref{lst:textwrap2-mod1}.
- \begin{widepage}
- \cmhlistingsfromfile{demonstrations/textwrap2-mod1.tex}{\texttt{textwrap2-mod1.tex}}{lst:textwrap2-mod1}
- \end{widepage}
- Furthermore, the text wrapping routine is performed after the trailing comments have been
- stored, and they are also exempt from text wrapping. For example, using the file in
- \cref{lst:textwrap3}
- \begin{widepage}
- \cmhlistingsfromfile{demonstrations/textwrap3.tex}{\texttt{textwrap3.tex}}{lst:textwrap3}
- \end{widepage}
- and running the following command and continuing to use \texttt{textwrap1.yaml} from
- \cref{lst:textwrap1-yaml},
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \index{switches!-o demonstration}
- \begin{commandshell}
-latexindent.pl -m textwrap3.tex -o textwrap3-mod1.tex -l textwrap1.yaml
+ \end{widepage}
+ gives the output in \cref{lst:tw-bb-announce1-mod2}, in which text wrapping \emph{has}
+ happened.
+ \begin{cmhtcbraster}[raster column skip=.1\linewidth,]
+ \cmhlistingsfromfile*{demonstrations/tw-bb-announce.yaml}[MLB-TCB]{\texttt{tw-bb-announce.yaml}}{lst:tw-bb-announce-yaml}
+ \cmhlistingsfromfile*{demonstrations/tw-bb-announce1-mod2.tex}{\texttt{tw-bb-announce1-mod2.tex}}{lst:tw-bb-announce1-mod2}
+ \end{cmhtcbraster}
+
+ \end{example}
+
+\subsubsection{Text wrap: \texttt{blocksEndBefore} examples}
+ We examine the \texttt{blocksEndBefore} field of \cref{lst:textWrapOptionsAll} with a
+ series of examples. \index{text wrap!blocksEndBefore}
+
+ \begin{example}
+ Let's use the sample text given in \cref{lst:tw-be-equation}. \index{text
+ wrap!blocksFollow!other} \index{regular expressions!text wrap!blocksFollow}
+
+ \cmhlistingsfromfile*{demonstrations/tw-be-equation.tex}{\texttt{tw-be-equation.tex}}{lst:tw-be-equation}
+
+ We note that \cref{lst:tw-be-equation} contains an environment. Upon running the command
+ \begin{commandshell}
+latexindent.pl -m -l textwrap1A.yaml tw-be-equation.tex
+\end{commandshell}
+ then we receive the output given in \cref{lst:tw-be-equation-mod1}.
+
+ \cmhlistingsfromfile*{demonstrations/tw-be-equation-mod1.tex}{\texttt{tw-be-equation-mod1.tex}}{lst:tw-be-equation-mod1}
+
+ With reference to \vref{lst:textWrapOptionsAll} the \texttt{other} field is set to
+ \lstinline!\\begin\{|\\\[|\\end\{!, which instructs \texttt{latexindent.pl} to
+ \emph{stop} text wrap blocks before \texttt{begin} statements, display math, and
+ \texttt{end} statements.
+
+ We can turn off this switch as in \cref{lst:tw-be-equation-yaml} and then run
+ \begin{widepage}
+ \begin{commandshell}
+latexindent.pl -m -l textwrap1A.yaml,tw-be-equation.yaml tw-be-equation.tex
\end{commandshell}
- then the output is as in \cref{lst:textwrap3-mod1}.
-
- \cmhlistingsfromfile{demonstrations/textwrap3-mod1.tex}{\texttt{textwrap3-mod1.tex}}{lst:textwrap3-mod1}
-
- The%
- \announce{2021-07-23}*{huge:overflow is now default}
- default value of \texttt{huge} is \texttt{overflow}, which means that words will
- \emph{not} be broken by the text wrapping routine, implemented by the \texttt{Text::Wrap}
- \cite{textwrap}. There are options to change the \texttt{huge} option for the
- \texttt{Text::Wrap} module to either \texttt{wrap} or \texttt{die}. Before modifying the
- value of \texttt{huge}, please bear in mind the following warning:
- \index{warning!changing huge (textwrap)}
+ \end{widepage}
+ gives the output in \cref{lst:tw-be-equation-mod2}, in which text wrapping has been
+ instructed \emph{not} to stop at these statements.
+
+ \cmhlistingsfromfile*{demonstrations/tw-be-equation.yaml}[MLB-TCB]{\texttt{tw-be-equation.yaml}}{lst:tw-be-equation-yaml}
+
+ \begin{widepage}
+ \cmhlistingsfromfile*{demonstrations/tw-be-equation-mod2.tex}{\texttt{tw-be-equation-mod2.tex}}{lst:tw-be-equation-mod2}
+ \end{widepage}
+
+ Naturally, you should feel encouraged to customise this as you see fit.
+ \end{example}
+
+\subsubsection{Text wrap: huge, tabstop and separator}
+ The \announce{2021-07-23}*{huge:overflow is now default} default value of \texttt{huge}
+ is \texttt{overflow}, which means that words will \emph{not} be broken by the text
+ wrapping routine, implemented by the \texttt{Text::Wrap} \cite{textwrap}. There are
+ options to change the \texttt{huge} option for the \texttt{Text::Wrap} module to either
+ \texttt{wrap} or \texttt{die}. Before modifying the value of \texttt{huge}, please bear
+ in mind the following warning: \index{warning!changing huge (textwrap)}%
\begin{warning}
\raggedright
Changing the value of \texttt{huge} to anything other than \texttt{overflow} will slow
down \texttt{latexindent.pl} significantly when the \texttt{-m} switch is active.
Furthermore, changing \texttt{huge} means that you may have some words \emph{or
- commands}(!) split across lines in your .tex file, which may affect your output. I do not
+ commands}(!) split across lines in your .tex file, which may affect your output. I do not
recommend changing this field.
\end{warning}
For example, using the settings in \cref{lst:textwrap2A-yaml,lst:textwrap2B-yaml} and
- running the commands
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
+ running the commands \index{switches!-l demonstration} \index{switches!-m demonstration}
\index{switches!-o demonstration}
\begin{commandshell}
-latexindent.pl -m textwrap4.tex -o=+-mod2A -l textwrap2A.yaml
-latexindent.pl -m textwrap4.tex -o=+-mod2B -l textwrap2B.yaml
+ latexindent.pl -m textwrap4.tex -o=+-mod2A -l textwrap2A.yaml
+ latexindent.pl -m textwrap4.tex -o=+-mod2B -l textwrap2B.yaml
\end{commandshell}
gives the respective output in \cref{lst:textwrap4-mod2A,lst:textwrap4-mod2B}.
@@ -137,16 +378,14 @@ latexindent.pl -m textwrap4.tex -o=+-mod2B -l textwrap2B.yaml
\cmhlistingsfromfile{demonstrations/textwrap2B.yaml}[MLB-TCB]{\texttt{textwrap2B.yaml}}{lst:textwrap2B-yaml}
\end{cmhtcbraster}
- You can also specify the \texttt{tabstop} field%
- \announce{2020-11-06}{tabstop option for text wrap module} as an integer value, which is
- passed to the text wrap module; see \cite{textwrap} for details. Starting with the code
- in \cref{lst:textwrap-ts} with settings in \cref{lst:tabstop}, and running the command
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \index{switches!-o demonstration}
+ You can also specify the \texttt{tabstop} field \announce{2020-11-06}{tabstop option for
+ text wrap module} as an integer value, which is passed to the text wrap module; see
+ \cite{textwrap} for details. Starting with the code in \cref{lst:textwrap-ts} with
+ settings in \cref{lst:tabstop}, and running the command \index{switches!-l demonstration}
+ \index{switches!-m demonstration} \index{switches!-o demonstration}%
\begin{commandshell}
-latexindent.pl -m textwrap-ts.tex -o=+-mod1 -l tabstop.yaml
-\end{commandshell}
+ latexindent.pl -m textwrap-ts.tex -o=+-mod1 -l tabstop.yaml
+ \end{commandshell}
gives the code given in \cref{lst:textwrap-ts-mod1}.
\begin{cmhtcbraster}[raster columns=3,
raster left skip=-3.5cm,
@@ -162,205 +401,3 @@ latexindent.pl -m textwrap-ts.tex -o=+-mod1 -l tabstop.yaml
\cref{lst:textwrap2B-yaml,lst:tabstop}, and they will be passed to the
\texttt{Text::Wrap} module. I have not found a useful reason to do this; see
\cite{textwrap} for more details.
-
-\subsubsection{Text wrapping on a per-code-block basis}\label{subsec:text-wrap-per-code-block} By default, if the value of
- \texttt{columns} is greater than 0 and the \texttt{-m} switch is active,
- then%
- \announce{2018-08-13}*{updates to textWrapOptions}
- the text wrapping routine will operate before the code blocks have been searched for.
- This behaviour is customisable; in particular, you can instead instruct
- \texttt{latexindent.pl} to apply \texttt{textWrap} on a per-code-block basis. Thanks to
- \cite{zoehneto} for their help in testing and shaping this feature.
- \index{modifying linebreaks! by text wrapping, per-code-block}
-
- The full details of \texttt{textWrapOptions} are shown in \cref{lst:textWrapOptionsAll}.
- In particular, note the field \texttt{perCodeBlockBasis: 0}.
- \index{specialBeginEnd!textWrapOptions}
-
- \cmhlistingsfromfile[style=textWrapOptionsAll]{../defaultSettings.yaml}[MLB-TCB,width=.95\linewidth,before=\centering]{\texttt{textWrapOptions}}{lst:textWrapOptionsAll}
-
- 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{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{mainDocument}.
-
- \begin{widepage}
- \cmhlistingsfromfile{demonstrations/textwrap5.tex}{\texttt{textwrap5.tex}}{lst:textwrap5}
- \end{widepage}
-
- With reference to this code block, the settings given in
- \cref{lst:textwrap3-yaml,lst:textwrap4-yaml,lst:textwrap5-yaml} each give the same
- output.
-
- \begin{cmhtcbraster}[raster columns=3,
- raster left skip=-3.5cm,
- raster right skip=-2cm,
- raster column skip=.03\linewidth]
- \cmhlistingsfromfile{demonstrations/textwrap3.yaml}[MLB-TCB]{\texttt{textwrap3.yaml}}{lst:textwrap3-yaml}
- \cmhlistingsfromfile{demonstrations/textwrap4.yaml}[MLB-TCB]{\texttt{textwrap4.yaml}}{lst:textwrap4-yaml}
- \cmhlistingsfromfile{demonstrations/textwrap5.yaml}[MLB-TCB]{\texttt{textwrap5.yaml}}{lst:textwrap5-yaml}
- \end{cmhtcbraster}
-
- Let's explore the similarities and differences in the equivalent (with respect to
- \cref{lst:textwrap5}) syntax specified in
- \cref{lst:textwrap3-yaml,lst:textwrap4-yaml,lst:textwrap5-yaml}:
- \begin{itemize}
- \item in each of \cref{lst:textwrap3-yaml,lst:textwrap4-yaml,lst:textwrap5-yaml} notice that
- \texttt{columns: 30};
- \item in each of \cref{lst:textwrap3-yaml,lst:textwrap4-yaml,lst:textwrap5-yaml} notice that
- \texttt{perCodeBlockBasis: 1};
- \item in \cref{lst:textwrap3-yaml} we have specified \texttt{all: 1} so that the text wrapping
- 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{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}
-
- Upon running the following commands
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \begin{commandshell}
-latexindent.pl -s textwrap5.tex -l=textwrap3.yaml -m
-latexindent.pl -s textwrap5.tex -l=textwrap4.yaml -m
-latexindent.pl -s textwrap5.tex -l=textwrap5.yaml -m
-\end{commandshell}
- we obtain the output shown in \cref{lst:textwrap5-mod3}.
-
- \cmhlistingsfromfile{demonstrations/textwrap5-mod3.tex}{\texttt{textwrap5-mod3.tex}}{lst:textwrap5-mod3}
-
- We can explore the idea of per-name text wrapping given in \cref{lst:textwrap5-yaml} by
- using \cref{lst:textwrap6}.
-
- \begin{widepage}
- \cmhlistingsfromfile{demonstrations/textwrap6.tex}{\texttt{textwrap6.tex}}{lst:textwrap6}
- \end{widepage}
-
- In particular, upon running
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \begin{commandshell}
-latexindent.pl -s textwrap6.tex -l=textwrap5.yaml -m
-\end{commandshell}
- we obtain the output given in \cref{lst:textwrap6-mod5}.
-
- \begin{widepage}
- \cmhlistingsfromfile{demonstrations/textwrap6-mod5.tex}{\texttt{textwrap6.tex} using \cref{lst:textwrap5-yaml}}{lst:textwrap6-mod5}
- \end{widepage}
-
- Notice that, because \texttt{environments} has been specified only for \texttt{myenv} (in
- \cref{lst:textwrap5-yaml}) that the environment named \texttt{another} has \emph{not} had
- text wrapping applied to it.
-
- The {all} field can be specified with exceptions which can either be done on a
- per-code-block or per-name basis; we explore this in relation to \cref{lst:textwrap6} in
- the settings given in \crefrange{lst:textwrap6-yaml}{lst:textwrap8-yaml}.
-
- \begin{adjustwidth}{-3.5cm}{-2.5cm}
- \begin{minipage}{.33\linewidth}
- \cmhlistingsfromfile{demonstrations/textwrap6.yaml}[MLB-TCB]{\texttt{textwrap6.yaml}}{lst:textwrap6-yaml}
- \end{minipage}%
- \begin{minipage}{.33\linewidth}
- \cmhlistingsfromfile{demonstrations/textwrap7.yaml}[MLB-TCB]{\texttt{textwrap7.yaml}}{lst:textwrap7-yaml}
- \end{minipage}%
- \begin{minipage}{.33\linewidth}
- \cmhlistingsfromfile{demonstrations/textwrap8.yaml}[MLB-TCB]{\texttt{textwrap8.yaml}}{lst:textwrap8-yaml}
- \end{minipage}
- \end{adjustwidth}
-
- Upon running the commands
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \begin{commandshell}
-latexindent.pl -s textwrap6.tex -l=textwrap6.yaml -m
-latexindent.pl -s textwrap6.tex -l=textwrap7.yaml -m
-latexindent.pl -s textwrap6.tex -l=textwrap8.yaml -m
-\end{commandshell}
- we receive the respective output given in
- \crefrange{lst:textwrap6-mod6}{lst:textwrap6-mod8}.
- \begin{widepage}
- \cmhlistingsfromfile{demonstrations/textwrap6-mod6.tex}{\texttt{textwrap6.tex} using \cref{lst:textwrap6-yaml}}{lst:textwrap6-mod6}
-
- \cmhlistingsfromfile{demonstrations/textwrap6-mod7.tex}{\texttt{textwrap6.tex} using \cref{lst:textwrap7-yaml}}{lst:textwrap6-mod7}
-
- \cmhlistingsfromfile{demonstrations/textwrap6-mod8.tex}{\texttt{textwrap6.tex} using \cref{lst:textwrap8-yaml}}{lst:textwrap6-mod8}
- \end{widepage}
-
- Notice that:
- \begin{itemize}
- \item in \cref{lst:textwrap6-mod6} the text wrapping routine has not been applied to any
- \texttt{environments} because it has been switched off (per-code-block) in
- \cref{lst:textwrap6-yaml};
- \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{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;
- we've seen two basic ways already: the default (set to \texttt{0}) and a positive integer
- (see \vref{lst:textwrap6}, for example). We explore further options in
- \crefrange{lst:textwrap9-yaml}{lst:textwrap11-yaml}.
-
- \begin{cmhtcbraster}[raster columns=3,
- raster left skip=-3.5cm,
- raster right skip=-2cm,
- raster column skip=.03\linewidth]
- \cmhlistingsfromfile{demonstrations/textwrap9.yaml}[MLB-TCB]{\texttt{textwrap9.yaml}}{lst:textwrap9-yaml}
- \cmhlistingsfromfile{demonstrations/textwrap10.yaml}[MLB-TCB]{\texttt{textwrap10.yaml}}{lst:textwrap10-yaml}
- \cmhlistingsfromfile{demonstrations/textwrap11.yaml}[MLB-TCB]{\texttt{textwrap11.yaml}}{lst:textwrap11-yaml}
- \end{cmhtcbraster}
-
- \Cref{lst:textwrap9-yaml} and \cref{lst:textwrap10-yaml} are equivalent. Upon running
- the commands
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \begin{commandshell}
-latexindent.pl -s textwrap6.tex -l=textwrap9.yaml -m
-latexindent.pl -s textwrap6.tex -l=textwrap11.yaml -m
-\end{commandshell}
- we receive the respective output given in \cref{lst:textwrap6-mod9,lst:textwrap6-mod11}.
-
- \begin{widepage}
- \cmhlistingsfromfile{demonstrations/textwrap6-mod9.tex}{\texttt{textwrap6.tex} using \cref{lst:textwrap9-yaml}}{lst:textwrap6-mod9}
-
- \cmhlistingsfromfile{demonstrations/textwrap6-mod11.tex}{\texttt{textwrap6.tex} using \cref{lst:textwrap11-yaml}}{lst:textwrap6-mod11}
- \end{widepage}
-
- Notice that:
- \begin{itemize}
- \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{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
- default value for \texttt{columns} then \texttt{80} will be used.
-
- \texttt{alignAtAmpersandTakesPriority} is set to \texttt{1} by default; assuming
- that text wrapping is occurring on a per-code-block basis, and the current
- environment/code block is specified within \vref{lst:aligndelims:basic} then text
- wrapping will be disabled for this code block.
-
- If you wish to specify \texttt{afterHeading} commands (see
- \vref{lst:indentAfterHeadings}) on a per-name basis, then you need to append the name
- with \texttt{:heading}, for example, you might use \texttt{section:heading}.
diff --git a/support/latexindent/documentation/subsubsec-commands-with-arguments.tex b/support/latexindent/documentation/subsubsec-commands-with-arguments.tex
index bcdf75f00c..b748787739 100644
--- a/support/latexindent/documentation/subsubsec-commands-with-arguments.tex
+++ b/support/latexindent/documentation/subsubsec-commands-with-arguments.tex
@@ -3,7 +3,7 @@
Let's begin with the simple example in \cref{lst:mycommand}; when \texttt{latexindent.pl}
operates on this file, the default output is shown in \cref{lst:mycommand-default}.
\footnote{The command code blocks have quite a few subtleties, described in
- \vref{subsec:commands-string-between}.}
+ \vref{subsec:commands-string-between}.}
\begin{cmhtcbraster}[raster column skip=.1\linewidth]
\cmhlistingsfromfile{demonstrations/mycommand.tex}{\texttt{mycommand.tex}}{lst:mycommand}
@@ -22,8 +22,7 @@
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycommand-noAdd2.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{mycommand-noAdd2.yaml}}{lst:mycommand-noAdd2}
\end{minipage}
- After running the following commands,
- \index{switches!-l demonstration}
+ After running the following commands, \index{switches!-l demonstration}
\begin{commandshell}
latexindent.pl mycommand.tex -l mycommand-noAdd1.yaml
latexindent.pl mycommand.tex -l mycommand-noAdd2.yaml
@@ -57,8 +56,7 @@ latexindent.pl mycommand.tex -l mycommand-noAdd2.yaml
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycommand-noAdd4.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{mycommand-noAdd4.yaml}}{lst:mycommand-noAdd4}
\end{minipage}
- After running the following commands,
- \index{switches!-l demonstration}
+ After running the following commands, \index{switches!-l demonstration}
\begin{commandshell}
latexindent.pl mycommand.tex -l mycommand-noAdd3.yaml
latexindent.pl mycommand.tex -l mycommand-noAdd4.yaml
@@ -90,8 +88,7 @@ latexindent.pl mycommand.tex -l mycommand-noAdd4.yaml
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycommand-noAdd6.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{mycommand-noAdd6.yaml}}{lst:mycommand-noAdd6}
\end{minipage}
- After running the following commands,
- \index{switches!-l demonstration}
+ After running the following commands, \index{switches!-l demonstration}
\begin{commandshell}
latexindent.pl mycommand.tex -l mycommand-noAdd5.yaml
latexindent.pl mycommand.tex -l mycommand-noAdd6.yaml
diff --git a/support/latexindent/documentation/subsubsec-environments-and-their-arguments.tex b/support/latexindent/documentation/subsubsec-environments-and-their-arguments.tex
index 4fef79e334..1c877d978c 100644
--- a/support/latexindent/documentation/subsubsec-environments-and-their-arguments.tex
+++ b/support/latexindent/documentation/subsubsec-environments-and-their-arguments.tex
@@ -17,8 +17,7 @@
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/myenv-noAdd2.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-noAdd2.yaml}}{lst:myenv-noAdd2}
\end{minipage}
- On applying either of the following commands,
- \index{switches!-l demonstration}
+ On applying either of the following commands, \index{switches!-l demonstration}
\begin{commandshell}
latexindent.pl myenv.tex -l myenv-noAdd1.yaml
latexindent.pl myenv.tex -l myenv-noAdd2.yaml
@@ -30,8 +29,7 @@ latexindent.pl myenv.tex -l myenv-noAdd2.yaml
\cmhlistingsfromfile{demonstrations/myenvironment-simple-noAdd-body1.tex}{\texttt{myenv.tex} output (using either \cref{lst:myenv-noAdd1} or \cref{lst:myenv-noAdd2})}{lst:myenv-output}
Upon changing the YAML files to those shown in \cref{lst:myenv-noAdd3,lst:myenv-noAdd4},
- and running either
- \index{switches!-l demonstration}
+ and running either \index{switches!-l demonstration}
\begin{commandshell}
latexindent.pl myenv.tex -l myenv-noAdd3.yaml
latexindent.pl myenv.tex -l myenv-noAdd4.yaml
@@ -53,8 +51,7 @@ latexindent.pl myenv.tex -l myenv-noAdd4.yaml
\cmhlistingsfromfile{demonstrations/myenvironment-args.tex}{\texttt{myenv-args.tex}}{lst:myenv-args}
- Upon running
- \index{switches!-l demonstration}
+ Upon running \index{switches!-l demonstration}
\begin{commandshell}
latexindent.pl -l=myenv-noAdd1.yaml myenv-args.tex
\end{commandshell}
@@ -77,8 +74,7 @@ latexindent.pl -l=myenv-noAdd1.yaml myenv-args.tex
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/myenv-noAdd6.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-noAdd6.yaml}}{lst:myenv-noAdd6}
\end{minipage}
- Upon running
- \index{switches!-l demonstration}
+ Upon running \index{switches!-l demonstration}
\begin{commandshell}
latexindent.pl myenv.tex -l myenv-noAdd5.yaml
latexindent.pl myenv.tex -l myenv-noAdd6.yaml
@@ -107,8 +103,7 @@ latexindent.pl myenv.tex -l myenv-noAdd6.yaml
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/myenv-rules2.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-rules2.yaml}}{lst:myenv-rules2}
\end{cmhtcbraster}
- On applying either of the following commands,
- \index{switches!-l demonstration}
+ On applying either of the following commands, \index{switches!-l demonstration}
\begin{commandshell}
latexindent.pl myenv.tex -l myenv-rules1.yaml
latexindent.pl myenv.tex -l myenv-rules2.yaml
@@ -123,8 +118,7 @@ latexindent.pl myenv.tex -l myenv-rules2.yaml
space, it will be ignored.
Returning to the example in \cref{lst:myenv-args} that contains optional and mandatory
- arguments. Upon using \cref{lst:myenv-rules1} as in
- \index{switches!-l demonstration}
+ arguments. Upon using \cref{lst:myenv-rules1} as in \index{switches!-l demonstration}
\begin{commandshell}
latexindent.pl myenv-args.tex -l=myenv-rules1.yaml
\end{commandshell}
@@ -144,8 +138,7 @@ latexindent.pl myenv-args.tex -l=myenv-rules1.yaml
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/myenv-rules4.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-rules4.yaml}}{lst:myenv-rules4}
\end{minipage}
- After running
- \index{switches!-l demonstration}
+ After running \index{switches!-l demonstration}
\begin{commandshell}
latexindent.pl myenv-args.tex -l myenv-rules3.yaml
latexindent.pl myenv-args.tex -l myenv-rules4.yaml
@@ -180,8 +173,8 @@ latexindent.pl myenv-args.tex -l myenv-rules4.yaml
\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}
+ \cref{lst:noAdditionalIndentGlobal:environments}, and that you run \index{switches!-l
+ demonstration}
\begin{widepage}
\begin{commandshell}
@@ -219,8 +212,7 @@ latexindent.pl myenv-args.tex -l myenv-rules1.yaml,env-noAdditionalGlobal.yaml
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/mand-args-no-add-glob.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{mand-args-no-add-glob.yaml}}{lst:mand-args-no-add-glob}
\end{minipage}
- we may run the commands
- \index{switches!-l demonstration}
+ we may run the commands \index{switches!-l demonstration}
\begin{commandshell}
latexindent.pl myenv-args.tex -local opt-args-no-add-glob.yaml
latexindent.pl myenv-args.tex -local mand-args-no-add-glob.yaml
@@ -246,8 +238,7 @@ latexindent.pl myenv-args.tex -local mand-args-no-add-glob.yaml
\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}
+ \lstinline!" "!, and then run the following commands \index{switches!-l demonstration}
\begin{commandshell}
latexindent.pl myenv-args.tex -l env-indentRules.yaml
@@ -281,8 +272,7 @@ latexindent.pl myenv-args.tex -l myenv-rules1.yaml,env-indentRules.yaml
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/mand-args-indent-rules-glob.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{mand-args-indent-rules-glob.yaml}}{lst:mand-args-indent-rules-glob}
\end{minipage}
- Upon running the following commands
- \index{switches!-l demonstration}
+ Upon running the following commands \index{switches!-l demonstration}
\begin{commandshell}
latexindent.pl myenv-args.tex -local opt-args-indent-rules-glob.yaml
latexindent.pl myenv-args.tex -local mand-args-indent-rules-glob.yaml
diff --git a/support/latexindent/documentation/subsubsec-environments-with-items.tex b/support/latexindent/documentation/subsubsec-environments-with-items.tex
index bf561e5141..c6c471c474 100644
--- a/support/latexindent/documentation/subsubsec-environments-with-items.tex
+++ b/support/latexindent/documentation/subsubsec-environments-with-items.tex
@@ -15,8 +15,7 @@
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/item-rules1.yaml}[yaml-TCB]{\texttt{item-rules1.yaml}}{lst:item-rules1}
\end{cmhtcbraster}
- Upon running the following commands
- \index{switches!-l demonstration}
+ Upon running the following commands \index{switches!-l demonstration}
\begin{commandshell}
latexindent.pl items1.tex -local item-noAdd1.yaml
latexindent.pl items1.tex -local item-rules1.yaml
@@ -50,8 +49,7 @@ latexindent.pl items1.tex -local item-rules1.yaml
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/items-indentRulesGlobal.yaml}[yaml-TCB]{\texttt{items-indentRulesGlobal.yaml}}{lst:items-indentRulesGlobal}
\end{minipage}
- Upon running the following commands,
- \index{switches!-l demonstration}
+ Upon running the following commands, \index{switches!-l demonstration}
\begin{commandshell}
latexindent.pl items1.tex -local items-noAdditionalGlobal.yaml
latexindent.pl items1.tex -local items-indentRulesGlobal.yaml
diff --git a/support/latexindent/documentation/subsubsec-headings.tex b/support/latexindent/documentation/subsubsec-headings.tex
index 1eb7512015..0251a30ac9 100644
--- a/support/latexindent/documentation/subsubsec-headings.tex
+++ b/support/latexindent/documentation/subsubsec-headings.tex
@@ -22,8 +22,7 @@ latexindent.pl headings2.tex -l headings3.yaml
\end{cmhtcbraster}
If we specify \texttt{noAdditionalIndent} as in \cref{lst:headings4yaml} and run the
- command
- \index{switches!-l demonstration}
+ command \index{switches!-l demonstration}
\begin{commandshell}
latexindent.pl headings2.tex -l headings4.yaml
\end{commandshell}
@@ -72,7 +71,7 @@ latexindent.pl headings2.tex -l headings4.yaml
in \cref{lst:headings2-mod8,lst:headings2-mod9}. Note that in \cref{lst:headings8yaml}
the \emph{mandatory argument} of \texttt{paragraph} has received a (default) tab's worth
of indentation, while the body after the heading has received \emph{no additional
- indentation}. Similarly, in \cref{lst:headings2-mod9}, the \emph{argument} has received
+ indentation}. Similarly, in \cref{lst:headings2-mod9}, the \emph{argument} has received
both a (default) tab plus two spaces of indentation (from the global rule specified in
\cref{lst:headings9yaml}), and the remaining body after \texttt{paragraph} has received
just two spaces of indentation.
diff --git a/support/latexindent/documentation/subsubsec-ifelsefi.tex b/support/latexindent/documentation/subsubsec-ifelsefi.tex
index ee6bd54415..a735cf5ba3 100644
--- a/support/latexindent/documentation/subsubsec-ifelsefi.tex
+++ b/support/latexindent/documentation/subsubsec-ifelsefi.tex
@@ -26,8 +26,7 @@
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/ifnum-indent-rules.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{ifnum-indent-rules.yaml}}{lst:ifnum-indent-rules}
\end{minipage}
- After running the following commands,
- \index{switches!-l demonstration}
+ After running the following commands, \index{switches!-l demonstration}
\begin{commandshell}
latexindent.pl ifelsefi1.tex -local ifnum-noAdd.yaml
latexindent.pl ifelsefi1.tex -l ifnum-indent-rules.yaml
@@ -57,8 +56,7 @@ latexindent.pl ifelsefi1.tex -l ifnum-indent-rules.yaml
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/ifelsefi-indent-rules-global.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{ifelsefi-indent-rules-global.yaml}}{lst:ifelsefi-indent-rules-global}
\end{minipage}
- Upon running the following commands
- \index{switches!-l demonstration}
+ Upon running the following commands \index{switches!-l demonstration}
\begin{commandshell}
latexindent.pl ifelsefi1.tex -local ifelsefi-noAdd-glob.yaml
latexindent.pl ifelsefi1.tex -l ifelsefi-indent-rules-global.yaml
@@ -78,11 +76,10 @@ latexindent.pl ifelsefi1.tex -l ifelsefi-indent-rules-global.yaml
\cmhlistingsfromfile[showspaces=true]{demonstrations/ifelsefi1-indent-rules-global.tex}{\texttt{ifelsefi1.tex} using \cref{lst:ifelsefi-indent-rules-global}}{lst:ifelsefi1-output-indent-rules-global}
\end{minipage}
- We can further explore the treatment of \texttt{ifElseFi} code
- blocks%
- \announce{2018-04-27}*{updates to ifElseFi code blocks} in \cref{lst:ifelsefi2}, and the associated default output given in
- \cref{lst:ifelsefi2-default}; note, in particular, that the bodies of each of the `or
- statements' have been indented.
+ We can further explore the treatment of \texttt{ifElseFi} code blocks
+ \announce{2018-04-27}*{updates to ifElseFi code blocks} in \cref{lst:ifelsefi2}, and the
+ associated default output given in \cref{lst:ifelsefi2-default}; note, in particular,
+ that the bodies of each of the `or statements' have been indented.%
\begin{cmhtcbraster}[raster column skip=.1\linewidth]
\cmhlistingsfromfile{demonstrations/ifelsefi2.tex}{\texttt{ifelsefi2.tex}}{lst:ifelsefi2}
diff --git a/support/latexindent/documentation/subsubsec-no-add-remaining-code-blocks.tex b/support/latexindent/documentation/subsubsec-no-add-remaining-code-blocks.tex
index b6f84d47bd..437d1b827a 100644
--- a/support/latexindent/documentation/subsubsec-no-add-remaining-code-blocks.tex
+++ b/support/latexindent/documentation/subsubsec-no-add-remaining-code-blocks.tex
@@ -8,8 +8,8 @@
\paragraph{keyEqualsValuesBracesBrackets}
\texttt{latexindent.pl} defines this type of code block by the following criteria:
\begin{itemize}
- \item it must immediately follow either \lstinline!{! OR \lstinline![! OR
- \lstinline!,! with comments and blank lines allowed.
+ \item it must immediately follow either \lstinline!{! OR \lstinline![! OR \lstinline!,! with
+ comments and blank lines allowed.
\item then it has a name made up of the characters detailed in \vref{tab:code-blocks};
\item then an $=$ symbol;
\item then at least one set of curly braces or square brackets (comments and line breaks
@@ -41,14 +41,12 @@
the \emph{body} field for \texttt{noAdditionalIndent} and friends from
\cpageref{sec:noadd-indent-rules}.
\end{itemize}
- \paragraph{namedGroupingBracesBrackets}
- This type of code block is mostly motivated by tikz-based code; we define this code block
- as follows:
+ \paragraph{namedGroupingBracesBrackets} This type of code block is mostly motivated by
+ tikz-based code; we define this code block as follows:
\begin{itemize}
\item it must immediately follow either \emph{horizontal space} OR \emph{one or more line
- breaks} OR
- \lstinline!{! OR \lstinline![! OR \lstinline!$! OR
- \lstinline!)! OR \lstinline!(!
+ breaks} OR \lstinline!{! OR \lstinline![! OR \lstinline!$! OR \lstinline!)! OR
+ \lstinline!(!
\item the name may contain the characters detailed in \vref{tab:code-blocks};
\item then at least one set of curly braces or square brackets (comments and line breaks
allowed throughout).
@@ -71,7 +69,7 @@
In particular, \texttt{latexindent.pl} considers \texttt{child}, \texttt{parent} and
\texttt{node} all to be \texttt{namedGroupingBracesBrackets}\footnote{ You may like to
- verify this by using the \texttt{-tt} option and checking \texttt{indent.log}! }.
+ verify this by using the \texttt{-tt} option and checking \texttt{indent.log}! }.
Referencing \cref{lst:child1:default}, note that the maximum indentation is two tabs, and
these come from:
\begin{itemize}
@@ -82,12 +80,11 @@
\cpageref{sec:noadd-indent-rules}.
\end{itemize}
- \paragraph{UnNamedGroupingBracesBrackets} occur in a variety of situations; specifically,
- we define this type of code block as satisfying the following criteria:
+ \paragraph{UnNamedGroupingBracesBrackets} occur in a variety of situations; specifically, we
+ define this type of code block as satisfying the following criteria:
\begin{itemize}
- \item it must immediately follow either \lstinline!{! OR \lstinline![! OR
- \lstinline!,! OR \lstinline!&! OR \lstinline!)! OR
- \lstinline!(! OR \lstinline!$!;
+ \item it must immediately follow either \lstinline!{! OR \lstinline![! OR \lstinline!,! OR
+ \lstinline!&! OR \lstinline!)! OR \lstinline!(! OR \lstinline!$!;
\item then at least one set of curly braces or square brackets (comments and line breaks
allowed throughout).
\end{itemize}
diff --git a/support/latexindent/documentation/subsubsec-special.tex b/support/latexindent/documentation/subsubsec-special.tex
index fb8cb0af8a..693e7e44f3 100644
--- a/support/latexindent/documentation/subsubsec-special.tex
+++ b/support/latexindent/documentation/subsubsec-special.tex
@@ -7,8 +7,7 @@
`scalar' form for these type of code blocks, although the `field' form would work,
assuming that \texttt{body} was specified. Examples are shown in
\cref{lst:displayMath-noAdd,lst:displayMath-indent-rules}.
- \index{specialBeginEnd!noAdditionalIndent}
- \index{specialBeginEnd!indentRules example}
+ \index{specialBeginEnd!noAdditionalIndent} \index{specialBeginEnd!indentRules example}
\begin{minipage}{.49\textwidth}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/displayMath-noAdd.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{displayMath-noAdd.yaml}}{lst:displayMath-noAdd}
@@ -18,8 +17,7 @@
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/displayMath-indent-rules.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{displayMath-indent-rules.yaml}}{lst:displayMath-indent-rules}
\end{minipage}
- After running the following commands,
- \index{switches!-l demonstration}
+ After running the following commands, \index{switches!-l demonstration}
\begin{commandshell}
latexindent.pl special1.tex -local displayMath-noAdd.yaml
latexindent.pl special1.tex -l displayMath-indent-rules.yaml
@@ -49,8 +47,7 @@ latexindent.pl special1.tex -l displayMath-indent-rules.yaml
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/special-indent-rules-global.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{special-indent-rules-global.yaml}}{lst:special-indent-rules-global}
\end{minipage}
- Upon running the following commands
- \index{switches!-l demonstration}
+ Upon running the following commands \index{switches!-l demonstration}
\begin{commandshell}
latexindent.pl special1.tex -local special-noAdd-glob.yaml
latexindent.pl special1.tex -l special-indent-rules-global.yaml
diff --git a/support/latexindent/documentation/test-default-settings.tex b/support/latexindent/documentation/test-default-settings.tex
index 7e68a1b8eb..02b858a749 100644
--- a/support/latexindent/documentation/test-default-settings.tex
+++ b/support/latexindent/documentation/test-default-settings.tex
@@ -51,11 +51,6 @@ subsec-poly-switches.tex:
\cmhlistingsfromfile[style=modifylinebreaksEnv]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,MLB-TCB]{\texttt{environments}}{lst:environments-mlb}
-subsec-remove-para-line-breaks.tex:
-
-\cmhlistingsfromfile[style=removeParagraphLineBreaks]{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{removeParagraphLineBreaks}}{lst:removeParagraphLineBreaks}
-\cmhlistingsfromfile[style=paragraphsStopAt]{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{paragraphsStopAt}}{lst:paragraphsStopAt}
-
subsec-text-wrap.tex:
\cmhlistingsfromfile[style=textWrapOptions]{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{textWrapOptions}}{lst:textWrapOptions}
diff --git a/support/latexindent/documentation/title.tex b/support/latexindent/documentation/title.tex
index 6e559866e2..82975263d5 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.15
+ \centering\ttfamily\bfseries latexindent.pl\\[1cm] Version 3.16
\end{tcolorbox}
}
\author{Chris Hughes \thanks{and contributors!
See \vref{sec:contributors}.
For
all communication, please visit \cite{latexindent-home}.}}
-\date{2022-01-21}
+\date{2022-03-13}
\maketitle
\begin{adjustwidth}{1cm}{1cm}
\small