6. The `-m` (`modifylinebreaks`) switch¶

All features described in this section will only be relevant if the -m switch is used.

modifylinebreaks: fields

Listing 184 modifyLineBreaks¶

modifyLineBreaks:
    preserveBlankLines: 1
    condenseMultipleBlankLinesInto: 1

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

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:

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 below. 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: integer :math:`geq 0`

Assuming that this switch takes an integer value greater than 0, latexindent.pl will condense multiple blank lines into the number of blank lines illustrated by this switch. As an example, Listing 185 shows a sample file with blank lines; upon running

latexindent.pl myfile.tex -m

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

Listing 185 mlb1.tex¶

before blank line

after blank line

after blank line

Listing 186 mlb1.tex out output¶

before blank line

after blank line

after blank line

textWrapOptions: fields

When the -m switch is active latexindent.pl has the ability to wrap text using the options specified in the textWrapOptions field, see Listing 187. The value of columns specifies the column at which the text should be wrapped. By default, the value of columns is 0, so latexindent.pl will not wrap text; if you change it to a value of 2 or more, then text will be wrapped after the character in the specified column.

Listing 187 textWrapOptions¶

    textWrapOptions:
        columns: 0

For example, consider the file give in Listing 188.

Listing 188 textwrap1.tex¶

Here is a line of text that will be wrapped by latexindent.pl. Each line is quite long.

Here is a line of text that will be wrapped by latexindent.pl. Each line is quite long.

Using the file textwrap1.yaml in Listing 190, and running the command

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

we obtain the output in Listing 189.

Listing 189 textwrap1-mod1.tex¶

Here is a line of
text that will be
wrapped by
latexindent.pl.
Each line is quite
long.

Here is a line of
text that will be
wrapped by
latexindent.pl.
Each line is quite
long.

Listing 190 textwrap1.yaml¶

modifyLineBreaks:
    textWrapOptions:
        columns: 20

The text wrapping routine is performed after verbatim environments have been stored, so verbatim environments and verbatim commands are exempt from the routine. For example, using the file in Listing 191,

Listing 191 textwrap2.tex¶

Here is a line of text that will be wrapped by latexindent.pl. Each line is quite long.

\begin{verbatim}
    a long line in a verbatim environment, which will not be broken by latexindent.pl
\end{verbatim}

Here is a verb command: \verb!this will not be text wrapped!

and running the following command and continuing to use textwrap1.yaml from Listing 190,

latexindent.pl -m textwrap2.tex -o textwrap2-mod1.tex -l textwrap1.yaml

then the output is as in Listing 192.

Listing 192 textwrap2-mod1.tex¶

Here is a line of
text that will be
wrapped by
latexindent.pl.
Each line is quite
long.

\begin{verbatim}
    a long line in a verbatim environment, which will not be broken by latexindent.pl
\end{verbatim}

Here is a verb
command:
\verb!this will not be text wrapped!

Furthermore, the text wrapping routine is performed after the trailing comments have been stored, and they are also exempt from text wrapping. For example, using the file in Listing 193

Listing 193 textwrap3.tex¶

Here is a line of text that will be wrapped by latexindent.pl. Each line is quite long.

Here is a line % text wrapping does not apply to comments by latexindent.pl

and running the following command and continuing to use textwrap1.yaml from Listing 190,

latexindent.pl -m textwrap3.tex -o textwrap3-mod1.tex -l textwrap1.yaml

then the output is as in Listing 194.

Listing 194 textwrap3-mod1.tex¶

Here is a line of
text that will be
wrapped by
latexindent.pl.
Each line is quite
long.

Here is a line
% text wrapping does not apply to comments by latexindent.pl

Listing 195 textWrapOptions¶

    textWrapOptions:
        columns: 0
        separator: ""

The text wrapping routine of latexindent.pl is performed by the Text::Wrap module, which provides a separator feature to separate lines with characters other than a new line (see (“Text:Wrap Perl Module” 2017)). By default, the separator is empty (see Listing 195) which means that a new line token will be used, but you can change it as you see fit.

For example starting with the file in Listing 196

Listing 196 textwrap4.tex¶
Here is a line of text.

and using textwrap2.yaml from Listing 198 with the following command

latexindent.pl -m textwrap4.tex -o textwrap4-mod2.tex -l textwrap2.yaml

then we obtain the output in Listing 197.

Listing 197 textwrap4-mod2.tex¶

Here||is a||line||of||text||.

Listing 198 textwrap2.yaml¶

modifyLineBreaks:
    textWrapOptions:
        columns: 5
        separator: "||"

Summary of text wrapping It is important to note the following:

Verbatim environments (Listing 17) and verbatim commands (Listing 18) will not be affected by the text wrapping routine (see Listing 192);
comments will not be affected by the text wrapping routine (see Listing 194);
indentation is performed after the text wrapping routine; as such, indented code will likely exceed any maximum value set in the columns field.

6.1. `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 199, all of which we discuss next.

Listing 199 oneSentencePerLine¶

    oneSentencePerLine:
        manipulateSentences: 0     
        removeSentenceLineBreaks: 1
        sentencesFollow:
            par: 1
            blankLine: 1
            fullStop: 1
            exclamationMark: 1
            questionMark: 1
            rightBrace: 1
            commentOnPreviousLine: 1
            other: 0
        sentencesBeginWith:
            A-Z: 1
            a-z: 0
            other: 0
        sentencesEndWith:
            basicFullStop: 0
            betterFullStop: 1
            exclamationMark: 1
            questionMark: 1
            other: 0

manipulateSentences: 0|1

This is a binary switch that details if latexindent.pl should perform the sentence manipulation routine; it is off (set to 0) by default, and you will need to turn it on (by setting it to 1) if you want the script to modify line breaks surrounding and within sentences.

removeSentenceLineBreaks: 0|1

When operating upon sentences latexindent.pl will, by default, remove internal linebreaks as removeSentenceLineBreaks is set to 1. Setting this switch to 0 instructs latexindent.pl not to do so.

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

Listing 200 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 202 and Listing 204, 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 201 and Listing 203.

Listing 201 multiple-sentences.tex using Listing 202¶

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 202 manipulate-sentences.yaml¶

modifyLineBreaks:
    oneSentencePerLine:
        manipulateSentences: 1

Listing 203 multiple-sentences.tex using Listing 204¶

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 204 keep-sen-line-breaks.yaml¶

modifyLineBreaks:
    oneSentencePerLine:
        manipulateSentences: 1
        removeSentenceLineBreaks: 0

Notice, in particular, that the ‘internal’ sentence line breaks in Listing 200 have been removed in Listing 201, but have not been removed in Listing 203.

The remainder of the settings displayed in Listing 199 instruct latexindent.pl on how to define a sentence. From the perpesctive of latexindent.pl a sentence must:

follow a certain character or set of characters (see Listing 205); 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 206); by default, this is only capital letters;
end with a character (see Listing 207); 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.

-3.5cm-2.5cm

Listing 205 sentencesFollow¶

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

Listing 206 sentencesBeginWith¶

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

Listing 207 sentencesEndWith¶

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

6.1.1. `sentencesFollow`¶

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

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

we obtain the output given in Listing 208.

Listing 208 multiple-sentences.tex using Listing 209¶

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 209 sentences-follow1.yaml¶

modifyLineBreaks:
    oneSentencePerLine:
        manipulateSentences: 1
        sentencesFollow:
            blankLine: 0

Notice that, because blankLine is set to 0, latexindent.pl will not seek sentences following a blank line, and so the fourth sentence has not been accounted for.

We can explore the other field in Listing 205 with the .tex file detailed in Listing 210.

Listing 210 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 211 and Listing 212.

Listing 211 multiple-sentences1.tex using Listing 202¶

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

Listing 212 multiple-sentences1.tex using Listing 213¶

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

Listing 213 sentences-follow2.yaml¶

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

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

6.1.2. `sentencesBeginWith`¶

By default, latexindent.pl will only assume that sentences begin with the upper case letters A-Z; you can instruct the script to define sentences to begin with lower case letters (see Listing 206), and we can use the other field to define sentences to begin with other characters.

Listing 214 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 215 and Listing 216.

Listing 215 multiple-sentences2.tex using Listing 202¶

This is the first sentence.

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

Listing 216 multiple-sentences2.tex using Listing 217¶

This is the first sentence.

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

Listing 217 sentences-begin1.yaml¶

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

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

6.1.3. `sentencesEndWith`¶

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

Listing 218 multiple-sentences.tex using Listing 219¶

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 219 sentences-end1.yaml¶

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

Listing 220 multiple-sentences.tex using Listing 221¶

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 221 sentences-end2.yaml¶

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

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

Referencing Listing 207, you’ll notice that there is a field called basicFullStop, which is set to 0, and that the betterFullStop is set to 1 by default.

Let’s consider the file shown in Listing 222.

Listing 222 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 223.

Listing 223 url.tex using Listing 202¶

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.

The basicFullStop routine should probably be avoided in most situations, as it does not accomodate the specifications above. For example, using the YAML in Listing 225 gives the output from the following command in Listing 224.

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

-3.5cm-1.5cm

Listing 224 url.tex using Listing 225¶

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

Listing 225 alt-full-stop1.yaml¶

modifyLineBreaks:
    oneSentencePerLine:
        manipulateSentences: 1
        sentencesEndWith:
            basicFullStop: 1
            betterFullStop: 0

Notice that the full stop within the URL has not been accomodated correctly because of the non-default settings in Listing 225.

6.1.4. Features of the `oneSentencePerLine` routine¶

The sentence manipulation routine takes place after verbatim environments, preamble and trailing comments have been accounted for; this means that any characters within these types of code blocks will not be part of the sentence manipulation routine.

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

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

then we obtain the output in Listing 227.

Listing 226 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 227 multiple-sentences3.tex using Listing 202¶

The first sentence continues after the verbatim \begin{verbatim}
  there are sentences within this. These 
  will not be operated
  upon by latexindent.pl. 
\end{verbatim} and finishes here.
Second sentence contains trailing comments, which are ignored.
% a commented full stop.

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

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

then we obtain the output in Listing 229 and Listing 230.

Listing 228 multiple-sentences4.tex¶

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

Listing 229 multiple-sentences4.tex using Listing 202¶

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

Listing 230 multiple-sentences4.tex using Listing 204¶

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

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

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

the output of which is shown in Listing 231.

Listing 231 multiple-sentences4.tex using Listing 232¶

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

Listing 232 item-rules2.yaml¶

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

6.2. `removeParagraphLineBreaks`: modifying line breaks for paragraphs¶

When the -m switch is active latexindent.pl has the ability to remove line breaks from within paragraphs; the behaviour is controlled by the removeParagraphLineBreaks field, detailed in Listing 233. Thank you to Owens (2017) for shaping and assisting with the testing of this feature. removeParagraphLineBreaks: fields

This feature is considered complimentary to the oneSentencePerLine feature described in Section 6.1.

Listing 233 removeParagraphLineBreaks¶

    removeParagraphLineBreaks:
        all: 0
        alignAtAmpersandTakesPriority: 1
        environments: 
            quotation: 0
        ifElseFi: 0
        optionalArguments: 0
        mandatoryArguments: 0
        items: 0
        specialBeginEnd: 0
        afterHeading: 0
        filecontents: 0
        masterDocument: 0

This routine can be turned on globally for every code block type known to latexindent.pl (see Table 2) by using the all switch; by default, this switch is off. Assuming that the all switch is off, then the routine can be controlled on a per-code-block-type basis, and within that, on a per-name basis. We will consider examples of each of these in turn, but before we do, let’s specify what latexindent.pl considers as a paragraph:

it must begin on its own line with either an alphabetic or numeric character, and not with any of the code-block types detailed in Table 2;
it can include line breaks, but finishes when it meets either a blank line, a \par command, or any of the user-specified settings in the paragraphsStopAt field, detailed in Listing 250.

Let’s start with the .tex file in Listing 234, together with the YAML settings in Listing 235.

Listing 234 shortlines.tex¶

\begin{myenv}
The lines
in this 
environment
are very 
short
and contain
many linebreaks.

Another 
paragraph.
\end{myenv}

Listing 235 remove-para1.yaml¶

modifyLineBreaks:
    removeParagraphLineBreaks:
        all: 1

Upon running the command

latexindent.pl -m shortlines.tex -o shortlines1.tex -l remove-para1.yaml

then we obtain the output given in Listing 236.

Listing 236 shortlines1.tex¶

\begin{myenv}
	The lines in this  environment are very  short and contain many linebreaks.

	Another  paragraph.
\end{myenv}

Keen readers may notice that some trailing white space must be present in the file in Listing 234 which has crept in to the output in Listing 236. This can be fixed using the YAML file in Listing 297 and running, for example,

latexindent.pl -m shortlines.tex -o shortlines1-tws.tex -l remove-para1.yaml,removeTWS-before.yaml

in which case the output is as in Listing 237; notice that the double spaces present in Listing 236 have been addressed.

Listing 237 shortlines1-tws.tex¶

\begin{myenv}
	The lines in this environment are very short and contain many linebreaks.

	Another paragraph.
\end{myenv}

Keeping with the settings in Listing 235, we note that the all switch applies to all code block types. So, for example, let’s consider the files in Listing 238 and Listing 239

Listing 238 shortlines-mand.tex¶

\mycommand{
The lines
in this 
command
are very 
short
and contain
many linebreaks.

Another 
paragraph.
}

Listing 239 shortlines-opt.tex¶

\mycommand[
The lines
in this 
command
are very 
short
and contain
many linebreaks.

Another 
paragraph.
]

Upon running the commands

latexindent.pl -m shortlines-mand.tex -o shortlines-mand1.tex -l remove-para1.yaml
latexindent.pl -m shortlines-opt.tex -o shortlines-opt1.tex -l remove-para1.yaml

then we obtain the respective output given in Listing 240 and Listing 241.

Listing 240 shortlines-mand1.tex¶

\mycommand{
	The lines in this  command are very  short and contain many linebreaks.

	Another  paragraph.
}

Listing 241 shortlines-opt1.tex¶

\mycommand[
	The lines in this  command are very  short and contain many linebreaks.

	Another  paragraph.
]

Assuming that we turn off the all switch (by setting it to 0), then we can control the behaviour of removeParagraphLineBreaks either on a per-code-block-type basis, or on a per-name basis.

For example, let’s use the code in Listing 242, and consider the settings in Listing 243 and Listing 244; note that in Listing 243 we specify that every environment should receive treatment from the routine, while in Listing 244 we specify that only the one environment should receive the treatment.

Listing 242 shortlines-envs.tex¶

\begin{one}
The lines
in this 
environment
are very 
short
and contain
many linebreaks.

Another 
paragraph.
\end{one}

\begin{two}
The lines
in this 
environment
are very 
short
and contain
many linebreaks.

Another 
paragraph.
\end{two}

Listing 243 remove-para2.yaml¶

modifyLineBreaks:
    removeParagraphLineBreaks:
        environments: 1

Listing 244 remove-para3.yaml¶

modifyLineBreaks:
    removeParagraphLineBreaks:
        environments: 
            one: 1

Upon running the commands

latexindent.pl -m shortlines-envs.tex -o shortlines-envs2.tex -l remove-para2.yaml
latexindent.pl -m shortlines-envs.tex -o shortlines-envs3.tex -l remove-para3.yaml

then we obtain the respective output given in Listing 245 and Listing 246.

Listing 245 shortlines-envs2.tex¶

\begin{one}
	The lines in this  environment are very  short and contain many linebreaks.

	Another  paragraph.
\end{one}

\begin{two}
	The lines in this  environment are very  short and contain many linebreaks.

	Another  paragraph.
\end{two}

Listing 246 shortlines-envs3.tex¶

\begin{one}
	The lines in this  environment are very  short and contain many linebreaks.

	Another  paragraph.
\end{one}

\begin{two}
	The lines
	in this
	environment
	are very
	short
	and contain
	many linebreaks.

	Another
	paragraph.
\end{two}

The remaining code-block types can be customized in analogous ways, although note that commands, keyEqualsValuesBracesBrackets, namedGroupingBracesBrackets, UnNamedGroupingBracesBrackets are controlled by the optionalArguments and the mandatoryArguments.

The only special case is the masterDocument field; this is designed for ‘chapter’-type files that may contain paragraphs that are not within any other code-blocks. For example, consider the file in Listing 247, with the YAML settings in Listing 248.

Listing 247 shortlines-md.tex¶

The lines
in this 
document
are very 
short
and contain
many linebreaks.

Another 
paragraph.

\begin{myenv}
The lines
in this 
document
are very 
short
and contain
many linebreaks.
\end{myenv}

Listing 248 remove-para4.yaml¶

modifyLineBreaks:
    removeParagraphLineBreaks:
        masterDocument: 1

Upon running the following command

latexindent.pl -m shortlines-md.tex -o shortlines-md4.tex -l remove-para4.yaml

then we obtain the output in Listing 249.

Listing 249 shortlines-md4.tex¶

The lines in this  document are very  short and contain many linebreaks.

Another  paragraph.

\begin{myenv}
	The lines
	in this
	document
	are very
	short
	and contain
	many linebreaks.
\end{myenv}

paragraphsStopAt: fields

The paragraph line break routine considers blank lines and the \par command to be the end of a paragraph; you can fine tune the behaviour of the routine further by using the paragraphsStopAt fields, shown in Listing 250.

Listing 250 paragraphsStopAt¶

        paragraphsStopAt:
            environments: 1
            commands: 0
            ifElseFi: 0
            items: 0
            specialBeginEnd: 0
            heading: 0
            filecontents: 0
            comments: 0

The fields specified in paragraphsStopAt tell latexindent.pl to stop the current paragraph when it reaches a line that begins with any of the code-block types specified as 1 in Listing 250. By default, you’ll see that the paragraph line break routine will stop when it reaches an environment at the beginning of a line. It is not possible to specify these fields on a per-name basis.

Let’s use the .tex file in Listing 251; we will, in turn, consider the settings in Listing 252 and Listing 253.

Listing 251 sl-stop.tex¶

These lines
are very 
short 
\emph{and} contain
many linebreaks.
\begin{myenv}
Body of myenv
\end{myenv}

Another 
paragraph.
% a comment
% a comment

Listing 252 stop-command.yaml¶

modifyLineBreaks:
    removeParagraphLineBreaks:
        paragraphsStopAt:
            commands: 1

Listing 253 stop-comment.yaml¶

modifyLineBreaks:
    removeParagraphLineBreaks:
        paragraphsStopAt:
            comments: 1

Upon using the settings from Listing 248 and running the commands

latexindent.pl -m sl-stop.tex -o sl-stop4.tex -l remove-para4.yaml
latexindent.pl -m sl-stop.tex -o sl-stop4-command.tex -l=remove-para4.yaml,stop-command.yaml
latexindent.pl -m sl-stop.tex -o sl-stop4-comment.tex -l=remove-para4.yaml,stop-comment.yaml

we obtain the respective outputs in Listing 254 – Listing 256; notice in particular that:

in Listing 254 the paragraph line break routine has included commands and comments;
in Listing 255 the paragraph line break routine has stopped at the emph command, because in Listing 252 we have specified commands to be 1, and emph is at the beginning of a line;
in Listing 256 the paragraph line break routine has stopped at the comments, because in Listing 253 we have specified comments to be 1, and the comment is at the beginning of a line.

In all outputs in Listing 254 – Listing 256 we notice that the paragraph line break routine has stopped at \begin{myenv} because, by default, environments is set to 1 in Listing 250.

Listing 254 sl-stop4.tex¶

These lines are very  short  \emph{and} contain many linebreaks.
\begin{myenv}
	Body of myenv
\end{myenv}

Another  paragraph.  % a comment% a comment

Listing 255 sl-stop4-command.tex¶

These lines are very  short
\emph{and} contain
many linebreaks.
\begin{myenv}
	Body of myenv
\end{myenv}

Another  paragraph.  % a comment% a comment

Listing 256 sl-stop4-comment.tex¶

These lines are very  short  \emph{and} contain many linebreaks.
\begin{myenv}
	Body of myenv
\end{myenv}

Another  paragraph.
% a comment
% a comment

6.3. Poly-switches¶

Every other field in the modifyLineBreaks field uses poly-switches, and can take one of five *blank line poly-switch integer values:

remove mode: line breaks before or after the <part of thing> can be removed (assuming that preserveBlankLines is set to 0);
off mode: line breaks will not be modified for the <part of thing> under consideration;
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>;
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>;
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.

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.4. modifyLineBreaks for environments¶

We start by viewing a snippet of defaultSettings.yaml in Listing 257; note that it contains global settings (immediately after the environments field) and that per-name settings are also allowed – in the case of Listing 257, settings for equation* have been specified. Note that all poly-switches are off by default.

Listing 257 environments¶

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

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

Listing 258 env-mlb1.tex¶

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

6.4.1. Adding line breaks using `BeginStartsOnOwnLine` and `BodyStartsOnOwnLine`¶

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

Listing 259 env-mlb1.yaml¶

modifyLineBreaks:
    environments:
        BeginStartsOnOwnLine: 1

Listing 260 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 261 and Listing 262 respectively.

Listing 261 env-mlb.tex using Listing 259¶
before words
\begin{myenv}body of myenv\end{myenv} after words
Listing 262 env-mlb.tex using Listing 260¶
before words \begin{myenv}
	body of myenv\end{myenv} after words

There are a couple of points to note:

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

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

Listing 263 env-mlb3.yaml¶

modifyLineBreaks:
    environments:
        BeginStartsOnOwnLine: 2

Listing 264 env-mlb4.yaml¶

modifyLineBreaks:
    environments:
        BodyStartsOnOwnLine: 2

Upon running commands analogous to the above, we obtain Listing 265 and Listing 266.

Listing 265 env-mlb.tex using Listing 263¶
before words%
\begin{myenv}body of myenv\end{myenv} after words
Listing 266 env-mlb.tex using Listing 264¶
before words \begin{myenv}%
	body of myenv\end{myenv} after words

Note that line breaks have been added as in Listing 261 and Listing 262, but this time a comment symbol has been added before adding the line break; in both cases, trailing horizontal space has been stripped before doing so.

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

Listing 267 env-mlb5.yaml¶

modifyLineBreaks:
    environments:
        BeginStartsOnOwnLine: 3

Listing 268 env-mlb6.yaml¶

modifyLineBreaks:
    environments:
        BodyStartsOnOwnLine: 3

Upon running commands analogous to the above, we obtain Listing 269 and Listing 270.

Listing 269 env-mlb.tex using Listing 267¶
before words

\begin{myenv}body of myenv\end{myenv} after words
Listing 270 env-mlb.tex using Listing 268¶
before words \begin{myenv}

	body of myenv\end{myenv} after words

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

6.4.2. Adding line breaks using `EndStartsOnOwnLine` and `EndFinishesWithLineBreak`¶

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

Listing 271 env-mlb7.yaml¶

modifyLineBreaks:
    environments:
        EndStartsOnOwnLine: 1

Listing 272 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 273 and Listing 274.

Listing 273 env-mlb.tex using Listing 271¶
before words \begin{myenv}body of myenv
\end{myenv} after words
Listing 274 env-mlb.tex using Listing 272¶
before words \begin{myenv}body of myenv\end{myenv}
after words

There are a couple of points to note:

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

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

Listing 275 env-mlb9.yaml¶

modifyLineBreaks:
    environments:
        EndStartsOnOwnLine: 2

Listing 276 env-mlb10.yaml¶

modifyLineBreaks:
    environments:
        EndFinishesWithLineBreak: 2

Upon running commands analogous to the above, we obtain Listing 277 and Listing 278.

Listing 277 env-mlb.tex using Listing 275¶
before words \begin{myenv}body of myenv%
\end{myenv} after words
Listing 278 env-mlb.tex using Listing 276¶
before words \begin{myenv}body of myenv\end{myenv}%
after words

Note that line breaks have been added as in Listing 273 and Listing 274, but this time a comment symbol has been added before adding the line break; in both cases, trailing horizontal space has been stripped before doing so.

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

Listing 279 env-mlb11.yaml¶

modifyLineBreaks:
    environments:
        EndStartsOnOwnLine: 3

Listing 280 env-mlb12.yaml¶

modifyLineBreaks:
    environments:
        EndFinishesWithLineBreak: 3

Upon running commands analogous to the above, we obtain Listing 281 and Listing 282.

Listing 281 env-mlb.tex using Listing 279¶
before words \begin{myenv}body of myenv

\end{myenv} after words
Listing 282 env-mlb.tex using Listing 280¶
before words \begin{myenv}body of myenv\end{myenv} 

after words

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

6.4.3. poly-switches 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$), it will only do so if necessary. For example, if you process the file in Listing 283 using any of the YAML files presented so far in this section, it will be left unchanged.

Listing 283 env-mlb2.tex¶

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

Listing 284 env-mlb3.tex¶

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

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

Listing 285 env-mlb3.tex using Listing 260¶

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

Listing 286 env-mlb3.tex using Listing 264¶

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 257, an example is shown for the equation* environment.

6.4.4. Removing line breaks (poly-switches set to $-1$)¶

Setting poly-switches to $-1$ tells latexindent.pl to remove line breaks of the <part of the thing>, if necessary. We will consider the example code given in Listing 287, noting in particular the positions of the line break highlighters, ♠, ♥, ◆ and ♣, together with the associated YAML files in Listing 288 – Listing 291.

Listing 287 env-mlb4.tex¶

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

After

Listing 288 env-mlb13.yaml¶

modifyLineBreaks:
    environments:
        BeginStartsOnOwnLine: -1

Listing 289 env-mlb14.yaml¶

modifyLineBreaks:
    environments:
        BodyStartsOnOwnLine: -1

Listing 290 env-mlb15.yaml¶

modifyLineBreaks:
    environments:
        EndStartsOnOwnLine: -1

Listing 291 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 292 – Listing 295.

Listing 292 env-mlb4.tex using Listing 288¶
before words\begin{myenv}
	body of myenv
\end{myenv}
after words
Listing 293 env-mlb4.tex using Listing 289¶
before words
\begin{myenv}body of myenv
\end{myenv}
after words
Listing 294 env-mlb4.tex using Listing 290¶
before words
\begin{myenv}
	body of myenv\end{myenv}
after words
Listing 295 env-mlb4.tex using Listing 291¶
before words
\begin{myenv}
	body of myenv
\end{myenv}after words

Notice that in:

Listing 292 the line break denoted by ♠ in Listing 287 has been removed;
Listing 293 the line break denoted by ♥ in Listing 287 has been removed;
Listing 294 the line break denoted by ◆ in Listing 287 has been removed;
Listing 295 the line break denoted by ♣ in Listing 287 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 288 – Listing 291 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 258.

6.4.5. About trailing horizontal space¶

Recall that on we discussed the YAML field removeTrailingWhitespace, and that it has two (binary) switches to determine if horizontal space should be removed beforeProcessing and afterProcessing. The beforeProcessing is particularly relevant when considering the -m switch; let’s consider the file shown in Listing 296, which highlights trailing spaces.

Listing 296 env-mlb5.tex¶

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

The

Listing 297 removeTWS-before.yaml¶
removeTrailingWhitespace:
    beforeProcessing: 1

output from the following commands

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

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

Listing 298 env-mlb5.tex using Listing 292 – Listing 295¶
before words   \begin{myenv}           body of myenv      \end{myenv}     after words
Listing 299 env-mlb5.tex using Listing 292 – Listing 295 and Listing 297¶
before words\begin{myenv}body of myenv\end{myenv}after words

6.4.6. poly-switch line break removal and blank lines¶

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

Listing 300 env-mlb6.tex¶

 before words♠

 \begin{myenv}♥

 body of myenv◆

 \end{myenv}♣

 after words

Upon

Listing 301 UnpreserveBlankLines.yaml¶
modifyLineBreaks:
    preserveBlankLines: 0

running the following commands

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

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

Listing 302 env-mlb6.tex using Listing 292 – Listing 295¶
before words

\begin{myenv}

	body of myenv

\end{myenv}

after words

Listing 303 env-mlb6.tex using Listing 292 – Listing 295 and Listing 301¶

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

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

Listing 304 env-mlb7.tex¶

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

Upon running the following commands

latexindent.pl -m env-mlb7.tex -l env-mlb12.yaml,env-mlb13.yaml
latexindent.pl -m env-mlb7.tex -l env-mlb13.yaml,env-mlb14.yaml,UnpreserveBlankLines.yaml

we receive the outputs given in Listing 305 and Listing 306.

Listing 305 env-mlb7-preserve.tex¶

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

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

Listing 306 env-mlb7-no-preserve.tex¶

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

Notice that in:

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

6.5. Poly-switches for other code blocks¶

Rather than repeat the examples shown for the environment code blocks (in Section 6.4), 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 verbatim, filecontents and ‘comment-marked’ code blocks (Listing 48) can not be modified using latexindent.pl.

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 statement`★	★	ElseStartsOnOwnLine
	`\else`□	□	ElseFinishesWithLineBreak
	`body of else statement`◆	◆	FiStartsOnOwnLine
	`\fi`♣	♣	FiFinishesWithLineBreak
	`after words`
optionalArguments	`...`♠	♠	LSqBStartsOnOwnLine [1]
	`[`♥	♥	OptArgBodyStartsOnOwnLine
	`body of opt arg`◆	◆	RSqBStartsOnOwnLine
	`]`♣	♣	RSqBFinishesWithLineBreak
	`...`
mandatoryArguments	`...`♠	♠	LCuBStartsOnOwnLine [2]
	`{`♥	♥	MandArgBodyStartsOnOwnLine
	`body of mand arg`◆	◆	RCuBStartsOnOwnLine
	`}`♣	♣	RCuBFinishesWithLineBreak
	`...`
commands	`before words`♠	♠	CommandStartsOnOwnLine
	`\mycommand`♥	♥	CommandNameFinishesWithLineBreak
	<arguments>
namedGroupingBraces Brackets	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◆	◆	SpecialEndStartsOnOwnLine
	`\]`♣	♣	SpecialEndFinishesWithLineBreak
	after words

6.6. Partnering `BodyStartsOnOwnLine` with argument-based poly-switches¶

Some poly-switches need to be partnered together; in particular, when line breaks involving the first argument of a code block need to be accounted for using both BodyStartsOnOwnLine (or its equivalent, see Table 3) and LCuBStartsOnOwnLine for mandatory arguments, and LSqBStartsOnOwnLine for optional arguments.

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

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

Listing 308 mycommand1.tex using Listing 309¶

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

Listing 309 mycom-mlb1.yaml¶

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

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

Listing 310 mycommand1.tex using Listing 311¶

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

Listing 311 mycom-mlb2.yaml¶

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

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

Listing 312 mycommand1.tex using Listing 313¶

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

Listing 313 mycom-mlb3.yaml¶

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

6.7. Conflicting poly-switches: sequential code blocks¶

It is very easy to have conflicting poly-switches; if we use the example from Listing 307, and consider the YAML settings given in Listing 315. The output from running

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

is given in Listing 315.

Listing 314 mycommand1.tex using Listing 315¶

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

Listing 315 mycom-mlb4.yaml¶

modifyLineBreaks:
    mandatoryArguments:
        LCuBStartsOnOwnLine: -1
        RCuBFinishesWithLineBreak: 1

Studying Listing 315, 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 314, it is clear that LCuBStartsOnOwnLine won this conflict, and the reason is that the second argument was processed after the first – in general, the most recently-processed code block and associated poly-switch takes priority.

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

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

we obtain the output given in Listing 316.

Listing 316 mycommand1.tex using Listing 317¶

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

Listing 317 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 319, which give associated output in Listing 318.

Listing 318 mycommand1.tex using Listing 319¶

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

Listing 319 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.8. Conflicting poly-switches: nested code blocks¶

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

Listing 320 nested-env.tex¶

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

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

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

gives the output in Listing 321.

Listing 321 nested-env.tex using Listing 322¶

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

Listing 322 nested-env-mlb1.yaml¶

modifyLineBreaks:
    environments:
        EndStartsOnOwnLine: -1
        EndFinishesWithLineBreak: 1

In Listing 321, 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 320, 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 321, this means that during Phase 1:

the two environment is found first, and the line break ahead of the \end{two} statement is removed because EndStartsOnOwnLine is set to $-1$. Importantly, because, at this stage, \end{two} does finish with a line break, EndFinishesWithLineBreak causes no action.
next, the one environment is found; the line break ahead of \end{one} is removed because EndStartsOnOwnLine is set to $-1$.

The indentation is done in Phase 2; in Phase 3 there is no option to add a line break after the ``end`` statements. We can justify this by remembering that during Phase 3, the one environment will be found and processed first, followed by the two environment. If the two environment were to add a line break after the \end{two} statement, then latexindent.pl would have no way of knowing how much indentation to add to the subsequent text (in this case, \end{one}).

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

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

we obtain the output given in Listing 323.

Listing 323 nested-env.tex using Listing 324¶

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

Listing 324 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. https://github.com/cmhughes/latexindent.pl/issues/81.

Owens, John. 2017. “Paragraph Line Break Routine Removal.” May 27. https://github.com/cmhughes/latexindent.pl/issues/33.

“Text:Wrap Perl Module.” 2017. Accessed May 1. http://perldoc.perl.org/Text/Wrap.html.

[1]	LSqB stands for Left Square Bracket

[2]	LCuB stands for Left Curly Brace

6. The `-m` (`modifylinebreaks`) switch¶

6.1. `oneSentencePerLine`: modifying line breaks for sentences¶

6.1.1. `sentencesFollow`¶

6.1.2. `sentencesBeginWith`¶

6.1.3. `sentencesEndWith`¶

6.1.4. Features of the `oneSentencePerLine` routine¶

6.2. `removeParagraphLineBreaks`: modifying line breaks for paragraphs¶

6.3. Poly-switches¶

6.4. modifyLineBreaks for environments¶

6.4.1. Adding line breaks using `BeginStartsOnOwnLine` and `BodyStartsOnOwnLine`¶

6.4.2. Adding line breaks using `EndStartsOnOwnLine` and `EndFinishesWithLineBreak`¶

6.4.3. poly-switches only add line breaks when necessary¶

6.4.4. Removing line breaks (poly-switches set to \(-1\))¶

6.4.5. About trailing horizontal space¶

6.4.6. poly-switch line break removal and blank lines¶

6.5. Poly-switches for other code blocks¶

6.6. Partnering `BodyStartsOnOwnLine` with argument-based poly-switches¶

6.7. Conflicting poly-switches: sequential code blocks¶

6.8. Conflicting poly-switches: nested code blocks¶

Related Topics

Table Of Contents

6. The -m (modifylinebreaks) switch¶

6.1. oneSentencePerLine: modifying line breaks for sentences¶

6.1.1. sentencesFollow¶

6.1.2. sentencesBeginWith¶

6.1.3. sentencesEndWith¶

6.1.4. Features of the oneSentencePerLine routine¶

6.2. removeParagraphLineBreaks: modifying line breaks for paragraphs¶

6.3. Poly-switches¶

6.4. modifyLineBreaks for environments¶

6.4.1. Adding line breaks using BeginStartsOnOwnLine and BodyStartsOnOwnLine¶

6.4.2. Adding line breaks using EndStartsOnOwnLine and EndFinishesWithLineBreak¶

6.4.3. poly-switches only add line breaks when necessary¶

6.4.4. Removing line breaks (poly-switches set to \(-1\))¶

6.4.5. About trailing horizontal space¶

6.4.6. poly-switch line break removal and blank lines¶

6.5. Poly-switches for other code blocks¶

6.6. Partnering BodyStartsOnOwnLine with argument-based poly-switches¶

6.7. Conflicting poly-switches: sequential code blocks¶

6.8. Conflicting poly-switches: nested code blocks¶

6. The `-m` (`modifylinebreaks`) switch¶

6.1. `oneSentencePerLine`: modifying line breaks for sentences¶

6.1.1. `sentencesFollow`¶

6.1.2. `sentencesBeginWith`¶

6.1.3. `sentencesEndWith`¶

6.1.4. Features of the `oneSentencePerLine` routine¶

6.2. `removeParagraphLineBreaks`: modifying line breaks for paragraphs¶

6.4.1. Adding line breaks using `BeginStartsOnOwnLine` and `BodyStartsOnOwnLine`¶

6.4.2. Adding line breaks using `EndStartsOnOwnLine` and `EndFinishesWithLineBreak`¶

6.6. Partnering `BodyStartsOnOwnLine` with argument-based poly-switches¶