summaryrefslogtreecommitdiff
path: root/support/latexindent/documentation/subsec-text-wrap.tex
diff options
context:
space:
mode:
Diffstat (limited to 'support/latexindent/documentation/subsec-text-wrap.tex')
-rw-r--r--support/latexindent/documentation/subsec-text-wrap.tex645
1 files changed, 341 insertions, 304 deletions
diff --git a/support/latexindent/documentation/subsec-text-wrap.tex b/support/latexindent/documentation/subsec-text-wrap.tex
index 64eea3f1ab..2b4c96539e 100644
--- a/support/latexindent/documentation/subsec-text-wrap.tex
+++ b/support/latexindent/documentation/subsec-text-wrap.tex
@@ -1,131 +1,372 @@
% arara: pdflatex: { files: [latexindent]}
\subsection{Text Wrapping}\label{subsec:textwrapping}
- There are \emph{many} different configuration options for the text wrapping routine of
- \texttt{latexindent.pl}, perhaps \emph{too} many. The following sections are
- comprehensive, but quite long; in an attempt to to be brief, you might begin with the
- settings given in \cref{subsec:textwrapping-quick-start}.
+ \announce*{2022-03-13}{text wrap overhaul}\emph{The text wrapping routine has been over-hauled as
+ of V3.16; I hope that the interface is simpler, and most importantly, the results are
+ better}.
+
+ The complete settings for this feature are given in \cref{lst:textWrapOptionsAll}.
+
+ \cmhlistingsfromfile*[style=textWrapOptionsAll]{../defaultSettings.yaml}[MLB-TCB,width=.95\linewidth,before=\centering]{\texttt{textWrapOptions}}{lst:textWrapOptionsAll}
+
+\subsubsection{Text wrap: overview}
+ An overview of how the text wrapping feature works:
+ \begin{enumerate}
+ \item the default value of \texttt{columns} is 0, which means that text wrapping will
+ \emph{not} happen by default;
+ \item it happens \emph{after} verbatim blocks have been found;
+ \item it happens \emph{after} the oneSentencePerLine routine (see
+ \cref{sec:onesentenceperline});
+ \item it happens \emph{before} all of the other code blocks are found and does \emph{not}
+ operate on a per-code-block basis;
+ \item code blocks to be text wrapped will:
+ \begin{enumerate}
+ \item \emph{follow} the fields specified in \texttt{blocksFollow}
+ \item \emph{begin} with the fields specified in \texttt{blocksBeginWith}
+ \item \emph{end} before the fields specified in \texttt{blocksEndBefore}
+ \end{enumerate}
+ \item setting \texttt{columns} to a value $>0$ will text wrap blocks by first removing line
+ breaks, and then wrapping according to the specified value of \texttt{columns};
+ \item setting \texttt{columns} to $-1$ will \emph{only} remove line breaks within the text wrap
+ block.
+ \end{enumerate}
+
+ We demonstrate this feature using a series of examples.
+
+\subsubsection{Text wrap: simple examples}\label{subsec:textwrapping-quick-start}
+
+ \begin{example}
+ Let's use the sample text given in \cref{lst:textwrap1}. \index{text wrap!quick start}
+
+ \cmhlistingsfromfile*{demonstrations/textwrap1.tex}{\texttt{textwrap1.tex}}{lst:textwrap1}
+
+ We will change the value of \texttt{columns} in \cref{lst:textwrap1-yaml} and then run
+ the command
+ \begin{commandshell}
+latexindent.pl -m -l textwrap1.yaml textwrap1.tex
+\end{commandshell}
+ then we receive the output given in \cref{lst:textwrap1-mod1}.
-\subsubsection{Text wrap quick start}\label{subsec:textwrapping-quick-start}
+ \begin{cmhtcbraster}[raster column skip=.1\linewidth]
+ \cmhlistingsfromfile*{demonstrations/textwrap1-mod1.tex}{\texttt{textwrap1-mod1.tex}}{lst:textwrap1-mod1}
+ \cmhlistingsfromfile*{demonstrations/textwrap1.yaml}[MLB-TCB]{\texttt{textwrap1.yaml}}{lst:textwrap1-yaml}
+ \end{cmhtcbraster}
+ \end{example}
- Of all the available text wrapping options, I consider \cref{lst:textwrap-qs-yaml} to be
- among the most helpful starting points.
+ \begin{example}
+ If we set \texttt{columns} to $-1$ then \texttt{latexindent.pl} remove line breaks within
+ the text wrap block, and will \emph{not} perform text wrapping. We can use this to undo
+ text wrapping. \index{text wrap!setting columns to -1}
- \cmhlistingsfromfile{demonstrations/textwrap-qs.yaml}[MLB-TCB,width=1\linewidth]{\texttt{textwrap-qs.yaml}}{lst:textwrap-qs-yaml}
+ Starting from the file in \cref{lst:textwrap1-mod1} and using the settings in
+ \cref{lst:textwrap1A-yaml}
- \index{text wrap!quick start}
+ \cmhlistingsfromfile*{demonstrations/textwrap1A.yaml}[MLB-TCB]{\texttt{textwrap1A.yaml}}{lst:textwrap1A-yaml}
- You can read about \texttt{perCodeBlockBasis} in \cref{subsec:text-wrap-per-code-block}
- and \texttt{removeParagraphLineBreaks} in \cref{subsec:removeparagraphlinebreaks}.
+ and running
+ \begin{commandshell}
+latexindent.pl -m -l textwrap1A.yaml textwrap1-mod1.tex
+\end{commandshell}
+ gives the output in \cref{lst:textwrap1-mod1A}.
- If the settings in \cref{lst:textwrap-qs-yaml} do not give your desired output, take a
- look at the demonstration in \cref{subsubsec:text-wrap-remove-para-bfccb}, in particular
- \cref{lst:textwrap-bfccb-mod14}.
+ \cmhlistingsfromfile*{demonstrations/textwrap1-mod1A.tex}{\texttt{textwrap1-mod1A.tex}}{lst:textwrap1-mod1A}
+ \end{example}
-\subsubsection{textWrapOptions: modifying line breaks by text wrapping}
+ \begin{example}
+ By default, the text wrapping routine will convert multiple spaces into single spaces.
+ You can change this behaviour by flicking the switch \texttt{multipleSpacesToSingle}
+ which we have done in \cref{lst:textwrap1B-yaml}
- When the \texttt{-m} switch is active \texttt{latexindent.pl} has the ability to wrap
- text using the options%
- \announce{2017-05-27}{textWrapOptions} specified in the \texttt{textWrapOptions} field,
- see \cref{lst:textWrapOptions}.
+ Using the settings in \cref{lst:textwrap1B-yaml} and running
+ \begin{commandshell}
+latexindent.pl -m -l textwrap1B.yaml textwrap1-mod1.tex
+\end{commandshell}
+ gives the output in \cref{lst:textwrap1-mod1B}.
+ \begin{cmhtcbraster}[raster column skip=.1\linewidth]
+ \cmhlistingsfromfile*{demonstrations/textwrap1B.yaml}[MLB-TCB]{\texttt{textwrap1B.yaml}}{lst:textwrap1B-yaml}
+ \cmhlistingsfromfile*[showspaces=true]{demonstrations/textwrap1-mod1B.tex}{\texttt{textwrap1-mod1B.tex}}{lst:textwrap1-mod1B}
+ \end{cmhtcbraster}
+ We note that in \cref{lst:textwrap1-mod1B} the multiple spaces have \emph{not} been condensed into single spaces.
+ \end{example}
+
+\subsubsection{Text wrap: \texttt{blocksFollow} examples}
+ We examine the \texttt{blocksFollow} field of \cref{lst:textWrapOptionsAll}. \index{text
+ wrap!blocksFollow}
+
+ \begin{example}[label={example:tw:headings}]
+ Let's use the sample text given in \cref{lst:tw-headings1}. \index{text
+ wrap!blocksFollow!headings}
+
+ \cmhlistingsfromfile*{demonstrations/tw-headings1.tex}{\texttt{tw-headings1.tex}}{lst:tw-headings1}
+
+ We note that \cref{lst:tw-headings1} contains the heading commands \texttt{section} and
+ \texttt{subsection}. Upon running the command
+ \begin{commandshell}
+latexindent.pl -m -l textwrap1.yaml tw-headings1.tex
+\end{commandshell}
+ then we receive the output given in \cref{lst:tw-headings1-mod1}.
+
+ \cmhlistingsfromfile*{demonstrations/tw-headings1-mod1.tex}{\texttt{tw-headings1-mod1.tex}}{lst:tw-headings1-mod1}
+
+ We reference \vref{lst:textWrapOptionsAll} and also \vref{lst:indentAfterHeadings}:
+ \begin{itemize}
+ \item in \cref{lst:textWrapOptionsAll} the \texttt{headings} field is set to \texttt{1}, which
+ instructs \texttt{latexindent.pl} to read the fields from \vref{lst:indentAfterHeadings},
+ \emph{regardless of the value of indentAfterThisHeading or level};
+ \item the default is to assume that the heading command can, optionally, be followed by a
+ \texttt{label} command.
+ \end{itemize}
+ If you find scenarios in which the default value of \texttt{headings} does not work, then you
+ can explore the \texttt{other} field.
+
+ We can turn off \texttt{headings} as in \cref{lst:bf-no-headings-yaml} and then run
+ \begin{commandshell}
+latexindent.pl -m -l textwrap1.yaml,bf-no-headings.yaml tw-headings1.tex
+\end{commandshell}
+ gives the output in \cref{lst:tw-headings1-mod2}, in which text wrapping has been
+ instructed \emph{not to happen} following headings.
+ \begin{cmhtcbraster}[raster column skip=.1\linewidth,
+ raster left skip=-3.5cm,
+ raster right skip=-2cm,
+ ]
+ \cmhlistingsfromfile*{demonstrations/bf-no-headings.yaml}[MLB-TCB]{\texttt{bf-no-headings.yaml}}{lst:bf-no-headings-yaml}
+ \cmhlistingsfromfile*{demonstrations/tw-headings1-mod2.tex}{\texttt{tw-headings1-mod2.tex}}{lst:tw-headings1-mod2}
+ \end{cmhtcbraster}
+ \end{example}
+
+ \begin{example}[label={example:tw:comments}]
+ Let's use the sample text given in \cref{lst:tw-comments1}. \index{text wrap!blocksFollow!comments}
+
+ \cmhlistingsfromfile*{demonstrations/tw-comments1.tex}{\texttt{tw-comments1.tex}}{lst:tw-comments1}
+
+ We note that \cref{lst:tw-comments1} contains trailing comments. Upon running the command
+ \begin{commandshell}
+latexindent.pl -m -l textwrap1.yaml tw-comments1.tex
+\end{commandshell}
+ then we receive the output given in \cref{lst:tw-comments1-mod1}.
- \index{modifying linebreaks! by text wrapping, globally}
+ \cmhlistingsfromfile*{demonstrations/tw-comments1-mod1.tex}{\texttt{tw-comments1-mod1.tex}}{lst:tw-comments1-mod1}
- \cmhlistingsfromfile[style=textWrapOptions]{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{textWrapOptions}}{lst:textWrapOptions}
+ With reference to \vref{lst:textWrapOptionsAll} the \texttt{commentOnPreviousLine} field
+ is set to \texttt{1}, which instructs \texttt{latexindent.pl} to find text wrap blocks
+ after a comment on its own line.
- The value of \texttt{columns} specifies the column at which the text should be wrapped.
+ We can turn off \texttt{comments} as in \cref{lst:bf-no-comments-yaml} and then run
+ \begin{commandshell}
+latexindent.pl -m -l textwrap1.yaml,bf-no-comments.yaml tw-comments1.tex
+\end{commandshell}
+ gives the output in \cref{lst:tw-comments1-mod2}, in which text wrapping has been
+ instructed \emph{not to happen} following comments on their own line.
+ \begin{cmhtcbraster}[raster column skip=.1\linewidth,
+ raster left skip=-3.5cm,
+ raster right skip=-2cm,
+ ]
+ \cmhlistingsfromfile*{demonstrations/bf-no-comments.yaml}[MLB-TCB]{\texttt{bf-no-comments.yaml}}{lst:bf-no-comments-yaml}
+ \cmhlistingsfromfile*{demonstrations/tw-comments1-mod2.tex}{\texttt{tw-comments1-mod2.tex}}{lst:tw-comments1-mod2}
+ \end{cmhtcbraster}
+ \end{example}
+
+ Referencing \vref{lst:textWrapOptionsAll} the \texttt{blocksFollow} fields \texttt{par},
+ \texttt{blankline}, \texttt{verbatim} and \texttt{filecontents} fields operate in
+ analogous ways to those demonstrated in the above.
+
+ The \texttt{other} field of the \texttt{blocksFollow} can either be \texttt{0} (turned
+ off) or set as a regular expression. The default value is set to
+ \lstinline!\\\]|\\item(?:\h|\[)! which can be translated to \emph{backslash followed by a
+ square bracket} or \emph{backslash item followed by horizontal space or a square
+ bracket}, or in other words, \emph{end of display math} or an item command.
+
+ \begin{example}
+ Let's use the sample text given in \cref{lst:tw-disp-math1}. \index{text
+ wrap!blocksFollow!other} \index{regular expressions!text wrap!blocksFollow}
+
+ \cmhlistingsfromfile*{demonstrations/tw-disp-math1.tex}{\texttt{tw-disp-math1.tex}}{lst:tw-disp-math1}
+
+ We note that \cref{lst:tw-disp-math1} contains display math. Upon running the command
+ \begin{commandshell}
+latexindent.pl -m -l textwrap1.yaml tw-disp-math1.tex
+\end{commandshell}
+ then we receive the output given in \cref{lst:tw-disp-math1-mod1}.
- By default, the value of \texttt{columns} is \texttt{0}, so \texttt{latexindent.pl} will
- \emph{not} wrap text; if you change it to a value of \texttt{2} or more, then text will
- be wrapped after the character in the specified column.
+ \cmhlistingsfromfile*{demonstrations/tw-disp-math1-mod1.tex}{\texttt{tw-disp-math1-mod1.tex}}{lst:tw-disp-math1-mod1}
- By default, the text wrapping routine will operate \emph{before} the code blocks have
- been searched for; text wrapping on a \emph{per-code-block} basis is discussed in
- \cref{subsec:text-wrap-per-code-block}.
+ With reference to \vref{lst:textWrapOptionsAll} the \texttt{other} field is set to
+ \lstinline!\\\]!, which instructs \texttt{latexindent.pl} to find text wrap blocks after
+ the end of display math.
- We consider the file give in \cref{lst:textwrap1} for demonstration.
+ We can turn off this switch as in \cref{lst:bf-no-disp-math-yaml} and then run
+ \begin{widepage}
+ \begin{commandshell}
+latexindent.pl -m -l textwrap1.yaml,bf-no-disp-math.yaml tw-disp-math1.tex
+\end{commandshell}
+ \end{widepage}
+ gives the output in \cref{lst:tw-disp-math1-mod2}, in which text wrapping has been
+ instructed \emph{not to happen} following display math.
+ \begin{cmhtcbraster}[raster column skip=.1\linewidth]
+ \cmhlistingsfromfile*{demonstrations/bf-no-disp-math.yaml}[MLB-TCB]{\texttt{bf-no-disp-math.yaml}}{lst:bf-no-disp-math-yaml}
+ \cmhlistingsfromfile*{demonstrations/tw-disp-math1-mod2.tex}{\texttt{tw-disp-math1-mod2.tex}}{lst:tw-disp-math1-mod2}
+ \end{cmhtcbraster}
+
+ Naturally, you should feel encouraged to customise this as you see fit.
+ \end{example}
+
+ The \texttt{blocksFollow} field \emph{deliberately} does not default to allowing text
+ wrapping to occur after \texttt{begin environment} statements. You are encouraged to
+ customize the \texttt{other} field to accomodate the environments that you would like to
+ text wrap individually, as in the next example.
+
+ \begin{example}
+ Let's use the sample text given in \cref{lst:tw-bf-myenv1}. \index{text
+ wrap!blocksFollow!other} \index{regular expressions!text wrap!blocksFollow}
+
+ \cmhlistingsfromfile*{demonstrations/tw-bf-myenv1.tex}{\texttt{tw-bf-myenv1.tex}}{lst:tw-bf-myenv1}
+
+ We note that \cref{lst:tw-bf-myenv1} contains \texttt{myenv} environment. Upon running
+ the command
+ \begin{commandshell}
+latexindent.pl -m -l textwrap1.yaml tw-bf-myenv1.tex
+\end{commandshell}
+ then we receive the output given in \cref{lst:tw-bf-myenv1-mod1}.
- \begin{widepage}
- \cmhlistingsfromfile{demonstrations/textwrap1.tex}{\texttt{textwrap1.tex}}{lst:textwrap1}
- \end{widepage}
+ \cmhlistingsfromfile*{demonstrations/tw-bf-myenv1-mod1.tex}{\texttt{tw-bf-myenv1-mod1.tex}}{lst:tw-bf-myenv1-mod1}
- Using the file \texttt{textwrap1.yaml} in \cref{lst:textwrap1-yaml}, and running the
- command
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \index{switches!-o demonstration}
- \begin{commandshell}
-latexindent.pl -m textwrap1.tex -o textwrap1-mod1.tex -l textwrap1.yaml
+ We note that we have \emph{not} received much text wrapping. We can turn do better by
+ employing \cref{lst:tw-bf-myenv-yaml} and then run
+ \begin{commandshell}
+latexindent.pl -m -l textwrap1.yaml,tw-bf-myenv.yaml tw-bf-myenv1.tex
+\end{commandshell}
+ which gives the output in \cref{lst:tw-bf-myenv1-mod2}, in which text wrapping has been
+ implemented across the file.
+ \begin{cmhtcbraster}[raster column skip=.1\linewidth,
+ raster left skip=-3.5cm,
+ raster right skip=-2cm,
+ ]
+ \cmhlistingsfromfile*{demonstrations/tw-bf-myenv.yaml}[MLB-TCB]{\texttt{tw-bf-myenv.yaml}}{lst:tw-bf-myenv-yaml}
+ \cmhlistingsfromfile*{demonstrations/tw-bf-myenv1-mod2.tex}{\texttt{tw-bf-myenv1-mod2.tex}}{lst:tw-bf-myenv1-mod2}
+ \end{cmhtcbraster}
+
+ \end{example}
+
+\subsubsection{Text wrap: \texttt{blocksBeginWith} examples}
+ We examine the \texttt{blocksBeginWith} field of \cref{lst:textWrapOptionsAll} with a
+ series of examples. \index{text wrap!blocksBeginWith}
+
+ \begin{example}
+ By default, text wrap blocks can begin with the characters \texttt{a-z} and \texttt{A-Z}.
+
+ If we start with the file given in \cref{lst:tw-0-9}
+ \cmhlistingsfromfile*{demonstrations/tw-0-9.tex}{\texttt{tw-0-9.tex}}{lst:tw-0-9}
+ and run the command
+ \begin{commandshell}
+latexindent.pl -m -l textwrap1.yaml tw-0-9.tex
+\end{commandshell}
+ then we receive the output given in \cref{lst:tw-0-9-mod1} in which text wrapping has
+ \emph{not} occured.
+ \cmhlistingsfromfile*{demonstrations/tw-0-9-mod1.tex}{\texttt{tw-0-9-mod1.tex}}{lst:tw-0-9-mod1}
+
+ We can allow paragraphs to begin with \texttt{0-9} characters by using the settings in
+ \cref{lst:bb-0-9-yaml} and running
+ \begin{commandshell}
+latexindent.pl -m -l textwrap1.yaml,bb-0-9-yaml tw-0-9.tex
+\end{commandshell}
+ gives the output in \cref{lst:tw-0-9-mod2}, in which text wrapping \emph{has} happened.
+ \begin{cmhtcbraster}[raster column skip=.1\linewidth,]
+ \cmhlistingsfromfile*{demonstrations/bb-0-9.yaml}[MLB-TCB]{\texttt{bb-0-9.yaml.yaml}}{lst:bb-0-9-yaml}
+ \cmhlistingsfromfile*{demonstrations/tw-0-9-mod2.tex}{\texttt{tw-0-9-mod2.tex}}{lst:tw-0-9-mod2}
+ \end{cmhtcbraster}
+ \end{example}
+
+ \begin{example}
+ Let's now use the file given in \cref{lst:tw-bb-announce1}
+ \cmhlistingsfromfile*{demonstrations/tw-bb-announce1.tex}{\texttt{tw-bb-announce1.tex}}{lst:tw-bb-announce1}
+ and run the command
+ \begin{commandshell}
+latexindent.pl -m -l textwrap1.yaml tw-bb-announce1.tex
\end{commandshell}
- we obtain the output in \cref{lst:textwrap1-mod1}.
+ then we receive the output given in \cref{lst:tw-bb-announce1-mod1} in which text
+ wrapping has \emph{not} occured.
- \begin{cmhtcbraster}[raster column skip=.1\linewidth]
- \cmhlistingsfromfile{demonstrations/textwrap1-mod1.tex}{\texttt{textwrap1-mod1.tex}}{lst:textwrap1-mod1}
- \cmhlistingsfromfile{demonstrations/textwrap1.yaml}[MLB-TCB]{\texttt{textwrap1.yaml}}{lst:textwrap1-yaml}
- \end{cmhtcbraster}
+ \cmhlistingsfromfile*{demonstrations/tw-bb-announce1-mod1.tex}{\texttt{tw-bb-announce1-mod1.tex}}{lst:tw-bb-announce1-mod1}
- The text wrapping routine is performed \emph{after} verbatim environments
- \index{verbatim!in relation to textWrapOptions} have been stored, so verbatim
- environments and verbatim commands are exempt from the routine. For example, using the
- file in \cref{lst:textwrap2},
- \begin{widepage}
- \cmhlistingsfromfile{demonstrations/textwrap2.tex}{\texttt{textwrap2.tex}}{lst:textwrap2}
- \end{widepage}
- and running the following command and continuing to use \texttt{textwrap1.yaml} from
- \cref{lst:textwrap1-yaml},
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \index{switches!-o demonstration}
- \begin{commandshell}
-latexindent.pl -m textwrap2.tex -o textwrap2-mod1.tex -l textwrap1.yaml
+ We can allow \lstinline!\announce! to be at the beginning of paragraphs by using the
+ settings in \cref{lst:tw-bb-announce-yaml} and running
+ \begin{widepage}
+ \begin{commandshell}
+latexindent.pl -m -l textwrap1.yaml,tw-bb-announce.yaml tw-bb-announce1.tex
\end{commandshell}
- then the output is as in \cref{lst:textwrap2-mod1}.
- \begin{widepage}
- \cmhlistingsfromfile{demonstrations/textwrap2-mod1.tex}{\texttt{textwrap2-mod1.tex}}{lst:textwrap2-mod1}
- \end{widepage}
- Furthermore, the text wrapping routine is performed after the trailing comments have been
- stored, and they are also exempt from text wrapping. For example, using the file in
- \cref{lst:textwrap3}
- \begin{widepage}
- \cmhlistingsfromfile{demonstrations/textwrap3.tex}{\texttt{textwrap3.tex}}{lst:textwrap3}
- \end{widepage}
- and running the following command and continuing to use \texttt{textwrap1.yaml} from
- \cref{lst:textwrap1-yaml},
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \index{switches!-o demonstration}
- \begin{commandshell}
-latexindent.pl -m textwrap3.tex -o textwrap3-mod1.tex -l textwrap1.yaml
+ \end{widepage}
+ gives the output in \cref{lst:tw-bb-announce1-mod2}, in which text wrapping \emph{has}
+ happened.
+ \begin{cmhtcbraster}[raster column skip=.1\linewidth,]
+ \cmhlistingsfromfile*{demonstrations/tw-bb-announce.yaml}[MLB-TCB]{\texttt{tw-bb-announce.yaml}}{lst:tw-bb-announce-yaml}
+ \cmhlistingsfromfile*{demonstrations/tw-bb-announce1-mod2.tex}{\texttt{tw-bb-announce1-mod2.tex}}{lst:tw-bb-announce1-mod2}
+ \end{cmhtcbraster}
+
+ \end{example}
+
+\subsubsection{Text wrap: \texttt{blocksEndBefore} examples}
+ We examine the \texttt{blocksEndBefore} field of \cref{lst:textWrapOptionsAll} with a
+ series of examples. \index{text wrap!blocksEndBefore}
+
+ \begin{example}
+ Let's use the sample text given in \cref{lst:tw-be-equation}. \index{text
+ wrap!blocksFollow!other} \index{regular expressions!text wrap!blocksFollow}
+
+ \cmhlistingsfromfile*{demonstrations/tw-be-equation.tex}{\texttt{tw-be-equation.tex}}{lst:tw-be-equation}
+
+ We note that \cref{lst:tw-be-equation} contains an environment. Upon running the command
+ \begin{commandshell}
+latexindent.pl -m -l textwrap1A.yaml tw-be-equation.tex
+\end{commandshell}
+ then we receive the output given in \cref{lst:tw-be-equation-mod1}.
+
+ \cmhlistingsfromfile*{demonstrations/tw-be-equation-mod1.tex}{\texttt{tw-be-equation-mod1.tex}}{lst:tw-be-equation-mod1}
+
+ With reference to \vref{lst:textWrapOptionsAll} the \texttt{other} field is set to
+ \lstinline!\\begin\{|\\\[|\\end\{!, which instructs \texttt{latexindent.pl} to
+ \emph{stop} text wrap blocks before \texttt{begin} statements, display math, and
+ \texttt{end} statements.
+
+ We can turn off this switch as in \cref{lst:tw-be-equation-yaml} and then run
+ \begin{widepage}
+ \begin{commandshell}
+latexindent.pl -m -l textwrap1A.yaml,tw-be-equation.yaml tw-be-equation.tex
\end{commandshell}
- then the output is as in \cref{lst:textwrap3-mod1}.
-
- \cmhlistingsfromfile{demonstrations/textwrap3-mod1.tex}{\texttt{textwrap3-mod1.tex}}{lst:textwrap3-mod1}
-
- The%
- \announce{2021-07-23}*{huge:overflow is now default}
- default value of \texttt{huge} is \texttt{overflow}, which means that words will
- \emph{not} be broken by the text wrapping routine, implemented by the \texttt{Text::Wrap}
- \cite{textwrap}. There are options to change the \texttt{huge} option for the
- \texttt{Text::Wrap} module to either \texttt{wrap} or \texttt{die}. Before modifying the
- value of \texttt{huge}, please bear in mind the following warning:
- \index{warning!changing huge (textwrap)}
+ \end{widepage}
+ gives the output in \cref{lst:tw-be-equation-mod2}, in which text wrapping has been
+ instructed \emph{not} to stop at these statements.
+
+ \cmhlistingsfromfile*{demonstrations/tw-be-equation.yaml}[MLB-TCB]{\texttt{tw-be-equation.yaml}}{lst:tw-be-equation-yaml}
+
+ \begin{widepage}
+ \cmhlistingsfromfile*{demonstrations/tw-be-equation-mod2.tex}{\texttt{tw-be-equation-mod2.tex}}{lst:tw-be-equation-mod2}
+ \end{widepage}
+
+ Naturally, you should feel encouraged to customise this as you see fit.
+ \end{example}
+
+\subsubsection{Text wrap: huge, tabstop and separator}
+ The \announce{2021-07-23}*{huge:overflow is now default} default value of \texttt{huge}
+ is \texttt{overflow}, which means that words will \emph{not} be broken by the text
+ wrapping routine, implemented by the \texttt{Text::Wrap} \cite{textwrap}. There are
+ options to change the \texttt{huge} option for the \texttt{Text::Wrap} module to either
+ \texttt{wrap} or \texttt{die}. Before modifying the value of \texttt{huge}, please bear
+ in mind the following warning: \index{warning!changing huge (textwrap)}%
\begin{warning}
\raggedright
Changing the value of \texttt{huge} to anything other than \texttt{overflow} will slow
down \texttt{latexindent.pl} significantly when the \texttt{-m} switch is active.
Furthermore, changing \texttt{huge} means that you may have some words \emph{or
- commands}(!) split across lines in your .tex file, which may affect your output. I do not
+ commands}(!) split across lines in your .tex file, which may affect your output. I do not
recommend changing this field.
\end{warning}
For example, using the settings in \cref{lst:textwrap2A-yaml,lst:textwrap2B-yaml} and
- running the commands
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
+ running the commands \index{switches!-l demonstration} \index{switches!-m demonstration}
\index{switches!-o demonstration}
\begin{commandshell}
-latexindent.pl -m textwrap4.tex -o=+-mod2A -l textwrap2A.yaml
-latexindent.pl -m textwrap4.tex -o=+-mod2B -l textwrap2B.yaml
+ latexindent.pl -m textwrap4.tex -o=+-mod2A -l textwrap2A.yaml
+ latexindent.pl -m textwrap4.tex -o=+-mod2B -l textwrap2B.yaml
\end{commandshell}
gives the respective output in \cref{lst:textwrap4-mod2A,lst:textwrap4-mod2B}.
@@ -137,16 +378,14 @@ latexindent.pl -m textwrap4.tex -o=+-mod2B -l textwrap2B.yaml
\cmhlistingsfromfile{demonstrations/textwrap2B.yaml}[MLB-TCB]{\texttt{textwrap2B.yaml}}{lst:textwrap2B-yaml}
\end{cmhtcbraster}
- You can also specify the \texttt{tabstop} field%
- \announce{2020-11-06}{tabstop option for text wrap module} as an integer value, which is
- passed to the text wrap module; see \cite{textwrap} for details. Starting with the code
- in \cref{lst:textwrap-ts} with settings in \cref{lst:tabstop}, and running the command
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \index{switches!-o demonstration}
+ You can also specify the \texttt{tabstop} field \announce{2020-11-06}{tabstop option for
+ text wrap module} as an integer value, which is passed to the text wrap module; see
+ \cite{textwrap} for details. Starting with the code in \cref{lst:textwrap-ts} with
+ settings in \cref{lst:tabstop}, and running the command \index{switches!-l demonstration}
+ \index{switches!-m demonstration} \index{switches!-o demonstration}%
\begin{commandshell}
-latexindent.pl -m textwrap-ts.tex -o=+-mod1 -l tabstop.yaml
-\end{commandshell}
+ latexindent.pl -m textwrap-ts.tex -o=+-mod1 -l tabstop.yaml
+ \end{commandshell}
gives the code given in \cref{lst:textwrap-ts-mod1}.
\begin{cmhtcbraster}[raster columns=3,
raster left skip=-3.5cm,
@@ -162,205 +401,3 @@ latexindent.pl -m textwrap-ts.tex -o=+-mod1 -l tabstop.yaml
\cref{lst:textwrap2B-yaml,lst:tabstop}, and they will be passed to the
\texttt{Text::Wrap} module. I have not found a useful reason to do this; see
\cite{textwrap} for more details.
-
-\subsubsection{Text wrapping on a per-code-block basis}\label{subsec:text-wrap-per-code-block} By default, if the value of
- \texttt{columns} is greater than 0 and the \texttt{-m} switch is active,
- then%
- \announce{2018-08-13}*{updates to textWrapOptions}
- the text wrapping routine will operate before the code blocks have been searched for.
- This behaviour is customisable; in particular, you can instead instruct
- \texttt{latexindent.pl} to apply \texttt{textWrap} on a per-code-block basis. Thanks to
- \cite{zoehneto} for their help in testing and shaping this feature.
- \index{modifying linebreaks! by text wrapping, per-code-block}
-
- The full details of \texttt{textWrapOptions} are shown in \cref{lst:textWrapOptionsAll}.
- In particular, note the field \texttt{perCodeBlockBasis: 0}.
- \index{specialBeginEnd!textWrapOptions}
-
- \cmhlistingsfromfile[style=textWrapOptionsAll]{../defaultSettings.yaml}[MLB-TCB,width=.95\linewidth,before=\centering]{\texttt{textWrapOptions}}{lst:textWrapOptionsAll}
-
- The code blocks detailed in \cref{lst:textWrapOptionsAll} are with direct reference to
- those detailed in \vref{tab:code-blocks}.
-
- The only special case is the \texttt{mainDocument} field; this is designed for
- `chapter'-type files that may contain paragraphs that are not within any other
- code-blocks. The same notation is used between this feature and the
- \texttt{removeParagraphLineBreaks} described in \vref{lst:removeParagraphLineBreaks}; in
- fact, the two features can even be combined (this is detailed in
- \vref{subsec:removeparagraphlinebreaks:and:textwrap}).
-
- Note:
- \announce{2021-09-16}*{textWrapOptions: masterDocument now mainDocument}
- \texttt{mainDocument} replaces \texttt{masterDocument} which was used in previous verions
- of \texttt{latexindent.pl}. The field \texttt{masterDocument} is still supported, but it
- is anticipated to be removed in a future version, so I recommend using
- \texttt{mainDocument} instead.
-
- Let's explore these switches with reference to the code given in \cref{lst:textwrap5};
- the text outside of the environment is considered part of the \texttt{mainDocument}.
-
- \begin{widepage}
- \cmhlistingsfromfile{demonstrations/textwrap5.tex}{\texttt{textwrap5.tex}}{lst:textwrap5}
- \end{widepage}
-
- With reference to this code block, the settings given in
- \cref{lst:textwrap3-yaml,lst:textwrap4-yaml,lst:textwrap5-yaml} each give the same
- output.
-
- \begin{cmhtcbraster}[raster columns=3,
- raster left skip=-3.5cm,
- raster right skip=-2cm,
- raster column skip=.03\linewidth]
- \cmhlistingsfromfile{demonstrations/textwrap3.yaml}[MLB-TCB]{\texttt{textwrap3.yaml}}{lst:textwrap3-yaml}
- \cmhlistingsfromfile{demonstrations/textwrap4.yaml}[MLB-TCB]{\texttt{textwrap4.yaml}}{lst:textwrap4-yaml}
- \cmhlistingsfromfile{demonstrations/textwrap5.yaml}[MLB-TCB]{\texttt{textwrap5.yaml}}{lst:textwrap5-yaml}
- \end{cmhtcbraster}
-
- Let's explore the similarities and differences in the equivalent (with respect to
- \cref{lst:textwrap5}) syntax specified in
- \cref{lst:textwrap3-yaml,lst:textwrap4-yaml,lst:textwrap5-yaml}:
- \begin{itemize}
- \item in each of \cref{lst:textwrap3-yaml,lst:textwrap4-yaml,lst:textwrap5-yaml} notice that
- \texttt{columns: 30};
- \item in each of \cref{lst:textwrap3-yaml,lst:textwrap4-yaml,lst:textwrap5-yaml} notice that
- \texttt{perCodeBlockBasis: 1};
- \item in \cref{lst:textwrap3-yaml} we have specified \texttt{all: 1} so that the text wrapping
- will operate upon \emph{all} code blocks;
- \item in \cref{lst:textwrap4-yaml} we have \emph{not} specified \texttt{all}, and instead, have
- specified that text wrapping should be applied to each of \texttt{environments} and
- \texttt{mainDocument};
- \item in \cref{lst:textwrap5-yaml} we have specified text wrapping for \texttt{mainDocument}
- and on a \emph{per-name} basis for \texttt{environments} code blocks.
- \end{itemize}
-
- Upon running the following commands
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \begin{commandshell}
-latexindent.pl -s textwrap5.tex -l=textwrap3.yaml -m
-latexindent.pl -s textwrap5.tex -l=textwrap4.yaml -m
-latexindent.pl -s textwrap5.tex -l=textwrap5.yaml -m
-\end{commandshell}
- we obtain the output shown in \cref{lst:textwrap5-mod3}.
-
- \cmhlistingsfromfile{demonstrations/textwrap5-mod3.tex}{\texttt{textwrap5-mod3.tex}}{lst:textwrap5-mod3}
-
- We can explore the idea of per-name text wrapping given in \cref{lst:textwrap5-yaml} by
- using \cref{lst:textwrap6}.
-
- \begin{widepage}
- \cmhlistingsfromfile{demonstrations/textwrap6.tex}{\texttt{textwrap6.tex}}{lst:textwrap6}
- \end{widepage}
-
- In particular, upon running
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \begin{commandshell}
-latexindent.pl -s textwrap6.tex -l=textwrap5.yaml -m
-\end{commandshell}
- we obtain the output given in \cref{lst:textwrap6-mod5}.
-
- \begin{widepage}
- \cmhlistingsfromfile{demonstrations/textwrap6-mod5.tex}{\texttt{textwrap6.tex} using \cref{lst:textwrap5-yaml}}{lst:textwrap6-mod5}
- \end{widepage}
-
- Notice that, because \texttt{environments} has been specified only for \texttt{myenv} (in
- \cref{lst:textwrap5-yaml}) that the environment named \texttt{another} has \emph{not} had
- text wrapping applied to it.
-
- The {all} field can be specified with exceptions which can either be done on a
- per-code-block or per-name basis; we explore this in relation to \cref{lst:textwrap6} in
- the settings given in \crefrange{lst:textwrap6-yaml}{lst:textwrap8-yaml}.
-
- \begin{adjustwidth}{-3.5cm}{-2.5cm}
- \begin{minipage}{.33\linewidth}
- \cmhlistingsfromfile{demonstrations/textwrap6.yaml}[MLB-TCB]{\texttt{textwrap6.yaml}}{lst:textwrap6-yaml}
- \end{minipage}%
- \begin{minipage}{.33\linewidth}
- \cmhlistingsfromfile{demonstrations/textwrap7.yaml}[MLB-TCB]{\texttt{textwrap7.yaml}}{lst:textwrap7-yaml}
- \end{minipage}%
- \begin{minipage}{.33\linewidth}
- \cmhlistingsfromfile{demonstrations/textwrap8.yaml}[MLB-TCB]{\texttt{textwrap8.yaml}}{lst:textwrap8-yaml}
- \end{minipage}
- \end{adjustwidth}
-
- Upon running the commands
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \begin{commandshell}
-latexindent.pl -s textwrap6.tex -l=textwrap6.yaml -m
-latexindent.pl -s textwrap6.tex -l=textwrap7.yaml -m
-latexindent.pl -s textwrap6.tex -l=textwrap8.yaml -m
-\end{commandshell}
- we receive the respective output given in
- \crefrange{lst:textwrap6-mod6}{lst:textwrap6-mod8}.
- \begin{widepage}
- \cmhlistingsfromfile{demonstrations/textwrap6-mod6.tex}{\texttt{textwrap6.tex} using \cref{lst:textwrap6-yaml}}{lst:textwrap6-mod6}
-
- \cmhlistingsfromfile{demonstrations/textwrap6-mod7.tex}{\texttt{textwrap6.tex} using \cref{lst:textwrap7-yaml}}{lst:textwrap6-mod7}
-
- \cmhlistingsfromfile{demonstrations/textwrap6-mod8.tex}{\texttt{textwrap6.tex} using \cref{lst:textwrap8-yaml}}{lst:textwrap6-mod8}
- \end{widepage}
-
- Notice that:
- \begin{itemize}
- \item in \cref{lst:textwrap6-mod6} the text wrapping routine has not been applied to any
- \texttt{environments} because it has been switched off (per-code-block) in
- \cref{lst:textwrap6-yaml};
- \item in \cref{lst:textwrap6-mod7} the text wrapping routine has not been applied to
- \texttt{myenv} because it has been switched off (per-name) in \cref{lst:textwrap7-yaml};
- \item in \cref{lst:textwrap6-mod8} the text wrapping routine has not been applied to
- \texttt{mainDocument} because of the settings in \cref{lst:textwrap8-yaml}.
- \end{itemize}
-
- The \texttt{columns} field has a variety of different ways that it can be specified;
- we've seen two basic ways already: the default (set to \texttt{0}) and a positive integer
- (see \vref{lst:textwrap6}, for example). We explore further options in
- \crefrange{lst:textwrap9-yaml}{lst:textwrap11-yaml}.
-
- \begin{cmhtcbraster}[raster columns=3,
- raster left skip=-3.5cm,
- raster right skip=-2cm,
- raster column skip=.03\linewidth]
- \cmhlistingsfromfile{demonstrations/textwrap9.yaml}[MLB-TCB]{\texttt{textwrap9.yaml}}{lst:textwrap9-yaml}
- \cmhlistingsfromfile{demonstrations/textwrap10.yaml}[MLB-TCB]{\texttt{textwrap10.yaml}}{lst:textwrap10-yaml}
- \cmhlistingsfromfile{demonstrations/textwrap11.yaml}[MLB-TCB]{\texttt{textwrap11.yaml}}{lst:textwrap11-yaml}
- \end{cmhtcbraster}
-
- \Cref{lst:textwrap9-yaml} and \cref{lst:textwrap10-yaml} are equivalent. Upon running
- the commands
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \begin{commandshell}
-latexindent.pl -s textwrap6.tex -l=textwrap9.yaml -m
-latexindent.pl -s textwrap6.tex -l=textwrap11.yaml -m
-\end{commandshell}
- we receive the respective output given in \cref{lst:textwrap6-mod9,lst:textwrap6-mod11}.
-
- \begin{widepage}
- \cmhlistingsfromfile{demonstrations/textwrap6-mod9.tex}{\texttt{textwrap6.tex} using \cref{lst:textwrap9-yaml}}{lst:textwrap6-mod9}
-
- \cmhlistingsfromfile{demonstrations/textwrap6-mod11.tex}{\texttt{textwrap6.tex} using \cref{lst:textwrap11-yaml}}{lst:textwrap6-mod11}
- \end{widepage}
-
- Notice that:
- \begin{itemize}
- \item in \cref{lst:textwrap6-mod9} the text for the \texttt{mainDocument} has been wrapped
- using \texttt{30} columns, while \texttt{environments} has been wrapped using \texttt{50}
- columns;
- \item in \cref{lst:textwrap6-mod11} the text for \texttt{myenv} has been wrapped using
- \texttt{50} columns, the text for \texttt{another} has been wrapped using \texttt{15}
- columns, and \texttt{mainDocument} has been wrapped using \texttt{30} columns.
- \end{itemize}
- If you don't specify a \texttt{default} value on per-code-block basis, then the
- \texttt{default} value from \texttt{columns} will be inherited; if you don't specify a
- default value for \texttt{columns} then \texttt{80} will be used.
-
- \texttt{alignAtAmpersandTakesPriority} is set to \texttt{1} by default; assuming
- that text wrapping is occurring on a per-code-block basis, and the current
- environment/code block is specified within \vref{lst:aligndelims:basic} then text
- wrapping will be disabled for this code block.
-
- If you wish to specify \texttt{afterHeading} commands (see
- \vref{lst:indentAfterHeadings}) on a per-name basis, then you need to append the name
- with \texttt{:heading}, for example, you might use \texttt{section:heading}.