如何利用docker与vscode写latex？

前言

由于容器技术的发展，使用docker能很快地搭建出所需的latex编译环境而不占用主机资源，而且支持多平台。联系上vscode就无敌了，下面主要说一下步骤。

步骤

安装 docker 、vscode

具体的安装方法请看官网。
以mac为例，安装都使用homebrew。

安装 LaTeX Workshop 插件

插件的安装 插件的说明

访问GitHub获取插件的更多信息：LaTeX-Workshop

拉取镜像

docker pull tianon/latex

➜  ~ docker pull tianon/latex
Using default tag: latest
latest: Pulling from tianon/latex
27833a3ba0a5: Already exists 
0967e3dee126: Pull complete 
Digest: sha256:d9d5378ae77df3352aba36f9672a4c2d5c82861475508a1fae46b40369ed6ac9
Status: Downloaded newer image for tianon/latex:latest

官方说明：Using Docker

Starting with release 5.3.0, there is an experimental implementation on Docker support following the idea of @Arxisos. You can set latex-workshop.docker.enabled to true to use tianon/latex. It is advised that the image is 'pre-'pulled.

@Arxisos created snippets for LaTeX binaries in docker, and @lippertmarkus had another short description on how to use Docker with LaTeX Workshop.

所以还是用官方构建的镜像tianon/latex吧，具体在插件中是如何运行的?大致就是根据那个issue说的一样，使用docker run --rm 后面跟一些参数（--rm是Automatically remove the container when it exits，要知道使用docker run是运行一个新容器当执行完毕后容器被自动终止，这个--rm就是确认终止后是不是要自动删除），在GitHub上script文件夹中的源代码是这样写的：docker run -i --rm -w "$(pwd)" -v "$(pwd):$(pwd)" $LATEXWORKSHOP_DOCKER_LATEX latexmk "$@"。

插件设置

1. vscode 设置

   
   vscode 设置

2. 开启docker

   
   开启docker

3. latex recipe 的个人设置

   
   latex recipe 的个人设置

进入settings.json

主要是参照说明=》Compile，以及scripts : Resolve#673 customizable docker image进行更改，目前似乎只支持“Define the image for latexmk, synctex, texcount, and latexindent.”这四个，我选用的 是 latexmk 作为第一个也是默认的recipe，改动大致有：

• 把pdflatex换成xelatex以防止ctex宏包出错，使用"-xelatex"。
• Cleaning generated files，清除掉生成的不需要的文件，使用"-c"（注意这个要加在其他命令的后面，不推荐！！！在产生目录和交叉引用等时，需要编译两次才能获得正确结果，第二次编译需要第一次编译的中间文件做支持，所以不建议使用这种清除功能），你可能会想用官方所说的“Cleaning generated files”中的vscode编辑器中的一些设置如latex-workshop.latex.autoClean.run，也是不好的。清除的功能由于要用到交叉引用，暂时不考虑吧。

关键部分就在于：

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

目前我的vscode的整体配置如下：

{
    "python.pythonPath": "/usr/local/opt/python/bin/python3.7",
    // LaTeX Workshop
    "latex-workshop.view.pdf.viewer": "tab",
    "latex-workshop.docker.enabled": true,
    "latex-workshop.intellisense.package.enabled": true,
    "latex-workshop.latex.recipes": [
        {
            "name": "latexmk 🔃",
            "tools": [
            "latexmk"
            ]
        },
        {
            "name": "xelatex ➞ bibtex ➞ xelatex`×2",
            "tools": [
            "xelatex",
            "bibtex",
            "xelatex",
            "xelatex"
            ]
        }
    ],
    "latex-workshop.latex.tools": [
        {
            "name": "latexmk",
            "command": "latexmk",
            "args": [
            "-synctex=1",
            "-interaction=nonstopmode",
            "-file-line-error",
            "-xelatex",
            "-outdir=%OUTDIR%",
            "%DOCFILE%"
            ],
            "env": {}
        },
        {
            "name": "xelatex",
            "command": "xelatex",
            "args": [
            "-synctex=1",
            "-interaction=nonstopmode",
            "-file-line-error",
            "%DOCFILE%"
            ],
            "env": {}
        },
        {
            "name": "bibtex",
            "command": "bibtex",
            "args": [
            "%DOCFILE%"
            ],
            "env": {}
        }
    ]
}

Note that you can't use the %DOC% variable in the settings as it contains the path on the local machine instead of the one in the container.

latexmk --help
Latexmk 4.41: Automatic LaTeX document generation routine
Usage: latexmk [latexmk_options] [filename ...]
Latexmk_options:
-aux-directory=dir or -auxdir=dir
- set name of directory for auxiliary files (aux, log)
- Currently this only works with MiKTeX
-bibtex - use bibtex when needed (default)
-bibtex- - never use bibtex
-bibtex-cond - use bibtex when needed, but only if the bib files exist
-bm <message> - Print message across the page when converting to postscript
-bi <intensity> - Set contrast or intensity of banner
-bs <scale> - Set scale for banner
-commands - list commands used by latexmk for processing files
-c - clean up (remove) all nonessential files, except
dvi, ps and pdf files.
This and the other clean-ups are instead of a regular make.
-C - clean up (remove) all nonessential files
including aux, dep, dvi, postscript and pdf files
and file of database of file information
-CA - clean up (remove) all nonessential files.
Equivalent to -C option.
-CF - Remove file of database of file information before doing
other actions
-cd - Change to directory of source file when processing it
-cd- - Do NOT change to directory of source file when processing it
-dependents or -deps - Show list of dependent files after processing
-dependents- or -deps- - Do not show list of dependent files
-deps-out=file - Set name of output file for dependency list,
and turn on showing of dependency list
-dF <filter> - Filter to apply to dvi file
-dvi - generate dvi
-dvi- - turn off required dvi
-e <code> - Execute specified Perl code (as part of latexmk start-up
code)
-f - force continued processing past errors
-f- - turn off forced continuing processing past errors
-gg - Super go mode: clean out generated files (-CA), and then
process files regardless of file timestamps
-g - process regardless of file timestamps
-g- - Turn off -g
-h - print help
-help - print help
-jobname=STRING - set basename of output file(s) to STRING.
(Like --jobname=STRING on command line for many current
implementations of latex/pdflatex.)
-l - force landscape mode
-l- - turn off -l
-latex=<program> - set program used for latex.
(replace '<program>' by the program name)
-latexoption=<option> - add the given option to the (pdf)latex command
-logfilewarninglist or -logfilewarnings
give list of warnings after run of (pdf)latex
-logfilewarninglist- or -logfilewarnings-
do not give list of warnings after run of (pdf)latex
-M - Show list of dependent files after processing
-MF file - Specifies name of file to receives list dependent files
-MP - List of dependent files includes phony target for each source file.
-new-viewer - in -pvc mode, always start a new viewer
-new-viewer- - in -pvc mode, start a new viewer only if needed
-nobibtex - never use bibtex
-nodependents - Do not show list of dependent files after processing
-norc - omit automatic reading of system, user and project rc files
-output-directory=dir or -outdir=dir
- set name of directory for output files
-pdf - generate pdf by pdflatex
-pdfdvi - generate pdf by dvipdf
-pdflatex=<program> - set program used for pdflatex.
(replace '<program>' by the program name)
-pdfps - generate pdf by ps2pdf
-pdf- - turn off pdf
-ps - generate postscript
-ps- - turn off postscript
-pF <filter> - Filter to apply to postscript file
-p - print document after generating postscript.
(Can also .dvi or .pdf files -- see documentation)
-print=dvi - when file is to be printed, print the dvi file
-print=ps - when file is to be printed, print the ps file (default)
-print=pdf - when file is to be printed, print the pdf file
-pv - preview document. (Side effect turn off continuous preview)
-pv- - turn off preview mode
-pvc - preview document and continuously update. (This also turns
on force mode, so errors do not cause latexmk to stop.)
(Side effect: turn off ordinary preview mode.)
-pvc- - turn off -pvc
-quiet - silence progress messages from called programs
-r <file> - Read custom RC file
(N.B. This file could override options specified earlier
on the command line.)
-recorder - Use -recorder option for (pdf)latex
(to give list of input and output files)
-recorder- - Do not use -recorder option for (pdf)latex
-rules - Show list of rules after processing
-rules- - Do not show list of rules after processing
-showextraoptions - Show other allowed options that are simply passed
as is to latex and pdflatex
-silent - silence progress messages from called programs
-time - show CPU time used
-time- - don't show CPU time used
-use-make - use the make program to try to make missing files
-use-make- - don't use the make program to try to make missing files
-v - display program version
-verbose - display usual progress messages from called programs
-version - display program version
-view=default - viewer is default (dvi, ps, pdf)
-view=dvi - viewer is for dvi
-view=none - no viewer is used
-view=ps - viewer is for ps
-view=pdf - viewer is for pdf
-lualatex - use lualatex for processing files to pdf
and turn pdf mode on, dvi/ps modes off
-xelatex - use xelatex for processing files to pdf
and turn pdf mode on, dvi/ps modes off
filename = the root filename of LaTeX document
-p, -pv and -pvc are mutually exclusive
-h, -c and -C override all other options.
-pv and -pvc require one and only one filename specified
All options can be introduced by '-' or '--'. (E.g., --help or -help.)
In addition, latexmk recognizes many other options that are passed to
latex and/or pdflatex without interpretation by latexmk. Run latexmk
with the option -showextraoptions to see a list of these
Report bugs etc to John Collins <jcc8 at psu.edu>.

xelatex --help
Usage: xetex [OPTION]... [TEXNAME[.tex]] [COMMANDS]
or: xetex [OPTION]... \FIRST-LINE
or: xetex [OPTION]... &FMT ARGS
Run XeTeX on TEXNAME, usually creating TEXNAME.pdf.
Any remaining COMMANDS are processed as XeTeX input, after TEXNAME is read.
If the first line of TEXNAME is %&FMT, and FMT is an existing .fmt file,
use it. Else use NAME.fmt', where NAME is the program invocation name, most commonlyxetex'.
Alternatively, if the first non-option argument begins with a backslash,
interpret all non-option arguments as a line of XeTeX input.
Alternatively, if the first non-option argument begins with a &, the
next word is taken as the FMT to read, overriding all else. Any
remaining arguments are processed as above.
If no arguments or options are specified, prompt for input.
-etex enable e-TeX extensions
[-no]-file-line-error disable/enable file:line:error style messages
-fmt=FMTNAME use FMTNAME instead of program name or a %& line
-halt-on-error stop processing at the first error
-ini be xeinitex, for dumping formats; this is implicitly
true if the program name is `xeinitex'
-interaction=STRING set interaction mode (STRING=batchmode/nonstopmode/
scrollmode/errorstopmode)
-jobname=STRING set the job name to STRING
-kpathsea-debug=NUMBER set path searching debugging flags according to
the bits of NUMBER
[-no]-mktex=FMT disable/enable mktexFMT generation (FMT=tex/tfm)
-mltex enable MLTeX extensions such as \charsubdef
-output-comment=STRING use STRING for XDV file comment instead of date
-output-directory=DIR use existing DIR as the directory to write files in
-output-driver=CMD use CMD as the XDV-to-PDF driver instead of xdvipdfmx
-no-pdf generate XDV (extended DVI) output rather than PDF
[-no]-parse-first-line disable/enable parsing of first line of input file
-papersize=STRING set PDF media size to STRING
-progname=STRING set program (and fmt) name to STRING
-recorder enable filename recorder
[-no]-shell-escape disable/enable \write18{SHELL COMMAND}
-shell-restricted enable restricted \write18
-src-specials insert source specials into the XDV file
-src-specials=WHERE insert source specials in certain places of
the XDV file. WHERE is a comma-separated value
list: cr display hbox math par parend vbox
-synctex=NUMBER generate SyncTeX data for previewers if nonzero
-translate-file=TCXNAME (ignored)
-8bit make all characters printable, don't use ^^X sequences
-help display this help and exit
-version output version information and exit
Email bug reports to xetex@tug.org.

Each recipe in the list is an object containing its name and the names of tools to be used sequentially, which are defined in latex-workshop.latex.tools. **By default, the first recipe is used to compile the project. **

Each tool is labeled by its name. When invoked, command is spawned with arguments defined in args and environment variables defined in env. Typically no spaces should appear in each argument unless in paths. Placeholders %DOC%, %DOCFILE%, %DIR%, %TMPDIR% and %OUTDIR% are available. For details, please visit https://github.com/James-Yu/LaTeX-Workshop/wiki/Compile#latex-recipe.

测试

1. 编写 tex 文件

编写tex文件

\documentclass[UTF8]{article}
\usepackage{ctex}
\usepackage{lipsum}

\begin{document}

\tableofcontents

\section{第一章}

\subsection{Text for a subsection of the first section}
我们：
\lipsum[1-3]
\label{lip}
\subsection{Text for a subsection of the first section}
你好：
\lipsum[4-7]

\section{第二章}
\lipsum[8]
请看：我指的是\ref{lip}在这一页：\pageref{lip}。

\end{document}

2. build 大功告成！

build

参考

1. LaTeX-Workshop
2. Compile
3. 非常全的VsCode快捷键
4. Using docker for building documents
5. scripts : Resolve#673 customizable docker image
6. latexmk --help 及 vscode 的settings

结语

我忙活了好多天，从学习docker花了9天，到今天一个上午和半个下午都在研究vscode的配置，看了很多资料，主要是看懂script和Linux中--help一下，想一想原理，然后基本就成了，别在清除残余文件上花时间不值得啊。不得不说vscode上的插件真的是很强大啊。总共花了十多天就为了用docker搭出一个能写latex的环境，真的是耗时太久了！还有好多事情没做，真的是亚历山大！！！