This post will be part of a collection of notes about the way I currently deal with LaTeX documents. It is not a “for dummies” guide: some tools and extensions need a bit of configuration, and the user should already be familiar with LaTeX and some of its inner workings. I do feel that this setup allows an experienced user to become more productive in the long term, especially when dealing with a large document or with multiple documents at the same time.

Rationale

I started my LaTeX journey (more than ten years ago!) with TeXmaker, and I still think that IDEs are the way to go for novice users. However, the tailored environment provided by these editors becomes less useful as the user gets more confident with LaTeX. Moreover, IDE fatigue is a very real threat for people that use multiple editors on a daily basis. Shockingly, I found no actual definition of this phenomenon on the ’net, so I will provide my own: IDE fatigue is the mental overhead associated with regularly switching between multiple, advanced text editors. To avoid this, one should ideally use a single editor for most of their work, and switch to other IDEs only when it is absolutely necessary. In the past I tried to use Sublime Text to achieve this goal, but more recently I switched over to Visual Studio Code and I am pretty pleased with the change.

Visual Studio Code + select extensions

I am essentially writing this post because using the LaTeX-Workshop extension (LW, from now on) for VS Code left me thoroughly impressed. LW is very well-integrated with both the VS Code interface and LaTeX tooling. For instance, it supports latexmk out of the box, with sensible default settings. While the average (10-20-page-long) paper or the occasional Beamer slide deck builds just fine with the good old pdflatex + bibtex + pdflatex x2, building a hundred-page thesis will be noticeably faster with latexmk. Furthermore, LW integrates chktex messages in the VS Code “Problems” pane. For the uninitiated, chktex is a program that “reports typographic and other errors in LaTeX documents”.

Sure, sometimes its warnings may be overzealous or just plain wrong; however, after toying a bit with the settings, I found most warnings to be sensible and helpful. They may even teach you something new: for instance, did you know that you should use “intersentence spacing” when a sentence ends with a capital letter? I did’t!

There are at least two other extensions that deserve to be mentioned here.

• Todo Tree searches your workspace for tagged comments (TODO, FIXME and the like) and displays these comments in a VS Code pane. It supports a limited set of comment tokens (//, /*, #, <!--, ;) out of the box. No love for LaTeX! But one can simply change the default regular expression, i.e.

  "((//|#|<!--|;|/\\*)\\s*($TAGS)|^\\s*- \\[ \\])"

  to the following:

  ((//|\\|#|<!--|;|/\*|^|%)\s*($TAGS)|^\s*- \[ \])

  This will support not only % TODO comments, but also semantic annotations such as those offered by the todonotes package, i.e., \todo{...}. By the way, I found todonotes to be absolutely vital when working on my thesis.

• Spell Right is a spellcheck extension that ignores LaTeX commands and integrates with the “Problems” pane. Here, the ability of VS Code to customize settings on a per-workspace basis really makes it great. Let’s say that your latest paper is written in American English, while your thesis is in British English. After configuring Spell Right with the right dictionary for each workspace, you will never have to worry about adjusting its behavior (behaviour?) again. You can also make it ignore specific terms on a per-workspace basis.

Some Perl woes

LW uses another script, latexindent, to adjust the indentation of your LaTeX sources. Unfortunately, on my machine it failed with some errors about missing Perl libraries. In the end I solved the issue by following these steps:

#install perl and its package manager, cpan
brew install perl 
# install latexindent requirements
cpan Log::Log4perl
cpan Log::Dispatch::File
cpan YAML::Tiny
cpan File::HomeDir

Previewing the PDF

When it comes to PDF previews, any decent LaTeX environment should support the following features:

• The PDF viewer should automatically update the view when the PDF changes;
• The user should be able to select a position from the editor and have the viewer jump to the corresponding position in the PDF, and vice versa.

LW satisfies these requirements out-of-the-box, but by default it relies on PDF.js to display the PDF. I cannot say that I am a fan of this soluiton: the rendering is slow and a native PDF viewer is surely nicer to look at.

Personally, I prefer to use Skim on macOS. On Windows, I would recommend SumatraPDF. Here are the relevant LW settings to integrate Skim:

{
"latex-workshop.view.pdf.external.synctex.args": [
  "-r",
  "%LINE%",
  "%PDF%",
  "%TEX%"
],
"latex-workshop.view.pdf.external.synctex.command": "/Applications/Skim.app/Contents/SharedSupport/displayline",
"latex-workshop.view.pdf.external.viewer.args": [
  "-a",
  "Skim",
  "\"%PDF%\""
],
"latex-workshop.view.pdf.external.viewer.command": "open",
"latex-workshop.view.pdf.viewer": "external"
}

One also needs to configure Skim so that Shift-Cmd-clicking on a point of the PDF makes VS Code jump to the corresponding line in the LaTeX sources. This is done in the Sync pane of the Skim preferences dialog. Although Skim does feature a “Visual Studio Code” option, I found it to be a bit unreliable (e.g., it does not work well if the path contains any special characters). The following settings work best for me:

• Preset: Custom
• Command: code
• Arguments: -g "%file:%line"

Other LaTeX tools

textidote performs a host of additional checks, courtesy of the Language Tool library. It performs grammar- and style checks in addition to simple spell check. (I actually disable the spell-checker altogether, since I already rely on Spell Right for that.) For instance,you will get a warning if you end a \section{} title with a period. And it also works on Markdown documents! For instance, I purposefully wrote “work” instead of “works” in the previous sentences, then ran textidote on this file. Look what I got:

* L81C13-L81C17 Did you mean 'works'?. Suggestions:
  [works] (3395) [lt:en:IT_VBZ]
  And it also work on Markdown documents!
              ^^^^^

It is still a bit rough around the edges, and you might want to ignore a lot of the warnings it reports, but overall is a pretty useful addition to the toolbox.

checkcites finds unused citations, i.e., entries in your bibTeX file that you never use in your document. It supports both bibtex and biber, and can be useful when you want to trim down a huge .bib file without accidentally removing something you needed.

Conclusion

This was just a couple of notes about my current LaTeX setup, including some non-obvious configurations and fixes. In short: I edit my source files with VS Code and the Latex-Workshop extension, I use Skim to preview the document, and I can jump back and forth between them with ease. Todo Trees keeps track of the next things I have to do; Spell Right finds misspelt words. Every once in a while I perform additional checks with textidote and checkcites.

I believe this setup to be reasonably stable and effective. I hope you can find this post useful!

Edit (2020-06-09): I fixed the headings to follow the convention of my other posts.