PyTeXMK

简体中文 README | English README
LaTeX 辅助编译命令行程序
安装
官方版本 PyTeXMK 发布在 PyPI 上,并且可以通过 pip 包管理器从 PyPI 镜像轻松安装。
请注意,您必须使用 Python 3 版本pip:
pip3 install pytexmk
升级
pip3 install --upgrade pytexmk
使用入门
基础使用参见:Issues #1
请仔细阅读:待编译主文件及编译类型选定逻辑
PyTeXMK,仅支持 utf-8 编码的 TeX 文件。
默认配置
Pytexmk 默认配置如下:
- 编译程序:
XeLaTeX
- 待编译主文件名:
main.tex
- 编译结果存放在 LaTeX 项目的
Build
文件夹下 (VSCode 用户则需要在 settings.json
中注意设置 "latex-workshop.latex.outDir": "./Build",
使得 LaTeX-Workshop 能够找到 pdf ) - 辅助文件存放在 LaTeX 项目的
Auxiliary
文件夹下 - 编译模式:batch 模式(编译过程信息不显,如需显示编译过程信息请使用
-uq
参数)
注意:以上参数均可在配置文件中修改,具体请参考:配置文件说明
编译命令
PyTeXMK 支持:
- 编译程序:
XeLaTeX
PdfLaTeX
LuaLaTeX
- 参考文献:
bibtex
biblatex
thebibliography
- 符号索引:
glossaries
nomencl
mkeidx
位置参数:
Option | Description |
---|
document | 要被编译的文件名 |
选项:
Option | Description |
---|
-h, --help | 显示帮助信息 |
-v, --version | 显示程序版本号 |
-p, --PdfLaTeX | PdfLaTeX 进行编译 |
-x, --XeLaTeX | XeLaTeX 进行编译 |
-l, --LuaLaTeX | LuaLaTeX 进行编译 |
-d, --LaTeXDiff | 使用 LaTeXDiff 进行编译,生成改动对比文件 |
-dc, --LaTexDiff-compile | 使用 LaTeXDiff 进行编译,生成改动对比文件并编译新文件 |
-dr, --draft | 启用草稿模式进行编译,提高编译速度 (无图显示) |
-c, --clean | 清除所有主文件的辅助文件 |
-C, --Clean | 清除所有主文件的辅助文件(包含根目录)和输出文件 |
-ca, --clean-any | 清除所有带辅助文件后缀的文件 |
-Ca, --Clean-any | 清除所有带辅助文件后缀的文件(包含根目录)和主文件输出文件 |
-nq, --non_quiet | 非安静模式运行,此模式下显示编译过程 |
-vb, --verbose | 显示 PyTeXMK 运行过程中的详细信息 |
-pr, --pdf-repair | 修复所有根目录以外的 pdf 文件 |
-pv, --pdf-preview | 尝试编译结束后调用 Web 浏览器或者本地PDF阅读器预览生成的PDF文件,如有填写 'FILE_NAME' 则不进行编译打开指定文件 |
说明:
-pr
参数的功能是 "当 LaTeX 编译过程中报类似 invalid X X R object at offset XXXXX
的警告时,可使用此参数尝试修复所有 pdf 文件"
invalid X X R object at offset XXXXX
警告的出现是由于 PDF 图片文件在创建、编辑或传输过程中发生了某种形式的损坏或非法操作导致的,可能的原因包括文件部分内容缺失、xref表损坏、或者是文件结构中的其他问题-d
和 -dc
命令输入示例: pytexmk -d old_tex_file new_tex_file
和 pytexmk -dc old_tex_file new_tex_file
生成的改动对比文件名为 LaTeXDiff.tex
-pv
参数的功能是:尝试编译结束后调用 Web 浏览器或者本地PDF阅读器预览生成的PDF文件,仅支持输出目录下的 PDF 文件,如需在命令行中指定待编译主文件,则 -pv
命令,需放置 document
后面, -pv
命令无需指定参数,示例:pytexmk main -pv
;如无需在命令行中指定待编译主文件,则直接输入 -pv
即可,示例:pytexmk -pv
魔法注释
PyTeXMK 支持使用魔法注释来定义待编译主文件、编译程序、编译结果存放位置等(仅支持检索文档前 50 行)。
Magic Comment | Description |
---|
% !TEX program = XeLaTeX | 指定编译类型,可选 XeLaTeX PdfLaTeX LuaLaTeX |
% !TEX root = main.tex | 指定待编译 LaTeX 文件名,仅支持主文件在项目根目录下的情况 |
% !TEX outdir = out_folde | 指定编译结果存放位置,仅支持文件夹名称 |
% !TEX auxdir = aux_folder | 指定辅助文件存放位置,仅支持文件夹名称 |
魔法注释仅支持在主文件中定义,不支持在子文件中定义。
待编译主文件及编译类型选定逻辑
待编译主文件选定逻辑
- 如果命令行参数中指定了主文件,则使用该主文件名。
- 如果当前根目录下存在且只有一个主文件,则使用该文件作为待编译主文件。
- 如果存在魔法注释
% !TEX root
,则根据魔法注释指定的文件作为主文件。 - 检索 TeX 文件中的
\documentclass[]{}
或 \begin{document}
来判断(仅支持检索文档前 200 行) - 如果无法根据魔法注释确定主文件,则尝试根据默认主文件名
main.tex
指定待编译主文件。 - 如果仍然无法确定主文件,则输出错误信息并退出程序。
编译类型选定逻辑
- PyTeXMK 优先使用终端输入命令
-p
-x
-l
参数指定的编译类型 - 如果没有指定,则会使用
% !TEX program = XeLaTeX
指定的编译类型 - 如果没有指定,则会使用默认的编译类型
XeLaTeX
PyTeXMK 会优先使用 % !TEX outdir = PDFfile
指定的编译结果存放位置,如果没有指定,则会使用默认的编译结果存放位置 Build
配置文件说明
PyTeXMK 支持两种配置文件,分别为系统配置文件和本地配置文件。配置文件可以用于改变 Pytexmk 默认配置以及配置一些其他功能。
系统配置文件在首次运行 PyTeXMK 时自动生成,位于用户目录下,文件名为 .pytexmkrc
;
本地配置文件会在该项目首次运行 PyTeXMK 时自动生成,位于当前工作目录下,文件名为 .pytexmkrc
。
自动生成的配置文件中存在详细的注释,请根据注释进行配置。
配置文件路径
系统配置文件路径:Windows 系统为 C:\Users\用户名\.pytexmkrc
,Linux 系统为 ~/.pytexmkrc
本地配置文件路径:为当前工作目录下的 .pytexmkrc
文件
配置文件优先级
本地配置文件优先级高于系统配置文件,如果两者对相同参数进行配置,则优先使用本地配置文件的配置。
更新记录
更新记录详见 CHANGELOG 文档
未来工作方向