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

Listing 280 modifyLineBreaks

modifyLineBreaks:
    preserveBlankLines: 1
    condenseMultipleBlankLinesInto: 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 281 shows a sample file with blank lines; upon running

latexindent.pl myfile.tex -m -o=+-mod1

the output is shown in Listing 282; note that the multiple blank lines have been condensed into one blank line, and note also that we have used the -m switch!

Listing 281 mlb1.tex

before blank line



after blank line


after blank line

Listing 282 mlb1-mod1.tex

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

Listing 283 textWrapOptions

    textWrapOptions:
        columns: 0
        multipleSpacesToSingle: 1            
        removeBlockLineBreaks: 1
        blocksFollow:
           headings: 1
           commentOnPreviousLine: 1
           par: 1
           blankLine: 1
           verbatim: 1
           filecontents: 1
           other: '\\\]|\\item(?:\h|\[)'      # regex
        blocksBeginWith:
           A-Z: 1
           a-z: 1
           0-9: 0
           other: 0                           # regex
        blocksEndBefore:
           commentOnOwnLine: 1
           verbatim: 1
           filecontents: 1
           other: '\\begin\{|\\\[|\\end\{'    # regex
        huge: overflow                        # forbid mid-word line breaks
        separator: ""

6.1.1. Text wrap: overview

An overview of how the text wrapping feature works:

1. the default value of columns is 0, which means that text wrapping will not happen by default;
2. it happens after verbatim blocks have been found;
3. it happens after the oneSentencePerLine routine (see Section 6.2);
4. it happens before all of the other code blocks are found and does 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 columns
5. code blocks to be text wrapped will:
   1. follow the fields specified in blocksFollow
   2. begin with the fields specified in blocksBeginWith
   3. end before the fields specified in blocksEndBefore
6. setting columns to a value \(>0\) will text wrap blocks by first removing line breaks, and then wrapping according to the specified value of columns;
7. setting columns to \(-1\) will only remove line breaks within the text wrap block;
8. by default, the text wrapping routine will remove line breaks within text blocks because removeBlockLineBreaks is set to 1; switch it to 0 if you wish to change this;
9. about trailing comments within text wrap blocks:
   1. trailing comments that do not have leading space instruct the text wrap routine to connect the lines without space (see Listing 321);
   2. multiple trailing comments will be connected at the end of the text wrap block (see Listing 325);
   3. 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 327).

We demonstrate this feature using a series of examples.

6.1.2. Text wrap: simple examples

Example 8

Let’s use the sample text given in Listing 284.

Listing 284 textwrap1.tex

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 286 and then run the command

latexindent.pl -m -l textwrap1.yaml textwrap1.tex

then we receive the output given in Listing 285.

Listing 285 textwrap1-mod1.tex

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.

Listing 286 textwrap1.yaml

modifyLineBreaks:
    textWrapOptions:
        columns: 20

Example 9

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 285 and using the settings in Listing 287

Listing 287 textwrap1A.yaml

modifyLineBreaks:
    textWrapOptions:
        columns: -1

and running

latexindent.pl -m -l textwrap1A.yaml textwrap1-mod1.tex

gives the output in Listing 288.

Listing 288 textwrap1-mod1A.tex

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.

Example 10

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 289

Using the settings in Listing 289 and running

latexindent.pl -m -l textwrap1B.yaml textwrap1-mod1.tex

gives the output in Listing 290.

Listing 289 textwrap1B.yaml

modifyLineBreaks:
    textWrapOptions:
        columns: 20
        multipleSpacesToSingle: 0

Listing 290 textwrap1-mod1B.tex

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 note that in Listing 290 the multiple spaces have not been condensed into single spaces.

6.1.3. Text wrap: blocksFollow examples

We examine the blocksFollow field of Listing 283.

Example 11

Let’s use the sample text given in Listing 291.

Listing 291 tw-headings1.tex

\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 291 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 292.

Listing 292 tw-headings1-mod1.tex

\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 283 and also Listing 148:

• in Listing 283 the headings field is set to 1, which instructs latexindent.pl to read the fields from Listing 148, regardless of the value of indentAfterThisHeading or level;
• the default is to assume that the heading command can, optionally, be followed by a label command.

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 293 and then run

latexindent.pl -m -l textwrap1.yaml,bf-no-headings.yaml tw-headings1.tex

gives the output in Listing 294, in which text wrapping has been instructed not to happen following headings.

Listing 293 bf-no-headings.yaml

modifyLineBreaks:
    textWrapOptions:
        blocksFollow:
           headings: 0

Listing 294 tw-headings1-mod2.tex

\section{my heading}\label{mylabel1}
text to
be
wrapped from the first section
\subsection{subheading}
text to
be
wrapped from the first section

Example 12

Let’s use the sample text given in Listing 295.

Listing 295 tw-comments1.tex

% trailing comment
text to 
    be
 wrapped following first comment
% another comment
text to 
    be
 wrapped following second comment

We note that Listing 295 contains trailing comments. Upon running the command

latexindent.pl -m -l textwrap1.yaml tw-comments1.tex

then we receive the output given in Listing 296.

Listing 296 tw-comments1-mod1.tex

% trailing comment
text to be wrapped
following first
comment
% another comment
text to be wrapped
following second
comment

With reference to Listing 283 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 297 and then run

latexindent.pl -m -l textwrap1.yaml,bf-no-comments.yaml tw-comments1.tex

gives the output in Listing 298, in which text wrapping has been instructed not to happen following comments on their own line.

Listing 297 bf-no-comments.yaml

modifyLineBreaks:
    textWrapOptions:
        blocksFollow:
           commentOnPreviousLine: 0

Listing 298 tw-comments1-mod2.tex

% trailing comment
text to
be
wrapped following first comment
% another comment
text to
be
wrapped following second comment

Referencing Listing 283 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.

Example 13

Let’s use the sample text given in Listing 299.

Listing 299 tw-disp-math1.tex

text to 
    be
 wrapped before display math
 \[ y = x\]
text to 
    be
 wrapped after display math

We note that Listing 299 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 300.

Listing 300 tw-disp-math1-mod1.tex

text to be wrapped
before display math
\[ y = x\]
text to be wrapped
after display math

With reference to Listing 283 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 301 and then run

latexindent.pl -m -l textwrap1.yaml,bf-no-disp-math.yaml tw-disp-math1.tex

gives the output in Listing 302, in which text wrapping has been instructed not to happen following display math.

Listing 301 bf-no-disp-math.yaml

modifyLineBreaks:
    textWrapOptions:
        blocksFollow:
           other: 0

Listing 302 tw-disp-math1-mod2.tex

text to be wrapped
before display math
\[ y = x\]
text to
be
wrapped after display math

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 accomodate the environments that you would like to text wrap individually, as in the next example.

Example 14

Let’s use the sample text given in Listing 303.

Listing 303 tw-bf-myenv1.tex

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 303 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 304.

Listing 304 tw-bf-myenv1-mod1.tex

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 305 and then run

latexindent.pl -m -l textwrap1.yaml,tw-bf-myenv.yaml tw-bf-myenv1.tex

which gives the output in Listing 306, in which text wrapping has been implemented across the file.

Listing 305 tw-bf-myenv.yaml

modifyLineBreaks:
    textWrapOptions:
        blocksFollow:
           other: |-
             (?x)
                \\\]
                |
                \\item(?:\h|\[)
                |
                \\begin\{myenv\} # <--- new bit
                |                # <--- new bit
                \\end\{myenv\}   # <--- new bit

Listing 306 tw-bf-myenv1-mod2.tex

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

6.1.4. Text wrap: blocksBeginWith examples

We examine the blocksBeginWith field of Listing 283 with a series of examples.

Example 15

By default, text wrap blocks can begin with the characters a-z and A-Z.

If we start with the file given in Listing 307

Listing 307 tw-0-9.tex

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 308 in which text wrapping has not occured.

Listing 308 tw-0-9-mod1.tex

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 309 and running

latexindent.pl -m -l textwrap1.yaml,bb-0-9-yaml tw-0-9.tex

gives the output in Listing 310, in which text wrapping has happened.

Listing 309 bb-0-9.yaml.yaml

modifyLineBreaks:
    textWrapOptions:
        blocksBeginWith:
           0-9: 1

Listing 310 tw-0-9-mod2.tex

123 text to be
wrapped before
display math
\[ y = x\]
456 text to be
wrapped after
display math

Example 16

Let’s now use the file given in Listing 311

Listing 311 tw-bb-announce1.tex

% 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 312 in which text wrapping has not occured.

Listing 312 tw-bb-announce1-mod1.tex

% 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 313 and running

latexindent.pl -m -l textwrap1.yaml,tw-bb-announce.yaml tw-bb-announce1.tex

gives the output in Listing 314, in which text wrapping has happened.

Listing 313 tw-bb-announce.yaml

modifyLineBreaks:
    textWrapOptions:
        blocksBeginWith:
           other: '\\announce'

Listing 314 tw-bb-announce1-mod2.tex

% trailing comment
\announce{announce
	text} and text to
be wrapped before
goes here

6.1.5. Text wrap: blocksEndBefore examples

We examine the blocksEndBefore field of Listing 283 with a series of examples.

Example 17

Let’s use the sample text given in Listing 315.

Listing 315 tw-be-equation.tex

before 
equation
text
\begin{align}
  1 & 2 \\
  3 & 4
\end{align}
after 
equation
text

We note that Listing 315 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 316.

Listing 316 tw-be-equation-mod1.tex

before equation text
\begin{align}
	1 & 2 \\
	3 & 4
\end{align}
after
equation
text

With reference to Listing 283 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 317 and then run

latexindent.pl -m -l textwrap1A.yaml,tw-be-equation.yaml tw-be-equation.tex

gives the output in Listing 318, in which text wrapping has been instructed not to stop at these statements.

Listing 317 tw-be-equation.yaml

modifyLineBreaks:
    textWrapOptions:
        blocksEndBefore:
           other: 0

Listing 318 tw-be-equation-mod2.tex

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.

Example 18

The file in Listing 319 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 320.

Listing 319 tw-tc1.tex

foo %
bar

Listing 320 tw-tc1-mod1.tex

foo bar%

Example 19

The file in Listing 321 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 322.

Listing 321 tw-tc2.tex

foo%
bar

Listing 322 tw-tc2-mod1.tex

foobar%

We note that, because there is not a space before the trailing comment, that the lines have been joined without a space.

Example 20

The file in Listing 323 contains multiple trailing comments.

Running the command

latexindent.pl -m tw-tc3.tex -l textwrap1A.yaml -o=+-mod1

gives the output in Listing 324.

Listing 323 tw-tc3.tex

foo %1
bar%2
three

Listing 324 tw-tc3-mod1.tex

foo barthree%1%2

Example 21

The file in Listing 325 contains multiple trailing comments.

Running the command

latexindent.pl -m tw-tc4.tex -l textwrap1A.yaml -o=+-mod1

gives the output in Listing 326.

Listing 325 tw-tc4.tex

foo %1
bar%2
three%3

Listing 326 tw-tc4-mod1.tex

foo barthree%1%2%3

Example 22

The file in Listing 327 contains multiple trailing comments.

Running the command

latexindent.pl -m tw-tc5.tex -l textwrap1A.yaml -o=+-mod1

gives the output in Listing 328.

Listing 327 tw-tc5.tex

foo%1
bar%2
three %3

Listing 328 tw-tc5-mod1.tex

foobarthree %1%2%3

The space at the end of the text block has been preserved.

Example 23

The file in Listing 329 contains multiple trailing comments.

Running the command

latexindent.pl -m tw-tc6.tex -l textwrap1A.yaml -o=+-mod1

gives the output in Listing 330.

Listing 329 tw-tc6.tex

foo%1
bar 

Listing 330 tw-tc6-mod1.tex

foobar %1

The space at the end of the text block has been preserved.

6.1.7. 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 332 and Listing 334 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 331 and Listing 333.

Listing 331 textwrap4-mod2A.tex

He
re
is
a
li
ne
of
te
xt
.

Listing 332 textwrap2A.yaml

modifyLineBreaks:
  textWrapOptions:
    columns: 3
    huge: wrap

Listing 333 textwrap4-mod2B.tex

Here
is
a
line
of
text.

Listing 334 textwrap2B.yaml

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 335 with settings in Listing 336, and running the command

     latexindent.pl -m textwrap-ts.tex -o=+-mod1 -l tabstop.yaml

gives the code given in Listing 337.

Listing 335 textwrap-ts.tex

x       y

Listing 336 tabstop.yaml

modifyLineBreaks:
    textWrapOptions:
        columns: 80
        tabstop: 9
        multipleSpacesToSingle: 0

Listing 337 textwrap-ts-mod1.tex

x       y

You can specify separator, break and unexpand options in your settings in analogous ways to those demonstrated in Listing 334 and Listing 336, 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 338, all of which we discuss next.

Listing 338 oneSentencePerLine

    oneSentencePerLine:
        manipulateSentences: 0
        removeSentenceLineBreaks: 1
        multipleSpacesToSingle: 1
        textWrapSentences: 0   # setting to 1 disables main textWrap routine
        sentenceIndent: ""
        sentencesFollow:
            par: 1
            blankLine: 1
            fullStop: 1
            exclamationMark: 1
            questionMark: 1
            rightBrace: 1
            commentOnPreviousLine: 1
            other: 0
        sentencesBeginWith:
            A-Z: 1
            a-z: 0
            other: 0
        sentencesEndWith:
            basicFullStop: 0
            betterFullStop: 1
            exclamationMark: 1
            questionMark: 1
            other: 0

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

Listing 339 multiple-sentences.tex

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 341 and Listing 343, 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 340 and Listing 342.

Listing 340 multiple-sentences.tex using Listing 341

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.

Listing 341 manipulate-sentences.yaml

modifyLineBreaks:
    oneSentencePerLine:
        manipulateSentences: 1

Listing 342 multiple-sentences.tex using Listing 343

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.

Listing 343 keep-sen-line-breaks.yaml

modifyLineBreaks:
    oneSentencePerLine:
        manipulateSentences: 1
        removeSentenceLineBreaks: 0

Notice, in particular, that the ‘internal’ sentence line breaks in Listing 339 have been removed in Listing 340, but have not been removed in Listing 342.

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 338 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 344); 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 345); by default, this is only capital letters;
• end with a character (see Listing 346); 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.

Listing 344 sentencesFollow

        sentencesFollow:
            par: 1
            blankLine: 1
            fullStop: 1
            exclamationMark: 1
            questionMark: 1
            rightBrace: 1
            commentOnPreviousLine: 1
            other: 0

Listing 345 sentencesBeginWith

        sentencesBeginWith:
            A-Z: 1
            a-z: 0
            other: 0

Listing 346 sentencesEndWith

        sentencesEndWith:
            basicFullStop: 0
            betterFullStop: 1
            exclamationMark: 1
            questionMark: 1
            other: 0

6.2.1. sentencesFollow

Let’s explore a few of the switches in sentencesFollow; let’s start with Listing 339, and use the YAML settings given in Listing 348. Using the command

latexindent.pl multiple-sentences -m -l=sentences-follow1.yaml

we obtain the output given in Listing 347.

Listing 347 multiple-sentences.tex using Listing 348

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.

Listing 348 sentences-follow1.yaml

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 344 with the .tex file detailed in Listing 349.

Listing 349 multiple-sentences1.tex

(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 350 and Listing 351.

Listing 350 multiple-sentences1.tex using Listing 341

(Some sentences stand alone in brackets.) This is the first
sentence.
This is the; second, sentence.
This is the third sentence.

Listing 351 multiple-sentences1.tex using Listing 352

(Some sentences stand alone in brackets.)
This is the first sentence.
This is the; second, sentence.
This is the third sentence.

Listing 352 sentences-follow2.yaml

modifyLineBreaks:
    oneSentencePerLine:
        manipulateSentences: 1
        sentencesFollow:
           other: "\)"

Notice that in Listing 350 the first sentence after the ) has not been accounted for, but that following the inclusion of Listing 352, the output given in Listing 351 demonstrates that the sentence has been accounted for correctly.

6.2.2. 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 345), and we can use the other field to define sentences to begin with other characters.

Listing 353 multiple-sentences2.tex

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 354 and Listing 355.

Listing 354 multiple-sentences2.tex using Listing 341

This is the first sentence.

$a$ can
represent a
number. 7 is
at the beginning of this sentence.

Listing 355 multiple-sentences2.tex using Listing 356

This is the first sentence.

$a$ can represent a number.
7 is at the beginning of this sentence.

Listing 356 sentences-begin1.yaml

modifyLineBreaks:
    oneSentencePerLine:
        manipulateSentences: 1
        sentencesBeginWith:
            other: "\$|[0-9]"

Notice that in Listing 354, the first sentence has been accounted for but that the subsequent sentences have not. In Listing 355, all of the sentences have been accounted for, because the other field in Listing 356 has defined sentences to begin with either $ or any numeric digit, 0 to 9.

6.2.3. sentencesEndWith

Let’s return to Listing 339; we have already seen the default way in which latexindent.pl will operate on the sentences in this file in Listing 340. We can populate the other field with any character that we wish; for example, using the YAML specified in Listing 358 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 357.

Listing 357 multiple-sentences.tex using Listing 358

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.

Listing 358 sentences-end1.yaml

modifyLineBreaks:
    oneSentencePerLine:
        manipulateSentences: 1
        sentencesEndWith:
          other: "\:|\;|\,"

Listing 359 multiple-sentences.tex using Listing 360

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.

Listing 360 sentences-end2.yaml

modifyLineBreaks:
    oneSentencePerLine:
        manipulateSentences: 1
        sentencesEndWith:
          other: "\:|\;|\,"
        sentencesBeginWith:
          a-z: 1

There is a subtle difference between the output in Listing 357 and Listing 359; in particular, in Listing 357 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 360, and the associated output in Listing 359 reflects this.

Referencing Listing 346, 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 361.

Listing 361 url.tex

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

Listing 362 url.tex using Listing 341

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. and i.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 522.

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 364 gives the output in Listing 363.

Listing 363 url.tex using Listing 364

This sentence, \url{tex.
	stackexchange.com/} finishes here.Second sentence.

Listing 364 alt-full-stop1.yaml

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

6.2.4. 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 365, and run the command

latexindent.pl multiple-sentences3 -m -l=manipulate-sentences.yaml

then we obtain the output in Listing 366.

Listing 365 multiple-sentences3.tex

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.

Listing 366 multiple-sentences3.tex using Listing 341

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.

Furthermore, if sentences run across environments then, by default, the line breaks internal to the sentence will be removed. For example, if we use the .tex file in Listing 367 and run the commands

latexindent.pl multiple-sentences4 -m -l=manipulate-sentences.yaml
latexindent.pl multiple-sentences4 -m -l=keep-sen-line-breaks.yaml

then we obtain the output in Listing 368 and Listing 369.

Listing 367 multiple-sentences4.tex

This sentence 
\begin{itemize}
  \item continues
\end{itemize}
across itemize 
and finishes here.

Listing 368 multiple-sentences4.tex using Listing 341

This sentence \begin{itemize} \item continues \end{itemize} across itemize and finishes here.

Listing 369 multiple-sentences4.tex using Listing 343

This sentence
\begin{itemize}
	\item continues
\end{itemize}
across itemize
and finishes here.

Once you’ve read Section 6.3, you will know that you can accommodate the removal of internal sentence line breaks by using the YAML in Listing 371 and the command

latexindent.pl multiple-sentences4 -m -l=item-rules2.yaml

the output of which is shown in Listing 370.

Listing 370 multiple-sentences4.tex using Listing 371

This sentence
\begin{itemize}
	\item continues
\end{itemize}
across itemize and finishes here.

Listing 371 item-rules2.yaml

modifyLineBreaks:
    oneSentencePerLine:
        manipulateSentences: 1
    items:
        ItemStartsOnOwnLine: 1
    environments:
        BeginStartsOnOwnLine: 1
        BodyStartsOnOwnLine: 1
        EndStartsOnOwnLine: 1
        EndFinishesWithLineBreak: 1

6.2.5. 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 372.

Listing 372 multiple-sentences5.tex

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 374, and running the following command

latexindent.pl multiple-sentences5 -m -l=sentence-wrap1.yaml

we receive the output given in Listing 373.

Listing 373 multiple-sentences5.tex using Listing 374

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.

Listing 374 sentence-wrap1.yaml

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 346. Let’s explore this in relation to Listing 375.

Listing 375 multiple-sentences6.tex

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 376 and Listing 377.

Listing 376 multiple-sentences6-mod1.tex using Listing 374

Consider the following: \begin{itemize} \item
  firstly.
\item secondly.
\end{itemize}

Listing 377 multiple-sentences6-mod2.tex using Listing 374 and no sentence indentation

Consider the following: \begin{itemize} \item
	      firstly.
	\item secondly.
\end{itemize}

We note that Listing 376 the itemize code block has not been indented appropriately. This is because the oneSentencePerLine has been instructed to store sentences (because Listing 374); each sentence is then searched for code blocks.

We can tweak the settings in Listing 346 to ensure that full stops are not followed by item commands, and that the end of sentences contains \end{itemize} as in Listing 378 (if you intend to use this, ensure that you remove the line breaks from the other field).

Listing 378 itemize.yaml

modifyLineBreaks:
    oneSentencePerLine:
        manipulateSentences: 1
        sentencesEndWith:
            betterFullStop: 0
            other: '(?:\.\)(?!\h*[a-z]))|(?:(?<!(?:(?:e\.g)
                    |(?:i\.e)|(?:etc))))\.(?:\h*\R*(?:\\end\{itemize\})?)
                    (?!(?:[a-z]|[A-Z]|\-|\,|[0-9]|(?:(?:\R|\h)*\\item)))'

Upon running

latexindent.pl multiple-sentences6 -m -l=sentence-wrap1.yaml,itemize.yaml

we receive the output in Listing 379.

Listing 379 multiple-sentences6-mod3.tex using Listing 374 and Listing 378

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.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 preserveBlankLines is set to 0);

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 380; note that it contains global settings (immediately after the environments field) and that per-name settings are also allowed – in the case of Listing 380, settings for equation* have been specified for demonstration. Note that all poly-switches are off (set to 0) by default.

Listing 380 environments

    environments:
        BeginStartsOnOwnLine: 0
        BodyStartsOnOwnLine: 0
        EndStartsOnOwnLine: 0
        EndFinishesWithLineBreak: 0
        equation*:
            BeginStartsOnOwnLine: 0
            BodyStartsOnOwnLine: 0
            EndStartsOnOwnLine: 0
            EndFinishesWithLineBreak: 0

Let’s begin with the simple example given in Listing 381; note that we have annotated key parts of the file using ♠, ♥, ◆ and ♣, these will be related to fields specified in Listing 380.

Listing 381 env-mlb1.tex

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 382 and Listing 383, and in particular, let’s allow each of them in turn to take a value of \(1\).

Listing 382 env-mlb1.yaml

modifyLineBreaks:
    environments:
        BeginStartsOnOwnLine: 1

Listing 383 env-mlb2.yaml

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 384 and Listing 385 respectively.

Listing 384 env-mlb.tex using Listing 382

before words
\begin{myenv}body of myenv\end{myenv} after words

Listing 385 env-mlb.tex using Listing 383

before words \begin{myenv}
	body of myenv\end{myenv} after words

There are a couple of points to note:

• in Listing 384 a line break has been added at the point denoted by ♠ in Listing 381; no other line breaks have been changed;
• in Listing 385 a line break has been added at the point denoted by ♥ in Listing 381; furthermore, note that the body of myenv has received the appropriate (default) indentation.

Let’s now change each of the 1 values in Listing 382 and Listing 383 so that they are \(2\) and save them into env-mlb3.yaml and env-mlb4.yaml respectively (see Listing 386 and Listing 387).

Listing 386 env-mlb3.yaml

modifyLineBreaks:
    environments:
        BeginStartsOnOwnLine: 2

Listing 387 env-mlb4.yaml

modifyLineBreaks:
    environments:
        BodyStartsOnOwnLine: 2

Upon running commands analogous to the above, we obtain Listing 388 and Listing 389.

Listing 388 env-mlb.tex using Listing 386

before words%
\begin{myenv}body of myenv\end{myenv} after words

Listing 389 env-mlb.tex using Listing 387

before words \begin{myenv}%
	body of myenv\end{myenv} after words

Note that line breaks have been added as in Listing 384 and Listing 385, 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 382 and Listing 383 so that they are \(3\) and save them into env-mlb5.yaml and env-mlb6.yaml respectively (see Listing 390 and Listing 391).

Listing 390 env-mlb5.yaml

modifyLineBreaks:
    environments:
        BeginStartsOnOwnLine: 3

Listing 391 env-mlb6.yaml

modifyLineBreaks:
    environments:
        BodyStartsOnOwnLine: 3

Upon running commands analogous to the above, we obtain Listing 392 and Listing 393.

Listing 392 env-mlb.tex using Listing 390

before words

\begin{myenv}body of myenv\end{myenv} after words

Listing 393 env-mlb.tex using Listing 391

before words \begin{myenv}

	body of myenv\end{myenv} after words

Note that line breaks have been added as in Listing 384 and Listing 385, 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 390 and Listing 391 so that they are \(4\) and save them into env-beg4.yaml and env-body4.yaml respectively (see Listing 394 and Listing 395).

Listing 394 env-beg4.yaml

modifyLineBreaks:
    environments:
        BeginStartsOnOwnLine: 4

Listing 395 env-body4.yaml

modifyLineBreaks:
    environments:
        BodyStartsOnOwnLine: 4

We will demonstrate this poly-switch value using the code in Listing 396.

Listing 396 env-mlb1.tex

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 397 and Listing 398.

Listing 397 env-mlb1.tex using Listing 394

before words

\begin{myenv}
	body of myenv
\end{myenv}
after words

Listing 398 env-mlb1.tex using Listing 395

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:

1. in Listing 397 a blank line has been inserted before the \begin statement, even though the \begin statement was already on its own line;
2. in Listing 398 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 using EndStartsOnOwnLine and EndFinishesWithLineBreak

Let’s explore EndStartsOnOwnLine and EndFinishesWithLineBreak in Listing 399 and Listing 400, and in particular, let’s allow each of them in turn to take a value of \(1\).

Listing 399 env-mlb7.yaml

modifyLineBreaks:
    environments:
        EndStartsOnOwnLine: 1

Listing 400 env-mlb8.yaml

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 401 and Listing 402.

Listing 401 env-mlb.tex using Listing 399

before words \begin{myenv}body of myenv
\end{myenv} after words

Listing 402 env-mlb.tex using Listing 400

before words \begin{myenv}body of myenv\end{myenv}
after words

There are a couple of points to note:

• in Listing 401 a line break has been added at the point denoted by ◆ in Listing 381; no other line breaks have been changed and the \end{myenv} statement has not received indentation (as intended);
• in Listing 402 a line break has been added at the point denoted by ♣ in Listing 381.

Let’s now change each of the 1 values in Listing 399 and Listing 400 so that they are \(2\) and save them into env-mlb9.yaml and env-mlb10.yaml respectively (see Listing 403 and Listing 404).

Listing 403 env-mlb9.yaml

modifyLineBreaks:
    environments:
        EndStartsOnOwnLine: 2

Listing 404 env-mlb10.yaml

modifyLineBreaks:
    environments:
        EndFinishesWithLineBreak: 2

Upon running commands analogous to the above, we obtain Listing 405 and Listing 406.

Listing 405 env-mlb.tex using Listing 403

before words \begin{myenv}body of myenv%
\end{myenv} after words

Listing 406 env-mlb.tex using Listing 404

before words \begin{myenv}body of myenv\end{myenv}%
after words

Note that line breaks have been added as in Listing 401 and Listing 402, 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 399 and Listing 400 so that they are \(3\) and save them into env-mlb11.yaml and env-mlb12.yaml respectively (see Listing 407 and Listing 408).

Listing 407 env-mlb11.yaml

modifyLineBreaks:
    environments:
        EndStartsOnOwnLine: 3

Listing 408 env-mlb12.yaml

modifyLineBreaks:
    environments:
        EndFinishesWithLineBreak: 3

Upon running commands analogous to the above, we obtain Listing 409 and Listing 410.

Listing 409 env-mlb.tex using Listing 407

before words \begin{myenv}body of myenv

\end{myenv} after words

Listing 410 env-mlb.tex using Listing 408

before words \begin{myenv}body of myenv\end{myenv} 

after words

Note that line breaks have been added as in Listing 401 and Listing 402, and that a blank line has been added after the line break.

Let’s now change each of the 1 values in Listing 407 and Listing 408 so that they are \(4\) and save them into env-end4.yaml and env-end-f4.yaml respectively (see Listing 411 and Listing 412).

Listing 411 env-end4.yaml

modifyLineBreaks:
    environments:
        EndStartsOnOwnLine: 4

Listing 412 env-end-f4.yaml

modifyLineBreaks:
    environments:
        EndFinishesWithLineBreak: 4

We will demonstrate this poly-switch value using the code from Listing 396.

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 413 and Listing 414.

Listing 413 env-mlb1.tex using Listing 411

before words
\begin{myenv}
	body of myenv

\end{myenv}
after words

Listing 414 env-mlb1.tex using Listing 412

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:

1. in Listing 413 a blank line has been inserted before the \end statement, even though the \end statement was already on its own line;
2. in Listing 414 a blank line has been inserted after the \end statement, 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 415 using poly-switch values of 1, 2, or 3, it will be left unchanged.

Listing 415 env-mlb2.tex

before words 
\begin{myenv}
  body of myenv
\end{myenv} 
after words

Listing 416 env-mlb3.tex

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 397 and Listing 398 and Listing 413 and Listing 414.

In contrast, the output from processing the file in Listing 416 will vary depending on the poly-switches used; in Listing 417 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 418 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 416 and by setting the other poly-switches considered so far to 2 in turn.

Listing 417 env-mlb3.tex using Listing 383

before words
\begin{myenv}
	%
	body of myenv%
\end{myenv}% 
after words

Listing 418 env-mlb3.tex using Listing 387

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 380, 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 419, noting in particular the positions of the line break highlighters, ♠, ♥, ◆ and ♣, together with the associated YAML files in Listing 420 – Listing 423.

Listing 419 env-mlb4.tex

before words♠
\begin{myenv}♥
body of myenv◆
\end{myenv}♣
after words

After

Listing 420 env-mlb13.yaml

modifyLineBreaks:
    environments:
        BeginStartsOnOwnLine: -1

Listing 421 env-mlb14.yaml

modifyLineBreaks:
    environments:
        BodyStartsOnOwnLine: -1

Listing 422 env-mlb15.yaml

modifyLineBreaks:
    environments:
        EndStartsOnOwnLine: -1

Listing 423 env-mlb16.yaml

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 424 – Listing 427.

Listing 424 env-mlb4.tex using Listing 420

before words\begin{myenv}
	body of myenv
\end{myenv}
after words

Listing 425 env-mlb4.tex using Listing 421

before words
\begin{myenv}body of myenv
\end{myenv}
after words

Listing 426 env-mlb4.tex using Listing 422

before words
\begin{myenv}
	body of myenv\end{myenv}
after words

Listing 427 env-mlb4.tex using Listing 423

before words
\begin{myenv}
	body of myenv
\end{myenv}after words

Notice that in:

• Listing 424 the line break denoted by ♠ in Listing 419 has been removed;
• Listing 425 the line break denoted by ♥ in Listing 419 has been removed;
• Listing 426 the line break denoted by ◆ in Listing 419 has been removed;
• Listing 427 the line break denoted by ♣ in Listing 419 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 420 – Listing 423 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 381.

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; let’s consider the file shown in Listing 428, which highlights trailing spaces.

Listing 428 env-mlb5.tex

before words   ♠
\begin{myenv}           ♥
body of myenv      ◆
\end{myenv}     ♣
after words

The

Listing 429 removeTWS-before.yaml

removeTrailingWhitespace:
    beforeProcessing: 1

output from the following commands

latexindent.pl -m env-mlb5.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,env-mlb16.yaml
latexindent.pl -m env-mlb5.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,env-mlb16.yaml,removeTWS-before.yaml

is shown, respectively, in Listing 430 and Listing 431; note that the trailing horizontal white space has been preserved (by default) in Listing 430, while in Listing 431, it has been removed using the switch specified in Listing 429.

Listing 430 env-mlb5.tex using Listing 424 – Listing 427

before words   \begin{myenv}           body of myenv      \end{myenv}     after words

Listing 431 env-mlb5.tex using Listing 424 – Listing 427 and Listing 429

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 432, which contains blank lines.

Listing 432 env-mlb6.tex

before words♠


\begin{myenv}♥


body of myenv◆


\end{myenv}♣

after words

Upon

Listing 433 UnpreserveBlankLines.yaml

modifyLineBreaks:
    preserveBlankLines: 0

running the following commands

latexindent.pl -m env-mlb6.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,env-mlb16.yaml
latexindent.pl -m env-mlb6.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,env-mlb16.yaml,UnpreserveBlankLines.yaml

we receive the respective outputs in Listing 434 and Listing 435. In Listing 434 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 435, we have allowed the poly-switches to remove blank lines because, in Listing 433, we have set preserveBlankLines to 0.

Listing 434 env-mlb6.tex using Listing 424 – Listing 427

before words

\begin{myenv}

	body of myenv

\end{myenv}

after words

Listing 435 env-mlb6.tex using Listing 424 – Listing 427 and Listing 433

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

Listing 436 env-mlb7.tex

\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.yaml,env-mlb14.yaml,UnpreserveBlankLines.yaml

we receive the outputs given in Listing 437 and Listing 438.

Listing 437 env-mlb7-preserve.tex

\begin{one} one text \end{one} 

\begin{two} two text \end{two}

Listing 438 env-mlb7-no-preserve.tex

\begin{one} one text \end{one} \begin{two} two text \end{two}

Notice that in:

• Listing 437 that \end{one} has added a blank line, because of the value of EndFinishesWithLineBreak in Listing 408, and even though the line break ahead of \begin{two} should have been removed (because of BeginStartsOnOwnLine in Listing 420), the blank line has been preserved by default;
• Listing 438, by contrast, has had the additional line-break removed, because of the settings in Listing 433.

6.3.2. Poly-switches for double back slash

With reference to lookForAlignDelims (see Listing 55) you can specify poly-switches to dictate the line-break behaviour of double back slashes in environments (Listing 57), commands (Listing 91), or special code blocks (Listing 130). Note that for these poly-switches to take effect, the name of the code block must necessarily be specified within lookForAlignDelims (Listing 55); we will demonstrate this in what follows.

Consider the code given in Listing 439.

Listing 439 tabular3.tex

\begin{tabular}{cc}
 1 & 2 ★\\□ 3 & 4 ★\\□
\end{tabular}

Referencing Listing 439:

• DBS stands for double back slash;
• line breaks ahead of the double back slash are annotated by ★, and are controlled by DBSStartsOnOwnLine;
• line breaks after the double back slash are annotated by □, and are controlled by DBSFinishesWithLineBreak.

Let’s explore each of these in turn.

6.3.2.1. Double back slash starts on own line

We explore DBSStartsOnOwnLine (★ in Listing 439); starting with the code in Listing 439, together with the YAML files given in Listing 441 and Listing 443 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 440 and Listing 442.

Listing 440 tabular3.tex using Listing 441

\begin{tabular}{cc}
	1 & 2
	\\ 3 & 4
	\\
\end{tabular}

Listing 441 DBS1.yaml

modifyLineBreaks:
    environments:
        DBSStartsOnOwnLine: 1

Listing 442 tabular3.tex using Listing 443

\begin{tabular}{cc}
	1 & 2 %
	\\ 3 & 4%
	\\
\end{tabular}

Listing 443 DBS2.yaml

modifyLineBreaks:
    environments:
        tabular:
            DBSStartsOnOwnLine: 2

We note that

• Listing 441 specifies DBSStartsOnOwnLine for every environment (that is within lookForAlignDelims, Listing 58); the double back slashes from Listing 439 have been moved to their own line in Listing 440;
• Listing 443 specifies DBSStartsOnOwnLine on a per-name basis for tabular (that is within lookForAlignDelims, Listing 58); the double back slashes from Listing 439 have been moved to their own line in Listing 442, having added comment symbols before moving them.

6.3.2.2. Double back slash finishes with line break

Let’s now explore DBSFinishesWithLineBreak (□ in Listing 439); starting with the code in Listing 439, together with the YAML files given in Listing 445 and Listing 447 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 444 and Listing 446.

Listing 444 tabular3.tex using Listing 445

\begin{tabular}{cc}
	1 & 2 \\
	3 & 4 \\
\end{tabular}

Listing 445 DBS3.yaml

modifyLineBreaks:
    environments:
        DBSFinishesWithLineBreak: 1

Listing 446 tabular3.tex using Listing 447

\begin{tabular}{cc}
	1 & 2 \\%
	3 & 4 \\
\end{tabular}

Listing 447 DBS4.yaml

modifyLineBreaks:
    environments:
        tabular:
            DBSFinishesWithLineBreak: 2

We note that

• Listing 445 specifies DBSFinishesWithLineBreak for every environment (that is within lookForAlignDelims, Listing 58); the code following the double back slashes from Listing 439 has been moved to their own line in Listing 444;
• Listing 447 specifies DBSFinishesWithLineBreak on a per-name basis for tabular (that is within lookForAlignDelims, Listing 58); the first double back slashes from Listing 439 have moved code following them to their own line in Listing 446, having added comment symbols before moving them; the final double back slashes have not added a line break as they are at the end of the body within the code block.

6.3.2.3. Double back slash poly-switches for specialBeginEnd

Let’s explore the double back slash poly-switches for code blocks within specialBeginEnd code blocks (Listing 128); we begin with the code within Listing 448.

Listing 448 special4.tex

\< a& =b  \\ & =c\\ & =d\\ & =e \>

Upon using the YAML settings in Listing 450, and running the command

latexindent.pl -m special4.tex -l DBS5.yaml

then we receive the output given in Listing 449.

Listing 449 special4.tex using Listing 450

\<
	a & =b \\
	  & =c \\
	  & =d \\
	  & =e %
\>

Listing 450 DBS5.yaml

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 450 we have specified cmhMath within lookForAlignDelims; without this, the double back slash poly-switches would be ignored for this code block;
• the DBSFinishesWithLineBreak poly-switch has controlled the line breaks following the double back slashes;
• the SpecialEndStartsOnOwnLine poly-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 back slash poly-switches for optional and mandatory arguments

For clarity, we provide a demonstration of controlling the double back slash poly-switches for optional and mandatory arguments. We begin with the code in Listing 451.

Listing 451 mycommand2.tex

\mycommand [
	1&2   &3\\ 4&5&6]{
7&8   &9\\ 10&11&12
}

Upon using the YAML settings in Listing 453 and Listing 455, 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 452 and Listing 454.

Listing 452 mycommand2.tex using Listing 453

\mycommand [
	1 & 2 & 3 %
	\\%
	4 & 5 & 6]{
	7 & 8 & 9 \\ 10&11&12
}

Listing 453 DBS6.yaml

lookForAlignDelims:
    mycommand: 1
modifyLineBreaks:
    optionalArguments:
        DBSStartsOnOwnLine: 2
        DBSFinishesWithLineBreak: 2

Listing 454 mycommand2.tex using Listing 455

\mycommand [
	1&2   &3\\ 4&5&6]{
	7  & 8  & 9  %
	\\%
	10 & 11 & 12
}

Listing 455 DBS7.yaml

lookForAlignDelims:
    mycommand: 1
modifyLineBreaks:
    mandatoryArguments:
        DBSStartsOnOwnLine: 2
        DBSFinishesWithLineBreak: 2

6.3.2.5. Double back slash optional square brackets

The pattern matching for the double back slash 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 456

Listing 456 pmatrix3.tex

\begin{pmatrix}
1 & 2 \\[2pt] 3 & 4 \\ [ 3 ex] 5&6\\[    4  pt   ] 7 & 8 
\end{pmatrix}

and running the following command, using Listing 445,

latexindent.pl -m pmatrix3.tex -l DBS3.yaml

then we receive the output given in Listing 457.

Listing 457 pmatrix3.tex using Listing 445

\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 back slash by exploring the fine tuning field detailed in Listing 522.

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 92) can not be modified using latexindent.pl. However, there are two poly-switches available for verbatim code blocks: environments (Listing 34), commands (Listing 35) and specialBeginEnd (Listing 141).

Table 3 Poly-switch mappings for all code-block types

Code block	Sample
environment	before words♠	♠	BeginStartsOnOwnLine
	\begin{myenv}♥	♥	BodyStartsOnOwnLine
	body of myenv◆	◆	EndStartsOnOwnLine
	\end{myenv}♣	♣	EndFinishesWithLineBreak
	after words
ifelsefi	before words♠	♠	IfStartsOnOwnLine
	\if...♥	♥	BodyStartsOnOwnLine
	body of if/or statement▲	▲	OrStartsOnOwnLine
	\or▼	▼	OrFinishesWithLineBreak
	body of if/or statement★	★	ElseStartsOnOwnLine
	\else□	□	ElseFinishesWithLineBreak
	body of else statement◆	◆	FiStartsOnOwnLine
	\fi♣	♣	FiFinishesWithLineBreak
	after words
optionalArguments	...♠	♠	LSqBStartsOnOwnLine [1]
	[♥	♥	OptArgBodyStartsOnOwnLine
	value before comma★,	★	CommaStartsOnOwnLine
	□	□	CommaFinishesWithLineBreak
	end of body of opt arg◆	◆	RSqBStartsOnOwnLine
	]♣	♣	RSqBFinishesWithLineBreak
	...
mandatoryArguments	...♠	♠	LCuBStartsOnOwnLine [2]
	{♥	♥	MandArgBodyStartsOnOwnLine
	value before comma★,	★	CommaStartsOnOwnLine
	□	□	CommaFinishesWithLineBreak
	end of body of mand arg◆	◆	RCuBStartsOnOwnLine
	}♣	♣	RCuBFinishesWithLineBreak
	...
commands	before words♠	♠	CommandStartsOnOwnLine
	\mycommand♥	♥	CommandNameFinishesWithLineBreak
	<arguments>
namedGroupingBracesBrackets	before words♠	♠	NameStartsOnOwnLine
	myname♥	♥	NameFinishesWithLineBreak
	<braces/brackets>
keyEqualsValuesBracesBrackets	before words♠	♠	KeyStartsOnOwnLine
	key●=♥	●	EqualsStartsOnOwnLine
	<braces/brackets>	♥	EqualsFinishesWithLineBreak
items	before words♠	♠	ItemStartsOnOwnLine
	\item♥	♥	ItemFinishesWithLineBreak
	...
specialBeginEnd	before words♠	♠	SpecialBeginStartsOnOwnLine
	\[♥	♥	SpecialBodyStartsOnOwnLine
	body of special/middle★	★	SpecialMiddleStartsOnOwnLine
	\middle□	□	SpecialMiddleFinishesWithLineBreak
	body of special/middle ◆	◆	SpecialEndStartsOnOwnLine
	\]♣	♣	SpecialEndFinishesWithLineBreak
	after words
verbatim	before words♠\begin{verbatim}	♠	VerbatimBeginStartsOnOwnLine
	body of verbatim \end{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 458 and the YAML settings in Listing 460; with reference to Table 3, the key CommandNameFinishesWithLineBreak is an alias for BodyStartsOnOwnLine.

Listing 458 mycommand1.tex

\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 459; note that the second mandatory argument beginning brace { has had its leading line break removed, but that the first brace has not.

Listing 459 mycommand1.tex using Listing 460

\mycommand
{
	mand arg text
	mand arg text}{
	mand arg text
	mand arg text}

Listing 460 mycom-mlb1.yaml

modifyLineBreaks:
    commands:
        CommandNameFinishesWithLineBreak: 0
    mandatoryArguments:
        LCuBStartsOnOwnLine: -1

Now let’s change the YAML file so that it is as in Listing 462; upon running the analogous command to that given above, we obtain Listing 461; both beginning braces { have had their leading line breaks removed.

Listing 461 mycommand1.tex using Listing 462

\mycommand{
	mand arg text
	mand arg text}{
	mand arg text
	mand arg text}

Listing 462 mycom-mlb2.yaml

modifyLineBreaks:
    commands:
        CommandNameFinishesWithLineBreak: -1
    mandatoryArguments:
        LCuBStartsOnOwnLine: -1

Now let’s change the YAML file so that it is as in Listing 464; upon running the analogous command to that given above, we obtain Listing 463.

Listing 463 mycommand1.tex using Listing 464

\mycommand
{
	mand arg text
	mand arg text}
{
	mand arg text
	mand arg text}

Listing 464 mycom-mlb3.yaml

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; if we use the example from Listing 458, and consider the YAML settings given in Listing 466. The output from running

latexindent.pl -m -l=mycom-mlb4.yaml mycommand1.tex

is given in Listing 466.

Listing 465 mycommand1.tex using Listing 466

\mycommand
{
	mand arg text
	mand arg text}{
	mand arg text
	mand arg text}

Listing 466 mycom-mlb4.yaml

modifyLineBreaks:
    mandatoryArguments:
        LCuBStartsOnOwnLine: -1
        RCuBFinishesWithLineBreak: 1

Studying Listing 466, we see that the two poly-switches are at opposition with one another:

• on the one hand, LCuBStartsOnOwnLine should not start on its own line (as poly-switch is set to \(-1\));
• on the other hand, RCuBFinishesWithLineBreak should finish with a line break.

So, which should win the conflict? As demonstrated in Listing 465, 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 468; upon running the command

latexindent.pl -m -l=mycom-mlb5.yaml mycommand1.tex

we obtain the output given in Listing 467.

Listing 467 mycommand1.tex using Listing 468

\mycommand
{
	mand arg text
	mand arg text}
{
	mand arg text
	mand arg text}

Listing 468 mycom-mlb5.yaml

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 470, which give associated output in Listing 469.

Listing 469 mycommand1.tex using Listing 470

\mycommand
{
	mand arg text
	mand arg text}%
{
	mand arg text
	mand arg text}

Listing 470 mycom-mlb6.yaml

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 (RCuBFinishesWithLineBreak set to \(-1\));
• while processing the second argument, latexindent.pl finds that it does not begin on its own line, and so because LCuBStartsOnOwnLine is 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 471, noting that it contains nested environments.

Listing 471 nested-env.tex

\begin{one}
one text
\begin{two}
two text
\end{two}
\end{one}

Let’s use the YAML settings given in Listing 473, which upon running the command

latexindent.pl -m -l=nested-env-mlb1.yaml nested-env.tex

gives the output in Listing 472.

Listing 472 nested-env.tex using Listing 473

\begin{one}
	one text
	\begin{two}
		two text\end{two}\end{one}

Listing 473 nested-env-mlb1.yaml

modifyLineBreaks:
    environments:
        EndStartsOnOwnLine: -1
        EndFinishesWithLineBreak: 1

In Listing 472, 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:

1. 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 471, the two environment is found before the one environment; if the -m switch is active, then during this phase:
   • line breaks at the beginning of the body can be added (if BodyStartsOnOwnLine is \(1\) or \(2\)) or removed (if BodyStartsOnOwnLine is \(-1\));
   • line breaks at the end of the body can be added (if EndStartsOnOwnLine is \(1\) or \(2\)) or removed (if EndStartsOnOwnLine is \(-1\));
   • line breaks after the end statement can be added (if EndFinishesWithLineBreak is \(1\) or \(2\)).
2. Phase 2: indentation, in which white space is added to the begin, body, and end statements;
3. 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 begin statements can be added or removed (depending upon BeginStartsOnOwnLine);
   • line breaks after end statements can be removed but NOT added (see EndFinishesWithLineBreak).

With reference to Listing 472, this means that during Phase 1:

• the two environment is found first, and the line break ahead of the \end{two} statement is removed because EndStartsOnOwnLine is set to \(-1\). Importantly, because, at this stage, \end{two} does finish with a line break, EndFinishesWithLineBreak causes no action.
• next, the one environment is found; the line break ahead of \end{one} is removed because EndStartsOnOwnLine is 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 475; upon running the command

latexindent.pl -m -l=nested-env-mlb2.yaml nested-env.tex

we obtain the output given in Listing 474.

Listing 474 nested-env.tex using Listing 475

\begin{one}
	one text
	\begin{two}
		two text
	\end{two}\end{one}

Listing 475 nested-env-mlb2.yaml

modifyLineBreaks:
    environments:
        EndStartsOnOwnLine: 1
        EndFinishesWithLineBreak: -1

During Phase 1:

• the two environment is found first, and the line break ahead of the \end{two} statement is not changed because EndStartsOnOwnLine is set to \(1\). Importantly, because, at this stage, \end{two} does finish with a line break, EndFinishesWithLineBreak causes no action.
• next, the one environment 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.

[1]	LSqB stands for Left Square Bracket

[2]	LCuB stands for Left Curly Brace