# 9. Fine tuning¶

latexindent.pl operates by looking for the code blocks detailed in Table 2. The fine tuning of the details of such code blocks is controlled by the fineTuning field, detailed in Listing 522.

This field is for those that would like to peek under the bonnet/hood and make some fine tuning to latexindent.pl’s operating.

Warning

Making changes to the fine tuning may have significant consequences for your indentation scheme, proceed with caution!

Listing 522 fineTuning
 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 fineTuning: environments: name: '[a-zA-Z@\*0-9_\\]+' ifElseFi: name: '(?!@?if[a-zA-Z@]*?\{)@?if[a-zA-Z@]*?' commands: name: '[+a-zA-Z@\*0-9_\:]+?' items: canBeFollowedBy: '(?:$[^]]*?$)|(?:<[^>]*?>)' keyEqualsValuesBracesBrackets: name: '[a-zA-Z@\*0-9_\/.:\#-]+[a-zA-Z@\*0-9_\/.\h\{\}:\#-]*?' follow: '(?:(?<]+?' follow: '\h|\R|\{|\[|\$|\)|$$' UnNamedGroupingBracesBrackets: follow: '\{|\[|,|&|$$|$$|\' arguments: before: '(?:#\d\h*;?,?\/?)+|\<.*?\>' between: '_|\^|\*' trailingComments: notPreceededBy: '(? The fields given in Listing 522 are all regular expressions. This manual is not intended to be a tutorial on regular expressions; you might like to read, for example, (Friedl, n.d.) for a detailed covering of the topic. We make the following comments with reference to Listing 522: 1. the environments:name field details that the name of an environment can contain: 1. a-z lower case letters 2. A-Z upper case letters 3. @ the @ ’letter’ 4. \* stars 5. 0-9 numbers 6. _ underscores 7. \ backslashes The + at the end means at least one of the above characters. 2. the ifElseFi:name field: 1. @? means that it can possibly begin with @ 2. followed by if 3. followed by 0 or more characters from a-z, A-Z and @ 4. the ? the end means non-greedy, which means ‘stop the match as soon as possible’ 3. the keyEqualsValuesBracesBrackets contains some interesting syntax: 1. | means ‘or’ 2. (?:(?<!\$$\{) the (?:...) uses a non-capturing group – you don’t necessarily need to worry about what this means, but just know that for the fineTuning feature you should only ever use non-capturing groups, and not capturing groups, which are simply (...) 3. (?<!\\)\{) means a { but it can not be immediately preceded by a \ 4. in the arguments:before field 1. \d\h* means a digit (i.e. a number), followed by 0 or more horizontal spaces 2. ;?,? means possibly a semi-colon, and possibly a comma 3. \<.*?\> is designed for ’beamer’-type commands; the .*? means anything in between <...> 5. the modifyLineBreaks field refers to fine tuning settings detailed in Section 6. In particular: 1. betterFullStop is in relation to the one sentence per line routine, detailed in Section 6.2 2. doubleBackSlash is in relation to the DBSStartsOnOwnLine and DBSFinishesWithLineBreak polyswitches surrounding double back slashes, see Section 6.3.2 3. comma is in relation to the CommaStartsOnOwnLine and CommaFinishesWithLineBreak polyswitches surrounding commas in optional and mandatory arguments; see Table 3 It is not obvious from Listing 522, but each of the follow, before and between fields allow trailing comments, line breaks, and horizontal spaces between each character. Warning For the fineTuning feature you should only ever use non-capturing groups, such as (?:...) and not capturing groups, which are (...) Example 40 As a demonstration, consider the file given in Listing 523, together with its default output using the command latexindent.pl finetuning1.tex  is given in Listing 524. Listing 523 finetuning1.tex \mycommand{ \rule{G -> +H[-G]CL} \rule{H -> -G[+H]CL} \rule{g -> +h[-g]cL} \rule{h -> -g[+h]cL} }  Listing 524 finetuning1.tex default \mycommand{ \rule{G -> +H[-G]CL} \rule{H -> -G[+H]CL} \rule{g -> +h[-g]cL} \rule{h -> -g[+h]cL} }  It’s clear from Listing 524 that the indentation scheme has not worked as expected. We can fine tune the indentation scheme by employing the settings given in Listing 526 and running the command latexindent.pl finetuning1.tex -l=fine-tuning1.yaml  and the associated (desired) output is given in Listing 525. Listing 525 finetuning1.tex using Listing 526 \mycommand{ \rule{G -> +H[-G]CL} \rule{H -> -G[+H]CL} \rule{g -> +h[-g]cL} \rule{h -> -g[+h]cL} }  Listing 526 finetuning1.yaml fineTuning: arguments: between: '_|\^|\*|\->|\-|\+|h|H|g|G'  Example 41 Let’s have another demonstration; consider the file given in Listing 527, together with its default output using the command latexindent.pl finetuning2.tex  is given in Listing 528. Listing 527 finetuning2.tex @misc{ wikilatex, author = "{Wikipedia contributors}", title = "LaTeX --- {Wikipedia}{,}", note = "[Online; accessed 3-March-2020]" }  Listing 528 finetuning2.tex default @misc{ wikilatex, author = "{Wikipedia contributors}", title = "LaTeX --- {Wikipedia}{,}", note = "[Online; accessed 3-March-2020]" }  It’s clear from Listing 528 that the indentation scheme has not worked as expected. We can fine tune the indentation scheme by employing the settings given in Listing 530 and running the command latexindent.pl finetuning2.tex -l=fine-tuning2.yaml  and the associated (desired) output is given in Listing 529. Listing 529 finetuning2.tex using Listing 530 @misc{ wikilatex, author = "{Wikipedia contributors}", title = "LaTeX --- {Wikipedia}{,}", note = "[Online; accessed 3-March-2020]" }  Listing 530 finetuning2.yaml fineTuning: NamedGroupingBracesBrackets: follow: '\h|\R|\{|\[|\$|\)|$$|"' UnNamedGroupingBracesBrackets: follow: '\{|\[|,|&|$$||\|"' arguments: between: '_|\^|\*|---'  In particular, note that the settings in Listing 530 specify that NamedGroupingBracesBrackets and UnNamedGroupingBracesBrackets can follow " and that we allow --- between arguments. Example 42 You can tweak the fineTuning using the -y switch, but to be sure to use quotes appropriately. For example, starting with the code in Listing 531 and running the following command latexindent.pl -m -y='modifyLineBreaks:oneSentencePerLine:manipulateSentences: 1, modifyLineBreaks:oneSentencePerLine:sentencesBeginWith:a-z: 1, fineTuning:modifyLineBreaks:betterFullStop: "(?:\.|;|:(?![a-z]))|(?:(?<!(?:(?:e\.g)|(?:i\.e)|(?:etc))))\.(?!(?:[a-z]|[A-Z]|\-|~|\,|[0-9]))"' issue-243.tex -o=+-mod1  gives the output shown in Listing 532. Listing 531 finetuning3.tex We go; you see: this sentence \cite{tex:stackexchange} finishes here.  Listing 532 finetuning3.tex using -y switch We go; you see: this sentence \cite{tex:stackexchange} finishes here.  Example 43 We can tweak the fineTuning for how trailing comments are classified. For motivation, let’s consider the code given in Listing 533 Listing 533 finetuning4.tex some before text \href{Handbook%20for%30Spoken%40document.pdf}{my document} some after text  We will compare the settings given in Listing 534 and Listing 535. Listing 534 href1.yaml modifyLineBreaks: textWrapOptions: columns: -1 blocksEndBefore: verbatim: 0 blocksFollow: verbatim: 0 removeTrailingWhitespace: beforeProcessing: 1  Listing 535 href2.yaml fineTuning: trailingComments: notPreceededBy: '(?:(?<!Handbook)(?<!for)(?<!Spoken))' modifyLineBreaks: textWrapOptions: columns: -1 blocksEndBefore: verbatim: 0 blocksFollow: verbatim: 0 removeTrailingWhitespace: beforeProcessing: 1  Upon running the following commands latexindent.pl -m finetuning4.tex -o=+-mod1 -l=href1 latexindent.pl -m finetuning4.tex -o=+-mod2 -l=href2  we receive the respective output in Listing 536 and Listing 537. Listing 536 finetuning4.tex using Listing 534 some before text \href{Handbooksome after text%20for%30Spoken%40document.pdf}{my document}  Listing 537 finetuning4.tex using Listing 535 some before text \href{Handbook%20for%30Spoken%40document.pdf}{my document} some after text  We note that in: • Listing 536 the trailing comments are assumed to be everything following the first comment symbol, which has meant that everything following it has been moved to the end of the line; this is undesirable, clearly! • Listing 537 has fine-tuned the trailing comment matching, and says that % cannot be immediately preceeded by the words ‘Handbook’, ‘for’ or ‘Spoken’, which means that none of the % symbols have been treated as trailing comments, and the output is desirable. Another approach to this situation, which does not use fineTuning, is to use noIndentBlock which we discussed in Listing 40; using the settings in Listing 538 and running the command latexindent.pl -m finetuning4.tex -o=+-mod3 -l=href3  then we receive the same output given in Listing 537. Listing 538 href3.yaml modifyLineBreaks: textWrapOptions: columns: -1 blocksEndBefore: verbatim: 0 blocksFollow: verbatim: 0 noIndentBlock: href: begin: '\\href\{[^}]*?\}\{' body: '[^}]*?' end: '\}'  With reference to the body field in Listing 538, we note that the body field can be interpreted as: the fewest number of zero or more characters that are not right braces. This is an example of character class. Example 44 We can use the fineTuning field to assist in the formatting of bibliography files. Starting with the file in Listing 539 and running the command latexindent.pl bib1.tex -o=+-mod1  gives the output in Listing 540. Listing 539 bib1.bib @online{paulo, title="arararule,indent.yaml", author="PauloCereda", date={2013-05-23}, urldate={2021-03-19}, keywords={contributor},}  Listing 540 bib1-mod1.bib @online{paulo, title="arararule,indent.yaml", author="PauloCereda", date={2013-05-23}, urldate={2021-03-19}, keywords={contributor},}  Let’s assume that we would like to format the output so as to align the = symbols. Using the settings in Listing 542 and running the command latexindent.pl bib1.bib -l bibsettings1.yaml -o=+-mod2  gives the output in Listing 541. Listing 541 bib1.bib using Listing 542 @online{paulo, title = "arararule,indent.yaml", author = "PauloCereda", date = {2013-05-23}, urldate = {2021-03-19}, keywords = {contributor},}  Listing 542 bibsettings1.yaml lookForAlignDelims: online: delimiterRegEx: '(=)' fineTuning: keyEqualsValuesBracesBrackets: follow: '(?:(?<!\\{)|(?:(?<!\\)\[)'
UnNamedGroupingBracesBrackets:
follow: '\{|\[|,|&|\)|\(|\\$|='


• we have populated the lookForAlignDelims field with the online command, and have used the delimiterRegEx, discussed in Section 5.5.4;
• we have tweaked the keyEqualsValuesBracesBrackets code block so that it will not be found following a comma; this means that, in contrast to the default behaviour, the lines such as date={2013-05-23}, will not be treated as key-equals-value braces;
• the adjustment to keyEqualsValuesBracesBrackets necessitates the associated change to the UnNamedGroupingBracesBrackets field so that they will be searched for following = symbols.
Example 45

We can build upon Listing 542 for slightly more complicated bibliography files.

Starting with the file in Listing 543 and running the command

latexindent.pl bib2.bib -l bibsettings1.yaml -o=+-mod1


gives the output in Listing 544.

Listing 543 bib2.bib
@online{cmh:videodemo,
urldate={2017-02-21},
}

Listing 544 bib2-mod1.bib
@online{cmh:videodemo,
urldate = {2017-02-21},
}


The output in Listing 544 is not ideal, as the = symbol within the url field has been incorrectly used as an alignment delimiter.

We address this by tweaking the delimiterRegEx field in Listing 545.

Listing 545 bibsettings2.yaml
lookForAlignDelims:
online:


Upon running the command

latexindent.pl bib2.bib -l bibsettings1.yaml,bibsettings2.yaml -o=+-mod2


we receive the desired output in Listing 546.

Listing 546 bib2-mod2.bib
@online{cmh:videodemo,

With reference to Listing 545 we note that the delimiterRegEx has been adjusted so that = symbols are used as the delimiter, but only when they are not preceeded by either v or spfreload`.