1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
|
% arara: pdflatex: {shell: yes, 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}
|
