Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?
latexindent の使い方

How to use latexindent

latexindent はTeX ファイルを視覚的に綺麗に整形するためのツールである.
& による整列などを視覚的に綺麗にすることが出来る.

例えば,以下のようなtabular 環境に対してlatexindent を使用して整形することが出来る.

tabular.tex (before)

\begin{tabular}{ccc} \hline
ab&cde&fghi\\
jklm&n&op\\
qrstuv&wxy&z\\
\end{tabular}
$ latexindent tabular.tex

tabular.tex (after)

\begin{tabular}{ccc} \hline
    ab     & cde  & fghi \\
    jklm   & n    & op   \\
    qrstuv & wxyz &      \\
\end{tabular}

VSCode ではLaTeX Workshop からフォーマッターとして利用することが出来る.

本記事ではWindows をベースに紹介する.そのため,パスの設定などに関しては注意してほしい.また,Windows 以外ではPerl 環境が必要になる.他記事を参照して導入してほしい.(Perl とPerl のモジュールの両方が必要になるらしい)

設定例についてやVSCode の設定についてはこの下のファイルに続けている.

Command line

cf. 3. How to use the script

Linux とMac 向けにはPerl で提供される.Windows 向けにはexe で提供されている.基本的な使用方法はコマンドラインで利用する.

$ latexindent foo.tex

いくつかのスイッチがある.公式Wiki ではスイッチと書かれているが,本記事ではオプションとも表現することがある.どちらも同じものと思ってもらいたい.

YAML の設定が良くない場合,フォーマッタが実行を終了しない場合がある. 途中で停止させたい場合にはCtrl+C すれば良い.

▼ Important debak check

cf. cmhughes/latexindent.pl - README # important | GitHub

latexindent を利用する際にREADME がどれだけ読まれるのか分からないが,
latexindent によるフォーマットを実行することによってTeX ファイルに重大な損傷を与える変更や削除を加える場合がある ようだ.したがって,次のような確認作業を行うことを推奨している.

  • 少なくとも各ファイルの行数が同じになっていることを視覚的に確認
  • latexdiff やGit によるファイルのチェック

ただし,1つめの項目にある行数の確認は,いくつかの設定によって改行に変更を加えることが可能なため,あまり意味のある確認にならない可能性がある.また,Git による変更点の確認も面倒になると思われる.

したがって,latexdiff によるファイルの変更点の確認をお勧めしたい.これは,2つのTeX ファイルの差分を取って,PDF を作成後に色で差分を把握することが出来るようにするツールである.(これもPerl で書かれている)

また,Git 管理している場合にはlatexdiff-vc を利用することで,より簡単に差分を見ることが出来る.

▼ Switch

cf. 3.1 From the command line

よく使いそうなスイッチを一覧にしておく.

Switch Description
-s サイレントモード
-w ファイルの上書き
-l カレントディレクトリにあるYAML ファイルを読み込む
-c バックアップファイルなどのディレクトリ指定
-g ログファイルのファイル名を変更
-t,
-tt
より詳細なログを残す
(ログファイル内が煩雑になるため非推奨.また,処理も遅くなる)

この他に,改行や置き換えを許可するためのスイッチがある.もしも,これらを許可したい場合には適宜追加すると良いだろう.

もちろん,-h でヘルプの表示,-v でバージョンの表示も出来る.

Settings files

設定ファイルはYAML: "YAML Ain't Markup Language" 形式で記述されている.

各自の設定は# User settings で設定することが出来る. 複数の設定ファイルを読み込ませることが出来るため,ここでは読み込み順序を明らかにしておきたい.

cf. 4.4 Settings load order

複数の設定ファイルは以下の順に読み込まれる.後に読み込まれた設定が上書き定義する形で実行される.

  1. defaultSettings.yaml: 常に読み込まれる必須ファイル
  2. indentconfig.yamlなど: このファイルからパスで指定されたその他の任意名ファイルを呼び出す
  3. localSettings.yamlなど: -l スイッチで呼び出される
  4. -y スイッチで指定された設定: コマンドラインから設定する

読み込まれる順序の概略図

実線で結ばれたdefaultSettings.yaml ファイルは常に読み込まれる.破線で結ばれたファイルは適宜読み込まれる.

Image from Gyazo

cf. https://ftp.jaist.ac.jp/pub/CTAN/support/latexindent/documentation/latexindent.pdf ,Page.24

上の図においてユーザ設定するためのファイルは,any.yaml, name.yaml, you.yaml, want.yaml, localSettings.yaml となっている.

▼ Default settings

cf. 5. defaultSettings.yaml

デフォルトの設定は以下のディレクトリに格納されている.

%TEXMFDIST%\scripts\latexindent\defaultSettings.yaml

このファイルは編集しない.個人的な設定はuser-settings.yaml などのファイルを作成すること.

設定の詳細は上の参照リンクを見ると良いだろう.

▼ User settings

cf. 4. indentconfig.yaml, local settings and the -y switch

ユーザ設定は以下の3つの方法がある.これらの設定方法は共存することが出来る. いずれの方法を利用していても設定方法は同じである.また,読み込み順序は先に述べたとおりになる.

これらのファイルを配置したのちには,任意のTeX ファイルに実行してみよう.すると,indent.log が作成される.この中にWARN: がある場合,これらの設定ファイルが読み込まれていない可能性がある.上手く動作しない場合には確認すると良いだろう.

indentconfig.yaml file

  • ホームディレクトリに配置する
  • 実行時に常に探される (-d スイッチを有効にすることで回避することも可能)
  • さまざまなディレクトリにあるYAML ファイルを絶対パスで指定して呼び出す
  • ファイル名はindentconfig.yaml, .indentconfig.yaml のいずれか

このファイルは設定を書き込むファイルではなく,設定が書き込まれたファイルのパスを書き込むファイル になる.

すなわち,以下のみが書き込まれることになる.

paths:
  - X:\path\to\settings2.yaml
  - X:\path\to\settings1.yaml
  # and more yaml file paths...
  # Any file name you want

settings1.yaml では設定を書き込む.また,読み込み順序は上から順となる.したがって,今回の場合にはsettings2.yamlsettings1.yaml となる.

localSettings.yaml file

  • カレントディレクトリに配置する
  • -l スイッチを有効にすることで読み込まれる
  • ファイル名はlocalSettings.yaml, latexindent.yaml, .localSettings.yaml, .latexindent.yaml のいずれか

容易に利用が出来るので,初めて触る人はここから初めてみると良いかも.

-y switch

  • 特定のTeX ファイルに対してYAML ファイルを作成せずにコマンドラインから簡易的な設定を課すことが出来る
  • 設定を永続的に使用する場合,この-y を利用した設定はあまり現実的な設定ではないと思われる (設定のテストとして一時的に利用する分には有用かもしれない)

Format settings

cf. 5. defaultSettings.yaml

defaultSettings.yaml を確認すればある程度の設定を理解できるだろう.(下にdefaultSettings.yaml を貼り付けておく)

場合によってはdefaultSettings.yamluser-settings.yaml にコピペして設定を変更していくと楽だろう.ただし,変更点が不明瞭になることに注意が必要.
タイプミスすると動かないので注意.本当に.

ここで,latexindent のYAML を編集する上でいくつかの注意点を挙げておきたい.

  • 設定はインデントによって入れ子になっている
  • : のあとには半角スペースを挿入する
  • 真偽値はtrue or false ではなく1 (真) or 0 (偽) で指定するようになっている(非常に読み取りづらい)
  • 一部でPerl に組み込まれた正規表現の利用が可能

基本的にはYAML が扱えれば問題ないと思われる.初心者は慣れるまで難しく感じるかもしれない.

例えば,デフォルトのインデントはdefaultIndent で指定する.タブストップの場合には"\t" とし,半角スペース2つの場合には" " とする.

# Example
defaultIndent: "\t"

正規表現 (Regular expression) について

latexindent で使用される正規表現とはPerl に含まれている正規表現であり,文書内の文字列とマッチさせる際に利用することが出来る.特に# Line Breaks# Replacements で利用することになる.

Perl の正規表現については,公式ページやその他のページで紹介されている.参考にすると良いだろう.


latexindent では基本的に&\\ を整列させたり,インデントをどれだけ設けるかを設定させることが出来る.これらの設定のすべてをここで紹介すると本当に煩雑になってしまうため,ここでは紹介しない.それぞれの節で参照しているlatexindent 公式ページを参照してほしい.
ただし,これ以外の設定に関して知っておいた方が良さそうなものをいくつか紹介しておきたい.

▼ Backup file settings

バックアップファイルの設定.
デフォルトのままフォーマットを実行すれば,すればするだけバックアップファイルは増えてしまうので何かしらの設定はしておく必要がある.

Settings Value type Default value Description
backupExtension 拡張子名 .bak バックアップファイルの拡張子名を任意に変更
onlyOneBackUp 真偽値 0
(false)
バックアップファイルを単数作成にするかどうか
maxNumberOfBackUps 整数値 0 バックアップファイルの最大数
cycleThroughBackUps 真偽値 0
(false)
バックアップファイルをサイクルさせるかどうか

バックアップファイルを常に最後にフォーマットする直前のもののみにする場合は,以下のようにする.

onlyOneBackUp: 1

バックアップファイルを最新のものから4つまででサイクルさせる場合は,以下のようにする.

maxNumberOfBackUps: 4
cycleThroughBackUps: 1

また,デフォルトではログファイルにYAML で設定した内容がそのまま転記される.実際には必要ないので,これは表示しないようにしておきたい.(showEveryYamlRead: 0)

logFilePreferences:
    showEveryYamlRead: 0
    showAmalgamatedSettings: 0

もしも,実行したフォーマットの設定をデフォルトも含めてすべて表示させたい場合には,showAmalgamatedSettings: 1 とすれば良い.ただし,どの設定ファイルから決められたものか追うことは出来ない.

▼ Line breaks

cf. 6. The -m (modifylinebreaks) switch

標準的な使用ではインデントやスペースのみを与えるだけだが,これに改行を加えることも可能になる.このためには-m スイッチの有効化が必要になる. これによって実行される改行は,LaTeX ドキュメントそのものに影響を与える改行ではなく,編集中に見やすくする程度の改行になっている.

したがって,おおよそのエディタでは文章を適宜折り返してくれるため,ほとんどの場合では必要ないと思われる.

▼ Replacements

cf. 7. The -r, -rv and -rr switches — latexindent.pl 3.9.1 documentation

置き換えも可能だ.-r などのスイッチの有効化が必要になる.また,このスイッチには3つのバリエーションがある.以下に示しておく.

Switch Indent Respect verbatim
-r o x
-rv o o
-rr x o

"Indent" では,置換を行ったのちにインデントによる統一が実行されるかどうかを制御している.おおよその場合では,有効になっている方が良いだろう.

"Respect verbatim" では,verbatim 環境やlstlisting 環境などの言語コードをそのまま出力するような環境での置換を行うかどうかを制御している.多くの場合,LaTeX とは異なるフォーマットを持つと思われるため,-r スイッチを利用して置換が行われないようにしておく方が有意義になるだろう.

Known limitations

cf. 9. Conclusions and known limitations

既知の問題はいくつかあるようだ.

微調整することも可能だが,あまりいじらない方が良さそう.

cf. 8. Fine tuning — latexindent.pl 3.9.1 documentation

Reference

Digression

latexindent の設定方法でdefaultSettings.json を編集して設定する記事多くない? ちゃんと公式ドキュメントを参照してくれ……

詳細な設定に関してはまったく触れていないので,これに関しては他の記事を当たってほしい.あるいは公式ドキュメントを見れば確実だろう.かなりいろいろと設定できるので楽しい.

まともな?日本語ドキュメントをここに作成したので,よりよいlatexindent ライフを送れる人が多くなることを願うばかりである.

Example of settings for latexindent

いくつかの設定例を示しておきたい.

LaTeX のフォーマットはかなり個人によるところが大きい.そのため,多くの人にとって有用になりそうなものだけを取り出して紹介しておく.

この他にもさまざまに設定できるので,公式ドキュメントを参照してほしい.

また,これらの設定をする際に正規表現の知識が多分に必要になる場合がある.設定を変更しながら少しずつ理解できると良い.

Commonly used Regex

正規表現について以下などを参照すると良いだろう.

cf. perlreref - Perl の正規表現のリファレンス 5.30.0 | perldoc.jp

間違いが含まれている可能性があるが,現状理解している正規表現についていくつか列挙しておきたい

§ 正規表現の例

Regex Description
\h 半角スペース 1つ
\w a ~z, A ~Z, 0 ~9, _
\s \r, \n, \t, \f, \v,
\S \r, \n, \t, \f, \v, 以外
\d 0 ~9

§ 繰り返し表現

Regex Description
{n,m} n 回からm 回までの繰り返し
{n,} n 回以上の繰り返し
* 0回以上の繰り返し
+ 1回以上の繰り返し

§ 〇定△読み

肯定先読み,肯定後読み,否定先読み,否定後読みというマッチ方法がある.

ここで解説しないが,すこし厄介な概念. 重要なのは,これらのマッチした文字列はキャプチャしない点.

以下のようなものが出てきたら,これらのこと.

lookahead lookbehind
positive ?= ?<=
negative ?! ?<!

また,?: もキャプチャしない.

キャプチャするとキャプチャした文字列を左から順に$1 などと再帰的に利用することが出来る.

§ エスケープ文字

\ でエスケープする必要がある文字.

\ * + . ? { } ( ) [ ] ^ $ - | /

§ Tester

正規表現を試しながらYAML を修正するのは非常に面倒なので,正規表現のみを取り出してテストしてみると良いだろう.

Regex101

lookForAlignDlimis

tabular 環境などの& を揃える設定をすることが出来る.この設定では任意の環境に対して設定できる.すなわち,

lookForAlignDelims:
    hoge: 1

とすれば,hoge 環境内にある& を整列させることが出来る.自作環境に対しても有効にすることが出来るため,非常に有用だと思われる.

また,& 以外でも整列できるように変更できるため,さまざまな環境に対して使える.(コマンドに対しても可能なようである)

tabular 環境では以下のような設定になっているが,これは他の環境でも同じように設定することが出来る.

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

いくつか抜粋した設定の意味を挙げておきたい.

Settings Value description
delims Boolean & で整列の有無
spacesBeforeAmpersand n & の前に挿入されるスペースの数
spacesAfterAmpersand n & の後に挿入されるスペースの数
alignDoubleBackSlash Boolean \\ の整列の有無
spacesBeforeDoubleBackSlash n \\ の前に挿入されるスペースの数

specialBeginEnd

複数行に渡るコマンドブロックに対してインデントを行うことが出来る. 始点となる文字列と終点となる文字列を指定すると,その間にある行にインデントを与えることが出来る.

Auto Bracket indentation

公式ドキュメントでは以下のような\left \right で高さを自動調整する角括弧[] を紹介している.

indentRules:
    leftRightSquare: "  "
specialBeginEnd:
    leftRightSquare:
        begin: '\\left\['
        end: '\\right\]'
        lookForThis: 1

これと同じように丸括弧() や波括弧{} を設定すれば良いが,高さを自動調整するような括弧のバリエーションはさまざまあり,どの組み合わせで括弧を利用するか分からない.

以下のようにまとめてしまえばほとんどを網羅できるだろう.

indentRules:
    leftRightAutoSizeBrackets: '  '
specialBeginEnd:
    leftRightAutoSizeBrackets:
        begin: '\\left(?:\(|\[|\\\{|\.|\\l)'
        end: '\\right(?:\)|\]|\\\}|\.|\\r)'
        lookForThis: 1

丸括弧,角括弧,波括弧,.\l または\r から始まる任意の括弧の組み合わせのコマンドで囲まれた部分ののインデントを行う.すなわち,以下のようなことが出来る.

  \left\lvert
  \frac{1}{x}
  \right)

  \left\lvert
    \frac{1}{x}
  \right)

Replacements

基本的にはthisthat による置換が楽である.複雑な置換は正規表現による置換を利用する.

replacements:
    -
        amalgamate: 1
    -
        this: 'latexindent.pl'
        that: 'pl.latexindent'
        lookForThis: 1
        when: before

また,これらの置換は設定の順序に依存しているようだ.場合によっては気にした方が良いだろう.

正規表現を利用した置換では,-m スイッチを有効にしていなくても\n を挿入すれば改行を許してしまう.利用を禁止しているわけではないようだが,注意した方が良いだろう.

いくつかの置換例を紹介しておく.これらの置換で期待していない置換が行われないとは限らないので注意してほしい.

Remove Zenkaku space

全角スペースを取り除きたい.LaTeX でも全角スペースはあまり良くないため,これを半角スペースに取り替えたい.

以下のようにすれば良い.簡単.

    -
        this: ' '
        that: ' '
        lookForThis: 1

Reduce consecutive half-width spaces to one

連続する半角スペースを1つにしたい.どれだけあってもLaTeX は問題ないが,1つにしておいた方が見栄えが良いだろう.これはtabular 環境などの& を揃える設定には干渉しない.(-rv は除く)

    -
        # Be sure to set it last
        # Combine 2 or more "half-width spaces" into 1
        substitution: s/\h+/ /g
        lookForThis: 1
        when: before

Insert half-width space before/after plus-minus sign

数式環境などで+- の前後に半角スペースが1つあると少し見やすくなる.

    -
        # Insert 1 half-width space before and after "+"
        substitution: s/(?<!\+|\-)\h{0,}\+\h{0,}(?!\+|\-)/ \+ /g
        lookForThis: 1
    -
        # Insert 1 half-width space before and after "-"
        substitution: s/(?<!\+|\-)\h{0,}\-\h{0,}(?!\+|\-)/ \- /g
        lookForThis: 1

*/ の前後にもスペースを入れたくなるかもしれないが,align* 環境やパスに/ を使うことがあるため,あまりこれらの前後にスペースを入れることはしない方が良いだろう.

Insert one half-width space before \

任意のコマンド\hoge の前に半角スペースを1つ挿入する.

    -
        # Insert half-width space before the "\" in any command
        substitution: s/\h{0,}\\(?!=\{)(\w)/ \\$2/g
        lookForThis: 1

コマンド\hoge のが連続する場合,詰まっているとなんだか見づらい気がする.

VSCode formatter settings

VSCode ではLaTeX Workshop から設定することが出来る.latex-formatter をインストールする必要はない.

Format - James-Yu/LaTeX-Workshop Wiki

デフォルトのフォーマッタをLaTeX Workshop に設定しておく. また,latexindent の引数を設定する.デフォルトの設定ではあまり上手く実行できないので変更しておくと良いだろう. ただし,設定ファイルを作成しておくならば以下のように最低限に変更しておいても良いかもしれない.-y スイッチは不要だと思われる.

また,各LaTeX ドキュメントごとにログファイル名を変更したい場合には-g=%DOCFILE%-indent.log などとしておけば良いだろう.

その他,ローカルファイルを読み込む場合には-l スイッチ,置換を実行する場合には-r スイッチを有効にしておくと良いだろう.

settings.json

  "[latex]": {
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "James-Yu.latex-workshop",
  },
  "latex-workshop.latexindent.path": "latexindent",
  "latex-workshop.latexindent.args": [
    "%TMPFILE%",
    "-c=%DIR%/",
    // "-g=%DOCFILE%-indent.log",
    // "-r",
    // "-l",
    // "-y=defaultIndent: '%INDENT%'"
  ],

"editor.formatOnSave": true としている場合,保存時にフォーマットが実行される.無効にしたい場合はfalse にしておく. また,通常のフォーマット実行は保存してからShift +Alt +F を押下すれば良い.もしもlatexindent が実行されない場合は"latex-workshop.latexindent.path" を絶対パスで指定する.

また,latexindent からバックアップファイルなどを出力するディレクトリを指定する-c オプションがあるが,これは-c=<output_directory>/ とするのが正規の方法になるようだ. したがって,デフォルトであっても"-c=%DIR%/" とする必要がある(と思われる)

余談にはなるが,カレントディレクトリ以下に.\tmp などとして,このフォルダにバックアップファイルを入れたい場合には,-c=%DIR%/tmp/ とすれば良い.ただし,-c オプションにはフォルダを作成する機能は無いようだ.事前にフォルダを作成しておこう.

経験的に-s スイッチと-w スイッチは有効にしない方が良い.これらを有効にすると不具合が出るように感じられた.特に公式Wiki には記載されていなかったが,注意しておいて損はないと思われる.また,VSCode でフォーマットする分には必要のないスイッチではある.

ちなみに,プレースホルダ%INDENT% はsettings.json の"editor.insertSpaces""editor.tabSize" を反映して,インデントが"タブストップ" または"スペースいくつ分か" を挿入しているようだ.

cf. Format · James-Yu/LaTeX-Workshop Wiki · GitHub

Trim Final new lines and Trailing whitespace

VSCode の標準機能として,ファイル末の空白改行と行末の半角スペースを保存時に削除する機能を有効にすることも出来る.(latexindent でも可能) 利用する場合は,これらも[latex] 内に含めておくと良いだろう.

  "files.trimFinalNewlines": true,
  "files.trimTrailingWhitespace": true,

また,Ctrl+K Ctrl+X を押下して行末の半角スペースを削除することも出来る.(editor.action.trimTrailingWhitespace の実行)

全角スペースの削除等はVSCode 標準では対応していないが,mosapride.zenkaku を利用して視覚化したうえで削除すれば良いだろう. IME キーボードであればスペースキーを半角スペースのみにすることも可能なので,全角スペースを打てないようにしておくのも一つの手になる.
あるいは,全角スペースを半角スペースに置換すると良いだろう.

WARNING from VSCode

VSCode から以下のような警告をもらうことがある.

Formatting failed. Please refer to LaTeX Workshop Output for details.

Ctrl+Shift+U からOutput > LaTeX Wrokshop を確認するとフォーマッタの実行状況を確認することが出来るので,問題点を確認しておこう.

場合によってはlatexindent が導入されていないことやPerl が必要になっているなどもあり得るだろう.

▼ MALFUNCTION as formatter

いくつか不具合が見られたので紹介しておきたい.ただし,これらは個人的な設定が良くないのかどうか怪しいところがある.また,これの解決方法は特にない.

  1. latexindent を実行するとindent.log が出力されるはずなのだが,なぜか出力されない場合がある(ホームディレクトリに出力されている?)
  2. _latexindent_temp.tex が出力されることがある

_latexindent_temp.tex が出力されている時にはエラーが生じているためにフォーマットが中途で終わっているためのこともある.

LaTeX Workshop 側の問題かどうかを検証するためにCtrl+@ でターミナルを開いて実行してみることも大事になる. それでも解決できない場合にはGitHub にIssue として挙げれば回答が返ってくるだろう.

▼ KILL formatter

latexindent が終了しない場合,タスクマネージャからlatexindent.exe をタスク終了させれば良い. VSCode からlatexindent を停止させる方法はCtrl+C 出来ないためにおそらくこの方法しかない.

gitignore

latexindent によるフォーマットが上手くいかなかった場合,__latexindent_temp.tex が生成されたままになる.これをGit によって監視し続けてもしょうがないので,これを避けるために以下のように追加しておこう.

__latexindent_temp.tex

また,バックアップファイルをGit によって監視してほしくない場合には,以下も追加しておくと良いだろう.

*.bak
*.bak[0-9]

Digression

これでVSCode でlatexindent 使っていても困ることはないはず.

# defaultSettings.yaml for latexindent.pl, version 3.9.1, 2021-03-21
# a script that aims to
# beautify .tex, .sty, .cls files
#
# (or latexindent.exe if you're on Windows)
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# See http://www.gnu.org/licenses/.
#
# Chris Hughes, 2017
#
# For all communication, please visit: https://github.com/cmhughes/latexindent.pl
# You should feel encouraged to change anything you like in these settings, but
# it would probably be better to have your own user settings
# files somewhere else - remember that this file may be overwritten
# when you update your tex distribution. Please see the manual linked from:
#
# https://github.com/cmhughes/latexindent.pl
#
# for details of how to create and configure your own settings files.
#
# Please read the manual (linked from above) first to understand what each switch does.
# latexindent can be called to act on a file without using the file's extension,
# e.g, simply
# latexindent myfile
# in which case the choice of file extension is chosen
# according to the choices made in fileExtensionPreference
# Other file extensions can be added.
fileExtensionPreference:
.tex: 1
.sty: 2
.cls: 3
.bib: 4
# default file extension of backup file (if -w switch is active)
# for example, if your .tex file is called
# myfile.tex
# and you specify the backupExtension as BACKUP.bak then your
# backup file will be
# myfileBACKUP.bak
backupExtension: .bak
# only one backup per file:
# - if onlyOneBackUp is 0 then, as a safety measure,
# the number on the extension increments by 1 each time:
#
# myfile.bak0, myfile.bak1, myfile.bak2
# - if you set onlyOnebackUp to 1, then the backup file will
# be overwritten each time (not recommended until you trust the script)
onlyOneBackUp: 0
# some users may want a finite number of backup files,
# say at most 3; in which case, they can change this maxNumberOfBackUps.
#
# If maxNumberOfBackUps is set to 0 (or less) then infinitely
# many backups are possible, unless onlyOneBackUp is switched on
maxNumberOfBackUps: 0
# some users may wish to cycle through back up files.
#
# for example, with maxNumberOfBackUps: 4, they may
# wish to delete the oldest back up file, and keep only the most recent.
#
# 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 back up will be written to myfile.bak4
cycleThroughBackUps: 0
# preferences for information displayed in the log file
logFilePreferences:
showEveryYamlRead: 1
showAmalgamatedSettings: 0
showDecorationStartCodeBlockTrace: 0
showDecorationFinishCodeBlockTrace: 0
endLogFileWith: '--------------'
showGitHubInfoFooter: 1
# verbatim environments specified
# in this field will not be changed at all!
verbatimEnvironments:
verbatim: 1
lstlisting: 1
minted: 1
# verbatim commands such as \verb! body !, \lstinline$something else$
verbatimCommands:
verb: 1
lstinline: 1
# no indent blocks (not necessarily verbatim
# environments) which are marked as %\begin{noindent}
# or anything else that you detail in the following
noIndentBlock:
noindent: 1
cmhtest: 1
# remove trailing whitespace from all lines
removeTrailingWhitespace:
beforeProcessing: 0
afterProcessing: 1
# \begin{document} and \end{document} are treated differently
# by latexindent within filecontents environments
fileContentsEnvironments:
filecontents: 1
filecontents*: 1
# indent preamble
indentPreamble: 0
# assume no preamble in cls, sty, by default
lookForPreamble:
.tex: 1
.sty: 0
.cls: 0
.bib: 0
# some preambles can contain \begin and \end statements
# that are not in their 'standard environment block', for example,
# consider the following key = values:
# preheadhook={\begin{mdframed}[style=myframedstyle]},
# postfoothook=\end{mdframed},
preambleCommandsBeforeEnvironments: 0
# default value of indentation
defaultIndent: "\t"
# name of code blocks that should have their body aligned at ampersand delimiters
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
tabu: 1
array: 1
matrix: 1
listabla: 1
# amsmath
align: 1
align*: 1
alignat: 1
alignat*: 1
aligned: 1
bmatrix: 1
Bmatrix: 1
cases: 1
flalign: 1
flalign*: 1
pmatrix: 1
vmatrix: 1
Vmatrix: 1
# mathtools
cases*: 1
dcases: 1
dcases*: 1
rcases: 1
rcases*: 1
drcases: 1
drcases*: 1
# nicematrix
NiceMatrix: 1
pNiceMatrix: 1
bNiceMatrix: 1
BNiceMatrix: 1
vNiceMatrix: 1
VNiceMatrix: 1
NiceArray: 1
pNiceArrayC: 1
bNiceArrayC: 1
BNiceArrayC: 1
vNiceArrayC: 1
VNiceArrayC: 1
NiceArrayCwithDelims: 1
pNiceArrayRC: 1
bNiceArrayRC: 1
BNiceArrayRC: 1
vNiceArrayRC: 1
VNiceArrayRC: 1
NiceArrayRCwithDelims: 1
# if you want the script to look for \item commands
# and format it, as follows (for example),
# \begin{itemize}
# \item content here
# next line is indented
# next line is indented
# \item another item
# \end{itemize}
# then populate indentAfterItems. See also itemNames
indentAfterItems:
itemize: 1
enumerate: 1
description: 1
list: 1
# if you want to use other names for your items (for example, \part)
# then populate them here; note that you can trick latexindent.pl
# into indenting all kinds of commands (within environments specified in
# indentAfterItems) using this technique.
itemNames:
item: 1
myitem: 1
# specialBeginEnd is, by default, mathmode focus, although
# there's no restrictions
specialBeginEnd:
displayMath:
begin: '\\\['
end: '\\\]'
lookForThis: 1
inlineMath:
begin: '(?<!\$)(?<!\\)\$(?!\$)'
end: '(?<!\\)\$(?!\$)'
lookForThis: 1
displayMathTeX:
begin: '\$\$'
end: '\$\$'
lookForThis: 1
specialBeforeCommand: 0
# if you want to add indentation after
# a heading, such as \part, \chapter, etc
# then populate it in here - you can add
# an indent rule to indentRules if you would
# like something other than defaultIndent
#
# you can also change the level if you like,
# or add your own title command
indentAfterHeadings:
part:
indentAfterThisHeading: 0
level: 1
chapter:
indentAfterThisHeading: 0
level: 2
section:
indentAfterThisHeading: 0
level: 3
subsection:
indentAfterThisHeading: 0
level: 4
subsection*:
indentAfterThisHeading: 0
level: 4
subsubsection:
indentAfterThisHeading: 0
level: 5
paragraph:
indentAfterThisHeading: 0
level: 6
subparagraph:
indentAfterThisHeading: 0
level: 7
# maximum indentation, off by default
maximumIndentation: -1
# if you don't want to have additional indentation
# in a code block, then add it to noAdditionalIndent; note that
# code blocks in this field will inherit
# the *current* level of indentation they just won't
# get any *additional* indentation
noAdditionalIndent:
myexample: 1
mydefinition: 1
problem: 1
exercises: 1
mysolution: 1
foreach: 0
widepage: 1
comment: 1
document: 1
frame: 0
# if you have indent rules for particular code blocks
# then you can populate them in indentRules; for example, you might just want
# to use a space " " or maybe a double tab "\t\t"
indentRules:
myenvironment: "\t\t"
anotherenvironment: "\t\t\t\t"
chapter: " "
section: " "
item: " "
myitem: " "
# set noAdditionalIndent globally for codeblocks
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
# set indentRules globally for codeblocks; these need
# to be horizontal spaces, if they are to be used
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
# command code block details
commandCodeBlocks:
roundParenthesesAllowed: 1
stringsAllowedBetweenArguments:
-
amalgamate: 1
- 'node'
- 'at'
- 'to'
- 'decoration'
- '\+\+'
- '\-\-'
- '\#\#\d'
commandNameSpecial:
-
amalgamate: 1
- '@ifnextchar\['
# modifyLineBreaks will only be searched if the -m
# switch is active
#
# poly-switch examples:
#
# BeginStartsOnOwnLine:
# modify line breaks before a begin statement
#
# when set to -1, e.g
# some text some text
# \begin{myenvironment}
# will be changed to
# some text some text \begin{myenvironment}
# when set to 0, the switch is ignored
# when set to 1, e.g
# some text some text \begin{myenvironment}
# will be changed to
# some text some text
# \begin{myenvironment}
# when set to 2, e.g
# some text some text \begin{myenvironment}
# will be changed to
# some text some text%
# \begin{myenvironment}
# when set to 3, e.g
# some text some text \begin{myenvironment}
# will be changed to
# some text some text
#
# \begin{myenvironment}
#
# BodyStartsOnOwnLine:
# modify line breaks before the beginning of the body
#
# when set to -1, e.g
# \begin{myenv}
# body text body text
# will be changed to
# \begin{myenv}body text body text
# when set to 0, the switch is ignored
# when set to 1, e.g
# \begin{myenv}body text body text
# will be changed to
# \begin{myenv}
# body text body text
# when set to 2, e.g
# \begin{myenv}body text body text
# will be changed to
# \begin{myenv}%
# body text body text
# when set to 3, e.g
# \begin{myenv}body text body text
# will be changed to
# \begin{myenv}
#
# body text body text
#
# EndStartsOnOwnLine:
# modify line breaks before the end statement
#
# when set to -1, e.g
# some text some text
# \end{myenvironment}
# will be changed to
# some text some text \end{myenvironment}
# when set to 0, the switch is ignored
# when set to 1, e.g
# some text some text \end{myenvironment}
# will be changed to
# some text some text
# \end{myenvironment}
# when set to 2, e.g
# some text some text \end{myenvironment}
# will be changed to
# some text some text%
# \end{myenvironment}
# when set to 3, e.g
# some text some text \end{myenvironment}
# will be changed to
# some text some text
#
# \end{myenvironment}
#
# EndFinishesWithLineBreak:
# modify line breaks after the end statement
#
# when set to -1, e.g
# \end{myenvironment}
# some text some text
# will be changed to
# \end{myenvironment}some text some text
# when set to 0, the switch is ignored
# when set to 1, e.g
# \end{myenvironment}some text some text
# will be changed to
# \end{myenvironment}
# some text some text
# when set to 2, e.g
# \end{myenvironment}some text some text
# will be changed to
# \end{myenvironment}%
# some text some text
# when set to 3, e.g
# \end{myenvironment}some text some text
# will be changed to
# \end{myenvironment}
#
# some text some text
#
# you can specify settings on a per-name basis
modifyLineBreaks:
preserveBlankLines: 1
condenseMultipleBlankLinesInto: 1
oneSentencePerLine:
manipulateSentences: 0
removeSentenceLineBreaks: 1
textWrapSentences: 0
sentenceIndent: ""
sentencesFollow:
par: 1
blankLine: 1
fullStop: 1
exclamationMark: 1
questionMark: 1
rightBrace: 1
commentOnPreviousLine: 1
other: 0
sentencesBeginWith:
A-Z: 1
a-z: 0
other: 0
sentencesEndWith:
basicFullStop: 0
betterFullStop: 1
exclamationMark: 1
questionMark: 1
other: 0
textWrapOptions:
columns: 0
separator: ""
perCodeBlockBasis: 0
all: 0
alignAtAmpersandTakesPriority: 1
environments:
quotation: 0
ifElseFi: 0
optionalArguments: 0
mandatoryArguments: 0
items: 0
specialBeginEnd: 0
afterHeading: 0
preamble: 0
filecontents: 0
masterDocument: 0
removeParagraphLineBreaks:
all: 0
beforeTextWrap: 0
alignAtAmpersandTakesPriority: 1
environments:
quotation: 0
ifElseFi: 0
optionalArguments: 0
mandatoryArguments: 0
items: 0
specialBeginEnd: 0
afterHeading: 0
preamble: 0
filecontents: 0
masterDocument: 0
paragraphsStopAt:
environments: 1
verbatim: 1
commands: 0
ifElseFi: 0
items: 0
specialBeginEnd: 0
heading: 0
filecontents: 0
comments: 0
environments:
BeginStartsOnOwnLine: 0
BodyStartsOnOwnLine: 0
EndStartsOnOwnLine: 0
EndFinishesWithLineBreak: 0
equation*:
BeginStartsOnOwnLine: 0
BodyStartsOnOwnLine: 0
EndStartsOnOwnLine: 0
EndFinishesWithLineBreak: 0
ifElseFi:
IfStartsOnOwnLine: 0
BodyStartsOnOwnLine: 0
OrStartsOnOwnLine: 0
OrFinishesWithLineBreak: 0
ElseStartsOnOwnLine: 0
ElseFinishesWithLineBreak: 0
FiStartsOnOwnLine: 0
FiFinishesWithLineBreak: 0
ifnum:
IfStartsOnOwnLine: 0
BodyStartsOnOwnLine: 0
OrStartsOnOwnLine: 0
OrFinishesWithLineBreak: 0
ElseStartsOnOwnLine: 0
ElseFinishesWithLineBreak: 0
FiStartsOnOwnLine: 0
FiFinishesWithLineBreak: 0
commands:
CommandStartsOnOwnLine: 0
CommandNameFinishesWithLineBreak: 0
optionalArguments:
LSqBStartsOnOwnLine: 0
OptArgBodyStartsOnOwnLine: 0
RSqBStartsOnOwnLine: 0
RSqBFinishesWithLineBreak: 0
mandatoryArguments:
LCuBStartsOnOwnLine: 0
MandArgBodyStartsOnOwnLine: 0
RCuBStartsOnOwnLine: 0
RCuBFinishesWithLineBreak: 0
keyEqualsValuesBracesBrackets:
KeyStartsOnOwnLine: 0
EqualsStartsOnOwnLine: 0
EqualsFinishesWithLineBreak: 0
items:
ItemStartsOnOwnLine: 0
ItemFinishesWithLineBreak: 0
namedGroupingBracesBrackets:
NameStartsOnOwnLine: 0
NameFinishesWithLineBreak: 0
specialBeginEnd:
SpecialBeginStartsOnOwnLine: 0
SpecialBodyStartsOnOwnLine: 0
SpecialEndStartsOnOwnLine: 0
SpecialEndFinishesWithLineBreak: 0
verbatim:
VerbatimBeginStartsOnOwnLine: 0
VerbatimEndFinishesWithLineBreak: 0
# replacements, only active when either -r or -rr switches are active
replacements:
-
amalgamate: 1
-
this: 'latexindent.pl'
that: 'pl.latexindent'
lookForThis: 1
when: before
# fineTuning allows you to tweak the internal pattern matching that
# is central to latexindent.pl
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_\:]+?'
keyEqualsValuesBracesBrackets:
name: '[a-zA-Z@\*0-9_\/.:\#-]+[a-zA-Z@\*0-9_\/.\h\{\}:\#-]*?'
follow: '(?:(?<!\\)\{)|,|(?:(?<!\\)\[)'
namedGroupingBracesBrackets:
name: '[0-9\.a-zA-Z@\*><]+?'
follow: '\h|\R|\{|\[|\$|\)|\('
UnNamedGroupingBracesBrackets:
follow: '\{|\[|,|&|\)|\(|\$'
arguments:
before: '(?:#\d\h*;?,?\/?)+|\<.*?\>'
between: '_|\^|\*'
modifyLineBreaks:
betterFullStop: '(?:\.\)(?!\h*[a-z]))|(?:(?<!(?:(?:e\.g)|(?:i\.e)|(?:etc))))\.(?!(?:[a-z]|[A-Z]|\-|~|\,|[0-9]))'
doubleBackSlash: '\\\\(?:\h*\[\h*\d+\h*[a-zA-Z]+\h*\])?'
comma: ','
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment