5. defaultSettings.yaml

latexindent.pl loads its settings from defaultSettings.yaml. The idea is to separate the behaviour of the script from the internal working – this is very similar to the way that we separate content from form when writing our documents in LaTeX.

If you look in defaultSettings.yaml you’ll find the switches that govern the behaviour of latexindent.pl. If you’re not sure where defaultSettings.yaml resides on your computer, don’t worry as indent.log will tell you where to find it. defaultSettings.yaml is commented, but here is a description of what each switch is designed to do. The default value is given in each case; whenever you see integer in this section, assume that it must be greater than or equal to 0 unless otherwise stated.

fileExtensionPreference:fields

latexindent.pl can be called to act on a file without specifying the file extension. For example we can call

 latexindent.pl myfile

in which case the script will look for myfile with the extensions specified in fileExtensionPreference in their numeric order. If no match is found, the script will exit. As with all of the fields, you should change and/or add to this as necessary.

Listing 15 fileExtensionPreference
41
42
43
44
45
fileExtensionPreference:
    .tex: 1
    .sty: 2
    .cls: 3
    .bib: 4

Calling latexindent.pl myfile with the (default) settings specified in Listing 15 means that the script will first look for myfile.tex, then myfile.sty, myfile.cls, and finally myfile.bib in order [1].

backupExtension:extension name

If you call latexindent.pl with the -w switch (to overwrite myfile.tex) then it will create a backup file before doing any indentation; the default extension is .bak, so, for example, myfile.bak0 would be created when calling latexindent.pl myfile.tex for the first time.

By default, every time you subsequently call latexindent.pl with the -w to act upon myfile.tex, it will create successive back up files: myfile.bak1, myfile.bak2, etc.

onlyOneBackUp:integer

If you don’t want a backup for every time that you call latexindent.pl (so you don’t want myfile.bak1, myfile.bak2, etc) and you simply want myfile.bak (or whatever you chose backupExtension to be) then change onlyOneBackUp to 1; the default value of onlyOneBackUp is 0.

maxNumberOfBackUps:integer

Some users may only want a finite number of backup files, say at most \(3\), in which case, they can change this switch. The smallest value of maxNumberOfBackUps is \(0\) which will not prevent backup files being made; in this case, the behaviour will be dictated entirely by onlyOneBackUp. The default value of maxNumberOfBackUps is 0.

cycleThroughBackUps:integer

Some users may wish to cycle through backup files, by deleting the oldest backup file and keeping only the most recent; for example, with maxNumberOfBackUps: 4, and cycleThroughBackUps set to 1 then the copy procedure given below would be obeyed.

 copy myfile.bak1 to myfile.bak0
 copy myfile.bak2 to myfile.bak1
 copy myfile.bak3 to myfile.bak2
 copy myfile.bak4 to myfile.bak3

The default value of cycleThroughBackUps is 0.

logFilePreferences:fields

latexindent.pl writes information to indent.log, some of which can be customized by changing logFilePreferences; see Listing 16. If you load your own user settings (see Section 4) then latexindent.pl will detail them in indent.log; you can choose not to have the details logged by switching showEveryYamlRead to 0. Once all of your settings have been loaded, you can see the amalgamated settings in the log file by switching showAmalgamatedSettings to 1, if you wish.

Listing 16 logFilePreferences
85
86
87
88
89
90
91
92
93
94
95
logFilePreferences:
    showEveryYamlRead: 1
    showAmalgamatedSettings: 0
    showDecorationStartCodeBlockTrace: 0
    showDecorationFinishCodeBlockTrace: 0
    endLogFileWith: '--------------' 
    showGitHubInfoFooter: 1
    PatternLayout:
        default: "%A%n"
        trace: "%A%n"
        ttrace: "%A%n"

When either of the trace modes (see page page:traceswitch) are active, you will receive detailed information in indent.log. You can specify character strings to appear before and after the notification of a found code block using, respectively, showDecorationStartCodeBlockTrace and showDecorationFinishCodeBlockTrace. A demonstration is given in Section 11.3.

The log file will end with the characters given in endLogFileWith, and will report the GitHub address of latexindent.pl to the log file if showGitHubInfoFooter is set to 1.

latexindent.pl uses the log4perl module (“Log4perl Perl Module” 2017) to handle the creation of the logfile. You can specify the layout of the information given in the logfile using any of the Log Layouts detailed at (“Log4perl Perl Module” 2017).

verbatimEnvironments:fields

A field that contains a list of environments that you would like left completely alone – no indentation will be performed on environments that you have specified in this field, see Listing 17.

Listing 17 verbatimEnvironments
 99
100
101
102
verbatimEnvironments:
    verbatim: 1
    lstlisting: 1
    minted: 1
Listing 18 verbatimCommands
105
106
107
verbatimCommands:
    verb: 1
    lstinline: 1

Note that if you put an environment in verbatimEnvironments and in other fields such as lookForAlignDelims or noAdditionalIndent then latexindent.pl will always prioritize verbatimEnvironments.

verbatimCommands:fields

A field that contains a list of commands that are verbatim commands, for example \verb; any commands populated in this field are protected from line breaking routines (only relevant if the -m is active, see Section 6).

noIndentBlock:fields

If you have a block of code that you don’t want latexindent.pl to touch (even if it is not a verbatim-like environment) then you can wrap it in an environment from noIndentBlock; you can use any name you like for this, provided you populate it as demonstrate in Listing 19.

Listing 19 noIndentBlock
112
113
114
noIndentBlock:
    noindent: 1
    cmhtest: 1

Of course, you don’t want to have to specify these as null environments in your code, so you use them with a comment symbol, %, followed by as many spaces (possibly none) as you like; see Listing 20 for example.

Listing 20 noIndentBlock demonstration
 %(*@@*) \begin{noindent}
         this code
                 won't
      be touched
                     by
              latexindent.pl!
 %(*@@*)\end{noindent}
removeTrailingWhitespace:fields

Trailing white space can be removed both before and after processing the document, as detailed in Listing 21; each of the fields can take the values 0 or 1. See Listing 386 and Listing 387 and Listing 388 for before and after results. Thanks to (Voßkuhle 2013) for providing this feature.

Listing 21 removeTrailingWhitespace
117
118
119
removeTrailingWhitespace:
    beforeProcessing: 0
    afterProcessing: 1
Listing 22 removeTrailingWhitespace (alt)
 removeTrailingWhitespace: 1

You can specify removeTrailingWhitespace simply as 0 or 1, if you wish; in this case, latexindent.pl will set both beforeProcessing and afterProcessing to the value you specify; see Listing 22. .. describe:: fileContentsEnvironments:field

Before latexindent.pl determines the difference between preamble (if any) and the main document, it first searches for any of the environments specified in fileContentsEnvironments, see Listing 23. The behaviour of latexindent.pl on these environments is determined by their location (preamble or not), and the value indentPreamble, discussed next.

Listing 23 fileContentsEnvironments
123
124
125
fileContentsEnvironments:
    filecontents: 1
    filecontents*: 1
indentPreamble:0|1

The preamble of a document can sometimes contain some trickier code for latexindent.pl to operate upon. By default, latexindent.pl won’t try to operate on the preamble (as indentPreamble is set to 0, by default), but if you’d like latexindent.pl to try then change indentPreamble to 1.

lookForPreamble:fields

Not all files contain preamble; for example, sty, cls and bib files typically do not. Referencing Listing 24, if you set, for example, .tex to 0, then regardless of the setting of the value of indentPreamble, preamble will not be assumed when operating upon .tex files.

Listing 24 lookForPreamble
131
132
133
134
135
lookForPreamble:
    .tex: 1
    .sty: 0
    .cls: 0
    .bib: 0
preambleCommandsBeforeEnvironments:0|1

Assuming that latexindent.pl is asked to operate upon the preamble of a document, when this switch is set to 0 then environment code blocks will be sought first, and then command code blocks. When this switch is set to 1, commands will be sought first. The example that first motivated this switch contained the code given in Listing 25.

Listing 25 Motivating preambleCommandsBeforeEnvironments
 ...
 preheadhook={\begin{mdframed}[style=myframedstyle]},
 postfoothook=\end{mdframed},
 ...
defaultIndent:horizontal space

This is the default indentation (\t means a tab, and is the default value) used in the absence of other details for the command or environment we are working with; see indentRules in Section 5.4 for more details.

If you’re interested in experimenting with latexindent.pl then you can remove all indentation by setting defaultIndent: "".

lookForAlignDelims:fields

This contains a list of environments and/or commands that are operated upon in a special way by latexindent.pl (see Listing 26). In fact, the fields in lookForAlignDelims can actually take two different forms: the basic version is shown in Listing 26 and the advanced version in Listing 29; we will discuss each in turn.

Listing 26 lookForAlignDelims (basic)
 lookForAlignDelims:
    tabular: 1
    tabularx: 1
    longtable: 1
    array: 1
    matrix: 1
    ...

The environments specified in this field will be operated on in a special way by latexindent.pl. In particular, it will try and align each column by its alignment tabs. It does have some limitations (discussed further in Section 9), but in many cases it will produce results such as those in Listing 27 and Listing 28.

If you find that latexindent.pl does not perform satisfactorily on such environments then you can set the relevant key to 0, for example tabular: 0; alternatively, if you just want to ignore specific instances of the environment, you could wrap them in something from noIndentBlock (see Listing 19).

Listing 27 tabular1.tex
\begin{tabular}{cccc}
1&	2 &3       &4\\
5& &6       &\\
\end{tabular}
Listing 28 tabular1.tex default output
\begin{tabular}{cccc}
	1 & 2 & 3 & 4 \\
	5 &   & 6 &   \\
\end{tabular}

If, for example, you wish to remove the alignment of the \\ within a delimiter-aligned block, then the advanced form of lookForAlignDelims shown in Listing 29 is for you.

Listing 29 lookForAlignDelims (advanced)
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
lookForAlignDelims:
   tabular: 
      delims: 1
      alignDoubleBackSlash: 1
      spacesBeforeDoubleBackSlash: 1
      multiColumnGrouping: 0
      alignRowsWithoutMaxDelims: 1
      spacesBeforeAmpersand: 1
      spacesAfterAmpersand: 1
      justification: left
      alignFinalDoubleBackSlash: 0
      dontMeasure: 0
      delimiterRegEx: '(?<!\\)(&)'
      delimiterJustification: left
   tabularx:
      delims: 1
   longtable: 1

Note that you can use a mixture of the basic and advanced form: in Listing 29 tabular and tabularx are advanced and longtable is basic. When using the advanced form, each field should receive at least 1 sub-field, and can (but does not have to) receive any of the following fields:

  • delims: binary switch (0 or 1) equivalent to simply specifying, for example, tabular: 1 in the basic version shown in Listing 26. If delims is set to 0 then the align at ampersand routine will not be called for this code block (default: 1);
  • alignDoubleBackSlash: binary switch (0 or 1) to determine if \\ should be aligned (default: 1);
  • spacesBeforeDoubleBackSlash: optionally, specifies the number (integer \(\geq\) 0) of spaces to be inserted before \\ (default: 1). [2]
  • multiColumnGrouping: binary switch (0 or 1) that details if latexindent.pl should group columns above and below a \multicolumn command (default: 0);
  • alignRowsWithoutMaxDelims: binary switch (0 or 1) that details if rows that do not contain the maximum number of delimeters should be formatted so as to have the ampersands aligned (default: 1);
  • spacesBeforeAmpersand: optionally specifies the number (integer \(\geq\) 0) of spaces to be placed before ampersands (default: 1);
  • spacesAfterAmpersand: optionally specifies the number (integer \(\geq\) 0) of spaces to be placed After ampersands (default: 1);
  • justification: optionally specifies the justification of each cell as either left or right (default: left);
  • alignFinalDoubleBackSlash optionally specifies if the final double back slash should be used for alignment (default: 0);
  • dontMeasure optionally specifies if user-specified cells, rows or the largest entries should not be measured (default: 0);
  • delimiterRegEx optionally specifies the pattern matching to be used for the alignment delimeter (default: `` ‘(?<!\)(&)’``);
  • delimiterJustification optionally specifies the justification for the alignment delimeters (default: left); note that this feature is only useful if you have delimiters of different lengths in the same column, discussed in Section 5.2.

We will explore most of these features using the file tabular2.tex in Listing 30 (which contains a \multicolumn command), and the YAML files in Listing 31Listing 37; we will explore alignFinalDoubleBackSlash in Listing 46; the dontMeasure feature will be described in Section 5.1, and delimiterRegEx in Section 5.2.

Listing 30 tabular2.tex
\begin{tabular}{cccc}
A&    B & C       &D\\
AAA&    BBB & CCC       &DDD\\
  \multicolumn{2}{c}{first heading} & \multicolumn{2}{c}{second heading}\\
one&    two & three       &four\\
five& &six      &\\
seven & \\
\end{tabular}
Listing 31 tabular2.yaml
lookForAlignDelims:
   tabular: 
      multiColumnGrouping: 1
Listing 32 tabular3.yaml
lookForAlignDelims:
   tabular: 
      alignRowsWithoutMaxDelims: 0
Listing 33 tabular4.yaml
lookForAlignDelims:
   tabular: 
      spacesBeforeAmpersand: 4
Listing 34 tabular5.yaml
lookForAlignDelims:
   tabular: 
      spacesAfterAmpersand: 4
Listing 35 tabular6.yaml
lookForAlignDelims:
   tabular: 
      alignDoubleBackSlash: 0
Listing 36 tabular7.yaml
lookForAlignDelims:
   tabular: 
      spacesBeforeDoubleBackSlash: 0
Listing 37 tabular8.yaml
lookForAlignDelims:
   tabular: 
      justification: "right"

On running the commands

 latexindent.pl tabular2.tex
 latexindent.pl tabular2.tex -l tabular2.yaml
 latexindent.pl tabular2.tex -l tabular3.yaml
 latexindent.pl tabular2.tex -l tabular2.yaml,tabular4.yaml
 latexindent.pl tabular2.tex -l tabular2.yaml,tabular5.yaml
 latexindent.pl tabular2.tex -l tabular2.yaml,tabular6.yaml
 latexindent.pl tabular2.tex -l tabular2.yaml,tabular7.yaml
 latexindent.pl tabular2.tex -l tabular2.yaml,tabular8.yaml

we obtain the respective outputs given in Listing 38Listing 45.

Listing 38 tabular2.tex default output
\begin{tabular}{cccc}
	A                                 & B                                  & C     & D    \\
	AAA                               & BBB                                & CCC   & DDD  \\
	\multicolumn{2}{c}{first heading} & \multicolumn{2}{c}{second heading}                \\
	one                               & two                                & three & four \\
	five                              &                                    & six   &      \\
	seven                             &                                                   \\
\end{tabular}
Listing 39 tabular2.tex using Listing 31
\begin{tabular}{cccc}
	A     & B                         & C     & D                          \\
	AAA   & BBB                       & CCC   & DDD                        \\
	\multicolumn{2}{c}{first heading} & \multicolumn{2}{c}{second heading} \\
	one   & two                       & three & four                       \\
	five  &                           & six   &                            \\
	seven &                                                                \\
\end{tabular}
Listing 40 tabular2.tex using Listing 32
\begin{tabular}{cccc}
	A    & B   & C     & D                                                 \\
	AAA  & BBB & CCC   & DDD                                               \\
	\multicolumn{2}{c}{first heading} & \multicolumn{2}{c}{second heading} \\
	one  & two & three & four                                              \\
	five &     & six   &                                                   \\
	seven &                                                                \\
\end{tabular}
Listing 41 tabular2.tex using Listing 31 and Listing 33
\begin{tabular}{cccc}
	A        & B                         & C        & D                       \\
	AAA      & BBB                       & CCC      & DDD                     \\
	\multicolumn{2}{c}{first heading}    & \multicolumn{2}{c}{second heading} \\
	one      & two                       & three    & four                    \\
	five     &                           & six      &                         \\
	seven    &                                                                \\
\end{tabular}
Listing 42 tabular2.tex using Listing 31 and Listing 34
\begin{tabular}{cccc}
	A     &    B                      &    C     &    D                       \\
	AAA   &    BBB                    &    CCC   &    DDD                     \\
	\multicolumn{2}{c}{first heading} &    \multicolumn{2}{c}{second heading} \\
	one   &    two                    &    three &    four                    \\
	five  &                           &    six   &                            \\
	seven &                                                                   \\
\end{tabular}
Listing 43 tabular2.tex using Listing 31 and Listing 35
\begin{tabular}{cccc}
	A     & B                         & C     & D \\
	AAA   & BBB                       & CCC   & DDD \\
	\multicolumn{2}{c}{first heading} & \multicolumn{2}{c}{second heading} \\
	one   & two                       & three & four \\
	five  &                           & six   & \\
	seven & \\
\end{tabular}
Listing 44 tabular2.tex using Listing 31 and Listing 36
\begin{tabular}{cccc}
	A     & B                         & C     & D                         \\
	AAA   & BBB                       & CCC   & DDD                       \\
	\multicolumn{2}{c}{first heading} & \multicolumn{2}{c}{second heading}\\
	one   & two                       & three & four                      \\
	five  &                           & six   &                           \\
	seven &                                                               \\
\end{tabular}
Listing 45 tabular2.tex using Listing 31 and Listing 37
\begin{tabular}{cccc}
	                          A &   B &                           C &    D \\
	                        AAA & BBB &                         CCC &  DDD \\
	\multicolumn{2}{c}{first heading} & \multicolumn{2}{c}{second heading} \\
	                        one & two &                       three & four \\
	                       five &     &                         six &      \\
	                      seven &                                          \\
\end{tabular}

Notice in particular:

  • in both Listing 38 and Listing 39 all rows have been aligned at the ampersand, even those that do not contain the maximum number of ampersands (3 ampersands, in this case);
  • in Listing 38 the columns have been aligned at the ampersand;
  • in Listing 39 the \multicolumn command has grouped the \(2\) columns beneath and above it, because multiColumnGrouping is set to \(1\) in Listing 31;
  • in Listing 40 rows 3 and 6 have not been aligned at the ampersand, because alignRowsWithoutMaxDelims has been to set to \(0\) in Listing 32; however, the \\ have still been aligned;
  • in Listing 41 the columns beneath and above the \multicolumn commands have been grouped (because multiColumnGrouping is set to \(1\)), and there are at least \(4\) spaces before each aligned ampersand because spacesBeforeAmpersand is set to \(4\);
  • in Listing 42 the columns beneath and above the \multicolumn commands have been grouped (because multiColumnGrouping is set to \(1\)), and there are at least \(4\) spaces after each aligned ampersand because spacesAfterAmpersand is set to \(4\);
  • in Listing 43 the \\ have not been aligned, because alignDoubleBackSlash is set to 0, otherwise the output is the same as Listing 39;
  • in Listing 44 the \\ have been aligned, and because spacesBeforeDoubleBackSlash is set to 0, there are no spaces ahead of them; the output is otherwise the same as Listing 39.
  • in Listing 45 the cells have been right-justified; note that cells above and below the \multicol statements have still been group correctly, because of the settings in Listing 31.

We explore the alignFinalDoubleBackSlash feature by using the file in Listing 46. Upon running the following commands

 latexindent.pl tabular4.tex -o=+-default
 latexindent.pl tabular4.tex -o=+-FDBS -y="lookForAlignDelims:tabular:alignFinalDoubleBackSlash:1"

then we receive the respective outputs given in Listing 47 and Listing 48.

Listing 46 tabular4.tex
\begin{tabular}{lc}
    Name & \shortstack{Hi \\ Lo} \\
    Foo  & Bar            \\
\end{tabular}
Listing 47 tabular4-default.tex
\begin{tabular}{lc}
	Name & \shortstack{Hi \\ Lo} \\
	Foo  & Bar            \\
\end{tabular}
Listing 48 tabular4-FDBS.tex
\begin{tabular}{lc}
	Name & \shortstack{Hi \\ Lo} \\
	Foo  & Bar                   \\
\end{tabular}

We note that in:

  • Listing 47, by default, the first set of double back slashes in the first row of the tabular environment have been used for alignment;
  • Listing 48, the final set of double back slashes in the first row have been used, because we specified alignFinalDoubleBackSlash as 1.

As of Version 3.0, the alignment routine works on mandatory and optional arguments within commands, and also within ‘special’ code blocks (see specialBeginEnd on page yaml:specialBeginEnd); for example, assuming that you have a command called \matrix and that it is populated within lookForAlignDelims (which it is, by default), and that you run the command

 latexindent.pl matrix1.tex

then the before-and-after results shown in Listing 49 and Listing 50 are achievable by default.

Listing 49 matrix1.tex
\matrix [
	1&2   &3\\
4&5&6]{
7&8   &9\\
10&11&12
}
Listing 50 matrix1.tex default output
\matrix [
	1 & 2 & 3 \\
	4 & 5 & 6]{
	7  & 8  & 9  \\
	10 & 11 & 12
}

If you have blocks of code that you wish to align at the & character that are not wrapped in, for example, \begin{tabular}\end{tabular}, then you can use the mark up illustrated in Listing 51; the default output is shown in Listing 52. Note that the %* must be next to each other, but that there can be any number of spaces (possibly none) between the * and \begin{tabular}; note also that you may use any environment name that you have specified in lookForAlignDelims.

Listing 51 align-block.tex
%* \begin{tabular}
   1 & 2 & 3 & 4 \\
   5 &   & 6 &   \\
  %* \end{tabular}
Listing 52 align-block.tex default output
%* \begin{tabular}
	1 & 2 & 3 & 4 \\
	5 &   & 6 &   \\
%* \end{tabular}

With reference to Table 1 and the, yet undiscussed, fields of noAdditionalIndent and indentRules (see Section 5.4), these comment-marked blocks are considered environments.

5.1. lookForAlignDelims: the dontMeasure feature

The lookForAlignDelims field can, optionally, receive the dontMeasure option which can be specified in a few different ways. We will explore this feature in relation to the code given in Listing 53; the default output is shown in Listing 54.

Listing 53 tabular-DM.tex
\begin{tabular}{cccc}
  aaaaaa&bbbbb&ccc&dd\\
  11&2&33&4\\
  5&66&7&8
\end{tabular}
Listing 54 tabular-DM.tex default output
\begin{tabular}{cccc}
	aaaaaa & bbbbb & ccc & dd \\
	11     & 2     & 33  & 4  \\
	5      & 66    & 7   & 8
\end{tabular}

The dontMeasure field can be specified as largest, and in which case, the largest element will not be measured; with reference to the YAML file given in Listing 56, we can run the command

 latexindent.pl tabular-DM.tex -l=dontMeasure1.yaml

and receive the output given in Listing 55.

Listing 55 tabular-DM.tex using Listing 56
\begin{tabular}{cccc}
	aaaaaa & bbbbb & ccc & dd \\
	11 & 2  & 33 & 4          \\
	5  & 66 & 7  & 8
\end{tabular}
Listing 56 dontMeasure1.yaml
lookForAlignDelims:
   tabular: 
      dontMeasure: largest

We note that the largest column entries have not contributed to the measuring routine.

The dontMeasure field can also be specified in the form demonstrated in Listing 58. On running the following commands,

 latexindent.pl tabular-DM.tex -l=dontMeasure2.yaml

we receive the output in Listing 57.

Listing 57 tabular-DM.tex using Listing 58 or Listing 60
\begin{tabular}{cccc}
	aaaaaa & bbbbb & ccc & dd \\
	11 & 2  & 33 & 4          \\
	5  & 66 & 7  & 8
\end{tabular}
Listing 58 dontMeasure2.yaml
lookForAlignDelims:
   tabular: 
      dontMeasure:
        - aaaaaa
        - bbbbb
        - ccc
        - dd

We note that in Listing 58 we have specified entries not to be measured, one entry per line.

The dontMeasure field can also be specified in the forms demonstrated in Listing 60 and Listing 61. Upon running the commands

 latexindent.pl tabular-DM.tex -l=dontMeasure3.yaml
 latexindent.pl tabular-DM.tex -l=dontMeasure4.yaml

we receive the output given in Listing 59

Listing 59 tabular-DM.tex using Listing 60 or Listing 60
\begin{tabular}{cccc}
	aaaaaa & bbbbb & ccc & dd \\
	11 & 2  & 33 & 4          \\
	5  & 66 & 7  & 8
\end{tabular}
Listing 60 dontMeasure3.yaml
lookForAlignDelims:
   tabular: 
      dontMeasure:
        - 
          this: aaaaaa
          applyTo: cell
        - 
          this: bbbbb
        - ccc
        - dd
Listing 61 dontMeasure4.yaml
lookForAlignDelims:
   tabular: 
      dontMeasure:
        - 
          regex: [a-z]
          applyTo: cell

We note that in:

  • Listing 60 we have specified entries not to be measured, each one has a string in the this field, together with an optional specification of applyTo as cell;
  • Listing 61 we have specified entries not to be measured as a regular expression using the regex field, together with an optional specification of applyTo as cell field, together with an optional specification of applyTo as cell.

In both cases, the default value of applyTo is cell, and does not need to be specified.

We may also specify the applyTo field as row, a demonstration of which is given in Listing 63; upon running

 latexindent.pl tabular-DM.tex -l=dontMeasure5.yaml

we receive the output in Listing 62.

Listing 62 tabular-DM.tex using Listing 63
\begin{tabular}{cccc}
	aaaaaa & bbbbb & ccc & dd \\
	11 & 2  & 33 & 4          \\
	5  & 66 & 7  & 8
\end{tabular}
Listing 63 dontMeasure5.yaml
lookForAlignDelims:
   tabular: 
      dontMeasure:
        - 
          this: aaaaaa&bbbbb&ccc&dd\\
          applyTo: row

Finally, the applyTo field can be specified as row, together with a regex expression. For example, for the settings given in Listing 65, upon running

 latexindent.pl tabular-DM.tex -l=dontMeasure6.yaml

we receive the output in Listing 64.

Listing 64 tabular-DM.tex using Listing 65
\begin{tabular}{cccc}
	aaaaaa & bbbbb & ccc & dd \\
	11 & 2  & 33 & 4          \\
	5  & 66 & 7  & 8
\end{tabular}
Listing 65 dontMeasure6.yaml
lookForAlignDelims:
   tabular: 
      dontMeasure:
        - 
          regex: [a-z]
          applyTo: row

5.2. lookForAlignDelims: the delimiterRegEx and delimiterJustification feature

The delimiter alignment will, by default, align code blocks at the ampersand character. The behaviour is controlled by the delimiterRegEx field within lookForAlignDelims; the default value is '(?<!\\)(&)', which can be read as: an ampersand, as long as it is not immediately preceeded by a backslash.

Warning

Important: note the ‘capturing’ parenthesis in the (&) which are necessary; if you intend to customise this field, then be sure to include them appropriately.

We demonstrate how to customise this with respect to the code given in Listing 66; the default output from latexindent.pl is given in Listing 67.

Listing 66 tabbing.tex
\begin{tabbing}
    aa \=   bb \= cc \= dd \= ee \\
    \>2\> 1 \> 7 \> 3 \\
    \>3 \> 2\>8\> 3 \\
    \>4 \>2 \\
\end{tabbing}
Listing 67 tabbing.tex default output
\begin{tabbing}
	aa \=   bb \= cc \= dd \= ee \\
	\>2\> 1 \> 7 \> 3 \\
	\>3 \> 2\>8\> 3 \\
	\>4 \>2 \\
\end{tabbing}

Let’s say that we wish to align the code at either the \= or \>. We employ the settings given in Listing 69 and run the command

 latexindent.pl tabbing.tex -l=delimiterRegEx1.yaml

to receive the output given in Listing 68.

Listing 68 tabbing.tex using Listing 69
\begin{tabbing}
	aa \= bb \= cc \= dd \= ee \\
	   \> 2  \> 1  \> 7  \> 3  \\
	   \> 3  \> 2  \> 8  \> 3  \\
	   \> 4  \> 2              \\
\end{tabbing}
Listing 69 delimiterRegEx1.yaml
lookForAlignDelims:
   tabbing: 
    delimiterRegEx: '(\\(?:=|>))'

We note that:

  • in Listing 68 the code has been aligned, as intended, at both the \= and \>;
  • in Listing 69 we have heeded the warning and captured the expression using grouping parenthesis, specified a backslash using \\ and said that it must be followed by either = or >.

We can explore delimiterRegEx a little further using the settings in Listing 71 and run the command

 latexindent.pl tabbing.tex -l=delimiterRegEx2.yaml

to receive the output given in Listing 70.

Listing 70 tabbing.tex using Listing 71
\begin{tabbing}
	aa \=   bb \= cc \= dd \= ee \\
	 \> 2 \> 1 \> 7 \> 3         \\
	 \> 3 \> 2 \> 8 \> 3         \\
	 \> 4 \> 2                   \\
\end{tabbing}
Listing 71 delimiterRegEx2.yaml
lookForAlignDelims:
   tabbing: 
    delimiterRegEx: '(\\>)'

We note that only the \> have been aligned.

Of course, the other lookForAlignDelims options can be used alongside the delimiterRegEx; regardless of the type of delimiter being used (ampersand or anything else), the fields from Listing 29 remain the same; for example, using the settings in Listing 73, and running

 latexindent.pl tabbing.tex -l=delimiterRegEx3.yaml

to receive the output given in Listing 72.

Listing 72 tabbing.tex using Listing 73
\begin{tabbing}
	aa\=bb\=cc\=dd\=ee \\
	  \>2 \>1 \>7 \>3  \\
	  \>3 \>2 \>8 \>3  \\
	  \>4 \>2          \\
\end{tabbing}
Listing 73 delimiterRegEx3.yaml
lookForAlignDelims:
   tabbing: 
    delimiterRegEx: '(\\(?:=|>))'
    spacesBeforeAmpersand: 0
    spacesAfterAmpersand: 0

It is possible that delimiters specified within delimiterRegEx can be of different lengths. Consider the file in Listing 74, and associated YAML in Listing 76. Note that the Listing 76 specifies the option for the delimiter to be either # or \>, which are different lengths. Upon running the command

 latexindent.pl tabbing1.tex -l=delimiterRegEx4.yaml -o=+-mod4

we receive the output in Listing 75.

Listing 74 tabbing1.tex
\begin{tabbing}
    1#22\>333\\
    xxx#aaa#yyyyy\\
    .##&\\
\end{tabbing}
Listing 75 tabbing1-mod4.tex
\begin{tabbing}
	1   # 22  \> 333   \\
	xxx # aaa #  yyyyy \\
	.   #     #  &     \\
\end{tabbing}
Listing 76 delimiterRegEx4.yaml
lookForAlignDelims:
   tabbing: 
    delimiterRegEx: '(#|\\>)'

You can set the delimiter justification as either left (default) or right, which will only have effect when delimiters in the same column have different lengths. Using the settings in Listing 78 and running the command

 latexindent.pl tabbing1.tex -l=delimiterRegEx5.yaml -o=+-mod5

gives the output in Listing 77.

Listing 77 tabbing1-mod5.tex
\begin{tabbing}
	1   # 22  \> 333   \\
	xxx # aaa  # yyyyy \\
	.   #      # &     \\
\end{tabbing}
Listing 78 delimiterRegEx5.yaml
lookForAlignDelims:
   tabbing: 
    delimiterRegEx: '(#|\\>)'
    delimiterJustification: right

Note that in Listing 77 the second set of delimiters have been right aligned – it is quite subtle!

indentAfterItems:fields

The environment names specified in indentAfterItems tell latexindent.pl to look for \item commands; if these switches are set to 1 then indentation will be performed so as indent the code after each item. A demonstration is given in Listing 80 and Listing 81

Listing 79 indentAfterItems
191
192
193
194
195
indentAfterItems:
    itemize: 1
    enumerate: 1
    description: 1
    list: 1
Listing 80 items1.tex
\begin{itemize}
\item some text here
some more text here
some more text here
\item another item
some more text here
\end{itemize}
Listing 81 items1.tex default output
\begin{itemize}
	\item some text here
	      some more text here
	      some more text here
	\item another item
	      some more text here
\end{itemize}
itemNames:fields
If you have your own item commands (perhaps you prefer to use myitem, for example) then you can put populate them in itemNames. For example, users of the exam document class might like to add parts to indentAfterItems and part to itemNames to their user settings (see Section 4 for details of how to configure user settings, and Listing 13
in particular

.)

Listing 82 itemNames
201
202
203
itemNames:
    item: 1
    myitem: 1
specialBeginEnd:fields

The fields specified in specialBeginEnd are, in their default state, focused on math mode begin and end statements, but there is no requirement for this to be the case; Listing 83 shows the default settings of specialBeginEnd.

Listing 83 specialBeginEnd
207
208
209
210
211
212
213
214
215
216
217
218
219
220
specialBeginEnd:
    displayMath:
        begin: '\\\['
        end: '\\\]'
        lookForThis: 1
    inlineMath:
        begin: '(?<!\$)(?<!\\)\$(?!\$)'
        end: '(?<!\\)\$(?!\$)'
        lookForThis: 1
    displayMathTeX:
        begin: '\$\$'
        end: '\$\$'
        lookForThis: 1
    specialBeforeCommand: 0

The field displayMath represents \[...\], inlineMath represents $...$ and displayMathTex represents $$...$$. You can, of course, rename these in your own YAML files (see Section 4.2); indeed, you might like to set up your own special begin and end statements.

A demonstration of the before-and-after results are shown in Listing 84 and Listing 85.

Listing 84 special1.tex before
The function $f$ has formula
\[
f(x)=x^2.
\]
If you like splitting dollars,
$
g(x)=f(2x)
$
Listing 85 special1.tex default output
The function $f$ has formula
\[
	f(x)=x^2.
\]
If you like splitting dollars,
$
	g(x)=f(2x)
$

For each field, lookForThis is set to 1 by default, which means that latexindent.pl will look for this pattern; you can tell latexindent.pl not to look for the pattern, by setting lookForThis to 0.

There are examples in which it is advantageous to search for specialBeginEnd fields before searching for commands, and the specialBeforeCommand switch controls this behaviour. For example, consider the file shown in Listing 86.

Listing 86 specialLR.tex
\begin{equation}
\left[
\sqrt{
a+b
}
\right]
\end{equation}

Now consider the YAML files shown in Listing 87 and Listing 88

Listing 87 specialsLeftRight.yaml
specialBeginEnd:
    leftRightSquare:
        begin: '\\left\['
        end: '\\right\]'
        lookForThis: 1
Listing 88 specialBeforeCommand.yaml
specialBeginEnd:
    specialBeforeCommand: 1

Upon running the following commands

 latexindent.pl specialLR.tex -l=specialsLeftRight.yaml
 latexindent.pl specialLR.tex -l=specialsLeftRight.yaml,specialBeforeCommand.yaml

we receive the respective outputs in Listing 89 and Listing 90.

Listing 89 specialLR.tex using Listing 87
\begin{equation}
	\left[
		\sqrt{
			a+b
		}
		\right]
\end{equation}
Listing 90 specialLR.tex using Listing 87 and Listing 88
\begin{equation}
	\left[
		\sqrt{
			a+b
		}
	\right]
\end{equation}

Notice that in:

  • Listing 89 the \left has been treated as a command, with one optional argument;
  • Listing 90 the specialBeginEnd pattern in Listing 87 has been obeyed because Listing 88 specifies that the specialBeginEnd should be sought before commands.

You can,optionally, specify the middle field for anything that you specify in specialBeginEnd. For example, let’s consider the .tex file in Listing 91.

Listing 91 special2.tex
\If
something 0
\ElsIf 
something 1 
\ElsIf
something 2 
\ElsIf
something 3
\Else
something 4
\EndIf

Upon saving the YAML settings in Listing 92 and Listing 94 and running the commands

 latexindent.pl special2.tex -l=middle
 latexindent.pl special2.tex -l=middle1

then we obtain the output given in Listing 93 and Listing 95.

Listing 92 middle.yaml
specialBeginEnd:
    If:
        begin: '\\If'
        middle: '\\ElsIf'
        end: '\\EndIf'
        lookForThis: 1
Listing 93 special2.tex using Listing 92
\If
	something 0
\ElsIf
	something 1
\ElsIf
	something 2
\ElsIf
	something 3
	\Else
	something 4
\EndIf
Listing 94 middle1.yaml
specialBeginEnd:
    If:
        begin: '\\If'
        middle: 
          - '\\ElsIf'
          - '\\Else'
        end: '\\EndIf'
        lookForThis: 1
Listing 95 special2.tex using Listing 94
\If
	something 0
\ElsIf
	something 1
\ElsIf
	something 2
\ElsIf
	something 3
\Else
	something 4
\EndIf

We note that:

  • in Listing 93 the bodies of each of the Elsif statements have been indented appropriately;
  • the Else statement has not been indented appropriately in Listing 93 – read on!
  • we have specified multiple settings for the middle field using the syntax demonstrated in Listing 94 so that the body of the Else statement has been indented appropriately in Listing 95.

You may specify fields in specialBeginEnd to be treated as verbatim code blocks by changing lookForThis to be verbatim.

For example, beginning with the code in Listing 97 and the YAML in Listing 96, and running

 latexindent.pl special3.tex -l=special-verb1

then the output in Listing 97 is unchanged.

Listing 96 special-verb1.yaml
specialBeginEnd:
    displayMath:
        lookForThis: verbatim
Listing 97 special3.tex and output using Listing 96
\[
  special code 
blocks
    can be
  treated
    as verbatim\]
indentAfterHeadings:fields

This field enables the user to specify indentation rules that take effect after heading commands such as \part, \chapter, \section, \subsection*, or indeed any user-specified command written in this field. [3]

Listing 98 indentAfterHeadings
230
231
232
233
234
235
236
237
238
239
indentAfterHeadings:
    part:
       indentAfterThisHeading: 0
       level: 1
    chapter: 
       indentAfterThisHeading: 0
       level: 2
    section:
       indentAfterThisHeading: 0
       level: 3

The default settings do not place indentation after a heading, but you can easily switch them on by changing indentAfterThisHeading from 0 to 1. The level field tells latexindent.pl the hierarchy of the heading structure in your document. You might, for example, like to have both section and subsection set with level: 3 because you do not want the indentation to go too deep.

You can add any of your own custom heading commands to this field, specifying the level as appropriate. You can also specify your own indentation in indentRules (see Section 5.4); you will find the default indentRules contains chapter: " " which tells latexindent.pl simply to use a space character after headings (once indent is set to 1 for chapter).

For example, assuming that you have the code in Listing 99 saved into headings1.yaml, and that you have the text from Listing 100 saved into headings1.tex.

Listing 99 headings1.yaml
indentAfterHeadings:
    subsection:
       indentAfterThisHeading: 1
       level: 1
    paragraph:
       indentAfterThisHeading: 1
       level: 2
Listing 100 headings1.tex
\subsection{subsection title}
subsection text
subsection text
\paragraph{paragraph title}
paragraph text
paragraph text
\paragraph{paragraph title}
paragraph text
paragraph text

If you run the command

 latexindent.pl headings1.tex -l=headings1.yaml

then you should receive the output given in Listing 101.

Listing 101 headings1.tex using Listing 99
\subsection{subsection title}
	subsection text
	subsection text
	\paragraph{paragraph title}
		paragraph text
		paragraph text
	\paragraph{paragraph title}
		paragraph text
		paragraph text
Listing 102 headings1.tex second modification
\subsection{subsection title}
	subsection text
	subsection text
\paragraph{paragraph title}
	paragraph text
	paragraph text
\paragraph{paragraph title}
	paragraph text
	paragraph text

Now say that you modify the YAML from Listing 99 so that the paragraph level is 1; after running

 latexindent.pl headings1.tex -l=headings1.yaml

you should receive the code given in Listing 102; notice that the paragraph and subsection are at the same indentation level.

maximumIndentation:horizontal space

You can control the maximum indentation given to your file by specifying the maximumIndentation field as horizontal space (but not including tabs). This feature uses the Text::Tabs module (“Text::Tabs Perl Module” 2017), and is off by default.

For example, consider the example shown in Listing 103 together with the default output shown in Listing 104.

Listing 103 mult-nested.tex
\begin{one}
one
\begin{two}
    two
\begin{three}
     three 
\begin{four}
       four
\end{four}
\end{three}
\end{two}
\end{one}
Listing 104 mult-nested.tex default output
\begin{one}
	one
	\begin{two}
		two
		\begin{three}
			three
			\begin{four}
				four
			\end{four}
		\end{three}
	\end{two}
\end{one}

Now say that, for example, you have the max-indentation1.yaml from Listing 105 and that you run the following command:

 latexindent.pl mult-nested.tex -l=max-indentation1

You should receive the output shown in Listing 106.

Listing 105 max-indentation1.yaml
maximumIndentation: " "
Listing 106 mult-nested.tex using Listing 105
\begin{one}
 one
 \begin{two}
 two
 \begin{three}
 three
 \begin{four}
 four
 \end{four}
 \end{three}
 \end{two}
\end{one}

Comparing the output in Listing 104 and Listing 106 we notice that the (default) tabs of indentation have been replaced by a single space.

In general, when using the maximumIndentation feature, any leading tabs will be replaced by equivalent spaces except, of course, those found in verbatimEnvironments (see Listing 17) or noIndentBlock (see Listing 19).

5.3. The code blocks known latexindent.pl

As of Version 3.0, latexindent.pl processes documents using code blocks; each of these are shown in Table 1.

Table 1 Code blocks known to latexindent.pl
Code block characters allowed in name example
environments a-zA-Z@\*0-9_\\ \begin{myenv}body of myenv\end{myenv}
optionalArguments inherits name from parent (e.g environment name) [opt arg text]
mandatoryArguments inherits name from parent (e.g environment name) {mand arg text}
commands +a-zA-Z@\*0-9_\: \mycommand<arguments>
keyEqualsValuesBracesBrackets a-zA-Z@\*0-9_\/.\h\{\}:\#- my key/.style=<arguments>
namedGroupingBracesBrackets 0-9\.a-zA-Z@\*>< in<arguments>
UnNamedGroupingBracesBrackets No name! { or [ or , or & or ) or ( or $ followed by <arguments>
ifElseFi @a-zA-Z but must begin with either \if of \@if \ifnum......\else...\fi
items User specified, see Listing 79 and Listing 82 \begin{enumerate}  \item ...\end{enumerate}
specialBeginEnd User specified, see Listing 83 \[  ...\]
afterHeading User specified, see Listing 98 \chapter{title}  ...\section{title}
filecontents User specified, see Listing 23 \begin{filecontents}...\end{filecontents}

We will refer to these code blocks in what follows. Note that the fine tuning of the definition of the code blocks detailed in Table 1 is discussed in Section 8.

5.4. noAdditionalIndent and indentRules

latexindent.pl operates on files by looking for code blocks, as detailed in Section 5.3; for each type of code block in Table 1 (which we will call a <thing> in what follows) it searches YAML fields for information in the following order:

  1. noAdditionalIndent for the name of the current <thing>;
  2. indentRules for the name of the current <thing>;
  3. noAdditionalIndentGlobal for the type of the current <thing>;
  4. indentRulesGlobal for the type of the current <thing>.

Using the above list, the first piece of information to be found will be used; failing that, the value of defaultIndent is used. If information is found in multiple fields, the first one according to the list above will be used; for example, if information is present in both indentRules and in noAdditionalIndentGlobal, then the information from indentRules takes priority.

We now present details for the different type of code blocks known to latexindent.pl, as detailed in Table 1; for reference, there follows a list of the code blocks covered.

5.4.1. Environments and their arguments

There are a few different YAML switches governing the indentation of environments; let’s start with the code shown in Listing 107.

Listing 107 myenv.tex
\begin{outer}
\begin{myenv}
  body of environment
body of environment
     body of environment
\end{myenv}
\end{outer}
noAdditionalIndent:fields

If we do not wish myenv to receive any additional indentation, we have a few choices available to us, as demonstrated in Listing 108 and Listing 109.

Listing 108 myenv-noAdd1.yaml
noAdditionalIndent:
    myenv: 1
Listing 109 myenv-noAdd2.yaml
noAdditionalIndent:
    myenv: 
        body: 1

On applying either of the following commands,

 latexindent.pl myenv.tex -l myenv-noAdd1.yaml
 latexindent.pl myenv.tex -l myenv-noAdd2.yaml

we obtain the output given in Listing 110; note in particular that the environment myenv has not received any additional indentation, but that the outer environment has still received indentation.

Listing 110 myenv.tex output (using either Listing 108 or Listing 109)
\begin{outer}
	\begin{myenv}
	body of environment
	body of environment
	body of environment
	\end{myenv}
\end{outer}

Upon changing the YAML files to those shown in Listing 111 and Listing 112, and running either

 latexindent.pl myenv.tex -l myenv-noAdd3.yaml
 latexindent.pl myenv.tex -l myenv-noAdd4.yaml

we obtain the output given in Listing 113.

Listing 111 myenv-noAdd3.yaml
noAdditionalIndent:
    myenv: 0
Listing 112 myenv-noAdd4.yaml
noAdditionalIndent:
    myenv: 
        body: 0
Listing 113 myenv.tex output (using either Listing 111 or Listing 112)
\begin{outer}
	\begin{myenv}
		body of environment
		body of environment
		body of environment
	\end{myenv}
\end{outer}

Let’s now allow myenv to have some optional and mandatory arguments, as in Listing 114.

Listing 114 myenv-args.tex
\begin{outer}
\begin{myenv}[%
  optional argument text
        optional argument text]%
  { mandatory argument text
 mandatory argument text}
  body of environment
body of environment
     body of environment
\end{myenv}
\end{outer}

Upon running

 latexindent.pl -l=myenv-noAdd1.yaml myenv-args.tex

we obtain the output shown in Listing 115; note that the optional argument, mandatory argument and body all have received no additional indent. This is because, when noAdditionalIndent is specified in ‘scalar’ form (as in Listing 108), then all parts of the environment (body, optional and mandatory arguments) are assumed to want no additional indent.

Listing 115 myenv-args.tex using Listing 108
\begin{outer}
	\begin{myenv}[%
	optional argument text
	optional argument text]%
	{ mandatory argument text
	mandatory argument text}
	body of environment
	body of environment
	body of environment
	\end{myenv}
\end{outer}

We may customise noAdditionalIndent for optional and mandatory arguments of the myenv environment, as shown in, for example, Listing 116 and Listing 117.

Listing 116 myenv-noAdd5.yaml
noAdditionalIndent:
    myenv: 
        body: 0
        optionalArguments: 1
        mandatoryArguments: 0
Listing 117 myenv-noAdd6.yaml
noAdditionalIndent:
    myenv: 
        body: 0
        optionalArguments: 0
        mandatoryArguments: 1

Upon running

 latexindent.pl myenv.tex -l myenv-noAdd5.yaml
 latexindent.pl myenv.tex -l myenv-noAdd6.yaml

we obtain the respective outputs given in Listing 118 and Listing 119. Note that in Listing 118 the text for the optional argument has not received any additional indentation, and that in Listing 119 the mandatory argument has not received any additional indentation; in both cases, the body has not received any additional indentation.

Listing 118 myenv-args.tex using Listing 116
\begin{outer}
	\begin{myenv}[%
		optional argument text
		optional argument text]%
		{ mandatory argument text
			mandatory argument text}
		body of environment
		body of environment
		body of environment
	\end{myenv}
\end{outer}
Listing 119 myenv-args.tex using Listing 117
\begin{outer}
	\begin{myenv}[%
			optional argument text
			optional argument text]%
		{ mandatory argument text
		mandatory argument text}
		body of environment
		body of environment
		body of environment
	\end{myenv}
\end{outer}
indentRules:fields

We may also specify indentation rules for environment code blocks using the indentRules field; see, for example, Listing 120 and Listing 121.

Listing 120 myenv-rules1.yaml
indentRules:
    myenv: "   "
Listing 121 myenv-rules2.yaml
indentRules:
    myenv: 
        body: "   "

On applying either of the following commands,

 latexindent.pl myenv.tex -l myenv-rules1.yaml
 latexindent.pl myenv.tex -l myenv-rules2.yaml

we obtain the output given in Listing 122; note in particular that the environment myenv has received one tab (from the outer environment) plus three spaces from Listing 120 or Listing 121.

Listing 122 myenv.tex output (using either Listing 120 or Listing 121)
\begin{outer}
	\begin{myenv}
	   body of environment
	   body of environment
	   body of environment
	\end{myenv}
\end{outer}

If you specify a field in indentRules using anything other than horizontal space, it will be ignored.

Returning to the example in Listing 114 that contains optional and mandatory arguments. Upon using Listing 120 as in

 latexindent.pl myenv-args.tex -l=myenv-rules1.yaml

we obtain the output in Listing 123; note that the body, optional argument and mandatory argument of myenv have all received the same customised indentation.

Listing 123 myenv-args.tex using Listing 120
\begin{outer}
	\begin{myenv}[%
	      optional argument text
	      optional argument text]%
	   { mandatory argument text
	      mandatory argument text}
	   body of environment
	   body of environment
	   body of environment
	\end{myenv}
\end{outer}

You can specify different indentation rules for the different features using, for example, Listing 124 and Listing 125

Listing 124 myenv-rules3.yaml
indentRules:
    myenv: 
        body: "   "
        optionalArguments: " "
Listing 125 myenv-rules4.yaml
indentRules:
    myenv: 
        body: "   "
        mandatoryArguments: "\t\t"

After running

 latexindent.pl myenv-args.tex -l myenv-rules3.yaml
 latexindent.pl myenv-args.tex -l myenv-rules4.yaml

then we obtain the respective outputs given in Listing 126 and Listing 127.

Listing 126 myenv-args.tex using Listing 124
\begin{outer}
	\begin{myenv}[%
	    optional argument text
	    optional argument text]%
	   { mandatory argument text
		   mandatory argument text}
	   body of environment
	   body of environment
	   body of environment
	\end{myenv}
\end{outer}
Listing 127 myenv-args.tex using Listing 125
\begin{outer}
	\begin{myenv}[%
		   optional argument text
		   optional argument text]%
	   { mandatory argument text
			   mandatory argument text}
	   body of environment
	   body of environment
	   body of environment
	\end{myenv}
\end{outer}

Note that in Listing 126, the optional argument has only received a single space of indentation, while the mandatory argument has received the default (tab) indentation; the environment body has received three spaces of indentation.

In Listing 127, the optional argument has received the default (tab) indentation, the mandatory argument has received two tabs of indentation, and the body has received three spaces of indentation.

noAdditionalIndentGlobal:fields
Listing 128 noAdditionalIndentGlobal
288
289
noAdditionalIndentGlobal:
    environments: 0

Assuming that your environment name is not found within neither noAdditionalIndent nor indentRules, the next place that latexindent.pl will look is noAdditionalIndentGlobal, and in particular for the environments key (see Listing 128). Let’s say that you change the value of environments to 1 in Listing 128, and that you run

 latexindent.pl myenv-args.tex -l env-noAdditionalGlobal.yaml
 latexindent.pl myenv-args.tex -l myenv-rules1.yaml,env-noAdditionalGlobal.yaml

The respective output from these two commands are in Listing 129 and Listing 130; in Listing 129 notice that both environments receive no additional indentation but that the arguments of myenv still do receive indentation. In Listing 130 notice that the outer environment does not receive additional indentation, but because of the settings from myenv-rules1.yaml (in Listing 120), the myenv environment still does receive indentation.

Listing 129 myenv-args.tex using Listing 128
\begin{outer}
\begin{myenv}[%
	optional argument text
	optional argument text]%
{ mandatory argument text
	mandatory argument text}
body of environment
body of environment
body of environment
\end{myenv}
\end{outer}
Listing 130 myenv-args.tex using Listing 128 and Listing 120
\begin{outer}
\begin{myenv}[%
      optional argument text
      optional argument text]%
   { mandatory argument text
      mandatory argument text}
   body of environment
   body of environment
   body of environment
\end{myenv}
\end{outer}

In fact, noAdditionalIndentGlobal also contains keys that control the indentation of optional and mandatory arguments; on referencing Listing 131 and Listing 132

Listing 131 opt-args-no-add-glob.yaml
noAdditionalIndentGlobal:
    optionalArguments: 1
Listing 132 mand-args-no-add-glob.yaml
noAdditionalIndentGlobal:
    mandatoryArguments: 1

we may run the commands

 latexindent.pl myenv-args.tex -local opt-args-no-add-glob.yaml
 latexindent.pl myenv-args.tex -local mand-args-no-add-glob.yaml

which produces the respective outputs given in Listing 133 and Listing 134. Notice that in Listing 133 the optional argument has not received any additional indentation, and in Listing 134 the mandatory argument has not received any additional indentation.

Listing 133 myenv-args.tex using Listing 131
\begin{outer}
	\begin{myenv}[%
		optional argument text
		optional argument text]%
		{ mandatory argument text
			mandatory argument text}
		body of environment
		body of environment
		body of environment
	\end{myenv}
\end{outer}
Listing 134 myenv-args.tex using Listing 132
\begin{outer}
	\begin{myenv}[%
			optional argument text
			optional argument text]%
		{ mandatory argument text
		mandatory argument text}
		body of environment
		body of environment
		body of environment
	\end{myenv}
\end{outer}
indentRulesGlobal:fields
Listing 135 indentRulesGlobal
304
305
indentRulesGlobal:
    environments: 0

The final check that latexindent.pl will make is to look for indentRulesGlobal as detailed in Listing 135; if you change the environments field to anything involving horizontal space, say " ", and then run the following commands

 latexindent.pl myenv-args.tex -l env-indentRules.yaml
 latexindent.pl myenv-args.tex -l myenv-rules1.yaml,env-indentRules.yaml

then the respective output is shown in Listing 136 and Listing 137. Note that in Listing 136, both the environment blocks have received a single-space indentation, whereas in Listing 137 the outer environment has received single-space indentation (specified by indentRulesGlobal), but myenv has received "   ", as specified by the particular indentRules for myenv Listing 120.

Listing 136 myenv-args.tex using Listing 135
\begin{outer}
 \begin{myenv}[%
	  optional argument text
	  optional argument text]%
  { mandatory argument text
	  mandatory argument text}
  body of environment
  body of environment
  body of environment
 \end{myenv}
\end{outer}
Listing 137 myenv-args.tex using Listing 120 and Listing 135
\begin{outer}
 \begin{myenv}[%
       optional argument text
       optional argument text]%
    { mandatory argument text
       mandatory argument text}
    body of environment
    body of environment
    body of environment
 \end{myenv}
\end{outer}

You can specify indentRulesGlobal for both optional and mandatory arguments, as detailed in Listing 138 and Listing 139

Listing 138 opt-args-indent-rules-glob.yaml
indentRulesGlobal:
    optionalArguments: "\t\t"
Listing 139 mand-args-indent-rules-glob.yaml
indentRulesGlobal:
    mandatoryArguments: "\t\t"

Upon running the following commands

 latexindent.pl myenv-args.tex -local opt-args-indent-rules-glob.yaml
 latexindent.pl myenv-args.tex -local mand-args-indent-rules-glob.yaml

we obtain the respective outputs in Listing 140 and Listing 141. Note that the optional argument in Listing 140 has received two tabs worth of indentation, while the mandatory argument has done so in Listing 141.

Listing 140 myenv-args.tex using Listing 138
\begin{outer}
	\begin{myenv}[%
				optional argument text
				optional argument text]%
		{ mandatory argument text
			mandatory argument text}
		body of environment
		body of environment
		body of environment
	\end{myenv}
\end{outer}
Listing 141 myenv-args.tex using Listing 139
\begin{outer}
	\begin{myenv}[%
			optional argument text
			optional argument text]%
		{ mandatory argument text
				mandatory argument text}
		body of environment
		body of environment
		body of environment
	\end{myenv}
\end{outer}

5.4.2. Environments with items

With reference to Listing 79 and Listing 82, some commands may contain item commands; for the purposes of this discussion, we will use the code from Listing 80.

Assuming that you’ve populated itemNames with the name of your item, you can put the item name into noAdditionalIndent as in Listing 142, although a more efficient approach may be to change the relevant field in itemNames to 0. Similarly, you can customise the indentation that your item receives using indentRules, as in Listing 143

Listing 142 item-noAdd1.yaml
noAdditionalIndent:
    item: 1
# itemNames:
#   item: 0
Listing 143 item-rules1.yaml
indentRules:
    item: " "

Upon running the following commands

 latexindent.pl items1.tex -local item-noAdd1.yaml
 latexindent.pl items1.tex -local item-rules1.yaml

the respective outputs are given in Listing 144 and Listing 145; note that in Listing 144 that the text after each item has not received any additional indentation, and in Listing 145, the text after each item has received a single space of indentation, specified by Listing 143.

Listing 144 items1.tex using Listing 142
\begin{itemize}
	\item some text here
	some more text here
	some more text here
	\item another item
	some more text here
\end{itemize}
Listing 145 items1.tex using Listing 143
\begin{itemize}
	\item some text here
	 some more text here
	 some more text here
	\item another item
	 some more text here
\end{itemize}

Alternatively, you might like to populate noAdditionalIndentGlobal or indentRulesGlobal using the items key, as demonstrated in Listing 146 and Listing 147. Note that there is a need to ‘reset/remove’ the item field from indentRules in both cases (see the hierarchy description given on page sec:noadd-indent-rules) as the item command is a member of indentRules by default.

Listing 146 items-noAdditionalGlobal.yaml
indentRules:
    item: 0
noAdditionalIndentGlobal:
    items: 1
Listing 147 items-indentRulesGlobal.yaml
indentRules:
    item: 0
indentRulesGlobal:
    items: " "

Upon running the following commands,

 latexindent.pl items1.tex -local items-noAdditionalGlobal.yaml
 latexindent.pl items1.tex -local items-indentRulesGlobal.yaml

the respective outputs from Listing 144 and Listing 145 are obtained; note, however, that all such item commands without their own individual noAdditionalIndent or indentRules settings would behave as in these listings.

5.4.3. Commands with arguments

Let’s begin with the simple example in Listing 148; when latexindent.pl operates on this file, the default output is shown in Listing 149. [4]

Listing 148 mycommand.tex
\mycommand
{
mand arg text
mand arg text}
[
opt arg text
opt arg text
]
Listing 149 mycommand.tex default output
\mycommand
{
	mand arg text
	mand arg text}
[
	opt arg text
	opt arg text
]

As in the environment-based case (see Listing 108 and Listing 109) we may specify noAdditionalIndent either in ‘scalar’ form, or in ‘field’ form, as shown in Listing 150 and Listing 151

Listing 150 mycommand-noAdd1.yaml
noAdditionalIndent:
    mycommand: 1
Listing 151 mycommand-noAdd2.yaml
noAdditionalIndent:
    mycommand: 
        body: 1

After running the following commands,

 latexindent.pl mycommand.tex -l mycommand-noAdd1.yaml
 latexindent.pl mycommand.tex -l mycommand-noAdd2.yaml

we receive the respective output given in Listing 152 and Listing 153

Listing 152 mycommand.tex using Listing 150
\mycommand
{
mand arg text
mand arg text}
[
opt arg text
opt arg text
]
Listing 153 mycommand.tex using Listing 151
\mycommand
{
	mand arg text
	mand arg text}
[
	opt arg text
	opt arg text
]

Note that in Listing 152 that the ‘body’, optional argument and mandatory argument have all received no additional indentation, while in Listing 153, only the ‘body’ has not received any additional indentation. We define the ‘body’ of a command as any lines following the command name that include its optional or mandatory arguments.

We may further customise noAdditionalIndent for mycommand as we did in Listing 116 and Listing 117; explicit examples are given in Listing 154 and Listing 155.

Listing 154 mycommand-noAdd3.yaml
noAdditionalIndent:
    mycommand:
        body: 0
        optionalArguments: 1
        mandatoryArguments: 0
Listing 155 mycommand-noAdd4.yaml
noAdditionalIndent:
    mycommand:
        body: 0
        optionalArguments: 0
        mandatoryArguments: 1

After running the following commands,

 latexindent.pl mycommand.tex -l mycommand-noAdd3.yaml
 latexindent.pl mycommand.tex -l mycommand-noAdd4.yaml

we receive the respective output given in Listing 156 and Listing 157.

Listing 156 mycommand.tex using Listing 154
\mycommand
{
	mand arg text
	mand arg text}
[
opt arg text
opt arg text
]
Listing 157 mycommand.tex using Listing 155
\mycommand
{
mand arg text
mand arg text}
[
	opt arg text
	opt arg text
]

Attentive readers will note that the body of mycommand in both Listing 156 and Listing 157 has received no additional indent, even though body is explicitly set to 0 in both Listing 154 and Listing 155. This is because, by default, noAdditionalIndentGlobal for commands is set to 1 by default; this can be easily fixed as in Listing 158 and Listing 159.

Listing 158 mycommand-noAdd5.yaml
noAdditionalIndent:
    mycommand:
        body: 0
        optionalArguments: 1
        mandatoryArguments: 0
noAdditionalIndentGlobal:
    commands: 0
Listing 159 mycommand-noAdd6.yaml
noAdditionalIndent:
    mycommand:
        body: 0
        optionalArguments: 0
        mandatoryArguments: 1
noAdditionalIndentGlobal:
    commands: 0

After running the following commands,

 latexindent.pl mycommand.tex -l mycommand-noAdd5.yaml
 latexindent.pl mycommand.tex -l mycommand-noAdd6.yaml

we receive the respective output given in Listing 160 and Listing 161.

Listing 160 mycommand.tex using Listing 158
\mycommand
	{
		mand arg text
		mand arg text}
	[
	opt arg text
	opt arg text
	]
Listing 161 mycommand.tex using Listing 159
\mycommand
	{
	mand arg text
	mand arg text}
	[
		opt arg text
		opt arg text
	]

Both indentRules and indentRulesGlobal can be adjusted as they were for environment code blocks, as in Listing 124 and Listing 125 and Listing 135 and Listing 138 and Listing 139.

5.4.4. ifelsefi code blocks

Let’s use the simple example shown in Listing 162; when latexindent.pl operates on this file, the output as in Listing 163; note that the body of each of the \if statements have been indented, and that the \else statement has been accounted for correctly.

Listing 162 ifelsefi1.tex
\ifodd\radius
\ifnum\radius<14
\pgfmathparse{100-(\radius)*4};
\else
\pgfmathparse{200-(\radius)*3};
\fi\fi
Listing 163 ifelsefi1.tex default output
\ifodd\radius
	\ifnum\radius<14
		\pgfmathparse{100-(\radius)*4};
	\else
		\pgfmathparse{200-(\radius)*3};
	\fi\fi

It is recommended to specify noAdditionalIndent and indentRules in the ‘scalar’ form only for these type of code blocks, although the ‘field’ form would work, assuming that body was specified. Examples are shown in Listing 164 and Listing 165.

Listing 164 ifnum-noAdd.yaml
noAdditionalIndent:
    ifnum: 1
Listing 165 ifnum-indent-rules.yaml
indentRules:
    ifnum: "  "

After running the following commands,

 latexindent.pl ifelsefi1.tex -local ifnum-noAdd.yaml
 latexindent.pl ifelsefi1.tex -l ifnum-indent-rules.yaml

we receive the respective output given in Listing 166 and Listing 167; note that in Listing 166, the ifnum code block has not received any additional indentation, while in Listing 167, the ifnum code block has received one tab and two spaces of indentation.

Listing 166 ifelsefi1.tex using Listing 164
\ifodd\radius
	\ifnum\radius<14
	\pgfmathparse{100-(\radius)*4};
	\else
	\pgfmathparse{200-(\radius)*3};
	\fi\fi
Listing 167 ifelsefi1.tex using Listing 165
\ifodd\radius
	\ifnum\radius<14
	  \pgfmathparse{100-(\radius)*4};
	\else
	  \pgfmathparse{200-(\radius)*3};
	\fi\fi

We may specify noAdditionalIndentGlobal and indentRulesGlobal as in Listing 168 and Listing 169.

Listing 168 ifelsefi-noAdd-glob.yaml
noAdditionalIndentGlobal:
    ifElseFi: 1
Listing 169 ifelsefi-indent-rules-global.yaml
indentRulesGlobal:
    ifElseFi: " "

Upon running the following commands

 latexindent.pl ifelsefi1.tex -local ifelsefi-noAdd-glob.yaml
 latexindent.pl ifelsefi1.tex -l ifelsefi-indent-rules-global.yaml

we receive the outputs in Listing 170 and Listing 171; notice that in Listing 170 neither of the ifelsefi code blocks have received indentation, while in Listing 171 both code blocks have received a single space of indentation.

Listing 170 ifelsefi1.tex using Listing 168
\ifodd\radius
\ifnum\radius<14
\pgfmathparse{100-(\radius)*4};
\else
\pgfmathparse{200-(\radius)*3};
\fi\fi
Listing 171 ifelsefi1.tex using Listing 169
\ifodd\radius
 \ifnum\radius<14
  \pgfmathparse{100-(\radius)*4};
 \else
  \pgfmathparse{200-(\radius)*3};
 \fi\fi

We can further explore the treatment of ifElseFi code blocks in Listing 172, and the associated default output given in Listing 173; note, in particular, that the bodies of each of the ‘or statements’ have been indented.

Listing 172 ifelsefi2.tex
\ifcase#1
zero%
\or
one%
\or
two%
\or
three%
\else
default
\fi
Listing 173 ifelsefi2.tex default output
\ifcase#1
	zero%
\or
	one%
\or
	two%
\or
	three%
\else
	default
\fi

5.4.5. specialBeginEnd code blocks

Let’s use the example from Listing 84 which has default output shown in Listing 85.

It is recommended to specify noAdditionalIndent and indentRules in the ‘scalar’ form for these type of code blocks, although the ‘field’ form would work, assuming that body was specified. Examples are shown in Listing 174 and Listing 175.

Listing 174 displayMath-noAdd.yaml
noAdditionalIndent:
    displayMath: 1
Listing 175 displayMath-indent-rules.yaml
indentRules:
    displayMath: "\t\t\t"

After running the following commands,

 latexindent.pl special1.tex -local displayMath-noAdd.yaml
 latexindent.pl special1.tex -l displayMath-indent-rules.yaml

we receive the respective output given in Listing 176 and Listing 177; note that in Listing 176, the displayMath code block has not received any additional indentation, while in Listing 177, the displayMath code block has received three tabs worth of indentation.

Listing 176 special1.tex using Listing 174
The function $f$ has formula
\[
f(x)=x^2.
\]
If you like splitting dollars,
$
	g(x)=f(2x)
$
Listing 177 special1.tex using Listing 175
The function $f$ has formula
\[
			f(x)=x^2.
\]
If you like splitting dollars,
$
	g(x)=f(2x)
$

We may specify noAdditionalIndentGlobal and indentRulesGlobal as in Listing 178 and Listing 179.

Listing 178 special-noAdd-glob.yaml
noAdditionalIndentGlobal:
    specialBeginEnd: 1
Listing 179 special-indent-rules-global.yaml
indentRulesGlobal:
    specialBeginEnd: " "

Upon running the following commands

 latexindent.pl special1.tex -local special-noAdd-glob.yaml
 latexindent.pl special1.tex -l special-indent-rules-global.yaml

we receive the outputs in Listing 180 and Listing 181; notice that in Listing 180 neither of the special code blocks have received indentation, while in Listing 181 both code blocks have received a single space of indentation.

Listing 180 special1.tex using Listing 178
The function $f$ has formula
\[
f(x)=x^2.
\]
If you like splitting dollars,
$
g(x)=f(2x)
$
Listing 181 special1.tex using Listing 179
The function $f$ has formula
\[
 f(x)=x^2.
\]
If you like splitting dollars,
$
 g(x)=f(2x)
$

5.4.6. afterHeading code blocks

Let’s use the example Listing 182 for demonstration throughout this . As discussed on page lst:headings1, by default latexindent.pl will not add indentation after headings.

Listing 182 headings2.tex
\paragraph{paragraph 
title}
paragraph text
paragraph text

On using the YAML file in Listing 184 by running the command

 latexindent.pl headings2.tex -l headings3.yaml

we obtain the output in Listing 183. Note that the argument of paragraph has received (default) indentation, and that the body after the heading statement has received (default) indentation.

Listing 183 headings2.tex using Listing 184
\paragraph{paragraph
		title}
	paragraph text
	paragraph text
Listing 184 headings3.yaml
indentAfterHeadings:
    paragraph:
       indentAfterThisHeading: 1
       level: 1

If we specify noAdditionalIndent as in Listing 186 and run the command

 latexindent.pl headings2.tex -l headings4.yaml

then we receive the output in Listing 185. Note that the arguments and the body after the heading of paragraph has received no additional indentation, because we have specified noAdditionalIndent in scalar form.

Listing 185 headings2.tex using Listing 186
\paragraph{paragraph
title}
paragraph text
paragraph text
Listing 186 headings4.yaml
indentAfterHeadings:
    paragraph:
       indentAfterThisHeading: 1
       level: 1
noAdditionalIndent:
    paragraph: 1

Similarly, if we specify indentRules as in Listing 188 and run analogous commands to those above, we receive the output in Listing 187; note that the body, mandatory argument and content after the heading of paragraph have all received three tabs worth of indentation.

Listing 187 headings2.tex using Listing 188
\paragraph{paragraph
									title}
			paragraph text
			paragraph text
Listing 188 headings5.yaml
indentAfterHeadings:
    paragraph:
       indentAfterThisHeading: 1
       level: 1
indentRules:
    paragraph: "\t\t\t"

We may, instead, specify noAdditionalIndent in ‘field’ form, as in Listing 190 which gives the output in Listing 189.

Listing 189 headings2.tex using Listing 190
\paragraph{paragraph
	title}
paragraph text
paragraph text
Listing 190 headings6.yaml
indentAfterHeadings:
    paragraph:
       indentAfterThisHeading: 1
       level: 1
noAdditionalIndent:
    paragraph: 
        body: 0
        mandatoryArguments: 0
        afterHeading: 1

Analogously, we may specify indentRules as in Listing 192 which gives the output in Listing 191; note that mandatory argument text has only received a single space of indentation, while the body after the heading has received three tabs worth of indentation.

Listing 191 headings2.tex using Listing 192
\paragraph{paragraph
			 title}
			paragraph text
			paragraph text
Listing 192 headings7.yaml
indentAfterHeadings:
    paragraph:
       indentAfterThisHeading: 1
       level: 1
indentRules:
    paragraph: 
        mandatoryArguments: " "
        afterHeading: "\t\t\t"

Finally, let’s consider noAdditionalIndentGlobal and indentRulesGlobal shown in Listing 194 and Listing 196 respectively, with respective output in Listing 193 and Listing 195. Note that in Listing 194 the mandatory argument of paragraph has received a (default) tab’s worth of indentation, while the body after the heading has received no additional indentation. Similarly, in Listing 195, the argument has received both a (default) tab plus two spaces of indentation (from the global rule specified in Listing 196), and the remaining body after paragraph has received just two spaces of indentation.

Listing 193 headings2.tex using Listing 194
\paragraph{paragraph
	title}
paragraph text
paragraph text
Listing 194 headings8.yaml
indentAfterHeadings:
    paragraph:
       indentAfterThisHeading: 1
       level: 1
noAdditionalIndentGlobal:
    afterHeading: 1
Listing 195 headings2.tex using Listing 196
\paragraph{paragraph
	  title}
  paragraph text
  paragraph text
Listing 196 headings9.yaml
indentAfterHeadings:
    paragraph:
       indentAfterThisHeading: 1
       level: 1
indentRulesGlobal:
    afterHeading: "  "

5.4.7. The remaining code blocks

Referencing the different types of code blocks in Table 1, we have a few code blocks yet to cover; these are very similar to the commands code block type covered comprehensively in Section 5.4.3, but a small discussion defining these remaining code blocks is necessary.

keyEqualsValuesBracesBrackets

latexindent.pl defines this type of code block by the following criteria:

  • it must immediately follow either { OR [ OR , with comments and blank lines allowed.
  • then it has a name made up of the characters detailed in Table 1;
  • then an \(=\) symbol;
  • then at least one set of curly braces or square brackets (comments and line breaks allowed throughout).

See the keyEqualsValuesBracesBrackets: follow and keyEqualsValuesBracesBrackets: name fields of the fine tuning section in Listing 470 An example is shown in Listing 197, with the default output given in Listing 198.

Listing 197 pgfkeys1.tex
\pgfkeys{/tikz/.cd,
start coordinate/.initial={0,
\vertfactor},
}
Listing 198 pgfkeys1.tex default output
\pgfkeys{/tikz/.cd,
	start coordinate/.initial={0,
			\vertfactor},
}

In Listing 198, note that the maximum indentation is three tabs, and these come from:

  • the \pgfkeys command’s mandatory argument;
  • the start coordinate/.initial key’s mandatory argument;
  • the start coordinate/.initial key’s body, which is defined as any lines following the name of the key that include its arguments. This is the part controlled by the body field for noAdditionalIndent and friends from page sec:noadd-indent-rules.

namedGroupingBracesBrackets

This type of code block is mostly motivated by tikz-based code; we define this code block as follows:

  • it must immediately follow either horizontal space OR one or more line breaks OR { OR [ OR $ OR ) OR (
  • the name may contain the characters detailed in Table 1;
  • then at least one set of curly braces or square brackets (comments and line breaks allowed throughout).

See the NamedGroupingBracesBrackets: follow and NamedGroupingBracesBrackets: name fields of the fine tuning section in Listing 470 A simple example is given in Listing 199, with default output in Listing 200.

Listing 199 child1.tex
\coordinate
child[grow=down]{
edge from parent [antiparticle]
node [above=3pt] {$C$}
}
Listing 200 child1.tex default output
\coordinate
child[grow=down]{
		edge from parent [antiparticle]
		node [above=3pt] {$C$}
	}

In particular, latexindent.pl considers child, parent and node all to be namedGroupingBracesBrackets [5]. Referencing Listing 200, note that the maximum indentation is two tabs, and these come from:

  • the child’s mandatory argument;
  • the child’s body, which is defined as any lines following the name of the namedGroupingBracesBrackets that include its arguments. This is the part controlled by the body field for noAdditionalIndent and friends from page sec:noadd-indent-rules.

UnNamedGroupingBracesBrackets

occur in a variety of situations; specifically, we define this type of code block as satisfying the following criteria:

  • it must immediately follow either { OR [ OR , OR & OR ) OR ( OR $;
  • then at least one set of curly braces or square brackets (comments and line breaks allowed throughout).

See the UnNamedGroupingBracesBrackets: follow field of the fine tuning section in Listing 470 An example is shown in Listing 201 with default output give in Listing 202.

Listing 201 psforeach1.tex
\psforeach{\row}{%
{
{3,2.8,2.7,3,3.1}},%
{2.8,1,1.2,2,3},%
}
Listing 202 psforeach1.tex default output
\psforeach{\row}{%
	{
			{3,2.8,2.7,3,3.1}},%
	{2.8,1,1.2,2,3},%
}

Referencing Listing 202, there are three sets of unnamed braces. Note also that the maximum value of indentation is three tabs, and these come from:

  • the \psforeach command’s mandatory argument;
  • the first un-named braces mandatory argument;
  • the first un-named braces body, which we define as any lines following the first opening { or [ that defined the code block. This is the part controlled by the body field for noAdditionalIndent and friends from page sec:noadd-indent-rules.

Users wishing to customise the mandatory and/or optional arguments on a per-name basis for the UnNamedGroupingBracesBrackets should use always-un-named.

filecontents

code blocks behave just as environments, except that neither arguments nor items are sought.

5.4.8. Summary

Having considered all of the different types of code blocks, the functions of the fields given in Listing 203 and Listing 204 should now make sense.

Listing 203 noAdditionalIndentGlobal
288
289
290
291
292
293
294
295
296
297
298
299
300
noAdditionalIndentGlobal:
    environments: 0
    commands: 1
    optionalArguments: 0
    mandatoryArguments: 0
    ifElseFi: 0
    items: 0
    keyEqualsValuesBracesBrackets: 0
    namedGroupingBracesBrackets: 0
    UnNamedGroupingBracesBrackets: 0
    specialBeginEnd: 0
    afterHeading: 0
    filecontents: 0
Listing 204 indentRulesGlobal
304
305
306
307
308
309
310
311
312
313
314
315
316
indentRulesGlobal:
    environments: 0
    commands: 0
    optionalArguments: 0
    mandatoryArguments: 0
    ifElseFi: 0
    items: 0
    keyEqualsValuesBracesBrackets: 0
    namedGroupingBracesBrackets: 0
    UnNamedGroupingBracesBrackets: 0
    specialBeginEnd: 0
    afterHeading: 0
    filecontents: 0

5.5. Commands and the strings between their arguments

The command code blocks will always look for optional (square bracketed) and mandatory (curly braced) arguments which can contain comments, line breaks and ‘beamer’ commands <.*?> between them. There are switches that can allow them to contain other strings, which we discuss next.

commandCodeBlocks:fields

The commandCodeBlocks field contains a few switches detailed in Listing 205.

Listing 205 commandCodeBlocks
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
commandCodeBlocks:
    roundParenthesesAllowed: 1
    stringsAllowedBetweenArguments:
      - 
        amalgamate: 1
      - 'node'
      - 'at'
      - 'to'
      - 'decoration'
      - '\+\+'
      - '\-\-'
    commandNameSpecial:
      - 
        amalgamate: 1
      - '@ifnextchar\['
roundParenthesesAllowed:0|1

The need for this field was mostly motivated by commands found in code used to generate images in PSTricks and tikz; for example, let’s consider the code given in Listing 206.

Listing 206 pstricks1.tex
\defFunction[algebraic]{torus}(u,v)
{(2+cos(u))*cos(v+\Pi)}
{(2+cos(u))*sin(v+\Pi)}
{sin(u)}
Listing 207 pstricks1 default output
\defFunction[algebraic]{torus}(u,v)
{(2+cos(u))*cos(v+\Pi)}
{(2+cos(u))*sin(v+\Pi)}
{sin(u)}

Notice that the \defFunction command has an optional argument, followed by a mandatory argument, followed by a round-parenthesis argument, \((u,v)\).

By default, because roundParenthesesAllowed is set to \(1\) in Listing 205, then latexindent.pl will allow round parenthesis between optional and mandatory arguments. In the case of the code in Listing 206, latexindent.pl finds all the arguments of defFunction, both before and after (u,v).

The default output from running latexindent.pl on Listing 206 actually leaves it unchanged (see Listing 207); note in particular, this is because of noAdditionalIndentGlobal as discussed on page page:command:noAddGlobal.

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

 latexindent.pl pstricks1.tex -l noRoundParentheses.yaml

we obtain the output given in Listing 208.

Listing 208 pstricks1.tex using Listing 209
\defFunction[algebraic]{torus}(u,v)
{(2+cos(u))*cos(v+\Pi)}
	{(2+cos(u))*sin(v+\Pi)}
	{sin(u)}
Listing 209 noRoundParentheses.yaml
commandCodeBlocks:
    roundParenthesesAllowed: 0

Notice the difference between Listing 207 and Listing 208; in particular, in Listing 208, because round parentheses are not allowed, latexindent.pl finds that the \defFunction command finishes at the first opening round parenthesis. As such, the remaining braced, mandatory, arguments are found to be UnNamedGroupingBracesBrackets (see Table 1) which, by default, assume indentation for their body, and hence the tabbed indentation in Listing 208.

Let’s explore this using the YAML given in Listing 211 and run the command

 latexindent.pl pstricks1.tex -l defFunction.yaml

then the output is as in Listing 210.

Listing 210 pstricks1.tex using Listing 211
\defFunction[algebraic]{torus}(u,v)
 {(2+cos(u))*cos(v+\Pi)}
 {(2+cos(u))*sin(v+\Pi)}
 {sin(u)}
Listing 211 defFunction.yaml
indentRules:
    defFunction: 
        body: " "

Notice in Listing 210 that the body of the defFunction command i.e, the subsequent lines containing arguments after the command name, have received the single space of indentation specified by Listing 211.

stringsAllowedBetweenArguments:fields

tikz users may well specify code such as that given in Listing 212; processing this code using latexindent.pl gives the default output in Listing 213.

Listing 212 tikz-node1.tex
\draw[thin] 
(c) to[in=110,out=-90] 
++(0,-0.5cm) 
node[below,align=left,scale=0.5]
Listing 213 tikz-node1 default output
\draw[thin]
(c) to[in=110,out=-90]
++(0,-0.5cm)
node[below,align=left,scale=0.5]

With reference to Listing 205, we see that the strings

to, node, ++

are all allowed to appear between arguments; importantly, you are encouraged to add further names to this field as necessary. This means that when latexindent.pl processes Listing 212, it consumes:

  • the optional argument [thin]
  • the round-bracketed argument (c) because roundParenthesesAllowed is \(1\) by default
  • the string to (specified in stringsAllowedBetweenArguments)
  • the optional argument [in=110,out=-90]
  • the string ++ (specified in stringsAllowedBetweenArguments)
  • the round-bracketed argument (0,-0.5cm) because roundParenthesesAllowed is \(1\) by default
  • the string node (specified in stringsAllowedBetweenArguments)
  • the optional argument [below,align=left,scale=0.5]

We can explore this further, for example using Listing 215 and running the command

 latexindent.pl tikz-node1.tex -l draw.yaml

we receive the output given in Listing 214.

Listing 214 tikz-node1.tex using Listing 215
\draw[thin]
  (c) to[in=110,out=-90]
  ++(0,-0.5cm)
  node[below,align=left,scale=0.5]
Listing 215 draw.yaml
indentRules:
    draw: 
        body: "  "

Notice that each line after the \draw command (its ‘body’) in Listing 214 has been given the appropriate two-spaces worth of indentation specified in Listing 215.

Let’s compare this with the output from using the YAML settings in Listing 217, and running the command

 latexindent.pl tikz-node1.tex -l no-strings.yaml

given in Listing 216.

Listing 216 tikz-node1.tex using Listing 217
\draw[thin]
(c) to[in=110,out=-90]
++(0,-0.5cm)
node[below,align=left,scale=0.5]
Listing 217 no-strings.yaml
commandCodeBlocks:
    stringsAllowedBetweenArguments: 0

In this case, latexindent.pl sees that:

  • the \draw command finishes after the (c), as stringsAllowedBetweenArguments has been set to \(0\) so there are no strings allowed between arguments;
  • it finds a namedGroupingBracesBrackets called to (see Table 1) with argument [in=110,out=-90]
  • it finds another namedGroupingBracesBrackets but this time called node with argument [below,align=left,scale=0.5]

Referencing Listing 205, , we see that the first field in the stringsAllowedBetweenArguments is amalgamate and is set to 1 by default. This is for users who wish to specify their settings in multiple YAML files. For example, by using the settings in either Listing 218 or:numref:lst:amalgamate-demo1 is equivalent to using the settings in Listing 220.

Listing 218 amalgamate-demo.yaml
commandCodeBlocks:
    stringsAllowedBetweenArguments:
      - 'more'
      - 'strings'
      - 'here'
Listing 219 amalgamate-demo1.yaml
commandCodeBlocks:
    stringsAllowedBetweenArguments:
      - 
        amalgamate: 1
      - 'more'
      - 'strings'
      - 'here'
Listing 220 amalgamate-demo2.yaml
commandCodeBlocks:
    stringsAllowedBetweenArguments:
      - 
        amalgamate: 1
      - 'node'
      - 'at'
      - 'to'
      - 'decoration'
      - '\+\+'
      - '\-\-'
      - 'more'
      - 'strings'
      - 'here'

We specify amalgamate to be set to 0 and in which case any settings loaded prior to those specified, including the default, will be overwritten. For example, using the settings in Listing 221 means that only the strings specified in that field will be used.

Listing 221 amalgamate-demo3.yaml
commandCodeBlocks:
    stringsAllowedBetweenArguments:
      - 
        amalgamate: 0
      - 'further'
      - 'settings'

It is important to note that the amalgamate field, if used, must be in the first field, and specified using the syntax given in Listing 219 and Listing 220 and Listing 221.

We may explore this feature further with the code in Listing 222, whose default output is given in Listing 223.

Listing 222 for-each.tex
\foreach \x/\y in {0/1,1/2}{
body of foreach
}
Listing 223 for-each default output
\foreach \x/\y in {0/1,1/2}{
		body of foreach
	}

Let’s compare this with the output from using the YAML settings in Listing 225, and running the command

 latexindent.pl for-each.tex -l foreach.yaml

given in Listing 224.

Listing 224 for-each.tex using Listing 225
\foreach \x/\y in {0/1,1/2}{
	body of foreach
}
Listing 225 foreach.yaml
commandCodeBlocks:
    stringsAllowedBetweenArguments:
      - 
        amalgamate: 0
      - '\\x\/\\y'
      - 'in'

You might like to compare the output given in Listing 223 and Listing 224. Note,in particular, in Listing 223 that the foreach command has not included any of the subsequent strings, and that the braces have been treated as a namedGroupingBracesBrackets. In Listing 224 the foreach command has been allowed to have \x/\y and in between arguments because of the settings given in Listing 225.

commandNameSpecial:fields

There are some special command names that do not fit within the names recognised by latexindent.pl, the first one of which is \@ifnextchar[. From the perspective of latexindent.pl, the whole of the text \@ifnextchar[ is a command, because it is immediately followed by sets of mandatory arguments. However, without the commandNameSpecial field, latexindent.pl would not be able to label it as such, because the [ is, necessarily, not matched by a closing ].

For example, consider the sample file in Listing 226, which has default output in Listing 227.

Listing 226 ifnextchar.tex
\parbox{
\@ifnextchar[{arg 1}{arg 2}
}
Listing 227 ifnextchar.tex default output
\parbox{
	\@ifnextchar[{arg 1}{arg 2}
}

Notice that in Listing 227 the parbox command has been able to indent its body, because latexindent.pl has successfully found the command \@ifnextchar first; the pattern-matching of latexindent.pl starts from the inner most <thing> and works outwards, discussed in more detail on page page:phases.

For demonstration, we can compare this output with that given in Listing 228 in which the settings from Listing 229 have dictated that no special command names, including the \@ifnextchar[ command, should not be searched for specially; as such, the parbox command has been unable to indent its body successfully, because the \@ifnextchar[ command has not been found.

Listing 228 ifnextchar.tex using Listing 229
\parbox{
\@ifnextchar[{arg 1}{arg 2}
}
Listing 229 no-ifnextchar.yaml
commandCodeBlocks:
    commandNameSpecial: 0

The amalgamate field can be used for commandNameSpecial, just as for stringsAllowedBetweenArguments. The same condition holds as stated previously, which we state again here:

Warning

It is important to note that the amalgamate field, if used, in either commandNameSpecial or stringsAllowedBetweenArguments must be in the first field, and specified using the syntax given in Listing 219 and Listing 220 and Listing 221.

“Log4perl Perl Module.” 2017. Accessed September 24. http://search.cpan.org/~mschilli/Log-Log4perl-1.49/lib/Log/Log4perl.pm.

“Text::Tabs Perl Module.” 2017. Accessed July 6. http://search.cpan.org/~muir/Text-Tabs+Wrap-2013.0523/lib.old/Text/Tabs.pm.

Voßkuhle, Michel. 2013. “Remove Trailing White Space.” November 10. https://github.com/cmhughes/latexindent.pl/pull/12.

[1]Throughout this manual, listings shown with line numbers represent code taken directly from defaultSettings.yaml.
[2]Previously this only activated if alignDoubleBackSlash was set to 0.
[3]There is a slight difference in interface for this field when comparing Version 2.2 to Version 3.0; see Section 11.4 for details.
[4]The command code blocks have quite a few subtleties, described in Section 5.5.
[5]You may like to verify this by using the -tt option and checking indent.log!