README

# PyTeXMK

简体中文 README | English README

LaTeX 辅助编译命令行程序

## 安装

官方版本 PyTeXMK 发布在 PyPI 上，并且可以通过 pip 包管理器从 PyPI 镜像轻松安装。

请注意，您必须使用 Python 3 版本pip：

    pip3 install pytexmk

## 升级

    pip3 install --upgrade pytexmk

## 使用入门

请仔细阅读：待编译主文件及编译类型选定逻辑

> PyTeXMK，仅支持 utf-8 编码的 TeX 文件。

### 默认配置

Pytexmk 默认配置如下：

1. 编译程序：`XeLaTeX`
2. 待编译主文件名：`main.tex`
3. 编译结果存放在 LaTeX 项目的 `Build` 文件夹下 (VSCode 用户则需要在 `settings.json` 中注意设置 `"latex-workshop.latex.outDir": "./Build",` 使得 LaTeX-Workshop 能够找到 pdf )
4. 辅助文件存放在 LaTeX 项目的 `Auxiliary` 文件夹下
5. 编译模式：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 进行编译，生成改动对比文件并编译新文件
-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` | 指定辅助文件存放位置，仅支持文件夹名称

> 魔法注释仅支持在主文件中定义，不支持在子文件中定义。

### 待编译主文件及编译类型选定逻辑

待编译主文件选定逻辑

1. 如果命令行参数中指定了主文件，则使用该主文件名。
2. 如果当前根目录下存在且只有一个主文件，则使用该文件作为待编译主文件。
3. 如果存在魔法注释 `% !TEX root`，则根据魔法注释指定的文件作为主文件。
4. 检索 TeX 文件中的 `\documentclass[]{}` 或 `\begin{document}` 来判断（仅支持检索文档前 200 行）
5. 如果无法根据魔法注释确定主文件，则尝试根据默认主文件名 `main.tex` 指定待编译主文件。
6. 如果仍然无法确定主文件，则输出错误信息并退出程序。

编译类型选定逻辑

1. PyTeXMK 优先使用终端输入命令 `-p` `-x` `-l` 参数指定的编译类型
2. 如果没有指定，则会使用 `% !TEX program = XeLaTeX` 指定的编译类型
3. 如果没有指定，则会使用默认的编译类型 `XeLaTeX`

PyTeXMK 会优先使用 `% !TEX outdir = PDFfile` 指定的编译结果存放位置，如果没有指定，则会使用默认的编译结果存放位置 `Build`

### 配置文件说明

PyTeXMK 支持两种配置文件，分别为系统配置文件和本地配置文件。配置文件可以用于改变 Pytexmk 默认配置以及配置一些其他功能。
系统配置文件在首次运行 PyTeXMK 时自动生成，位于用户目录下，文件名为 `.pytexmkrc`；
本地配置文件会在该项目首次运行 PyTeXMK 时自动生成，位于当前工作目录下，文件名为 `.pytexmkrc`。
自动生成的配置文件中存在详细的注释，请根据注释进行配置。

#### 配置文件路径

系统配置文件路径：Windows 系统为 `C:\Users\用户名\.pytexmkrc`，Linux 系统为 `~/.pytexmkrc`
本地配置文件路径：为当前工作目录下的 `.pytexmkrc` 文件

#### 配置文件优先级

本地配置文件优先级高于系统配置文件，如果两者对相同参数进行配置，则优先使用本地配置文件的配置。

## 更新记录

更新记录详见 CHANGELOG 文档

## 未来工作方向

- 增加尝试修复根目录以外所有 PDF 文件的功能（在创建、编辑或传输过程中发生了某种形式的损坏或非法操作而导致在编译过程中出现类似 `invalid X X R object at offset XXXXX` 的警告的问题）

- 完善主文件判断功能：

  - 通过检索 TeX 文件中的 `\documentclass[]{}` 或 `\begin{document}` 来判断
  - 多主文件编译功能

- 魔法注释功能

  - 通过魔法注释设置主文件名
  - 通过魔法注释设置编译引擎类型
  - 通过魔法注释设置编译结果存放位置
  - 根据魔法注释设置辅助文件存放位置
  - 解决魔法注释大小写空格敏感问题
  - LaTeXDiff 相关魔法注释
  - 魔法注释重复定义的处理逻辑
    - 主文件于子文件中魔法注释的冲突处理
    - 解决多存在多个主文件时的主文件于子文件中魔法注释冲突问题

- 编译次数自动判断功能

  展开查看
  - 完善编译过程出错后的中断处理机制
  - 自动判断是否需要编译参考文献
  - 自动判断是否需要编译索引文件
  - 自动判断是否要重新编译

- 增加配置文件功能

  - 可配置默认的编译引擎 （目前默认编译命令是 `XeLaTeX`）
  - 可配置默认生成的结果文件存放位置（目前默认存放在 `Build` 子文件夹下）
  - 可配置默认的辅助文件存放位置（目前默认存放在 `Auxiliary` 子文件夹下）
  - 可配置其他索引宏包的配置
  - 可配置 PDF 编译完是否默认预览
  - 可配置 PDF 文件打开程序
  - 可配置默认安静模式状态
  - 可配置默认详细模式状态
  - 可配置默认文件名称
  - 可配置默认 LaTeXDiff 新 TeX 文件名
  - 可配置默认 LaTeXDiff 旧 TeX 文件名
  - 可配置默认 LaTeXDiff 输出文件名

- 预览与日志功能

  - 解决终端中文显示问题
  - PDF 预览功能
  - 报错信息显示功能
  - 进一步完善报错信息显示功能
  - 实现日志记录功能

- 完善清理功能

  展开查看
  - 完善清理辅助文件功能
  - 完善清理所有文件功能
  - 完善清理所有辅助文件功能

- 宏包检缺失并自动安装（texlive）

- 添加 PyTeXMK 更新检查功能

- LaTeXDiff 相关功能

  - 添加编译结束后将辅助文件移动到根目录下功能
  - LaTeXDiff 命令行参数的实现
  - 添加单个项目的配置文件功能
  - LaTeXDiff 编译判断逻辑

- 程序国际化

- README 文档完善

  - 增加配置文件相关说明