80 lines
5.6 KiB
Markdown
80 lines
5.6 KiB
Markdown
# BaGu Thesis
|
||
|
||
BaGu Thesis是一个专精于将LaTeX论文转换到DOCX格式转换的工具。它通过中间格式XThesis（基于XML）实现高质量的格式转换，特别适用于必须需要提交DOCX格式论文的场景。
|
||
|
||
## 简介和项目创建缘由
|
||
|
||
本项目旨在解决在中国国内高校中普遍存在的一个问题：大多数学校只提供DOCX格式的论文模板，且提交时也只能接受DOCX格式的论文。学校并不认可LaTeX编写的文章，也大多不愿意接受由LaTeX编译来的PDF格式的文档。此外，许多教师也只接受DOCX格式的文档。他们美其名曰"规范化"和"方便给你们添加评价"，实则是他们自己除了DOCX格式的文档以外，就不知道如何在其它文档格式（例如PDF）里添加注释。他们把一个本应专注于学术内容的评审过程，变成了迂腐的格式检查任务。本项目旨在帮助能够使用LaTeX编写论文的学生无痛地将他们的论文转换为DOCX格式，以应付这些无谓的要求。如果你所在的学校或导师接受LaTeX或PDF格式的论文，请优先使用这些格式（我知道的就有西安电子科技大学的XDUTS模板）。毕竟本项目只是为了应付现实而不得不做的妥协。
|
||
|
||
项目中的**BaGu（八股）**一词也来源于此现象：在中国，许多对于论文的审查都浪费在格式检查这一隔靴搔痒的事情上。论文格式要严格按照学校规定：页边距多少厘米、字号多少磅、行距多少倍、标题格式如何等等。这些琐碎的格式要求就像八股文一样。说到底，这都是因为论文本身的内容实际上没什么好看的，大家能写出来什么东西大家自己都心知肚明。无非是东拼西凑、复制粘贴、文献堆砌。审查的人们也心知肚明，但他们必须假装认真地审阅论文，于是格式就成了最好的挑刺对象。
|
||
|
||
本项目的存在，就是为了让你能够用LaTeX专注于内容创作，然后用最短的时间生成一个符合格式要求的DOCX文件，把时间浪费在更有意义的事情上：比如思考论文是否真的有意义，或者干脆出去玩一会儿。
|
||
|
||
## 与其他方案的比较
|
||
|
||
你可能听说过pandoc，它是一个强大的通用文档转换工具，理论上可以实现LaTeX到DOCX的转换。我也尝试过 pandoc，包括使用了[pandoc-tex-numbering](https://github.com/fncokg/pandoc-tex-numbering)等过滤器来完成相似的任务，但效果均不尽人意。主要问题在于：
|
||
|
||
1. **交叉引用问题**：pandoc 生成的DOCX在交叉引用上存在诸多问题，如图片编号、表格编号、公式编号、参考文献引用等，这些在pandoc转换后往往不符合纯粹使用DOCX格式制作论文的规范。例如参考文献的引用，通常是通过交叉引用列表项来实现的，而pandoc并不能做到这一点。
|
||
1. **学习曲线陡峭**：为了达到我想要的交叉引用效果，我不得不需要去使用Lua语言写很多pandoc过滤器。我不熟悉Lua语言，不熟悉pandoc的Lua模块，也不知道这些任务到底能不能在pandoc里完成。
|
||
|
||
因此，我选择单开了一个项目，在AI的辅助下完成这一目标。本项目专精于论文的LaTeX到DOCX格式的转换，而非通用的文档转换器，能够更好地处理学术论文中的各种特殊需求。
|
||
|
||
## 使用方法
|
||
|
||
本项目使用 `uv` 作为包管理工具，确保你已经安装了 `uv`，并初始化了项目。
|
||
|
||
整个项目分为两部分，首先将LaTeX转为XThesis格式，再将XThesis格式转为DOCX格式。
|
||
|
||
### LaTeX转XThesis格式
|
||
|
||
使用以下命令将LaTeX格式转换为XThesis格式：
|
||
|
||
```bash
|
||
uv run latex2xthesis.py --in example.tex --out example.xml --config latex2xthesis.toml --resource-dir /path/to/your/example
|
||
```
|
||
|
||
**参数说明**：
|
||
|
||
- `--in` 或 `-i`：指定输入的 LaTeX 文件路径（必选）
|
||
- `--out` 或 `-o`：指定输出的 XThesis XML 文件路径（必选）
|
||
- `--config` 或 `-c`：指定配置文件路径，用于控制转换过程中的各种选项（必选）
|
||
- `--resource-dir` 或 `-r`：指定资源文件路径，用于查找图片、参考文献等在你LaTeX文件中引用的外部资源。通常是你LaTeX文件所在的文件夹（必选）
|
||
|
||
### XThesis转DOCX格式
|
||
|
||
使用以下命令将XThesis格式转换为DOCX格式：
|
||
|
||
```bash
|
||
uv run xthesis2docx.py --in example.xml --out example.docx --config xthesis2docx.toml
|
||
```
|
||
|
||
**参数说明**：
|
||
|
||
- `--in` 或 `-i`：指定输入的 XThesis XML 文件路径（必选）
|
||
- `--out` 或 `-o`：指定输出的 DOCX 文件路径（必选）
|
||
- `--config` 或 `-c`：指定配置文件路径，用于控制 DOCX 格式的各种样式和排版选项（必选）
|
||
|
||
### 一站式转换
|
||
|
||
如果你不需要中间文件，可以直接使用以下命令将LaTeX格式转换为DOCX格式：
|
||
|
||
```bash
|
||
uv run baguthesis.py --in example.tex --out example.docx --frontend-config latex2xthesis.toml --backend-config xthesis2docx.toml --resource-dir /path/to/your/example
|
||
```
|
||
|
||
**参数说明**：
|
||
|
||
- `--in` 或 `-i`：指定输入的 LaTeX 文件路径（必选）
|
||
- `--out` 或 `-o`：指定输出的 DOCX 文件路径（必选）
|
||
- `--frontend-config`：指定前端配置文件路径（即LaTeX转XThesis的配置文件）（必选）
|
||
- `--backend-config`：指定后端配置文件路径（即XThesis转DOCX的配置文件）（必选）
|
||
- `--resource-dir` 或 `-r`：指定资源文件路径，用于查找图片、参考文献等在你LaTeX文件中引用的外部资源。通常是你LaTeX文件所在的文件夹（必选）
|
||
|
||
## 许可证
|
||
|
||
本项目采用MIT许可证。
|
||
|
||
## 贡献
|
||
|
||
如果你在使用过程中遇到任何问题，或者有改进建议，欢迎提交Issue和Pull Request。
|