用于 Visual Studio Code 的 LaTeX Workshop

本文是译文，点击 此处查看原文。

0. 简介

LaTeX Workshop 是 Visual Studio Code 的一个扩展，旨在为使用 Visual Studio Code 进行 LaTeX 排版提供一体化的特性和工具。

如果没有社区的贡献，这个项目就不会成功，特别是现在和过去的主要贡献者：

• Jerome Lelong @jlelong
• Takashi Tamura @tamuratak
• Tecosaur @tecosaur
• James Booth @jabooth

注意，从 7.0.0 版本开始，LaTeX Workshop 至少需要 VS Code 1.34.0。

1. 特性

这不是一个完整的列表，而是一些最酷功能的预览。

• 建立 LaTeX (包括 BibTeX) 的 PDF 自动保存。
  
• 即时查看 PDF(在 VS Code 或浏览器中)。
  
• 直接和反向 SyncTeX。单击可在 .tex 源和 PDF 中的位置之间跳转，反之亦然。
  
• LaTeX 日志解析器，在 VS Code 中自动报告 LaTeX 构建中的错误和警告。
  
  • Linting
    
• 片段
  • 可以使用从 \ 开始的代码片段输入许多 LaTeX 命令，然后输入部分命令来缩小搜索范围。
    
  • 周围一些选定的文本与 LaTeX 命令使用 ctrl + l、ctrl + w。将弹出一个新菜单来选择该命令。这适用于多选择。使用 \ 的前一种方法已经被弃用。
    
  • 我们还提供了其他一些片段机制：
    • 希腊字母是 @ + letter。有些字母有变体，可用 @v + letter 表示。参见这里。
      
    • 常见的环境可以通过 BXY 来获得，其中 XY 是环境名称的前两个字母，例如。BEQ 给出了 equation 环境。如果您想要环境的星型版本，请使用 BSXX，例如。BSEQ 给出了 equation* 环境。参见这里。
    • 常见的字体命令可以由 FXY 获得，其中 XY 是字体命令名称的最后两个字母，例如。FIT 给出了 \textit{}.。参见这里。
      
    • 许多其他数学符号可以用 @ 前缀来表示。参见这里。
      
• 快捷键
  • 除了代码片段之外，扩展还提供了一些快捷键，允许您轻松地格式化文本(以及一两个其他内容)。
    
• 当当前行以 \item 或 \item[] 开始时，按回车键将自动添加以相同方式开始的新行。为了更好地处理最后一项，在只包含 \item 或 \item[] 的行上按回车键实际上会删除该行的内容。alt+Enter 被绑定到标准的换行命令。可以通过设置 latex-workshop.bind.enter.key 为 false 来禁用 \item 的自动插入。
  
• 悬停预览。将鼠标悬停在一个数学环境的开始标记上，会弹出 mathjax 预览。
  

2. 安装和基本设置

2.1 需求

• LaTeX 在系统 PATH 上分发。例如，TeX Live。
• 请注意，MikTeX 不与 SyncTeX 一起提供。请使用内置的 synctex 功能。
• 构建 LaTeX 项目的默认配方需要 latexmk。或者，你可以设置自己的 LaTeX 配方。
• 可选：安装 ChkTeX 到 lint LaTeX 工程。
• 可选：如果您的 LaTeX 发行版没有提供对格式化的支持，那么可以安装 latexindent.pl。

2.2 安装

安装 LaTeX Workshop 简单。您可以在 Visual Studio Code Marketplace 中找到它，或者在 VS Code Quick Open(ctrl/cmd + P) 中运行 ext install latex-workshop。

2.3 设置 PATH 环境变量

通常，您不必设置 PATH 环境变量。TeX 发行版在您的系统上适当地设置了变量。而且，LaTeX Workshop 从来没有接触过这个变量。如果 VS Code 找不到 TeX 的可执行文件，这意味着你的系统设置被破坏了。有关在 Windows 上设置环境变量的方法，请参阅 link 或 link。在 macOS 和 Linux 上，参考 rbenv 开发团队的文档。

如果无法修复系统的设置，也可以使用 LaTeX 配方的 env 属性覆盖 PATH。

2.4 使用

典型的用法是打开一个 .tex 文件并查看 TeX 侧栏以访问所有扩展特性：

• 构建
• 查看和从源代码到PDF来回转换
• 捕获错误和警告
• 环境中导航
• 在文档结构中导航。LaTeX 大纲层次结构的节名是在 latex-workshop.view.outline.sections 中定义的。此属性是按文档结构层次结构顺序排列的大小写敏感字符串数组。对于同一级别的多个标记，使用 | 作为分隔符分隔标记，如 section|alternative。它也被折叠机构使用。
• 各种各样的动作
  • 打开引文浏览器，查看引文的智能感知

如果您希望通过右键菜单访问一些最常见的操作，请设置 latex-workshop.showContextMenu 为 true 。默认值是 false。

2.5 使用 Docker

从 1.35.0 开始，VS Code 支持带有 Remote - Containers 的 Docker。LaTeX Workshop 与此扩展配合良好。请先试试此扩展。

从 5.3.0 版本开始，这里有一个基于 @Arxisos 思想的 Docker 支持的实验性实现。你可以设置 latex-workshop.docker.enabled 为 true 以使用基于 LaTeX 发布的一个 docker。要使用的 docker 镜像由 latex-workshop.docker.image.latex 定义，默认值是 tianon/latex。这里建议的镜像是 'pre-'pulled。

@Arxisos 在 docker 中创建了用于 LaTeX 二进制文件的代码片段，而 @lippertmarkus 对如何将 docker 与 LaTeX Workshop 结合起来进行了简短的描述。

2.6 使用WSL

从 1.35.0 开始，VS Code 通过 Remote - WSL 支持 WSL。LaTeX Workshop 与此扩展配合良好。

3. 编译功能

3.1 构建文档

一个 LaTeX 文件通常通过从 Command Palette 或 TeX 侧栏调用命令 Build LaTeX project 来构建。此命令绑定到快捷键 ctrl+alt+b。如果不能在键绑定中使用 ctrl+alt，请参阅 FAQ。此命令调用的 recipe 由 latex-workshop.latex.recipe.default 定义。

如果您有一个多文件项目，请参阅多文件项目以了解如何发现根文件的更多细节。

您可以定义几个编译工具链，以使用 LaTeX recipes 来构建 LaTeX 项目，然后调用命令 Build with recipe 来选择适当的工具链来实际构建项目。或者，您可以直接从 TeX 侧栏中选择适当的 recipe。

以下设置有助于如何自定义构建一个项目以及如何处理失败。

设置键	描述	默认	类型
latex-workshop.latex.autoBuild.run	当扩展使用默认 recipe 自动构建 LaTeX 项目时	onFileChange	string
latex-workshop.latex.recipes	用于构建的要运行的工具序列		JSON object
latex-workshop.latex.tools	用于构建的可用工具		JSON object
latex-workshop.latex.magic.args	用于 TeX 程序的参数		array of strings
latex-workshop.latex.magic.bib.args	用于 BIB 程序的参数		array of strings
latex-workshop.latex.build.forceRecipeUsage	强制 recipes 的使用	false	boolean

一个进度条指示构建进度。可以使用以下配置变量对其进行定制：

• latex-workshop.progress.runIconType
• latex-workshop.progress.barLength
• latex-workshop.progress.barStyle

3.2 终止当前编译

要终止当前编译，可以通过从命令面板调用 Kill LaTeX compiler process ，或者通过 Build LaTeX Project 中的 TeX 侧栏调用 Terminate current compilation。

3.3 自动构建 LaTeX

除了手动调用 Build LaTeX Project 命令来编译文档外，您还可以让扩展在文件更改时自动开始编译它。这可以在 latex-workshop.latex.autoBuild.run 中定义。自动构建调用的 recipe 由 latex-workshop.latex.recipe.default 定义。

3.3.1 latex-workshop.latex.autoBuild.run

类型	默认值	可选值
string	“onFileChange”	“never”,“onFileChange”

• "never"：禁用自动生成功能
• "onFileChange"：在检测到依赖项中的任何文件更改时构建项目。甚至可以在 vscode 之外修改文件。在这里可以看到关于什么是依赖项以及如何忽略它们中的一些的解释。

3.3.2 latex-workshop.latex.autoBuild.interval

两个连续自动构建之间的最小时间间隔(以毫秒为单位)。

类型	默认值
integer	1000

3.4 清理生成的文件

LaTeX 编译通常会生成几个辅助文件。可以通过从命令面板或 TeX 侧栏调用 Clean up auxiliary files 来删除它们。此命令绑定到 ctrl+alt+c。如果不能在键绑定中使用 ctrl+alt，请参阅 FAQ。

设置键	描述	默认	类型
latex-workshop.latex.autoBuild.cleanAndRetry.enabled	在构建工具链中出现错误后，再次启用清理和构建	true	boolean
latex-workshop.latex.autoClean.run	定义何时自动删除辅助文件	“never”	string
latex-workshop.latex.clean.fileTypes	要清理的文件扩展名		array of strings
latex-workshop.latex.clean.subfolder.enabled	在 latex-workshop.latex.outDir 的子文件夹中递归清理辅助文件	false	boolean

3.4.1 latex-workshop.latex.autoClean.run

类型	默认值	可选值
string	“never”	“never”,“onFailed”, “onBuilt”

• “never”：禁用自动清理功能
• “onFailed”：编译失败后清理项目。
• “onBuilt”：在完成一次编译后清理项目，无论编译是否成功。

3.5 LaTeX recipes

一个 LaTeX recipe 是指在构建 LaTeX 项目时，LaTeX Workshop 按顺序执行的一系列命令。它是由 latex-workshop.latex.recipes 定义的。默认情况下，LaTeX Workshop 包含由变量 latex-workshop.latex.recipes 和 latex-workshop.latex.tools 定义的两个基本 recipes：

• 第一个简单地依赖于 latexmk 命令
• 第二个命令运行以下命令序列：pdflatex → bibtex → pdflatex → pdflatex。

[
  {
    "name": "latexmk ",
    "tools": [
      "latexmk"
    ]
  },
  {
    "name": "pdflatex ➞ bibtex ➞ pdflatex`×2",
    "tools": [
      "pdflatex",
      "bibtex",
      "pdflatex",
      "pdflatex"
    ]
  }
]

出现在 tools 字段中的每个工具都定义为 latex-workshop.latex.tools。其默认值由以下给出：

[
  {
    "name": "latexmk",
    "command": "latexmk",
    "args": [
      "-synctex=1",
      "-interaction=nonstopmode",
      "-file-line-error",
      "-pdf",
      "-outdir=%OUTDIR%",
      "%DOC%"
    ],
    "env": {}
  },
  {
    "name": "pdflatex",
    "command": "pdflatex",
    "args": [
      "-synctex=1",
      "-interaction=nonstopmode",
      "-file-line-error",
      "%DOC%"
    ],
    "env": {}
  },
  {
    "name": "bibtex",
    "command": "bibtex",
    "args": [
      "%DOCFILE%"
    ],
    "env": {}
  }
]

您可以使用不同的工具创建多个 recipes。每个 recipe 都是配置列表中的一个对象，包含一个 name 字段和一个要在 recipe 中调用的 tools 列表。

recipes 中的 tools 可以在 latex-workshop.latex.tools 中定义，其中每个命令都是一个 tool。每个工具都是一个对象，包括一个 name、要生成的一个 command、参数(args)和一些特定的环境变量(env)。env 条目是一个字典。假设您想要在您的home项目中使用一个 texmf 子目录，只需编写：

  "env": {
      "TEXMFHOME": "%DIR%/texmf"
  }

您还可以覆盖 PATH 环境变量。

要在菜谱中包含工具，工具的名称应该包括在菜谱的工具列表中。

在构建项目时，根文件中的魔法注释将被使用，否则将使用第一个配方。可以通过命令latex-workshop.recipes编译另一个配方。默认情况下使用latexmk。这个工具被捆绑在大多数LaTeX发行版中，并且需要perl来执行。对于非perl用户，以下来自MikTeX的texify工具链值得一试：

"latex-workshop.latex.recipes": [{
  "name": "texify",
  "tools": [
    "texify"
  ]
}],
"latex-workshop.latex.tools": [{
  "name": "texify",
  "command": "texify",
  "args": [
    "--synctex",
    "--pdf",
    "--tex-option=\"-interaction=nonstopmode\"",
    "--tex-option=\"-file-line-error\"",
    "%DOC%.tex"
  ],
    "env": {}
}]

args和env参数可以包含%包围的符号。这些占位符是动态替换的。乳胶工场登记下列占位符：

占位符	替换为
%DOC%	LaTeX根文件路径和名称，不带.tex扩展名
%DOCFILE%	不带.tex扩展名的LaTeX根文件名
%DIR%	LaTeX根文件路径
%TMPDIR%	存储辅助文件的临时文件夹
%OUTDIR%	在latex-workshop.latex.outDir中配置的输出目录

或者，您也可以在不使用占位符的情况下设置命令，就像您可以在终端中输入的内容一样。由于大多数LaTeX编译器不接受扩展名，所以%DOC%和%DOCFILE%不包含.tex扩展名。同时，texify需要扩展。因此，在上面的工具中，为了完整性，将%DOC%和.tex连接起来。

latex-workshop.latex.recipe.default
定义Build LaTeX项目命令使用的配方。
type default value possible values
string “first” “first”,“lastUsed”
“第一”:使用latex-workshop.latex.recipes中定义的第一个食谱。
“lastUsed”:使用LaTeX工作室提供的最后一个使用过的配方。
latex-workshop.latex.build.forceRecipeUsage
强制使用recipe系统，即使有一个神奇的注释定义了一个TeX命令。
type default value
boolean false
外部构建命令
尽管上面描述的配方机制是通用的，但是当构建整个LaTeX项目是由个人脚本或Makefile完成时，它可能不能满足您的需要。对于这种特殊情况，我们提供了一个外部构建命令机制，它完全绕过配方机制。只需使用以下两个配置变量定义命令及其参数

latex-workshop.latex.external.build.command
调用latex-workshop.build时要执行的外部命令。

这在编译依赖于Makefile或定制脚本时非常有用。当定义时，它完全绕过配方和根文件检测机制。
type default value
string “”
latex-workshop.latex.external.build.args
调用latex-workshop.build时，latex.external.build.命令的参数
type default value
string[] []

神奇的评论
TeX程序和选项
LaTeX Workshop支持% !TEX程序的魔术注释来指定编译程序。但是，建议使用recipe系统而不是magic程序来定义构建过程，因为后者仅用于向后兼容。

对于% !TEX程序的魔术注释，它的参数定义在latex-workshop.latex.magic.args:

"latex-workshop.latex.magic.args": [
  "-synctex=1",
  "-interaction=nonstopmode",
  "-file-line-error",
  "%DOC%"
]

或者，您也可以使用magic注释直接定义.tex文件中的args !%TEX选项，它覆盖了latex-workshop.latex.magic.args。请注意，它必须包含要处理的文件。例如，要重现默认行为，您应该使用

% !TEX选项= -synctex=1 -交互=非停机模式-文件行错误"%DOC%"
假设根文件中有一行% !TEX program = xelatex。在构建项目之后，LaTeX Workshop将解析根文件并确定应该使用xelatex。

BIB程序和选项
当使用带有参考书目的% !TEX程序时，bib编译器必须用% ! bib程序注释来定义，例如% ! bib程序= bibtex。否则，该扩展将仅使用指定的LaTeX编译器运行一次编译。如果需要，可以使用latex-workshop.latex.magic.bib将额外的参数传递给!BIB程序。参数变量：

"latex-workshop.latex.magic.bib.args": [
  "%DOCFILE%"
]

或者，您也可以使用magic注释直接定义.tex文件中的args !%BIB选项，它覆盖latex-workshop.latex.magic.bib.args。请注意，它必须包含要处理的文件。例如，要重现默认行为，应该使用!%BIB选项= “%DOCFILE%”。

捕获错误和警告
编译工具链发出的警告和错误显示在Problems窗格中。以下设置使您能够自定义要在该面板中获取的内容。如果面板中显示的信息似乎是错误的，请参阅FAQ。

原始编译器日志可以在“输出”窗格中访问，请选择“乳胶编译器”。默认情况下，在调用配方的每个工具之前清除日志。如果您希望保留菜谱中所有工具的日志，请设置latex-workshop.latex.build.clearLog.everyRecipeStep。使为false。

设置的细节
latex-workshop.message.log.show
显示乳胶车间调试日志到输出面板。

此属性定义LaTeX Workshop是否将其调试日志输出到日志面板。

类型默认值
布尔真
latex-workshop.message.badbox.show
在问题面板中显示badbox信息。

类型默认值
布尔真
latex-workshop.message.latexlog.exclude
从问题面板中排除匹配给定regexp的日志消息。

类型默认值
字符串数组[]
latex-workshop.message.information.show
在弹出通知中显示信息消息。

类型默认值
布尔假
latex-workshop.message.warning.show
在弹出式通知中显示警告消息。

类型默认值
布尔真
latex-workshop.message.error.show
在弹出通知中显示错误消息。

类型默认值
布尔真
latex-workshop.message.update.show
显示乳胶车间更新信息的新版本。

类型默认值
布尔真
latex-workshop.latex.build.clearLog.everyRecipeStep.enabled
在配方的每个步骤之前清除LaTeX编译器日志。

将此属性设置为false，以保留菜谱中所有工具的日志。

类型默认值
布尔真
latex-workshop.progress.runIconType
用来表示运行编号的样式"

类型默认值
enum“括号”
可能的值是

“括号”:“⑴⑵⑶…”,
“圈”:“①②③…”,
“固体圈”:“❶❷❸…”,
“句号”:“⒈⒉⒊……”

latex-workshop.progress.barLength
进度条中字符的长度。

类型默认值
15号
latex-workshop.progress.barStyle
类型默认值
枚举”块阴影
可能的值是

“块宽度”:“█████▋░░░(8水平/块)”,
“块阴影”:“█████▓░░░(4水平/块)”,
“块象限”:“█████▙░░░(4水平/块)”,
“没有”:没有酒吧。