summaryrefslogtreecommitdiff
path: root/support/latexindent/documentation/sec-the-m-switch.tex
diff options
context:
space:
mode:
Diffstat (limited to 'support/latexindent/documentation/sec-the-m-switch.tex')
-rw-r--r--support/latexindent/documentation/sec-the-m-switch.tex164
1 files changed, 78 insertions, 86 deletions
diff --git a/support/latexindent/documentation/sec-the-m-switch.tex b/support/latexindent/documentation/sec-the-m-switch.tex
index c77ed24ec4..d8cdbe62c6 100644
--- a/support/latexindent/documentation/sec-the-m-switch.tex
+++ b/support/latexindent/documentation/sec-the-m-switch.tex
@@ -136,35 +136,26 @@ latexindent.pl -m textwrap3.tex -o textwrap3-mod1.tex -l textwrap1.yaml
\cmhlistingsfromfile{demonstrations/textwrap3-mod1.tex}{\texttt{textwrap3-mod1.tex}}{lst:textwrap3-mod1}
- The text wrapping routine of \texttt{latexindent.pl} is performed by the
- \texttt{Text::Wrap} module, which provides a \texttt{separator} feature
- to separate lines with characters other than a new line (see
- \cite{textwrap}). By default, the separator is empty which means that a new
- line token will be used, but you can change it as you see fit.
-
- For example starting with the file in \cref{lst:textwrap4}
-
- \cmhlistingsfromfile{demonstrations/textwrap4.tex}{\texttt{textwrap4.tex}}{lst:textwrap4}
- and using \texttt{textwrap2.yaml} from \cref{lst:textwrap2-yaml} with the following
- command
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \index{switches!-o demonstration}
- \begin{commandshell}
-latexindent.pl -m textwrap4.tex -o textwrap4-mod2.tex -l textwrap2.yaml
-\end{commandshell}
- then we obtain the output in \cref{lst:textwrap4-mod2}.
+ 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.
- \begin{cmhtcbraster}[raster column skip=.1\linewidth]
- \cmhlistingsfromfile{demonstrations/textwrap4-mod2.tex}{\texttt{textwrap4-mod2.tex}}{lst:textwrap4-mod2}
- \cmhlistingsfromfile{demonstrations/textwrap2.yaml}[MLB-TCB]{\texttt{textwrap2.yaml}}{lst:textwrap2-yaml}
- \end{cmhtcbraster}
+ 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 recommend
+ changing this field.
+ \end{warning}
- There are options to specify the \texttt{huge} option for the
- \texttt{Text::Wrap} module \cite{textwrap}
- \announce{2019-09-07}{huge option for text wrap module}. This can be helpful if you would like to forbid the
- \texttt{Text::Wrap} routine from breaking words. For example, using the settings
- in \cref{lst:textwrap2A-yaml,lst:textwrap2B-yaml} and running the commands
+ 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}
\index{switches!-o demonstration}
@@ -176,10 +167,10 @@ latexindent.pl -m textwrap4.tex -o=+-mod2B -l textwrap2B.yaml
\begin{cmhtcbraster}[raster column skip=.1\linewidth]
\cmhlistingsfromfile{demonstrations/textwrap4-mod2A.tex}{\texttt{textwrap4-mod2A.tex}}{lst:textwrap4-mod2A}
- \cmhlistingsfromfile{demonstrations/textwrap2A.yaml}[MLB-TCB]{\texttt{textwrap2A.yaml}}{lst:textwrap2A-yaml}
+ \cmhlistingsfromfile*{demonstrations/textwrap2A.yaml}[MLB-TCB]{\texttt{textwrap2A.yaml}}{lst:textwrap2A-yaml}
\cmhlistingsfromfile{demonstrations/textwrap4-mod2B.tex}{\texttt{textwrap4-mod2B.tex}}{lst:textwrap4-mod2B}
- \cmhlistingsfromfile{demonstrations/textwrap2B.yaml}[MLB-TCB]{\texttt{textwrap2B.yaml}}{lst:textwrap2B-yaml}
+ \cmhlistingsfromfile*{demonstrations/textwrap2B.yaml}[MLB-TCB]{\texttt{textwrap2B.yaml}}{lst:textwrap2B-yaml}
\end{cmhtcbraster}
You can also specify the \texttt{tabstop}
@@ -204,10 +195,11 @@ latexindent.pl -m textwrap-ts.tex -o=+-mod1 -l tabstop.yaml
\cmhlistingsfromfile[showtabs=true]*{demonstrations/textwrap-ts-mod1.tex}{\texttt{textwrap-ts-mod1.tex}}{lst:textwrap-ts-mod1}
\end{cmhtcbraster}
- You can specify \texttt{break} and \texttt{unexpand} options in
- your settings in analogous ways to those demonstrated in \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.
+ You can specify \texttt{separator}, \texttt{break} and
+ \texttt{unexpand} options in your settings in analogous ways to those
+ demonstrated in \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}
By default, if the value of \texttt{columns} is greater than 0 and the
@@ -223,7 +215,7 @@ latexindent.pl -m textwrap-ts.tex -o=+-mod1 -l tabstop.yaml
In particular, note the field \texttt{perCodeBlockBasis: 0}.
\index{specialBeginEnd!textWrapOptions}
- \cmhlistingsfromfile[style=textWrapOptionsAll]*{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{textWrapOptions}}{lst:textWrapOptionsAll}
+ \cmhlistingsfromfile*[style=textWrapOptionsAll]*{../defaultSettings.yaml}[MLB-TCB,width=.85\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
@@ -375,7 +367,7 @@ latexindent.pl -s textwrap6.tex -l=textwrap11.yaml -m
\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}
+ \cmhlistingsfromfile*{demonstrations/textwrap6-mod11.tex}{\texttt{textwrap6.tex} using \cref{lst:textwrap11-yaml}}{lst:textwrap6-mod11}
\end{widepage}
Notice that:
@@ -1897,70 +1889,70 @@ latexindent.pl -m pmatrix3.tex -l DBS3.yaml
\clearpage
\begin{longtable}{llll}
- \caption{Poly-switch mappings for all code-block types}\label{tab:poly-switch-mapping} \\
+ \caption{Poly-switch mappings for all code-block types}\label{tab:poly-switch-mapping} \\
\toprule
- Code block & Sample & \multicolumn{2}{c}{Poly-switch mapping} \\
+ Code block & Sample & \multicolumn{2}{c}{Poly-switch mapping} \\
\midrule
- environment & \verb!before words!$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & BeginStartsOnOwnLine \\
+ environment & \verb!before words!$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & BeginStartsOnOwnLine \\
& \verb!\begin{myenv}!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & BodyStartsOnOwnLine \\
& \verb!body of myenv!$\EndStartsOnOwnLine$ & $\EndStartsOnOwnLine$ & EndStartsOnOwnLine \\
- & \verb!\end{myenv}!$\EndFinishesWithLineBreak$ & $\EndFinishesWithLineBreak$ & EndFinishesWithLineBreak \\
- & \verb!after words! & & \\
+ & \verb!\end{myenv}!$\EndFinishesWithLineBreak$ & $\EndFinishesWithLineBreak$ & EndFinishesWithLineBreak \\
+ & \verb!after words! & & \\
\cmidrule{2-4}
- ifelsefi & \verb!before words!$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & IfStartsOnOwnLine \\
- & \verb!\if...!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & BodyStartsOnOwnLine \\
- & \verb!body of if/or statement!$\OrStartsOnOwnLine$ & $\OrStartsOnOwnLine$ & OrStartsOnOwnLine %
- \announce{2018-04-27}{new ifElseFi code block poly-switches} \\
- & \verb!\or!$\OrFinishesWithLineBreak$ & $\OrFinishesWithLineBreak$ & OrFinishesWithLineBreak \\
- & \verb!body of if/or statement!$\ElseStartsOnOwnLine$ & $\ElseStartsOnOwnLine$ & ElseStartsOnOwnLine \\
- & \verb!\else!$\ElseFinishesWithLineBreak$ & $\ElseFinishesWithLineBreak$ & ElseFinishesWithLineBreak \\
- & \verb!body of else statement!$\EndStartsOnOwnLine$ & $\EndStartsOnOwnLine$ & FiStartsOnOwnLine \\
- & \verb!\fi!$\EndFinishesWithLineBreak$ & $\EndFinishesWithLineBreak$ & FiFinishesWithLineBreak \\
- & \verb!after words! & & \\
+ ifelsefi & \verb!before words!$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & IfStartsOnOwnLine \\
+ & \verb!\if...!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & BodyStartsOnOwnLine \\
+ & \verb!body of if/or statement!$\OrStartsOnOwnLine$ & $\OrStartsOnOwnLine$ & OrStartsOnOwnLine %
+ \announce{2018-04-27}{new ifElseFi code block poly-switches} \\
+ & \verb!\or!$\OrFinishesWithLineBreak$ & $\OrFinishesWithLineBreak$ & OrFinishesWithLineBreak \\
+ & \verb!body of if/or statement!$\ElseStartsOnOwnLine$ & $\ElseStartsOnOwnLine$ & ElseStartsOnOwnLine \\
+ & \verb!\else!$\ElseFinishesWithLineBreak$ & $\ElseFinishesWithLineBreak$ & ElseFinishesWithLineBreak \\
+ & \verb!body of else statement!$\EndStartsOnOwnLine$ & $\EndStartsOnOwnLine$ & FiStartsOnOwnLine \\
+ & \verb!\fi!$\EndFinishesWithLineBreak$ & $\EndFinishesWithLineBreak$ & FiFinishesWithLineBreak \\
+ & \verb!after words! & & \\
\cmidrule{2-4}
- optionalArguments & \verb!...!$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & LSqBStartsOnOwnLine\footnote{LSqB stands for Left Square Bracket} \\
- & \verb![!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & OptArgBodyStartsOnOwnLine \\
- \announce{2019-07-13}{new comma-related poly-switches} & \verb!value before comma!$\ElseStartsOnOwnLine$, & $\ElseStartsOnOwnLine$ & CommaStartsOnOwnLine \\
- & $\ElseFinishesWithLineBreak$ & $\ElseFinishesWithLineBreak$ & CommaFinishesWithLineBreak \\
- & \verb!end of body of opt arg!$\EndStartsOnOwnLine$ & $\EndStartsOnOwnLine$ & RSqBStartsOnOwnLine \\
- & \verb!]!$\EndFinishesWithLineBreak$ & $\EndFinishesWithLineBreak$ & RSqBFinishesWithLineBreak \\
- & \verb!...! & & \\
+ optionalArguments & \verb!...!$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & LSqBStartsOnOwnLine\footnote{LSqB stands for Left Square Bracket} \\
+ & \verb![!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & OptArgBodyStartsOnOwnLine \\
+ \announce{2019-07-13}{new comma-related poly-switches} & \verb!value before comma!$\ElseStartsOnOwnLine$, & $\ElseStartsOnOwnLine$ & CommaStartsOnOwnLine \\
+ & $\ElseFinishesWithLineBreak$ & $\ElseFinishesWithLineBreak$ & CommaFinishesWithLineBreak \\
+ & \verb!end of body of opt arg!$\EndStartsOnOwnLine$ & $\EndStartsOnOwnLine$ & RSqBStartsOnOwnLine \\
+ & \verb!]!$\EndFinishesWithLineBreak$ & $\EndFinishesWithLineBreak$ & RSqBFinishesWithLineBreak \\
+ & \verb!...! & & \\
\cmidrule{2-4}
- mandatoryArguments & \verb!...!$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & LCuBStartsOnOwnLine\footnote{LCuB stands for Left Curly Brace} \\
- & \verb!{!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & MandArgBodyStartsOnOwnLine \\
- \announce{2019-07-13}{new comma-related poly-switches} & \verb!value before comma!$\ElseStartsOnOwnLine$, & $\ElseStartsOnOwnLine$ & CommaStartsOnOwnLine \\
- & $\ElseFinishesWithLineBreak$ & $\ElseFinishesWithLineBreak$ & CommaFinishesWithLineBreak \\
- & \verb!end of body of mand arg!$\EndStartsOnOwnLine$ & $\EndStartsOnOwnLine$ & RCuBStartsOnOwnLine \\
- & \verb!}!$\EndFinishesWithLineBreak$ & $\EndFinishesWithLineBreak$ & RCuBFinishesWithLineBreak \\
- & \verb!...! & & \\
+ mandatoryArguments & \verb!...!$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & LCuBStartsOnOwnLine\footnote{LCuB stands for Left Curly Brace} \\
+ & \verb!{!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & MandArgBodyStartsOnOwnLine \\
+ \announce{2019-07-13}{new comma-related poly-switches} & \verb!value before comma!$\ElseStartsOnOwnLine$, & $\ElseStartsOnOwnLine$ & CommaStartsOnOwnLine \\
+ & $\ElseFinishesWithLineBreak$ & $\ElseFinishesWithLineBreak$ & CommaFinishesWithLineBreak \\
+ & \verb!end of body of mand arg!$\EndStartsOnOwnLine$ & $\EndStartsOnOwnLine$ & RCuBStartsOnOwnLine \\
+ & \verb!}!$\EndFinishesWithLineBreak$ & $\EndFinishesWithLineBreak$ & RCuBFinishesWithLineBreak \\
+ & \verb!...! & & \\
\cmidrule{2-4}
- commands & \verb!before words!$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & CommandStartsOnOwnLine \\
- & \verb!\mycommand!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & CommandNameFinishesWithLineBreak \\
- & $\langle$\itshape{arguments}$\rangle$ & & \\
+ commands & \verb!before words!$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & CommandStartsOnOwnLine \\
+ & \verb!\mycommand!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & CommandNameFinishesWithLineBreak \\
+ & $\langle$\itshape{arguments}$\rangle$ & & \\
\cmidrule{2-4}
- namedGroupingBraces Brackets & before words$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & NameStartsOnOwnLine \\
- & myname$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & NameFinishesWithLineBreak \\
- & $\langle$\itshape{braces/brackets}$\rangle$ & & \\
+ namedGroupingBraces Brackets & before words$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & NameStartsOnOwnLine \\
+ & myname$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & NameFinishesWithLineBreak \\
+ & $\langle$\itshape{braces/brackets}$\rangle$ & & \\
\cmidrule{2-4}
- keyEqualsValuesBraces\newline Brackets & before words$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & KeyStartsOnOwnLine \\
- & key$\EqualsStartsOnOwnLine$=$\BodyStartsOnOwnLine$ & $\EqualsStartsOnOwnLine$ & EqualsStartsOnOwnLine \\
- & $\langle$\itshape{braces/brackets}$\rangle$ & $\BodyStartsOnOwnLine$ & EqualsFinishesWithLineBreak \\
+ keyEqualsValuesBraces\newline Brackets & before words$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & KeyStartsOnOwnLine \\
+ & key$\EqualsStartsOnOwnLine$=$\BodyStartsOnOwnLine$ & $\EqualsStartsOnOwnLine$ & EqualsStartsOnOwnLine \\
+ & $\langle$\itshape{braces/brackets}$\rangle$ & $\BodyStartsOnOwnLine$ & EqualsFinishesWithLineBreak \\
\cmidrule{2-4}
- items & before words$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & ItemStartsOnOwnLine \\
- & \verb!\item!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & ItemFinishesWithLineBreak \\
- & \verb!...! & & \\
+ items & before words$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & ItemStartsOnOwnLine \\
+ & \verb!\item!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & ItemFinishesWithLineBreak \\
+ & \verb!...! & & \\
\cmidrule{2-4}
- specialBeginEnd & before words$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & SpecialBeginStartsOnOwnLine \\
- & \verb!\[!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & SpecialBodyStartsOnOwnLine \\
- & \verb!body of special/middle!$\ElseStartsOnOwnLine$ & $\ElseStartsOnOwnLine$ & SpecialMiddleStartsOnOwnLine %
- \announce{2018-04-27}{new special code block poly-switches} \\
- & \verb!\middle!$\ElseFinishesWithLineBreak$ & $\ElseFinishesWithLineBreak$ & SpecialMiddleFinishesWithLineBreak \\
- & body of special/middle $\EndStartsOnOwnLine$ & $\EndStartsOnOwnLine$ & SpecialEndStartsOnOwnLine \\
- & \verb!\]!$\EndFinishesWithLineBreak$ & $\EndFinishesWithLineBreak$ & SpecialEndFinishesWithLineBreak \\
- & after words & & \\
+ specialBeginEnd & before words$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & SpecialBeginStartsOnOwnLine \\
+ & \verb!\[!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & SpecialBodyStartsOnOwnLine \\
+ & \verb!body of special/middle!$\ElseStartsOnOwnLine$ & $\ElseStartsOnOwnLine$ & SpecialMiddleStartsOnOwnLine %
+ \announce{2018-04-27}{new special code block poly-switches} \\
+ & \verb!\middle!$\ElseFinishesWithLineBreak$ & $\ElseFinishesWithLineBreak$ & SpecialMiddleFinishesWithLineBreak \\
+ & body of special/middle $\EndStartsOnOwnLine$ & $\EndStartsOnOwnLine$ & SpecialEndStartsOnOwnLine \\
+ & \verb!\]!$\EndFinishesWithLineBreak$ & $\EndFinishesWithLineBreak$ & SpecialEndFinishesWithLineBreak \\
+ & after words & & \\
\cmidrule{2-4}
- verbatim & before words$\BeginStartsOnOwnLine$\verb!\begin{verbatim}! & $\BeginStartsOnOwnLine$ & VerbatimBeginStartsOnOwnLine \\
+ verbatim & before words$\BeginStartsOnOwnLine$\verb!\begin{verbatim}! & $\BeginStartsOnOwnLine$ & VerbatimBeginStartsOnOwnLine \\
\announce{2019-05-05}{verbatim poly-switches} & body of verbatim \verb!\end{verbatim}!$\EndFinishesWithLineBreak$ & $\EndFinishesWithLineBreak$ & VerbatimEndFinishesWithLineBreak \\
- & after words & & \\
+ & after words & & \\
\bottomrule
\end{longtable}