diff options
| author | Karl Berry <karl@freefriends.org> | 2022-03-13 20:50:20 +0000 |
|---|---|---|
| committer | Karl Berry <karl@freefriends.org> | 2022-03-13 20:50:20 +0000 |
| commit | a0fa10fa8cbb6079d678193d1a6df01bbc9c957b (patch) | |
| tree | 81eeebd7f12fb5c006f5e93da8ea64d02b3f4d89 | |
| parent | a370b71536d38cec18c7baf3908c2bbaa83e1a0d (diff) | |
latexindent (13mar22)
git-svn-id: svn://tug.org/texlive/trunk@62690 c570f23f-e606-0410-a88d-b1316a301751
48 files changed, 1425 insertions, 2229 deletions
diff --git a/Build/source/texk/texlive/linked_scripts/latexindent/latexindent.pl b/Build/source/texk/texlive/linked_scripts/latexindent/latexindent.pl index d52f46f10fd..70edb2f4a75 100755 --- a/Build/source/texk/texlive/linked_scripts/latexindent/latexindent.pl +++ b/Build/source/texk/texlive/linked_scripts/latexindent/latexindent.pl @@ -1,5 +1,5 @@ #!/usr/bin/env perl -# latexindent.pl, version 3.15, 2022-01-21 +# latexindent.pl, version 3.16, 2022-03-13 # # This program is free software: you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by diff --git a/Master/bin/win32/latexindent.exe b/Master/bin/win32/latexindent.exe Binary files differindex c2ebd63ae21..f16741ae229 100755 --- a/Master/bin/win32/latexindent.exe +++ b/Master/bin/win32/latexindent.exe diff --git a/Master/texmf-dist/doc/support/latexindent/README b/Master/texmf-dist/doc/support/latexindent/README index f14024e491b..e84183e4cef 100644 --- a/Master/texmf-dist/doc/support/latexindent/README +++ b/Master/texmf-dist/doc/support/latexindent/README @@ -1,5 +1,5 @@ %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - latexindent.pl, version 3.15, 2022-01-21 + latexindent.pl, version 3.16, 2022-03-13 PERL script to indent code within environments, and align delimited environments in .tex files. diff --git a/Master/texmf-dist/doc/support/latexindent/latexindent-yaml-schema.json b/Master/texmf-dist/doc/support/latexindent/latexindent-yaml-schema.json index 013c7c76562..34c9354f755 100644 --- a/Master/texmf-dist/doc/support/latexindent/latexindent-yaml-schema.json +++ b/Master/texmf-dist/doc/support/latexindent/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/Master/texmf-dist/doc/support/latexindent/latexindent.pdf b/Master/texmf-dist/doc/support/latexindent/latexindent.pdf Binary files differindex 78f618b3770..a6623c6b94a 100644 --- a/Master/texmf-dist/doc/support/latexindent/latexindent.pdf +++ b/Master/texmf-dist/doc/support/latexindent/latexindent.pdf diff --git a/Master/texmf-dist/doc/support/latexindent/latexindent.tex b/Master/texmf-dist/doc/support/latexindent/latexindent.tex index 0ccca1d0ea2..95fa9d694a7 100644 --- a/Master/texmf-dist/doc/support/latexindent/latexindent.tex +++ b/Master/texmf-dist/doc/support/latexindent/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/Master/texmf-dist/doc/support/latexindent/sec-appendices.tex b/Master/texmf-dist/doc/support/latexindent/sec-appendices.tex index b797f2ebcca..64f49180e9f 100644 --- a/Master/texmf-dist/doc/support/latexindent/sec-appendices.tex +++ b/Master/texmf-dist/doc/support/latexindent/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/Master/texmf-dist/doc/support/latexindent/sec-conclusions-know-limitations.tex b/Master/texmf-dist/doc/support/latexindent/sec-conclusions-know-limitations.tex index fe31bde7940..5afdddb6cc7 100644 --- a/Master/texmf-dist/doc/support/latexindent/sec-conclusions-know-limitations.tex +++ b/Master/texmf-dist/doc/support/latexindent/sec-conclusions-know-limitations.tex @@ -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/Master/texmf-dist/doc/support/latexindent/sec-default-user-local.tex b/Master/texmf-dist/doc/support/latexindent/sec-default-user-local.tex index 6be0bbe3f51..94fbdce46cc 100644 --- a/Master/texmf-dist/doc/support/latexindent/sec-default-user-local.tex +++ b/Master/texmf-dist/doc/support/latexindent/sec-default-user-local.tex @@ -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/Master/texmf-dist/doc/support/latexindent/sec-fine-tuning.tex b/Master/texmf-dist/doc/support/latexindent/sec-fine-tuning.tex index 0a0739adc8d..352040cc7f9 100644 --- a/Master/texmf-dist/doc/support/latexindent/sec-fine-tuning.tex +++ b/Master/texmf-dist/doc/support/latexindent/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/Master/texmf-dist/doc/support/latexindent/sec-how-to-use.tex b/Master/texmf-dist/doc/support/latexindent/sec-how-to-use.tex index f5c79077292..944a38292c1 100644 --- a/Master/texmf-dist/doc/support/latexindent/sec-how-to-use.tex +++ b/Master/texmf-dist/doc/support/latexindent/sec-how-to-use.tex @@ -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/Master/texmf-dist/doc/support/latexindent/sec-indent-config-and-settings.tex b/Master/texmf-dist/doc/support/latexindent/sec-indent-config-and-settings.tex index 9c7eed4f959..b25cc70b7bc 100644 --- a/Master/texmf-dist/doc/support/latexindent/sec-indent-config-and-settings.tex +++ b/Master/texmf-dist/doc/support/latexindent/sec-indent-config-and-settings.tex @@ -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/Master/texmf-dist/doc/support/latexindent/sec-introduction.tex b/Master/texmf-dist/doc/support/latexindent/sec-introduction.tex index 22fbd3cd664..8812e106b93 100644 --- a/Master/texmf-dist/doc/support/latexindent/sec-introduction.tex +++ b/Master/texmf-dist/doc/support/latexindent/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/Master/texmf-dist/doc/support/latexindent/sec-replacements.tex b/Master/texmf-dist/doc/support/latexindent/sec-replacements.tex index a36c4199cf2..5491df6072a 100644 --- a/Master/texmf-dist/doc/support/latexindent/sec-replacements.tex +++ b/Master/texmf-dist/doc/support/latexindent/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/Master/texmf-dist/doc/support/latexindent/sec-the-line-switch.tex b/Master/texmf-dist/doc/support/latexindent/sec-the-line-switch.tex index 2fdab465124..6c2d097e89c 100644 --- a/Master/texmf-dist/doc/support/latexindent/sec-the-line-switch.tex +++ b/Master/texmf-dist/doc/support/latexindent/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/Master/texmf-dist/doc/support/latexindent/sec-the-m-switch.tex b/Master/texmf-dist/doc/support/latexindent/sec-the-m-switch.tex index 0d16cc43dbf..1f18d2f76cd 100644 --- a/Master/texmf-dist/doc/support/latexindent/sec-the-m-switch.tex +++ b/Master/texmf-dist/doc/support/latexindent/sec-the-m-switch.tex @@ -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/Master/texmf-dist/doc/support/latexindent/subsec-combine-text-wrap-para-line-breaks.tex b/Master/texmf-dist/doc/support/latexindent/subsec-combine-text-wrap-para-line-breaks.tex index 94aab37b325..e84c92f8c6d 100644 --- a/Master/texmf-dist/doc/support/latexindent/subsec-combine-text-wrap-para-line-breaks.tex +++ b/Master/texmf-dist/doc/support/latexindent/subsec-combine-text-wrap-para-line-breaks.tex @@ -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/Master/texmf-dist/doc/support/latexindent/subsec-commands-and-their-options.tex b/Master/texmf-dist/doc/support/latexindent/subsec-commands-and-their-options.tex index cb2d0999945..7ed4d4eaeb3 100644 --- a/Master/texmf-dist/doc/support/latexindent/subsec-commands-and-their-options.tex +++ b/Master/texmf-dist/doc/support/latexindent/subsec-commands-and-their-options.tex @@ -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/Master/texmf-dist/doc/support/latexindent/subsec-one-sentence-per-line.tex b/Master/texmf-dist/doc/support/latexindent/subsec-one-sentence-per-line.tex index 1b6fbcf4b15..37a57e8f1a6 100644 --- a/Master/texmf-dist/doc/support/latexindent/subsec-one-sentence-per-line.tex +++ b/Master/texmf-dist/doc/support/latexindent/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/Master/texmf-dist/doc/support/latexindent/subsec-poly-switches.tex b/Master/texmf-dist/doc/support/latexindent/subsec-poly-switches.tex index 42b077453f4..9ac53f6648e 100644 --- a/Master/texmf-dist/doc/support/latexindent/subsec-poly-switches.tex +++ b/Master/texmf-dist/doc/support/latexindent/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/Master/texmf-dist/doc/support/latexindent/subsec-remove-para-line-breaks.tex b/Master/texmf-dist/doc/support/latexindent/subsec-remove-para-line-breaks.tex deleted file mode 100644 index b4572468f93..00000000000 --- a/Master/texmf-dist/doc/support/latexindent/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/Master/texmf-dist/doc/support/latexindent/subsec-text-wrap-summary.tex b/Master/texmf-dist/doc/support/latexindent/subsec-text-wrap-summary.tex deleted file mode 100644 index 99b9975a2a0..00000000000 --- a/Master/texmf-dist/doc/support/latexindent/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/Master/texmf-dist/doc/support/latexindent/subsec-text-wrap.tex b/Master/texmf-dist/doc/support/latexindent/subsec-text-wrap.tex index 64eea3f1ab6..2b4c96539e9 100644 --- a/Master/texmf-dist/doc/support/latexindent/subsec-text-wrap.tex +++ b/Master/texmf-dist/doc/support/latexindent/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/Master/texmf-dist/doc/support/latexindent/subsubsec-commands-with-arguments.tex b/Master/texmf-dist/doc/support/latexindent/subsubsec-commands-with-arguments.tex index bcdf75f00c0..b748787739b 100644 --- a/Master/texmf-dist/doc/support/latexindent/subsubsec-commands-with-arguments.tex +++ b/Master/texmf-dist/doc/support/latexindent/subsubsec-commands-with-arguments.tex @@ -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/Master/texmf-dist/doc/support/latexindent/subsubsec-environments-and-their-arguments.tex b/Master/texmf-dist/doc/support/latexindent/subsubsec-environments-and-their-arguments.tex index 4fef79e3340..1c877d978c7 100644 --- a/Master/texmf-dist/doc/support/latexindent/subsubsec-environments-and-their-arguments.tex +++ b/Master/texmf-dist/doc/support/latexindent/subsubsec-environments-and-their-arguments.tex @@ -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/Master/texmf-dist/doc/support/latexindent/subsubsec-environments-with-items.tex b/Master/texmf-dist/doc/support/latexindent/subsubsec-environments-with-items.tex index bf561e51410..c6c471c4748 100644 --- a/Master/texmf-dist/doc/support/latexindent/subsubsec-environments-with-items.tex +++ b/Master/texmf-dist/doc/support/latexindent/subsubsec-environments-with-items.tex @@ -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/Master/texmf-dist/doc/support/latexindent/subsubsec-headings.tex b/Master/texmf-dist/doc/support/latexindent/subsubsec-headings.tex index 1eb75120155..0251a30ac9e 100644 --- a/Master/texmf-dist/doc/support/latexindent/subsubsec-headings.tex +++ b/Master/texmf-dist/doc/support/latexindent/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/Master/texmf-dist/doc/support/latexindent/subsubsec-ifelsefi.tex b/Master/texmf-dist/doc/support/latexindent/subsubsec-ifelsefi.tex index ee6bd544155..a735cf5ba36 100644 --- a/Master/texmf-dist/doc/support/latexindent/subsubsec-ifelsefi.tex +++ b/Master/texmf-dist/doc/support/latexindent/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/Master/texmf-dist/doc/support/latexindent/subsubsec-no-add-remaining-code-blocks.tex b/Master/texmf-dist/doc/support/latexindent/subsubsec-no-add-remaining-code-blocks.tex index b6f84d47bd7..437d1b827af 100644 --- a/Master/texmf-dist/doc/support/latexindent/subsubsec-no-add-remaining-code-blocks.tex +++ b/Master/texmf-dist/doc/support/latexindent/subsubsec-no-add-remaining-code-blocks.tex @@ -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/Master/texmf-dist/doc/support/latexindent/subsubsec-special.tex b/Master/texmf-dist/doc/support/latexindent/subsubsec-special.tex index fb8cb0af8ac..693e7e44f33 100644 --- a/Master/texmf-dist/doc/support/latexindent/subsubsec-special.tex +++ b/Master/texmf-dist/doc/support/latexindent/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/Master/texmf-dist/doc/support/latexindent/test-default-settings.tex b/Master/texmf-dist/doc/support/latexindent/test-default-settings.tex index 7e68a1b8eba..02b858a7494 100644 --- a/Master/texmf-dist/doc/support/latexindent/test-default-settings.tex +++ b/Master/texmf-dist/doc/support/latexindent/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/Master/texmf-dist/doc/support/latexindent/title.tex b/Master/texmf-dist/doc/support/latexindent/title.tex index 6e559866e26..82975263d5a 100644 --- a/Master/texmf-dist/doc/support/latexindent/title.tex +++ b/Master/texmf-dist/doc/support/latexindent/title.tex @@ -8,14 +8,14 @@ sharp corners, enhanced, overlay={\node[anchor=north east,outer sep=2pt] at ([xshift=3cm,yshift=4mm]frame.north east) {\includegraphics[width=3cm]{logo}}; }] - \centering\ttfamily\bfseries latexindent.pl\\[1cm] Version 3.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 diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/Arguments.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/Arguments.pm index 028f0ec842b..35ea03a63e9 100644 --- a/Master/texmf-dist/scripts/latexindent/LatexIndent/Arguments.pm +++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/Arguments.pm @@ -82,7 +82,7 @@ sub find_opt_mand_arguments{ # text wrapping can make the ID split across lines ${$arguments}{idRegExp} = ${$arguments}{id}; - if($is_m_switch_active){ + if($is_m_switch_active and ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{huge} ne "overflow"){ my $IDwithLineBreaks = join("\\R?\\h*",split(//,${$arguments}{id})); ${$arguments}{idRegExp} = qr/$IDwithLineBreaks/s; } diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/BlankLines.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/BlankLines.pm index a3e439d2e0d..b1a3cee40dd 100644 --- a/Master/texmf-dist/scripts/latexindent/LatexIndent/BlankLines.pm +++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/BlankLines.pm @@ -83,7 +83,11 @@ sub unprotect_blank_lines{ ${$self}{body} =~ s/^\h*\R//mg; $logger->trace("Unprotecting blank lines (see preserveBlankLines)") if $is_t_switch_active; - my $blankLineToken = join("(?:\\h|\\R)*",split(//,$tokens{blanklines})); + my $blankLineToken = $tokens{blanklines}; + + if($is_m_switch_active and ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{huge} ne "overflow"){ + $blankLineToken = join("(?:\\h|\\R)*",split(//,$tokens{blanklines})); + } # loop through the body, looking for the blank line token while(${$self}{body} =~ m/$blankLineToken/s){ diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/Document.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/Document.pm index 5be50847293..2ad655a56a8 100644 --- a/Master/texmf-dist/scripts/latexindent/LatexIndent/Document.pm +++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/Document.pm @@ -27,12 +27,13 @@ use LatexIndent::Logger qw/@logFileLines/; use LatexIndent::Check qw/simple_diff/; use LatexIndent::Lines qw/lines_body_selected_lines lines_verbatim_create_line_block/; use LatexIndent::Replacement qw/make_replacements/; -use LatexIndent::GetYamlSettings qw/yaml_read_settings yaml_modify_line_breaks_settings yaml_get_indentation_settings_for_this_object yaml_poly_switch_get_every_or_custom_value yaml_get_indentation_information yaml_get_object_attribute_for_indentation_settings yaml_alignment_at_ampersand_settings yaml_get_textwrap_removeparagraphline_breaks %mainSettings yaml_get_columns/; +use LatexIndent::GetYamlSettings qw/yaml_read_settings yaml_modify_line_breaks_settings yaml_get_indentation_settings_for_this_object yaml_poly_switch_get_every_or_custom_value yaml_get_indentation_information yaml_get_object_attribute_for_indentation_settings yaml_alignment_at_ampersand_settings %mainSettings /; use LatexIndent::FileExtension qw/file_extension_check/; use LatexIndent::BackUpFileProcedure qw/create_back_up_file/; use LatexIndent::BlankLines qw/protect_blank_lines unprotect_blank_lines condense_blank_lines/; -use LatexIndent::ModifyLineBreaks qw/modify_line_breaks_body modify_line_breaks_end modify_line_breaks_end_after remove_line_breaks_begin adjust_line_breaks_end_parent text_wrap remove_paragraph_line_breaks construct_paragraph_reg_exp text_wrap_remove_paragraph_line_breaks verbatim_modify_line_breaks/; +use LatexIndent::ModifyLineBreaks qw/modify_line_breaks_body modify_line_breaks_end modify_line_breaks_end_after remove_line_breaks_begin adjust_line_breaks_end_parent verbatim_modify_line_breaks/; use LatexIndent::Sentence qw/one_sentence_per_line/; +use LatexIndent::Wrap qw/text_wrap/; use LatexIndent::TrailingComments qw/remove_trailing_comments put_trailing_comments_back_in add_comment_symbol construct_trailing_comment_regexp/; use LatexIndent::HorizontalWhiteSpace qw/remove_trailing_whitespace remove_leading_space/; use LatexIndent::Indent qw/indent wrap_up_statement determine_total_indentation indent_begin indent_body indent_end_statement final_indentation_check get_surrounding_indentation indent_children_recursively check_for_blank_lines_at_beginning put_blank_lines_back_in_at_beginning add_surrounding_indentation_to_begin_statement post_indentation_check/; @@ -104,9 +105,8 @@ sub operate_on_file{ $self->find_verbatim_special; $logger->trace("*Verbatim storage:") if $is_tt_switch_active; $logger->trace(Dumper(\%verbatimStorage)) if $is_tt_switch_active; - $self->verbatim_modify_line_breaks if $is_m_switch_active; + $self->verbatim_modify_line_breaks (when=>"beforeTextWrap") if $is_m_switch_active; $self->make_replacements(when=>"before") if $is_rv_switch_active; - $self->text_wrap if ($is_m_switch_active and !${$mainSettings{modifyLineBreaks}{textWrapOptions}}{perCodeBlockBasis} and ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{columns}>1); $self->protect_blank_lines if $is_m_switch_active; $self->remove_trailing_whitespace(when=>"before"); $self->find_file_contents_environments_and_preamble; @@ -142,7 +142,6 @@ sub construct_regular_expressions{ $self->construct_key_equals_values_regexp; $self->construct_grouping_braces_brackets_regexp; $self->construct_unnamed_grouping_braces_brackets_regexp; - $self->construct_paragraph_reg_exp if $is_m_switch_active; } sub output_indented_text{ @@ -231,19 +230,23 @@ sub find_objects{ # one sentence per line: sentences are objects, as of V3.5.1 $self->one_sentence_per_line if ($is_m_switch_active and ${$mainSettings{modifyLineBreaks}{oneSentencePerLine}}{manipulateSentences}); - if ($is_m_switch_active and !${$self}{preamblePresent}){ - $self->yaml_get_textwrap_removeparagraphline_breaks; - } - - if( $is_m_switch_active and ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{beforeFindingChildCodeBlocks} == 1){ - # call the remove_paragraph_line_breaks and text_wrap routines - if(${$mainSettings{modifyLineBreaks}{removeParagraphLineBreaks}}{beforeTextWrap}){ - $self->remove_paragraph_line_breaks if ${$self}{removeParagraphLineBreaks}; - $self->text_wrap if (${$self}{textWrapOptions} and ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{perCodeBlockBasis}); - } else { - $self->text_wrap if (${$self}{textWrapOptions} and ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{perCodeBlockBasis}); - $self->remove_paragraph_line_breaks if ${$self}{removeParagraphLineBreaks}; - } + # text wrapping + # + # note: this routine will *not* be called if + # + # modifyLineBreaks: + # oneSentencePerLine: + # manipulateSentences: 1 + # textWrapSentences: 1 + # + if ($is_m_switch_active + and !${$mainSettings{modifyLineBreaks}{oneSentencePerLine}}{manipulateSentences} + and !${$mainSettings{modifyLineBreaks}{oneSentencePerLine}}{textWrapSentences} + and ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{columns} !=0 ){ + $self->text_wrap(); + + # text wrapping can affect verbatim poly-switches, so we run it again + $self->verbatim_modify_line_breaks(when=>"afterTextWrap"); } # search for environments @@ -261,18 +264,6 @@ sub find_objects{ # the ordering of finding commands and special code blocks can change $self->find_commands_or_key_equals_values_braces_and_special if ${$self}{body} =~ m/$specialBeginAndBracesBracketsBasicRegExp/s; - # documents without preamble need a manual call to the paragraph_one_line routine - if ($is_m_switch_active and ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{beforeFindingChildCodeBlocks} == 0 ){ - # call the remove_paragraph_line_breaks and text_wrap routines - if(${$mainSettings{modifyLineBreaks}{removeParagraphLineBreaks}}{beforeTextWrap}){ - $self->remove_paragraph_line_breaks if ${$self}{removeParagraphLineBreaks}; - $self->text_wrap if (${$self}{textWrapOptions} and ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{perCodeBlockBasis}); - } else { - $self->text_wrap if (${$self}{textWrapOptions} and ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{perCodeBlockBasis}); - $self->remove_paragraph_line_breaks if ${$self}{removeParagraphLineBreaks}; - } - } - # if there are no children, return if(${$self}{children}){ $logger->trace("*Objects have been found.") if $is_t_switch_active; @@ -326,15 +317,9 @@ sub get_settings_and_store_new_object{ # there are a number of tasks common to each object $latexIndentObject->tasks_common_to_each_object(%{$self}); - # removeParagraphLineBreaks and textWrapping fun! - $latexIndentObject->text_wrap_remove_paragraph_line_breaks if( $is_m_switch_active and ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{beforeFindingChildCodeBlocks} ); - # tasks particular to each object $latexIndentObject->tasks_particular_to_each_object; - # removeParagraphLineBreaks and textWrapping fun! - $latexIndentObject->text_wrap_remove_paragraph_line_breaks if($is_m_switch_active and !${$mainSettings{modifyLineBreaks}{textWrapOptions}}{beforeFindingChildCodeBlocks} ); - # store children in special hash push(@{${$self}{children}},$latexIndentObject); diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/FileContents.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/FileContents.pm index 439e764b312..4683cc7a119 100644 --- a/Master/texmf-dist/scripts/latexindent/LatexIndent/FileContents.pm +++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/FileContents.pm @@ -93,7 +93,7 @@ sub find_file_contents_environments_and_preamble{ # text wrapping can make the ID split across lines ${$fileContentsBlock}{idRegExp} = ${$fileContentsBlock}{id}; - if($is_m_switch_active){ + if($is_m_switch_active and ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{huge} ne "overflow"){ my $IDwithLineBreaks = join("\\R?\\h*",split(//,${$fileContentsBlock}{id})); ${$fileContentsBlock}{idRegExp} = qr/$IDwithLineBreaks/s; } @@ -112,7 +112,7 @@ sub find_file_contents_environments_and_preamble{ push(@fileContentsStorageArray,$fileContentsBlock); # log file output - $logger->trace("FILECONTENTS environment found: ${$fileContentsEnv}{name}")if $is_t_switch_active; + $logger->trace("FILECONTENTS environment found: ${$fileContentsBlock}{name}")if $is_t_switch_active; # remove the environment block, and replace with unique ID ${$self}{body} =~ s/$fileContentsRegExp/${$fileContentsBlock}{replacementText}/sx; @@ -157,7 +157,7 @@ sub find_file_contents_environments_and_preamble{ # text wrapping can make the ID split across lines ${$preamble}{idRegExp} = ${$preamble}{id}; - if($is_m_switch_active){ + if($is_m_switch_active and ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{huge} ne "overflow"){ my $IDwithLineBreaks = join("\\R?\\h*",split(//,${$preamble}{id})); ${$preamble}{idRegExp} = qr/$IDwithLineBreaks/s; } @@ -220,6 +220,8 @@ sub find_file_contents_environments_and_preamble{ if($needToStorePreamble){ $preamble->dodge_double_backslash; $preamble->remove_leading_space; + # text wrapping + $preamble->text_wrap() if ($is_m_switch_active and ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{columns} !=0 ); $preamble->find_commands_or_key_equals_values_braces if($mainSettings{preambleCommandsBeforeEnvironments}); $preamble->tasks_particular_to_each_object; push(@{${$self}{children}},$preamble); @@ -238,23 +240,6 @@ sub create_unique_id{ sub tasks_particular_to_each_object{ my $self = shift; - # text wrapping, remove paragraph line breaks - if ($is_m_switch_active){ - $self->yaml_get_textwrap_removeparagraphline_breaks; - } - - # option to textWrap beforeFindingChildCodeBlocks - if( $is_m_switch_active and ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{beforeFindingChildCodeBlocks} == 1){ - # call the remove_paragraph_line_breaks and text_wrap routines - if(${$mainSettings{modifyLineBreaks}{removeParagraphLineBreaks}}{beforeTextWrap}){ - $self->remove_paragraph_line_breaks if ${$self}{removeParagraphLineBreaks}; - $self->text_wrap if (${$self}{textWrapOptions} and ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{perCodeBlockBasis}); - } else { - $self->text_wrap if (${$self}{textWrapOptions} and ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{perCodeBlockBasis}); - $self->remove_paragraph_line_breaks if ${$self}{removeParagraphLineBreaks}; - } - } - # search for environments $self->find_environments if ${$self}{body} =~ m/$environmentBasicRegExp/s; @@ -266,18 +251,6 @@ sub tasks_particular_to_each_object{ # search for commands and special code blocks $self->find_commands_or_key_equals_values_braces_and_special if ${$self}{body} =~ m/$specialBeginAndBracesBracketsBasicRegExp/s; - - # text wrapping, remove paragraph line breaks - if ($is_m_switch_active and ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{beforeFindingChildCodeBlocks} == 0){ - # call the remove_paragraph_line_breaks and text_wrap routines - if(${$mainSettings{modifyLineBreaks}{removeParagraphLineBreaks}}{beforeTextWrap}){ - $self->remove_paragraph_line_breaks if ${$self}{removeParagraphLineBreaks}; - $self->text_wrap if (${$self}{textWrapOptions} and ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{perCodeBlockBasis}); - } else { - $self->text_wrap if (${$self}{textWrapOptions} and ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{perCodeBlockBasis}); - $self->remove_paragraph_line_breaks if ${$self}{removeParagraphLineBreaks}; - } - } } 1; diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/GetYamlSettings.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/GetYamlSettings.pm index 50d33a4f2ff..b8a9aa0d4e1 100644 --- a/Master/texmf-dist/scripts/latexindent/LatexIndent/GetYamlSettings.pm +++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/GetYamlSettings.pm @@ -24,7 +24,7 @@ use File::HomeDir; use Cwd; use Exporter qw/import/; use LatexIndent::LogFile qw/$logger/; -our @EXPORT_OK = qw/yaml_read_settings yaml_modify_line_breaks_settings yaml_get_indentation_settings_for_this_object yaml_poly_switch_get_every_or_custom_value yaml_get_indentation_information yaml_get_object_attribute_for_indentation_settings yaml_alignment_at_ampersand_settings yaml_get_textwrap_removeparagraphline_breaks %mainSettings yaml_get_columns/; +our @EXPORT_OK = qw/yaml_read_settings yaml_modify_line_breaks_settings yaml_get_indentation_settings_for_this_object yaml_poly_switch_get_every_or_custom_value yaml_get_indentation_information yaml_get_object_attribute_for_indentation_settings yaml_alignment_at_ampersand_settings %mainSettings/; # Read in defaultSettings.YAML file our $defaultSettings; @@ -590,100 +590,6 @@ sub yaml_read_settings{ } - if( $is_m_switch_active - and ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{beforeFindingChildCodeBlocks} - and !${$mainSettings{modifyLineBreaks}{textWrapOptions}}{perCodeBlockBasis} ){ - - # the following settings don't make sense, so we change - # - # modifyLineBreaks: - # textWrapOptions: - # perCodeBlockBasis: 0 - # beforeFindingChildCodeBlocks: 1 - # into - # - # modifyLineBreaks: - # textWrapOptions: - # perCodeBlockBasis: 0 - # beforeFindingChildCodeBlocks: 0 - $logger->warn("*textWrapOptions:beforeFindingChildCodeBlocks:1 with textWrapOptions:perCodeBlockBasis:0"); - $logger->warn("turning off beforeFindingChildCodeBlocks by changing textWrapOptions:beforeFindingOtherCodeBlocks to be 0"); - $logger->warn("you need to set *both* values to be 1 to use the beforeFindingChildCodeBlocks feature"); - ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{beforeFindingChildCodeBlocks} = 0; - } - - # modifyLineBreaks: - # textWrapOptions: - # columns: 80 - # perCodeBlockBasis: 1 - # masterDocument: 1 - # - # needs to be interpretted as - # - # modifyLineBreaks: - # textWrapOptions: - # columns: 80 - # perCodeBlockBasis: 1 - # mainDocument: 1 - # - if( $is_m_switch_active - and ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{perCodeBlockBasis} - and ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{masterDocument} ){ - $logger->warn("*textWrapOptions:masterDocument specified when textWrapOptions:mainDocument preferred"); - $logger->warn("setting textWrapOptions:mainDocument: 1, but note that future versions of latexindent.pl may not support this"); - $logger->warn("recommendation to use textWrapOptions:mainDocument: 1 in place of textWrapOptions:masterDocument:1"); - ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{mainDocument} = 1; - } - - # modifyLineBreaks: - # removeParagraphLineBreaks: - # masterDocument: 1 - # - # needs to be interpretted as - # - # modifyLineBreaks: - # removeParagraphLineBreaks: - # mainDocument: 1 - # - if( $is_m_switch_active and ${$mainSettings{modifyLineBreaks}{removeParagraphLineBreaks}}{masterDocument} ){ - $logger->warn("*removeParagraphLineBreaks:masterDocument specified when removeParagraphLineBreaks:mainDocument preferred"); - $logger->warn("setting removeParagraphLineBreaks:mainDocument: 1, but note that future versions of latexindent.pl may not support this"); - $logger->warn("recommendation to use removeParagraphLineBreaks:mainDocument: 1 in place of removeParagraphLineBreaks:masterDocument:1"); - ${$mainSettings{modifyLineBreaks}{removeParagraphLineBreaks}}{mainDocument} = 1; - } - - # modifyLineBreaks: - # textWrapOptions/removeParagraphLineBreaks: - # all: - # except: - # - 'masterDocument' - # - # need to be interpretted as - # - # modifyLineBreaks: - # textWrapOptions/removeParagraphLineBreaks: - # all: - # except: - # - 'mainDocument' - # - if( $is_m_switch_active ){ - foreach ("textWrapOptions","removeParagraphLineBreaks"){ - if ( ref ${$mainSettings{modifyLineBreaks}{$_}}{all} eq "HASH" - and - defined ${${$mainSettings{modifyLineBreaks}{$_}}{all}}{except} - and - ref ${${$mainSettings{modifyLineBreaks}{$_}}{all}}{except} eq "ARRAY") { - my %except = map { $_ => 1 } @{${${$mainSettings{modifyLineBreaks}}{$_}}{all}{except}}; - if($except{masterDocument}){ - $logger->warn("*$_:all:except:masterDocument specified when mainDocument preferred"); - $logger->warn("setting $_:all:except:mainDocument:1, but note that future versions of latexindent.pl may not support this"); - $logger->warn("recommendation to use $_:all:except:mainDocument:1 in place of $_:all:except:masterDocument:1"); - push( @{${${$mainSettings{modifyLineBreaks}}{$_}}{all}{except}}, "mainDocument" ); - } - } - } - } - # some users may wish to see showAmalgamatedSettings # which details the overall state of the settings modified # from the default in various user files @@ -870,188 +776,6 @@ sub yaml_modify_line_breaks_settings{ ); }; - $self->yaml_get_textwrap_removeparagraphline_breaks; - return; -} - -sub yaml_get_textwrap_removeparagraphline_breaks{ - my $self = shift; - - # textWrap and removeParagraphLineBreaks settings - foreach ("textWrapOptions","removeParagraphLineBreaks"){ - - # first check for either - # - # textWrapOptions: - # all: 0 - # - # or - # - # removeParagraphLineBreaks: - # all: 0 - # - # *IMPORTANT* - # even if all is set to 1, then it can still be disabled on either a - # - # per-object: - # - # for example - # - # textWrapOptions: - # all: - # except: - # - environments - # - # will disable textWrapOptions for *all* environments - # - # per-name - # - # for example - # - # textWrapOptions: - # all: - # except: - # - itemize - # - # will disable textWrapOptions for itemize - - # if 'all' is set as a hash, then the default value is 1, to be turned off (possibly) later - ${$self}{$_} = ( ref ${$mainSettings{modifyLineBreaks}{$_}}{all} eq "HASH" ? 1 : ${$mainSettings{modifyLineBreaks}{$_}}{all}); - - # get the columns - if($_ eq "textWrapOptions" and ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{perCodeBlockBasis}){ - $self->yaml_get_columns; - } - - # name of the object in the modifyLineBreaks yaml (e.g environments, ifElseFi, etc) - my $YamlName = ${$self}{modifyLineBreaksYamlName}; - - # if the YamlName is either optionalArguments or mandatoryArguments, then we'll be looking for information about the *parent* - my $name = ($YamlName =~ m/Arguments/) ? ${$self}{parent} : ${$self}{name}; - - # move to the next <thing> if - # - # textWrapOptions/removeParagraphLineBreaks:: - # all: 1 - # - if(${$self}{$_} - and - ref ${$mainSettings{modifyLineBreaks}{$_}}{all} ne "HASH" - and - ${$mainSettings{modifyLineBreaks}{$_}}{all}){ - $logger->trace("$_ for $name is ${$self}{$_}") if $is_t_switch_active; - next; - }; - - # otherwise, look for exceptions, either through - # - # textWrapOptions/removeParagraphLineBreaks: - # all: - # except: - # - <*type* of thing or *name* of thing> - # - # so, for example, the following (per code-block) is acceptable - # which makes an exception for all *environments* - # - # all: - # except: - # - 'environments' - # - # the following (per-name) is acceptable - # which only makes an exception for things called itemize - # - # all: - # except: - # - 'itemize' - # - if(${$self}{$_} - and - defined ${${$mainSettings{modifyLineBreaks}{$_}}{all}}{except} - and - ref ${${$mainSettings{modifyLineBreaks}{$_}}{all}}{except} eq "ARRAY" - ){ - my %except = map { $_ => 1 } @{${${$mainSettings{modifyLineBreaks}}{$_}}{all}{except}}; - if( $except{$name} or $except{$YamlName}){ - ${$self}{$_} = 0; - my $detail = ($except{$name} ? "per-name" : "per-code-block-type"); - $logger->trace("$_ for $name is ${$self}{$_} (found as exception $detail, see $_:all:except)") if $is_t_switch_active; - next; - } - } else { - # or otherwise through, for example - # - # all: 0 - # ifElseFi: 1 - # - # the textWrapOptions/removeParagraphLineBreaks can contain fields that are hashes or scalar - # - if(ref ${$mainSettings{modifyLineBreaks}{$_}}{$YamlName} eq "HASH"){ - # textWrapOptions/removeParagraphLineBreaks: - # all: 0 - # environments: - # quotation: 0 - $logger->trace("*$YamlName specified with fields in $_, looking for $name") if $is_t_switch_active; - ${$self}{$_} = ${${$mainSettings{modifyLineBreaks}{$_}}{$YamlName}}{$name} if (defined ${${$mainSettings{modifyLineBreaks}{$_}}{$YamlName}}{$name}); - } elsif(defined ${$mainSettings{modifyLineBreaks}{$_}}{$YamlName}){ - # textWrapOptions/removeParagraphLineBreaks: - # all: 0 - # environments: 0 - $logger->trace("*$YamlName specified with just a number in $_ ${$mainSettings{modifyLineBreaks}{$_}}{$YamlName}") if $is_t_switch_active; - ${$self}{$_} = ${$mainSettings{modifyLineBreaks}{$_}}{$YamlName} if (defined ${$mainSettings{modifyLineBreaks}{$_}}{$YamlName}); - } - } - - # summary to log file - $logger->trace("$_ for $name is ${$self}{$_}") if $is_t_switch_active; - } - - return; -} - -sub yaml_get_columns{ - my $self = shift; - - my $YamlName = ${$self}{modifyLineBreaksYamlName}; - - # the columns settings can have a variety of different ways of being specified - if(ref ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{columns} eq "HASH"){ - # assign default value of $columns - my $columns; - if(defined ${${$mainSettings{modifyLineBreaks}{textWrapOptions}}{columns}}{default}){ - $columns = ${${$mainSettings{modifyLineBreaks}{textWrapOptions}}{columns}}{default}; - } else { - $columns = 80; - } - - # possibly specify object wrapping on a per-name basis - if(ref ${${$mainSettings{modifyLineBreaks}{textWrapOptions}}{columns}}{$YamlName} eq "HASH"){ - # for example: - # modifyLineBreaks: - # textWrapOptions: - # columns: - # default: 80 - # environments: - # default: 80 - # something: 10 - # another: 20 - if(defined ${${${$mainSettings{modifyLineBreaks}{textWrapOptions}}{columns}}{$YamlName}}{${$self}{name}}){ - $columns = ${${${$mainSettings{modifyLineBreaks}{textWrapOptions}}{columns}}{$YamlName}}{${$self}{name}}; - } elsif (${${${$mainSettings{modifyLineBreaks}{textWrapOptions}}{columns}}{$YamlName}}{default}){ - $columns = ${${${$mainSettings{modifyLineBreaks}{textWrapOptions}}{columns}}{$YamlName}}{default}; - } - } else { - # for example: - # modifyLineBreaks: - # textWrapOptions: - # columns: - # default: 80 - # environments: 10 - $columns = ${${$mainSettings{modifyLineBreaks}{textWrapOptions}}{columns}}{$YamlName}; - } - ${$self}{columns} = $columns; - } else { - ${$self}{columns} = ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{columns}; - } return; } diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/HiddenChildren.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/HiddenChildren.pm index a402a7cbce9..0e6d9657800 100644 --- a/Master/texmf-dist/scripts/latexindent/LatexIndent/HiddenChildren.pm +++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/HiddenChildren.pm @@ -19,6 +19,7 @@ use warnings; use LatexIndent::Switches qw/$is_t_switch_active $is_tt_switch_active $is_m_switch_active /; use LatexIndent::Tokens qw/%tokens/; use LatexIndent::LogFile qw/$logger/; +use LatexIndent::GetYamlSettings qw/%mainSettings/; use Data::Dumper; use Exporter qw/import/; our @EXPORT_OK = qw/find_surrounding_indentation_for_children update_family_tree get_family_tree check_for_hidden_children %familyTree hidden_children_preparation_for_alignment unpack_children_into_body/; @@ -158,7 +159,7 @@ sub check_for_hidden_children{ my @matched; # grab the matches - if($is_m_switch_active){ + if($is_m_switch_active and ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{huge} ne "overflow"){ # if modifyLineBreaks is active, then the IDS can be split across lines my $ifElseFiSpecialBegin = join("\\R?\\h*",split(//,$tokens{ifelsefiSpecial})); my $BeginwithLineBreaks = join("\\R?\\h*",split(//,$tokens{beginOfToken})); diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/ModifyLineBreaks.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/ModifyLineBreaks.pm index 128dcd8ed81..63f6c2d03f6 100644 --- a/Master/texmf-dist/scripts/latexindent/LatexIndent/ModifyLineBreaks.pm +++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/ModifyLineBreaks.pm @@ -17,7 +17,6 @@ package LatexIndent::ModifyLineBreaks; use strict; use warnings; use Exporter qw/import/; -use Text::Wrap; use LatexIndent::GetYamlSettings qw/%mainSettings/; use LatexIndent::Tokens qw/%tokens/; use LatexIndent::TrailingComments qw/$trailingCommentRegExp/; @@ -25,7 +24,7 @@ use LatexIndent::Switches qw/$is_m_switch_active $is_t_switch_active $is_tt_swit use LatexIndent::Item qw/$listOfItems/; use LatexIndent::LogFile qw/$logger/; use LatexIndent::Verbatim qw/%verbatimStorage/; -our @EXPORT_OK = qw/modify_line_breaks_body modify_line_breaks_end modify_line_breaks_end_after adjust_line_breaks_end_parent remove_line_breaks_begin text_wrap remove_paragraph_line_breaks construct_paragraph_reg_exp text_wrap_remove_paragraph_line_breaks verbatim_modify_line_breaks/; +our @EXPORT_OK = qw/modify_line_breaks_body modify_line_breaks_end modify_line_breaks_end_after adjust_line_breaks_end_parent remove_line_breaks_begin verbatim_modify_line_breaks/; our $paragraphRegExp = q(); sub modify_line_breaks_body{ @@ -247,6 +246,7 @@ sub verbatim_modify_line_breaks{ # verbatim modify line breaks are a bit special, as they happen before # any of the main processes have been done my $self = shift; + my %input = @_; while ( my ($key,$child)= each %verbatimStorage){ if(defined ${$child}{BeginStartsOnOwnLine}){ my $BeginStringLogFile = ${$child}{aliases}{BeginStartsOnOwnLine}; @@ -272,191 +272,32 @@ sub verbatim_modify_line_breaks{ ${$self}{body} =~ s/\h*${$child}{id}/$trailingCharacterToken\n${$child}{id}/s; } } - } -} - -sub text_wrap_remove_paragraph_line_breaks{ - my $self = shift; - - if(${$mainSettings{modifyLineBreaks}{removeParagraphLineBreaks}}{beforeTextWrap}){ - $self->remove_paragraph_line_breaks if ${$self}{removeParagraphLineBreaks}; - $self->text_wrap if (${$self}{textWrapOptions} and ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{perCodeBlockBasis}); - } else { - $self->text_wrap if (${$self}{textWrapOptions} and ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{perCodeBlockBasis}); - } - -} - -sub text_wrap{ - - my $self = shift; - - # alignment at ampersand can take priority - return if(${$self}{lookForAlignDelims} and ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{alignAtAmpersandTakesPriority}); - - # goal: get an accurate measurement of verbatim objects; - # - # example: - # Lorem \verb!x+y! ipsum dolor sit amet - # - # is represented as - # - # Lorem LTXIN-TK-VERBATIM1-END ipsum dolor sit amet - # - # so we *measure* the verbatim token and replace it with - # an appropriate-length string - # - # Lorem a2A41233rt ipsum dolor sit amet - # - # and then put the body back to - # - # Lorem LTXIN-TK-VERBATIM1-END ipsum dolor sit amet - # - # following the text wrapping - my @putVerbatimBackIn; - - # check body for verbatim and get measurements - if (${$self}{body} =~ m/$tokens{verbatim}/s and ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{huge} eq "overflow"){ - - # reference: https://stackoverflow.com/questions/10336660/in-perl-how-can-i-generate-random-strings-consisting-of-eight-hex-digits - my @set = ('0' ..'9', 'A' .. 'Z', 'a' .. 'z'); - - # loop through verbatim objects - while( my ($verbatimID,$child)= each %verbatimStorage){ - my $verbatimThing = ${$child}{begin}.${$child}{body}.${$child}{end}; - - # if the object has line breaks, don't measure it - next if $verbatimThing =~ m/\R/s; - - if(${$self}{body} =~m/$verbatimID/s){ - - # measure length - my $verbatimLength = Unicode::GCString->new($verbatimThing)->columns(); - - # create temporary ID, and check that it is not contained in the body - my $verbatimTmpID = join '' => map $set[rand @set], 1 .. $verbatimLength; - while(${$self}{body} =~m/$verbatimTmpID/s){ - $verbatimTmpID = join '' => map $set[rand @set], 1 .. $verbatimLength; + # after text wrap poly-switch check + if ($input{when} eq "afterTextWrap"){ + $logger->trace("*post text wrap poly-switch check for EndFinishesWithLineBreak") if $is_t_switch_active ; + if (defined ${$child}{EndFinishesWithLineBreak} + and ${$child}{EndFinishesWithLineBreak}>=1 + and ${$self}{body} =~m/${$child}{id}\h*\S+/m){ + ${$child}{linebreaksAtEnd}{end} = 1; + + # by default, assume that no trailing comment token is needed + my $trailingCommentToken = q(); + my $lineBreakCharacter = q(); + my $EndStringLogFile = ${$self}{aliases}{EndStartsOnOwnLine}||"EndStartsOnOwnLine"; + + if(${$child}{EndFinishesWithLineBreak}==1){ + $logger->trace("Adding a linebreak at the end of ${$child}{end} (post text wrap $EndStringLogFile==1)") if $is_t_switch_active; + $lineBreakCharacter = "\n"; + } elsif(${$child}{EndFinishesWithLineBreak}==2 and ${$self}{body} !~ m/${$child}{id}\h*$trailingCommentRegExp/s){ + $logger->trace("Adding a % immediately after ${$child}{end} (post text wrap $EndStringLogFile==2)") if $is_t_switch_active; + $trailingCommentToken = "%".$self->add_comment_symbol."\n"; + } elsif(${$child}{EndFinishesWithLineBreak}==3){ + $lineBreakCharacter .= (${$mainSettings{modifyLineBreaks}}{preserveBlankLines}?$tokens{blanklines}:"\n")."\n"; } - - # store for use after the text wrapping - push(@putVerbatimBackIn,{origVerbatimID=>$verbatimID,tmpVerbatimID=>$verbatimTmpID}); - - # make the substitution - ${$self}{body} =~ s/$verbatimID/$verbatimTmpID/s; + ${$self}{body} =~s/${$child}{id}(\h*)/${$child}{id}$1$trailingCommentToken$lineBreakCharacter/s; } } } - - # call the text wrapping routine - my $columns; - - # columns might have been defined by the user - if(defined ${$self}{columns}){ - $columns = ${$self}{columns}; - } elsif(ref ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{columns} eq "HASH"){ - if(defined ${${$mainSettings{modifyLineBreaks}{textWrapOptions}}{columns}}{default}){ - $columns = ${${$mainSettings{modifyLineBreaks}{textWrapOptions}}{columns}}{default}; - } else { - $columns = 80; - } - } elsif (defined ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{columns}){ - $columns = ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{columns} ; - } else { - $columns = 80; - } - - # vital Text::Wrap options - $Text::Wrap::columns=$columns; - $Text::Wrap::huge = ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{huge}; - - # all other Text::Wrap options not usually needed/helpful, but available - $Text::Wrap::separator=${$mainSettings{modifyLineBreaks}{textWrapOptions}}{separator} if(${$mainSettings{modifyLineBreaks}{textWrapOptions}}{separator} ne ''); - $Text::Wrap::break = ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{break} if ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{break}; - $Text::Wrap::unexpand = ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{unexpand} if ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{unexpand}; - $Text::Wrap::tabstop = ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{tabstop} if ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{tabstop}; - - # perform the text wrapping - ${$self}{body} = wrap('','',${$self}{body}); - - ${$self}{body} =~ s/${$_}{tmpVerbatimID}/${$_}{origVerbatimID}/s foreach (@putVerbatimBackIn); } -sub construct_paragraph_reg_exp{ - my $self = shift; - - $logger->trace("*Constructing the paragraph-stop regexp (see paragraphsStopAt)") if $is_t_switch_active ; - my $stopAtRegExp = q(); - while( my ($paragraphStopAt,$yesNo)= each %{${$mainSettings{modifyLineBreaks}{removeParagraphLineBreaks}}{paragraphsStopAt}}){ - if($yesNo){ - # the headings (chapter, section, etc) need a slightly special treatment - $paragraphStopAt = "afterHeading" if($paragraphStopAt eq "heading"); - - # the comment need a slightly special treatment - $paragraphStopAt = "trailingComment" if($paragraphStopAt eq "comments"); - - # output to log file - $logger->trace("The paragraph-stop regexp WILL include $tokens{$paragraphStopAt} (see paragraphsStopAt)") if $is_t_switch_active ; - - # update the regexp - if($paragraphStopAt eq "items"){ - $stopAtRegExp .= "|(?:\\\\(?:".$listOfItems."))"; - } else { - $stopAtRegExp .= "|(?:".($paragraphStopAt eq "trailingComment" ? "%" : q() ).$tokens{$paragraphStopAt}."\\d+)"; - } - } else { - $logger->trace("The paragraph-stop regexp won't include $tokens{$paragraphStopAt} (see paragraphsStopAt)") if ($tokens{$paragraphStopAt} and $is_t_switch_active); - } - } - - $paragraphRegExp = qr/ - ^ - (?!$tokens{beginOfToken}) - (\w - (?: - (?! - (?:$tokens{blanklines}|\\par) - ). - )*? - ) - ( - (?: - ^(?:(\h*\R)|\\par|$tokens{blanklines}$stopAtRegExp) - ) - | - \z # end of string - )/sxm; - - $logger->trace("The paragraph-stop-regexp is:") if $is_tt_switch_active ; - $logger->trace($paragraphRegExp) if $is_tt_switch_active ; -} - -sub remove_paragraph_line_breaks{ - my $self = shift; - return unless ${$self}{removeParagraphLineBreaks}; - - # alignment at ampersand can take priority - return if(${$self}{lookForAlignDelims} and ${$mainSettings{modifyLineBreaks}{removeParagraphLineBreaks}}{alignAtAmpersandTakesPriority}); - - $logger->trace("Checking ${$self}{name} for paragraphs (see removeParagraphLineBreaks)") if $is_t_switch_active; - - my $paragraphCounter; - my @paragraphStorage; - - ${$self}{body} =~ s/$paragraphRegExp/ - $paragraphCounter++; - push(@paragraphStorage,{id=>$tokens{paragraph}.$paragraphCounter.$tokens{endOfToken},value=>$1}); - - # replace comment with dummy text - $tokens{paragraph}.$paragraphCounter.$tokens{endOfToken}.$2; - /xsmeg; - - while( my $paragraph = pop @paragraphStorage){ - # remove all line breaks from paragraph, except for any at the very end - ${$paragraph}{value} =~ s/\R(?!\z)/ /sg; - ${$self}{body} =~ s/${$paragraph}{id}/${$paragraph}{value}/; - } -} - - 1; diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/Preamble.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/Preamble.pm index eab45a10d9a..bade8d42d11 100644 --- a/Master/texmf-dist/scripts/latexindent/LatexIndent/Preamble.pm +++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/Preamble.pm @@ -51,23 +51,6 @@ sub indent{ sub tasks_particular_to_each_object{ my $self = shift; - # text wrapping, remove paragraph line breaks - if ($is_m_switch_active){ - $self->yaml_get_textwrap_removeparagraphline_breaks; - } - - # option to textWrap beforeFindingChildCodeBlocks - if( $is_m_switch_active and ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{beforeFindingChildCodeBlocks} == 1){ - # call the remove_paragraph_line_breaks and text_wrap routines - if(${$mainSettings{modifyLineBreaks}{removeParagraphLineBreaks}}{beforeTextWrap}){ - $self->remove_paragraph_line_breaks if ${$self}{removeParagraphLineBreaks}; - $self->text_wrap if (${$self}{textWrapOptions} and ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{perCodeBlockBasis}); - } else { - $self->text_wrap if (${$self}{textWrapOptions} and ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{perCodeBlockBasis}); - $self->remove_paragraph_line_breaks if ${$self}{removeParagraphLineBreaks}; - } - } - # search for environments $self->find_environments if ${$self}{body} =~ m/$environmentBasicRegExp/; @@ -87,19 +70,6 @@ sub tasks_particular_to_each_object{ # search for special begin/end $self->find_special if ${$self}{body} =~ m/$specialBeginBasicRegExp/s; } - - # text wrapping, remove paragraph line breaks - if ($is_m_switch_active and ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{beforeFindingChildCodeBlocks} == 0){ - # call the remove_paragraph_line_breaks and text_wrap routines - if(${$mainSettings{modifyLineBreaks}{removeParagraphLineBreaks}}{beforeTextWrap}){ - $self->remove_paragraph_line_breaks if ${$self}{removeParagraphLineBreaks}; - $self->text_wrap if (${$self}{textWrapOptions} and ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{perCodeBlockBasis}); - } else { - $self->text_wrap if (${$self}{textWrapOptions} and ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{perCodeBlockBasis}); - $self->remove_paragraph_line_breaks if ${$self}{removeParagraphLineBreaks}; - } - } - } 1; diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/Sentence.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/Sentence.pm index d41c8869b6b..9370f55886d 100644 --- a/Master/texmf-dist/scripts/latexindent/LatexIndent/Sentence.pm +++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/Sentence.pm @@ -251,8 +251,7 @@ sub one_sentence_per_line{ ); # text wrapping - $sentenceObj->yaml_get_columns; - if(${$sentenceObj}{columns}<=0){ + if(${$mainSettings{modifyLineBreaks}{textWrapOptions}}{columns}==0){ $logger->warn("*Sentence text wrap warning:"); $logger->info("You have specified oneSentencePerLine:textWrapSentences, but columns is set to 0"); $logger->info("You might wish to specify, for example: modifyLineBreaks: textWrapOptions: columns: 80"); @@ -305,8 +304,8 @@ sub tasks_particular_to_each_object{ my $self = shift; # option to text wrap (and option to indent) sentences - if(${$mainSettings{modifyLineBreaks}{oneSentencePerLine}}{textWrapSentences}){ - $self->yaml_get_columns; + if(${$mainSettings{modifyLineBreaks}{oneSentencePerLine}}{textWrapSentences} + and ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{columns} !=0 ){ $self->text_wrap; } diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/Tokens.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/Tokens.pm index 2e358e0b62f..98926a97594 100644 --- a/Master/texmf-dist/scripts/latexindent/LatexIndent/Tokens.pm +++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/Tokens.pm @@ -48,6 +48,7 @@ our %tokens = ( arguments=>$beginningToken."ARGUMENTS", roundBracket=>$beginningToken."ROUND-BRACKET", verbatim=>$beginningToken."VERBATIM", + verbatimInline=>$beginningToken."VERBATIM-inline", preamble=>$beginningToken."preamble", beginOfToken=>$beginningToken, doubleBackSlash=>$beginningToken."DOUBLEBACKSLASH", diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/TrailingComments.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/TrailingComments.pm index 7d03349c528..82ff154c876 100644 --- a/Master/texmf-dist/scripts/latexindent/LatexIndent/TrailingComments.pm +++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/TrailingComments.pm @@ -99,7 +99,9 @@ sub put_trailing_comments_back_in{ # the -m switch can modify max characters per line, and trailing comment IDs can # be split across lines - if($is_m_switch_active and ${$self}{body} !~ m/%$trailingcommentID/m){ + if($is_m_switch_active + and ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{huge} ne "overflow" + and ${$self}{body} !~ m/%$trailingcommentID/m){ $logger->trace("$trailingcommentID not found in body using /m matching, assuming it has been split across line (see modifyLineBreaks: textWrapOptions)") if($is_t_switch_active); my $trailingcommentIDwithLineBreaks; @@ -126,6 +128,8 @@ sub put_trailing_comments_back_in{ /mx and $1 ne ''){ $logger->trace("Comment not at end of line $trailingcommentID, moving it to end of line")if $is_t_switch_active; ${$self}{body} =~ s/%$trailingcommentID(.*)$/$1%$trailingcommentValue/m; + #####if(${$self}{body} =~ m/%$trailingcommentID\h*[^%]+?$/mx){ + ##### $logger->trace("Comment not at end of line $trailingcommentID, moving it to end of line") if $is_t_switch_active; } else { ${$self}{body} =~ s/%$trailingcommentID/%$trailingcommentValue/; } diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/Verbatim.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/Verbatim.pm index 0bb41c52272..edff0698a84 100644 --- a/Master/texmf-dist/scripts/latexindent/LatexIndent/Verbatim.pm +++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/Verbatim.pm @@ -332,6 +332,13 @@ sub find_verbatim_commands{ # output, if desired $logger->trace(Dumper($verbatimCommand),'ttrace') if($is_tt_switch_active); + # check for nested verbatim commands + if(${$verbatimCommand}{body} =~ m/($tokens{verbatimInline}\d+$tokens{endOfToken})/s){ + my $verbatimNestedID = $1; + my $verbatimBody = ${$verbatimStorage{$verbatimNestedID}}{begin}.${$verbatimStorage{$verbatimNestedID}}{body}.${$verbatimStorage{$verbatimNestedID}}{end}; + ${$verbatimCommand}{body} =~ s/$verbatimNestedID/$verbatimBody/s; + delete $verbatimStorage{$verbatimNestedID}; + } # verbatim children go in special hash $verbatimStorage{${$verbatimCommand}{id}}=$verbatimCommand; @@ -534,7 +541,7 @@ sub create_unique_id{ my $self = shift; $verbatimCounter++; - ${$self}{id} = "$tokens{verbatim}$verbatimCounter$tokens{endOfToken}"; + ${$self}{id} = (${$self}{type} eq 'command' ? $tokens{verbatimInline} : $tokens{verbatim}).$verbatimCounter.$tokens{endOfToken}; return; } diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/Version.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/Version.pm index 313d0ffb02c..7727a270e98 100644 --- a/Master/texmf-dist/scripts/latexindent/LatexIndent/Version.pm +++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/Version.pm @@ -19,6 +19,6 @@ use warnings; use Exporter qw/import/; our @EXPORT_OK = qw/$versionNumber $versionDate/; -our $versionNumber = '3.15'; -our $versionDate = '2022-01-21'; +our $versionNumber = '3.16'; +our $versionDate = '2022-03-13'; 1 diff --git a/Master/texmf-dist/scripts/latexindent/LatexIndent/Wrap.pm b/Master/texmf-dist/scripts/latexindent/LatexIndent/Wrap.pm new file mode 100644 index 00000000000..a2b8383d94b --- /dev/null +++ b/Master/texmf-dist/scripts/latexindent/LatexIndent/Wrap.pm @@ -0,0 +1,317 @@ +package LatexIndent::Wrap; +# This program is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# See http://www.gnu.org/licenses/. +# +# Chris Hughes, 2017 +# +# For all communication, please visit: https://github.com/cmhughes/latexindent.pl +use strict; +use warnings; +use Text::Wrap; +use LatexIndent::Tokens qw/%tokens/; +use LatexIndent::TrailingComments qw/$trailingCommentRegExp/; +use LatexIndent::GetYamlSettings qw/%mainSettings/; +use LatexIndent::Switches qw/$is_t_switch_active $is_tt_switch_active $is_m_switch_active/; +use LatexIndent::LogFile qw/$logger/; +use LatexIndent::Verbatim qw/%verbatimStorage/; +use Exporter qw/import/; +our @ISA = "LatexIndent::Document"; # class inheritance, Programming Perl, pg 321 +our @EXPORT_OK = qw/text_wrap/; +our $sentenceCounter; + +sub text_wrap{ + my $self = shift; + + $logger->trace("*Text wrap regular expression construction: (see textWrapOptions: )") if $is_t_switch_active; + + # textWrap Blocks FOLLOW + # textWrap Blocks FOLLOW + # textWrap Blocks FOLLOW + my $blocksFollow = q(); + my $blocksFollowHash = \%{${$mainSettings{modifyLineBreaks}{textWrapOptions}}{blocksFollow}}; + + foreach my $blocksFollowEachPart (sort keys %{$blocksFollowHash}) { + my $yesNo = $blocksFollowHash->{$blocksFollowEachPart}; + if($yesNo){ + if($blocksFollowEachPart eq "par"){ + $blocksFollowEachPart = qr/\R?\\par/s; + } elsif ($blocksFollowEachPart eq "blankLine"){ + $blocksFollowEachPart = qr/ + (?:\A(?:$tokens{blanklines}\R)+) # the order of each of these + | # is important, as (like always) the first + (?:\G(?:$tokens{blanklines}\R)+) # thing to be matched will + | # be accepted + (?:(?:$tokens{blanklines}\h*\R)+) + | + \R{2,} + | + \G + /sx; + } elsif ($blocksFollowEachPart eq "commentOnPreviousLine"){ + $blocksFollowEachPart = qr/^$trailingCommentRegExp/m; + } elsif ($blocksFollowEachPart eq "verbatim"){ + $blocksFollowEachPart = qr/$tokens{verbatim}\d+$tokens{endOfToken}/; + } elsif ($blocksFollowEachPart eq "filecontents"){ + $blocksFollowEachPart = qr/$tokens{filecontents}\d+$tokens{endOfToken}/; + } elsif ($blocksFollowEachPart eq "headings"){ + $blocksFollowEachPart = q(); + + my %headingsLevels = %{$mainSettings{indentAfterHeadings}}; + while( my ($headingName,$headingInfo)= each %headingsLevels){ + # check for a * in the name + $headingName =~ s/\*/\\\*/g; + + # make the regex as + # + # headingName + # <hspace> # possible horizontal space + # []? # possible optional argument + # <hspace> # possible horizontal space + # {} # mandatory argument + # + $headingName = qr/\\$headingName\h*(?:\[[^]]*?\])?\h*\{[^}]*?\}\h*(?:\\label\{[^}]*?\})?/m; + + # put starred headings at the front of the regexp + if($headingName =~ m/\*/){ + $blocksFollowEachPart = $headingName.($blocksFollowEachPart eq '' ?q():"|$blocksFollowEachPart"); + } else { + $blocksFollowEachPart .= ($blocksFollowEachPart eq '' ?q():"|").$headingName ; + } + } + } elsif ($blocksFollowEachPart eq "other"){ + $blocksFollowEachPart = qr/$yesNo/x; + } + $blocksFollow .= ($blocksFollow eq '' ? q() : "|").qr/$blocksFollowEachPart/sx; + } + } + + # if blankLine is not active from blocksFollow then we need to set up the + # beginning of the string, but make sure that it is *not* followed by a + # blank line token, or a blank line + if(!${${$mainSettings{modifyLineBreaks}{textWrapOptions}}{blocksFollow}}{blankLine}){ + $blocksFollow .= ($blocksFollow eq '' ? q() : "|"). + qr/ + \G + (?!$tokens{blanklines}) + /sx; + } + + # followed by 0 or more h-space and line breaks + $blocksFollow = ($blocksFollow eq '' ? q() : qr/(?:$blocksFollow)(?:\h|\R)*/sx ); + + $logger->trace("textWrap blocks follow regexp:") if $is_tt_switch_active; + $logger->trace($blocksFollow) if $is_tt_switch_active; + + # textWrap Blocks BEGIN with + # textWrap Blocks BEGIN with + # textWrap Blocks BEGIN with + my $blocksBeginWith = q(); + my $blocksBeginWithHash = \%{${$mainSettings{modifyLineBreaks}{textWrapOptions}}{blocksBeginWith}}; + + foreach my $blocksBeginWithEachPart (sort keys %{$blocksBeginWithHash}) { + my $yesNo = $blocksBeginWithHash->{$blocksBeginWithEachPart}; + if($yesNo){ + if($blocksBeginWithEachPart eq "A-Z"){ + $logger->trace("textWrap Blocks BEGINS with capital letters (see textWrap:blocksBeginWith:A-Z)") if $is_t_switch_active; + $blocksBeginWithEachPart = qr/(?!(?:$tokens{blanklines}|$tokens{verbatim}|$tokens{preamble}))[A-Z]/; + } elsif ($blocksBeginWithEachPart eq "a-z"){ + $logger->trace("textWrap Blocks BEGINS with lower-case letters (see textWrap:blocksBeginWith:a-z)") if $is_t_switch_active; + $blocksBeginWithEachPart = qr/[a-z]/; + } elsif ($blocksBeginWithEachPart eq "0-9"){ + $logger->trace("textWrap Blocks BEGINS with numbers (see textWrap:blocksBeginWith:0-9)") if $is_t_switch_active; + $blocksBeginWithEachPart = qr/[0-9]/; + } elsif ($blocksBeginWithEachPart eq "other"){ + $logger->trace("textWrap Blocks BEGINS with other $yesNo (reg exp) (see textWrap:blocksBeginWith:other)") if $is_t_switch_active; + $blocksBeginWithEachPart = qr/$yesNo/; + } + $blocksBeginWith .= ($blocksBeginWith eq "" ? q(): "|" ).$blocksBeginWithEachPart; + } + } + $blocksBeginWith = qr/$blocksBeginWith/; + + # textWrap Blocks END with + # textWrap Blocks END with + # textWrap Blocks END with + my $blocksEndBefore = q(); + my $blocksEndBeforeHash = \%{${$mainSettings{modifyLineBreaks}{textWrapOptions}}{blocksEndBefore}}; + + foreach my $blocksEndBeforeEachPart (sort keys %{$blocksEndBeforeHash}) { + my $yesNo = $blocksEndBeforeHash->{$blocksEndBeforeEachPart}; + if($yesNo){ + if ($blocksEndBeforeEachPart eq "other"){ + $logger->trace("textWrap Blocks ENDS with other $yesNo (reg exp) (see textWrap:blocksEndBefore:other)") if $is_t_switch_active; + $blocksEndBeforeEachPart = qr/\R?$yesNo/; + } elsif ($blocksEndBeforeEachPart eq "commentOnOwnLine"){ + $logger->trace("textWrap Blocks ENDS with commentOnOwnLine (see textWrap:blocksEndBefore:commentOnOwnLine)") if $is_t_switch_active; + $blocksEndBeforeEachPart = qr/^$trailingCommentRegExp/m; + } elsif ($blocksEndBeforeEachPart eq "verbatim"){ + $logger->trace("textWrap Blocks ENDS with verbatim (see textWrap:blocksEndBefore:verbatim)") if $is_t_switch_active; + $blocksEndBeforeEachPart = qr/$tokens{verbatim}\d/; + } elsif ($blocksEndBeforeEachPart eq "filecontents"){ + $logger->trace("textWrap Blocks ENDS with filecontents (see textWrap:blocksEndBefore:filecontents)") if $is_t_switch_active; + $blocksEndBeforeEachPart = qr/$tokens{filecontents}/; + } + $blocksEndBefore .= ($blocksEndBefore eq "" ? q(): "|" ).$blocksEndBeforeEachPart; + } + } + $blocksEndBefore = qr/$blocksEndBefore/; + + # the OVERALL textWrap Blocks regexp + # the OVERALL textWrap Blocks regexp + # the OVERALL textWrap Blocks regexp + $logger->trace("Overall textWrap Blocks end with regexp:") if $is_tt_switch_active; + $logger->trace($blocksEndBefore) if $is_tt_switch_active; + + # store the text wrap blocks + my @textWrapBlockStorage = split(/($blocksFollow)/,${$self}{body}); + + # sentences need special treatment + if (${$self}{modifyLineBreaksYamlName} eq 'sentence'){ + @textWrapBlockStorage = (${$self}{body}); + } + + # call the text wrapping routine + my $columns = ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{columns}; + + # vital Text::Wrap options + $Text::Wrap::columns=$columns; + $Text::Wrap::huge = ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{huge}; + + # all other Text::Wrap options not usually needed/helpful, but available + $Text::Wrap::separator = ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{separator} if(${$mainSettings{modifyLineBreaks}{textWrapOptions}}{separator} ne ''); + $Text::Wrap::break = ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{break} if ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{break}; + $Text::Wrap::unexpand = ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{unexpand} if ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{unexpand}; + $Text::Wrap::tabstop = ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{tabstop} if ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{tabstop}; + + # clear the body, which will be updated with newly wrapped body + ${$self}{body} = q(); + + # loop back through the text wrap block storage + foreach my $textWrapBlockStorageValue (@textWrapBlockStorage){ + if ($textWrapBlockStorageValue =~ m/^\s*$blocksBeginWith/s or ${$self}{modifyLineBreaksYamlName} eq 'sentence') { + + # LIMIT is one greater than the maximum number of times EXPR may be split + my @textWrapBeforeEndWith = split(/($blocksEndBefore)/,$textWrapBlockStorageValue,2); + + # sentences need special treatment + if (${$self}{modifyLineBreaksYamlName} eq 'sentence'){ + @textWrapBeforeEndWith = (); + } + + # if we have an occurence of blocksEndBefore, then grab the stuff before it + if (scalar @textWrapBeforeEndWith > 1){ + $textWrapBlockStorageValue = $textWrapBeforeEndWith[0]; + } + + $logger->trace("TEXTWRAP BLOCK: $textWrapBlockStorageValue") if $is_tt_switch_active; + + # initiate the trailing comments storage + my $trailingComments = q(); + + # grab all *internal* trailing comments from the block + while($textWrapBlockStorageValue =~ m|$trailingCommentRegExp|){ + $textWrapBlockStorageValue =~ s|(\h*$trailingCommentRegExp)||s; + $trailingComments .= $1; + } + + # remove internal line breaks + $textWrapBlockStorageValue =~ s/\R(?!\Z)/ /sg; + + # convert multiple spaces into single + $textWrapBlockStorageValue =~ s/\h{2,}/ /sg if ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{multipleSpacesToSingle}; + + # goal: get an accurate measurement of verbatim objects; + # + # example: + # Lorem \verb!x+y! ipsum dolor sit amet + # + # is represented as + # + # Lorem LTXIN-TK-VERBATIM1-END ipsum dolor sit amet + # + # so we *measure* the verbatim token and replace it with + # an appropriate-length string + # + # Lorem a2A41233rt ipsum dolor sit amet + # + # and then put the body back to + # + # Lorem LTXIN-TK-VERBATIM1-END ipsum dolor sit amet + # + # following the text wrapping + my @putVerbatimBackIn; + + # check body for verbatim and get measurements + if ($textWrapBlockStorageValue =~ m/$tokens{verbatim}/s and ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{huge} eq "overflow"){ + + # reference: https://stackoverflow.com/questions/10336660/in-perl-how-can-i-generate-random-strings-consisting-of-eight-hex-digits + my @set = ('0' ..'9', 'A' .. 'Z', 'a' .. 'z'); + + # loop through verbatim objects + while( my ($verbatimID,$child)= each %verbatimStorage){ + my $verbatimThing = ${$child}{begin}.${$child}{body}.${$child}{end}; + + # if the object has line breaks, don't measure it + next if $verbatimThing =~ m/\R/s; + + if($textWrapBlockStorageValue =~m/$verbatimID/s){ + + # measure length + my $verbatimLength = Unicode::GCString->new($verbatimThing)->columns(); + + # create temporary ID, and check that it is not contained in the body + my $verbatimTmpID = join '' => map $set[rand @set], 1 .. $verbatimLength; + while($textWrapBlockStorageValue=~m/$verbatimTmpID/s){ + $verbatimTmpID = join '' => map $set[rand @set], 1 .. $verbatimLength; + } + + # store for use after the text wrapping + push(@putVerbatimBackIn,{origVerbatimID=>$verbatimID,tmpVerbatimID=>$verbatimTmpID}); + + # make the substitution + $textWrapBlockStorageValue =~ s/$verbatimID/$verbatimTmpID/s; + } + } + } + + # perform the text wrap routine + $textWrapBlockStorageValue = wrap('','',$textWrapBlockStorageValue) if ${$mainSettings{modifyLineBreaks}{textWrapOptions}}{columns} > 0; + + # append trailing comments from WITHIN the block + $textWrapBlockStorageValue =~ s/\R?$/$trailingComments\n/s if ($trailingComments ne ''); + + # append blocksEndBefore and the stuff following it + if (scalar @textWrapBeforeEndWith > 1){ + $textWrapBlockStorageValue .= $textWrapBeforeEndWith[1].$textWrapBeforeEndWith[2]; + } + + # put blank line tokens on their own lines, should only happen when the following is used: + # blocksFollow: + # blankLine: 0 + while ($textWrapBlockStorageValue =~ m/^\H.*?$tokens{blanklines}/m ){ + $textWrapBlockStorageValue =~ s/^(\H.*?)$tokens{blanklines}/$1\n$tokens{blanklines}/m; + } + + # remove surrounding spaces from blank line tokens + $textWrapBlockStorageValue =~ s/^\h*$tokens{blanklines}\h*/$tokens{blanklines}/mg; + + # put verbatim back in + $textWrapBlockStorageValue=~ s/${$_}{tmpVerbatimID}/${$_}{origVerbatimID}/s foreach (@putVerbatimBackIn); + } + + # update the body + ${$self}{body} .= $textWrapBlockStorageValue; + } + +} + +1; diff --git a/Master/texmf-dist/scripts/latexindent/defaultSettings.yaml b/Master/texmf-dist/scripts/latexindent/defaultSettings.yaml index f375b470230..fabc5f5b6e9 100755 --- a/Master/texmf-dist/scripts/latexindent/defaultSettings.yaml +++ b/Master/texmf-dist/scripts/latexindent/defaultSettings.yaml @@ -1,4 +1,4 @@ -# defaultSettings.yaml for latexindent.pl, version 3.15, 2022-01-21 +# defaultSettings.yaml for latexindent.pl, version 3.16, 2022-03-13 # a script that aims to # beautify .tex, .sty, .cls files # @@ -216,6 +216,10 @@ lookForAlignDelims: vNiceArrayRC: 1 VNiceArrayRC: 1 NiceArrayRCwithDelims: 1 + # tabularray + tblr: 1 + longtblr: 1 + talltblr: 1 # if you want the script to look for \item commands # and format it, as follows (for example), @@ -490,7 +494,7 @@ modifyLineBreaks: oneSentencePerLine: manipulateSentences: 0 removeSentenceLineBreaks: 1 - textWrapSentences: 0 + textWrapSentences: 0 # setting to 1 disables main textWrap routine sentenceIndent: "" sentencesFollow: par: 1 @@ -513,48 +517,28 @@ modifyLineBreaks: other: 0 textWrapOptions: columns: 0 - huge: overflow # forbid mid-word line breaks + multipleSpacesToSingle: 1 + blocksFollow: + headings: 1 + commentOnPreviousLine: 1 + par: 1 + blankLine: 1 + verbatim: 1 + filecontents: 1 + other: '\\\]|\\item(?:\h|\[)' # regex + blocksBeginWith: + A-Z: 1 + a-z: 1 + 0-9: 0 + other: 0 # regex + blocksEndBefore: + commentOnOwnLine: 1 + verbatim: 1 + filecontents: 1 + other: '\\begin\{|\\\[|\\end\{' # regex + huge: overflow # forbid mid-word line breaks separator: "" - perCodeBlockBasis: 0 - beforeFindingChildCodeBlocks: 0 - all: 0 - alignAtAmpersandTakesPriority: 1 - environments: - quotation: 0 - ifElseFi: 0 - optionalArguments: 0 - mandatoryArguments: 0 - items: 0 - specialBeginEnd: 0 - afterHeading: 0 - preamble: 0 - filecontents: 0 - mainDocument: 0 - removeParagraphLineBreaks: - all: 0 - beforeTextWrap: 0 - alignAtAmpersandTakesPriority: 1 - environments: - quotation: 0 - ifElseFi: 0 - optionalArguments: 0 - mandatoryArguments: 0 - items: 0 - specialBeginEnd: 0 - afterHeading: 0 - preamble: 0 - filecontents: 0 - mainDocument: 0 - paragraphsStopAt: - environments: 1 - verbatim: 1 - commands: 0 - ifElseFi: 0 - items: 0 - specialBeginEnd: 0 - heading: 0 - filecontents: 0 - comments: 0 + # poly-switches below here environments: BeginStartsOnOwnLine: 0 BodyStartsOnOwnLine: 0 diff --git a/Master/texmf-dist/scripts/latexindent/latexindent.pl b/Master/texmf-dist/scripts/latexindent/latexindent.pl index d52f46f10fd..70edb2f4a75 100755 --- a/Master/texmf-dist/scripts/latexindent/latexindent.pl +++ b/Master/texmf-dist/scripts/latexindent/latexindent.pl @@ -1,5 +1,5 @@ #!/usr/bin/env perl -# latexindent.pl, version 3.15, 2022-01-21 +# latexindent.pl, version 3.16, 2022-03-13 # # This program is free software: you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by |