--- title: "thaipdf" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{thaipdf} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r, include = FALSE} knitr::opts_chunk$set( collapse = TRUE, comment = "#>" ) ``` ## Introduction ถ้าได้ลองพิมพ์ภาษาไทยใน R Markdown แล้ว knit เป็น `pdf_document` จะพบว่าเกิด error ขึ้น Error: LaTeX failed to compile something.tex. การสร้าง PDF จาก R Markdown นั้น จะผ่านกระบวนการที่แปลงเอกสารหลายขั้นตอน ซึ่ง **ภาษาไทย** จะมีปัญหาที่ขั้นตอน > **LaTeX -\> PDF** วิธีแก้นั้น จะต้องมีการตั้งค่าต่างๆ ใน LaTeX preamble และ YAML header ของ R Markdown เพื่อให้รองรับกับการใช้งานภาษาไทยได้ โดย **R package นี้จึงถูกสร้างขึ้นเพื่อช่วยใน workflow จุดนี้** (ขอบคุณคำแนะนำจาก: [คําแนะนําการตั้งค่า LATEX สําหรับใช้ภาษาไทย](http://pioneer.netserv.chula.ac.th/~wdittaya/LaTeX/LaTeXThai.pdf)) ## Installation การ install เหล่านี้ทำเพียงครั้งเดียวเท่านั้น - **Install thaipdf:** ติดตั้ง development version ของ thaipdf จาก [GitHub](https://github.com/Lightbridge-KS/thaipdf) ด้วย: ``` r # install.packages("remotes") remotes::install_github("Lightbridge-KS/thaipdf") ``` - **Install XeLaTeX และ LaTeX package** ที่จำเป็นสำหรับการใช้ภาษาไทย อาจทำได้อย่างง่ายโดยใช้ [{tinytex}](https://yihui.org/tinytex/) R package: ``` r install.packages("tinytex") # For using R Markdown tinytex::install_tinytex() # Install LaTeX PKG required by `thaipdf` tinytex::tlmgr_install(c( "fontspec", "ucharclasses", "polyglossia" )) ``` โดย LaTeX package ที่จำเป็นสำหรับ type setting ภาษาไทยคือ "fontspec", "ucharclasses" และ "polyglossia" - **Check font:** ตรวจสอบว่าในเครื่องมีฟอนท์ [TH Sarabun New](https://www.f0nt.com/release/th-sarabun-new/) ถ้าไม่มีให้ติดตั้งด้วย (เนื่องจาก thaipdf ใช้ font นี้เป็นตัวหลัก) # Basic Usage ## Stand-alone R Markdown Template วิธีใช้ที่ง่ายที่สุด คือสร้าง R Markdown ที่รองรับภาษาไทยจาก template ที่ package นี้มีให้ ถ้าท่านใช้ RStudio ให้ไปที่ `File -> New File -> R Markdown... -> From Template` ![New R Markdown Template](img/rmd-from-temp.png){alt="New R Markdown Template" width="600"} เลือก template **Thai PDF R Markdown** หรือ **Thai PDF Bookdown** จากเมนู กดปุ่ม **`OK`** จะเปิดไฟล์ R Markdown template ที่รองรับกับภาษาไทย ![thaipdf R Markdown in RStudio](img/rstudio-rmd.png){alt="thaipdf R Markdown in RStudio" width="600"} จากนั้นกดปุ่ม **`Knit`** (cmd/ctr + shift + K) ได้เลย จะได้เอกสารเป็น PDF ภาษาไทยที่มี เนื้อหา โค้ด และ กราฟ อยู่รวมกัน ![ตัวอย่าง R Markdown PDF ภาษาไทย](img/pdf-doc-1.png){width="600"} โปรดสังเกตุว่าการที่ภาษาไทยใช้งานได้นั้น เนื่องจากมีการตั้งค่า YAML header ในส่วน ``` yaml output: thaipdf::thaipdf_document: ``` โดยที่ template ของ thaipdf ทั้ง 2 แบบ - **Thai PDF R Markdown** --- ใช้ output เป็น `thaipdf_document()` ซึ่งเป็น wrapper ของ [`pdf_document()`](https://pkgs.rstudio.com/rmarkdown/reference/pdf_document.html) ที่สามารถรองรับ**ภาษาไทย**ได้ สำหรับการใช้งานอย่างง่าย หรือ - **Thai PDF Bookdown** --- ใช้ output เป็น `thaipdf_book()` ซึ่งเป็น wrapper ของ [`bookdown::pdf_book()`](https://pkgs.rstudio.com/bookdown/reference/pdf_book.html) ที่สามารถรองรับ**ภาษาไทย**ได้ และมี feature ของ bookdown ที่เหมาะสำหรับการเขียนเอกสารทางวิชาการหรืองานตีพิมพ์ที่ต้องการทำ cross references หรือ citation จากแหล่งต่างๆ ## Customization ### Thai Font & Line Spacing สำหรับ `thaipdf_document()` และ `thaipdf_book()` จะมี argument ที่สร้างไว้ให้รองรับ **การตั้งค่าสำหรับภาษาไทย** ดังนี้ - **`thai_font`:** สำหรับตั้งค่า font family ภาษาไทย โดย default เป็น "TH Sarabun New" ซึ่งสามารถเปลี่ยนเป็น font ใดก็ได้ที่ลงไว้ในเครื่อง - **`line_spacing`:** สำหรับระยะห่างระหว่างบรรทัด โดย default ตั้งอยู่ที่ 1.5 เท่า สาเหตุที่เลือกให้ห่างขึ้นมา เพื่อเว้นที่ให้กับสระ และ วรรณยุกต์ ที่อยู่บน/ล่างตัวอักษรภาษาไทย ``` yaml output: thaipdf::thaipdf_document: thai_font: "TH Sarabun New" line_spacing: 1.5 ``` ### R Markdown / Bookdown Arguments เนื่องจากทั้ง 2 function ของ thaipdf นี้ (`thaipdf_document()`, `thaipdf_book()`) สามารถ "**ส่งต่อ argument"** ไปยัง [`rmarkdown::pdf_document()`](https://pkgs.rstudio.com/rmarkdown/reference/pdf_document.html) หรือ [`bookdown::pdf_book()`](https://pkgs.rstudio.com/bookdown/reference/pdf_book.html) ได้ ดังนั้นเราจึงสามารถ ใส่ argument อื่นๆ ที่รองรับโดย 2 function ดังกล่าวได้เลย (ยกเว้น `latex_engine` กับ `includes`) เช่น ``` yaml --- title: "R Markdown ภาษาไทย" author: "`thaipdf` package" output: thaipdf::thaipdf_book: thai_font: "TH Sarabun New" line_spacing: 1.5 toc: true # table of content keep_tex: false # "true" to keep intermediate LaTeX --- ``` สังเกตุว่าต้อง **indent 4 space** ด้วย เพราะจากตัวอย่างเป็น argument ที่ส่งเข้า `thaipdf_book()` - `toc: true` คือกำหนดให้มีสารบัญ - `keep_tex: true` คือเก็บไฟล์ LaTeX ไว้ด้วย ก่อนที่ pandoc จะ compile เป็น PDF สำหรับ argument ตัวอื่นๆ ที่ใช้ได้ ของ [`rmarkdown::pdf_document()`](https://pkgs.rstudio.com/rmarkdown/reference/pdf_document.html) ยังมีอีกมาก ลองอ่านได้ที่: - [PDF document --- R Markdown: The Definitive Guide](https://bookdown.org/yihui/rmarkdown/pdf-document.html#other-features) ### Pandoc Variables เนื่องจาก R Markdown ใช้ pandoc เป็นตัวแปลง LaTeX เป็น PDF ดังนั้นจึงสามารถใส่ [pandoc variable](https://pandoc.org/MANUAL.html#variables-for-latex) ใน YAML header ได้โดยตรง ซึ่งจะมีประโยชน์ในการปรับ setting อื่นๆ เช่น ปรับขนาด font, เปลี่ยน font family ภาษาอังกฤษ, ทำให้ link หรือ citation มีสีสัน เช่น ``` yaml --- title: "R Markdown ภาษาไทย" author: "`thaipdf` package" output: thaipdf::thaipdf_document: thai_font: "TH Sarabun New" fontsize: 12pt mainfont: "TeX Gyre Termes" monofont: "Fira Code iScript" # Color provided by LaTeX "xcolor" package linkcolor: BrickRed urlcolor: NavyBlue --- ``` **Font size ---** จากตัวอย่าง ปรับขนาด font ด้วย `fontsize` **Font family ---** จากตัวอย่าง มี font family ทั้ง 3 ชนิดในเอกสารคือ - `thai_font`: คือ font **ภาษาไทย** - `mainfont`: คือ font หลัก **ภาษาอังกฤษ** - `monofont`: คือ font ของ `code` **Color** --- จากตัวอย่าง ปรับสีของ link ในเอกสาร และ URL ได้ด้วย `linkcolor` และ `urlcolor` ตามลำดับ นอกจากนี้ยังมี pandoc variable อื่นๆ อีกมาก ลองอ่านได้ที่ [Pandoc variable for LaTeX](https://pandoc.org/MANUAL.html#variables-for-latex) ------------------------------------------------------------------------ # Advance Usage ## R Markdown Template with LaTeX preamble {#rmd-pre} สำหรับผู้ที่ใช้ LaTeX เป็น และต้องการ customize หลายสิ่งกับ LaTeX ให้ลองเลือก template ที่ชื่อว่า `Thai PDF R Markdown (with preamble)` ![New R Markdown Template with Preamble](img/rmd-from-temp-preamble.png){alt="New R Markdown Template with Preamble" width="600"} จากนั้นใส่ชื่อไฟล์และตำแหน่งที่ให้สร้างที่ช่อง **Name** กับ **Location** แล้วคลิก **OK** จะมีการสร้าง folder ใน structure แบบนี้ (`` คือชื่อที่กรอกในช่อง Name ไป) / | |--> .Rmd | |--> pre-tex/ | |--> thai-preamble.tex ใน folder จะมี R Markdown file ที่มี YAML header ที่ตั้งค่าที่สำคัญคือ: ``` yaml output: pdf_document: latex_engine: xelatex # จำเป็นต้องใช้ xelatex สำหรับภาษาไทย includes: in_header: "pre-tex/thai-preamble.tex" # path ไปยัง preamble ที่มีปรับให้ใช้ภาษาไทยได้ ``` - **`latex_engine`** เป็น "xelatex" เพื่อให้ใช้ภาษาไทยได้ - **`includes`** คือการนำไฟล์ LaTeX preamble ที่ตั้งค่าให้ใช้ภาษาไทยได้ (`thai-preamble.tex`) มาแทรกใน preamble header (`in_header`) ของ output LaTeX อีกที ก่อนที่จะ compile เป็น PDF ดังนั้นเราจึงสามารถเขียน LaTeX เพิ่มเติม หรือ load package และตั้งค่าอื่นๆ ในไฟล์ `thai-preamble.tex` ได้อีกด้วย เช่นทำ link ให้มีสี (เหมือนภาพแรกสุดที่แสดง) ## Use LaTeX preamble {#latex-preamble} จะเป็นการสร้างไฟล์ `thai-preamble.tex` ที่เป็น LaTeX preamble สำหรับภาษาไทย ขึ้นมาใน working directory (สามารถเปลี่ยนได้) และมีคำแนะนำการตั้งค่าใน YAML ของ R Markdown ให้ด้วย ทางเลือกนี้เหมาะสำหรับ 1. ผู้ที่มีไฟล์ R Markdown อยู่แล้ว แต่ต้องการปรับให้ใช้กับภาษาไทยได้ 2. ผู้ที่ใช้ LaTeX เป็น สามารถดึงตัว LaTeX preamble ภาษาไทยมาใช้ และ customize เพิ่มเติมตามที่ต้องการได้เลย ฟังก์ชั่น **`thaipdf::use_thai_preamble()`** ถูกออกแบบในทำนอง [usethis package](https://usethis.r-lib.org) โดยจะทำการ - **สร้างไฟล์ LaTeX preamble** ชื่อว่า `thai-preamble.tex` (default) โดยจะมีการเรียกใช้ LaTeX package และคำสั่งต่างๆ ในการตั้งค่าภาษาไทยในไฟล์นี้ เช่น ฟอนท์ภาษาไทย (`thai_font`) หรือ ระยะห่างระหว่างบรรทัด (`line_spacing`) จากนั้นให้ **ปรับ [YAML header](https://bookdown.org/yihui/rmarkdown-cookbook/rmarkdown-anatomy.html)** ของ R Markdown ในส่วนของ [`pdf_document:`](https://pkgs.rstudio.com/rmarkdown/reference/pdf_document.html) หรือ [`bookdown::pdf_document2:`](https://pkgs.rstudio.com/bookdown/reference/html_document2.html) ซึ่งต้องทำเอง ดังนี้ - ตั้ง `latex_engine: xelatex` - ใส่ path ให้ `thai-preamble.tex` ถูก includes ไปที่ `in_header:` - ใส่คำสั่ง `\sloppy` เพื่อตัดคำภาษาไทย ไปที่ R Markdown ส่วนต้น (หลังจาก YAML header) ## Example ```{r use_thai_preamble} .old_wd <- setwd(tempdir()) # for example only thaipdf::use_thai_preamble() setwd(.old_wd) # for example only ``` **ใน R Markdown** (`pdf_document`) ให้ปรับ **YAML header** และใส่คำสั่ง `\sloppy` ``` markdown --- title: "ทดสอบภาษาไทย" output: pdf_document: latex_engine: xelatex # จำเป็นต้องใช้ xelatex สำหรับภาษาไทย includes: in_header: thai-preamble.tex # path ไปยัง preamble ที่มีปรับให้ใช้ภาษาไทยได้ --- \sloppy # สวัสดีชาวโลก นี่คือเอกสาร R Markdown **ภาษาไทย** ที่สร้าง PDF ด้วย \LaTeX ``` เสร็จแล้วสามารถกด **`knit`** ได้เลย ![](img/rmd-simple.png){width="600"} # Special Thanks - [คําแนะนําการตั้งค่า LaTeX สําหรับใช้ภาษาไทย (ฑิตยา หวานวารี)](http://pioneer.netserv.chula.ac.th/~wdittaya/LaTeX/LaTeXThai.pdf) - [How to add LaTeX code to the preamble](https://bookdown.org/yihui/rmarkdown-cookbook/latex-preamble.html) - [polygloTeX template by mathmd](https://github.com/mathmd/polygloTeX/blob/master/polyglot_template.tex) ------------------------------------------------------------------------ Last Updated: `r Sys.Date()`