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

Listing 316 modifyLineBreaks

modifyLineBreaks:
  preserveBlankLines: 1                 # 0/1
  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.

Example 78

As an example, Listing 317 shows a sample file with blank lines; upon running

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

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

Listing 317 mlb1.tex

before blank line

after blank line

after blank line

Listing 318 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 319.

Listing 319 textWrapOptions

  textWrapOptions:
    columns: 0
    multipleSpacesToSingle: 1
    removeBlockLineBreaks: 1
    when: before                        # before/after
    comments:
      wrap: 0                           # 0/1
      inheritLeadingSpace: 0            # 0/1
    blocksFollow:
      headings: 1                       # 0/1
      commentOnPreviousLine: 1          # 0/1
      par: 1                            # 0/1
      blankLine: 1                      # 0/1
      verbatim: 1                       # 0/1
      filecontents: 1                   # 0/1
      other: \\\]|\\item(?:\h|\[)       # regex
    blocksBeginWith:
      A-Z: 1                            # 0/1
      a-z: 1                            # 0/1
      0-9: 0                            # 0/1
      other: 0                          # regex
    blocksEndBefore:
      commentOnOwnLine: 1               # 0/1
      verbatim: 1                       # 0/1
      filecontents: 1                   # 0/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:

the default value of columns is 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 before this means that, including indentation, you may receive a column width wider than that which you specify in columns, and in which case you probably wish to explore after in Section 6.1.7;
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
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;
setting columns to $-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 removeBlockLineBreaks is set to 1; switch it to 0 if you wish to change this;
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 357);
2. multiple trailing comments will be connected at the end of the text wrap block (see Listing 361);
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 363);
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

Example 79

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

Listing 320 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 322 and then run the command

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

then we receive the output given in Listing 321.

Listing 321 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 322 textwrap1.yaml

modifyLineBreaks:
    textWrapOptions:
        columns: 20

Example 80

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 321 and using the settings in Listing 323

Listing 323 textwrap1A.yaml

modifyLineBreaks:
    textWrapOptions:
        columns: -1

and running

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

gives the output in Listing 324.

Listing 324 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 81

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 326

Using the settings in Listing 326 and running

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

gives the output in Listing 325.

Listing 325 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.

Listing 326 textwrap1B.yaml

modifyLineBreaks:
    textWrapOptions:
        columns: 20
        multipleSpacesToSingle: 0

We note that in Listing 325 the multiple spaces have not been condensed into single spaces.

6.1.3. Text wrap: `blocksFollow` examples

We examine the blocksFollow field of Listing 319.

Example 82

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

Listing 327 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 327 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 328.

Listing 328 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 319 and also Listing 178:

in Listing 319 the headings field is set to 1, which instructs latexindent.pl to read the fields from Listing 178, 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 330 and then run

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

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

Listing 329 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

Listing 330 bf-no-headings.yaml

modifyLineBreaks:
    textWrapOptions:
        blocksFollow:
           headings: 0

Example 83

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

Listing 331 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 331 contains trailing comments. Upon running the command

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

then we receive the output given in Listing 332.

Listing 332 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 319 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 334 and then run

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

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

Listing 333 tw-comments1-mod2.tex

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

Listing 334 bf-no-comments.yaml

modifyLineBreaks:
    textWrapOptions:
        blocksFollow:
           commentOnPreviousLine: 0

Referencing Listing 319 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 84

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

Listing 335 tw-disp-math1.tex

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

We note that Listing 335 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 336.

Listing 336 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 319 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 338 and then run

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

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

Listing 337 tw-disp-math1-mod2.tex

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

Listing 338 bf-no-disp-math.yaml

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.

Example 85

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

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

Listing 340 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 342 and then run

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

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

Listing 341 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

Listing 342 tw-bf-myenv.yaml

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 319 with a series of examples.

Example 86

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

If we start with the file given in Listing 343

Listing 343 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 344 in which text wrapping has not occurred.

Listing 344 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 346 and running

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

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

Listing 345 tw-0-9-mod2.tex

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

Listing 346 bb-0-9.yaml.yaml

modifyLineBreaks:
    textWrapOptions:
        blocksBeginWith:
           0-9: 1

Example 87

Let’s now use the file given in Listing 347

Listing 347 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 348 in which text wrapping has not occurred.

Listing 348 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 350 and running

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

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

Listing 349 tw-bb-announce1-mod2.tex

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

Listing 350 tw-bb-announce.yaml

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

6.1.5. Text wrap: `blocksEndBefore` examples

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

Example 88

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

Listing 351 tw-be-equation.tex

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

We note that Listing 351 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 352.

Listing 352 tw-be-equation-mod1.tex

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

With reference to Listing 319 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 353 and then run

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

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

Listing 353 tw-be-equation.yaml

modifyLineBreaks:
    textWrapOptions:
        blocksEndBefore:
           other: 0

Listing 354 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 89

The file in Listing 355 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 356.

Listing 355 tw-tc1.tex

foo %
bar

Listing 356 tw-tc1-mod1.tex

foo bar%

Example 90

The file in Listing 357 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 358.

Listing 357 tw-tc2.tex

foo%
bar

Listing 358 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 91

The file in Listing 359 contains multiple trailing comments.

Running the command

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

gives the output in Listing 360.

Listing 359 tw-tc3.tex

foo %1
bar%2
three

Listing 360 tw-tc3-mod1.tex

foo barthree%1%2

Example 92

The file in Listing 361 contains multiple trailing comments.

Running the command

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

gives the output in Listing 362.

Listing 361 tw-tc4.tex

foo %1
bar%2
three%3

Listing 362 tw-tc4-mod1.tex

foo barthree%1%2%3

Example 93

The file in Listing 363 contains multiple trailing comments.

Running the command

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

gives the output in Listing 364.

Listing 363 tw-tc5.tex

foo%1
bar%2
three %3

Listing 364 tw-tc5-mod1.tex

foobarthree %1%2%3

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

Example 94

The file in Listing 365 contains multiple trailing comments.

Running the command

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

gives the output in Listing 366.

Listing 365 tw-tc6.tex

foo%1
bar 

Listing 366 tw-tc6-mod1.tex

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:

before means it is likely that the columns of wrapped text may exceed the value specified in columns;
after means it columns of wrapped text should not exceed the value specified in columns.

We demonstrate this in the following examples. See also Section 6.2.8.

Example 95

Let’s begin with the file in Listing 367.

Listing 367 textwrap8.tex

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 369 and running the command

latexindent.pl textwrap8.tex -o=+-mod1.tex -l=tw-before1.yaml -m

gives the output given in Listing 368.

Listing 368 textwrap8-mod1.tex

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

Listing 369 tw-before1.yaml

defaultIndent: '  '

modifyLineBreaks:
    textWrapOptions:
        columns: 35
        when: before  # <!-------
        blocksFollow:
          other: \\begin\{myenv\}

We note that, in Listing 368, that the wrapped text has exceeded the specified value of columns (35) given in Listing 369. We can affect this by changing when; we explore this next.

Example 96

We continue working with Listing 367.

Using the settings given in Listing 371 and running the command

latexindent.pl textwrap8.tex -o=+-mod2.tex -l=tw-after1.yaml -m

gives the output given in Listing 370.

Listing 370 textwrap8-mod2.tex

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

Listing 371 tw-after1.yaml

defaultIndent: '  '

modifyLineBreaks:
    textWrapOptions:
        columns: 35
        when: after   # <!-------
        blocksFollow:
          other: \\begin\{myenv\}

We note that, in Listing 370, that the wrapped text has obeyed the specified value of columns (35) given in Listing 371.

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.

Example 97

We use the file in Listing 372 which contains a trailing comment block.

Listing 372 textwrap9.tex

My first sentence
% first comment
%   second
%third comment
%     fourth

Using the settings given in Listing 374 and running the command

latexindent.pl textwrap9.tex -o=+-mod1.tex -l=wrap-comments1.yaml -m

gives the output given in Listing 373.

Listing 373 textwrap9-mod1.tex

My first sentence
% first comment second third
% comment fourth
----|----|----|----|----|----|----|----|
   5   10   15   20   25   30   35   40

Listing 374 wrap-comments1.yaml

modifyLineBreaks:
  textWrapOptions:
    columns: 35
    comments: 
      wrap: 1  #<!-------

We note that, in Listing 373, that the comments have been combined and wrapped because of the annotated line specified in Listing 374.

Example 98

We use the file in Listing 375 which contains a trailing comment block.

Listing 375 textwrap10.tex

My first sentence
%    first comment
%   second
%third comment
%     fourth

Using the settings given in Listing 377 and running the command

latexindent.pl textwrap10.tex -o=+-mod1.tex -l=wrap-comments1.yaml -m

gives the output given in Listing 376.

Listing 376 textwrap10-mod1.tex

My first sentence
% first comment second third
% comment fourth
----|----|----|----|----|----|----|----|
   5   10   15   20   25   30   35   40

Listing 377 wrap-comments1.yaml

modifyLineBreaks:
  textWrapOptions:
    columns: 35
    comments: 
      wrap: 1  #<!-------

We note that, in Listing 376, that the comments have been combined and wrapped because of the annotated line specified in Listing 377, and that the space from the leading comment has not been inherited; we will explore this further in the next example.

Example 99

We continue to use the file in Listing 375.

Using the settings given in Listing 379 and running the command

latexindent.pl textwrap10.tex -o=+-mod2.tex -l=wrap-comments2.yaml -m

gives the output given in Listing 378.

Listing 378 textwrap10-mod2.tex

My first sentence
%    first comment second third
%    comment fourth
----|----|----|----|----|----|----|----|
   5   10   15   20   25   30   35   40

Listing 379 wrap-comments2.yaml

modifyLineBreaks:
  textWrapOptions:
    columns: 35
    comments: 
      wrap: 1                #<!-------
      inheritLeadingSpace: 1 #<!-------

We note that, in Listing 378, that the comments have been combined and wrapped and that the leading space has been inherited because of the annotated lines specified in Listing 379.

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.

Example 100

For example, using the settings in Listing 381 and Listing 383 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 380 and Listing 382.

Listing 380 textwrap4-mod2A.tex

He
re
is
a
li
ne
of
te
xt
.

Listing 381 textwrap2A.yaml

modifyLineBreaks:
  textWrapOptions:
    columns: 3
    huge: wrap

Listing 382 textwrap4-mod2B.tex

Here
is
a
line
of
text.

Listing 383 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.

Example 101

Starting with the code in Listing 384 with settings in Listing 385, and running the command

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

gives the code given in Listing 386.

Listing 384 textwrap-ts.tex

x       y

Listing 385 tabstop.yaml

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

Listing 386 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 383 and Listing 385, 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 387, all of which we discuss next.

Listing 387 oneSentencePerLine

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

6.2.1. oneSentencePerLine: overview

An overview of how the oneSentencePerLine routine feature works:

the default value of manipulateSentences is 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:
1. follow the fields specified in sentencesFollow
2. begin with the fields specified in sentencesBeginWith
3. end with the fields specified in sentencesEndWith
by default, the oneSentencePerLine routine will remove line breaks within sentences because removeBlockLineBreaks is 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 either before or after the main indentation routine (see Section 6.2.8);
about trailing comments within text wrap blocks:
1. multiple trailing comments will be connected at the end of the sentence;
2. 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.

Example 102

For example, consider multiple-sentences.tex shown in Listing 388.

Listing 388 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 390 and Listing 392, 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 389 and Listing 391.

Listing 389 multiple-sentences.tex using Listing 390

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 390 manipulate-sentences.yaml

modifyLineBreaks:
    oneSentencePerLine:
        manipulateSentences: 1

Listing 391 multiple-sentences.tex using 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.

Listing 392 keep-sen-line-breaks.yaml

modifyLineBreaks:
    oneSentencePerLine:
        manipulateSentences: 1
        removeSentenceLineBreaks: 0

Notice, in particular, that the ‘internal’ sentence line breaks in Listing 388 have been removed in Listing 389, but have not been removed in Listing 391.

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 387 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 393); 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 394); by default, this is only capital letters;
end with a character (see Listing 395); 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 393 sentencesFollow

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

Listing 394 sentencesBeginWith

    sentencesBeginWith:
      A-Z: 1                            # 0/1
      a-z: 0                            # 0/1
      other: 0                          # regex

Listing 395 sentencesEndWith

    sentencesEndWith:
      basicFullStop: 0                  # 0/1
      betterFullStop: 1                 # 0/1
      exclamationMark: 1                # 0/1
      questionMark: 1                   # 0/1
      other: 0                          # regex

6.2.2. oneSentencePerLine: sentencesFollow

Let’s explore a few of the switches in sentencesFollow.

Example 103

We start with Listing 388, and use the YAML settings given in Listing 397. Using the command

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

we obtain the output given in Listing 396.

Listing 396 multiple-sentences.tex using Listing 397

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

Example 104

We can explore the other field in Listing 393 with the .tex file detailed in Listing 398.

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

Listing 399 multiple-sentences1.tex using Listing 390

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

Listing 400 multiple-sentences1.tex using Listing 401

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

Listing 401 sentences-follow2.yaml

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

Notice that in Listing 399 the first sentence after the ) has not been accounted for, but that following the inclusion of Listing 401, the output given in Listing 400 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 394), and we can use the other field to define sentences to begin with other characters.

Example 105

We use the file in Listing 402.

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

Listing 403 multiple-sentences2.tex using Listing 390

This is the first sentence.

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

Listing 404 multiple-sentences2.tex using Listing 405

This is the first sentence.

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

Listing 405 sentences-begin1.yaml

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

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

6.2.4. oneSentencePerLine: sentencesEndWith

Example 106

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

Listing 406 multiple-sentences.tex using Listing 407

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 407 sentences-end1.yaml

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

Listing 408 multiple-sentences.tex using Listing 409

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 409 sentences-end2.yaml

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

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

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

Example 107

Let’s consider the file shown in Listing 410.

Listing 410 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 411.

Listing 411 url.tex using Listing 390

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

The basicFullStop routine should probably be avoided in most situations, as it does not accommodate the specifications above.

Example 108

For example, using the following command

latexindent.pl url -m -l=alt-full-stop1.yaml

and the YAML in Listing 413 gives the output in Listing 412.

Listing 412 url.tex using Listing 413

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

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

6.2.5. oneSentencePerLine: sentencesDoNOTcontain

You can specify patterns that sentences do not contain using the field in Listing 414.

Listing 414 sentencesDoNOTcontain

    sentencesDoNOTcontain:
      other: \\begin                    # regex

If sentences run across environments then, by default, they will not be considered a sentence by latexindent.pl.

Example 109

For example, if we use the .tex file in Listing 415

Listing 415 multiple-sentences4.tex

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

and run the command

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 Listing 415 to have a sentence. \\begin

Example 110

We can customise the sentencesDoNOTcontain field with anything that we do not want sentences to contain.

We begin with the file in Listing 416.

Listing 416 sentence-dnc1.tex

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

Listing 417 sentence-dnc1-mod1.tex

This should not be a sentence \cmh{?} and should not change.
But this one should.

Listing 418 dnc1.yaml

modifyLineBreaks:
    oneSentencePerLine:
        manipulateSentences: 1
        sentencesDoNOTcontain:
            other: |-
              (?x)
              \\begin
              |
              \\cmh

The settings in Listing 418 say that sentences do not contain \begin and that they do not contain \cmh

Example 111

We can implement case insensitivity for the sentencesDoNOTcontain field.

We begin with the file in Listing 419.

Listing 419 sentence-dnc2.tex

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

Listing 420 sentence-dnc2-mod2.tex

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.

Listing 421 dnc2.yaml

modifyLineBreaks:
    oneSentencePerLine:
        manipulateSentences: 1
        sentencesDoNOTcontain:
            other: |-
              (?xi)    #<!----
              \\begin
              |
              \\cmh

The settings in Listing 421 say that sentences do not contain \begin and that they do not contain case insensitive versions of \cmh

Example 112

We can turn off sentenceDoNOTcontain by setting it to 0 as in Listing 422.

Listing 422 dnc-off.yaml

modifyLineBreaks:
    oneSentencePerLine:
        manipulateSentences: 1
        sentencesDoNOTcontain: 0

The settings in Listing 422 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.

Example 113

For example, if we begin with the .tex file in Listing 423, and run the command

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

then we obtain the output in Listing 424.

Listing 423 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 424 multiple-sentences3.tex using Listing 390

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.

Example 114

Let’s use the code in Listing 425.

Listing 425 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 427, and running the following command

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

we receive the output given in Listing 426.

Listing 426 multiple-sentences5.tex using Listing 427

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

Example 115

The indentation of sentences requires that sentences are stored as code blocks. This means that you may need to tweak Listing 395. Let’s explore this in relation to Listing 428.

Listing 428 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 429 and Listing 430.

Listing 429 multiple-sentences6-mod1.tex using Listing 427

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

Listing 430 multiple-sentences6-mod2.tex using Listing 427 and no sentence indentation

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

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

Example 116

We can tweak the settings in Listing 395 to ensure that full stops are not followed by item commands, and that the end of sentences contains \end{itemize} as in Listing 431. This setting is actually an appended version of the betterFullStop from the fineTuning, detailed in Listing 591.

Listing 431 itemize.yaml

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

Listing 432 multiple-sentences6-mod3.tex using Listing 427 and Listing 431

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:

before means it is likely that the columns of wrapped text may exceed the value specified in columns;
after means it columns of wrapped text should not exceed the value specified in columns.

We demonstrate this in the following examples. See also Section 6.1.7.

Example 117

Let’s begin with the file in Listing 433.

Listing 433 multiple-sentences8.tex

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 435 and running the command

latexindent.pl multiple-sentences8 -o=+-mod1.tex -l=sentence-wrap2 -m

gives the output given in Listing 434.

Listing 434 multiple-sentences8-mod1.tex

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

Listing 435 sentence-wrap2.yaml

defaultIndent: '   '
modifyLineBreaks:
    oneSentencePerLine:
        manipulateSentences: 1     
        textWrapSentences: 1
    textWrapOptions:
        columns: 35
        when: before  # <!-------

We note that, in Listing 434, that the wrapped text has exceeded the specified value of columns (35) given in Listing 435. We can affect this by changing when; we explore this next.

Example 118

We continue working with Listing 433.

Using the settings given in Listing 437 and running the command

latexindent.pl multiple-sentences8.tex -o=+-mod2.tex -l=sentence-wrap3 -m

gives the output given in Listing 436.

Listing 436 multiple-sentences8-mod2.tex

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

Listing 437 sentence-wrap3.yaml

defaultIndent: '   '
modifyLineBreaks:
    oneSentencePerLine:
        manipulateSentences: 1     
        textWrapSentences: 1
    textWrapOptions:
        columns: 35
        when: after  # <!-------

We note that, in Listing 436, that the wrapped text has obeyed the specified value of columns (35) given in Listing 437.

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.

Example 119

Let’s begin with the file in Listing 438.

Listing 438 multiple-sentences9.tex

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 440 and running the command

latexindent.pl multiple-sentences9 -o=+-mod1.tex -l=sentence-wrap4 -m

gives the output given in Listing 439.

Listing 439 multiple-sentences9-mod1.tex

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

Listing 440 sentence-wrap4.yaml

defaultIndent: '   '
modifyLineBreaks:
    oneSentencePerLine:
        manipulateSentences: 1     
        textWrapSentences: 1
    textWrapOptions:
        columns: 35
        comments: 
          wrap: 1  #<!-------

We note that, in Listing 439, that the sentences have been wrapped, and so too have the comments because of the annotated line in Listing 440.

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

Listing 441 environments

  environments:
    BeginStartsOnOwnLine: 0             # -1,0,1,2,3,4
    BodyStartsOnOwnLine: 0              # -1,0,1,2,3,4
    EndStartsOnOwnLine: 0               # -1,0,1,2,3,4
    EndFinishesWithLineBreak: 0         # -1,0,1,2,3,4
    # equation*:
    #     BeginStartsOnOwnLine: 0         # -1,0,1,2,3,4
    #     BodyStartsOnOwnLine: 0          # -1,0,1,2,3,4
    #     EndStartsOnOwnLine: 0           # -1,0,1,2,3,4
    #     EndFinishesWithLineBreak: 0     # -1,0,1,2,3,4

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

Listing 442 env-mlb1.tex

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

6.3.1.1. Adding line breaks: BeginStartsOnOwnLine and BodyStartsOnOwnLine

Example 120

Let’s explore BeginStartsOnOwnLine and BodyStartsOnOwnLine in Listing 443 and Listing 444, and in particular, let’s allow each of them in turn to take a value of $1$.

Listing 443 env-mlb1.yaml

modifyLineBreaks:
    environments:
        BeginStartsOnOwnLine: 1

Listing 444 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 445 and Listing 446 respectively.

Listing 445 env-mlb.tex using Listing 443

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

Listing 446 env-mlb.tex using Listing 444

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

There are a couple of points to note:

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

Example 121

Let’s now change each of the 1 values in Listing 443 and Listing 444 so that they are $2$ and save them into env-mlb3.yaml and env-mlb4.yaml respectively (see Listing 447 and Listing 448).

Listing 447 env-mlb3.yaml

modifyLineBreaks:
    environments:
        BeginStartsOnOwnLine: 2

Listing 448 env-mlb4.yaml

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 449 and Listing 450.

Listing 449 env-mlb.tex using Listing 447

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

Listing 450 env-mlb.tex using Listing 448

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

Note that line breaks have been added as in Listing 445 and Listing 446, 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.

Example 122

Let’s now change each of the 1 values in Listing 443 and Listing 444 so that they are $3$ and save them into env-mlb5.yaml and env-mlb6.yaml respectively (see Listing 451 and Listing 452).

Listing 451 env-mlb5.yaml

modifyLineBreaks:
    environments:
        BeginStartsOnOwnLine: 3

Listing 452 env-mlb6.yaml

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 453 and Listing 454.

Listing 453 env-mlb.tex using Listing 451

before words

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

Listing 454 env-mlb.tex using Listing 452

before words \begin{myenv}

	body of myenv\end{myenv} after words

Note that line breaks have been added as in Listing 445 and Listing 446, but this time a blank line has been added after adding the line break.

Example 123

Let’s now change each of the 1 values in Listing 451 and Listing 452 so that they are $4$ and save them into env-beg4.yaml and env-body4.yaml respectively (see Listing 455 and Listing 456).

Listing 455 env-beg4.yaml

modifyLineBreaks:
    environments:
        BeginStartsOnOwnLine: 4

Listing 456 env-body4.yaml

modifyLineBreaks:
    environments:
        BodyStartsOnOwnLine: 4

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

Listing 457 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 458 and Listing 459.

Listing 458 env-mlb1.tex using Listing 455

before words

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

Listing 459 env-mlb1.tex using Listing 456

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 458 a blank line has been inserted before the \begin statement, even though the \begin statement was already on its own line;
in Listing 459 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

Example 124

Let’s explore EndStartsOnOwnLine and EndFinishesWithLineBreak in Listing 460 and Listing 461, and in particular, let’s allow each of them in turn to take a value of $1$.

Listing 460 env-mlb7.yaml

modifyLineBreaks:
    environments:
        EndStartsOnOwnLine: 1

Listing 461 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 462 and Listing 463.

Listing 462 env-mlb.tex using Listing 460

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

Listing 463 env-mlb.tex using Listing 461

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

There are a couple of points to note:

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

Example 125

Let’s now change each of the 1 values in Listing 460 and Listing 461 so that they are $2$ and save them into env-mlb9.yaml and env-mlb10.yaml respectively (see Listing 464 and Listing 465).

Listing 464 env-mlb9.yaml

modifyLineBreaks:
    environments:
        EndStartsOnOwnLine: 2

Listing 465 env-mlb10.yaml

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 466 and Listing 467.

Listing 466 env-mlb.tex using Listing 464

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

Listing 467 env-mlb.tex using Listing 465

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

Note that line breaks have been added as in Listing 462 and Listing 463, 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.

Example 126

Let’s now change each of the 1 values in Listing 460 and Listing 461 so that they are $3$ and save them into env-mlb11.yaml and env-mlb12.yaml respectively (see Listing 468 and Listing 469).

Listing 468 env-mlb11.yaml

modifyLineBreaks:
    environments:
        EndStartsOnOwnLine: 3

Listing 469 env-mlb12.yaml

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 470 and Listing 471.

Listing 470 env-mlb.tex using Listing 468

before words \begin{myenv}body of myenv

\end{myenv} after words

Listing 471 env-mlb.tex using Listing 469

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

after words

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

Example 127

Let’s now change each of the 1 values in Listing 468 and Listing 469 so that they are $4$ and save them into env-end4.yaml and env-end-f4.yaml respectively (see Listing 472 and Listing 473).

Listing 472 env-end4.yaml

modifyLineBreaks:
    environments:
        EndStartsOnOwnLine: 4

Listing 473 env-end-f4.yaml

modifyLineBreaks:
    environments:
        EndFinishesWithLineBreak: 4

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

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 474 and Listing 475.

Listing 474 env-mlb1.tex using Listing 472

before words
\begin{myenv}
	body of myenv

\end{myenv}
after words

Listing 475 env-mlb1.tex using Listing 473

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 474 a blank line has been inserted before the \end statement, even though the \end statement was already on its own line;
in Listing 475 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.

Example 128

For example, if you process the file in Listing 476 using poly-switch values of 1, 2, or 3, it will be left unchanged.

Listing 476 env-mlb2.tex

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

Listing 477 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 458 and Listing 459 and Listing 474 and Listing 475.

Example 129

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

Listing 478 env-mlb3.tex using Listing 444

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

Listing 479 env-mlb3.tex using Listing 448

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 441, 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.

Example 130

We will consider the example code given in Listing 480, noting in particular the positions of the line break highlighters, ♠, ♥, ◆ and ♣, together with the associated YAML files in Listing 481 – Listing 484.

Listing 480 env-mlb4.tex

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

After

Listing 481 env-mlb13.yaml

modifyLineBreaks:
    environments:
        BeginStartsOnOwnLine: -1

Listing 482 env-mlb14.yaml

modifyLineBreaks:
    environments:
        BodyStartsOnOwnLine: -1

Listing 483 env-mlb15.yaml

modifyLineBreaks:
    environments:
        EndStartsOnOwnLine: -1

Listing 484 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 485 – Listing 488.

Listing 485 env-mlb4.tex using Listing 481

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

Listing 486 env-mlb4.tex using Listing 482

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

Listing 487 env-mlb4.tex using Listing 483

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

Listing 488 env-mlb4.tex using Listing 484

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

Notice that in:

Listing 485 the line break denoted by ♠ in Listing 480 has been removed;
Listing 486 the line break denoted by ♥ in Listing 480 has been removed;
Listing 487 the line break denoted by ◆ in Listing 480 has been removed;
Listing 488 the line break denoted by ♣ in Listing 480 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 481 – Listing 484 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 442.

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.

Example 131

We consider the file shown in Listing 489, which highlights trailing spaces.

Listing 489 env-mlb5.tex

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

The

Listing 490 removeTWS-before.yaml

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 491 and Listing 492; note that the trailing horizontal white space has been preserved (by default) in Listing 491, while in Listing 492, it has been removed using the switch specified in Listing 490.

Listing 491 env-mlb5.tex using Listing 485 – Listing 488

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

Listing 492 env-mlb5.tex using Listing 485 – Listing 488 and Listing 490

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

6.3.1.6. poly-switch line break removal and blank lines

Example 132

Now let’s consider the file in Listing 493, which contains blank lines.

Listing 493 env-mlb6.tex

before words♠

\begin{myenv}♥

body of myenv◆

\end{myenv}♣

after words

Upon

Listing 494 UnpreserveBlankLines.yaml

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 495 and Listing 496. In Listing 495 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 496, we have allowed the poly-switches to remove blank lines because, in Listing 494, we have set preserveBlankLines to 0.

Listing 495 env-mlb6.tex using Listing 485 – Listing 488

before words

\begin{myenv}

	body of myenv

\end{myenv}

after words

Listing 496 env-mlb6.tex using Listing 485 – Listing 488 and Listing 494

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

Example 133

We can explore this further using the blank-line poly-switch value of $3$; let’s use the file given in Listing 497.

Listing 497 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,env-mlb14,UnpreserveBlankLines

we receive the outputs given in Listing 498 and Listing 499.

Listing 498 env-mlb7-preserve.tex

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

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

Listing 499 env-mlb7-no-preserve.tex

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

Notice that in:

Listing 498 that \end{one} has added a blank line, because of the value of EndFinishesWithLineBreak in Listing 469, and even though the line break ahead of \begin{two} should have been removed (because of BeginStartsOnOwnLine in Listing 481), the blank line has been preserved by default;
Listing 499, by contrast, has had the additional line-break removed, because of the settings in Listing 494.

6.3.2. Poly-switches for double backslash

With reference to lookForAlignDelims (see Listing 72) you can specify poly-switches to dictate the line-break behaviour of double backslashes in environments (Listing 74), commands (Listing 108), or special code blocks (Listing 153). 1

Consider the code given in Listing 500.

Listing 500 tabular3.tex

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

Referencing Listing 500:

DBS stands 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

Example 134

We explore DBSStartsOnOwnLine (★ in Listing 500); starting with the code in Listing 500, together with the YAML files given in Listing 502 and Listing 504 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 501 and Listing 503.

Listing 501 tabular3.tex using Listing 502

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

Listing 502 DBS1.yaml

modifyLineBreaks:
    environments:
        DBSStartsOnOwnLine: 1

Listing 503 tabular3.tex using Listing 504

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

Listing 504 DBS2.yaml

modifyLineBreaks:
    environments:
        tabular:
            DBSStartsOnOwnLine: 2

We note that

Listing 502 specifies DBSStartsOnOwnLine for every environment (that is within lookForAlignDelims, Listing 75); the double backslashes from Listing 500 have been moved to their own line in Listing 501;
Listing 504 specifies DBSStartsOnOwnLine on a per-name basis for tabular (that is within lookForAlignDelims, Listing 75); the double backslashes from Listing 500 have been moved to their own line in Listing 503, having added comment symbols before moving them.

Example 135

We can combine DBS poly-switches with, for example, the alignContentAfterDoubleBackSlash in Section 5.5.6.

For example, starting with the file Listing 505, and using the settings in Listing 144 and Listing 146 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 506 and Listing 507.

Listing 505 tabular6.tex

\begin{tabular}{cc}
 1&22\\333&4444\\55555&666666
\end{tabular}

Listing 506 tabular6-mod1.tex

\begin{tabular}{cc}
	   1     & 22
	\\ 333   & 4444
	\\ 55555 & 666666
\end{tabular}

Listing 507 tabular6-mod2.tex

\begin{tabular}{cc}
	     1     & 22
	\\   333   & 4444
	\\   55555 & 666666
\end{tabular}

We note that:

in Listing 506 the content after the double back slash has been aligned;
in Listing 507 we see that 3 spaces have been added after the double back slash.

6.3.2.2. Double backslash finishes with line break

Example 136

Let’s now explore DBSFinishesWithLineBreak (□ in Listing 500); starting with the code in Listing 500, together with the YAML files given in Listing 509 and Listing 511 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 508 and Listing 510.

Listing 508 tabular3.tex using Listing 509

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

Listing 509 DBS3.yaml

modifyLineBreaks:
    environments:
        DBSFinishesWithLineBreak: 1

Listing 510 tabular3.tex using Listing 511

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

Listing 511 DBS4.yaml

modifyLineBreaks:
    environments:
        tabular:
            DBSFinishesWithLineBreak: 2

We note that

Listing 509 specifies DBSFinishesWithLineBreak for every environment (that is within lookForAlignDelims, Listing 75); the code following the double backslashes from Listing 500 has been moved to their own line in Listing 508;
Listing 511 specifies DBSFinishesWithLineBreak on a per-name basis for tabular (that is within lookForAlignDelims, Listing 75); the first double backslashes from Listing 500 have moved code following them to their own line in Listing 510, 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

Example 137

Let’s explore the double backslash poly-switches for code blocks within specialBeginEnd code blocks (Listing 151); we begin with the code within Listing 512.

Listing 512 special4.tex

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

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

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

then we receive the output given in Listing 513.

Listing 513 special4.tex using Listing 514

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

Listing 514 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 514 we have specified cmhMath within lookForAlignDelims; without this, the double backslash poly-switches would be ignored for this code block;
the DBSFinishesWithLineBreak poly-switch has controlled the line breaks following the double backslashes;
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 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.

Example 138

We use with the code in Listing 515.

Listing 515 mycommand2.tex

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

Upon using the YAML settings in Listing 517 and Listing 519, 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 516 and Listing 518.

Listing 516 mycommand2.tex using Listing 517

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

Listing 517 DBS6.yaml

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

Listing 518 mycommand2.tex using Listing 519

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

Listing 519 DBS7.yaml

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

Example 139

For example, beginning with the code in Listing 520

Listing 520 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 509,

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

then we receive the output given in Listing 521.

Listing 521 pmatrix3.tex using Listing 509

\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 591.

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

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 2
	`[`♥	♥	OptArgBodyStartsOnOwnLine
	`value before comma`★,	★	CommaStartsOnOwnLine
	□	□	CommaFinishesWithLineBreak
	`end of body of opt arg`◆	◆	RSqBStartsOnOwnLine
	`]`♣	♣	RSqBFinishesWithLineBreak
	`...`
mandatoryArguments	`...`♠	♠	LCuBStartsOnOwnLine 3
	`\{`♥	♥	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.

Example 140

Let’s begin with the code in Listing 522 and the YAML settings in Listing 524; with reference to Table 3, the key CommandNameFinishesWithLineBreak is an alias for BodyStartsOnOwnLine.

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

Listing 523 mycommand1.tex using Listing 524

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

Listing 524 mycom-mlb1.yaml

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

Example 141

Now let’s change the YAML file so that it is as in Listing 526; upon running the command

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

we obtain Listing 525; both beginning braces \{ have had their leading line breaks removed.

Listing 525 mycommand1.tex using Listing 526

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

Listing 526 mycom-mlb2.yaml

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

Example 142

Now let’s change the YAML file so that it is as in Listing 528; upon running the command

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

we obtain Listing 527.

Listing 527 mycommand1.tex using Listing 528

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

Listing 528 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.

Example 143

We use the example from Listing 522, and consider the YAML settings given in Listing 530. The output from running

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

is given in Listing 530.

Listing 529 mycommand1.tex using Listing 530

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

Listing 530 mycom-mlb4.yaml

modifyLineBreaks:
    mandatoryArguments:
        LCuBStartsOnOwnLine: -1
        RCuBFinishesWithLineBreak: 1

Studying Listing 530, 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 529, 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.

Example 144

We can explore this further by considering the YAML settings in Listing 532; upon running the command

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

we obtain the output given in Listing 531.

Listing 531 mycommand1.tex using Listing 532

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

Listing 532 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 534, and run the command

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

which gives the output in Listing 533.

Listing 533 mycommand1.tex using Listing 534

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

Listing 534 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

Example 145

Now let’s consider an example when nested code blocks have conflicting poly-switches; we’ll use the code in Listing 535, noting that it contains nested environments.

Listing 535 nested-env.tex

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

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

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

gives the output in Listing 536.

Listing 536 nested-env.tex using Listing 537

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

Listing 537 nested-env-mlb1.yaml

modifyLineBreaks:
    environments:
        EndStartsOnOwnLine: -1
        EndFinishesWithLineBreak: 1

In Listing 536, 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 535, 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$).
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 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 536, 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}).

Example 146

We can explore this further using the poly-switches in Listing 539; upon running the command

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

we obtain the output given in Listing 538.

Listing 538 nested-env.tex using Listing 539

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

Listing 539 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: There is no longer any need for the code block to be specified within lookForAlignDelims for DBS poly-switches to activate.
2: LSqB stands for Left Square Bracket
3: LCuB stands for Left Curly Brace

6. The -m (modifylinebreaks) switch

6.1. Text Wrapping

6.1.1. Text wrap: overview

6.1.2. Text wrap: simple examples

6.1.3. Text wrap: blocksFollow examples

6.1.4. Text wrap: blocksBeginWith examples

6.1.5. Text wrap: blocksEndBefore examples

6.1.6. Text wrap: trailing comments and spaces

6.1.7. Text wrap: when before/after

6.1.8. Text wrap: wrapping comments

6.1.9. Text wrap: huge, tabstop and separator

6.2. oneSentencePerLine: modifying line breaks for sentences

6.2.1. oneSentencePerLine: overview

6.2.2. oneSentencePerLine: sentencesFollow

6.2.3. oneSentencePerLine: sentencesBeginWith

6.2.4. oneSentencePerLine: sentencesEndWith

6.2.5. oneSentencePerLine: sentencesDoNOTcontain

6.2.6. Features of the oneSentencePerLine routine

6.2.7. oneSentencePerLine: text wrapping and indenting sentences

6.2.8. oneSentencePerLine: text wrapping and indenting sentences, when before/after

6.2.9. oneSentencePerLine: text wrapping sentences and comments

6.3. Poly-switches

6.3.1. Poly-switches for environments

6.3.1.1. Adding line breaks: BeginStartsOnOwnLine and BodyStartsOnOwnLine

6.3.1.2. Adding line breaks: EndStartsOnOwnLine and EndFinishesWithLineBreak

6.3.1.3. poly-switches 1, 2, and 3 only add line breaks when necessary

6.3.1.4. Removing line breaks (poly-switches set to \(-1\))

6.3.1.5. About trailing horizontal space

6.3.1.6. poly-switch line break removal and blank lines

6.3.2. Poly-switches for double backslash

6.3.2.1. Double backslash starts on own line

6.3.2.2. Double backslash finishes with line break

6.3.2.3. Double backslash poly-switches for specialBeginEnd

6.3.2.4. Double backslash poly-switches for optional and mandatory arguments

6.3.2.5. Double backslash optional square brackets

6.3.3. Poly-switches for other code blocks

6.3.4. Partnering BodyStartsOnOwnLine with argument-based poly-switches

6.3.5. Conflicting poly-switches: sequential code blocks

6.3.6. Conflicting poly-switches: nested code blocks

6.1.3. Text wrap: `blocksFollow` examples

6.1.4. Text wrap: `blocksBeginWith` examples

6.1.5. Text wrap: `blocksEndBefore` examples