1 簡介

ntuthesis2 是透過 Pandoc 建立的論文模板，讓使用者能透過 (Pandoc) Markdown 語法撰寫論文 (無須安裝與了解 LaTeX!!)。此專案的前身是 R 套件，但由於 R + Bookdown + LaTeX 的設定相對龐雜，對非 R 的使用者而言有相當難度，因此改以 Python 3 + Pandoc 實作 (這兩者在 Windows 與 Unix 上的安裝都相當容易)，希望讓更多人能夠使用。

輸出範例：

1.1 安裝

只要電腦上有 Python (3.5 以上) 即可使用 (無須安裝其它東西)

Clone 或下載這個 repo
安裝相關套件：
```
pip install -r requirements.txt 
```
執行主程式：
```
python3 main.py  
# python main.py 
```
第一次執行主程式時，會自動下載 Pandoc 執行檔 (置於 pandoc/ 當中)，之後便會出現互動式界面引導使用者輸出論文。

1.2 使用

ntuthesis2 運作的流程如圖：

由於 LaTeX (TeX Live 或 MikTeX 的安裝十分令人頭痛，而且即使安裝完成，後續生成 PDF 的過程仍會常常出錯。為了儘量避開這些問題，ntuthesis2 在設計上結合 Overleaf，讓使用者能將輸出的 .tex 檔透過 (免費) 網路服務輸出成 PDF 檔 (上圖綠色箭號流程)。當然，若使用者個人電腦上已有 LaTeX，也可直接在電腦上輸出 PDF。此外，ntuthesis2 也提供一個相當簡約的 .html 輸出格式，目的是方便在撰寫時預覽論文 (因為 LaTeX 的輸出相當耗時)。

1.2.1 輸出論文

/
├── front_matter.yml       # 論文封面設定
├── thesis-setup.yml       # 論文格式設定、摘要、謝辭
├── ref.bib                # 引用文獻 (可直接覆寫)
├── cite-style.csl         # Citation style
├── chapters/              # 章節內容 (Markdown 文件), 章節照檔名排序
│   ├── 01-intro.md         
│   ├── 02-literature.md            
│   └── 90-references.md       # 這個檔案不須更改 (除了想更改標題)
├── figures/               # 論文用到的圖片 (需用相對路徑，以 repo 根目錄為準)
│   ├── os_meme.png            # 範例圖片   
│   └── watermark.png          # PDF 論文右上角的浮水印
├── fonts/                 # 字體檔
├── latex/                 # 模板
├── pandoc/                # Pandoc 執行檔 (程式會自動下載)
├── docs/                  # 輸出論文 (PDF/HTML/Overleaf)
├── ntuthesis.cls          # LaTeX 格式設定 (論文封面)
├── requirements.txt       # Python dependencies
├── main.py                # 互動式主程式 (安裝 Pandoc、輸出論文)
└── README.md

上方是論文模板 (即此 repo) 的檔案結構及其內容說明，下方為論文的輸出說明 (檔案對應至上方的結構):

製作論文封面 (封面、口試委員審定書)
1. 在 front_matter.yml 修改相關資訊 (姓名、日期、指導教授…)
2. 執行互動主程式 python3 main.py
  - 若電腦上有 LaTeX，在終端機依序輸入 pdf, english (或 chinese) 與 front_matter：
```
[USER] Select output format [html / pdf / overleaf / exit] > pdf 
    [USER] Select language [chinese / english] > english
    [USER] Which to output [thesis / front_matter] > front_matter
...
[OUTPUT] docs/front_matter.pdf
```
  - 若無 LaTeX，
    1. 在終端機依序輸入 overleaf, english (或 chinese)：
      [USER] Select output format [html / pdf / overleaf / exit] > overleaf [USER] Select language [chinese / english] > english ... [OUTPUT] docs/overleaf.zip
    2. 這時便可將 docs/overleaf.zip 上傳至 Overleaf (需註冊帳號)
      1. 上傳之後，Overleaf 會自動解壓展開檔案，請點選 front_matter.tex (這時自動 Compile 應會失敗)
      2. 點選左方 Menu，Compiler 選擇 XeLaTeX (見下圖 2)
      3. 點選畫面左上方 Recompile
      4. 輸出完成後，下載 PDF 檔 (Recompile 右側的下載鍵) 至 docs/ 並將檔名命名為 front_matter.pdf
輸出完整論文
1. 編輯論文：
  - 在 thesis-setup.yml 設定論文相關格式、撰寫摘要、謝辭
  - 在 chapters/ 裡的 .md 檔編輯論文章節。若需要用到圖片，需將圖片置於 figures/，並以相對路徑連結圖片，例如，figures/os_meme.png (相對路徑以此 repo 根目錄作為起點)
  - 將文獻管理軟體 (EndNote, Zotero, JabRef, …) 中的引用資料輸出成 .bib 檔，取代掉原本的 ref.bib
  - 若要修改引用格式 (原本的 cite-style.csl 為 APA 格式)，可至 https://www.zotero.org/styles 或 https://github.com/citation-style-language/styles 下載需要的格式 (.csl檔)，取代掉原本的 cite-style.csl
2. 執行互動主程式 python3 main.py
  - 若電腦上有 LaTeX，在終端機依序輸入 pdf, english (或 chinese) 與 thesis：
```
[USER] Select output format [html / pdf / overleaf / exit] > pdf 
    [USER] Select language [chinese / english] > english
    [USER] Which to output [thesis / front_matter] > thesis
...
[OUTPUT] docs/thesis.pdf
```
  - 若無 LaTeX，
    1. 請依照上方輸出封面的方式操作主程式
    2. 將 output/overleaf.zip 上傳至 Overleaf 後，
      1. 點選 thesis.tex，並將 Compiler 設為 XeLaTeX
      2. 點選左上方新增資料夾 (New Folder) docs 並將 front_matter.pdf 放入 docs/
      3. Recompile 後下載輸出的 PDF 檔

Figure 2: 將 Compiler 設為 XeLaTex — Figure 2: 將 Compiler 設為 `XeLaTex`

1.2.2 論文撰寫：文內超連結

Table 1: Cross-reference 語法.
	定義	引用
段落	`Section Two {#sec:2}`	`@sec:id`
圖片	`![Caption.](image.png){#fig:id}`	`@fig:id`
公式	`$$ y = mx + b $$ {#eq:id}`	`@eq:id`
表格	`Table: Caption. {#tbl:id}`	`@tbl:id`

詳見 pandoc-xnos。

1.2.3 論文撰寫：文獻引用

文獻引用是透過 .bib 檔裡的書目資料以及 Pandoc’s Citation syntax 達成。.bib 檔的產生方式可以由 Endnote, Zotero, JabRef 等書目管理軟體匯出。匯出後，將檔名命名為 ref.bib 取代根目錄中原本的檔案。

下方是 .bib 內的一篇引用資料 (一個 .bib 可以有很多篇)：

@article{leung2008,
  title = {Multicultural Experience Enhances Creativity: {{The}} When and How.},
  volume = {63},
  issn = {1935-990X(Electronic),0003-066X(Print)},
  doi = {10.1037/0003-066X.63.3.169},
  number = {3},
  journaltitle = {American Psychologist},
  date = {2008},
  pages = {169-181},
  keywords = {*Cognition,*Creativity,
    *Culture (Anthropological),
    *Experiences (Events),Multiculturalism},
  author = {Leung, Angela Ka-yee and 
    Maddux, William W. and 
    Galinsky, Adam D. and Chiu, Chi-yue}
}

其中第一行的 leung2008 即為 citation key。Pandoc 透過 @citekey (e.g., @leung2008) 在 .md 檔中插入 citation。匯出論文時，Pandoc 會依據 cite-style.csl 的格式自動產生引用文獻。下方為一些文獻引用語法的範例，詳見 Pandoc’s Citation syntax。

Table 2: 文獻引用語法.
	內文	輸出 (根據 `.csl` 改變)
單篇	`[@stanford2008]`	(Stanford, 2008)
多篇	`[@stanford2008; @kassin2017]`	(Kassin, Fein, & Markus, 2017; Stanford, 2008)
文內引用	`@stanford2008 says ...`	Stanford (2008) says
隱藏作者	`Stanford says blah [-@stanford2008]`	Stanford says blah (2008)
其它註解	`see @kassin2017, pp. 33-35`	see Kassin, Fein, & Markus (2017), pp. 33-35

1.3 尋求協助

若有套件使用上的問題，可在 GitHub 回報。若沒有 GitHub 帳號，可透過 Emailliao961120@gmail.com 聯絡 Yongfu Liao。

1.4 特別感謝

此論文模板的封面是根據 tzhuan/ntu-thesis 修改而成。

Kassin, S., Fein, S., & Markus, H. R. (2017). Social Psychology (10th ed.). Boston: Cengage Learning.

Stanford, J. N. (2008). Child dialect acquisition: New perspectives on parent/peer Influence1. Journal of Sociolinguistics, 12(5), 567–596. https://doi.org/10.1111/j.1467-9841.2008.00383.x

Last updated: 26 February, 2021