---
name: handout-remake
description: 把上課教材（PPT、PDF、筆記）重製成 iPad 上好讀、可手寫的深色 PDF 講義：從零講起、圖解、例題、練習與書寫區。使用者丟課程講義並要求做講義、教材、好讀版，或說「幫我整理這章」時使用，適用各種工程學科。
---

# iPad 深色講義製作 SOP

把老師的上課教材重新教一次，做成一份在 11 吋 iPad 直向閱讀、可以用 Apple Pencil 作答的深色 PDF。
這份文件是規則（怎麼教、怎麼排、怎麼畫）；排版與建置用的檔案放在本 skill 資料夾（這份 SKILL.md 所在的資料夾），見〈檔案〉。

讀者設定：對這門課幾乎零基礎；用台灣正體中文；最在意資訊排版清楚，討厭花俏和雜亂的層級；喜歡生活例子和動手練習。

## 流程

1. **讀懂來源**。PPT 用 `soffice --headless --convert-to pdf` 轉成 PDF，再用 `pdftotext -layout` 取文字、`pdftoppm -r 40 -png` 轉縮圖並實際看過每一頁（公式和圖常常只存在圖片裡）。來源檔放在獨立資料夾，不要在裡面執行程式。
2. **決定範圍並切段**。一份講義只教一個小節，大約對應 6–12 張投影片、成品 12–18 頁。範圍以投影片為準，但不要逐張翻譯：先自己弄懂，再依「初學者要先知道什麼」重新安排順序。一章太長就拆成多份（例如「上」「下」），並在回覆中說明這份涵蓋到哪一頁。切成 3–6 個段落，每個段落只講一個概念。
3. **寫內容**，遵守〈教學規則〉。
4. **畫圖**，遵守〈圖解規則〉。
5. **排成 HTML**。照〈環境準備〉建立工作資料夾並複製檔案，然後複製 `template.html` 改寫內容。一個 `<section class="page">` 就是一頁，手動分頁。
6. **建置與檢查**。`node build.mjs 講義.html 講義.pdf`，有任何「溢出」就調整內容或分頁直到為零。再用 `pdftoppm -r 80 -png` 轉圖，逐頁用 Read 看過，照〈交付前檢查〉走一遍。
7. **驗算與交付**。所有例題、練習、解答的數字用程式重算一次；生活例子裡的事實不確定就查證。存成 `課名_節次_標題.pdf` 交給使用者，回覆只需一兩句說明涵蓋範圍，以及任何你不確定或自行補充的地方。

## 教學規則

**每個段落的順序**：生活情境或動機 → 白話定義（術語中英對照）→ 圖解 → 公式 → 例題。每 2–3 個段落之後放一頁練習，**解答固定放在練習的下一頁**。整份最後依序是：本節重點、公式一覽、自我檢查、術語對照、下一節預告。

- **從零講起**。假設讀者只會國高中數學。每個新名詞出現前先有情境，出現時立刻定義，不要用還沒教的詞解釋新詞。
- **術語中英對照**。第一次出現寫成 `<b>中文</b> <span class="en">english term</span>`，之後用中文。公式卡下方附英文原式，題目中的關鍵量保留英文名，方便對照考卷與課本。
- **生活連結要具體**。說出這個概念用在哪個真實的產品或場景，並帶數字。舉不出好例子就不要硬舉。
- **例題一步一步做**。多步驟的題目先列「已知／要求／想法」，再用編號步驟解；每步有一句小標說明這步在做什麼，最後一步固定是「檢查答案合不合理」。投影片上有的例題優先採用並標明出處頁。
- **練習有層次**。每頁最多 3 題，標上「基本／觀念／變化／綜合」。練習不能只是把例題換數字，至少一題要換問法。每題配書寫區。
- **解答頁**：先給用螢光標出的最終答案，再給完整步驟；頁尾放「寫錯了？回頭看這裡」，指向該複習的頁碼。
- **動手做**（可選）。當概念能在電腦或手邊工具上親眼看到時（終端機指令、幾行 Python、試算表、計算機），用編號步驟帶著做，每步寫出「應該會看到什麼」。沒有實際執行過的輸出要註明是示意。
- **語氣**。白話、短句、直接講結論。不寫客套和過場，不用「不是……而是……」這類繞路的句型。
- **不確定就說**。投影片有錯或語焉不詳時照正確的教，並在回覆中告訴使用者；超出投影片的補充要有必要性。

**中英混排**：漢字與英數之間加半形空格；全形標點旁不加空格；引號用「」和『』；數字與單位之間加空格（`10 秒`、`4 GHz`），百分比和度數不加（`25%`）；專有名詞大小寫正確。

## 視覺規則

頁面是 834 × 1194 pt，等於 11 吋 iPad 直向的螢幕點數，所以 CSS 的 pt 就是螢幕上的 pt，不需要縮放。所有尺寸都寫在 `handout.css` 的變數裡，不要在 HTML 內另外寫死字級、顏色或間距。

- **內文** 18pt、行高 1.8、每行約 37 個漢字。字重只有 400 和 600。
- **深色**：底色 `#1c1c1e`、內文 `#e8e8ed`，不用純黑純白。
- **文字只有三種顏色**：內文色、次要灰、一個藍色強調色。鮮豔色只能出現在圖解、公式色塊和提示框的小標。
- **粗體只給第一次出現的術語**；每頁最多一處 `<mark>` 螢光，留給最關鍵的一句。
- **每頁最多三層**：頁標題 → 區塊（圖、公式、例題、提示框）→ 內文。新的段落一律從新的一頁開始，頁標題上方用 `.eyebrow` 標「段落 N」與投影片頁碼。
- **內容靠上排，下方留白沒關係**，不要為了填滿而加東西；也不要把一頁塞到剩餘空間低於 0。
- **元件只有這些**，不要自創新樣式：術語定義 `.terms`、圖解 `figure > .panel`、公式卡 `.formula`、例題 `.example`、練習 `.practice` 加書寫區 `.write`、提示框 `.note`、表格、程式碼 `pre.code`、解答 `.answer`、重點 `.keypoints`、公式一覽 `.fsheet`、自我檢查 `.check`。
- **提示框只有三種**，一頁最多兩個：`.note.life`（生活中）、`.note.warn`（留意：容易搞錯的地方）、`.note.lab`（動手做的補充）。沒有側邊色條，靠淡色底與彩色小標區分。
- **表格只有橫線**；成對的概念用 `.terms` 並排比較。
- **程式碼**用等寬字型 JetBrains Mono，並關閉連字（`==`、`!=`、`>=`、`<=` 要照原樣顯示，不能被合成 ≠、≥ 這類符號）；程式碼裡的中文註解由字型堆疊中的 Noto Sans TC 顯示。這兩點已寫在 `handout.css`，不要在 HTML 另外處理。
- 標題以「開頭時加 `class="hang"`，讓引號懸掛、文字對齊版心。

**版面預算**（每頁可用高度 1062pt）：內文一行 32pt；頁標題區約 80pt；三行的提示框約 130pt；圖解約為 SVG 高度加 90pt；書寫區高度依題目選 164／200／260pt，一頁三題的書寫區總和不要超過 590pt。

## 圖解規則

適合畫圖的時機：有先後順序、有結構或層次、要比較大小、數量之間有關係、隨時間變化。只是把文字放進框框裡不算圖解，不要畫。

- 用行內 SVG，`viewBox` 寬度固定 626，放在 `.panel` 裡，這樣 SVG 的單位就等於 pt。文字 13–15，標題類用 600。
- **顏色一律用變數**（`fill="var(--blue)"`），不寫色碼。每個色相有三階：`--x` 是圖形本體的鮮色，`--x-tint` 是深色的淡底，`--x-ink` 是放在深底上的亮色文字與線條。可用色相：blue、orange、green、pink、purple、teal、yellow；中性用 `--text`、`--text-2`、`--axis`、`--line-strong`、`--gray-fill`、`--gray-soft`。
- **一個顏色只代表一件事**，同一份講義裡跨圖一致，而且和公式色塊用同一套對應（例如某個物理量在公式裡是藍色，圖裡代表它的圖形也是藍色）。圖說要寫出顏色代表什麼。
- 一張圖最多三個色相加灰色。
- **鮮色圖形裡面不放字**；文字放在圖形的上下或旁邊，用對齊或細線連結。
- 扁平風格：圓角 8–10、線寬 1.5、線端圓頭；不用漸層、陰影、立體效果、表情符號。
- 每張圖編號並附一句圖說；內文提到時用「圖 N」。
- 節首頁右上角放一個 220pt 的小圖徽，用圓、圓角矩形、線條這些基本形狀和色盤組成，代表這一節的主題。
- 函數圖形與座標圖：座標軸用 `--axis` 線寬 1.2，曲線用鮮色線寬 2.5–3。真正的資料圖表另外參考 dataviz 技能。

## 公式

- **文字公式**（用中文量名）寫成 `.eq`，每個量包在 `<span class="v blue">` 這類色塊裡，分數用 `.frac`。
- **符號公式**用 KaTeX：行內 `<span class="tex">…</span>`，獨立一行 `<div class="tex">…</div>`，內容是 LaTeX 原始碼（`<`、`&` 要寫成 HTML 實體）。上色用巨集 `\cB{}`、`\cO{}`、`\cG{}`、`\cP{}`、`\cV{}`、`\cT{}`、`\cY{}`，分別是藍、橘、綠、粉紅、紫、青、黃，和色塊同色。
- 重要公式放進 `.formula` 公式卡：第一行文字公式，第二行同色的符號公式，最下面 `.eq-en` 放英文原式。
- 例題步驟裡的算式放在 `<p class="work">`。

## 檔案

| 檔案 | 用途 |
|---|---|
| `assets/handout.css` | 全部樣式與色盤變數 |
| `assets/template.html` | 每種頁面各一頁的骨架。裡面的歐姆定律只是示範元件怎麼用，製作時整段換成該課內容，頁數與段落數依教材調整 |
| `assets/package.json` | 字型與 KaTeX 的固定版本 |
| `scripts/build.mjs` | 渲染 KaTeX、鋪書寫區點陣、檢查每頁溢出、輸出向量 PDF |

這些檔案直接複製使用，不要改寫或重打；需要調整樣式時改 `handout.css` 的變數。有些平台只接受特定副檔名，封包裡的檔案可能多了 `.txt`（例如 `handout.css.txt`），複製到工作資料夾時去掉 `.txt` 即可。

## 環境準備

```bash
SKILL_DIR=<這份 SKILL.md 所在的資料夾>
mkdir -p handout && cd handout
cp "$SKILL_DIR"/assets/{handout.css,template.html,package.json} "$SKILL_DIR"/scripts/build.mjs .
npm install
node build.mjs template.html test.pdf   # 先確認環境能跑
```

`build.mjs` 會自動尋找 Playwright（先找本地，再找 `/opt/npm-tools/node_modules`）；都沒有時執行 `npm i playwright`。字型一定要用 `@fontsource` 的靜態字重版本，改用 variable 版本會讓 PDF 內嵌成 Type 3 字型。

## 交付前檢查

- [ ] `build.mjs` 沒有回報任何溢出
- [ ] 每一頁都轉成圖看過：沒有文字重疊、孤字、被截掉的圖
- [ ] 每個段落都從新的一頁開始；解答在練習的下一頁
- [ ] 術語第一次出現都有英文；最後的術語對照表沒有漏
- [ ] 圖的顏色對應和公式色塊一致，圖說有說明
- [ ] 例題、練習、解答的數字都用程式驗算過
- [ ] `pdffonts` 沒有 Type 3；`pdfimages -list` 是空的（全向量）
- [ ] HTML 裡沒有寫死的色碼（`grep -n '#[0-9a-fA-F]\{6\}' 講義.html` 應該沒有結果）

## 補充

內容較多時，複習的各區塊可以拆成兩頁（重點與公式一頁、自我檢查與術語對照一頁）。若使用者改用其他尺寸的 iPad，只需調整 `handout.css` 的 `--page-w`、`--page-h`、`@page` 與 `build.mjs` 的 viewport，並維持每行 35–40 個漢字。