編譯自： https://opensource.com/article/18/9/pandoc-research-paper

作者： Kiko Fernandez-reyes

譯者： dianbanjiu

學習如何用 Markdown 管理章節引用、圖像、表格以及更多。

這篇文章對於使用 Markdown 語法做一篇調研論文進行了一個深度體驗。覆蓋了如何創建和引用章節、圖像（用 Markdown 和 LaTeX ）和參考書目。我們也討論了一些棘手的案例和為什麼使用 LaTex 是一個正確的做法。

調研

調研論文一般包括對章節、圖像、表格和參考書目的引用。 Pandoc 本身並不能交叉引用這些，但是它能夠利用 pandoc-crossref 過濾器來完成自動編號和章節、圖像、表格的交叉引用。

讓我們從重寫原本以 LaTax 撰寫的 一個教育調研報告的例子 開始，然後用 Markdown（和一些 LaTax）、Pandoc 和 Pandoc-crossref 重寫。

添加並引用章節

要想章節被自動編號，必須使用 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 圖片很相似：

{#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]

這篇論文將會產生像下面這樣被標號的參考書目：

引用文章的集合也很容易：只要引用使用分號 ; 分隔開被標記的參考文獻就可以了。如果一個引用有兩個標籤 —— 例如： 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 環境參數，它可以讓用戶控制圖像的位置。

我們看一個上面提到的圖像的例子：

{#fig:scatter-matrix}

然後使用 LaTeX 重寫：

egin{figure}[t]

includegraphics{data/scatterplots/RScatterplotMatrix2.png}

caption{label{fig:matrix}Scatterplot matrix}

end{figure}

在 LaTeX 中，figure 環境參數中的 [t] 選項表示這張圖用該位於該頁的最頂部。有關更多選項，參閱 LaTex/Floats, Figures, and Captions 這篇 Wikibooks 的文章。

產生一篇論文

到目前為止，我們講了如何添加和引用（子）章節、圖像和參考書目，現在讓我們重溫一下如何生成一篇 PDF 格式的論文。要生成 PDF，我們將使用 Pandoc 生成一篇可以被構建成最終 PDF 的 LaTeX 文件。我們還會討論如何以 LaTeX，使用一套自定義的模板和元信息文件生成一篇調研論文，以及如何將 LaTeX 文檔編譯為最終的 PDF 格式。

很多會議都提供了一個 .cls 文件或者一套論文應有樣式的模板；例如，它們是否應該使用兩列的格式以及其它的設計風格。在我們的例子中，會議提供了一個名為 acmart.cls 的文件。

作者通常想要在他們的論文中包含他們所屬的機構，然而，這個選項並沒有包含在默認的 Pandoc 的 LaTeX 模板（注意，可以通過輸入 pandoc -D latex 來查看 Pandoc 模板）當中。要包含這個內容，找一個 Pandoc 默認的 LaTeX 模板，並添加一些新的內容。將這個模板像下面這樣複製進一個名為 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}

egin{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 找到：

結論

在我看來，研究的重點是協作、思想的傳播，以及在任何一個恰好存在的領域中改進現有的技術。許多計算機科學家和工程師使用 LaTeX 文檔系統來寫論文，它對數學提供了完美的支持。來自社會科學的研究人員似乎更喜歡 DOCX 文檔。

當身處不同社區的研究人員一同寫一篇論文時，他們首先應該討論一下他們將要使用哪種格式。然而如果包含太多的數學符號，DOCX 對於工程師來說不會是最簡便的選擇，LaTeX 對於缺乏編程經驗的研究人員來說也有一些問題。就像這篇文章中展示的，Markdown 是一門工程師和社會科學家都很輕易能夠使用的語言。

via: https://opensource.com/article/18/9/pandoc-research-paper

作者： Kiko Fernandez-Reyes 選題： lujun9972 譯者： dianbanjiu 校對： wxy

本文由 LCTT 原創編譯， Linux中國 榮譽推出

點擊「了解更多」可訪問文內鏈接

喜歡這篇文章嗎？立刻分享出去讓更多人知道吧！