images images

心理科學研究必用神器4 ~ 動態文件寫作入門

這不是我第一篇介紹寫作動態文件的網誌,這個網站就是用開放源碼的動態文件套件架構與維護。有興趣的讀者可以到首頁,參考建構這個網站的資訊。這篇介紹如何寫作一般的報告與筆記,包括學生的報告,研究人員的計畫與論文手稿等。

多數人習慣使用的文書處理軟體,像是WORD與google doc,集合文字編輯與排版。寫作正式文件時,需要同時顧慮編輯與排版的契合,雖然之前介紹的zotero已經減輕編輯文內引用與排版參考文獻的工作,一份文件內要安置圖表,乃至數學符號與統計數據的整理,還是需要花時間在不同軟體之間剪貼。

這篇網誌說明如何編輯一篇有列舉參考文獻,無任何圖表及數學符號的中文文件。讓讀者了解動態文件的文字編輯與排版是兩件分開的工作,並提出支援中文寫作的動態文件套件,還需要改進的地方。

基礎知識

與建置這套個人網站一樣,一切準備從安裝RstudoR開始。Rstudio開發的套件knitr可由使用者自行安裝,或者是第一次使用Rstudio編輯動態文件時,會自動下載安裝。knitr的功能是將有指定語法標籤的純文字文件,例如markdownR,轉換為其他排版軟體能辨識的內容。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.docxTurri.bibapa-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帳號就能留言!