VSCode で LaTeX を書く (2018)

時期的に卒論や修論の執筆の最盛期だと思われるので、今現在の最新の状況を踏まえた
論文執筆の環境構築について書いていきます。

LaTeX を書く環境は

などの GUI ベースな統合環境もあれば、Vim や Emacs, Sublime Text, VSCode 等のテキストエディタで拡張機能を利用するものもあります。

今回は、比較的馴染みやすく、拡張機能や設定を細かくカスタマイズすることができるなどの理由で VSCode を選んでいます。

少し前までは、LaTeXTools という Sublime Text の拡張機能がすごく優秀だったため、Sublime Text を利用していましたが、最近では、VSCode 用の拡張機能である LaTeX Workshop が多機能になり LaTeXTools に肉薄していることや、日本語記述環境として Sublime Text より VSCode のほうが優秀であるなどの理由もあります。

また、この記事は VSCode や Sublime Text のようなエディタを一度も使ったことがない、あるいは使うのに慣れていない人向けに書いたので、冗長な書き方になっていると思います。

前提条件

TeX の環境構築が終わっていること
- コマンドプロンプトやターミナル上で次のコマンドが使えること

bash

  $ latex
  $ uplatex
  $ xelatex
  $ latexmk

powershell

  PS> latex
  PS> uplatex
  PS> xelatex
  PS> latexmk

LaTeX 側での作業

ビルド環境の構築

LaTeX の環境構築で一番躓くところは ビルド環境の構築 だと思います。LaTeX ソースが PDF にビルドできてしまえば、ほとんど終わりです。

今回は LaTeX Workshop のデフォルトとして使われている latexmk を LaTeX のビルドに使用します。

シンプルな LaTeX 文章であればビルドは1回でいいのですが、参考文献や図表参照などを利用した場合は複数回のビルドや、参考文献ファイルのビルドなどが必要になり面倒です。

latexmk はそれらの面倒な手続きを自動で行ってくれる素晴らしいツールです。

`.latexmkrc` ファイルの作成

latexmk はビルドの設定用のファイル .latexmkrc を利用してビルドを行うので、このファイルを作成します。

以下の内容をコピーして、現在のユーザーのホームディレクトリに .latexmkrc として保存してください。

なお、Windows の場合はファイル名がピリオド (.) で始まるファイルを作成する場合は、
[ファイル名].とする必要があるため、.latexmkrc.というファイル名でファイルを保存するようにしてください。

追記 (2019/06/02)
コメント欄での指摘に基づき、Windows 環境における LuaLaTeX のビルドコマンドを修正しました。

@skytomo221 さん、ありがとうございました。

.latexmkrc

#!/usr/bin/env perl

# OS によって実行ファイル名が異なるので、OSを判断する
# Windows の場合
if ($^O eq 'MSWin32') {
  # 通常の LaTeX ドキュメントのビルドコマンド
  $latex                         = 'uplatex %O -kanji=utf8 -no-guess-input-enc -synctex=1 -interaction=nonstopmode %S';
  # pdfLaTeX のビルドコマンド
  $pdflatex                      = 'pdflatex %O -synctex=1 -interaction=nonstopmode %S';
  # LuaLaTeX のビルドコマンド
  # 追記(2019/06/02): @skytomo221 さんの指摘に基づき修正
  $lualatex                      = 'lualatex %O -synctex=1 -interaction=nonstopmode %S';
  # XeLaTeX のビルドコマンド
  $xelatex                       = 'xelatex %O -no-pdf -synctex=1 -shell-escape -interaction=nonstopmode %S';
  # Biber, BibTeX のビルドコマンド
  $biber                         = 'biber %O --bblencoding=utf8 -u -U --output_safechars %B';
  $bibtex                        = 'upbibtex %O %B';
  # makeindex のビルドコマンド
  $makeindex                     = 'upmendex %O -o %D %S';
  # dvipdf のビルドコマンド
  $dvipdf                        = 'dvipdfmx %O -o %D %S';
  # dvipd のビルドコマンド
  $dvips                         = 'dvips %O -z -f %S | convbkmk -u > %D';
  $ps2pdf                        = 'ps2pdf.exe %O %S %D';
  # PDF の作成方法を指定するオプション
  # $pdf_mode = 0; PDF を作成しません。
  # $pdf_mode = 1; $pdflatex を利用して PDF を作成します。
  # $pdf_mode = 2; $ps2pdf を利用して .ps ファイルから PDF を作成します。
  # $pdf_mode = 3; $dvipdf を利用して .dvi ファイルから PDF を作成します。
  # $pdf_mode = 4; $lualatex を利用して .dvi ファイルから PDF を作成します。
  # $pdf_mode = 5; xdvipdfmx を利用して .xdv ファイルから PDF を作成します。
  $pdf_mode                      = 3;
  # PDF ビュアーの設定 for Windows
  # Windows では SyncTeX が利用できる SumatraPDF が推奨されている。
  # SumatraPDF: https://www.sumatrapdfreader.org/free-pdf-reader.html
  if (-f 'C:/Program Files/SumatraPDF/SumatraPDF.exe') {
    $pdf_previewer               = '"C:/Program Files/SumatraPDF/SumatraPDF.exe" -reuse-instance';
  } elsif (-f 'C:/Program Files (x86)/SumatraPDF/SumatraPDF.exe') {
    $pdf_previewer               = '"C:/Program Files (x86)/SumatraPDF/SumatraPDF.exe" -reuse-instance';
  } else {
    # SumatraPDF が存在しない場合は、TeXworks で開くように設定されている。
    # 別のアプリケーション(Adobe Reader 等)で開きたい場合はここに実行ファイルのパスを設定する
    $pdf_previewer               = 'texworks';
  }
# Windows 以外の OS の場合 (Linux, macOS)
} else {
  $latex                         = 'uplatex %O -synctex=1 -interaction=nonstopmode %S';
  $pdflatex                      = 'pdflatex %O -synctex=1 -interaction=nonstopmode %S';
  $lualatex                      = 'lualatex %O -synctex=1 -interaction=nonstopmode %S';
  $xelatex                       = 'xelatex %O -no-pdf -synctex=1 -shell-escape -interaction=nonstopmode %S';
  $biber                         = 'biber %O --bblencoding=utf8 -u -U --output_safechars %B';
  $bibtex                        = 'upbibtex %O %B';
  $makeindex                     = 'upmendex %O -o %D %S';
  $dvipdf                        = 'dvipdfmx %O -o %D %S';
  $dvips                         = 'dvips %O -z -f %S | convbkmk -u > %D';
  $ps2pdf                        = 'ps2pdf %O %S %D';
  $pdf_mode                      = 3;
  # macOS の場合のみの設定
  if ($^O eq 'darwin') {
    # 一時ファイルの作成を抑止するオプション(0: 抑止)
    # Skim 等の変更検知機構のあるビュアーで変更箇所を検知できるようにするため
    $pvc_view_file_via_temporary = 0;
    # PDF ビュアーの設定 for macOS
    # macOS では SyncTeX が利用できる Skim が推奨されている。
    $pdf_previewer               = 'open -ga /Applications/Skim.app';
  } else {
    # PDF ビュアーの設定 for Linux
    # Linux ではディストリビューションによってインストールされているアプリケーションが
    # 異なるため、ディストリビューションに依存しない xdg-open で開くようにする
    $pdf_previewer               = 'xdg-open';
  }
}

VSCode 側での作業

VSCode のインストール

VSCode がまだ入ってない方はインストールしましょう。
- Visual Studio Code - Code Editing. Redefined

基本的には、ページ上部の Download for と書いてあるリンクからダウンロードしたものをインストールすれば問題ないと思います。

日本語化

VSCode が起動したら、左のサイドバーのから 拡張機能 のアイコン (下の画像を参考) をクリック

検索バーに japanese language pack と検索して、一番上位のもの (下の画像を参考) を選択 → インストールしましょう

インストールが終わると、VSCode を再起動するよう指示があると思いますので再起動します。もし出なかった場合は手動で VSCode を終了してください。

再起動後、メニューバーや各部が日本語化されていると思います。

LaTeX Workshop のインストール

上記の日本語化と同じ手順で LaTeX Workshop をインストールしてみましょう (下の画像を参考)

通常、VSCode の拡張機能をインストールする場合は、インストール後に再起動は必要ありませんが、再読み込み は必要になることが多いです。LaTeX Workshop のインストールが終わったら、再読み込みを押しましょう。

これで LaTeX Workshop のインストールは完了です。

LaTeX Workshop の設定

VSCode のメニューバーから [表示] → [コマンドパレット] を選択して、コマンドパレットを出してください。

コマンドパレットに Settings (JSON) と入力し、 基本設定: 設定 (JSON) を開く を選択してください (下の画像を参考)。

表示された右側の「ユーザー設定」のエディタに次の内容をコピペしてください

settings.json

{
    // editor.wordSeparators: 単語単位での移動を行う場合の区切り文字を指定
    // 日本語文書で単語移動を使うため、助詞や読点、括弧を区切り文字として指定する
    "editor.wordSeparators": "./\\()\"'-:,.;<>~!@#$%^&*|+=[]{}`~?　、。「」【】『』（）！？てにをはがのともへでや",

    // 設定: LaTeX Workshop

    // LaTeX Workshop ではビルド設定を「Tool」と「Recipe」という2つで考える
    //   Tool: 実行される1つのコマンド。コマンド (command) と引数 (args) で構成される
    //   Recipe: Tool の組み合わわせを定義する。Tool の組み合わせ (tools) で構成される。
    //           tools の中で利用される Tool は "latex-workshop.latex.tools" で定義されている必要がある。


    // latex-workshop.latex.tools: Tool の定義
    "latex-workshop.latex.tools": [
        // latexmk を利用した xelatex によるビルドコマンド
        {
          "name": "Latexmk (XeLaTeX)",
          "command": "latexmk",
          "args": [
            "-f", "-gg", "-pv", "-xelatex", "-synctex=1", "-interaction=nonstopmode", "-file-line-error", "%DOC%"
          ]
        },
        // latexmk を利用した uplatex によるビルドコマンド
        {
          "name": "Latexmk (upLaTeX)",
          "command": "latexmk",
          "args": [
            "-f", "-gg", "-pv", "-synctex=1", "-interaction=nonstopmode", "-file-line-error", "%DOC%"
          ]
        },
        // latexmk を利用した platex によるビルドコマンド
        // 古い LaTeX のテンプレートを使いまわしている (ドキュメントクラスが jreport や jsreport ) 場合のため
        {
          "name": "Latexmk (pLaTeX)",
          "command": "latexmk",
          "args": [
            "-f", "-gg", "-pv", "-latex='platex'", "-latexoption='-kanji=utf8 -no-guess-input-env'", "-synctex=1", "-interaction=nonstopmode", "-file-line-error", "%DOC%"
          ]
        },
        // latexmk を利用した lualatex によるビルドコマンド
        {
          "name": "Latexmk (LuaLaTeX)",
          "command": "latexmk",
          "args": [
            "-f", "-gg", "-pv", "-lualatex", "-synctex=1", "-interaction=nonstopmode", "-file-line-error", "%DOC%"
          ]
        }
    ],

    // latex-workshop.latex.recipes: Recipe の定義
    "latex-workshop.latex.recipes": [
        // XeLaTeX で書かれた文書のビルドレシピ
        {
          "name": "XeLaTeX",
          "tools": [
            "Latexmk (XeLaTeX)"
          ]
        },
        // LaTeX(upLaTeX) で書かれた文書のビルドレシピ
        {
          "name": "upLaTeX",
          "tools": [
            "Latexmk (upLaTeX)"
          ]
        },
        // LaTeX(pLaTeX) で書かれた文書のビルドレシピ
        {
          "name": "pLaTeX",
          "tools": [
            "Latexmk (pLaTeX)"
          ]
        },
        // LuaLaTeX で書かれた文書のビルドレシピ
        {
          "name": "LuaLaTeX",
          "tools": [
            "Latexmk (LuaLaTeX)"
          ]
        }
    ],

    // latex-workshop.latex.magic.args: マジックコメント付きの LaTeX ドキュメントをビルドする設定
    // '%!TEX' で始まる行はマジックコメントと呼ばれ、LaTeX のビルド時にビルドプログラムに解釈され、
    // プログラムの挙動を制御する事ができる。
    // 参考リンク: https://blog.miz-ar.info/2016/11/magic-comments-in-tex/
    "latex-workshop.latex.magic.args": [
      "-f", "-gg", "-pv", "-synctex=1", "-interaction=nonstopmode", "-file-line-error", "%DOC%"
    ],

    // latex-workshop.latex.clean.fileTypes: クリーンアップ時に削除されるファイルの拡張子
    // LaTeX 文書はビルド時に一時ファイルとしていくつかのファイルを生成するが、最終的に必要となるのは
    // PDF ファイルのみである場合などが多い。また、LaTeX のビルド時に失敗した場合、失敗時に生成された
    // 一時ファイルの影響で、修正後のビルドに失敗してしまう事がよくある。そのため、一時的なファイルを
    // 削除する機能 (クリーンアップ) が LaTeX Workshop には備わっている。
    "latex-workshop.latex.clean.fileTypes": [
        "*.aux", "*.bbl", "*.blg", "*.idx", "*.ind", "*.lof", "*.lot", "*.out", "*.toc", "*.acn", "*.acr", "*.alg", "*.glg", "*.glo", "*.gls", "*.ist", "*.fls", "*.log", "*.fdb_latexmk", "*.synctex.gz",
        // for Beamer files
        "_minted*", "*.nav", "*.snm", "*.vrb",
    ],

    // latex-workshop.view.pdf.viewer: PDF ビューアの開き方
    // VSCode 自体には PDF ファイルを閲覧する機能が備わっていないが、
    // LaTeX Workshop にはその機能が備わっている。
    // "tab" オプションを指定すると、今開いているエディタを左右に分割し、右側に生成されたPDFを表示するようにしてくれる
    // この PDF ビュアーは LaTeX のビルドによって更新されると同期して内容を更新してくれる。
    "latex-workshop.view.pdf.viewer": "tab",

    // latex-workshop.latex.autoClean.run: ビルド失敗時に一時ファイルのクリーンアップを行うかどうか
    // 上記説明にもあったように、ビルド失敗時に生成された一時ファイルが悪影響を及ぼす事があるため、自動で
    // クリーンアップがかかるようにしておく。
    "latex-workshop.latex.autoClean.run": "onFailed",

    // latex-workshop.latex.autoBuild.run: .tex ファイルの保存時に自動的にビルドを行うかどうか
    // LaTeX ファイルは .tex ファイルを変更後にビルドしないと、PDF ファイル上に変更結果が反映されないため、
    // .tex ファイルの保存と同時に自動的にビルドを実行する設定があるが、文書が大きくなるに連れてビルドにも
    // 時間がかかってしまい、ビルドプログラムの負荷がエディタに影響するため、無効化しておく。
    "latex-workshop.latex.autoBuild.run": "never",
}

ビルドしてみる

LaTeX は様々なエンジン (pLaTex, upLaTeX, XeLaTeX, LuaLaTeX) や、それら専用に合わせたドキュメントクラスで書かれることが
あるため、それぞれの環境で正しくビルドできるか、いくつかの文書でビルドテストを行ってみます。

VSCode 上で LaTeX 文書をビルドを実行する方法はいくつかあります。

一つは先程利用したコマンドパレットを利用する方法です。コマンドパレットを表示し、latex buildと入力し、LaTeX Workshop: Build with recipe を選択してください (下の画像を参考)。

次に、今開いている LaTeX ファイルに合わせたビルドレシピを選択してください (下の画像を参考)。

もう一つは、サイドバーから実行する方法です。LaTeX Workshop がインストールされていると、.tex ファイルを開いているときに左に TeX のアイコンが表示されるはずです (下の画像を参考)。

表示されたサイドバーの [COMMANDS] → [Build LaTeX project] の下に [Recipe: ... ] という項目がいくつか表示されていると思います (下の画像を参考)。該当するレシピを選択することで、ビルドをすることができます。

また、同じ画面にある [View LaTeX PDF] を選択することで、出力された PDF ファイルを閲覧することができます。

pLaTeX

Test_pLaTeX.tex

%!TEX encoding = UTF-8
% ビルドレシピは「pLaTeX」を選択する
\documentclass{jsreport}

\begin{document}
  \chapter{はじめに}
    \section{概要}
      これは \LaTeX が Visual Studio Code でビルドできるかどうかのテスト文章である。
  \chapter{おわりに}
    これが表示されていれば成功である。
\end{document}

upLaTeX

Test_upLaTeX.tex

%!TEX encoding = UTF-8
% ビルドレシピは「upLaTeX」を選択する
\documentclass{ujreport}

\begin{document}
  \chapter{はじめに}
    \section{概要}
      これは \LaTeX が Visual Studio Code でビルドできるかどうかのテスト文章である。
  \chapter{おわりに}
    これが表示されていれば成功である。
\end{document}

LuaLaTeX

Test_LuaLaTeX.tex

%!TEX encoding = UTF-8
% ビルドレシピは「LuaLaTeX」を選択する
\documentclass[lualatex,ja=standard]{bxjsreport}

\begin{document}
  \chapter{はじめに}
    \section{概要}
      これは \LaTeX が Visual Studio Code でビルドできるかどうかのテスト文章である。
  \chapter{おわりに}
    これが表示されていれば成功である。
\end{document}

XeLaTeX

Test_XeLaTeX.tex

%!TEX encoding = UTF-8
% ビルドレシピは「XeLaTeX」を選択する
\documentclass[xelatex,ja=standard]{bxjsreport}

\begin{document}
  \chapter{はじめに}
    \section{概要}
      これは \LaTeX が Visual Studio Code でビルドできるかどうかのテスト文章である。
  \chapter{おわりに}
    これが表示されていれば成功である。
\end{document}

VSCode で LaTeX を書く (2018)

VSCode で LaTeX を書く (2018)

前提条件

LaTeX 側での作業

ビルド環境の構築

.latexmkrc ファイルの作成

VSCode 側での作業

VSCode のインストール

日本語化

LaTeX Workshop のインストール

LaTeX Workshop の設定

ビルドしてみる

pLaTeX

upLaTeX

LuaLaTeX

XeLaTeX

`.latexmkrc` ファイルの作成