uplatexでSyncTeXするための最低限のVS Code設定

## 本稿の目標

VS CodeでLaTeXを使う場合, 拡張機能 [LaTeX Workshop](https://marketplace.visualstudio.com/items?itemName=James-Yu.latex-workshop) を用いるのがスタンダードになっていますが, (u)platex を使おうと思うと少し設定が大変です.

そのため, 解説ページがいくつかあります:


- [TeXはVSCodeとLaTeX Workshopで書け](https://kajindowsxp.com/texworkshop/)
- [VSCode で最高の LaTeX 環境を作る - Qiita](https://qiita.com/rainbartown/items/d7718f12d71e688f3573)
- [LaTeX Workshop を使いこなす - Qiita](https://qiita.com/Yarakashi_Kikohshi/items/a9357dd469320ffb65a0)
- [Visual Studio Code/LaTeX - TeX Wiki](https://texwiki.texjp.org/?Visual%20Studio%20Code%2FLaTeX)


しかし, (u)platexで文章を書くだけの人にとっては余計な設定が多く, コピペしてブラックボックスとして使うことになる可能性があります.
それでも動けば良いかもしれませんが, エラーが出たときに大変です.

そこで本稿では, **なるべく簡単な設定でuplatexを使いつつ, SyncTeXも利用できるようにする**ことを目指します.
なお, SyncTeXとは, texファイルとpdfファイルの間を行き来できる仕組みです.
例えば, VS Codeでpdfを表示する場合, 


- texファイル上で `Ctrl` + `Alt` + `J` を押すと, **texファイルのカーソル位置に対応するpdfファイルの位置にジャンプする**
- pdfファイル上で `Ctrl` を押しながらクリックすると, **クリックした位置に対応するtexファイルの位置にカーソルが飛ぶ**

といったことが可能になり, 非常に便利です.

### 参考リンク

http://uncorrelated.hatenablog.com/entry/2020/10/23/143623

上記サイトはかなりシンプルな設定を紹介していますが, SyncTeXに関する設定はしていませんので, 本稿はこれにSyncTeXの設定を加える形になります.

### 前提

Windowsでの作業を前提としてます. その上で,

- LaTeX, VS Code, LateX Workshop がインストールされている
- VS CodeはPATHが通っている
- [Sumatra PDF](https://www.sumatrapdfreader.org/free-pdf-reader.html)でpdfを表示する場合, これもインストールされている

ことは仮定します.

なお, LaTeXによる簡単な文書作成ができか, これからやろうとしている人を読者として想定しています.
これからの人はこちらもご覧ください (宣伝):

https://qiita.com/t_kemmochi/items/78064daaa3903b7925ab


## 基本の設定

pdfファイルによるプレビューをVS Code内で行うか, Sumatra PDF等の外部アプリで行うかによって, 少し設定方法が異なります.
まずは, 両方に共通する設定を説明します.


### 手順1. `.latexmkrc` を作る (このファイルがない場合)

まずはlatexmkに関する設定をします.
(latexmkに関しては下記折りたたみ内を参照してください)

1. ホームディレクトリ (Windowsの場合, ユーザー名のフォルダ) で右クリック → 「Codeで開く」をクリック <br> (「Codeで開く」がない場合: [Windowsの右クリックメニューに「VSCodeで開く」を追加する](https://qiita.com/kaityo256/items/7fefd1d1463184ae1420))
1. 左上のところの, 下図のボタンをクリックし, 新しいファイルを作る <br>![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/111178/d014b1a7-2deb-2581-b26f-b9f176bdc003.png)
1. ファイル名として, `.latexmkrc` と記入する (先頭にドットを入れる)
1. `.latexmkrc` に次を入力して保存: 

```
$latex = 'uplatex %O %S';
$bibtex = 'upbibtex %O %B';
$dvipdf = 'dvipdfmx %O -o %D %S';
$max_repeat = 10;
```

<details><summary>この部分で何をやっているか (折りたたみ)</summary>
<div>
ここでは, latexmk というソフトに関する設定をしています (VS Codeは関係ありません).
そもそもLaTeXでは, 数式番号などの相互参照をした場合, 複数回のコンパイルが必要です.
ファイルの編集のたびに複数回のコンパイルを手作業で行うのは面倒ですので, なるべくなら機械に任せたいところです.
それを可能にしてくれるのが latexmk というソフトです.

`.latexmkrc` は, latexmk を実行する際の設定を記述しています.
上に記入した4行は順に, 

1. latexのコンパイルには `uplatex %O %S` というコマンドを実行せよ
1. bibtexのコンパイルには `upbibtex %O %B` というコマンドを実行せよ
1. dviファイルをpdfファイルに変換するには `dvipdfmx %O -o %D %S` というコマンドを実行せよ
1. コンパイルが終わらなくても10回で停止せよ

という意味になっています. 
ただし, `%O` などはプレースホルダーです.
それぞれの意味は, latexmk のマニュアルを参照してください.
([CTAN](https://www.ctan.org/pkg/latexmk/) の「Manual page, PDF」のp.21～22)

</div>
</details>


### 手順2. LaTeX Workshop の tools の設定 

LaTeX Workshop は, 

- tools によってコンパイル時のコマンドを指定
- recipe によってtoolsの組み合わせを指定

という二段構えになっています. まずは, 1段目の tools を設定します.

1. VS Codeの設定画面を開く (`Ctrl` + `,` (カンマ) で開く) 
1. テキストボックスに `latex-workshop.latex.tools` と入力し, 出てくる項目の「settings.json で編集」をクリック[^settings]
1. `settings.json` が開き, 以下のような位置にカーソルが来るはず 

[^settings]: 直接 `settings.json` を開いて設定するのではなく, 少し面倒な方法をとっていますが, これはわざとです. こうすることで他の tools が `settings.json` に表示されるので, どんな tool が定義されているかがわかりやすくなると思います. こうしない場合, 他の tools として何があるかを調べるためには, `defaultSettings.json` を開く必要があります.

```json:settings.json
    "latex-workshop.latex.tools": [
       //←ここにカーソル
        {
            "name": "latexmk",
            "command": "latexmk",
            "args": [
                "-synctex=1",
                "-interaction=nonstopmode",
                "-file-line-error",
                "-pdf",
                "-outdir=%OUTDIR%",
                "%DOC%"
            ],
            "env": {}
        },
        (以下省略)
```

そのカーソル位置に次のように追記し, 保存する

```json:settings.json
    "latex-workshop.latex.tools": [
        { // ここから追記
            "name": "latexmk-uplatex",
            "command": "latexmk",
            "args": [
                "-synctex=1",
                "-interaction=nonstopmode",
                "-file-line-error",
                "-pdfdvi",
                "-outdir=%OUTDIR%",
                "%DOC%"
            ],
            "env": {}
        }, // ここまで追記
        {
            "name": "latexmk",
            "command": "latexmk",
            "args": [
                "-synctex=1",
                "-interaction=nonstopmode",
                "-file-line-error",
                "-pdf",
                "-outdir=%OUTDIR%",
                "%DOC%"
            ],
            "env": {}
        },
        (以下省略)
```

この設定は, 「`"latexmk-uplatex"` という名前の, 以下のコマンドを実行する tool を作るよ」という意味です.

```bash
latexmk -synctex=1 -interaction=nonstopmode -file-line-error -pdfdvi -outdir=%OUTDIR% %DOC%
```

`%OUTDIR` 等は LaTeX Workshop のプレースホルダーです.
それぞれの意味は[公式ドキュメント](https://github.com/James-Yu/LaTeX-Workshop/wiki/Compile#placeholders)を参照してください.


### 手順3. LaTeX Workshop の recipes の設定

LaTeX Workshop の設定の2段目, recipes の設定をします.

1. 設定画面のテキストボックスに `latex-workshop.latex.recipes` と入力し, 出てくる項目の「settings.json で編集」をクリック
1. 今度は以下のような位置にカーソルが来るはず:

```json

    "latex-workshop.latex.recipes": [
       //←ここにカーソル
        {
            "name": "latexmk 🔃",
            "tools": [
                "latexmk"
            ]
        },
        (以下省略)
```

そのカーソル位置に次のように追記し, 保存する

```json
    "latex-workshop.latex.recipes": [
        { // ここから追記
            "name": "latexmk (uplatex)",
            "tools": [
                "latexmk-uplatex"
            ]
        }, // ここまで追記
        {
            "name": "latexmk 🔃",
            "tools": [
                "latexmk"
            ]
        },
        (以下省略)
```

これは, 「`"latexmk-uplatex"` という tool を使う, `"latexmk (uplatex)"`という名前の recipe を作るよ」という意味です.


### 手順4. VS Code のその他の設定

VS Codeの設定画面で, 以下の項目を設定すると良いです.
それぞれ, 項目の部分を設定画面のテキストボックスに入力すると, その項目だけを絞り込めます.

| 項目 | 値/チェック等 | 意味 |
| --- | --- | --- |
| `editor.suggest.snippetsPreventQuickSuggestions` | `false` | スニペットに関する挙動 |
| `latex-workshop.intellisense.package.enabled` | `true` | コマンドの補完について (お好みで) |
| `latex-workshop.latex.autoBuild.run` | `onSave` | 保存すると自動コンパイル |
| `latex-workshop.latex.autoClean.run` | `onBuilt` | pdfファイル出力後に一時ファイルなどを削除 |
| `latex-workshop.synctex.afterBuild.enabled` | `true` |  コンパイル後にtexファイルのカーソル位置に対応するpdfの位置に飛ぶ |
| `latex-workshop.latex.recipe.default` | `first` または `latexmk (uplatex)` | デフォルトの recipe をどうするか |


## VS Code内でプレビューする場合の設定

VS Codeの設定画面で, `latex-workshop.view.pdf.viewer` を `tab` に設定します.
これは, 「pdfファイルをVS Code内で開く」という意味です.


ここまで終われば, あとはtexファイルを作って保存すると, 自動でコンパイルしてくれます.
しかも, SyncTeX によって, 以下の操作が可能になります:

- texファイル上で `Ctrl` + `Alt` + `J` (Jump の J と覚える) と押すと, texファイルのカーソル位置に対応するpdfファイルの位置にジャンプする
- pdfファイル上で `Ctrl` を押しながらクリックすると, クリックした位置に対応するtexファイルの位置にカーソルが飛ぶ



## Sumatra PDFでpdfファイルを開く場合

Sumatra PDFを用いる場合, 少し設定項目が増えます.
参考: [Using SyncTeX with an external viewer](https://github.com/James-Yu/LaTeX-Workshop/wiki/View#using-synctex-with-an-external-viewer)

### 手順1. VS Codeの設定

まず, 新たに以下のように設定してください.

| 項目 | 値/チェック等 | 意味 |
| --- | --- | --- |
| `latex-workshop.view.pdf.viewer`  | `external` | pdfファイルを外部ビューアで開く |
| `latex-workshop.view.pdf.external.viewer.command` | `SumatraPDF.exe` のパスを入力 | 外部ビューアとしてSumatra PDFを使う |
| `latex-workshop.view.pdf.external.synctex.command` | `SumatraPDF.exe` のパスを入力  | SyncTeXにもSumatra PDFを使う |

さらに, `latex-workshop.view.pdf.external.synctex.args` を以下の図のようにします:
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/111178/85f0b5c8-975d-2c41-5a9c-a47c5e37c6d2.png)


入力内容を以下に記載します.

```
-forward-search
%TEX%
%LINE%
-reuse-instance
-inverse-search
code -r -g "%f:%l"
%PDF%
```
1つずつ入力するのが面倒な場合は, `settings.json` を開いて, 以下を記入します.

```settings.json
    "latex-workshop.view.pdf.external.synctex.args": [
        "-forward-search",
        "%TEX%",
        "%LINE%",
        "-reuse-instance",
        "-inverse-search",
        "code.cmd -r -g \"%f:%l\"",
        "%PDF%",
    ]
```

### 手順2. Sumatra PDFの設定 (これは不要？)

Sumatra PDFを開き, 以下のようにします.
 
1. 左上の [三] みたいなボタンをクリック → 設定 → 詳細設定 と進み, `SumatraPDF-settings.txt` を開く.
1. `Ctrl` + `F` によって `EnableTeXEnhancements` を検索し, 該当する部分が `false` になっていたら `true` にする
1. `SumatraPDF-settings.txt` を上書き保存して閉じる
1.  [三]  → 設定 → オプション と進み, 「逆順検索コマンドラインの設定」に以下を記入し, OKをクリックして閉じる:

```bash
code.cmd -r -g "%f:%l"
```

これによってSyncTeXが使えるようになり,

- texファイル上で `Ctrl` + `Alt` + `J` と押すと, texファイルのカーソル位置に対応するpdfファイルの位置にジャンプする
- pdfファイル上で ダブルクリックすると, クリックした位置に対応するtexファイルの位置にカーソルが飛ぶ


## 終わりに

ちょっと長くなりましたが, いろいろと説明を書いたからで, 実際に設定していることはそこまで多くない, と思います.
より複雑なことをやりたい場合は, 冒頭に上げたリンク先を参照してください.