歡迎光臨
每天分享高質量文章

用 Pandoc 生成一篇調研論文 | Linux 中國

學習如何用 Markdown 管理章節取用、圖像、表格以及更多。
— Kiko Fernandez-reyes


致謝
編譯自 | 
https://opensource.com/article/18/9/pandoc-research-paper
 
 作者 | Kiko Fernandez-reyes
 譯者 | dianbanjiu ??共計翻譯:9.0 篇 貢獻時間:29 天

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

這篇文章對於使用 Markdown[1] 語法做一篇調研論文進行了一個深度體驗。改寫瞭如何創建和取用章節、圖像(用 Markdown 和 LaTeX[2])和參考書目。我們也討論了一些棘手的案例和為什麼使用 LaTex 是一個正確的做法。

調研

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

讓我們從重寫原本以 LaTax 撰寫的 一個教育調研報告的例子[5] 開始,然後用 Markdown(和一些 LaTax)、Pandoc 和 Pandoc-crossref 重寫。

添加並取用章節

要想章節被自動編號,必須使用 Markdown H1 標題編寫。子章節使用 H2-H4 子標題編寫(通常不需要更多級別了)。例如一個章節的標題是 “Implementation”,寫作 # Implementation {#sec: implementation},然後 Pandoc 會把它轉化為 3. Implementation(或者轉換為相應的章節編號)。Implementation 這個標題使用了 H1 並且宣告了一個 {#sec: implementation} 的標簽,這是作者用於取用該章節的標簽。要想取用一個章節,輸入 @符號並跟上對應章節標簽,使用方括號括起來即可: [@ sec:implementation]

在這篇論文中[5], 我們發現了下麵這個例子:

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

Pandoc 轉換:

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

章節被自動編號(這在本文最後的 Makefile 當中說明)。要創建無編號的章節,輸入章節的標題併在最後添加 {-}。例如:### Designing a game for maintainability {-} 就以標題 “Designing a game for maintainability”,創建了一個無標號的章節。

添加並取用圖像

添加並取用一個圖像,跟添加並取用一個章節和添加一個 Markdown 圖片很相似:

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

上面這一行是告訴 Pandoc,有一個標有 Scatterplot matrix 的圖像以及這張圖片路徑是 data/scatterplots/RScatterplotMatrix2.png{#fig:scatter-matrix}表明瞭用於取用該圖像的名字。

這裡是從一篇論文中進行圖像取用的例子:

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

Pandoc 產生如下輸出:

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

添加及取用參考書目

大多數調研報告都把取用放在一個 BibTeX 的資料庫檔案中。在這個例子中,該檔案被命名為 biblio.bib[6],它包含了論文中所有的取用。下麵是這個檔案的樣子:

  1. @inproceedings{wrigstad2017mastery,

  2.    Author =       {Wrigstad, Tobias and Castegren, Elias},

  3.    Booktitle =    {SPLASH-E},

  4.    Title =        {Mastery Learning-Like Teaching with Achievements},

  5.    Year =         2017

  6. }

  7. @inproceedings{review-gamification-framework,

  8.  Author =       {A. Mora and D. Riera and C. Gonzalez and J. Arnedo-Moreno},

  9.  Publisher =    {IEEE},

  10.  Booktitle =    {2015 7th International Conference on Games and Virtual Worlds

  11.                  for Serious Applications (VS-Games)},

  12.  Doi =          {10.1109/VS-GAMES.2015.7295760},

  13.  Keywords =     {formal specification;serious games (computing);design

  14.                  framework;formal design process;game components;game design

  15.                  elements;gamification design frameworks;gamification-based

  16.                  solutions;Bibliographies;Context;Design

  17.                  methodology;Ethics;Games;Proposals},

  18.  Month =        {Sept},

  19.  Pages =        {1-8},

  20.  Title =        {A Literature Review of Gamification Design Frameworks},

  21.  Year =         2015,

  22.  Bdsk-Url-1 =   {http://dx.doi.org/10.1109/VS-GAMES.2015.7295760}

  23. }

  24. ...

第一行的 @inproceedings{wrigstad2017mastery, 表明瞭出版物 的型別(inproceedings),以及用來指向那篇論文的標簽(wrigstad2017mastery)。

取用這篇題為 “Mastery Learning-Like Teaching with Achievements” 的論文, 輸入:

  1. the achievement-driven learning methodology [@wrigstad2017mastery]

Pandoc 將會輸出:

  1. the achievement- driven learning methodology [30]

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

取用文章的集合也很容易:只要取用使用分號 ; 分隔開被標記的參考文獻就可以了。如果一個取用有兩個標簽 —— 例如: SEABORN201514 和 gamification-leaderboard-benefits—— 像下麵這樣把它們放在一起取用:

  1. Thus, the most important benefit is its potential to increase students' motivation

  2. and engagement [@SEABORN201514;@gamification-leaderboard-benefits].

Pandoc 將會產生:

  1. Thus, the most important benefit is its potential to increase students motivation

  2. and engagement [26, 28]

問題案例

一個常見的問題是所需專案與頁面不匹配。不匹配的部分會自動移動到它們認為合適的地方,即便這些位置並不是讀者期望看到的位置。因此在圖像或者表格接近於它們被提及的地方時,我們需要調節一下那些元素放置的位置,使得它們更加易於閱讀。為了達到這個效果,我建議使用 figure 這個 LaTeX 環境引數,它可以讓用戶控製圖像的位置。

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

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

然後使用 LaTeX 重寫:

  1. \begin{figure}[t]

  2. \includegraphics{data/scatterplots/RScatterplotMatrix2.png}

  3. \caption{\label{fig:matrix}Scatterplot matrix}

  4. \end{figure}

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

產生一篇論文

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

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

作者通常想要在他們的論文中包含他們所屬的機構,然而,這個選項並沒有包含在預設的 Pandoc 的 LaTeX 模板(註意,可以通過輸入 pandoc -D latex 來查看 Pandoc 模板)當中。要包含這個內容,找一個 Pandoc 預設的 LaTeX 模板,並添加一些新的內容。將這個模板像下麵這樣複製進一個名為 mytemplate.tex 的檔案中:

  1. pandoc -D latex > mytemplate.tex

預設的模板包含以下代碼:

  1. $if(author)$

  2. \author{$for(author)$$author$$sep$ \and $endfor$}

  3. $endif$

  4. $if(institute)$

  5. \providecommand{\institute}[1]{}

  6. \institute{$for(institute)$$institute$$sep$ \and $endfor$}

  7. $endif$

因為這個模板應該包含作者的聯繫方式和電子郵件地址,在其他一些選項之間,我們更新這個模板以添加以下內容(我們還做了一些其他的更改,但是因為檔案的長度,就沒有包含在此處):

  1. latex

  2. $for(author)$

  3.    $if(author.name)$

  4.        \author{$author.name$}

  5.        $if(author.affiliation)$

  6.            \affiliation{\institution{$author.affiliation$}}

  7.        $endif$

  8.        $if(author.email)$

  9.            \email{$author.email$}

  10.        $endif$

  11.    $else$

  12.        $author$

  13.    $endif$

  14. $endfor$

要讓這些更改起作用,我們還應該有下麵的檔案:

◈ main.md 包含調研論文
◈ biblio.bib 包含參考書目資料庫
◈ acmart.cls 我們使用的文件的集合
◈ mytemplate.tex 是我們使用的模板檔案(代替預設的)

讓我們添加論文的元信息到一個 meta.yaml 檔案:

  1. ---

  2. template: 'mytemplate.tex'

  3. documentclass: acmart

  4. classoption: sigconf

  5. title: The impact of opt-in gamification on `\\`{=latex} students' grades in a software design course

  6. author:

  7. - name: Kiko Fernandez-Reyes

  8.   affiliation: Uppsala University

  9.   email: [email protected]

  10. - name: Dave Clarke

  11.   affiliation: Uppsala University

  12.   email: [email protected]

  13. - name: Janina Hornbach

  14.   affiliation: Uppsala University

  15.   email: [email protected]

  16. bibliography: biblio.bib

  17. abstract: |

  18.   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)

  19. include-before: |

  20.      \` ``{=latex}

  21.      \copyrightyear{2018}

  22.      \acmYear{2018}

  23.      \setcopyright{acmlicensed}

  24.      \acmConference[MODELS '18 Companion]{ACM/IEEE 21th International Conference on Model Driven Engineering Languages and Systems}{October 14--19, 2018}{Copenhagen, Denmark}

  25.      \acmBooktitle{ACM/IEEE 21th International Conference on Model Driven Engineering Languages and Systems (MODELS '18 Companion), October 14--19, 2018, Copenhagen, Denmark}

  26.      \acmPrice{XX.XX}

  27.      \acmDOI{10.1145/3270112.3270118}

  28.      \acmISBN{978-1-4503-5965-8/18/10}

  29.      \begin{CCSXML}

  30.     

  31.     

  32.      10010405.10010489

  33.      Applied computing~Education

  34.      500

  35.     

  •     

  •      \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 是一個包含例如 nameaffiliation 和 email 的地方
    ◈ bibliography 指向包含參考書目的檔案(biblio.bib
    ◈ abstract 包含論文的摘要
    ◈ 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.
    ◈ secPrefix 指定如何取用文件中其他地方提到的部分(類似之前的圖像和概覽)

    現在已經設置好了元信息,讓我們來創建一個 Makefile,它會產生你想要的輸出。Makefile 使用 Pandoc 產生 LaTeX 檔案,pandoc-crossref 產生交叉取用,pdflatex 構建 LaTeX 為 PDF,bibtex 處理取用。

    Makefile 已經展示如下:

    1. all: paper

    2. paper:

    3.         @pandoc -s -F pandoc-crossref --natbib meta.yaml --template=mytemplate.tex -N \

    4.          -f markdown -t latex+raw_tex+tex_math_dollars+citations -o main.tex main.md

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

    6.         @bibtex main &> /dev/null

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

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

    9. clean:

    10.         rm main.aux main.tex main.log main.bbl main.blg main.out

    11. .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 讓我們可以使用 這個擴展[9]

    要從 LaTeX 產生 PDF,按 來自bibtex[10] 的指導處理參考書目:

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

    2. @bibtex main &> /dev/null

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

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

    腳本用 @ 忽略輸出,並且重定向標準輸出和錯誤到 /dev/null ,因此我們在使用這些命令的可執行檔案時不會看到任何的輸出。

    最終的結果展示如下。這篇文章的庫可以在 GitHub[11] 找到:

    結論

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

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


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

    作者:Kiko Fernandez-Reyes[13] 選題:lujun9972 譯者:dianbanjiu 校對:wxy

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

    赞(0)

    分享創造快樂

    © 2021 知識星球   网站地图