$\rm{\LaTeX}$-th

VS Code Dev Containers + Alpine image + $\rm{\TeX}$ Live (APK package)

$\rm{\LaTeX}$ Repository Template

$tex-hero.png$

ทดสอบการใช้งานแล้วกับ $\rm{\LaTeX{}2e}$

ที่มาของ Template

Template นี้ถูกสร้างขึ้นเพื่อเป็นเครื่องมืออำนวยความสะดวกให้กับสมาชิกของห้องแลบวิจัย CNC ในการใช้ $\rm{\LaTeX}$ สร้างสรรค์ผลงานทางวิชาการ

Communications, Analytics, and Cloud Research Laboratory (CNC Lab)
ภาควิชาวิทยาการคอมพิวเตอร์ คณะวิทยาศาสตร์ มหาวิทยาลัยเกษตรศาสตร์ ประเทศไทย

เริ่มต้น

GitHub Codespaces^1

ใช้ template นี้บน cloud ด้วย GitHub Codespaces

[!CAUTION]
Codespace อาจถูกลบโดยอัตโนมัติเมื่อไม่ได้ถูกใช้งานเป็นระยะเวลาหนึ่ง^2

$tex-codespaces.png$

สร้าง repository ใหม่บน GitHub โดยใช้ template นี้
ที่ repository ที่สร้างใหม่ กดปุ่ม Code → Codespaces → Create codespace on main

$setting-up-codespace-01.png$
รอจน Codespace ถูกตั้งค่าจนเสร็จแล้วเริ่มใช้งานได้เลย

$setting-up-codespace-02.png$

VS Code Dev Containers[^3]

ใช้ template นี้บนคอมพิวเตอร์ของคุณเองด้วย VS Code Dev Containers

สิ่งที่คุณจะต้องติดตั้ง

ขั้นตอนการตั้งค่า

สร้าง repository ใหม่บน GitHub โดยใช้ template นี้
เปิด repository ที่สร้างใหม่ใน VS Code
ติดตั้ง VS Code extension ms-vscode-remote.remote-containers
- เลือกที่ Extensions → ค้นหา ms-vscode-remote.remote-containers → ติดตั้ง extension
- (อีกวิธีหนึ่ง) เรียกคำสั่ง View: Show Extensions ผ่าน VS Code Command Palette หรือด้วยคีย์ลัด (Shift+Command+X (Mac) / Ctrl+Shift+X (Windows/Linux))
หากเปิดใช้งานคำสั่ง code ของ VS Code ไว้ สามารถใช้คำสั่งด้านล่างนี้
```
$ code --install-extension ms-vscode-remote.remote-containers
```
เรียก VS Code Command Palette (Shift+Command+P (Mac) / Ctrl+Shift+P (Windows/Linux)) แล้วเลือกคำสั่ง Remote-Containers: Reopen in Container

$reincon.png$
รอจน container ถูกตั้งค่าจนเสร็จแล้วเริ่มใช้งานได้เลย

การทดสอบการใช้งาน

เปิดไฟล์ทดสอบ _test/hello.tex
หากเปิดใช้งานคำสั่ง code ของ VS Code ไว้ สามารถใช้คำสั่งด้านล่างนี้
```
$ code _test/hello.tex
```
Compile ไฟล์ทดสอบด้วยการกดปุ่ม run หรือเรียกคำสั่ง LaTeX Workshop: Build LaTeX Project ผ่าน VS Code Command Palette หรือด้วยคีย์ลัด (Option+Command+B (Mac) / Ctrl+Alt+B (Windows/Linux))
หาก compile เสร็จสมบูรณ์ ควรจะได้ _test/hello.pdf ที่ไม่ว่างเปล่า (not blank)

เมื่อต้องการหยุดใช้งาน

GitHub Codespaces

เรียก VS Code Command Palette (Shift+Command+P (Mac) / Ctrl+Shift+P (Windows/Linux)) แล้วเลือกคำสั่ง Codespaces: Stop Codespace

VS Code Dev Containers

หากต้องการเปลี่ยนไปใช้งานนอก Dev Container ให้เรียกคำสั่ง Dev Containers: Reopen Folder Locally ผ่าน VS Code Command Palette

$refolo.png$
หากต้องการหยุดใช้งาน (ปิด project) ให้เรียกคำสั่ง Remote: Close Remote Connection ผ่าน VS Code Command Palette

การ Compile และการตั้งค่า Build Steps

[!NOTE]
หากใช้งาน LaTeX Workshop สามารถตรวจสอบบันทึก (logs) การ compile ได้ที่ Output pane ของ VS Code หรือใช้คีย์ลัด (Shift+Command+U (Mac) / Ctrl+Alt+U (Windows/Linux)) แล้วเลือก LaTeX Compiler

การ Compile

โดยทั่วไป สามารถ compile/build $\rm{\LaTeX}$ projects ได้ด้วยวิธีต่อไปนี้

Command Line Interface (CLI)
LaTeX Workshop Magic Comments ดูข้อมูลเพิ่มเติมได้ที่ Compiling Features ด้านล่าง
LaTeX Workshop Recipe system (build steps)

การตั้งค่า Build Steps

Template นี้อาศัย VS Code extension ที่ชื่อว่า LaTeX Workshop ในการจัดการขั้นตอนการ build

(จากประสบการณ์การใช้งานของผู้เขียน) Recipe system มีลำดับความสำคัญเหนือกว่า Magic Comments
การสั่ง build สามารถทำได้หลายวิธี อย่างเช่น ด้วยการกดปุ่ม run หรือเรียกคำสั่ง LaTeX Workshop: Build LaTeX Project ผ่าน VS Code Command Palette หรือด้วยคีย์ลัด (Shift+Command+B (Mac) / Ctrl+Alt+B (Windows/Linux)) เป็นต้น
สามารถตั้งค่าคำสั่งที่ต้องการให้ทำเมื่อ build ได้ที่ .vscode/settings.json
- คำสั่งอย่างเช่น pdflatex, xelatex, หรือ bibtex จะถูกกำหนดที่ "latex-workshop.latex.tools": [] โดยแต่ละคำสั่งจะถูกเรียกว่า Tool
- ขั้นตอนการ build จะถูกกำหนดที่ "latex-workshop.latex.recipes": [] โดยขั้นตอนแต่ละแบบจะถูกเรียกว่า Recipe
- หนึ่ง Recipe คือหนึ่ง sequence ที่จะต้องประกอบด้วย $\ge$ หนึ่ง Tool ถึงจะทำงานได้
- ที่ "latex-workshop.latex.recipes": [], Recipe ที่อยู่ลำดับแรกสุดจะถูกเรียกเมื่อกดปุ่ม run หรือเรียกคำสั่ง LaTeX Workshop: Build LaTeX Project ผ่าน VS Code Command Palette หรือด้วยคีย์ลัด (Shift+Command+B (Mac) / Ctrl+Alt+B (Windows/Linux))
- Tools และ Recipes ที่เตรียมไว้ให้เพิ่มเติมจากค่าเริ่มต้นมีดังนี้
```
{
  ...

  "latex-workshop.latex.tools": [
    {
      // ใช้สำหรับเรียกคำสั่ง xelatex ด้วย option -shell-escape
      "name": "xelatexsh",
      "command": "xelatex",
      "args": ["-shell-escape", "-pdf", "%DOC%"]
    }
  ],
  "latex-workshop.latex.recipes": [
    {
      "name": "xelatex ➞ bibtex ➞ xelatex × 2",
      "tools": ["xelatex", "bibtex", "xelatex", "xelatex"]
    },
    {
      "name": "xelatexsh × 3",
      "tools": ["xelatexsh", "xelatexsh", "xelatexsh"]
    },
    {
      "name": "xelatexsh ➞ bibtex ➞ xelatexsh × 2",
      "tools": ["xelatexsh", "bibtex", "xelatexsh", "xelatexsh"]
    }
  ],

  ...
}
```
สามารถลบไฟล์ auxiliary ต่าง ๆ ที่ถูกสร้างขึ้นมาระหว่างที่ build ได้โดยเรียกคำสั่ง LaTeX Workshop: Clean up auxiliary files ผ่าน VS Code Command Palette หรือด้วยคีย์ลัด (Option+Command+C (Mac) / Ctrl+Alt+C (Windows/Linux))
สามารถยกเลิกการ build ได้โดยเรียกคำสั่ง LaTeX Workshop: Kill LaTeX compiler process ผ่าน VS Code Command Palette

คำสั่งและคีย์ลัดพื้นฐาน[^4]

การกระทำ	VS Code Command Palette	Shortcuts (Mac)	Shortcuts (Windows/Linux)
VS Code Command Palette	$\emptyset$	`Shift`+`Command`+`P`	`Ctrl`+`Shift`+`P`
เปิด `.vscode/settings.json` (Workspace settings)	Preferences: Open Workspace Settings (JSON)	$\emptyset$	$\emptyset$
VS Code extensions	View: Show Extensions	`Shift`+`Command`+`X`	`Ctrl`+`Shift`+`X`
Build $\rm{\LaTeX}$ project	LaTeX Workshop: Build LaTeX project	`Option`+`Command`+`B`	`Ctrl`+`Alt`+`B`
ยกเลิกการ build (Kill compiler process)	LaTeX Workshop: Kill LaTeX compiler process	$\emptyset$	$\emptyset$
ลบไฟล์ auxiliary ต่าง ๆ	LaTeX Workshop: Clean up auxiliary files	`Option`+`Command`+`C`	`Ctrl`+`Alt`+`C`
ดูบันทึกการ compile (Compiler logs)	LaTeX Workshop: View LaTeX compiler logs	`Shift`+`Command`+`U` → LaTeX Compiler	`Ctrl`+`Shift`+`U` → LaTeX Compiler
[Codespaces] หยุดการทำงานของ Codespace	Codespaces: Stop Codespace	$\emptyset$	$\emptyset$
[Dev Containers] เปิด project ใน container	Remote-Containers: Reopen in Container	$\emptyset$	$\emptyset$
[Dev Containers] เปลี่ยนไปใช้งานนอก Dev Container	Dev Containers: Reopen Folder Locally	$\emptyset$	$\emptyset$
[Dev Containers] ปิด project	Remote: Close Remote Connection	$\emptyset$	$\emptyset$

ข้อมูลเพิ่มเติม

LaTeX Workshop (VS Code Extension)

Compiling Features^5

[!CAUTION]
โดยค่าเริ่มต้น Magic Comments จะถูกปิดใช้งานด้วยเหตุผลด้านความปลอดภัย^6

คุณสามารถเลือก $\rm{\LaTeX}$ compiler ได้ผ่าน

Recipe system
Magic Comments โดยเพิ่ม % !TEX program = <program> ใส่ในไฟล์ .tex
โดยค่าเริ่มต้น คุณจะไม่สามารถใช้ feature นี้ได้ ด้วยเหตุผลด้านความปลอดภัย แต่ถ้าคุณยังคงต้องการใช้ Magic Comments ให้ตั้งค่าดังต่อไปนี้

ในไฟล์ .vscode/settings.json
```
{
...

"latex-workshop.latex.build.forceRecipeUsage": false,

...
}
```

[^3]: https://containers.dev/,
https://code.visualstudio.com/docs/devcontainers/containers

[^4]: https://code.visualstudio.com/docs/getstarted/keybindings,
https://github.com/James-Yu/LaTeX-Workshop/wiki/Snippets

naiithink / latex-th

readme