重庆大学毕业论文 Markdown 转 Word (docx) 方案

重庆大学毕业论文 Markdown 转 Word (docx) 方案

这是一套使用 Markdown 书写重庆大学毕业论文，最终转换为符合重庆大学排版要求的 Word (docx) 文件的方案。

我们做的主要工作是：

使输出的 docx 文件符合重庆大学的排版要求
对 Markdown 语法进行若干必要的扩充以满足撰写毕业论文的需求
结合开发者自己的经验对 Markdown 加入了若干语法糖

详见 template/template.md 中的示例。

（pandoc_cqu_thesis 为该项目的程序部分）

注意！因为Markdown和Word的一些功能限制，该项目并不能完全实现Word中的所有功能！请自行判断使用风险。 另，模版的所有功能完全符合Word的排版规范，故可以在任何时候从该方案中跳出后直接修改输出的Word文件。

使用方法

安装 python （Python安装时请确保勾选了Add to Path选项以添加环境变量）和 pandoc
安装所需的 pandoc_cqu_thesis:
```
pip install pandoc_cqu_thesis
```
建议的工作环境：
- 使用VS Code做为写作软件，以下是一些推荐的VS Code扩展，用来提高写作舒适度
- 使用Markdown Preview Enhanced来预览markdown文件
- 使用Markdown Image来粘贴图片到Markdown文件中
- 使用markdown shortcuts，markdown all in one扩展来提供快捷键和其他的各种语法高亮等支持
- 使用Pancod Citer扩展来辅助参考文献的插入（可在插入参考文献时再来看所有和参考文献相关的内容）
- 所有建议的扩展都已写在template和MWE文件夹下的.vscode/extensions.json配置文件内
- 一些必要的配置参数已写在template和MWE文件夹下的.vscode/settings.json配置文件内
编译范例文档：该文档包含了所有的语法和使用方法，切换到本仓库 template 目录并进行编译：
- Windows: 运行 make.ps1
- *nix: 根据Makefile文件，执行 make 命令
自行撰写文档：文件夹MWE为最小工作范例，即在保证所有需要的内容的情况下，不包含任何多余内容。用户可自行复制该文件夹（或直接使用该文件夹）从头开始撰写文档，而不必到template/template.md文件中一边筛选其中的必要内容一边删除其中的文档。打开MWE/paper.md文件，而后在其中撰写内容，再运行make.ps1（*unix系统使用Makefile文件）编译即可。
编译完成后

范例文档生成 template.docx文件，其中列举了的该方案的各种用法，可对照md文件查看语法和效果。

自行撰写的文档生成paper.docx文件，即为用户需要的内容。

文档生成后，首次打开会提示“该文档引用了其他文件，是否更新”这样的警告，这是因为文档中的交叉引用（例如封面）会被Word识别成引用了别的文件，存在风险。此处应当选“是”来更新这些内容，否则目录等内容无法正常显示，保存一次之后就不会再出现该提示了。

还应当使用 Ctrl+A全选整个文档 -> F9 -> 更新整个目录 刷新某些交叉引用，例如图目录中的图片编号。

而对于页眉页脚而言，因为Word的设计缺陷，页眉页脚无法在上述过程中更新，因此建议执行一次导出PDF操作，来使Word完全刷新整个文档，所有内容即可正常显示。操作步骤为：文件 -> 导出 -> 创建 PDF/XPS -> 保存；或，直接另存为，文件类型选择PDF格式即可。

注意事项：

对于目录，因为目录中的各级标题中的字号不同，所以导致右侧的页码字号也不同，这不符合重庆大学的排版要求（详见“排版要求”中的“目录”相关部分），为了符合重庆大学对目录的格式要求，应当在输出Word并完成所有修订和检查之后，导入文件 AdjustTOC.bas中的宏到Word中，而后选中整个目录应用该宏，即可将目录的所有页码统一。
关于脚注上方的分隔线对齐问题（输出中的脚注横线会偏右），需要手动到草稿视图中（“视图”选项卡-->“草稿视图”），再打开“备注”（“引用”选项卡-->“显示备注”），然后在下方出现的备注面板中的“脚注”下拉菜单中选择“脚注分隔符”，用退格键删除前面的缩进（具体可自行百度“Word 脚注分隔线”）

Tips: 需要将论文分成多个文件的，可以在 make.ps1 或 Makefile 中的 template.md 处依次加入论文不同部分的文件。

文件/编译说明

template文件夹：本模版的范例文档（使用说明）
- .vscode文件夹：为VS Code提供的推荐设置
- figures文件夹：存储模版文件中使用到的图片，其中存储了封面中用到的重庆大学logo图片
- head.md文件：文档的配置参数
- cover_bachelor.md文件：本科生的封面
- template.md文件：范例文档的主文件
- refs.bib文件：bib格式的参考文献记录文件（插入参考文献的话，去论文网站上复制bib格式的参考文献记录到该文件中，而后在正文template.md文件中引用即可）
- china-national-standard-xxxx.csl文件：参考文献的样式文件，理科使用numeric.csl文件，文科使用author-date.csl文件
- reference.docx文件：控制输出文档格式的格式模版
- Table.docx文件：演示“插入外部的Word文件”时，用到的表格文件
- make.ps1，Makefile文件：Windows系统和 *nix系统下的编译文件，其中make.ps1中有一些配置参数，用户可以自行修改，例如是否每次编译完成后自动打开Word文件（编译之前记得先关闭输出的文档，否则会因为文件占用无法写入新的文档）
MWE文件夹：为让用户快速撰写新文档而提供的最小工作示例，直接编写里面的paper.md文件再编译即可；除删除了部分不需要的文件以外，与template文件夹无任何区别

故运行make.ps1后的编译流程为

make.ps1中的前部提供一些设定，例如是否自动打开生成的Word文件，使用的封面文件是哪个，要编译主的文件是哪个
pandoc依次拼接 head.md, cover_bachelor.md, 主文件template.md ，得到完整的文档
pandoc对完整文档进行读取和识别
pandoc将自己识别后的内容传递给上方使用方法中提到的Python插件pandoc_cqu_thesis进行处理
Python插件pandoc_cqu_thesis将自己处理完的内容再传回给pandoc
pandoc再使用自己的参考文献处理插件citeproc（编译命令中的--citeproc参数）处理参考文献
citeproc从refs.bib中读取每条参考文献的信息（标题，作者等），而后根据参考文献样式文件china-national-xxxx.csl文件中定义的参考文献的格式来生成最终看见的参考文献条目格式
到此，pandoc就得到了所有的文档内容，再根据格式模版文件reference.docx中定义的各种格式输出最终符合格式要求的Word文档

这也就串起了上面提到的所有必要文件

样式

reference.docx中，除了 pandoc 预设的那几个样式外，还定义了以下几种特殊样式

TOC Heading: 目录标题
Heading Numbering：标题的编号列表
Key Word：“关键字”的前缀字符样式
Equation：显示公式的样式，带有段前段后各一行，用来保证公式可以完整显示
Appendix Text: 附录正文样式
AppendixHeading2: 附录二级标题
AppendixHeading3: 附录三级标题
Definition: 定理环境的正文（pandoc自带段落样式）
Definition Preffix: 定理环境的前缀（文本样式）
Definition Title: 定理环境的标题（文本样式）
noindent：无首行缩进（段落样式）
EquationTable：给公式编号的表格

TODO

后面的内容有待整理，用户请直接忽略

命令定义

标题{-}：后面的{-}表示去掉某标题的编号，根据排版要求和实现方案，仅提供一级标题（适用于摘要，附录，参考文献）和二级标题（适用于附录内部的二级标题A,B等）
附录{- .appendix}：{}中的-表示去掉编号，.appendix表示该部分是目录。因为排版要求规定附录中的字号比正文小，所以需要单独标注出附录来为附录中的正文套用单独的附录样式（见样式章节）
- 实现原理：单独定义了未编号的一级标题和二级标题样式（见样式部分）
\Space{n}：生成n个空格，用来生成摘要中间的4个空格，n可为空
\KeyWord{关键词：}：产生名为“关键词：”的关键词前缀，可自定义
- 实现原理：对{}内的内容套用预设的Key Word文本样式
\toc{目录}：产生标题为目录的目录
\newSection{Content}和\newSection{TOC}：产生分节符，对应摘要后方的分节符和目录后方的分节符
- 实现原理：通过文本匹配替换，直接插入对应的ooxml代码
- 分节符的作用：控制分节符位置前方的页面的“页面参数”，例如纸张大小，分栏，仅在不同的“节”中才能生成不同样式的页眉页脚，所以为了实现不同的页眉页脚效果，必须插入分节符
\newLine{}：插入换行符，在不分段的情况下进入下一行（即Word中Shift + Enter的效果），可用来产生双语题注
- 实现原理：替换为ooxml代码或pandoc原生的LineBreak对象
\newPara{n}：生成n个空段落，用来产生一定的间距，参数可为空
- 要求只能在空段落中使用，即RawBlock，若和其他内容在同一段落，则会被解析成RawInline，造成错误
\newPage{}：插入分页符，跳转到下一页
\Caption2{fig}：插入双语题注的第二题注时，用该命令产生第二语言的编号前缀，例如中英题注中，默认会生成中文的题注编号图1.3，而英文题注的编号则须用该命令产生Fig 1.3
- 实现原理：预设第二题注的前缀，插入域代码生成编号
\Reference{}：在当前位置插入参考文献，因为排版要求规定附录在参考文献之后，而pandoc默认参考文献插入在文档最后，所以需要定义命令以在任意位置插入参考文献
- 通过插入ooxml代码实现
[被标记文本]{#书签名字}：可以对被标记文本标记一个名为书签名字的书签，通过书签和域代码配合，可以实现交叉引用。该功能为pandoc自带功能
## 123{#xxx}：可对标题进行标记书签，通过[@sec-xxx-no]可以引用标题的编号
`{some code}`{=field}：some code为域代码，{=field}表示把该部分内容作为域代码处理，通过该语法可以实现插入自定义域代码的功能
\includeDoc{xxx}：通过相对路径实现域代码{IncludeText xxx}的功能
~~\Style{name}：对当前段落应用name样式（特殊的内置样式名称可能不一样）~~
\metadata{}：从metadata中获取某个信息

第一阶段TODO

项目TODO

★拆分交叉引用的设定，使模块先具有通用性，并发布收集反馈
优化另一仓库中的readme，给出效果，拆分当前readme文件
重写交叉引用文档
拆分项目的更新日志到另一仓库

模版TODO

修改标题样式，使“段前段后”一行的效果与word匹配
允许在西文单词中间断字，以增强“超链接”的显示效果

代码TODO

可以单独实现

第二阶段TODO

项目TODO

兼容panbook的写法，借用其中的子图等写法
子图如何处理，能否提供接口实现按照页面比例创建表格而后插入图片？
```
![xxx]()
![xxx]()
![xxx]()
{30, 40, 30}
```

模版 TODO

表格图片前后一行
图片表格行距问题
- 段前段后空一行的行距问题
  - 强行提高倍数拉高？
  - 在代码中增加空行？

目录相关
- 索引
- 术语表
尾注（英语专业需要）
表格样式能否实现？？
- 普通表格的样式问题
- 简单的三线表能否通过套样式实现？
标题编号的制表符与目录的位置微调（更好看）（低优先级）

文档TODO

编写《给小白的排版指导》，根据同学的不好的排版文档给出相应的指导和正确写法
Word模版的文档，分两部分
- （本科检查不严格，全部按研究生办）
- 《给小白的Word排版思维指导》
  - 介绍排版思维，比如“样式”“分节符”
- 《模版使用说明》
  - 介绍模版是如何实现排版要求的
  - 具体做了哪些工作，如何排版出来
目前的template.md作为模块的使用说明如何？
- 记得写出交叉引用用的是自己的书签，而Word里用的是Word生成出来的标签

本科研究生的区别
- 目前按照研究生标准处理页眉字号（当本科是打错字了）
- 按研究生处理目录字体
- 按研究生处理编号字体
编写《pandoc的妙用》？？（暂不考虑，低优先级）
- 批量插入图片得到Word
  - 使用ls或者dir命令生成图片的路径，然后使用竖向的文本编辑生成图片格式插入到Markdown中转换

已知问题

公式会截断有序列表
在有首行缩进的情况下，某些情况下多级列表会错误缩进

表格目前无法合并单元格，等后期提issue然后pandoc更新
- 可以通过插入域代码引入外部Word文件实现{IncludeText xxxx}
对于列表嵌套配合正文样式缩进什么的效果之后可能看起来会很奇怪，但是没有办法调整pandoc自带的编号层级，所以目前无法实现
脚注中的代码块会使用正文的代码字号，无法使用不同的字号（要求脚注小五，实际代码块五号）
- 可以考虑定义脚注中的代码块样式，然后对其增加判断功能，目前暂不考虑
参考文献的英文多作者要求使用et al而非等，修改csl文件？
- 经查证，似乎csl语言不支持这样的写法，因为无法判断中文文献和英文文献的标准？

可以通过后处理脚本实现

脚注的分隔线和其他设置
- 脚注的分隔线缩进定义在footnotes.xml中，pandoc并不保留这个文件
- 这玩意无解，只能最后导出之后用户手动调整
- 一种思路是，在指定文件夹内保留相应的xml文件，处理完之后解压文档替换xml

许可证

本仓库除了 CQU论文排版要求文件夹的部分内容外，其他内容的许可证为 MIT.

ilcpm/cqu-thesis-markdown

重庆大学毕业论文 Markdown 转 Word (docx) 方案

使用方法

文件/编译说明

样式

命令定义

第一阶段TODO

项目TODO

模版TODO

代码TODO

第二阶段TODO

项目TODO

模版 TODO

文档TODO

已知问题

可以通过后处理脚本实现

许可证