A tool for rendering HUST graduation thesis(including master and bachelor) using pandoc and latex.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
example
src
template
.gitignore
README.md
gulpfile.js
package.json

README.md

HUST Graduation Thesis Pandoc

使用Pandoc Markdown和LaTeX写华中科技大学毕业论文(包括硕士论文和本科论文)。

用法

前置安装

  1. 安装最新版的Tex Live。 强烈建议下载ISO文件安装,这样只需要半个小时就能完成安装(网络安装可能需要一个多小时)。**最后请确保Tex Live的bin文件夹在PATH中。**测试:命令行执行xelatex -vlualatex -v可以正常显示版本。
    • 降级pgf:下载pgf v2.10,解压出tex/generic/pgf/utilities/pgfkeys.code.tex,替换掉Tex Live安装目录下<texlive path>/<texlive version>/texmf-dist/tex/generic/pgf/utilities的文件,具体原因参照这里第4个问题
  2. 安装最新版的Pandoc。测试:命令行执行pandoc -v可以正常显示版本。
  3. 安装最新版的Node.js。测试:命令行执行node -v可以正常显示版本。
  4. 安装必需的宋体、黑体、仿宋、楷体字体,可以从这里下载。
  5. 执行以下命令:
git clone https://github.com/raytaylorlin/hust-graduation-thesis-pandoc
cd hust-graduation-thesis-pandoc
npm install -g gulp
npm install

使用

  • src/文件夹下存放了多个文件夹,每个文件夹代表一个project也就是一篇论文,其中包含了生成一篇论文所需要的各种源文件。例如在src/thesis-simple/中,thesis.md为论文正文,ref.bib为引用的文献(使用bibtex,谷歌学术可以直接复制出bib格式的引用),figures/文件夹存放的是引用的图片。

  • 使用时可以从src/中任意一个示例项目复制一份出来,并重新命名,如mythesis(下面以这个项目名举例)

  • 论文标题、姓名、专业、导师等基本信息,请修改src/mythesis/info.tex

  • 论文摘要,请修改src/mythesis/abstract.tex

  • 致谢信息,请修改src/mythesis/thanks.tex

  • 编辑完之后,执行gulp --thesis mythesis命令即可构建pdf,生成的pdf存放于dist文件夹下。

    • --thesis参数可指定论文所在的项目目录,项目目录必须放在src/文件夹下
    • 注意:如果在系统中无法使用xelatex命令(现发现有同学单独运行xelatex无任何反应),可以尝试加入--lualatex参数来构建pdf(此方案编译会稍慢一些)
  • 论文类型(草稿/正式版、硕士/学士论文),请修改template/template.tex第1行的参数,具体请阅读原Latex模板说明文档

    format = <draft|final>:提交草稿选择draft 选项,提交最终版选final选项。其中草稿正文页包括页 眉(“华中科技大学 xx 学位论文”)、页眉修饰线(双线)、页脚(页码)和页脚 修饰线(单线)。而最终版正文页不包括页眉、页眉修饰线和页脚修饰线,仅包 含页脚(页码)。

    degree = <none|fyp|bachelor|master|phd> 指定论文种类,影响中英文封面处的标题和正文处的页眉(如果format设为draft)。

  • 插入一大段代码,使用\begin{lstlisting}[language=javascript]\end{lstlisting}将你的代码段包围起来,请不要使用md的三引号语法。详情参见src/thesis-simple/thesis.md中代码段的写法。

说明

致谢

感谢@pyrocat101成为使用markdown写毕业论文的先驱者,本项目参考了其hust-thesis-pandoc

感谢@xu-cheng提供的华中科技大学毕业论文Latex模板,本项目将其模板解包之后进行略微的修改而成。

原理

本项目旨在让各位毕业生能够脱离用Word编辑论文及其格式的苦海,用优雅的markdown专注于论文的写作。**注意:为了应对论文内容的多样化,本项目使用Pandoc Markdown来写作,这是一种增强版的markdown,具体请参见官方文档。**然后用Pandoc将.md转换成.tex,最后用xelatex命令行工具将.tex转换为最终的.pdf

本项目使用gulp来自动构建最终的pdf,其流程由多个gulp任务完成。实际所有编译工作均发生在临时目录temp/下。流程说明如下:

  1. (用户先编辑src/文件夹下的md文档、bib文献引用、图片等等)
  2. gulp pandoc-parts:pandoc将论文的组成部分(如abstract、thanks等).md编译成相应的.tex
  3. gulp pandoc-thesis:pandoc将正文thesis.md,结合template/template.tex和上一步生成的.tex,生成thesis.tex
  4. gulp copy-template:将编译latex所需的.cls类文件,华科标题图片等模板文件复制到temp
  5. gulp copy-src:将编译latex所需的.bib和图片复制到temp
  6. gulp pdf:进入到temp文件夹,依次调用xelatex thesisbibtex thesisxelatex thesisxelatex thesis,生成thesis.pdf(至于为什么要反复调用同一个xelatex命令,请参见这里
  7. gulp copy-pdf:将编译完的pdf复制到dist目录下

报错解决

TODO

  • Error: EBUSY: resource busy or locked, open 'XXX/XXX/dist/thesis.pdf':thesis.pdf文件处于打开状态,文件无法写入,请关闭后重新执行gulp

测试环境

  • Windows 8.1
  • Node.js v5.2.0
  • pandoc 1.15.2
  • XeTeX 3.14159265-2.6-0.99992 / BibTeX 0.99d (TeX Live 2015/W32TeX)

由于环境限制,我没有在Mac或Linux下测过,希望有志同道合的人能帮我测试一下,有问题欢迎给我issue或者pull request,谢谢。

声明

由于之前实验室几乎没有人用Latex写过毕业论文,更没有人用markdown来写过论文,所以本项目目前仍处于试验期,我会在写毕业论文期间不断维护这个项目。但如果最终由于技(zhuang)术(bi)问(shi)题(bai)无法解决,导致不能生成最终可以提交给学校的论文,还请大家见谅。(也就是最终只能将内容一一复制到word中)

本人不会Latex,无法提供论文格式上微调的帮助,如果有需要还请各位自行解决。我相信@xu-cheng提供的华中科技大学毕业论文Latex模板应该是久经考验的,应该也不用怎么调。

本项目目前只能生成pdf,至于硕士论文盲审要不要用word的问题,后面我再看看能不能转word。现在至少本科生可以用得上=。=

TODO

  • 制作论文通用工具:拍平markdown文件以得到纯文本,便于查重
  • 制作论文通用工具:按论文引用的顺序排序bibtex
  • 目前图片宽度一旦超过500px就会超出页面范围,应让图片宽度自适应
  • 构建报错时可以显示更加具体的错误信息

更新日志

  • v0.6.0: 新增对Javascript代码的高亮显示支持
  • v0.5.0: 新增project概念,现在一个文件夹表示一个project,对应一篇论文,可以由--thesis参数来指定一个文件夹。(原--thesis参数的含义已弃用)
  • v0.4.2:修复最新版的Pandoc v1.15.2,在生成列表时改用了命令\tightlist而产生编译错误的问题
  • v0.4.1:给pandoc-thesis任务添加报错判断信息,并增加对temp文件夹是否存在的判断
  • v0.4.0:增加``--lualatex`选项,以备在无法使用xelatex编译的情况下用lualatex编译
  • v0.3.1:修复图片比较大时超出页面宽度的问题
  • v0.3.0:新增ELWG专用论文example,gulp脚本新增--thesis参数
  • v0.2.0:将论文模板template.tex中基本信息、摘要和致谢部分拆分成独立的文件
  • v0.1.0:发布第一版,可以使用gulp来自动构建论文,生成pdf

License

MIT License