用 Pandoc 生成一篇調研論文
學習如何用 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' motivationand engagement [@SEABORN201514;@gamification-leaderboard-benefits].
Pandoc 將會產生：
Thus, the most important benefit is its potential to increase students’ motivationand engagement [26, 28]
問題案例
一個常見的問題是所需專案與頁面不匹配。不匹配的部分會自動移動到它們認為合適的地方，即便這些位置並不是讀者期望看到的位置。因此在影象或者表格接近於它們被提及的地方時，我們需要調節一下那些元素放置的位置，使得它們更加易於閱讀。為了達到這個效果，我建議使用 figure 這個 LaTeX 環境引數，它可以讓使用者控制影象的位置。
我們看一個上面提到的影象的例子：
{#fig:scatter-matrix}
然後使用 LaTeX 重寫：
\begin{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: acmartclassoption: sigconftitle: The impact of opt-in gamification on `\\`{=latex} students' grades in a software design courseauthor:- name: Kiko Fernandez-Reyes affiliation: Uppsala University email: [email protected] name: Dave Clarke affiliation: Uppsala University email: [email protected] name: Janina Hornbach affiliation: Uppsala University email: [email protected]: biblio.bibabstract: | 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: paperpaper: @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/nullclean: 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_texLaTeX。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 是一門工程師和社會科學家都很輕易能夠使用的語言。