YuShenLiu06/yushen-skills

latex-pdf — 專業 LaTeX PDF 排版指南

目標不是「能編譯」，而是讀者拿起 PDF 就覺得專業。 交付以內容與實際頁面為準；編譯成功只證明編譯完成，不能替代視覺驗收。

目錄

1. 核心理念
2. 引擎選擇
3. 編譯策略
4. 可讀性排版原則
5. 工作流
6. 坑速查

---

核心理念

排版遵循兩個檢查目標，不依賴另一個技能才能運行：

① 排版服務於閱讀 — 每個排版決策都回答「這幫讀者更好地理解了嗎」。 如果刪掉一個設置後閱讀體驗不變，那它不需要存在。

② 克制即專業 — 刪掉所有不傳遞資訊的視覺元素。 裝飾性線條、底紋、彩色框——大部分該刪。專業的排版「看起來毫不費力」， 而業餘的排版往往「看起來很努力但很亂」。

詳細的可讀性原則映射見 readability-principles。

---

引擎選擇

選錯引擎是最常見的錯誤，尤其是中文內容用 pdflatex。

有中文/日文/韓文？
├─ 是 → xelatex（+ ctex 包）
│        （lualatex 也行，但編譯更慢）
└─ 否 → 需要系統字型？
         ├─ 是 → xelatex 或 lualatex（+ fontspec）
         └─ 否 → pdflatex（最快、最相容）

新建 CJK 文件優先 XeLaTeX 或 LuaLaTeX，並核對實際字型支援。已有可用的 pdfLaTeX/CJK 模板不應無故替換；fandol 不適用於普通 pdfLaTeX 路徑。

引擎	優勢	劣勢	適用場景
pdflatex	最快、最穩定、生態最廣	不支援 Unicode 原生、不能用系統字型	純英文文件
xelatex	原生 Unicode、系統字型、CJK 友好	較慢	中文文件預設選擇
lualatex	最強大的字型處理、可嵌入 Lua	最慢	需要進階排版功能

---

編譯策略

先檢查來源與執行邊界

編譯前靜態檢查 .tex、被引入的 .sty/.cls、建置配置及附件路徑，留意檔案讀寫、外部命令和 Lua 等執行能力。靜態檢查不等於安全證明。對不可信專案，使用無私有檔案、無網路且限制寫入、執行時間和資源的隔離環境；沒有合適隔離時停止編譯並報告，不在個人環境試跑。

預設禁用 shell-escape，不為了 minted 或圖形外部化自動放開。執行 latexmk 時用 -norc 避免自動載入系統、使用者或專案 rc；其他建置腳本和外部輔助程式另行審閱。安裝、聯網取包或修改環境須在已有授權內；未覆蓋時先取得批准。

複用適合的編譯鏈

已有專案沿用適用的建置方式；需要自動處理多遍編譯與參考文獻時可用 latexmk。以下範例只針對已檢查的輸入，在允許的工作目錄執行：

# xelatex 文件（中文預設）
latexmk -norc -xelatex -latexoption=-no-shell-escape -interaction=nonstopmode -halt-on-error main.tex

# pdflatex 文件
latexmk -norc -pdf -latexoption=-no-shell-escape -interaction=nonstopmode -halt-on-error main.tex

# 清理輔助檔案
latexmk -norc -c

參數說明：

• -interaction=nonstopmode：遇錯不暫停等待輸入（腳本環境必需）
• -halt-on-error：第一個錯誤就停止，方便定位問題

biber（參考文獻）

需要參考文獻時，核對 latexmk 計畫呼叫的 biber/BibTeX 與輸入，允許後再執行；不要把自動偵測當作額外執行權限。

---

可讀性排版原則

以下是核心原則摘要，詳細映射和程式碼範例見 readability-principles。

頁面幾何

目標每行 50-75 字元（66 為理想值，TeX 預設恰好）。

\usepackage{geometry}
\geometry{a4paper, margin=2.5cm}
% 中文每字元約為英文 2 倍寬，35 中文字/行 ≈ 70 英文字元/行

表格

常規資料表優先 booktabs 的無豎線樣式；使用者、期刊或機構模板另有要求時保留其規範：

\usepackage{booktabs}
\begin{tabular}{lrr}
    \toprule
    指標 & 2024 & 2025 \\
    \midrule
    營收 & 120 & 150 \\
    \bottomrule
\end{tabular}

booktabs 設計前提就是無豎線——有豎線時橫線間距會斷裂，這不是 bug 是 feature。

間距系統

段落分隔二選一，不要混用：

% 方案 A：首行縮排（學術文件、ctex 預設）
\setlength{\parindent}{2em}

% 方案 B：段間距（技術文件、報告）
\setlength{\parindent}{0pt}
\setlength{\parskip}{0.5\baselineskip}

字型

正文用襯線（閱讀舒適），程式碼用等寬。xelatex/lualatex 用 fontspec 設定系統字型：

\usepackage{fontspec}
\setmainfont{TeX Gyre Termes}[Ligatures=TeX]
\setmonofont{TeX Gyre Cursor}

microtype

幾乎免費的品質提升——字距微調讓正文更整齊：

\usepackage{microtype}
% 注意：xelatex 下只有 protrusion（無 font expansion），但仍值得載入

孤行/寡行

防止段落首行或尾行單獨出現在頁面邊界：

\widowpenalty=10000
\clubpenalty=10000

程式碼高亮

預設用 listings（無外部依賴）。minted 品質更高但需要 Python + Pygments/latexminted：

\usepackage{listings}
\usepackage{xcolor}

\lstset{
    basicstyle=\ttfamily\small,
    keywordstyle=\color{blue!70!black},
    commentstyle=\color{gray},
    stringstyle=\color{green!50!black},
    numbers=left,
    numberstyle=\tiny\color{gray},
    frame=none,
    breaklines=true,
    showstringspaces=false,
}

---

工作流

面向第一次使用此工作流的人。

Step 0: 環境偵測

僅在需要本機編譯且現有工具資訊不足時偵測。先讀取 偵測腳本，確認其呼叫的是可信 PATH 程式且符合現有權限；它只報告，不安裝或修改設定。

從本次實際讀取的 SKILL.md 的絕對父目錄解析 skill_root，不要假設目前工作目錄是技能目錄，再執行：

bash "$skill_root/scripts/check_latex_env.sh"

缺失元件與偵測失敗分開報告。只安裝任務實際需要且已獲授權的依賴；無授權時給出缺口或已有替代。詳細步驟按需讀 環境偵測指南。

Step 1: 理解需求

確認：

• 文件類型：論文 / 報告 / 履歷 / 幻燈片 / 通用
• 語言：中文 / 英文 / 混排
• 讀者：學術 / 商業 / 技術 / 大眾
• 特殊需求：參考文獻 / 程式碼區塊 / 數學公式 / 資料圖表

Step 2: 引擎選擇

按上面的引擎選擇決策樹確定。中文 → xelatex 是最常見選擇。

Step 3: 生成 .tex

應用可讀性排版原則，遵循 package-guide 的標準載入順序模板。

Step 4: 編譯

latexmk -norc -xelatex -latexoption=-no-shell-escape -interaction=nonstopmode -halt-on-error main.tex

Step 5: 檢查日誌

打開 main.log，搜尋 Warning 和 Overfull/Underfull：

• Overfull hbox → 定位溢出的文字、公式或欄寬，檢查實際頁面並局部修復；不以全域 \sloppy 掩蓋問題
• Underfull hbox → 行太鬆，通常無害
• Font shape warning → 字型形狀不可用，檢查 fontspec 設定
• Undefined references → 需要再編譯一遍（latexmk 應已自動處理）

修復影響交付的警告，例如缺字、未解析引用和可見溢出；無害或受模板約束的警告說明理由，不強求所有 warning 為零。

Step 6: 實際頁面檢查與交付

渲染或開啟實際 PDF，檢查頁數、缺字、裁切、表格/公式/程式碼、連結、書籤及相關無障礙要求；按需檢查字型嵌入與可複製文字。修復後重新編譯並複查受影響頁面。無法渲染時明確標記「視覺未驗證」，不把編譯成功寫成頁面驗收通過。

輸出實際生成並核對的檔案：

1. PDF — 最終交付物
2. .tex 原始檔與所需本地資源 — 保留可複現的入口、實際命令、編譯結果和未驗證項。

evals/evals.json 是評估用資料，不是執行指令；僅在測試本技能時讀取。

---

坑速查

遇到問題時，按類型查閱：

問題類型	查閱檔案	常見症狀
編譯錯誤	common-pitfalls §編譯錯誤 Top 10	Undefined control sequence、Missing $、卡住
編碼/字元	common-pitfalls §編碼與字元	非 ASCII 報錯、智慧引號、中文標點間距
浮動體	common-pitfalls §浮動體	圖表跑到文件末尾
表格	common-pitfalls §表格	欄寬溢出、跨頁
字型	common-pitfalls §字型	系統字型找不到、CJK 不生效
包衝突	package-guide §包衝突矩陣	Option clash、功能異常
載入順序	package-guide §載入順序規則	書籤錯亂、連結斷裂
排版品質	readability-principles	文件看起來「業餘」
環境問題	environment-check	命令找不到、權限錯誤
ctex 字型	environment-check §常見環境問題 §6	fontset 'fandol' is unavailable

快速診斷清單

編譯失敗時按此順序排查：

1. ✅ 用了正確的引擎？（中文 → xelatex）
2. ✅ 用了 latexmk？（自動處理多遍編譯和 biber）
3. ✅ 用了 -interaction=nonstopmode？（不會卡在互動模式）
4. ✅ 包載入順序符合目前文件類及包的實際約束？（通常 hyperref 靠後，cleveref 隨後）
5. ✅ 所有 \begin{...} 都有對應的 \end{...}？
6. ✅ 所有 { 都有對應的 }？
7. ✅ 圖片路徑正確？（\graphicspath 設定搜尋路徑）
8. ✅ 包都裝了？（kpsewhich <pkg>.sty 檢查）
9. ✅ 中文文件用了 ctex 且指定了正確的 fontset？
10. ✅ 查看日誌末尾——LaTeX 的錯誤資訊通常指向真正的問題行