用 Pandoc 生成一篇調研論文
這篇文章對於使用 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 圖片很相似:
![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]
這篇論文將會產生像下面這樣被標號的參考書目:
引用文章的集合也很容易:只要引用使用分號 ;
分隔開被標記的參考文獻就可以了。如果一個引用有兩個標籤 —— 例如: 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]
選項表示這張圖用該位於該頁的最頂部。有關更多選項,參閱 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}
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 找到:
結論
在我看來,研究的重點是協作、思想的傳播,以及在任何一個恰好存在的領域中改進現有的技術。許多計算機科學家和工程師使用 LaTeX 文檔系統來寫論文,它對數學提供了完美的支持。來自社會科學的研究人員似乎更喜歡 DOCX 文檔。
當身處不同社區的研究人員一同寫一篇論文時,他們首先應該討論一下他們將要使用哪種格式。然而如果包含太多的數學符號,DOCX 對於工程師來說不會是最簡便的選擇,LaTeX 對於缺乏編程經驗的研究人員來說也有一些問題。就像這篇文章中展示的,Markdown 是一門工程師和社會科學家都很輕易能夠使用的語言。
via: https://opensource.com/article/18/9/pandoc-research-paper
作者:Kiko Fernandez-Reyes 選題:lujun9972 譯者:dianbanjiu 校對:wxy
本文轉載來自 Linux 中國: https://github.com/Linux-CN/archive