本文件是《ACPI ASL 從零到實戰》各模組撰寫者的統一規範。 動筆前必讀三個檔案：

  1. 本指南
  2. acpibook.sty — 所有可用的巨集與環境定義
  3. modules/module01.tex — 品質與風格標竿（exemplar），你的輸出必須與它同風格

專案結構

main.tex                 主檔（勿修改）
acpibook.sty             樣式檔（勿修改）
harness.tex              單模組編譯測試框架（勿修改）
modules/moduleNN.tex     各模組內容（你要寫的檔案）
modules/projects.tex     實戰專案

章節編號對照表（固定，不可變動）

Module 檔案 章 Part 標題 難度
1 module01.tex 1 ACPI 基礎與架構 1
2 module02.tex 2–3 ASL、AML 與 ACPI Namespace 2
3 module03.tex 4–7 ASL 基本語法 2
4 module04.tex 8 Device 與硬體描述 3
5 module05.tex 9–11 OperationRegion 與 Field 3
6 module06.tex 12–14 Control Method 3
7 module07.tex 15–17 Power Management 4
8 module08.tex 18–20 DSDT / SSDT 實戰 4
9 module09.tex 21 iASL Toolchain 4
10 module10.tex 22–24 Linux ACPI Debugging 4
11 module11.tex 25 進階整合：ACPI、C/C++ 與 Linux Kernel 5
12 projects.tex 26–30 實戰專案 5

正文中提到其他章節時，直接寫「第 9 章」「Module 7」這種文字（編號固定）， 不要跨檔案使用 \ref。

檔案骨架

每個模組檔案的結構：

% ============================================================
% Module N：標題（第 X–Y 章）
% ============================================================
\acpipart{Part 標題}{難度數字 1-5}{模組簡介，2–4 句話，說明本模組解決什麼問題、學完能做什麼。}

\chapter{章標題}
\label{ch:唯一標籤}

一到兩段導言（不放在任何框裡）：為什麼需要本章、與前一章的銜接。

\begin{goalbox}
\begin{itemize}
  \item 具體、可檢驗的學習目標（4–6 條，用「說明／寫出／畫出／除錯」等動詞開頭）。
\end{itemize}
\end{goalbox}

\section{...}    % 正文若干節
...

% 每章固定以這兩個框收尾：
\begin{keybox}[本章重點回顧]
\begin{itemize} 4–6 條重點 \end{itemize}
\end{keybox}

\begin{exbox}
\begin{enumerate} 3–5 題，由淺入深，最後一題動手實作 \end{enumerate}
\end{exbox}

可用環境與巨集（cookbook）

教學彩框（皆可加選用子標題 [子標題]）

\begin{keybox}[OSPM 的分工] ... \end{keybox}   % 核心觀念（藍）
\begin{notebox} ... \end{notebox}              % 補充說明（青）
\begin{warnbox}[常見誤解] ... \end{warnbox}    % 注意（橘）
\begin{exbox} ... \end{exbox}                  % 動手練習（綠）
\begin{labbox}[逐步操作] ... \end{labbox}      % Lab 實作步驟（青藍）
\begin{goalbox} ... \end{goalbox}              % 本章學習目標（紫，無選用參數）

禁止把 asl/shell/clang/asciitree 程式碼環境放進任何彩框內。 框內可用 \code{...}、itemize、enumerate、粗體。

程式碼環境（都支援 [title={...}]）

\begin{asl}[title={範例：test.dsl}]      % ASL 程式碼（關鍵字自動上色）
DefinitionBlock ("test.aml", "SSDT", 2, "DEMO", "TEST", 0x00000001)
{
    ...
}
\end{asl}

\begin{shell}[title={...}]   % 終端機指令與輸出
$ iasl test.dsl
\end{shell}

\begin{clang}[title={...}]   % C 語言（Linux kernel / driver 範例）
\end{clang}

\begin{asciitree}[title={...}]   % Namespace 樹、表鏈結構等 ASCII 圖
\
├── _SB_
│   ├── PCI0
│   └── EC0_
└── _TZ_
\end{asciitree}

規則：

  • 程式碼環境內是 verbatim，底線、反斜線直接寫，不要跳脫。
  • asl/shell/clang 內只能有 ASCII；註解一律英文。
  • asciitree 內可以用中文與這些字元：│ ├ └ ─ ← ↓ →（已驗證可渲染）。
  • 每個 ASL 範例必須是語法正確、iasl 可編譯的（或明確標註為片段）。
  • 行寬 ≤ 72 字元，縮排 4 空格。

流程圖

\begin{vflow}[4.5mm]          % 垂直流程；參數 = 節點間距（可省略）
\fnode{Hardware}
\fnode{BIOS / UEFI}
\fnodel{iasl 編譯}{AML}       % 箭頭旁帶標籤
\fnode[flownodealt]{重點節點} % 金色變體
\end{vflow}

\begin{hflow}                  % 水平流程（節點自動縮小）
\fnode{ASL}
\fnodel[above]{iasl}{AML}     % 水平流程的標籤放 above
\end{hflow}
  • 節點文字可含中文；可用 \\ 換行（例如加 {\scriptsize 副標}）。
  • 垂直流程 ≤ 9 個節點；水平流程 ≤ 5 個節點以免超寬。
  • 節點內不要放引號 "。

行內巨集

\code{\_HID}                  % 行內程式碼；底線必須跳脫成 \_
\nspath{\_SB.PCI0.LPCB}       % 帶根反斜線的 namespace 路徑（自動加 \）
\keyterm{OSPM}                % 首次出現的關鍵術語（藍色粗體）

表格（統一 booktabs 風格）

\begin{center}
\small
\begin{tabular}{llL{6.8cm}}   % L{寬度} = 自動換行的靠左欄
\toprule
\rowcolor{acpiblue!10}
\textbf{欄一} & \textbf{欄二} & \textbf{說明} \\
\midrule
... & ... & ... \\
\bottomrule
\end{tabular}
\end{center}

不要用 \begin{table} 浮動環境，一律用上面的 center 寫法。

LaTeX 撰寫鐵律（違反會編譯失敗）

  1. 正文（非程式碼環境）中：_ 必須寫成 \_，& 寫成 \&， % 寫成 \%，# 寫成 \#。這是最常見的錯誤來源。
  2. 正文中不可出現 Unicode 箭頭（→ ↓ ←），請用 $\to$ 或改寫文字； asciitree 環境內例外。
  3. 反斜線路徑在正文中一律用 \nspath{\_SB.PCI0}，不要手寫 \textbackslash。
  4. 不可 \usepackage、不可定義新巨集、不可修改 acpibook.sty。
  5. \part 不可直接使用，只能用 \acpipart{...}{...}{...}（每檔一次，除非該檔含兩個模組）。
  6. 中文引號用「」；破折號用——；省略號用……。
  7. \label 加上模組前綴避免衝突（如 ch:namespace、ch:field）。
  8. 每個環境的 \begin/\end 務必配對；itemize/enumerate 內的 item 文字若含 \code{} 沒問題，但不要在 item 內開程式碼環境。

內容風格

  • 語言：台灣慣用的繁體中文；技術名詞保留英文 （Namespace、Method、Device、OperationRegion、Interpreter、bring-up……）。
  • 口吻比照 module01.tex：像資深韌體工程師帶新人，先講「為什麼」再講「怎麼做」， 用具體場景（筆電電池、上蓋開關、I2C 溫度感測器）當例子。
  • 每章節奏：觀念講解 → 完整範例 → 逐行拆解 → 常見陷阱 → 練習。
  • 每章至少：1 張流程圖或 asciitree、1 個完整 ASL 範例、1 個 warnbox（常見錯誤）、 1 個 notebox（規格或實務補充）。
  • 逐行拆解：程式碼列出後，用文字或 itemize 解釋關鍵行在做什麼、為什麼這樣寫。
  • 每章篇幅目標：排版後 5–8 頁（約 250–420 行 LaTeX）。
  • 內容以 ACPI 6.5 與 ACPICA 現行工具為準；新舊語法（legacy operator 與 ASL 2.0 symbolic operator）都要教，並說明實務上何時會遇到哪種。

自我驗證（必做）

寫完後，在專案根目錄用 harness 單獨編譯你的檔案（jobname 用你的模組號， 避免與其他人衝突）：

xelatex -jobname=chk02 -interaction=nonstopmode "\def\modfile{modules/module02}\input{harness.tex}"
rg -n "^!" chk02.log            # 必須無輸出（無錯誤）
rg -n "Missing character" chk02.log   # 必須無輸出（無缺字）

若一個檔案含兩個模組（如 module04 + module05），兩個檔案都要各自通過。 編譯錯誤必須自己修到乾淨才算完成。完成後刪除 chkNN.* 產物（rm -f chkNN.*）。