LaTeX Workshop をもっと使いこなす

# LaTeX Workshop をもっと使いこなす

:::note info
[LaTeX Workshop \| James Yu](https://marketplace.visualstudio.com/items?itemName=James-Yu.latex-workshop)
投稿時; ver.8.14.0（2020/12 現在）、最終更新時; **ver.8.28.0**
:::

本記事ではもっと使いこなすと銘打っているので、最大限使っていきたい。
ホバーによるプレビュー機能とインテリセンス機能、エラー等のメッセージについて紹介していく。

これらのホバーやインテリセンス、メッセージはデフォルトでは有効 (`true`) になっている。このままでも全く問題ないが、不必要に感じる機能があれば無効化させておくと良いだろう。

関連記事は [\# この節](#関連記事) にあります。

## ○ Hover & IntelliSense

<!-- 読むのが面倒だったら画像だけ見るだけでも良さそう。なホバーとインテリセンスたち。編集しているときにはこれなしにはやっていけなくなる中毒性もありそう。（そんなものはない） -->

### ■ 概要

まずはざっくりと一覧を示しておきたい。そのあとにそれぞれの詳細を与えていく。

正直どちらの機能なのか分からないような場合があるが、設定で `"~.hover.++"` となっていればホバー機能、`"~.intellisense.++"` となっていればインテリセンス機能としている。

#### ▼ Hover

![preview equations](https://github.com/James-Yu/LaTeX-Workshop/raw/master/demo_media/hover.gif "https://github.com/James-Yu/LaTeX-Workshop/raw/master/demo_media/hover.gif")

エディタ画面で特定のコマンド等にマウスポインタを合わせると、様々な情報をホバーウィンドウによって閲覧することが出来る。
ホバーで見ることのできるものの一覧は以下のようなものになる。

- `\usepackage` で読み込まれるパッケージ（ここからローカルにあるドキュメントや CTAN を開けることも可能）
- コマンドからどのパッケージから提供されているのかを見る
- 特定の数式環境のプレビュー表示
    - `\newcommand` で定義されたコマンドの数式のホバー
    - 相互参照で `\ref` となっている数式
- `\includegraphics` で読み込まれる画像ファイル
- `\cite` で参照された引用

<!-- ※ tabular 環境はサポートされていない。(「tabular 環境はサポートされていない」とわざわざ明記されていたのは、のちにはサポートされるということなのだろうか…) -->

#### ▼ IntelliSense

![reference intellisense png](https://github.com/James-Yu/LaTeX-Workshop/blob/master/demo_media/figure%20intelisense.png?raw=true "https://github.com/James-Yu/LaTeX-Workshop/blob/master/demo_media/figure%20intelisense.png")

以下のオートコンプリート（サジェストを表示して補完する機能）が有効になる。
相互参照や新たに定義したコマンドなど（パッケージ名やデフォルトのスニペット以外）のオートコンプリートは保存時に解析が実行され有効になるようだ。

- 文書クラス名、パッケージ名のオートコンプリート（CTAN 提供のもの）
- コマンドや環境名のオートコンプリート
- 相互参照の際の `\ref` コマンドに対する label 名のオートコンプリート
- BibTeX のオートコンプリート
- ファイル名のオートコンプリート

<!--
<details>
<summary> デフォルトのインテリセンス設定一部抜粋（折りたたみ）</summary>
<div>

もしもインテリセンスが邪魔に感じる場合は、以下の設定を `false` にしてしまえば良いだろう。

|                             設定                              | 説明 |
| :-----------------------------------------------------------: | :--- |
| `latex-workshop.intellisense.includegraphics.preview.enabled` |      |
|         `latex-workshop.intellisense.package.enabled`         |      |
|       `latex-workshop.intellisense.package.env.enabled`       |      |

```json
  "latex-workshop.intellisense.includegraphics.preview.enabled": true,
  "latex-workshop.intellisense.includegraphics.preview.pdf.enabled": true,
  "latex-workshop.intellisense.package.enabled": true,
  "latex-workshop.intellisense.package.env.enabled": true,
  "latex-workshop.intellisense.optionalArgsEntries.enabled": true,
  "latex-workshop.intellisense.label.keyval": true,
```
-->

インテリセンスをより拡張したり個人的なインテリセンスを作成したい場合には、以下の記事を参照してほしい。

> [LaTeX Workshop のインテリセンスをカスタマイズする - Qiita](https://qiita.com/Yarakashi_Kikohshi/items/165d1180aa515655aebd)

### ■ パッケージ

パッケージ名の自動補完し、`\usepackage` の上にマウスポインタを置くと **View documentation** が表示され、ここから texdoc を利用してパッケージドキュメントを開くことができる。

![package view](https://github.com/James-Yu/LaTeX-Workshop/raw/master/demo_media/hover-package.gif "https://github.com/James-Yu/LaTeX-Workshop/raw/master/demo_media/hover-package.gif")

パッケージガイドを開くための *texdoc* のコマンドと引数は以下のように設定されている。おおよそこのままで問題ないと思われる。

```json
  "latex-workshop.texdoc.path": "texdoc",
  "latex-workshop.texdoc.args": ["--view"],
```

また、パッケージから提供されるコマンドの上にマウスポインタを置くと、ざっくりとしたコマンドの使い方と**View documentation for package(s) hoge** が表示され、パッケージドキュメントを開くことが出来る。

![commands document view](https://github.com/James-Yu/LaTeX-Workshop/raw/master/demo_media/hover-command.gif "https://github.com/James-Yu/LaTeX-Workshop/raw/master/demo_media/hover-command.gif")

<!--
これらに関するファイルは以下のディレクトリに格納されている。気になれば中身を確認してみても良いだろう。

```
~\.vscode\extensions\james-yu.latex-workshop-<version>\date
```

中身を見てもいじらないように。
-->

※ パッケージ名と CTAN での登録名が異なる場合、*texdoc* によるパッケージドキュメントの表示が不可能な場合やオートコンプリートは効かない場合がある。（例: mathrsfs）
これは texdoc そのものの問題であり LaTeX Workshop 側の問題ではない。場合によっては CTAN をインターネット検索して探す方が早い。

### ■ 数式

数式環境の `\begin{` にマウスポインタを合わせるとホバーで数式をレンダリングして表示することが出来る。MathJax を使ってその都度レンダリングしている。

おそらく一番多くの人がありがたく感じる機能の 1 つ。

![preview equations](https://github.com/James-Yu/LaTeX-Workshop/raw/master/demo_media/hover.gif "https://github.com/James-Yu/LaTeX-Workshop/raw/master/demo_media/hover.gif")

ホバーウィンドウでサポートされている数式環境は次のもの。

| `\[`, `$`, `$$`, array, subarray, eqnarray(\*), equation(\*), align(\*), alignat(\*), gather(\*), multline(\*), cases, split, aligned, alignedat, gathered, matrix, smallmatrix, bmatrix, Bmatrix, pmatrix, vmatrix, Vmatrix |
| :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

ホバープレビューの最大行数は 20 行となっている。(`"~.hover.preview.maxLines": 20`) あまり行数を多くするとレンダリングが重くなる可能性があるため、このままで問題ないだろう。

<!-- このホバーには `\newcommand` で定義されているコマンドもプレビューすることが出来る。ただし、複雑な定義は読み取れないようだ。（例: xparse パッケージを利用して作成されている physics パッケージから提供されているコマンドをホバーで見ることは出来ない。） -->

この他、MathJax のバージョン更新に伴っていくつかのパッケージを取り込むことが出来るようになった。以下の記事に詳しいため参照してほしい。

> [LaTeX Workshop の数式プレビューを使いこなす - Qiita](https://qiita.com/Yarakashi_Kikohshi/items/4570bba51787e47a03c6)

#### ▼ ホバーサイズの変更

```json
  "latex-workshop.hover.preview.scale": 1
```

ホバーサイズの変更ができる。

ホバープレビューのデフォルトサイズは `1` となっている。小さく感じる場合はもう少し大きくしてもいいかも知れない。

#### ▼ カーソルのレンダリング

数学プレビューではデフォルトでカーソルもレンダリングされる。このときのカーソルの記号と色を構成することが出来る。

|                     設定                      |   構成 <br>（デフォルト）   | 説明                   |
| :-------------------------------------------: | :------------------------: | :--------------------- |
| `latex-workshop.hover.preview.cursor.enabled` |   boolean <br> (`true`)    | カーソルを表示させるか |
| `latex-workshop.hover.preview.cursor.symbol`  | string <br> (`"\\!\|\\!"`) | カーソルの形状         |
|  `latex-workshop.hover.preview.cursor.color`  |   string <br> (`"auto"`)   | カーソルの色           |

<!--
```json
  "latex-workshop.hover.preview.cursor.enabled": true,
  "latex-workshop.hover.preview.cursor.symbol": "\\!|\\!",
  "latex-workshop.hover.preview.cursor.color": "auto",
```
-->

<!-- 公式 Wiki では `\ddagger` がカーソルとして表示されるはずだが、どうしてかバーティカルバーが表示されていた。`\ddagger` にしたい場合には `"~.cursor.symbol": "\\ddagger"` とすれば良い。 -->

カーソルの色は 19 色と `"auto"`（デフォルト）が使用できる。

| `"black"`, `"darkgray"`, `"gray"`, `"lightgray"`, `"white"`, `"brown"`, `"magenta"`, `"red"`, `"pink"`, `"orange"`, `"yellow"`, `"green"`, `"olive"`, `"lime"`, `"blue"`, `"cyan"`, `"teal"`, `"purple"`, `"violet"`, |
| :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

ただし、数学記号の間であればカーソルがレンダリングされるが、`\alpha` などの途中でカーソル置いてもレンダリングされない。

#### ▼ 数学プレビューパネル

ホバーウィンドウで数式を確認しながら打ちたい場合には、Math Preview Panel から数式をリアルタイムプレビューしながら編集すると良いだろう。

キーボードショートカット `Ctrl+Alt+M` から開くことが出来る。

<!--
|        | コマンド                               |
| :----: | :------------------------------------- |
|  開く  | `latex-workshop.openMathPreviewPanel`  |
| 閉じる | `latex-workshop.closeMathPreviewPanel` |
-->

また、このプレビューパネルを表示する位置を変更することが出来る。

```json
  "latex-workshop.mathpreviewpanel.editorGroup": "<panel-position>"
```

|     `<panel-position>`     | Description            |
| :------------------------: | :--------------------- |
| `below` <br>（デフォルト） | エディタの下側         |
|          `above`           | エディタの上側         |
|          `right`           | エディタの右側         |
|           `left`           | エディタの左側         |
|         `current`          | 現在のエディタグループ |

### ■ 画像

```json
"latex-workshop.intellisense.includegraphics.preview.enabled": true
```

`\includegraphics` の際にファイル名を補完することが出来る。

また、`\includegraphics` の上にマウスポインタを置くと画像がプレビューされる。対応するファイル形式は、PNG、JPEG、PDF のようだ。ただし、PDF をプレビューするには SNIPPET VIEW を一度開ける必要がある。

![includegraphics](https://i.gyazo.com/0ed46851a4574cd609c31697b0c6cbd3.gif)

<!-- 場合によっては以下のようにインテリセンスを無効化しておいても良いだろう。 -->

<!--
```json
  "latex-workshop.intellisense.includegraphics.preview.enabled": true
  "latex-workshop.intellisense.includegraphics.preview.pdf.enabled": false
```
-->

<!--
```json
  "latex-workshop.intellisense.includegraphics.preview.enabled": true
```
-->

<!-- PDF 以外はプレビュー可能だが、PDF はプレビューしないようにしている。（おおよそ PDF で挿入している気がするので、このホバー機能はないも同然とも言えてしまうかもしれない。） -->

<!-- いずれにしても、ファイル名からどのような画像を挿入していたのかくらいは分かるようにしておくことを心掛けておきたい。 -->

### ■ 相互参照

`\ref` とすると `\label` から参照名を読みとって自動的に補完してくれる。

ラベル名が少し間違っているために相互参照が上手くいかないという現象をほとんどなくしてくれるであろう、地味ながらかなりありがたい機能。

![reference intellisense](https://github.com/James-Yu/LaTeX-Workshop/raw/master/demo_media/ref.gif "https://github.com/James-Yu/LaTeX-Workshop/raw/master/demo_media/ref.gif")

![reference intellisense png](https://github.com/James-Yu/LaTeX-Workshop/blob/master/demo_media/figure%20intelisense.png?raw=true "https://github.com/James-Yu/LaTeX-Workshop/blob/master/demo_media/figure%20intelisense.png")

また、`\ref` に関連するコマンドの上にマウスポインタを置くと数式・図表のプレビュー (`"~.hover.ref.enabled"`) と参照番号 (`"~.hover.ref.number.enabled"`)、**View on PDF** が表示される。この “View on PDF” をクリックすると対応する PDF [^pdfviewer] 上の数式・図表に飛ぶことが出来る。（下の Gif では小さくて確認しづらいかもしれない）

[^pdfviewer]: `"latex-workshop.view.pdf.ref.viewer": "auto"` によって自動的にビューワを選択してくれる。

書いた後からどのラベルを参照しているのか確認するのに非常に楽になる。

![preview reference](https://github.com/James-Yu/LaTeX-Workshop/raw/master/demo_media/hover-ref.gif "https://github.com/James-Yu/LaTeX-Workshop/raw/master/demo_media/hover-ref.gif")

この相互参照による機能は amsmath から提供されている `\eqref` や `\newcommand` で定義し直した参照コマンドに対しても有効になるようだ。

また、`\cite` に対してもホバーウィンドウからプレビューを見ることが出来る。

<!-- BibTeX に対しても同様に相互参照ホバーが機能する。~~別記事にしたい。~~ -->

![preview citation details](https://github.com/James-Yu/LaTeX-Workshop/raw/master/demo_media/hover-cite.gif "https://github.com/James-Yu/LaTeX-Workshop/raw/master/demo_media/hover-cite.gif")

<!-- # Information & Error message -->

タイプセットした際の実行状況やエラー等のメッセージを見ることが出来る。使っていればなんとなく分かるようになるが、一応確認しておきたい。

<!--
\#\# ■ LaTeX Compilation Live Info

コマンドパレットから**LaTeX-workshop: Show LaTeX Compilation Info**とすることで見ることが出来る。
コマンド `latex-workshop.showCompilationPanel` からでも開くことが出来る。場合によってはショートカットを作成しておいても良いかもしれない。

これを見て何が面白いのかまだ分かっていないが、タイプセットの様子を見ることが出来る。

> *Example*
>
> <img src = "https://user-images.githubusercontent.com/1909532/79014150-87c50b00-7b27-11ea-8717-4d7b823d172b.png" width = "30%" alt = "Example of LaTeX Compilation Live Info" ></img>
> > *cf*. [Latex Compilation Live Info rules out of order - Issue #2030 | James-Yu/LaTeX-Workshop - GitHub](https://github.com/James-Yu/LaTeX-Workshop/issues/2030)
-->

## ○ Error message

LaTeX のメッセージは以下のような場所から表示される。

| 設定                           | メッセージ内容 |    表示場所    |
| :----------------------------- | :------------: | :------------: |
| `~.message.error.show`         |     エラー     |  ポップアップ  |
| `~.message.warning.show`       |      警告      |  ポップアップ  |
| `~.message.information.show` ※ |  information   |  ポップアップ  |
| `~.message.badbox.show`        | badbox エラー  | PROBLEM パネル |
| `~.message.log.show`           |  デバッグログ  | OUTPUT パネル  |

※ `false` となっている。

ポップアップはウィンドウ右下の :bell: から表示される。PROBLEM パネルは `Ctrl+Shift+M` から、OUTPUT パネルは `Ctrl+Shift+U` から開くことが出来る。

<!-- LaTeX のタイプセットに引数で `-file-line-error` が含まれている場合には、Problem パネルから問題の箇所にジャンプすることが可能。 -->

PROBLEM パネルに表示されているエラーや警告の数は、ウィンドウ左下ステータスバーの :x: や :warning: に表されている。
もしもポップアップによる表示が邪魔に感じる場合は、上の設定を無効にしてステータスバーを確認するようにしても良いだろう。ただし、`~.message.badbox.show` や `~.message.log.show` に関しては表示させておくと良いだろう。

より詳細には以下の記事を参照してほしい。

> [エラーと警告を読むゾ - Qiita](https://qiita.com/Yarakashi_Kikohshi/items/4ede21b06d094ad3b89e)

# 参考

- 公式 Wiki
    - [Hover \- James-Yu/LaTeX-Workshop Wiki - GitHub](https://github.com/James-Yu/LaTeX-Workshop/wiki/Hover)
    - [Intellisense \- James-Yu/LaTeX-Workshop Wiki - GitHub](https://github.com/James-Yu/LaTeX-Workshop/wiki/Intellisense)
    - [Compile # Settings Details \- James\-Yu/LaTeX\-Workshop Wiki](https://github.com/James-Yu/LaTeX-Workshop/wiki/Compile#settings-details)

## 関連記事

LaTeX Workshop に関する記事は以下の 5 つがあります。本記事と合わせてご覧ください。

1. **[LaTeX Workshop を使いこなす \- Qiita](https://qiita.com/Yarakashi_Kikohshi/items/a9357dd469320ffb65a0)**

    > LaTeX Workshop を使って TeX ファイルをタイプセットして PDF を作成するまでを紹介します。

2. **[LaTeX Workshop をもう少し使いこなす \- Qiita](https://qiita.com/Yarakashi_Kikohshi/items/1a275f2046b002e398b3)**

    > LaTeX Workshop で利用できるスニペットやコマンドを紹介します。また、他のカスタマイズを考えます。

3. **[LaTeX Workshop をもっと使いこなす \- Qiita](https://qiita.com/Yarakashi_Kikohshi/items/1f2225c7e28aad498998)**  ← 本記事 :slime:

    > LaTeX Workshop の便利な特徴を紹介します。ホバーによる数式や相互参照の確認、インテリセンスによる補完機能などがあります。

4. **[Zotero と LaTeX Workshop で bib ファイルを扱いこなす \- Qiita](https://qiita.com/Yarakashi_Kikohshi/items/8f720643543ba175f7cc)**

    > Zotero から bib ファイルを出力して LaTeX Workshop でフォーマットするする方法を紹介します。

5. **[LaTeX Workshop の数式プレビューを使いこなす - Qiita](https://qiita.com/Yarakashi_Kikohshi/items/4570bba51787e47a03c6)**

    > 数式プレビューをもっと使えるようにカスタマイズします。

# 余談

スニペット以外にもかなりサポートされていて LaTeX 初心者でも間違いを少なく作成することが出来るようになるのではないかと思う。しかし、使っていても知らない機能があると宝の持ち腐れになってしまうこともある。この記事から拡張機能をより利用できるようになることを願う。

# 追記

- 2021/06/20: いくつかの項目で公式 Wiki から Gif 画像を引用。
- 2021/07/23: 関連記事リンクを追加。
- 2022/07/29: Ver.8.28.0 に対応。軽微修正。