Handout Remake

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">。

檔案

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

環境準備

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 個漢字。