心理科學研究必用神器4 ~ 動態文件寫作入門
這不是我第一篇介紹寫作動態文件的網誌,這個網站就是用開放源碼的動態文件套件架構與維護。有興趣的讀者可以到首頁,參考建構這個網站的資訊。這篇介紹如何寫作一般的報告與筆記,包括學生的報告,研究人員的計畫與論文手稿等。
多數人習慣使用的文書處理軟體,像是WORD與google doc,集合文字編輯與排版。寫作正式文件時,需要同時顧慮編輯與排版的契合,雖然之前介紹的zotero已經減輕編輯文內引用與排版參考文獻的工作,一份文件內要安置圖表,乃至數學符號與統計數據的整理,還是需要花時間在不同軟體之間剪貼。
這篇網誌說明如何編輯一篇有列舉參考文獻,無任何圖表及數學符號的中文文件。讓讀者了解動態文件的文字編輯與排版是兩件分開的工作,並提出支援中文寫作的動態文件套件,還需要改進的地方。
基礎知識
與建置這套個人網站一樣,一切準備從安裝Rstudo與R開始。Rstudio開發的套件knitr
可由使用者自行安裝,或者是第一次使用Rstudio編輯動態文件時,會自動下載安裝。knitr
的功能是將有指定語法標籤的純文字文件,例如markdown
與R
,轉換為其他排版軟體能辨識的內容。Rstudio已經整合一套開源排版軟體pandoc,可將轉換後的純文字文件,按排版設定渲染(render)輸出word或pdf檔案。
上圖是Rstudio開啟新文件的選單,除了R script與Text File,其他檔案格式都是可用其他軟體渲染輸出各種排版或編譯產物。這也是為何管理動態文件,應區分文字編輯與排版兩種工作。以一份R Markdown文件為例,有開頭的yaml
與內文兩部分,yaml
是列舉排版這份文件的所需資訊,以符號 --- 標記資訊開始及結尾。以本文的示範文件為例,這份文件要輸出為WORD檔案,yaml
包含的資訊如下:
output:
word_document:
reference_docx: word_style_reference.docx
bibliography: Turri.bib
csl: apa-old-doi-prefix.csl
與這份示範文件放在一起的三個外部檔案:word_style_reference.docx、Turri.bib、apa-old-doi-prefix.csl,分別提供渲染這份文件需要的排版樣式、書目資訊、以及引用格式。zotero網誌曾介紹如何管理書目資訊與引用格式的檔案,docx檔是提供一份有所需樣式與版面設定範例的word檔,也就是一個排版範本,有關WORD的排版可參考官方說明網站。
寫作示範
建議讀者先下載前述連結的檔案,嘗試重現示範文件的輸出成果,會更理理以下示範說明。
R markdown內文與一般markdown文件一樣,未在置入任何標籤的任何文字等於一般WORD文件的內文,pandoc
會根據排版範本的內文樣式渲染。標記標題的#或##等,會根據排版範本的標題一、標題二等樣式渲染。如果使用者需要呈現頁碼,只要在排版範本預做安排。
文內引用的書目是將存在於書目資訊檔案的bibtex key,置入在內文要呈現的地方,例如以下節錄的示範文字。詳細的置入語法與調整設定,可參考Rstudio的介紹。
美國哲學家Gettier[-@gettierJustifiedTrueBelief1963]發表一篇短論文,提出兩個即使符合JTB三種條件,依然無法確定某人有沒有正確知識的反例。
只要有引用的書目資訊,pandoc
會根據引用格式檔案內的資訊,與文末排列參考文獻。示範文件中使用的格式是APA 6並呈現doi的一般格式。因此一份文件由兩位以上共同編輯,只要共享需要的書目資訊,也不必依賴付費軟體編輯與管理引用文獻。有關格式檔案的設定方法,可參考pulipuli的網誌。
進階套件
未來我還會撰寫在動態文件編輯圖表與統計數據的網誌,待讀者熟練本篇介紹的操作,推薦安裝以下套件,增益編輯動態文件的效率:
citr
:這套Rstudio的外掛可幫助使用者在編輯過程中,有插入引用文獻的bibtext key的需要,以視窗介面搜尋並編輯。我的使用建議是先準備好書目資訊檔案,編輯過程中不必開啟zotero。如果有需要更新書目資訊檔案,最好先暫停文件編輯工作,更新完成後再繼續編輯。
papaja
: citr
作者的代表作,可創建符合APA格式的手稿檔案,並支援圖表與數據的排版功能。初版使用手冊今年已正式上線。
期待的改進
這篇介紹的動態文件套件在支援中文寫作有兩個值得改進之處。首先是生成pdf檔的問題,目前簡體中文有R牛人Yihui Xie的努力,已有支援出簡體中文pdf的套件,但是繁體中文仍然不夠全面。也可能是我找不到正確的支援方法所致,還請網友賜教。第二點是pandoc渲染參考文獻的功能只有支援英文書目,讀者可從示範文件裡的中文書目發現問題。這兩個問題如果能獲得改進,相信更多研究者與學生會更容易接受動態文件,提高研究過程與成果的透明度也有更清楚的標準。
20190114突破補充
寫作這篇網誌到這個日期之間,我已使用papaja編寫至少兩篇論文,對於latex的排版語法有更新的認識。這一日終於試出能成功產生中文論文的方法,原理是相容中日韓字符xeCJK,,目前只有xelatex這套文件生成引擎能完整支援。加上中文字的特殊設定,YAML必須有以下設定。
## Get the header from http://newsletter.ascc.sinica.edu.tw/news/read_news.php?nid=2198
## ptt latex board
## Section begin: this section has to be above 'output:'
header-includes:
- \usepackage[no-math]{fontspec}
- \usepackage{xeCJK}
- \setCJKmainfont{標楷體} ## 可改成已安裝的其他字型
- \XeTeXlinebreaklocale "zh"
- \XeTeXlinebreakskip = 0pt plus 1pt
## Section end: this section has to be above 'output:'
## Get this setting from https://stackoverflow.com/questions/36806255/rstudio-on-windows-not-using-xelatex
## This option forced Rstudio use xelatex compile this document
output:
pdf_document:
latex_engine: xelatex
未來論文寫作工作告一段落,我將寫一份papaja完整中文教學,介紹如何運用這些套件製作可重製報告。
!登入個人github帳號就能留言!