6. The -m (modifylinebreaks) switch
All features described in this section will only be relevant if the -m switch is used.
- modifylinebreaks:fields
As of Version 3.0, latexindent.pl has the -m switch, which permits latexindent.pl to modify line breaks, according to the specifications in the modifyLineBreaks field. The settings in this field will only be considered if the ``-m`` switch has been used. A snippet of the default settings of this field is shown in Listing 312.
500modifyLineBreaks:
501 preserveBlankLines: 1 # 0/1
502 condenseMultipleBlankLinesInto: 1 # 0/1
Having read the previous paragraph, it should sound reasonable that, if you call latexindent.pl using the -m switch, then you give it permission to modify line breaks in your file, but let’s be clear:
Warning
If you call latexindent.pl with the -m switch, then you are giving it permission to modify line breaks. By default, the only thing that will happen is that multiple blank lines will be condensed into one blank line; many other settings are possible, discussed next.
- preserveBlankLines:0|1
This field is directly related to poly-switches, discussed in Section 6.3. By default, it is set to 1, which means that blank lines will be protected from removal; however, regardless of this setting, multiple blank lines can be condensed if condenseMultipleBlankLinesInto is greater than 0, discussed next.
- condenseMultipleBlankLinesInto:positive integer
Assuming that this switch takes an integer value greater than 0, latexindent.pl will condense multiple blank lines into the number of blank lines illustrated by this switch.
As an example, Listing 313 shows a sample file with blank lines; upon running
latexindent.pl myfile.tex -m -o=+-mod1
the output is shown in Listing 314; note that the multiple blank lines have been condensed into one blank line, and note also that we have used the -m switch!
before blank line
after blank line
after blank line
before blank line
after blank line
after blank line
6.1. Text Wrapping
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 Listing 315.
530 textWrapOptions:
531 columns: 0
532 multipleSpacesToSingle: 1
533 removeBlockLineBreaks: 1
534 when: before # before/after
535 comments:
536 wrap: 0 # 0/1
537 inheritLeadingSpace: 0 # 0/1
538 blocksFollow:
539 headings: 1 # 0/1
540 commentOnPreviousLine: 1 # 0/1
541 par: 1 # 0/1
542 blankLine: 1 # 0/1
543 verbatim: 1 # 0/1
544 filecontents: 1 # 0/1
545 other: \\\]|\\item(?:\h|\[) # regex
546 blocksBeginWith:
547 A-Z: 1 # 0/1
548 a-z: 1 # 0/1
549 0-9: 0 # 0/1
550 other: 0 # regex
551 blocksEndBefore:
552 commentOnOwnLine: 1 # 0/1
553 verbatim: 1 # 0/1
554 filecontents: 1 # 0/1
555 other: \\begin\{|\\\[|\\end\{ # regex
556 huge: overflow # forbid mid-word line breaks
557 separator: ""
6.1.1. Text wrap: overview
An overview of how the text wrapping feature works:
the default value of
columnsis 0, which means that text wrapping will not happen by default;it happens after verbatim blocks have been found;
it happens after the oneSentencePerLine routine (see Section 6.2);
it can happen before or after all of the other code blocks are found and does not operate on a per-code-block basis; when using
beforethis means that, including indentation, you may receive a column width wider than that which you specify incolumns, and in which case you probably wish to exploreafterin Section 6.1.7;code blocks to be text wrapped will:
follow the fields specified in
blocksFollowbegin with the fields specified in
blocksBeginWithend before the fields specified in
blocksEndBefore
setting
columnsto a value \(>0\) will text wrap blocks by first removing line breaks, and then wrapping according to the specified value ofcolumns;setting
columnsto \(-1\) will only remove line breaks within the text wrap block;by default, the text wrapping routine will remove line breaks within text blocks because
removeBlockLineBreaksis set to 1; switch it to 0 if you wish to change this;about trailing comments within text wrap blocks:
trailing comments that do not have leading space instruct the text wrap routine to connect the lines without space (see Listing 353);
multiple trailing comments will be connected at the end of the text wrap block (see Listing 357);
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 Listing 359);
trailing comments can receive text wrapping ; examples are shown in Section 6.1.8 and Section 6.2.9.
We demonstrate this feature using a series of examples.
6.1.2. Text wrap: simple examples
Let’s use the sample text given in Listing 316.
Here is a line of text that will be wrapped by latexindent.pl.
Here is a line of text that will be wrapped by latexindent.pl.
We will change the value of columns in Listing 318 and then run the command
latexindent.pl -m -l textwrap1.yaml textwrap1.tex
then we receive the output given in Listing 317.
Here is a line of
text that will be
wrapped by
latexindent.pl.
Here is a line of
text that will be
wrapped by
latexindent.pl.
modifyLineBreaks:
textWrapOptions:
columns: 20
If we set columns to \(-1\) then latexindent.pl remove line breaks within the text wrap block, and will not perform text wrapping. We can use this to undo text wrapping.
Starting from the file in Listing 317 and using the settings in Listing 319
modifyLineBreaks:
textWrapOptions:
columns: -1
and running
latexindent.pl -m -l textwrap1A.yaml textwrap1-mod1.tex
gives the output in Listing 320.
Here is a line of text that will be wrapped by latexindent.pl.
Here is a line of text that will be wrapped by latexindent.pl.
By default, the text wrapping routine will convert multiple spaces into single spaces. You can change this behaviour by flicking the switch multipleSpacesToSingle which we have done in Listing 322
Using the settings in Listing 322 and running
latexindent.pl -m -l textwrap1B.yaml textwrap1-mod1.tex
gives the output in Listing 321.
Here is a line of
text that will be
wrapped by
latexindent.pl.
Here is a line of
text that will be
wrapped by
latexindent.pl.
modifyLineBreaks:
textWrapOptions:
columns: 20
multipleSpacesToSingle: 0
We note that in Listing 321 the multiple spaces have not been condensed into single spaces.
6.1.3. Text wrap: blocksFollow examples
We examine the blocksFollow field of Listing 315.
Let’s use the sample text given in Listing 323.
\section{my heading}\label{mylabel1}
text to
be
wrapped from the first section
\subsection{subheading}
text to
be
wrapped from the first section
We note that Listing 323 contains the heading commands section and subsection. Upon running the command
latexindent.pl -m -l textwrap1.yaml tw-headings1.tex
then we receive the output given in Listing 324.
\section{my heading}\label{mylabel1}
text to be wrapped
from the first
section
\subsection{subheading}
text to be wrapped
from the first
section
We reference Listing 315 and also Listing 174:
in Listing 315 the
headingsfield is set to1, which instructslatexindent.plto read the fields from Listing 174, regardless of the value of indentAfterThisHeading or level;the default is to assume that the heading command can, optionally, be followed by a
labelcommand.
If you find scenarios in which the default value of headings does not work, then you can explore the other field.
We can turn off headings as in Listing 326 and then run
latexindent.pl -m -l textwrap1.yaml,bf-no-headings.yaml tw-headings1.tex
gives the output in Listing 325, in which text wrapping has been instructed not to happen following headings.
\section{my heading}\label{mylabel1}
text to
be
wrapped from the first section
\subsection{subheading}
text to
be
wrapped from the first section
modifyLineBreaks:
textWrapOptions:
blocksFollow:
headings: 0
Let’s use the sample text given in Listing 327.
% trailing comment
text to
be
wrapped following first comment
% another comment
text to
be
wrapped following second comment
We note that Listing 327 contains trailing comments. Upon running the command
latexindent.pl -m -l textwrap1.yaml tw-comments1.tex
then we receive the output given in Listing 328.
% trailing comment
text to be wrapped
following first
comment
% another comment
text to be wrapped
following second
comment
With reference to Listing 315 the commentOnPreviousLine field is set to 1, which instructs latexindent.pl to find text wrap blocks after a comment on its own line.
We can turn off comments as in Listing 330 and then run
latexindent.pl -m -l textwrap1.yaml,bf-no-comments.yaml tw-comments1.tex
gives the output in Listing 329, in which text wrapping has been instructed not to happen following comments on their own line.
% trailing comment
text to
be
wrapped following first comment
% another comment
text to
be
wrapped following second comment
modifyLineBreaks:
textWrapOptions:
blocksFollow:
commentOnPreviousLine: 0
Referencing Listing 315 the blocksFollow fields par, blankline, verbatim and filecontents fields operate in analogous ways to those demonstrated in the above.
The other field of the blocksFollow can either be 0 (turned off) or set as a regular expression. The default value is set to \\\]|\\item(?:\h|\[) which can be translated to backslash followed by a square bracket or backslash item followed by horizontal space or a square bracket, or in other words, end of display math or an item command.
Let’s use the sample text given in Listing 331.
text to
be
wrapped before display math
\[ y = x\]
text to
be
wrapped after display math
We note that Listing 331 contains display math. Upon running the command
latexindent.pl -m -l textwrap1.yaml tw-disp-math1.tex
then we receive the output given in Listing 332.
text to be wrapped
before display math
\[ y = x\]
text to be wrapped
after display math
With reference to Listing 315 the other field is set to \\\], which instructs latexindent.pl to find text wrap blocks after the end of display math.
We can turn off this switch as in Listing 334 and then run
latexindent.pl -m -l textwrap1.yaml,bf-no-disp-math.yaml tw-disp-math1.tex
gives the output in Listing 333, in which text wrapping has been instructed not to happen following display math.
text to be wrapped
before display math
\[ y = x\]
text to
be
wrapped after display math
modifyLineBreaks:
textWrapOptions:
blocksFollow:
other: 0
Naturally, you should feel encouraged to customise this as you see fit.
The blocksFollow field deliberately does not default to allowing text wrapping to occur after begin environment statements. You are encouraged to customize the other field to accommodate the environments that you would like to text wrap individually, as in the next example.
Let’s use the sample text given in Listing 335.
text to
be
wrapped before myenv environment
\begin{myenv}
text to
be
wrapped within myenv environment
\end{myenv}
text to
be
wrapped after myenv environment
We note that Listing 335 contains myenv environment. Upon running the command
latexindent.pl -m -l textwrap1.yaml tw-bf-myenv1.tex
then we receive the output given in Listing 336.
text to be wrapped
before myenv
environment
\begin{myenv}
text to
be
wrapped within myenv environment
\end{myenv}
text to
be
wrapped after myenv environment
We note that we have not received much text wrapping. We can turn do better by employing Listing 338 and then run
latexindent.pl -m -l textwrap1.yaml,tw-bf-myenv.yaml tw-bf-myenv1.tex
which gives the output in Listing 337, in which text wrapping has been implemented across the file.
text to be wrapped
before myenv
environment
\begin{myenv}
text to be wrapped
within myenv
environment
\end{myenv}
text to be wrapped
after myenv
environment
modifyLineBreaks:
textWrapOptions:
blocksFollow:
other: |-
(?x)
\\\]
|
\\item(?:\h|\[)
|
\\begin\{myenv\} # <--- new bit
| # <--- new bit
\\end\{myenv\} # <--- new bit
6.1.4. Text wrap: blocksBeginWith examples
We examine the blocksBeginWith field of Listing 315 with a series of examples.
By default, text wrap blocks can begin with the characters a-z and A-Z.
If we start with the file given in Listing 339
123 text to
be
wrapped before display math
\[ y = x\]
456 text to
be
wrapped after display math
and run the command
latexindent.pl -m -l textwrap1.yaml tw-0-9.tex
then we receive the output given in Listing 340 in which text wrapping has not occurred.
123 text to
be
wrapped before display math
\[ y = x\]
456 text to
be
wrapped after display math
We can allow paragraphs to begin with 0-9 characters by using the settings in Listing 342 and running
latexindent.pl -m -l textwrap1.yaml,bb-0-9-yaml tw-0-9.tex
gives the output in Listing 341, in which text wrapping has happened.
123 text to be
wrapped before
display math
\[ y = x\]
456 text to be
wrapped after
display math
modifyLineBreaks:
textWrapOptions:
blocksBeginWith:
0-9: 1
Let’s now use the file given in Listing 343
% trailing comment
\announce{announce text}
and text
to be
wrapped before
goes here
and run the command
latexindent.pl -m -l textwrap1.yaml tw-bb-announce1.tex
then we receive the output given in Listing 344 in which text wrapping has not occurred.
% trailing comment
\announce{announce text}
and text
to be
wrapped before
goes here
We can allow \announce to be at the beginning of paragraphs by using the settings in Listing 346 and running
latexindent.pl -m -l textwrap1.yaml,tw-bb-announce.yaml tw-bb-announce1.tex
gives the output in Listing 345, in which text wrapping has happened.
% trailing comment
\announce{announce
text} and text to
be wrapped before
goes here
modifyLineBreaks:
textWrapOptions:
blocksBeginWith:
other: '\\announce'
6.1.5. Text wrap: blocksEndBefore examples
We examine the blocksEndBefore field of Listing 315 with a series of examples.
Let’s use the sample text given in Listing 347.
before
equation
text
\begin{align}
1 & 2 \\
3 & 4
\end{align}
after
equation
text
We note that Listing 347 contains an environment. Upon running the command
latexindent.pl -m -l textwrap1A.yaml tw-be-equation.tex
then we receive the output given in Listing 348.
before equation text
\begin{align}
1 & 2 \\
3 & 4
\end{align}
after
equation
text
With reference to Listing 315 the other field is set to \\begin\{|\\\[|\\end\{, which instructs latexindent.pl to stop text wrap blocks before begin statements, display math, and end statements.
We can turn off this switch as in Listing 349 and then run
latexindent.pl -m -l textwrap1A.yaml,tw-be-equation.yaml tw-be-equation.tex
gives the output in Listing 350, in which text wrapping has been instructed not to stop at these statements.
modifyLineBreaks:
textWrapOptions:
blocksEndBefore:
other: 0
before equation text \begin{align} 1 & 2 \\ 3 & 4 \end{align} after equation text
Naturally, you should feel encouraged to customise this as you see fit.
6.1.6. Text wrap: trailing comments and spaces
We explore the behaviour of the text wrap routine in relation to trailing comments using the following examples.
The file in Listing 351 contains a trailing comment which does have a space infront of it.
Running the command
latexindent.pl -m tw-tc1.tex -l textwrap1A.yaml -o=+-mod1
gives the output given in Listing 352.
foo %
bar
foo bar%
The file in Listing 353 contains a trailing comment which does not have a space infront of it.
Running the command
latexindent.pl -m tw-tc2.tex -l textwrap1A.yaml -o=+-mod1
gives the output in Listing 354.
foo%
bar
foobar%
We note that, because there is not a space before the trailing comment, that the lines have been joined without a space.
The file in Listing 355 contains multiple trailing comments.
Running the command
latexindent.pl -m tw-tc3.tex -l textwrap1A.yaml -o=+-mod1
gives the output in Listing 356.
foo %1
bar%2
three
foo barthree%1%2
The file in Listing 357 contains multiple trailing comments.
Running the command
latexindent.pl -m tw-tc4.tex -l textwrap1A.yaml -o=+-mod1
gives the output in Listing 358.
foo %1
bar%2
three%3
foo barthree%1%2%3
The file in Listing 359 contains multiple trailing comments.
Running the command
latexindent.pl -m tw-tc5.tex -l textwrap1A.yaml -o=+-mod1
gives the output in Listing 360.
foo%1
bar%2
three %3
foobarthree %1%2%3
The space at the end of the text block has been preserved.
The file in Listing 361 contains multiple trailing comments.
Running the command
latexindent.pl -m tw-tc6.tex -l textwrap1A.yaml -o=+-mod1
gives the output in Listing 362.
foo%1
bar
foobar %1
The space at the end of the text block has been preserved.
6.1.7. Text wrap: when before/after
The text wrapping routine operates, by default, before the code blocks have been found, but this can be changed to after:
beforemeans it is likely that the columns of wrapped text may exceed the value specified incolumns;aftermeans it columns of wrapped text should not exceed the value specified incolumns.
We demonstrate this in the following examples. See also Section 6.2.8.
Let’s begin with the file in Listing 363.
This paragraph
has line breaks throughout its paragraph;
we would like to combine
the textwrapping
and paragraph removal routine.
\begin{myenv}
This paragraph
has line breaks throughout its paragraph;
we would like to combine
the textwrapping
and paragraph removal routine.
\end{myenv}
Using the settings given in Listing 365 and running the command
latexindent.pl textwrap8.tex -o=+-mod1.tex -l=tw-before1.yaml -m
gives the output given in Listing 364.
This paragraph has line breaks
throughout its paragraph; we would
like to combine the textwrapping
and paragraph removal routine.
\begin{myenv}
This paragraph has line breaks
throughout its paragraph; we would
like to combine the textwrapping
and paragraph removal routine.
\end{myenv}
----|----|----|----|----|----|----|----|
5 10 15 20 25 30 35 40
defaultIndent: ' '
modifyLineBreaks:
textWrapOptions:
columns: 35
when: before # <!-------
blocksFollow:
other: \\begin\{myenv\}
We note that, in Listing 364, that the wrapped text has exceeded the specified value of columns (35) given in Listing 365. We can affect this by changing when; we explore this next.
We continue working with Listing 363.
Using the settings given in Listing 367 and running the command
latexindent.pl textwrap8.tex -o=+-mod2.tex -l=tw-after1.yaml -m
gives the output given in Listing 366.
This paragraph has line breaks
throughout its paragraph; we would
like to combine the textwrapping
and paragraph removal routine.
\begin{myenv}
This paragraph has line breaks
throughout its paragraph; we
would like to combine the
textwrapping and paragraph
removal routine.
\end{myenv}
----|----|----|----|----|----|----|----|
5 10 15 20 25 30 35 40
defaultIndent: ' '
modifyLineBreaks:
textWrapOptions:
columns: 35
when: after # <!-------
blocksFollow:
other: \\begin\{myenv\}
We note that, in Listing 366, that the wrapped text has obeyed the specified value of columns (35) given in Listing 367.
6.1.8. Text wrap: wrapping comments
You can instruct latexindent.pl to apply text wrapping to comments ; we demonstrate this with examples, see also Section 6.2.9.
We use the file in Listing 368 which contains a trailing comment block.
My first sentence
% first comment
% second
%third comment
% fourth
Using the settings given in Listing 370 and running the command
latexindent.pl textwrap9.tex -o=+-mod1.tex -l=wrap-comments1.yaml -m
gives the output given in Listing 369.
My first sentence
% first comment second third
% comment fourth
----|----|----|----|----|----|----|----|
5 10 15 20 25 30 35 40
modifyLineBreaks:
textWrapOptions:
columns: 35
comments:
wrap: 1 #<!-------
We note that, in Listing 369, that the comments have been combined and wrapped because of the annotated line specified in Listing 370.
We use the file in Listing 371 which contains a trailing comment block.
My first sentence
% first comment
% second
%third comment
% fourth
Using the settings given in Listing 373 and running the command
latexindent.pl textwrap10.tex -o=+-mod1.tex -l=wrap-comments1.yaml -m
gives the output given in Listing 372.
My first sentence
% first comment second third
% comment fourth
----|----|----|----|----|----|----|----|
5 10 15 20 25 30 35 40
modifyLineBreaks:
textWrapOptions:
columns: 35
comments:
wrap: 1 #<!-------
We note that, in Listing 372, that the comments have been combined and wrapped because of the annotated line specified in Listing 373, and that the space from the leading comment has not been inherited; we will explore this further in the next example.
We continue to use the file in Listing 371.
Using the settings given in Listing 375 and running the command
latexindent.pl textwrap10.tex -o=+-mod2.tex -l=wrap-comments2.yaml -m
gives the output given in Listing 374.
My first sentence
% first comment second third
% comment fourth
----|----|----|----|----|----|----|----|
5 10 15 20 25 30 35 40
modifyLineBreaks:
textWrapOptions:
columns: 35
comments:
wrap: 1 #<!-------
inheritLeadingSpace: 1 #<!-------
We note that, in Listing 374, that the comments have been combined and wrapped and that the leading space has been inherited because of the annotated lines specified in Listing 375.
6.1.9. Text wrap: huge, tabstop and separator
The default value of huge is overflow, which means that words will not be broken by the text wrapping routine, implemented by the Text::Wrap (“Text::Wrap Perl Module” n.d.). There are options to change the huge option for the Text::Wrap module to either wrap or die. Before modifying the value of huge, please bear in mind the following warning:
Warning
Changing the value of huge to anything other than overflow will slow down latexindent.pl significantly when the -m switch is active.
Furthermore, changing huge means that you may have some words or commands(!) split across lines in your .tex file, which may affect your output. I do not recommend changing this field.
For example, using the settings in Listing 377 and Listing 379 and running the commands
latexindent.pl -m textwrap4.tex -o=+-mod2A -l textwrap2A.yaml
latexindent.pl -m textwrap4.tex -o=+-mod2B -l textwrap2B.yaml
gives the respective output in Listing 376 and Listing 378.
He
re
is
a
li
ne
of
te
xt
.
modifyLineBreaks:
textWrapOptions:
columns: 3
huge: wrap
Here
is
a
line
of
text.
modifyLineBreaks:
textWrapOptions:
columns: 3
You can also specify the tabstop field as an integer value, which is passed to the text wrap module; see (“Text::Wrap Perl Module” n.d.) for details.
Starting with the code in Listing 380 with settings in Listing 381, and running the command
latexindent.pl -m textwrap-ts.tex -o=+-mod1 -l tabstop.yaml
gives the code given in Listing 382.
x y
modifyLineBreaks:
textWrapOptions:
columns: 80
tabstop: 9
multipleSpacesToSingle: 0
x y
You can specify separator, break and unexpand options in your settings in analogous ways to those demonstrated in Listing 379 and Listing 381, and they will be passed to the Text::Wrap module. I have not found a useful reason to do this; see (“Text::Wrap Perl Module” n.d.) for more details.
6.2. oneSentencePerLine: modifying line breaks for sentences
You can instruct latexindent.pl to format your file so that it puts one sentence per line. Thank you to (mlep 2017) for helping to shape and test this feature. The behaviour of this part of the script is controlled by the switches detailed in Listing 383, all of which we discuss next.
503 oneSentencePerLine:
504 manipulateSentences: 0 # 0/1
505 removeSentenceLineBreaks: 1 # 0/1
506 multipleSpacesToSingle: 1 # 0/1
507 textWrapSentences: 0 # 1 disables main textWrap
508 sentenceIndent: ""
509 sentencesFollow:
510 par: 1 # 0/1
511 blankLine: 1 # 0/1
512 fullStop: 1 # 0/1
513 exclamationMark: 1 # 0/1
514 questionMark: 1 # 0/1
515 rightBrace: 1 # 0/1
516 commentOnPreviousLine: 1 # 0/1
517 other: 0 # regex
518 sentencesBeginWith:
519 A-Z: 1 # 0/1
520 a-z: 0 # 0/1
521 other: 0 # regex
522 sentencesEndWith:
523 basicFullStop: 0 # 0/1
524 betterFullStop: 1 # 0/1
525 exclamationMark: 1 # 0/1
526 questionMark: 1 # 0/1
527 other: 0 # regex
528 sentencesDoNOTcontain:
529 other: \\begin # regex
6.2.1. oneSentencePerLine: overview
An overview of how the oneSentencePerLine routine feature works:
the default value of
manipulateSentencesis 0, which means that oneSentencePerLine will not happen by default;it happens after verbatim blocks have been found;
it happens before the text wrapping routine (see Section 6.1);
it happens before the main code blocks have been found;
sentences to be found:
follow the fields specified in
sentencesFollowbegin with the fields specified in
sentencesBeginWithend with the fields specified in
sentencesEndWith
by default, the oneSentencePerLine routine will remove line breaks within sentences because
removeBlockLineBreaksis set to 1; switch it to 0 if you wish to change this;sentences can be text wrapped according to
textWrapSentences, and will be done eitherbeforeorafterthe main indentation routine (see Section 6.2.8);about trailing comments within text wrap blocks:
multiple trailing comments will be connected at the end of the sentence;
the number of spaces between the end of the sentence and the (possibly combined) trailing comments is determined by the spaces (if any) at the end of the sentence.
We demonstrate this feature using a series of examples. .. describe:: manipulateSentences:0|1
This is a binary switch that details if latexindent.pl should perform the sentence manipulation routine; it is off (set to 0) by default, and you will need to turn it on (by setting it to 1) if you want the script to modify line breaks surrounding and within sentences.
- removeSentenceLineBreaks:0|1
When operating upon sentences latexindent.pl will, by default, remove internal line breaks as removeSentenceLineBreaks is set to 1. Setting this switch to 0 instructs latexindent.pl not to do so.
For example, consider multiple-sentences.tex shown in Listing 384.
This is the first
sentence. This is the; second, sentence. This is the
third sentence.
This is the fourth
sentence! This is the fifth sentence? This is the
sixth sentence.
If we use the YAML files in Listing 386 and Listing 388, and run the commands
latexindent.pl multiple-sentences -m -l=manipulate-sentences.yaml
latexindent.pl multiple-sentences -m -l=keep-sen-line-breaks.yaml
then we obtain the respective output given in Listing 385 and Listing 387.
This is the first sentence.
This is the; second, sentence.
This is the third sentence.
This is the fourth sentence!
This is the fifth sentence?
This is the sixth sentence.
modifyLineBreaks:
oneSentencePerLine:
manipulateSentences: 1
This is the first
sentence.
This is the; second, sentence.
This is the
third sentence.
This is the fourth
sentence!
This is the fifth sentence?
This is the
sixth sentence.
modifyLineBreaks:
oneSentencePerLine:
manipulateSentences: 1
removeSentenceLineBreaks: 0
Notice, in particular, that the ‘internal’ sentence line breaks in Listing 384 have been removed in Listing 385, but have not been removed in Listing 387.
- multipleSpacesToSingle:0|1
By default, the one-sentence-per-line routine will convert multiple spaces into single spaces. You can change this behaviour by changing the switch multipleSpacesToSingle to a value of 0.
The remainder of the settings displayed in Listing 383 instruct latexindent.pl on how to define a sentence. From the perspective of latexindent.pl a sentence must:
follow a certain character or set of characters (see Listing 389); by default, this is either
\par, a blank line, a full stop/period (.), exclamation mark (!), question mark (?) right brace (}) or a comment on the previous line;begin with a character type (see Listing 390); by default, this is only capital letters;
end with a character (see Listing 391); by default, these are full stop/period (.), exclamation mark (!) and question mark (?).
In each case, you can specify the other field to include any pattern that you would like; you can specify anything in this field using the language of regular expressions.
509 sentencesFollow:
510 par: 1 # 0/1
511 blankLine: 1 # 0/1
512 fullStop: 1 # 0/1
513 exclamationMark: 1 # 0/1
514 questionMark: 1 # 0/1
515 rightBrace: 1 # 0/1
516 commentOnPreviousLine: 1 # 0/1
517 other: 0 # regex
518 sentencesBeginWith:
519 A-Z: 1 # 0/1
520 a-z: 0 # 0/1
521 other: 0 # regex
522 sentencesEndWith:
523 basicFullStop: 0 # 0/1
524 betterFullStop: 1 # 0/1
525 exclamationMark: 1 # 0/1
526 questionMark: 1 # 0/1
527 other: 0 # regex
6.2.2. oneSentencePerLine: sentencesFollow
Let’s explore a few of the switches in sentencesFollow.
We start with Listing 384, and use the YAML settings given in Listing 393. Using the command
latexindent.pl multiple-sentences -m -l=sentences-follow1.yaml
we obtain the output given in Listing 392.
This is the first sentence.
This is the; second, sentence.
This is the third sentence.
This is the fourth
sentence!
This is the fifth sentence?
This is the sixth sentence.
modifyLineBreaks:
oneSentencePerLine:
manipulateSentences: 1
sentencesFollow:
blankLine: 0
Notice that, because blankLine is set to 0, latexindent.pl will not seek sentences following a blank line, and so the fourth sentence has not been accounted for.
We can explore the other field in Listing 389 with the .tex file detailed in Listing 394.
(Some sentences stand alone in brackets.) This is the first
sentence. This is the; second, sentence. This is the
third sentence.
Upon running the following commands
latexindent.pl multiple-sentences1 -m -l=manipulate-sentences.yaml
latexindent.pl multiple-sentences1 -m -l=manipulate-sentences.yaml,sentences-follow2.yaml
then we obtain the respective output given in Listing 395 and Listing 396.
(Some sentences stand alone in brackets.) This is the first
sentence.
This is the; second, sentence.
This is the third sentence.
(Some sentences stand alone in brackets.)
This is the first sentence.
This is the; second, sentence.
This is the third sentence.
modifyLineBreaks:
oneSentencePerLine:
manipulateSentences: 1
sentencesFollow:
other: "\)"
Notice that in Listing 395 the first sentence after the ) has not been accounted for, but that following the inclusion of Listing 397, the output given in Listing 396 demonstrates that the sentence has been accounted for correctly.
6.2.3. oneSentencePerLine: sentencesBeginWith
By default, latexindent.pl will only assume that sentences begin with the upper case letters A-Z; you can instruct the script to define sentences to begin with lower case letters (see Listing 390), and we can use the other field to define sentences to begin with other characters.
We use the file in Listing 398.
This is the first
sentence.
$a$ can
represent a
number. 7 is
at the beginning of this sentence.
Upon running the following commands
latexindent.pl multiple-sentences2 -m -l=manipulate-sentences.yaml
latexindent.pl multiple-sentences2 -m -l=manipulate-sentences.yaml,sentences-begin1.yaml
then we obtain the respective output given in Listing 399 and Listing 400.
This is the first sentence.
$a$ can
represent a
number. 7 is
at the beginning of this sentence.
This is the first sentence.
$a$ can represent a number.
7 is at the beginning of this sentence.
modifyLineBreaks:
oneSentencePerLine:
manipulateSentences: 1
sentencesBeginWith:
other: "\$|[0-9]"
Notice that in Listing 399, the first sentence has been accounted for but that the subsequent sentences have not. In Listing 400, all of the sentences have been accounted for, because the other field in Listing 401 has defined sentences to begin with either $ or any numeric digit, 0 to 9.
6.2.4. oneSentencePerLine: sentencesEndWith
Let’s return to Listing 384; we have already seen the default way in which latexindent.pl will operate on the sentences in this file in Listing 385. We can populate the other field with any character that we wish; for example, using the YAML specified in Listing 403 and the command
latexindent.pl multiple-sentences -m -l=sentences-end1.yaml
latexindent.pl multiple-sentences -m -l=sentences-end2.yaml
then we obtain the output in Listing 402.
This is the first sentence.
This is the;
second, sentence.
This is the third sentence.
This is the fourth sentence!
This is the fifth sentence?
This is the sixth sentence.
modifyLineBreaks:
oneSentencePerLine:
manipulateSentences: 1
sentencesEndWith:
other: "\:|\;|\,"
This is the first sentence.
This is the;
second,
sentence.
This is the third sentence.
This is the fourth sentence!
This is the fifth sentence?
This is the sixth sentence.
modifyLineBreaks:
oneSentencePerLine:
manipulateSentences: 1
sentencesEndWith:
other: "\:|\;|\,"
sentencesBeginWith:
a-z: 1
There is a subtle difference between the output in Listing 402 and Listing 404; in particular, in Listing 402 the word sentence has not been defined as a sentence, because we have not instructed latexindent.pl to begin sentences with lower case letters. We have changed this by using the settings in Listing 405, and the associated output in Listing 404
reflects this.
Referencing Listing 391, you’ll notice that there is a field called basicFullStop, which is set to 0, and that the betterFullStop is set to 1 by default.
Let’s consider the file shown in Listing 406.
This sentence, \url{tex.stackexchange.com/} finishes here. Second sentence.
Upon running the following commands
latexindent.pl url -m -l=manipulate-sentences.yaml
we obtain the output given in Listing 407.
This sentence, \url{tex.stackexchange.com/} finishes here.
Second sentence.
Notice that the full stop within the url has been interpreted correctly. This is because, within the betterFullStop, full stops at the end of sentences have the following properties:
they are ignored within
e.g.andi.e.;they can not be immediately followed by a lower case or upper case letter;
they can not be immediately followed by a hyphen, comma, or number.
If you find that the betterFullStop does not work for your purposes, then you can switch it off by setting it to 0, and you can experiment with the other field. You can also seek to customise the betterFullStop routine by using the fine tuning, detailed in Listing 586.
The basicFullStop routine should probably be avoided in most situations, as it does not accommodate the specifications above.
For example, using the following command
latexindent.pl url -m -l=alt-full-stop1.yaml
and the YAML in Listing 409 gives the output in Listing 408.
This sentence, \url{tex.
stackexchange.com/} finishes here.Second sentence.
modifyLineBreaks:
oneSentencePerLine:
manipulateSentences: 1
sentencesEndWith:
basicFullStop: 1
betterFullStop: 0
Notice that the full stop within the URL has not been accommodated correctly because of the non-default settings in Listing 409.
6.2.5. oneSentencePerLine: sentencesDoNOTcontain
You can specify patterns that sentences do not contain using the field in Listing 410.
528 sentencesDoNOTcontain:
529 other: \\begin # regex
530 textWrapOptions:
If sentences run across environments then, by default, they will not be considered a sentence by latexindent.pl. .. proof:example:
For example, if we use the ``.tex`` file in :numref:`lst:multiple-sentences4`
.. literalinclude:: demonstrations/multiple-sentences4.tex
:class: .tex
:caption: ``multiple-sentences4.tex``
:name: lst:multiple-sentences4
and run the command
.. index:: switches;-l demonstration
.. index:: switches;-m demonstration
.. code-block:: latex
:class: .commandshell
latexindent.pl multiple-sentences4 -m -l=manipulate-sentences.yaml
then the output is unchanged, because the default value of ``sentencesDoNOTcontain`` says, *sentences do NOT contain*
This means that, by default, ``latexindent.pl`` does *not* consider the file in :numref:`lst:multiple-sentences4` to have a sentence. ``\\begin``
We can customise the sentencesDoNOTcontain field with anything that we do not want sentences to contain.
We begin with the file in Listing 411.
This should not be a sentence \cmh{?} and should not change.
But this
one should.
Upon running the following commands
latexindent.pl sentence-dnc1.tex -m -l=dnc1.yaml
then we obtain the output given in Listing 412.
This should not be a sentence \cmh{?} and should not change.
But this one should.
modifyLineBreaks:
oneSentencePerLine:
manipulateSentences: 1
sentencesDoNOTcontain:
other: |-
(?x)
\\begin
|
\\cmh
The settings in Listing 413 say that sentences do not contain \begin and that they do not contain \cmh
We can implement case insensitivity for the sentencesDoNOTcontain field.
We begin with the file in Listing 414.
This should not be a sentence \cmh{?} and should not change.
This should not be a sentence \CMH{?} and should not change.
But this
one should.
Upon running the following commands
latexindent.pl sentence-dnc2.tex -m -l=dnc2.yaml
then we obtain the output given in Listing 415.
This should not be a sentence \cmh{?} and should not change.
This should not be a sentence \CMH{?} and should not change.
But this one should.
modifyLineBreaks:
oneSentencePerLine:
manipulateSentences: 1
sentencesDoNOTcontain:
other: |-
(?xi) #<!----
\\begin
|
\\cmh
The settings in Listing 416 say that sentences do not contain \begin and that they do not contain case insensitive versions of \cmh
We can turn off sentenceDoNOTcontain by setting it to 0 as in Listing 417.
modifyLineBreaks:
oneSentencePerLine:
manipulateSentences: 1
sentencesDoNOTcontain: 0
The settings in Listing 417 mean that sentences can contain any character.
6.2.6. Features of the oneSentencePerLine routine
The sentence manipulation routine takes place after verbatim
environments, preamble and trailing comments have been accounted for; this means that any characters within these types of code blocks will not be part of the sentence manipulation routine.
For example, if we begin with the .tex file in Listing 418, and run the command
latexindent.pl multiple-sentences3 -m -l=manipulate-sentences.yaml
then we obtain the output in Listing 419.
The first sentence continues after the verbatim
\begin{verbatim}
there are sentences within this. These
will not be operated
upon by latexindent.pl.
\end{verbatim}
and finishes here. Second sentence % a commented full stop.
contains trailing comments,
which are ignored.
The first sentence continues after the verbatim \begin{verbatim}
there are sentences within this. These
will not be operated
upon by latexindent.pl.
\end{verbatim} and finishes here.
Second sentence contains trailing comments, which are ignored.
% a commented full stop.
6.2.7. oneSentencePerLine: text wrapping and indenting sentences
The oneSentencePerLine can be instructed to perform text wrapping and indentation upon sentences.
Let’s use the code in Listing 420.
A distincao entre conteudo \emph{real} e conteudo \emph{intencional} esta
relacionada, ainda, a distincao entre o conceito husserliano de
\emph{experiencia} e o uso popular desse termo. No sentido comum,
o \term{experimentado} e um complexo de eventos exteriores,
e o \term{experimentar} consiste em percepcoes (alem de julgamentos e outros
atos) nas quais tais eventos aparecem como objetos, e objetos frequentemente
to the end.
Referencing Listing 422, and running the following command
latexindent.pl multiple-sentences5 -m -l=sentence-wrap1.yaml
we receive the output given in Listing 421.
A distincao entre conteudo \emph{real} e conteudo
\emph{intencional} esta relacionada, ainda, a
distincao entre o conceito husserliano de
\emph{experiencia} e o uso popular desse termo.
No sentido comum, o \term{experimentado} e um
complexo de eventos exteriores, e o
\term{experimentar} consiste em percepcoes (alem
de julgamentos e outros atos) nas quais tais
eventos aparecem como objetos, e objetos
frequentemente to the end.
modifyLineBreaks:
oneSentencePerLine:
manipulateSentences: 1
removeSentenceLineBreaks: 1
textWrapSentences: 1
sentenceIndent: " "
textWrapOptions:
columns: 50
If you specify textWrapSentences as 1, but do not specify a value for columns then the text wrapping will not operate on sentences, and you will see a warning in indent.log.
The indentation of sentences requires that sentences are stored as code blocks. This means that you may need to tweak Listing 391. Let’s explore this in relation to Listing 423.
Consider the following:
\begin{itemize}
\item firstly.
\item secondly.
\end{itemize}
By default, latexindent.pl will find the full-stop within the first item, which means that, upon running the following commands
latexindent.pl multiple-sentences6 -m -l=sentence-wrap1.yaml
latexindent.pl multiple-sentences6 -m -l=sentence-wrap1.yaml -y="modifyLineBreaks:oneSentencePerLine:sentenceIndent:''"
we receive the respective output in Listing 424 and Listing 425.
Consider the following:
\begin{itemize}
\item firstly.
\item secondly.
\end{itemize}
Consider the following:
\begin{itemize}
\item firstly.
\item secondly.
\end{itemize}
We note that Listing 424 the itemize code block has not been indented appropriately. This is because the oneSentencePerLine has been instructed to store sentences (because Listing 422); each sentence is then searched for code blocks.
We can tweak the settings in Listing 391 to ensure that full stops are not followed by item commands, and that the end of sentences contains \end{itemize} as in Listing 426. This setting is actually an appended version of the betterFullStop from the fineTuning, detailed in Listing 586.
modifyLineBreaks:
textWrapOptions:
columns: 45
oneSentencePerLine:
sentencesEndWith:
betterFullStop: 0
other: |-
(?x)
(?: # new
(?:\R|\h)*\\item # new
) # new
|
(?:
\.\)
(?!\h*[a-z])
)
|
(?:
(?<!
(?:
(?:[eE]\.[gG])
|
(?:[iI]\.[eE])
|
(?:etc)
)
)
)
\.
(?:\h*\R*(?:\\end\{itemize\})?) # new
(?!
(?:
[a-zA-Z0-9-~,]
|
\),
|
\)\.
)
)
Upon running
latexindent.pl multiple-sentences6 -m -l=sentence-wrap1.yaml,itemize.yaml
we receive the output in Listing 427.
Consider the following:
\begin{itemize}
\item firstly.
\item secondly.
\end{itemize}
Notice that the sentence has received indentation, and that the itemize code block has been found and indented correctly.
Text wrapping when using the oneSentencePerLine routine determines if it will remove line breaks while text wrapping, from the value of removeSentenceLineBreaks.
6.2.8. oneSentencePerLine: text wrapping and indenting sentences, when before/after
The text wrapping routine operates, by default, before the code blocks have been found, but this can be changed to after:
beforemeans it is likely that the columns of wrapped text may exceed the value specified incolumns;aftermeans it columns of wrapped text should not exceed the value specified incolumns.
We demonstrate this in the following examples. See also Section 6.1.7.
Let’s begin with the file in Listing 428.
This paragraph
has line breaks throughout its paragraph;
we would like to combine
the textwrapping
and paragraph removal routine.
\begin{myenv}
This paragraph
has line breaks throughout its paragraph;
we would like to combine
the textwrapping
and paragraph removal routine.
\end{myenv}
Using the settings given in Listing 430 and running the command
latexindent.pl multiple-sentences8 -o=+-mod1.tex -l=sentence-wrap2 -m
gives the output given in Listing 429.
This paragraph has line breaks
throughout its paragraph; we would
like to combine the textwrapping
and paragraph removal routine.
\begin{myenv}
This paragraph has line breaks
throughout its paragraph; we would
like to combine the textwrapping
and paragraph removal routine.
\end{myenv}
----|----|----|----|----|----|----|----|
5 10 15 20 25 30 35 40
defaultIndent: ' '
modifyLineBreaks:
oneSentencePerLine:
manipulateSentences: 1
textWrapSentences: 1
textWrapOptions:
columns: 35
when: before # <!-------
We note that, in Listing 429, that the wrapped text has exceeded the specified value of columns (35) given in Listing 430. We can affect this by changing when; we explore this next.
We continue working with Listing 428.
Using the settings given in Listing 432 and running the command
latexindent.pl multiple-sentences8.tex -o=+-mod2.tex -l=sentence-wrap3 -m
gives the output given in Listing 431.
This paragraph has line breaks
throughout its paragraph; we would
like to combine the textwrapping
and paragraph removal routine.
\begin{myenv}
This paragraph has line breaks
throughout its paragraph; we
would like to combine the
textwrapping and paragraph
removal routine.
\end{myenv}
----|----|----|----|----|----|----|----|
5 10 15 20 25 30 35 40
defaultIndent: ' '
modifyLineBreaks:
oneSentencePerLine:
manipulateSentences: 1
textWrapSentences: 1
textWrapOptions:
columns: 35
when: after # <!-------
We note that, in Listing 431, that the wrapped text has obeyed the specified value of columns (35) given in Listing 432.
6.2.9. oneSentencePerLine: text wrapping sentences and comments
We demonstrate the one sentence per line routine with respect to text wrapping comments. See also Section 6.1.8.
Let’s begin with the file in Listing 433.
This paragraph% first comment
has line breaks throughout its paragraph;% second comment
we would like to combine% third comment
the textwrapping% fourth comment
and paragraph removal routine. % fifth comment
Using the settings given in Listing 435 and running the command
latexindent.pl multiple-sentences9 -o=+-mod1.tex -l=sentence-wrap4 -m
gives the output given in Listing 434.
This paragraph has line breaks
throughout its paragraph; we would
like to combine the textwrapping
and paragraph removal routine.
% first comment second comment
% third comment fourth comment
% fifth comment
----|----|----|----|----|----|----|----|
5 10 15 20 25 30 35 40
defaultIndent: ' '
modifyLineBreaks:
oneSentencePerLine:
manipulateSentences: 1
textWrapSentences: 1
textWrapOptions:
columns: 35
comments:
wrap: 1 #<!-------
We note that, in Listing 434, that the sentences have been wrapped, and so too have the comments because of the annotated line in Listing 435.
6.3. Poly-switches
Every other field in the modifyLineBreaks field uses poly-switches, and can take one of the following integer values:
- \(-1\)
remove mode: line breaks before or after the <part of thing> can be removed (assuming that
preserveBlankLinesis set to0);- 0
off mode: line breaks will not be modified for the <part of thing> under consideration;
- 1
add mode: a line break will be added before or after the <part of thing> under consideration, assuming that there is not already a line break before or after the <part of thing>;
- 2
comment then add mode: a comment symbol will be added, followed by a line break before or after the <part of thing> under consideration, assuming that there is not already a comment and line break before or after the <part of thing>;
- 3
add then blank line mode : a line break will be added before or after the <part of thing> under consideration, assuming that there is not already a line break before or after the <part of thing>, followed by a blank line;
- 4
add blank line mode ; a blank line will be added before or after the <part of thing> under consideration, even if the <part of thing> is already on its own line.
In the above, <part of thing> refers to either the begin statement, body or end statement of the code blocks detailed in Table 2. All poly-switches are off by default; latexindent.pl searches first of all for per-name settings, and then followed by global per-thing settings.
6.3.1. Poly-switches for environments
We start by viewing a snippet of defaultSettings.yaml in Listing 436; note that it contains global settings (immediately after the environments field) and that per-name settings are also allowed – in the case of Listing 436, settings for equation* have been specified for demonstration. Note that all poly-switches are off (set to 0) by default.
559 environments:
560 BeginStartsOnOwnLine: 0 # -1,0,1,2,3,4
561 BodyStartsOnOwnLine: 0 # -1,0,1,2,3,4
562 EndStartsOnOwnLine: 0 # -1,0,1,2,3,4
563 EndFinishesWithLineBreak: 0 # -1,0,1,2,3,4
564 ## equation*:
565 ## BeginStartsOnOwnLine: 0 # -1,0,1,2,3,4
566 ## BodyStartsOnOwnLine: 0 # -1,0,1,2,3,4
567 ## EndStartsOnOwnLine: 0 # -1,0,1,2,3,4
568 ## EndFinishesWithLineBreak: 0 # -1,0,1,2,3,4
Let’s begin with the simple example given in Listing 437; note that we have annotated key parts of the file using ♠, ♥, ◆ and ♣, these will be related to fields specified in Listing 436.
before words♠ \begin{myenv}♥body of myenv◆\end{myenv}♣ after words
6.3.1.1. Adding line breaks: BeginStartsOnOwnLine and BodyStartsOnOwnLine
Let’s explore BeginStartsOnOwnLine and BodyStartsOnOwnLine in Listing 438 and Listing 439, and in particular, let’s allow each of them in turn to take a value of \(1\).
modifyLineBreaks:
environments:
BeginStartsOnOwnLine: 1
modifyLineBreaks:
environments:
BodyStartsOnOwnLine: 1
After running the following commands,
latexindent.pl -m env-mlb.tex -l env-mlb1.yaml
latexindent.pl -m env-mlb.tex -l env-mlb2.yaml
the output is as in Listing 440 and Listing 441 respectively.
before words
\begin{myenv}body of myenv\end{myenv} after words
before words \begin{myenv}
body of myenv\end{myenv} after words
There are a couple of points to note:
in Listing 440 a line break has been added at the point denoted by ♠ in Listing 437; no other line breaks have been changed;
in Listing 441 a line break has been added at the point denoted by ♥ in Listing 437; furthermore, note that the body of
myenvhas received the appropriate (default) indentation.
Let’s now change each of the 1 values in Listing 438 and Listing 439 so that they are \(2\) and save them into env-mlb3.yaml and env-mlb4.yaml respectively (see Listing 442 and Listing 443).
modifyLineBreaks:
environments:
BeginStartsOnOwnLine: 2
modifyLineBreaks:
environments:
BodyStartsOnOwnLine: 2
Upon running the commands
latexindent.pl -m env-mlb.tex -l env-mlb3.yaml
latexindent.pl -m env-mlb.tex -l env-mlb4.yaml
we obtain Listing 444 and Listing 445.
before words%
\begin{myenv}body of myenv\end{myenv} after words
before words \begin{myenv}%
body of myenv\end{myenv} after words
Note that line breaks have been added as in Listing 440 and Listing 441, but this time a comment symbol has been added before adding the line break; in both cases, trailing horizontal space has been stripped before doing so.
Let’s now change each of the 1 values in Listing 438 and Listing 439 so that they are \(3\) and save them into env-mlb5.yaml and env-mlb6.yaml respectively (see Listing 446 and Listing 447).
modifyLineBreaks:
environments:
BeginStartsOnOwnLine: 3
modifyLineBreaks:
environments:
BodyStartsOnOwnLine: 3
Upon running the commands
latexindent.pl -m env-mlb.tex -l env-mlb5.yaml
latexindent.pl -m env-mlb.tex -l env-mlb6.yaml
we obtain Listing 448 and Listing 449.
before words
\begin{myenv}body of myenv\end{myenv} after words
before words \begin{myenv}
body of myenv\end{myenv} after words
Note that line breaks have been added as in Listing 440 and Listing 441, but this time a blank line has been added after adding the line break.
Let’s now change each of the 1 values in Listing 446 and Listing 447 so that they are \(4\) and save them into env-beg4.yaml and env-body4.yaml respectively (see Listing 450 and Listing 451).
modifyLineBreaks:
environments:
BeginStartsOnOwnLine: 4
modifyLineBreaks:
environments:
BodyStartsOnOwnLine: 4
We will demonstrate this poly-switch value using the code in Listing 452.
before words
\begin{myenv}
body of myenv
\end{myenv}
after words
Upon running the commands
latexindent.pl -m env-mlb1.tex -l env-beg4.yaml
latexindent.pl -m env-mlb.1tex -l env-body4.yaml
then we receive the respective outputs in Listing 453 and Listing 454.
before words
\begin{myenv}
body of myenv
\end{myenv}
after words
before words
\begin{myenv}
body of myenv
\end{myenv}
after words
We note in particular that, by design, for this value of the poly-switches:
in Listing 453 a blank line has been inserted before the
\beginstatement, even though the\beginstatement was already on its own line;in Listing 454 a blank line has been inserted before the beginning of the body, even though it already began on its own line.
6.3.1.2. Adding line breaks: EndStartsOnOwnLine and EndFinishesWithLineBreak
Let’s explore EndStartsOnOwnLine and EndFinishesWithLineBreak in Listing 455 and Listing 456, and in particular, let’s allow each of them in turn to take a value of \(1\).
modifyLineBreaks:
environments:
EndStartsOnOwnLine: 1
modifyLineBreaks:
environments:
EndFinishesWithLineBreak: 1
After running the following commands,
latexindent.pl -m env-mlb.tex -l env-mlb7.yaml
latexindent.pl -m env-mlb.tex -l env-mlb8.yaml
the output is as in Listing 457 and Listing 458.
before words \begin{myenv}body of myenv
\end{myenv} after words
before words \begin{myenv}body of myenv\end{myenv}
after words
There are a couple of points to note:
in Listing 457 a line break has been added at the point denoted by ◆ in Listing 437; no other line breaks have been changed and the
\end{myenv}statement has not received indentation (as intended);in Listing 458 a line break has been added at the point denoted by ♣ in Listing 437.
Let’s now change each of the 1 values in Listing 455 and Listing 456 so that they are \(2\) and save them into env-mlb9.yaml and env-mlb10.yaml respectively (see Listing 459 and Listing 460).
modifyLineBreaks:
environments:
EndStartsOnOwnLine: 2
modifyLineBreaks:
environments:
EndFinishesWithLineBreak: 2
Upon running the commands
latexindent.pl -m env-mlb.tex -l env-mlb9.yaml
latexindent.pl -m env-mlb.tex -l env-mlb10.yaml
we obtain Listing 461 and Listing 462.
before words \begin{myenv}body of myenv%
\end{myenv} after words
before words \begin{myenv}body of myenv\end{myenv}%
after words
Note that line breaks have been added as in Listing 457 and Listing 458, but this time a comment symbol has been added before adding the line break; in both cases, trailing horizontal space has been stripped before doing so.
Let’s now change each of the 1 values in Listing 455 and Listing 456 so that they are \(3\) and save them into env-mlb11.yaml and env-mlb12.yaml respectively (see Listing 463 and Listing 464).
modifyLineBreaks:
environments:
EndStartsOnOwnLine: 3
modifyLineBreaks:
environments:
EndFinishesWithLineBreak: 3
Upon running the commands
latexindent.pl -m env-mlb.tex -l env-mlb11.yaml
latexindent.pl -m env-mlb.tex -l env-mlb12.yaml
we obtain Listing 465 and Listing 466.
before words \begin{myenv}body of myenv
\end{myenv} after words
before words \begin{myenv}body of myenv\end{myenv}
after words
Note that line breaks have been added as in Listing 457 and Listing 458, and that a blank line has been added after the line break.
Let’s now change each of the 1 values in Listing 463 and Listing 464 so that they are \(4\) and save them into env-end4.yaml and env-end-f4.yaml respectively (see Listing 467 and Listing 468).
modifyLineBreaks:
environments:
EndStartsOnOwnLine: 4
modifyLineBreaks:
environments:
EndFinishesWithLineBreak: 4
We will demonstrate this poly-switch value using the code from Listing 452.
Upon running the commands
latexindent.pl -m env-mlb1.tex -l env-end4.yaml
latexindent.pl -m env-mlb.1tex -l env-end-f4.yaml
then we receive the respective outputs in Listing 469 and Listing 470.
before words
\begin{myenv}
body of myenv
\end{myenv}
after words
before words
\begin{myenv}
body of myenv
\end{myenv}
after words
We note in particular that, by design, for this value of the poly-switches:
in Listing 469 a blank line has been inserted before the
\endstatement, even though the\endstatement was already on its own line;in Listing 470 a blank line has been inserted after the
\endstatement, even though it already began on its own line.
6.3.1.3. poly-switches 1, 2, and 3 only add line breaks when necessary
If you ask latexindent.pl to add a line break (possibly with a comment) using a poly-switch value of \(1\) (or \(2\) or \(3\)), it will only do so if necessary.
For example, if you process the file in Listing 471 using poly-switch values of 1, 2, or 3, it will be left unchanged.
before words
\begin{myenv}
body of myenv
\end{myenv}
after words
before words
\begin{myenv} %
body of myenv%
\end{myenv}%
after words
Setting the poly-switches to a value of \(4\) instructs latexindent.pl to add a line break even if the <part of thing> is already on its own line; see Listing 453 and Listing 454 and Listing 469 and Listing 470.
In contrast, the output from processing the file in Listing 472 will vary depending on the poly-switches used; in Listing 473 you’ll see that the comment symbol after the \begin{myenv} has been moved to the next line, as BodyStartsOnOwnLine is set to 1. In Listing 474 you’ll see that the comment has been accounted for correctly because BodyStartsOnOwnLine has been set to 2, and the comment symbol has not been moved to its own
line. You’re encouraged to experiment with Listing 472 and by setting the other poly-switches considered so far to 2 in turn.
before words
\begin{myenv}
%
body of myenv%
\end{myenv}%
after words
before words
\begin{myenv} %
body of myenv%
\end{myenv}%
after words
The details of the discussion in this section have concerned global poly-switches in the environments field; each switch can also be specified on a per-name basis, which would take priority over the global values; with reference to Listing 436, an example is shown for the equation* environment.
6.3.1.4. Removing line breaks (poly-switches set to \(-1\))
Setting poly-switches to \(-1\) tells latexindent.pl to remove line breaks of the <part of the thing>, if necessary.
We will consider the example code given in Listing 475, noting in particular the positions of the line break highlighters, ♠, ♥, ◆ and ♣, together with the associated YAML files in Listing 476 – Listing 479.
before words♠
\begin{myenv}♥
body of myenv◆
\end{myenv}♣
after words
After
modifyLineBreaks:
environments:
BeginStartsOnOwnLine: -1
modifyLineBreaks:
environments:
BodyStartsOnOwnLine: -1
modifyLineBreaks:
environments:
EndStartsOnOwnLine: -1
modifyLineBreaks:
environments:
EndFinishesWithLineBreak: -1
running the commands
latexindent.pl -m env-mlb4.tex -l env-mlb13.yaml
latexindent.pl -m env-mlb4.tex -l env-mlb14.yaml
latexindent.pl -m env-mlb4.tex -l env-mlb15.yaml
latexindent.pl -m env-mlb4.tex -l env-mlb16.yaml
we obtain the respective output in Listing 480 – Listing 483.
before words\begin{myenv}
body of myenv
\end{myenv}
after words
before words
\begin{myenv}body of myenv
\end{myenv}
after words
before words
\begin{myenv}
body of myenv\end{myenv}
after words
before words
\begin{myenv}
body of myenv
\end{myenv}after words
Notice that in:
Listing 480 the line break denoted by ♠ in Listing 475 has been removed;
Listing 481 the line break denoted by ♥ in Listing 475 has been removed;
Listing 482 the line break denoted by ◆ in Listing 475 has been removed;
Listing 483 the line break denoted by ♣ in Listing 475 has been removed.
We examined each of these cases separately for clarity of explanation, but you can combine all of the YAML settings in Listing 476 – Listing 479 into one file; alternatively, you could tell latexindent.pl to load them all by using the following command, for example
latexindent.pl -m env-mlb4.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,env-mlb16.yaml
which gives the output in Listing 437.
6.3.1.5. About trailing horizontal space
Recall that on page yaml:removeTrailingWhitespace we discussed the YAML field removeTrailingWhitespace, and that it has two (binary) switches to determine if horizontal space should be removed beforeProcessing and afterProcessing. The beforeProcessing is particularly relevant when considering the -m switch.
We consider the file shown in Listing 484, which highlights trailing spaces.
before words ♠
\begin{myenv} ♥
body of myenv ◆
\end{myenv} ♣
after words
The
removeTrailingWhitespace:
beforeProcessing: 1
output from the following commands
latexindent.pl -m env-mlb5.tex -l env-mlb13,env-mlb14,env-mlb15,env-mlb16
latexindent.pl -m env-mlb5.tex -l env-mlb13,env-mlb14,env-mlb15,env-mlb16,removeTWS-before
is shown, respectively, in Listing 486 and Listing 487; note that the trailing horizontal white space has been preserved (by default) in Listing 486, while in Listing 487, it has been removed using the switch specified in Listing 485.
before words \begin{myenv} body of myenv \end{myenv} after words
before words\begin{myenv}body of myenv\end{myenv}after words
6.3.1.6. poly-switch line break removal and blank lines
Now let’s consider the file in Listing 488, which contains blank lines.
before words♠
\begin{myenv}♥
body of myenv◆
\end{myenv}♣
after words
Upon
modifyLineBreaks:
preserveBlankLines: 0
running the following commands
latexindent.pl -m env-mlb6.tex -l env-mlb13,env-mlb14,env-mlb15,env-mlb16
latexindent.pl -m env-mlb6.tex -l env-mlb13,env-mlb14,env-mlb15,env-mlb16,UnpreserveBlankLines
we receive the respective outputs in Listing 490 and Listing 491. In Listing 490 we see that the multiple blank lines have each been condensed into one blank line, but that blank lines have not been removed by the poly-switches – this is because, by default, preserveBlankLines is set to 1. By contrast, in Listing 491, we have allowed the poly-switches to
remove blank lines because, in Listing 489, we have set preserveBlankLines to 0.
before words
\begin{myenv}
body of myenv
\end{myenv}
after words
before words\begin{myenv}body of myenv\end{myenv}after words
We can explore this further using the blank-line poly-switch value of \(3\); let’s use the file given in Listing 492.
\begin{one} one text \end{one} \begin{two} two text \end{two}
Upon running the following commands
latexindent.pl -m env-mlb7.tex -l env-mlb12.yaml,env-mlb13.yaml
latexindent.pl -m env-mlb7.tex -l env-mlb13,env-mlb14,UnpreserveBlankLines
we receive the outputs given in Listing 493 and Listing 494.
\begin{one} one text \end{one}
\begin{two} two text \end{two}
\begin{one} one text \end{one} \begin{two} two text \end{two}
Notice that in:
Listing 493 that
\end{one}has added a blank line, because of the value ofEndFinishesWithLineBreakin Listing 464, and even though the line break ahead of\begin{two}should have been removed (because ofBeginStartsOnOwnLinein Listing 476), the blank line has been preserved by default;Listing 494, by contrast, has had the additional line-break removed, because of the settings in Listing 489.
6.3.2. Poly-switches for double backslash
With reference to lookForAlignDelims (see Listing 75) you can specify poly-switches to dictate the line-break behaviour of double backslashes in environments (Listing 77), commands (Listing 111), or special code blocks (Listing 156). 1
Consider the code given in Listing 495.
\begin{tabular}{cc}
1 & 2 ★\\□ 3 & 4 ★\\□
\end{tabular}
Referencing Listing 495:
DBSstands for double backslash;line breaks ahead of the double backslash are annotated by ★, and are controlled by
DBSStartsOnOwnLine;line breaks after the double backslash are annotated by □, and are controlled by
DBSFinishesWithLineBreak.
Let’s explore each of these in turn.
6.3.2.1. Double backslash starts on own line
We explore DBSStartsOnOwnLine (★ in Listing 495); starting with the code in Listing 495, together with the YAML files given in Listing 497 and Listing 499 and running the following commands
latexindent.pl -m tabular3.tex -l DBS1.yaml
latexindent.pl -m tabular3.tex -l DBS2.yaml
then we receive the respective output given in Listing 496 and Listing 498.
\begin{tabular}{cc}
1 & 2
\\ 3 & 4
\\
\end{tabular}
modifyLineBreaks:
environments:
DBSStartsOnOwnLine: 1
\begin{tabular}{cc}
1 & 2 %
\\ 3 & 4%
\\
\end{tabular}
modifyLineBreaks:
environments:
tabular:
DBSStartsOnOwnLine: 2
We note that
Listing 497 specifies
DBSStartsOnOwnLinefor every environment (that is withinlookForAlignDelims, Listing 78); the double backslashes from Listing 495 have been moved to their own line in Listing 496;Listing 499 specifies
DBSStartsOnOwnLineon a per-name basis fortabular(that is withinlookForAlignDelims, Listing 78); the double backslashes from Listing 495 have been moved to their own line in Listing 498, having added comment symbols before moving them.
We can combine DBS poly-switches with, for example, the alignContentAfterDoubleBackSlash in Section 5.5.6.
For example, starting with the file Listing 500, and using the settings in Listing 147 and Listing 149 and running
latexindent.pl -s -m -l alignContentAfterDBS1.yaml,DBS1.yaml tabular6.tex -o=+-mod1
latexindent.pl -s -m -l alignContentAfterDBS2.yaml,DBS1.yaml tabular6.tex -o=+-mod2
gives the respective outputs shown in Listing 501 and Listing 502.
\begin{tabular}{cc}
1&22\\333&4444\\55555&666666
\end{tabular}
\begin{tabular}{cc}
1 & 22
\\ 333 & 4444
\\ 55555 & 666666
\end{tabular}
\begin{tabular}{cc}
1 & 22
\\ 333 & 4444
\\ 55555 & 666666
\end{tabular}
We note that:
in Listing 501 the content after the double back slash has been aligned;
in Listing 502 we see that 3 spaces have been added after the double back slash.
6.3.2.2. Double backslash finishes with line break
Let’s now explore DBSFinishesWithLineBreak (□ in Listing 495); starting with the code in Listing 495, together with the YAML files given in Listing 504 and Listing 506 and running the following commands
latexindent.pl -m tabular3.tex -l DBS3.yaml
latexindent.pl -m tabular3.tex -l DBS4.yaml
then we receive the respective output given in Listing 503 and Listing 505.
\begin{tabular}{cc}
1 & 2 \\
3 & 4 \\
\end{tabular}
modifyLineBreaks:
environments:
DBSFinishesWithLineBreak: 1
\begin{tabular}{cc}
1 & 2 \\%
3 & 4 \\
\end{tabular}
modifyLineBreaks:
environments:
tabular:
DBSFinishesWithLineBreak: 2
We note that
Listing 504 specifies
DBSFinishesWithLineBreakfor every environment (that is withinlookForAlignDelims, Listing 78); the code following the double backslashes from Listing 495 has been moved to their own line in Listing 503;Listing 506 specifies
DBSFinishesWithLineBreakon a per-name basis fortabular(that is withinlookForAlignDelims, Listing 78); the first double backslashes from Listing 495 have moved code following them to their own line in Listing 505, having added comment symbols before moving them; the final double backslashes have not added a line break as they are at the end of the body within the code block.
6.3.2.3. Double backslash poly-switches for specialBeginEnd
Let’s explore the double backslash poly-switches for code blocks within specialBeginEnd code blocks (Listing 154); we begin with the code within Listing 507.
\< a& =b \\ & =c\\ & =d\\ & =e \>
Upon using the YAML settings in Listing 509, and running the command
latexindent.pl -m special4.tex -l DBS5.yaml
then we receive the output given in Listing 508.
\<
a & =b \\
& =c \\
& =d \\
& =e %
\>
specialBeginEnd:
cmhMath:
lookForThis: 1
begin: '\\<'
end: '\\>'
lookForAlignDelims:
cmhMath: 1
modifyLineBreaks:
specialBeginEnd:
cmhMath:
DBSFinishesWithLineBreak: 1
SpecialBodyStartsOnOwnLine: 1
SpecialEndStartsOnOwnLine: 2
There are a few things to note:
in Listing 509 we have specified
cmhMathwithinlookForAlignDelims; without this, the double backslash poly-switches would be ignored for this code block;the
DBSFinishesWithLineBreakpoly-switch has controlled the line breaks following the double backslashes;the
SpecialEndStartsOnOwnLinepoly-switch has controlled the addition of a comment symbol, followed by a line break, as it is set to a value of 2.
6.3.2.4. Double backslash poly-switches for optional and mandatory arguments
For clarity, we provide a demonstration of controlling the double backslash poly-switches for optional and mandatory arguments.
We use with the code in Listing 510.
\mycommand [
1&2 &3\\ 4&5&6]{
7&8 &9\\ 10&11&12
}
Upon using the YAML settings in Listing 512 and Listing 514, and running the command
latexindent.pl -m mycommand2.tex -l DBS6.yaml
latexindent.pl -m mycommand2.tex -l DBS7.yaml
then we receive the output given in Listing 511 and Listing 513.
\mycommand [
1 & 2 & 3 %
\\%
4 & 5 & 6]{
7 & 8 & 9 \\ 10&11&12
}
lookForAlignDelims:
mycommand: 1
modifyLineBreaks:
optionalArguments:
DBSStartsOnOwnLine: 2
DBSFinishesWithLineBreak: 2
\mycommand [
1&2 &3\\ 4&5&6]{
7 & 8 & 9 %
\\%
10 & 11 & 12
}
lookForAlignDelims:
mycommand: 1
modifyLineBreaks:
mandatoryArguments:
DBSStartsOnOwnLine: 2
DBSFinishesWithLineBreak: 2
6.3.2.5. Double backslash optional square brackets
The pattern matching for the double backslash will also, optionally, allow trailing square brackets that contain a measurement of vertical spacing, for example \\[3pt].
For example, beginning with the code in Listing 515
\begin{pmatrix}
1 & 2 \\[2pt] 3 & 4 \\ [ 3 ex] 5&6\\[ 4 pt ] 7 & 8
\end{pmatrix}
and running the following command, using Listing 504,
latexindent.pl -m pmatrix3.tex -l DBS3.yaml
then we receive the output given in Listing 516.
\begin{pmatrix}
1 & 2 \\[2pt]
3 & 4 \\ [ 3 ex]
5 & 6 \\[ 4 pt ]
7 & 8
\end{pmatrix}
You can customise the pattern for the double backslash by exploring the fine tuning field detailed in Listing 586.
6.3.3. Poly-switches for other code blocks
Rather than repeat the examples shown for the environment code blocks (in Section 6.3.1), we choose to detail the poly-switches for all other code blocks in Table 3; note that each and every one of these poly-switches is off by default, i.e, set to 0.
Note also that, by design, line breaks involving, filecontents and ‘comment-marked’ code blocks (Listing 112) can not be modified using latexindent.pl. However, there are two poly-switches available for verbatim code blocks: environments (Listing 54), commands (Listing 55) and specialBeginEnd (Listing 168).
Code block |
Sample |
||
|---|---|---|---|
environment |
|
♠ |
BeginStartsOnOwnLine |
|
♥ |
BodyStartsOnOwnLine |
|
|
◆ |
EndStartsOnOwnLine |
|
|
♣ |
EndFinishesWithLineBreak |
|
|
|||
ifelsefi |
|
♠ |
IfStartsOnOwnLine |
|
♥ |
BodyStartsOnOwnLine |
|
|
▲ |
OrStartsOnOwnLine |
|
|
▼ |
OrFinishesWithLineBreak |
|
|
★ |
ElseStartsOnOwnLine |
|
|
□ |
ElseFinishesWithLineBreak |
|
|
◆ |
FiStartsOnOwnLine |
|
|
♣ |
FiFinishesWithLineBreak |
|
|
|||
optionalArguments |
|
♠ |
LSqBStartsOnOwnLine 2 |
|
♥ |
OptArgBodyStartsOnOwnLine |
|
|
★ |
CommaStartsOnOwnLine |
|
□ |
□ |
CommaFinishesWithLineBreak |
|
|
◆ |
RSqBStartsOnOwnLine |
|
|
♣ |
RSqBFinishesWithLineBreak |
|
|
|||
mandatoryArguments |
|
♠ |
LCuBStartsOnOwnLine 3 |
|
♥ |
MandArgBodyStartsOnOwnLine |
|
|
★ |
CommaStartsOnOwnLine |
|
□ |
□ |
CommaFinishesWithLineBreak |
|
|
◆ |
RCuBStartsOnOwnLine |
|
|
♣ |
RCuBFinishesWithLineBreak |
|
|
|||
commands |
|
♠ |
CommandStartsOnOwnLine |
|
♥ |
CommandNameFinishesWithLineBreak |
|
<arguments> |
|||
namedGroupingBracesBrackets |
before words♠ |
♠ |
NameStartsOnOwnLine |
myname♥ |
♥ |
NameFinishesWithLineBreak |
|
<braces/brackets> |
|||
keyEqualsValuesBracesBrackets |
before words♠ |
♠ |
KeyStartsOnOwnLine |
key●=♥ |
● |
EqualsStartsOnOwnLine |
|
<braces/brackets> |
♥ |
EqualsFinishesWithLineBreak |
|
items |
before words♠ |
♠ |
ItemStartsOnOwnLine |
|
♥ |
ItemFinishesWithLineBreak |
|
|
|||
specialBeginEnd |
before words♠ |
♠ |
SpecialBeginStartsOnOwnLine |
|
♥ |
SpecialBodyStartsOnOwnLine |
|
|
★ |
SpecialMiddleStartsOnOwnLine |
|
|
□ |
SpecialMiddleFinishesWithLineBreak |
|
body of special/middle ◆ |
◆ |
SpecialEndStartsOnOwnLine |
|
|
♣ |
SpecialEndFinishesWithLineBreak |
|
after words |
|||
verbatim |
before words♠ |
♠ |
VerbatimBeginStartsOnOwnLine |
body of verbatim |
♣ |
VerbatimEndFinishesWithLineBreak |
|
after words |
6.3.4. Partnering BodyStartsOnOwnLine with argument-based poly-switches
Some poly-switches need to be partnered together; in particular, when line breaks involving the first argument of a code block need to be accounted for using both BodyStartsOnOwnLine (or its equivalent, see Table 3) and LCuBStartsOnOwnLine for mandatory arguments, and LSqBStartsOnOwnLine for optional arguments.
Let’s begin with the code in Listing 517 and the YAML settings in Listing 519; with reference to Table 3, the key CommandNameFinishesWithLineBreak is an alias for BodyStartsOnOwnLine.
\mycommand
{
mand arg text
mand arg text}
{
mand arg text
mand arg text}
Upon running the command
latexindent.pl -m -l=mycom-mlb1.yaml mycommand1.tex
we obtain Listing 518; note that the second mandatory argument beginning brace \{ has had its leading line break removed, but that the first brace has not.
\mycommand
{
mand arg text
mand arg text}{
mand arg text
mand arg text}
modifyLineBreaks:
commands:
CommandNameFinishesWithLineBreak: 0
mandatoryArguments:
LCuBStartsOnOwnLine: -1
Now let’s change the YAML file so that it is as in Listing 521; upon running the command
latexindent.pl -m -l=mycom-mlb2.yaml mycommand1.tex
we obtain Listing 520; both beginning braces \{ have had their leading line breaks removed.
\mycommand{
mand arg text
mand arg text}{
mand arg text
mand arg text}
modifyLineBreaks:
commands:
CommandNameFinishesWithLineBreak: -1
mandatoryArguments:
LCuBStartsOnOwnLine: -1
Now let’s change the YAML file so that it is as in Listing 523; upon running the command
latexindent.pl -m -l=mycom-mlb3.yaml mycommand1.tex
we obtain Listing 522.
\mycommand
{
mand arg text
mand arg text}
{
mand arg text
mand arg text}
modifyLineBreaks:
commands:
CommandNameFinishesWithLineBreak: -1
mandatoryArguments:
LCuBStartsOnOwnLine: 1
6.3.5. Conflicting poly-switches: sequential code blocks
It is very easy to have conflicting poly-switches.
We use the example from Listing 517, and consider the YAML settings given in Listing 525. The output from running
latexindent.pl -m -l=mycom-mlb4.yaml mycommand1.tex
is given in Listing 525.
\mycommand
{
mand arg text
mand arg text}{
mand arg text
mand arg text}
modifyLineBreaks:
mandatoryArguments:
LCuBStartsOnOwnLine: -1
RCuBFinishesWithLineBreak: 1
Studying Listing 525, we see that the two poly-switches are at opposition with one another:
on the one hand,
LCuBStartsOnOwnLineshould not start on its own line (as poly-switch is set to \(-1\));on the other hand,
RCuBFinishesWithLineBreakshould finish with a line break.
So, which should win the conflict? As demonstrated in Listing 524, it is clear that LCuBStartsOnOwnLine won this conflict, and the reason is that the second argument was processed after the first – in general, the most recently-processed code block and associated poly-switch takes priority.
We can explore this further by considering the YAML settings in Listing 527; upon running the command
latexindent.pl -m -l=mycom-mlb5.yaml mycommand1.tex
we obtain the output given in Listing 526.
\mycommand
{
mand arg text
mand arg text}
{
mand arg text
mand arg text}
modifyLineBreaks:
mandatoryArguments:
LCuBStartsOnOwnLine: 1
RCuBFinishesWithLineBreak: -1
As previously, the most-recently-processed code block takes priority – as before, the second (i.e, last) argument.
Exploring this further, we consider the YAML settings in Listing 529, and run the command
latexindent.pl -m -l=mycom-mlb6.yaml mycommand1.tex
which gives the output in Listing 528.
\mycommand
{
mand arg text
mand arg text}%
{
mand arg text
mand arg text}
modifyLineBreaks:
mandatoryArguments:
LCuBStartsOnOwnLine: 2
RCuBFinishesWithLineBreak: -1
Note that a % has been added to the trailing first }; this is because:
while processing the first argument, the trailing line break has been removed (
RCuBFinishesWithLineBreakset to \(-1\));while processing the second argument,
latexindent.plfinds that it does not begin on its own line, and so becauseLCuBStartsOnOwnLineis set to \(2\), it adds a comment, followed by a line break.
6.3.6. Conflicting poly-switches: nested code blocks
Now let’s consider an example when nested code blocks have conflicting poly-switches; we’ll use the code in Listing 530, noting that it contains nested environments.
\begin{one}
one text
\begin{two}
two text
\end{two}
\end{one}
Let’s use the YAML settings given in Listing 532, which upon running the command
latexindent.pl -m -l=nested-env-mlb1.yaml nested-env.tex
gives the output in Listing 531.
\begin{one}
one text
\begin{two}
two text\end{two}\end{one}
modifyLineBreaks:
environments:
EndStartsOnOwnLine: -1
EndFinishesWithLineBreak: 1
In Listing 531, let’s first of all note that both environments have received the appropriate (default) indentation; secondly, note that the poly-switch EndStartsOnOwnLine appears to have won the conflict, as \end{one} has had its leading line break removed.
To understand it, let’s talk about the three basic phases
of latexindent.pl:
Phase 1: packing, in which code blocks are replaced with unique ids, working from the inside to the outside, and then sequentially – for example, in Listing 530, the
twoenvironment is found before theoneenvironment; if the -m switch is active, then during this phase:line breaks at the beginning of the
bodycan be added (ifBodyStartsOnOwnLineis \(1\) or \(2\)) or removed (ifBodyStartsOnOwnLineis \(-1\));line breaks at the end of the body can be added (if
EndStartsOnOwnLineis \(1\) or \(2\)) or removed (ifEndStartsOnOwnLineis \(-1\));line breaks after the end statement can be added (if
EndFinishesWithLineBreakis \(1\) or \(2\)).
Phase 2: indentation, in which white space is added to the begin, body, and end statements;
Phase 3: unpacking, in which unique ids are replaced by their indented code blocks; if the -m switch is active, then during this phase,
line breaks before
beginstatements can be added or removed (depending uponBeginStartsOnOwnLine);line breaks after end statements can be removed but NOT added (see
EndFinishesWithLineBreak).
With reference to Listing 531, this means that during Phase 1:
the
twoenvironment is found first, and the line break ahead of the\end{two}statement is removed becauseEndStartsOnOwnLineis set to \(-1\). Importantly, because, at this stage,\end{two}does finish with a line break,EndFinishesWithLineBreakcauses no action.next, the
oneenvironment is found; the line break ahead of\end{one}is removed becauseEndStartsOnOwnLineis set to \(-1\).
The indentation is done in Phase 2; in Phase 3 there is no option to add a line break after the ``end`` statements. We can justify this by remembering that during Phase 3, the one environment will be found and processed first, followed by the two environment. If the two environment were to add a line break after the \end{two} statement, then latexindent.pl would have no way of knowing how much indentation to add to the subsequent text (in this case, \end{one}).
We can explore this further using the poly-switches in Listing 534; upon running the command
latexindent.pl -m -l=nested-env-mlb2.yaml nested-env.tex
we obtain the output given in Listing 533.
\begin{one}
one text
\begin{two}
two text
\end{two}\end{one}
modifyLineBreaks:
environments:
EndStartsOnOwnLine: 1
EndFinishesWithLineBreak: -1
During Phase 1:
the
twoenvironment is found first, and the line break ahead of the\end{two}statement is not changed becauseEndStartsOnOwnLineis set to \(1\). Importantly, because, at this stage,\end{two}does finish with a line break,EndFinishesWithLineBreakcauses no action.next, the
oneenvironment is found; the line break ahead of\end{one}is already present, and no action is needed.
The indentation is done in Phase 2, and then in Phase 3, the one environment is found and processed first, followed by the two environment. At this stage, the two environment finds EndFinishesWithLineBreak is \(-1\), so it removes the trailing line break; remember, at this point, latexindent.pl has completely finished with the one environment.
mlep. 2017. “One Sentence Per Line.” August 16, 2017. https://github.com/cmhughes/latexindent.pl/issues/81.
“Text::Wrap Perl Module.” n.d. Accessed May 1, 2017. http://perldoc.perl.org/Text/Wrap.html.