如何使用 Pandoc 撰写研究论文

了解如何在 Markdown 中管理章节引用、图表、表格等。
315 位读者喜欢这篇文章。
Green paperclips
图片来源

公共领域的原始图片。 Jason Baker 修改。 CC BY-SA 4.0。

本文深入探讨如何使用（主要是）Markdown 语法撰写研究论文。我们将介绍如何创建和引用章节、图表（在 Markdown 和 LaTeX 中）和参考文献。我们还将讨论一些棘手的情况，以及为什么使用 LaTeX 编写是正确的方法。

研究

研究论文通常包含对章节、图表、表格和参考文献的引用。Pandoc 本身不能轻易地交叉引用这些，但它可以利用 pandoc-crossref 过滤器来实现章节、图表和表格的自动编号和交叉引用。

让我们从重写 一篇教育研究论文的示例 开始，该论文最初是用 LaTeX 编写的，现在使用 Pandoc 和 pandoc-crossref 以 Markdown（和一些 LaTeX）重写。

添加和引用章节

章节会自动编号，并且必须使用 Markdown 标题 H1 编写。子章节使用子标题 H2-H4 编写（通常不需要更多）。例如，要编写一个标题为“Implementation”的章节，请编写 # Implementation {#sec:implementation}，Pandoc 会生成 3. Implementation（或相应的编号章节）。标题“Implementation”使用标题 H1 并声明了一个标签 {#sec:implementation}，作者可以使用该标签来引用该章节。要引用一个章节，请输入 @ 符号，后跟章节的标签，并用方括号括起来：[@sec:implementation]。

在这篇论文中，我们找到了以下示例

we lack experience (consistency between TAs, [@sec:implementation]).

Pandoc 生成

we lack experience (consistency between TAs, Section 4).

章节会自动编号（这将在文章末尾的 Makefile 中介绍）。要创建未编号的章节，请输入章节的标题，后跟 {-}。例如，### Designing a game for maintainability {-} 创建一个标题为“Designing a game for maintainability”的未编号子章节。

添加和引用图表

添加和引用图表类似于引用章节和添加 Markdown 图像

![Scatterplot matrix](data/scatterplots/RScatterplotMatrix2.png){#fig:scatter-matrix}

上面这行代码告诉 Pandoc，这里有一个图表，标题为Scatterplot matrix，图像的路径为 data/scatterplots/RScatterplotMatrix2.png。{#fig:scatter-matrix} 声明了用于引用该图表的名称。

这是一个来自示例论文的图表引用的示例

The boxes "Enjoy", "Grade" and "Motivation" ([@fig:scatter-matrix]) ...

Pandoc 生成以下输出

The boxes "Enjoy", "Grade" and "Motivation" (Fig. 1) ...

添加和引用参考文献

大多数研究论文将参考文献保存在 BibTeX 数据库文件中。在本例中，该文件名为 biblio.bib，其中包含论文的所有参考文献。以下是该文件的外观

@inproceedings{wrigstad2017mastery,
    Author =       {Wrigstad, Tobias and Castegren, Elias},
    Booktitle =    {SPLASH-E},
    Title =        {Mastery Learning-Like Teaching with Achievements},
    Year =         2017
}

@inproceedings{review-gamification-framework,
  Author =       {A. Mora and D. Riera and C. Gonzalez and J. Arnedo-Moreno},
  Publisher =    {IEEE},
  Booktitle =    {2015 7th International Conference on Games and Virtual Worlds
                  for Serious Applications (VS-Games)},
  Doi =          {10.1109/VS-GAMES.2015.7295760},
  Keywords =     {formal specification;serious games (computing);design
                  framework;formal design process;game components;game design
                  elements;gamification design frameworks;gamification-based
                  solutions;Bibliographies;Context;Design
                  methodology;Ethics;Games;Proposals},
  Month =        {Sept},
  Pages =        {1-8},
  Title =        {A Literature Review of Gamification Design Frameworks},
  Year =         2015,
  Bdsk-Url-1 =   {http://dx.doi.org/10.1109/VS-GAMES.2015.7295760}
}

...

第一行 @inproceedings{wrigstad2017mastery, 声明了出版物类型 (inproceedings) 和用于引用该论文的标签 (wrigstad2017mastery)。

要引用标题为Mastery Learning-Like Teaching with Achievements的论文，请输入

the achievement-driven learning methodology [@wrigstad2017mastery]

Pandoc 将输出

the achievement- driven learning methodology [30]

我们将生成的论文包含一个参考文献章节，其中包含如下编号的参考文献

bibliography-numbered examples.png

引用文章集合很容易：只需引用每篇文章，使用分号 ; 分隔标记的参考文献。如果有两个标记的参考文献——例如 SEABORN201514 和 gamification-leaderboard-benefits——将它们一起引用，如下所示

Thus, the most important benefit is its potential to increase students' motivation
and engagement [@SEABORN201514;@gamification-leaderboard-benefits].

Pandoc 将生成

Thus, the most important benefit is its potential to increase students’ motivation
and engagement [26, 28]

问题案例

一个常见的问题涉及无法放入页面的对象。它们会浮动到最适合的位置，即使该位置不是读者期望看到的位置。由于当图表或表格出现在它们被提及的位置附近时，论文更容易阅读，因此我们需要对这些元素的位置进行一些控制。因此，我建议使用 figure LaTeX 环境，这使使用者能够控制图表的位置。

让我们以上面显示的图表示例为例

![Scatterplot matrix](data/scatterplots/RScatterplotMatrix2.png){#fig:scatter-matrix}

并在 LaTeX 中重写它

\begin{figure}[t]
\includegraphics{data/scatterplots/RScatterplotMatrix2.png}
\caption{\label{fig:matrix}Scatterplot matrix}
\end{figure}

在 LaTeX 中，figure 环境中的 [t] 选项声明图像应放置在页面顶部。有关更多选项，请参阅 Wikibooks 文章 LaTex/浮动体、图表和标题。

生成论文

到目前为止，我们已经介绍了如何添加和引用（子）章节和图表，以及引用参考文献——现在让我们回顾一下如何以 PDF 格式生成研究论文。为了生成 PDF，我们将使用 Pandoc 生成一个 LaTeX 文件，该文件可以编译成最终的 PDF。我们还将讨论如何使用自定义模板和元信息文件在 LaTeX 中生成研究论文，以及如何将 LaTeX 文档编译成最终的 PDF 格式。

大多数会议都提供一个 .cls 文件或模板，用于指定论文的外观；例如，它们是否应使用双栏格式和其他设计处理。在我们的示例中，会议提供了一个名为 acmart.cls 的文件。

通常期望作者在其论文中包含其所属机构。但是，默认的 Pandoc LaTeX 模板中未包含此选项（请注意，可以通过键入 pandoc -D latex 来检查 Pandoc 模板）。要包含单位，请获取默认的 Pandoc LaTeX 模板并添加一个新字段。Pandoc 模板被复制到一个名为 mytemplate.tex 的文件中，如下所示

pandoc -D latex > mytemplate.tex

默认模板包含以下代码

$if(author)$
\author{$for(author)$$author$$sep$ \and $endfor$}
$endif$
$if(institute)$
\providecommand{\institute}[1]{}
\institute{$for(institute)$$institute$$sep$ \and $endfor$}
$endif$

由于模板应包含作者的单位和电子邮件地址等信息，因此我们对其进行了更新以包含这些字段（我们也进行了其他更改，但由于文件长度，此处未包含）。

latex
$for(author)$
    $if(author.name)$
        \author{$author.name$}
        $if(author.affiliation)$
            \affiliation{\institution{$author.affiliation$}}
        $endif$
        $if(author.email)$
            \email{$author.email$}
        $endif$
    $else$
        $author$
    $endif$
$endfor$

完成这些更改后，我们应该有以下文件

  • main.md 包含研究论文
  • biblio.bib 包含书目数据库
  • acmart.cls 是我们应该使用的文档类
  • mytemplate.tex 是要使用的模板文件（代替默认模板）

让我们在 meta.yaml 文件中添加论文的元信息

---
template: 'mytemplate.tex'
documentclass: acmart
classoption: sigconf
title: The impact of opt-in gamification on `\\`{=latex} students' grades in a software design course
author:
- name: Kiko Fernandez-Reyes
  affiliation: Uppsala University
  email: kiko.fernandez@it.uu.se
- name: Dave Clarke
  affiliation: Uppsala University
  email: dave.clarke@it.uu.se
- name: Janina Hornbach
  affiliation: Uppsala University
  email: janina.hornbach@fek.uu.se
bibliography: biblio.bib
abstract: |
  An achievement-driven methodology strives to give students more control over their learning with enough flexibility to engage them in deeper learning. (more stuff continues)

include-before: |
  ```{=latex}
  \copyrightyear{2018}
  \acmYear{2018}
  \setcopyright{acmlicensed}
  \acmConference[MODELS '18 Companion]{ACM/IEEE 21th International Conference on Model Driven Engineering Languages and Systems}{October 14--19, 2018}{Copenhagen, Denmark}
  \acmBooktitle{ACM/IEEE 21th International Conference on Model Driven Engineering Languages and Systems (MODELS '18 Companion), October 14--19, 2018, Copenhagen, Denmark}
  \acmPrice{XX.XX}
  \acmDOI{10.1145/3270112.3270118}
  \acmISBN{978-1-4503-5965-8/18/10}

  \begin{CCSXML}
  <ccs2012>
  <concept>
  <concept_id>10010405.10010489</concept_id>
  <concept_desc>Applied computing~Education</concept_desc>
  <concept_significance>500</concept_significance>
  </concept>
  </ccs2012>
  \end{CCSXML}

  \ccsdesc[500]{Applied computing~Education}

  \keywords{gamification, education, software design, UML}
  ```
figPrefix:
  - "Fig."
  - "Figs."
secPrefix:
  - "Section"
  - "Sections"
...

此元信息文件在 LaTeX 中设置以下变量

  • template 指的是要使用的模板 ('mytemplate.tex')
  • documentclass 指的是要使用的 LaTeX 文档类 (acmart)
  • classoption 指的是类的选项，在本例中为 sigconf
  • title 指定论文的标题
  • author 是一个包含其他字段的对象，例如 name、affiliation 和 email。
  • bibliography 指的是包含书目的文件 (biblio.bib)
  • abstract 包含论文的摘要
  • include-before 是应包含在论文实际内容之前的信息；这在 LaTeX 中被称为 序言。我在此处包含它是为了展示如何生成计算机科学论文，但您可以选择跳过它
  • figPrefix 指定如何在文档中引用图表，即，当引用图表 [@fig:scatter-matrix] 时应显示什么。例如，当前的 figPrefix 在示例 The boxes "Enjoy", "Grade" and "Motivation" ([@fig:scatter-matrix]) 中生成此输出：The boxes "Enjoy", "Grade" and "Motivation" (Fig. 3)。如果有多个图表，当前设置声明它应该改为在图表编号旁边显示 Figs.。
  • secPrefix 指定如何在文档的其他位置引用章节（类似于上面描述的图表）

现在元信息已设置，让我们创建一个 Makefile 来生成所需的输出。此 Makefile 使用 Pandoc 生成 LaTeX 文件，pandoc-crossref 生成交叉引用，pdflatex 将 LaTeX 编译为 PDF，以及 bibtex 处理参考文献。

Makefile 如下所示

all: paper

paper:
	@pandoc -s -F pandoc-crossref --natbib meta.yaml --template=mytemplate.tex -N \
	 -f markdown -t latex+raw_tex+tex_math_dollars+citations -o main.tex main.md
	@pdflatex main.tex &> /dev/null
	@bibtex main &> /dev/null
	@pdflatex main.tex &> /dev/null
	@pdflatex main.tex &> /dev/null

clean:
	rm main.aux main.tex main.log main.bbl main.blg main.out

.PHONY: all clean paper

Pandoc 使用以下标志

  • -s 创建独立的 LaTeX 文档
  • -F pandoc-crossref 使用过滤器 pandoc-crossref
  • --natbib 使用 natbib 渲染参考文献（您也可以选择 --biblatex）
  • --template 设置要使用的模板文件
  • -N 对章节标题进行编号
  • -f 和 -t 指定从哪个格式到哪个格式的转换。-t 通常包含格式，后跟使用的 Pandoc 扩展。在示例中，我们声明了 raw_tex+tex_math_dollars+citations 以允许在 Markdown 文件中间使用 raw_tex LaTeX。tex_math_dollars 使我们能够像在 LaTeX 中一样键入数学公式，citations 使我们能够使用 此扩展。

要从 LaTeX 生成 PDF，请按照 bibtex 中的指南处理参考文献

@pdflatex main.tex &> /dev/null
@bibtex main &> /dev/null
@pdflatex main.tex &> /dev/null
@pdflatex main.tex &> /dev/null

脚本包含 @ 以忽略输出，我们将标准输出和错误的文件句柄重定向到 /dev/null，这样我们就不会看到执行这些命令生成的输出。

最终结果如下所示。可以在 GitHub 上找到本文的存储库

abstract-image.png

结论

在我看来，研究就是关于协作、传播思想以及改进任何特定领域的现有技术水平。大多数计算机科学家和工程师使用 LaTeX 文档系统编写论文，该系统为数学提供了出色的支持。社会科学研究人员似乎坚持使用 DOCX 文档。

当来自不同社区的研究人员一起撰写论文时，他们应首先讨论他们将使用的格式。虽然 DOCX 对于涉及数学的工程师来说可能不方便，但 LaTeX 对于缺乏编程背景的研究人员来说可能很麻烦。正如本文所示，Markdown 是一种易于使用的语言，工程师和社会科学家都可以使用。

标签
教育
Kiko Fernandez-Reyes
User profile image.
Kiko 是编程语言专业的博士生，也是乌普萨拉大学高级软件设计课程的主要讲师。他还是 Encore 编程语言的核心开发人员，撰写了关于并发和并行数据结构的研究出版物，并在他短暂的学术生涯中获得了两项最佳论文奖和两项杰出成果奖。
更多关于我

3 条评论

Avatar
craig | 2018 年 11 月 30 日
还没有读者喜欢这篇文章。

希望其中一些内容能帮助我。我目前正在尝试用 pandoc 和 LaTeX 替换 InDesign，以制作可下载且美观的类 Linux 教程。

Avatar
der.hans | 2018 年 12 月 29 日
还没有读者喜欢这篇文章。

感谢 Pandoc 文章。我学到了一些有用的东西。

在本文中，我注意到一个错别字。

“originally written in LaTeX and rewrites it in Markdown”

s/rewrites/rewrite/

相关内容

知识共享许可协议本作品根据知识共享署名-相同方式共享 4.0 国际许可协议获得许可。
© . All rights reserved.