diff --git a/README.md b/README.md index 2aa2fca..9236b06 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # BaGu Thesis -BaGu Thesis是一个专精于将LaTeX论文转换到DOCX格式转换的工具。它通过中间格式XThesis（基于XML）实现高质量的格式转换，特别适用于必须需要提交DOCX格式论文的场景。 +BaGu Thesis是一个专精于将LaTeX论文转换到DOCX格式转换的工具。它凭借Pandoc的文档转换能力，以及一系列附加脚本，来实现高质量的格式转换，特别适用于必须需要提交DOCX格式论文的场景。 ## 简介和项目创建缘由 @@ -10,65 +10,19 @@ BaGu Thesis是一个专精于将LaTeX论文转换到DOCX格式转换的工具。 本项目的存在，就是为了让你能够用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`，并初始化了项目。 +本项目由两部分组成，它们分别位于`pandoc`和`winword`文件夹中。 -整个项目分为两部分，首先将LaTeX转为XThesis格式，再将XThesis格式转为DOCX格式。 +一般来说，使用`pandoc`中的内容就足以将你的LaTeX文档转换成较为标准的DOCX文档了。但有时候，你的上级会给你发所谓的DOCX模板，这时候你就需要使用`winword`文件夹中提供的方法来将生成的DOCX文档套用到你的DOCX模板之上了。 -### LaTeX转XThesis格式 +有关如何使用这两部分，请分别查看`pandoc`和`winword`的README文件。 -使用以下命令将LaTeX格式转换为XThesis格式： +## 未来规划 -```bash -uv run latex2xthesis.py --in example.tex --out example.xml --config latex2xthesis.toml --resource-dir /path/to/your/example -``` +该项目未来计划编写专用的格式转换器，该转换器通过中间格式XThesis（基于XML）实现高质量的格式转换，而非依赖于Pandoc。这主要是因为Pandoc生成的DOCX在交叉引用上存在诸多问题，如图片编号、表格编号、公式编号、参考文献引用等。这些在Pandoc转换后往往不符合**纯粹**使用DOCX格式制作论文的规范。例如参考文献的引用，通常是通过交叉引用列表项来实现的，而Pandoc并不能做到这一点，尽管Pandoc生成的引用仍然可以被点击并转到正确引用源。如果一定要做到这一点，则需要编写大量的Pandoc Filter来实现，而我不熟悉Pandoc的API，也不知道这些任务能不能使用Pandoc Filter完成。 -**参数说明**： - -- `--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文件所在的文件夹（必选） +该计划的进度可在`xthesis`分支中进行浏览，但其远远达不到可供使用的地步。 ## 许可证 diff --git a/pandoc/.gitattributes b/pandoc/.gitattributes new file mode 100644 index 0000000..d050677 --- /dev/null +++ b/pandoc/.gitattributes @@ -0,0 +1,2 @@ +# See all DOCX file as binary +*.docx binary diff --git a/pandoc/README.md b/pandoc/README.md index 756f08c..8669dc1 100644 --- a/pandoc/README.md +++ b/pandoc/README.md @@ -1,12 +1,23 @@ # Pandoc Thesis Environment -适用于Pandoc，将LaTeX论文转换为DOCX格式论文的环境。 +适用于Pandoc的将LaTeX论文转换为DOCX格式论文的环境。 -这是我一开始尝试的，使用Pandoc配合pandoc filter来实现论文转换的环境。后来我觉得不太好，就放弃，转而开发本项目，但这个环境还是留着。 +# 必要条件 + +你需要一些必要条件来使用本环境： + +- Pandoc 3.9.0.2 + * 我强烈建议安装完全一致的版本，因为我曾看过一些Pandoc Filter需要与Pandoc版本完全一致才能使用，比如`pandoc-crossref`，而我不太清楚我现在用的Pandoc Filter是否有相似的要求，除非你完全确信你选择的版本可以运行（多试试也没坏处，如果你不是急着要转换文档的话）。 + * 安装完成后需要确保Pandoc在你的环境变量中。使用`pandoc --version`指令检查Pandoc版本并测试是否能成功找到Pandoc。 +- Python 3.11和Astral UV + * Python和UV的版本实际上限制不是那么大，没必要完全一致，确定能用即可。 + * Astral UV安装完后在本目录下运行`uv sync`来初始化环境。 # 用法 -```bash +在本目录下执行以下指令进行文档转换： + +```bat uv run pandoc \ -s \ -f latex -t docx \ @@ -14,14 +25,64 @@ uv run pandoc \ --metadata-file=meta.yaml \ -F pandoc-tex-numbering \ --resource-path \ + --reference-doc=my-thesis.docx \ -o ``` 参数解释： -- `-s`：Standalone模式 -- `-f latex -t docx`：显式指定输入输出格式 -- `--citeproc`：启用引用解析功能，不启用就没有引用标识 -- `--metadata-file=meta.yaml`：指定元数据，包括：引用文献样式，以及pandoc-tex-numbering过滤器的相关配置 -- `-F pandoc-tex-numbering`：使用pandoc-tex-numbering过滤器 -- `--resource-path`：设置LaTeX资源文件夹，要找的图片等内容，都会在这个文件夹里找，一般来说，就是你LaTeX文件所在的文件夹 +- `uv run pandoc`要求在UV的虚拟环境中执行Pandoc命令，让Pandoc能够找到在虚拟环境中安装的使用Python编写的Pandoc Filter。 +- ``在执行的时候替换为指向你待转换的LaTeX文档的路径。 +- `-s`表示Standalone模式，用于表示生成一个独立的文档，而不仅仅是文档片段。 +- `-f latex -t docx`用于显式指定输入输出格式。 +- `--citeproc`用于启用引用解析功能，不启用就没有引用标识。 +- `--metadata-file=meta.yaml`指定了元数据，包括：引用文献样式和`pandoc-tex-numbering`过滤器等相关配置。 +- `-F pandoc-tex-numbering`显式指定使用`pandoc-tex-numbering`过滤器。 +- `--resource-path `用于设置LaTeX资源文件夹。Pandoc会在你指定的``文件夹中查找文档中引用的图片和子文档等内容。一般来说，需要设置为你待转换的LaTeX文件所在的文件夹的路径。 +- `--reference-doc=my-thesis.docx`设置了转换到DOCX格式时使用的模板。你也可以把`my-thesis.docx`换成你想要的模板，至于如何编辑属于你的模板，请参考后文。 +- `-o `：在执行的时候将``替换为指向你存储转换后的DOCX文档的路径。 + +# DOCX模板 + +该目录下的`my-thesis.docx`文件是我已经编辑好的模板。该模板可以满足我的大部分的需求，输出也足够的美观。 + +## 创建模板 + +通常而言你无需重新创建该模板，但如果你更换了Pandoc的版本，或者你的格式需求与我不一致，你就需要重新创建属于你自己的DOCX模板。以下内容将讲述如何创建属于你自己的DOCX模板，这也是我创建我自己模板时的步骤。 + +### 导出默认模板 + +使用`pandoc -o --print-default-data-file reference.docx`来导出模板。其中： + +- ``是导出的DOCX模板的存放路径。 +- `--print-default-data-file`用于指示Pandoc导出内部模板。 +- `reference.docx`是固定文本，不得改变。 + +### 修改模板 + +使用Word，而非WPS，LibreOffice，macOS Word等软件，来修改此模板。打开模板后，你会发现其中包含一系列文本。这些文本是方便你预览效果用的，我们需要修改的是样式，修改样式后这些文本也会变化。 + +在Ribbon栏的“开始”选项卡下，找到“样式”部分，点击右下角的小箭头，展开“样式”对话框。可选的，你可以点击最下方的“选项...”按钮，将列表的排序方式选择为“按类型”以获得更好的浏览体验。 + +- 找到“正文”样式，它是几乎所有样式的基础，我们要在这里修改全局的字体设置。点击其右边的小箭头，选择“修改”，打开对话框。 + * 字体的中文改为宋体，西文改为Times New Roman，字号设置为小四。 + * 段落的间距改为段后0.5行。 +- 找到“正文文本”样式，它是所有正文文字的样式。其段落为首行缩进2字符。 +- 找到“标题1”至“标题9”样式，依次修改。将颜色设置为自动。中文改为黑体，西文保持Times New Roman。字号依次为：三号，四号，小四（后面全是小四）。并删除所有倾斜和加粗。 +- 找到“标题”样式，它是除了正文标题以外的其它标题的基础格式。将字体中文改为黑体，西文改为Times New Roman。 +- 找到“题注”样式，它是“Image Caption”和“Table Caption”这两个样式的基础。对其进行修改。 + * 字体设置为黑体，字号为五号，并删除斜体样式。 + * 段落设置为居中。 +- 找到“Figure”样式，它决定了插入的图的样式。将其段落设置为居中，以让插入的图居中。 +- 找到“超链接”样式，删除其颜色。 +- 找到“书目”样式，它是参考文献列表所用的样式。 + * 字体设置为宋体，字号为五号。 + * 段落设置为悬挂缩进2字符。 +- 找到“脚注文本”样式。它是脚注文本的样式。 + * 字体的字号改为五号。 +- 点击文档中的表格，转到Ribbon栏的“表设计”选项卡下，点击表格样式右边的下拉箭头，选择“修改表格样式”。打开对话框。 + * 进入“边框和底纹”对话框，把上下框线加上，这样就实现了三线表。 + * 进入“表格属性”对话框设置 + - 把“表格”选项卡里的“对齐方式”设置为“居中”，让表格在段落中居中。 + - 把“行”选项卡里的“允许跨页断行选项”关掉，以保证表格美观。 + diff --git a/pandoc/my-thesis.docx b/pandoc/my-thesis.docx new file mode 100644 index 0000000..4fba830 Binary files /dev/null and b/pandoc/my-thesis.docx differ diff --git a/pandoc/pyproject.toml b/pandoc/pyproject.toml index 5adfb7e..0a2e8ec 100644 --- a/pandoc/pyproject.toml +++ b/pandoc/pyproject.toml @@ -5,5 +5,5 @@ description = "The environment used for converting LaTeX thesis into DOCX format readme = "README.md" requires-python = ">=3.11" dependencies = [ - "pandoc-tex-numbering>=1.3.3", + "pandoc-tex-numbering==1.3.3", ] diff --git a/pandoc/uv.lock b/pandoc/uv.lock index 6f452f4..c0d346b 100644 --- a/pandoc/uv.lock +++ b/pandoc/uv.lock @@ -45,7 +45,7 @@ dependencies = [ ] [package.metadata] -requires-dist = [{ name = "pandoc-tex-numbering", specifier = ">=1.3.3" }] +requires-dist = [{ name = "pandoc-tex-numbering", specifier = "==1.3.3" }] [[package]] name = "panflute" diff --git a/winword/README.md b/winword/README.md new file mode 100644 index 0000000..e69de29