summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/support/latexindent/subsec-text-wrap.tex
blob: fddbffd98b8e7980d7c25626902bfa361405928a (plain)
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
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
% arara: pdflatex: { files: [latexindent]}
\subsection{Text Wrapping}\label{subsec:textwrapping}
 \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; this means that, including indentation, you may
        receive a column width wider than that which you specify in \texttt{columns}
  \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;
  \item by default, the text wrapping routine will remove line breaks within text blocks because
        \texttt{removeBlockLineBreaks} is set to 1; switch it to 0 if you wish to change this;
  \item about trailing comments within text wrap blocks:
        \begin{enumerate}
         \item trailing comments that do \emph{not} have leading space instruct the text wrap routine to
               connect the lines \emph{without} space (see \cref{lst:tw-tc2});
         \item multiple trailing comments will be connected at the end of the text wrap block (see
               \cref{lst:tw-tc4});
         \item the number of spaces between the end of the text wrap block and the (possibly combined)
               trailing comments is determined by the spaces (if any) at the end of the text wrap block
               (see \cref{lst:tw-tc5}).
        \end{enumerate}
 \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}.

  \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}

 \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}

  Starting from the file in \cref{lst:textwrap1-mod1} and using the settings in
  \cref{lst:textwrap1A-yaml}

  \cmhlistingsfromfile{demonstrations/textwrap1A.yaml}[MLB-TCB]{\texttt{textwrap1A.yaml}}{lst:textwrap1A-yaml}

  and running
  \begin{commandshell}
latexindent.pl -m -l textwrap1A.yaml textwrap1-mod1.tex
\end{commandshell}
  gives the output in \cref{lst:textwrap1-mod1A}.

  \cmhlistingsfromfile{demonstrations/textwrap1-mod1A.tex}{\texttt{textwrap1-mod1A.tex}}{lst:textwrap1-mod1A}
 \end{example}

 \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}

  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}
  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}
  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}.

  \cmhlistingsfromfile{demonstrations/tw-comments1-mod1.tex}{\texttt{tw-comments1-mod1.tex}}{lst:tw-comments1-mod1}

  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.

  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}.

  \cmhlistingsfromfile{demonstrations/tw-disp-math1-mod1.tex}{\texttt{tw-disp-math1-mod1.tex}}{lst:tw-disp-math1-mod1}

  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 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}.

  \cmhlistingsfromfile{demonstrations/tw-bf-myenv1-mod1.tex}{\texttt{tw-bf-myenv1-mod1.tex}}{lst:tw-bf-myenv1-mod1}

  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}
  then we receive the output given in \cref{lst:tw-bb-announce1-mod1} in which text
  wrapping has \emph{not} occured.

  \cmhlistingsfromfile{demonstrations/tw-bb-announce1-mod1.tex}{\texttt{tw-bb-announce1-mod1.tex}}{lst:tw-bb-announce1-mod1}

  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}
  \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}
  \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: trailing comments and spaces}
 We explore the behaviour of the text wrap routine in relation to trailing comments using
 the following examples.

 \begin{example}
  The file in \cref{lst:tw-tc1} contains a trailing comment which \emph{does} have a space
  infront of it.

  Running the command
  \begin{commandshell}
latexindent.pl -m tw-tc1.tex -l textwrap1A.yaml -o=+-mod1 
\end{commandshell}
  gives the output given in \cref{lst:tw-tc1-mod1}.

  \begin{cmhtcbraster}[raster column skip=.1\linewidth]
   \cmhlistingsfromfile*[showspaces=true]{demonstrations/tw-tc1.tex}{\texttt{tw-tc1.tex}}{lst:tw-tc1}
   \cmhlistingsfromfile*{demonstrations/tw-tc1-mod1.tex}{\texttt{tw-tc1-mod1.tex}}{lst:tw-tc1-mod1}
  \end{cmhtcbraster}
 \end{example}

 \begin{example}
  The file in \cref{lst:tw-tc2} contains a trailing comment which does \emph{not} have a
  space infront of it.

  Running the command
  \begin{commandshell}
latexindent.pl -m tw-tc2.tex -l textwrap1A.yaml -o=+-mod1 
\end{commandshell}
  gives the output in \cref{lst:tw-tc2-mod1}.
  \begin{cmhtcbraster}[raster column skip=.1\linewidth]
   \cmhlistingsfromfile*{demonstrations/tw-tc2.tex}{\texttt{tw-tc2.tex}}{lst:tw-tc2}
   \cmhlistingsfromfile*{demonstrations/tw-tc2-mod1.tex}{\texttt{tw-tc2-mod1.tex}}{lst:tw-tc2-mod1}
  \end{cmhtcbraster}
  We note that, because there is \emph{not} a space before the trailing comment, that the
  lines have been joined \emph{without} a space.
 \end{example}

 \begin{example}
  The file in \cref{lst:tw-tc3} contains multiple trailing comments.

  Running the command
  \begin{commandshell}
latexindent.pl -m tw-tc3.tex -l textwrap1A.yaml -o=+-mod1 
\end{commandshell}
  gives the output in \cref{lst:tw-tc3-mod1}.
  \begin{cmhtcbraster}[raster column skip=.1\linewidth]
   \cmhlistingsfromfile*{demonstrations/tw-tc3.tex}{\texttt{tw-tc3.tex}}{lst:tw-tc3}
   \cmhlistingsfromfile*{demonstrations/tw-tc3-mod1.tex}{\texttt{tw-tc3-mod1.tex}}{lst:tw-tc3-mod1}
  \end{cmhtcbraster}
 \end{example}

 \begin{example}
  The file in \cref{lst:tw-tc4} contains multiple trailing comments.

  Running the command
  \begin{commandshell}
latexindent.pl -m tw-tc4.tex -l textwrap1A.yaml -o=+-mod1 
\end{commandshell}
  gives the output in \cref{lst:tw-tc4-mod1}.
  \begin{cmhtcbraster}[raster column skip=.1\linewidth]
   \cmhlistingsfromfile*{demonstrations/tw-tc4.tex}{\texttt{tw-tc4.tex}}{lst:tw-tc4}
   \cmhlistingsfromfile*{demonstrations/tw-tc4-mod1.tex}{\texttt{tw-tc4-mod1.tex}}{lst:tw-tc4-mod1}
  \end{cmhtcbraster}
 \end{example}

 \begin{example}
  The file in \cref{lst:tw-tc5} contains multiple trailing comments.

  Running the command
  \begin{commandshell}
latexindent.pl -m tw-tc5.tex -l textwrap1A.yaml -o=+-mod1 
\end{commandshell}
  gives the output in \cref{lst:tw-tc5-mod1}.
  \begin{cmhtcbraster}[raster column skip=.1\linewidth]
   \cmhlistingsfromfile*[showspaces=true]{demonstrations/tw-tc5.tex}{\texttt{tw-tc5.tex}}{lst:tw-tc5}
   \cmhlistingsfromfile*[showspaces=true]{demonstrations/tw-tc5-mod1.tex}{\texttt{tw-tc5-mod1.tex}}{lst:tw-tc5-mod1}
  \end{cmhtcbraster}
  The space at the end of the text block has been preserved.
 \end{example}

 \begin{example}
  The file in \cref{lst:tw-tc6} contains multiple trailing comments.

  Running the command
  \begin{commandshell}
latexindent.pl -m tw-tc6.tex -l textwrap1A.yaml -o=+-mod1 
\end{commandshell}
  gives the output in \cref{lst:tw-tc6-mod1}.
  \begin{cmhtcbraster}[raster column skip=.1\linewidth]
   \cmhlistingsfromfile*[showspaces=true]{demonstrations/tw-tc6.tex}{\texttt{tw-tc6.tex}}{lst:tw-tc6}
   \cmhlistingsfromfile*[showspaces=true]{demonstrations/tw-tc6-mod1.tex}{\texttt{tw-tc6-mod1.tex}}{lst:tw-tc6-mod1}
  \end{cmhtcbraster}
  The space at the end of the text block has been preserved.
 \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
  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}
 \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
\end{commandshell}
 gives the respective output in \cref{lst:textwrap4-mod2A,lst:textwrap4-mod2B}.

 \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/textwrap4-mod2B.tex}{\texttt{textwrap4-mod2B.tex}}{lst:textwrap4-mod2B}
  \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}%
 \begin{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,
   raster right skip=-2cm,
   raster column skip=.03\linewidth]
  \cmhlistingsfromfile[showtabs=true]{demonstrations/textwrap-ts.tex}{\texttt{textwrap-ts.tex}}{lst:textwrap-ts}
  \cmhlistingsfromfile{demonstrations/tabstop.yaml}[MLB-TCB]{\texttt{tabstop.yaml}}{lst:tabstop}
  \cmhlistingsfromfile[showtabs=true]{demonstrations/textwrap-ts-mod1.tex}{\texttt{textwrap-ts-mod1.tex}}{lst:textwrap-ts-mod1}
 \end{cmhtcbraster}

 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.