VS Code as LaTeX editor

Snippets

LaTeX workshop supports smart snippets with autocomplete.

Reproduced here for my offline reference are the most useful ones.

Build recipes

Building using something modern or fancy? The default build workflow is some pdflatex+BibTeX system that is ok but outdated. I would prefer a simpler more modern workflow that supports e.g. XeTeX. Out of the box, neither XeTeX or latexmk were available workflows for me. There are two ways to do set these up.

Firstly, the old school way that the developers of LaTeX workshop seem to dislike, but which was far and away the easiest for me: Use the Latex Workshop-style TeX magic This looks like, e.g.

% !TEX program = latexmk
% !TEX options = -synctex=1 -file-line-error -halt-on-error -xelatex -outdir="%OUTDIR%" "%DOC%"

I put that at the start of the master document and things behave as expected. Good. For this particular build tool, latexmk, to actually have any advantage, one would want to disable auto-clean (a.k.a. delete everything and rebuild from scratch all the time) so that latexmk can be smart about rebuilds. Looks like the following setting:

"latex-workshop.latex.autoBuild.cleanAndRetry.enabled": false,

The price one pays for this is needing to manually clean up the detritus from time to time. The developer-preferred way of configuring the build is difficult, verbose and error-prone but supposedly ineffably better. That kind of argument is one that I am curiously susceptible to, in the same way that I occasionally find myself buying biodynamic yoghurt even though biodynamic is definitely nonsense.

Anyway, in the biodynamic configuration method, we make new “recipes” in the configuration JSON. The result is 😴.

    "latex-workshop.latex.recipes": [
        {
            "name": "latexmk 🔃",
            "tools": [
                "latexmk"
            ]
        },
        {
            "name": "xelatexmk 🔃",
            "tools": [
                "xelatexmk"
            ]
        },
        {
            "name": "platexmk 🔃",
            "tools": [
                "platexmk"
            ]
        },
        {
            "name": "pdflatex ➞ bibtex ➞ pdflatex`×2",
            "tools": [
                "pdflatex",
                "bibtex",
                "pdflatex",
                "pdflatex"
            ]
        },
        {
            "name": "xelatex ➞ biber ➞ xelatex",
            "tools": [
                "xelatex",
                "biber",
                "xelatex"
            ]
        }
    ],
    "latex-workshop.latex.tools": [
        {
            "name": "latexmk",
            "command": "latexmk",
            "args": [
                "-synctex=1",
                "-file-line-error",
                "-outdir=%OUTDIR%",
                "%DOC%"
            ],
            "env": {}
        },
        {
            "name": "platexmk",
            "command": "latexmk",
            "args": [
                "-synctex=1",
                "-file-line-error",
                "-pdf",
                "-outdir=%OUTDIR%",
                "%DOC%"
            ],
            "env": {}
        },
        {
            "name": "xelatexmk",
            "command": "latexmk",
            "args": [
                "-synctex=1",
                "-file-line-error",
                "-xelatex",
                "-outdir=%OUTDIR%",
                "-interaction=nonstopmode",
                "-halt-on-error",
                "%DOC%"
            ],
            "env": {}
        },
        {
            "name": "pdflatex",
            "command": "pdflatex",
            "args": [
                "-synctex=1",
                "-interaction=nonstopmode",
                "-halt-on-error",
                "-file-line-error",
                "%DOC%"
            ],
            "env": {}
        },
        {
            "name": "xelatex",
            "command": "xelatex",
            "args": [
                "-synctex=1",
                "-interaction=nonstopmode",
                "-halt-on-error",
                "-file-line-error",
                "%DOC%"
            ],
            "env": {}
        },
        {
            "name": "bibtex",
            "command": "bibtex",
            "args": [
                "%DOCFILE%"
            ],
            "env": {}
        },
        {
            "name": "biber",
            "command": "biber",
            "args": [
                "%DOCFILE%"
            ],
            "env": {}
        }
    ]

To use the disruptive new tectonic build system, try this:

"latex-workshop.latex.tools": [
    {
        "name": "tectonic",
        "command": "tectonic",
        "args": [ "%DOC%"  ],
        "env": {}
    }
],
"latex-workshop.latex.recipes": [
    {
        "name": "tectonic",
        "tools": [
            "tectonic"
        ]
    }
]

Now you can use the tectonic system from LaTeX-workshop! That is, like, biodynamic and ketogenic at the same time, or something.

SyncTeX

SyncTeX makes discerning what I am typing somewhat easier, by connecting the cursor location in the source code to the viewing location in the PDF (and, on some systems, vice versa). The built-in implementation in Latex-workshop OK; we are somewhat hamstrung because everything is constrained to a single window by VS Code. (Although see VS Code’s dual window hack). External PDF viewers are not officially supported but more-or-less work for me, and are superior for a dual monitor setup, although definitely jankier.

Minuses of external PDF viewers

• Documentation is perfunctory.
• Sync works in AFAICT one direction only — I can sync from VS Code to the PDF viewer, but not the reverse.

Since they are unsupported, one needs to guess the config to make them go. A good example of reverse engineering the config for kubuntu’s PDF viewer okular is given by Heiko/@miteron.

{
    "latex-workshop.view.pdf.viewer": "external",
    // @sync host=work-pc
    "latex-workshop.view.pdf.external.viewer.command": "okular",
    // @sync host=work-pc
    "latex-workshop.view.pdf.external.viewer.args": [
            "--unique",
            "%PDF%"
    ],
    // @sync host=work-pc
    "latex-workshop.view.pdf.external.synctex.command": "okular",
    // @sync host=work-pc
    "latex-workshop.view.pdf.external.synctex.args": [
        "--unique",
        "%PDF%#src:%LINE%%TEX%"
    ],
}

For GNOME doc viewer evince things are more complicated. Specifically, I needed a bridging script and special config:

{
    // @sync host=home-pc
    "latex-workshop.view.pdf.external.viewer.command": "evince2",
    // @sync host=home-pc
    "latex-workshop.view.pdf.external.viewer.args": [
        "%PDF%"
    ],
    // @sync host=home-pc
    "latex-workshop.view.pdf.external.synctex.command": "evince_forward_search",
    // @sync host=home-pc
    "latex-workshop.view.pdf.external.synctex.args": [
        "%PDF%",
        "%LINE%",
        "%TEX%"
    ],
}

Gotchas

Gotcha: If there are weird “provider errors” in the vscode exthost log, the problem might be that latexindent must be installed, and possibly it was not for me because I installed a minimalist TeX distribution.

tlmgr install latexindent

If I want to switch TeX installations, I can do so by environment variables, so I whack the following in my settings.json:

  {
    "name": "latexmk",
    "command": "latexmk",
    "args": [
      "-synctex=1",
      "-interaction=nonstopmode",
      "-file-line-error",
      "-pdf",
      "-outdir=%OUTDIR%",
      "%DOC%"
    ],
    "env": {"TEXMFHOME": "c:/texlive/2019"}
  }