document/TranslateProject
2
0
Fork 0
mirror of https://github.com/LCTT/TranslateProject.git synced 2025-02-25 00:50:15 +08:00
Code Issues Packages Projects Releases Wiki Activity

PRF:20181019 How to use Pandoc to produce a research paper.md

Browse Source 
@dianbanjiu
This commit is contained in:
Xingyu.Wang 2018-11-01 13:04:43 +08:00
parent ce1e9bbda3
commit 338ef3f318
1 changed files with 86 additions and 90 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

158
translated/tech/20181019 How to use Pandoc to produce a research paper.md
View File

@ -1,19 +1,21 @@
用 Pandoc 做一篇调研论文 用 Pandoc 生成一篇调研论文
====== ======
学习如何用 Markdown 管理引用、图像、表格、以及更多。
> 学习如何用 Markdown 管理章节引用、图像、表格以及更多。
![](https://opensource.com/sites/default/files/styles/image-full-size/public/lead-images/life_paperclips.png?itok=j48op49T) ![](https://opensource.com/sites/default/files/styles/image-full-size/public/lead-images/life_paperclips.png?itok=j48op49T)
这篇文章对于使用 [Markdown][1] 语法做一篇调研论文进行了一个深度体验。覆盖了如何创建和引用、图像（用 Markdown 和 [LaTeX][2]）和参考书目。我们也讨论了一些棘手的案例和为什么使用 LaTex 是一个正确的做法。 这篇文章对于使用 [Markdown][1] 语法做一篇调研论文进行了一个深度体验。覆盖了如何创建和引用章节、图像（用 Markdown 和 [LaTeX][2]）和参考书目。我们也讨论了一些棘手的案例和为什么使用 LaTex 是一个正确的做法。
### 调查 ### 调研
调研论文一般包括引用、图像、表格和参考书目。[Pandoc][3] 本身并不能交叉引用这些，但是但是它能够利用 [pandoc-crossref][4] 过滤来完成自动编号和章节、图像、表格的交叉引用。 调研论文一般包括对章节、图像、表格和参考书目的引用。[Pandoc][3] 本身并不能交叉引用这些，但是它能够利用 [pandoc-crossref][4] 过滤器来完成自动编号和章节、图像、表格的交叉引用。
让我们开始正常的使用 LaTax 重写 [一个教育调研报告的例子][5]，然后用 Markdown（和一些 LaTax）、Pandoc 和 Pandoc-crossref 再重写。 让我们从重写原本以 LaTax 撰写的 [一个教育调研报告的例子][5] 开始，然后用 Markdown（和一些 LaTax）、Pandoc 和 Pandoc-crossref 重写。
#### 添加并引用章节 #### 添加并引用章节
要想章节被自动编号，必须使用 Markdown 标题 H1 编写。子章节使用子标题 H2-H4 编写（通常不需要更多的东西）。例如一个章节的标题是 “履行”，写作 `# 履行 {#sec: 履行}`，然后 Pandoc 会把它转化为 `3. 履行`（或者转换为相应的章节标号）。`履行` 这个标题使用了 H1 并且声明了一个 `{#sec: 履行}` 的标签，这是作者引用了该章节的标签。要想引用一个章节，在对应章节后面输入 `@` 符号并使用方括号括起来即可： `[@sec:履行]` 要想章节被自动编号，必须使用 Markdown H1 标题编写。子章节使用 H2-H4 子标题编写（通常不需要更多级别了）。例如一个章节的标题是 “Implementation”，写作 `# Implementation {#sec: implementation}`，然后 Pandoc 会把它转化为 `3. Implementation `（或者转换为相应的章节编号）。`Implementation` 这个标题使用了 H1 并且声明了一个 `{#sec: implementation}` 的标签，这是作者用于引用该章节的标签。要想引用一个章节，输入 `@` 符号并跟上对应章节标签，使用方括号括起来即可： `[@ sec:implementation]`
[在这篇论文中][5], 我们发现了下面这个例子： [在这篇论文中][5], 我们发现了下面这个例子：
@ -27,7 +29,7 @@ Pandoc 转换：
we lack experience (consistency between TAs, Section 4). we lack experience (consistency between TAs, Section 4).
``` ```
章节被自动（这包含在文章最后的 `Makefile` 当中）标号。要创建无标号的章节，输入章节的标题并在最后添加 `{-}`。例如：`### 设计一个可维护的游戏 {-}` 就以标题 “设计一个可维护的游戏”，创建了一个无标号的章节。 章节被自动编号（这在本文最后的 `Makefile` 当中说明）。要创建无编号的章节，输入章节的标题并在最后添加 `{-}`。例如：`### Designing a game for maintainability {-}` 就以标题 “Designing a game for maintainability”，创建了一个无标号的章节。
#### 添加并引用图像 #### 添加并引用图像
@ -36,7 +38,8 @@ we lack experience (consistency between TAs, Section 4).
``` ```
![Scatterplot matrix](data/scatterplots/RScatterplotMatrix2.png){#fig:scatter-matrix} ![Scatterplot matrix](data/scatterplots/RScatterplotMatrix2.png){#fig:scatter-matrix}
``` ```
上面这一行是告诉 Pandoc，有一个标有 Scatterplot matrix 的图像以及这张图片路径是 `data/scatterplots/RScatterplotMatrix2.png`。`{#fig:scatter-matrix}` 表明了应该引用的图像的名字。
上面这一行是告诉 Pandoc，有一个标有 Scatterplot matrix 的图像以及这张图片路径是 `data/scatterplots/RScatterplotMatrix2.png`。`{#fig:scatter-matrix}` 表明了用于引用该图像的名字。
这里是从一篇论文中进行图像引用的例子： 这里是从一篇论文中进行图像引用的例子：
@ -51,46 +54,47 @@ The boxes "Enjoy", "Grade" and "Motivation" (Fig. 1) ...
``` ```
#### 添加及引用参考书目 #### 添加及引用参考书目
大多数调研报告都把引用放在一个 BibTeX 的数据库文件中。在这个例子中，该文件被命名为 [biblio.bib][6]，它包含了论文中所有的引用。下面是这个文件的样子： 大多数调研报告都把引用放在一个 BibTeX 的数据库文件中。在这个例子中，该文件被命名为 [biblio.bib][6]，它包含了论文中所有的引用。下面是这个文件的样子：
``` ```
@inproceedings{wrigstad2017mastery, @inproceedings{wrigstad2017mastery,
    Author =       {Wrigstad, Tobias and Castegren, Elias}, Author = {Wrigstad, Tobias and Castegren, Elias},
    Booktitle =    {SPLASH-E}, Booktitle = {SPLASH-E},
    Title =        {Mastery Learning-Like Teaching with Achievements}, Title = {Mastery Learning-Like Teaching with Achievements},
    Year =         2017 Year = 2017
} }
@inproceedings{review-gamification-framework, @inproceedings{review-gamification-framework,
  Author =       {A. Mora and D. Riera and C. Gonzalez and J. Arnedo-Moreno}, Author = {A. Mora and D. Riera and C. Gonzalez and J. Arnedo-Moreno},
  Publisher =    {IEEE}, Publisher = {IEEE},
  Booktitle =    {2015 7th International Conference on Games and Virtual Worlds Booktitle = {2015 7th International Conference on Games and Virtual Worlds
                  for Serious Applications (VS-Games)}, for Serious Applications (VS-Games)},
  Doi =          {10.1109/VS-GAMES.2015.7295760}, Doi = {10.1109/VS-GAMES.2015.7295760},
  Keywords =     {formal specification;serious games (computing);design Keywords = {formal specification;serious games (computing);design
                  framework;formal design process;game components;game design framework;formal design process;game components;game design
                  elements;gamification design frameworks;gamification-based elements;gamification design frameworks;gamification-based
                  solutions;Bibliographies;Context;Design solutions;Bibliographies;Context;Design
                  methodology;Ethics;Games;Proposals}, methodology;Ethics;Games;Proposals},
  Month =        {Sept}, Month = {Sept},
  Pages =        {1-8}, Pages = {1-8},
  Title =        {A Literature Review of Gamification Design Frameworks}, Title = {A Literature Review of Gamification Design Frameworks},
  Year =         2015, Year = 2015,
  Bdsk-Url-1 =   {http://dx.doi.org/10.1109/VS-GAMES.2015.7295760} Bdsk-Url-1 = {http://dx.doi.org/10.1109/VS-GAMES.2015.7295760}
} }
... ...
``` ```
第一行的 `@inproceedings{wrigstad2017mastery,` 表明了出版物 (`inproceedings`) 的类型，以及用来指向那篇论文 (`wrigstad2017mastery`) 的标签。 第一行的 `@inproceedings{wrigstad2017mastery,` 表明了出版物 的类型（`inproceedings`），以及用来指向那篇论文的标签（`wrigstad2017mastery`）。
引用这篇题为 “Mastery Learning-Like Teaching with Achievements” 的论文, 输入: 引用这篇题为 “Mastery Learning-Like Teaching with Achievements” 的论文, 输入：
``` ```
the achievement-driven learning methodology [@wrigstad2017mastery] the achievement-driven learning methodology [@wrigstad2017mastery]
``` ```
Pandoc 将会输出: Pandoc 将会输出：
``` ```
the achievement- driven learning methodology [30] the achievement- driven learning methodology [30]
@ -104,21 +108,19 @@ the achievement- driven learning methodology [30]
``` ```
Thus, the most important benefit is its potential to increase students' motivation Thus, the most important benefit is its potential to increase students' motivation
and engagement [@SEABORN201514;@gamification-leaderboard-benefits]. and engagement [@SEABORN201514;@gamification-leaderboard-benefits].
``` ```
Pandoc 将会产生: Pandoc 将会产生：
``` ```
Thus, the most important benefit is its potential to increase students’ motivation Thus, the most important benefit is its potential to increase students’ motivation
and engagement [26, 28] and engagement [26, 28]
``` ```
### 问题案例 ### 问题案例
一个常见的问题是项目与页面不匹配。不匹配的部分会自动移动到它们认为合适的地方，即便这些位置并不是读者期望看到的位置。因此在图像或者表格接近于它们被提及的地方时，我们需要调节一下它们在此处的元素组合，使得他们更加易于阅读。为了达到这个效果，我建议使用 `figure` 这个 LaTeX 环境参数，它可以让用户控制图像的位置。 一个常见的问题是所需项目与页面不匹配。不匹配的部分会自动移动到它们认为合适的地方，即便这些位置并不是读者期望看到的位置。因此在图像或者表格接近于它们被提及的地方时，我们需要调节一下那些元素放置的位置，使得它们更加易于阅读。为了达到这个效果，我建议使用 `figure` 这个 LaTeX 环境参数，它可以让用户控制图像的位置。
我们看一个上面提到的图像的例子： 我们看一个上面提到的图像的例子：
@ -139,9 +141,9 @@ and engagement [26, 28]
### 产生一篇论文 ### 产生一篇论文
到目前为止，我们讲了如何添加和引用（子）章节、图像和参考书目，现在让我们重温一下如何生产一篇 PDF 格式的论文，生成 PDF，我们将使用 Pandoc 生成一篇可以被构建成最终 PDF 的 LaTeX 文件。我们还会讨论如何以 LaTeX，使用一套自定义的模板和元信息文件生成一篇调研论文，以及如何构建 LaTeX 文档为最终的 PDF 格式。 到目前为止，我们讲了如何添加和引用（子）章节、图像和参考书目，现在让我们重温一下如何生成一篇 PDF 格式的论文。要生成 PDF，我们将使用 Pandoc 生成一篇可以被构建成最终 PDF 的 LaTeX 文件。我们还会讨论如何以 LaTeX，使用一套自定义的模板和元信息文件生成一篇调研论文，以及如何将 LaTeX 文档编译为最终的 PDF 格式。
很多会议都提供了一个 **.cls** 文件或者一套论文该有样子的模板; 例如，他们是否应该使用两列的格式以及其他的设计风格。在我们的例子中，会议提供了一个名为 **acmart.cls** 的文件。 很多会议都提供了一个 .cls 文件或者一套论文应有样式的模板；例如，它们是否应该使用两列的格式以及其它的设计风格。在我们的例子中，会议提供了一个名为 `acmart.cls` 的文件。
作者通常想要在他们的论文中包含他们所属的机构，然而，这个选项并没有包含在默认的 Pandoc 的 LaTeX 模板（注意，可以通过输入 `pandoc -D latex` 来查看 Pandoc 模板）当中。要包含这个内容，找一个 Pandoc 默认的 LaTeX 模板，并添加一些新的内容。将这个模板像下面这样复制进一个名为 `mytemplate.tex` 的文件中： 作者通常想要在他们的论文中包含他们所属的机构，然而，这个选项并没有包含在默认的 Pandoc 的 LaTeX 模板（注意，可以通过输入 `pandoc -D latex` 来查看 Pandoc 模板）当中。要包含这个内容，找一个 Pandoc 默认的 LaTeX 模板，并添加一些新的内容。将这个模板像下面这样复制进一个名为 `mytemplate.tex` 的文件中：
@ -161,32 +163,30 @@ $if(institute)$
$endif$ $endif$
``` ```
因为这个模板应该包含作者的联系方式和电子邮件地址，在其他一些选项之间，我们可以添加以下内容（我们还做了一些其他的更改，但是因为文件的长度，就没有包含在此处）更新这个模板 因为这个模板应该包含作者的联系方式和电子邮件地址，在其他一些选项之间，我们更新这个模板以添加以下内容（我们还做了一些其他的更改，但是因为文件的长度，就没有包含在此处）：
``` ```
latex latex
$for(author)$ $for(author)$
    $if(author.name)$ $if(author.name)$
        \author{$author.name$} \author{$author.name$}
        $if(author.affiliation)$ $if(author.affiliation)$
            \affiliation{\institution{$author.affiliation$}} \affiliation{\institution{$author.affiliation$}}
        $endif$ $endif$
        $if(author.email)$ $if(author.email)$
            \email{$author.email$} \email{$author.email$}
        $endif$ $endif$
    $else$ $else$
        $author$ $author$
    $endif$ $endif$
$endfor$ $endfor$
``` ```
要让这些更改起作用，我们还应该有下面的文件： 要让这些更改起作用，我们还应该有下面的文件：
* `main.md` 包含调研论文 * `main.md` 包含调研论文
* `biblio.bib` 包含参考书目数据库 * `biblio.bib` 包含参考书目数据库
* `acmart.cls` 我们使用的文档的集合 * `acmart.cls` 我们使用的文档的集合
* `mytemplate.tex` 是我们使用的模板文件（代替默认的） * `mytemplate.tex` 是我们使用的模板文件（代替默认的）
让我们添加论文的元信息到一个 `meta.yaml` 文件： 让我们添加论文的元信息到一个 `meta.yaml` 文件：
@ -211,7 +211,7 @@ 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)   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: | include-before: |
  \```{=latex}   \` ``{=latex}
  \copyrightyear{2018}   \copyrightyear{2018}
  \acmYear{2018}   \acmYear{2018}
  \setcopyright{acmlicensed}   \setcopyright{acmlicensed}
@ -234,7 +234,7 @@ include-before: |
  \ccsdesc[500]{Applied computing~Education}   \ccsdesc[500]{Applied computing~Education}
  \keywords{gamification, education, software design, UML}   \keywords{gamification, education, software design, UML}
  \```   \` ``
figPrefix: figPrefix:
  - "Fig."   - "Fig."
  - "Figs."   - "Figs."
@ -246,18 +246,16 @@ secPrefix:
这个元信息文件使用 LaTeX 设置下列参数： 这个元信息文件使用 LaTeX 设置下列参数：
* `template` 指向使用的模板（’mytemplate.tex‘） * `template` 指向使用的模板（`mytemplate.tex`）
* `documentclass` 指向使用的 LaTeX 文档集合 (`acmart`) * `documentclass` 指向使用的 LaTeX 文档集合（`acmart`）
* `classoption` 是在 `sigconf` 的案例中，指向这个类的选项 * `classoption` 是在 `sigconf` 的案例中，指向这个类的选项
* `title` 指定论文的标题 * `title` 指定论文的标题
* `author` 是一个包含例如 `name`, `affiliation`, 和 `email` 的地方 * `author` 是一个包含例如 `name`、`affiliation` 和 `email` 的地方
* `bibliography` 指向包含参考书目的文件 (biblio.bib) * `bibliography` 指向包含参考书目的文件（`biblio.bib`）
* `abstract` 包含论文的摘要 * `abstract` 包含论文的摘要
* `include-before` 是这篇论文的真实内容之前应该被包含的信息；在 LaTeX 中被称为 [前言][8]。我在这里包含它去展示如何产生一篇计算机科学的论文，但是你可以选择跳过 * `include-before` 是这篇论文的具体内容之前应该被包含的信息；在 LaTeX 中被称为 [前言][8]。我在这里包含它去展示如何产生一篇计算机科学的论文，但是你可以选择跳过
* `figPrefix` 指向如何引用文档中的图像，例如：当引用图像的 `[@fig:scatter-matrix]` 时应该显示什么。例如，当前的 `figPrefix` 在这个例子 `The boxes "Enjoy", "Grade" and "Motivation" ([@fig:scatter-matrix])`中，产生了这样的输出：`The boxes "Enjoy", "Grade" and "Motivation" (Fig. 3)`。如果这里有很多图像，目前的设置表明它应该在图像号码旁边显示 `Figs.`。 * `figPrefix` 指向如何引用文档中的图像，例如：当引用图像的 `[@fig:scatter-matrix]` 时应该显示什么。例如，当前的 `figPrefix` 在这个例子 `The boxes "Enjoy", "Grade" and "Motivation" ([@fig:scatter-matrix])`中，产生了这样的输出：`The boxes "Enjoy", "Grade" and "Motivation" (Fig. 3)`。如果这里有很多图像，目前的设置表明它应该在图像号码旁边显示 `Figs.`
* `secPrefix` 指定如何引用文档中其他地方提到的部分（类似之前的图像和概览） * `secPrefix` 指定如何引用文档中其他地方提到的部分（类似之前的图像和概览）
现在已经设置好了元信息，让我们来创建一个 `Makefile`，它会产生你想要的输出。`Makefile` 使用 Pandoc 产生 LaTeX 文件，`pandoc-crossref` 产生交叉引用，`pdflatex` 构建 LaTeX 为 PDF，`bibtex ` 处理引用。 现在已经设置好了元信息，让我们来创建一个 `Makefile`，它会产生你想要的输出。`Makefile` 使用 Pandoc 产生 LaTeX 文件，`pandoc-crossref` 产生交叉引用，`pdflatex` 构建 LaTeX 为 PDF，`bibtex ` 处理引用。
@ -283,16 +281,14 @@ clean:
Pandoc 使用下面的标记： Pandoc 使用下面的标记：
* `-s` 创建一个独立的 LaTeX 文档 * `-s` 创建一个独立的 LaTeX 文档
* `-F pandoc-crossref` 利用 `pandoc-crossref` 进行过滤 * `-F pandoc-crossref` 利用 `pandoc-crossref` 进行过滤
* `--natbib` 用 `natbib` （你也可以选择 `--biblatex`）对参考书目进行渲染 * `--natbib` 用 `natbib` （你也可以选择 `--biblatex`）对参考书目进行渲染
* `--template` 设置使用的模板文件 * `--template` 设置使用的模板文件
* `-N` 为章节的标题编号 * `-N` 为章节的标题编号
* `-f` 和 `-t` 指定从哪个格式转换到哪个格式。`-t` 通常包含格式和 Pandoc 使用的扩展。在这个例子中，我们标明的 `raw_tex+tex_math_dollars+citations` 允许在 Markdown 中使用 `raw_tex` LaTeX。 `tex_math_dollars` 让我们能够像在 LaTeX 中一样输入数学符号，`citations` 让我们可以使用 [这个扩展][9]. * `-f` 和 `-t` 指定从哪个格式转换到哪个格式。`-t` 通常包含格式和 Pandoc 使用的扩展。在这个例子中，我们标明的 `raw_tex+tex_math_dollars+citations` 允许在 Markdown 中使用 `raw_tex` LaTeX。 `tex_math_dollars` 让我们能够像在 LaTeX 中一样输入数学符号，`citations` 让我们可以使用 [这个扩展][9]。
要从 LaTeX 产生 PDF，按 [来自bibtex][10] 的指导处理参考书目：
由 LaTeX 产生 PDF，接着引导行 [从 bibtex][10] 处理参考书目：
``` ```
@pdflatex main.tex &> /dev/null @pdflatex main.tex &> /dev/null
@ -309,9 +305,9 @@ Pandoc 使用下面的标记：
### 结论 ### 结论
在我看来，研究的重点是协作，思想的传播，以及在任何一个恰好存在的领域中改进现有的技术。许多计算机科学家和工程师使用 LaTeX 文档系统来写论文，它对数学提供了完美的支持。来自社会科学的调查员似乎更喜欢 DOCX 文档。 在我看来，研究的重点是协作、思想的传播，以及在任何一个恰好存在的领域中改进现有的技术。许多计算机科学家和工程师使用 LaTeX 文档系统来写论文，它对数学提供了完美的支持。来自社会科学的研究人员似乎更喜欢 DOCX 文档。
当身处不同社区的调查员一同写一篇论文时，他们首先应该讨论一下他们将要使用哪种格式。然而如果包含太多的数学符号，DOCX 对于工程师来说不会是最简便的选择，LaTeX 对于缺乏编程经验的调查员来说也有一些问题。就像这篇文章中展示的，Markdown 是一门工程师和社会科学家都很轻易能够使用的语言。 当身处不同社区的研究人员一同写一篇论文时，他们首先应该讨论一下他们将要使用哪种格式。然而如果包含太多的数学符号，DOCX 对于工程师来说不会是最简便的选择，LaTeX 对于缺乏编程经验的研究人员来说也有一些问题。就像这篇文章中展示的，Markdown 是一门工程师和社会科学家都很轻易能够使用的语言。
-------------------------------------------------------------------------------- --------------------------------------------------------------------------------
@ -320,7 +316,7 @@ via: https://opensource.com/article/18/9/pandoc-research-paper
作者：[Kiko Fernandez-Reyes][a] 作者：[Kiko Fernandez-Reyes][a]
选题：[lujun9972][b] 选题：[lujun9972][b]
译者：[dianbanjiu](https://github.com/dianbanjiu) 译者：[dianbanjiu](https://github.com/dianbanjiu)
校对：[校对者ID](https://github.com/校对者ID) 校对：[wxy](https://github.com/wxy)
本文由 [LCTT](https://github.com/LCTT/TranslateProject) 原创编译，[Linux中国](https://linux.cn/) 荣誉推出 本文由 [LCTT](https://github.com/LCTT/TranslateProject) 原创编译，[Linux中国](https://linux.cn/) 荣誉推出