Skip to content

reference

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

reference

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
README.md
README.md
 
 
textutil-manpage.txt
textutil-manpage.txt
 
 

README.md

Reference Repos

外部參考資料索引。這個資料夾本身被 .gitignore 忽略(見 repo root .gitignore reference/),只有這份 README.md 進版控,讓任何 clone macdoc 的人知道要去哪裡把這些參考資料拉下來。

快速安裝

cd reference/
git clone https://github.com/dolanmiu/docx.git docx-js
git clone https://github.com/python-openxml/python-docx.git
git clone https://github.com/ml-explore/mlx-swift-lm.git
git clone https://github.com/jgm/pandoc.git
git clone https://github.com/apple/swift-argument-parser.git
# textutil-manpage.txt 已在版控中

索引

路徑 類型 Upstream 用途
docx-js/ git repo https://github.com/dolanmiu/docx Node.js OOXML 函式庫。word-builder-swift 是其 1:1 Swift 移植,寫新 API 前先看 JS 對應實作。典範:typed builder
python-docx/ git repo https://github.com/python-openxml/python-docx Python + lxml 的 OOXML 函式庫。典範:tree-backed wrapper——每個 Document / Paragraph / Run 包一個 lxml _Element,typed accessor 讀寫該 element。word-aligned-state-sync 的 Phase 1 (typed views as tree projections) 直接對照它。詳見 docs/docx-libraries-comparison.md
mlx-swift-lm/ git repo https://github.com/ml-explore/mlx-swift-lm Apple MLX Swift LLM runtime。pdf-to-latex-swift Phase 1 的 local GLM-OCR backend 用它載模型
pandoc/ git repo https://github.com/jgm/pandoc Haskell 文件轉換工具。macdoc 不依賴 pandoc,純粹參考它怎麼處理邊界情況(複雜 table、field、footnote 跨段落)
swift-argument-parser/ git repo https://github.com/apple/swift-argument-parser Apple 官方 CLI 解析器。macdoc CLI 已是使用者,這裡留一份方便查 source-level 行為(尤其是 subcommand dispatch、ExitCode)
textutil-manpage.txt 單檔 textutil(1) macOS man page macOS 內建 textutil 的 manual。macdoc convert 的 CLI 語法對齊 textutil(見 .claude/rules/cli-design/textutil-compat.md),改 CLI 前對一下

用途與 macdoc 的對照

docx-js → word-builder-swift

word-builder-swift 的設計原則是「1:1 mirror of docx.js 9.6.x」。寫 Paragraph、Table、Run、SectionProperties 等 builder API 時,先看 docx-js/src/file/<component> 對應的 TypeScript 類別,確認參數名、chain 行為、預設值。

關鍵參考路徑:

  • docx-js/src/file/document/ — 文件根結構
  • docx-js/src/file/paragraph/ — 段落 builder
  • docx-js/src/file/table/ — 表格(含 merge 邏輯)
  • docx-js/src/file/drawing/ — 圖片 anchor/inline

python-docx → ooxml-swift Phase 1 設計對照

word-aligned-state-sync Phase 1 要把 Paragraph / Run / Table / SectionProperties 從「typed model with parsed children」改成「typed view over shared XmlNode tree + op emitter on mutation」。python-docx 多年用 lxml-tree-backed wrapper 走過同樣的路,是最直接的參考實作。

關鍵參考路徑:

  • python-docx/src/docx/oxml/ — XML element 類別(對應我們的 Tree/)
  • python-docx/src/docx/oxml/parser.py — element-class registration / lxml parser hook
  • python-docx/src/docx/document.py — top-level Document API
  • python-docx/src/docx/blkcntnr.py — block container 抽象(對應未來 BodyChildren)
  • python-docx/src/docx/text/paragraph.py — typed wrapper 案例(怎麼從 lxml element 推 typed API)
  • python-docx/src/docx/comments.py — comment 處理(macdoc Phase 1 的 Comment 重寫對照組)

注意:python-docx 沒有 op log,直接 mutate lxml tree。macdoc 的 op log 是 differentiator——對照 python-docx 看「沒有 op log 怎麼處理同步」就會理解我們為什麼要加。

mlx-swift-lm → pdf-to-latex-swift / ocr-swift

ocr-swift 的 MLX backend 直接 import MLXLMCommon。要改 sampling、streaming、tokenizer 行為前先看:

  • mlx-swift-lm/Libraries/MLXLMCommon/ — 共用 protocol
  • mlx-swift-lm/Libraries/MLXLLM/ — LLM runtime
  • mlx-swift-lm/Libraries/MLXVLM/ — vision-language model(GLM-OCR 是 VLM)

pandoc → 格式轉換邊界情境

不直接使用 pandoc 產出。純粹當「黃金對照」——寫 word-to-md / html-to-md / pdf-to-md 遇到詭異輸入(nested table、複雜 list、cross-reference)時,丟同一份檔案給 pandoc 看它怎麼處理,再決定 macdoc 要不要跟進。

關鍵參考路徑:

  • pandoc/src/Text/Pandoc/Readers/Docx.hs — Word 讀取邏輯
  • pandoc/src/Text/Pandoc/Readers/HTML.hs — HTML 讀取邏輯
  • pandoc/src/Text/Pandoc/Writers/Markdown.hs — Markdown 輸出邏輯

swift-argument-parser → macdoc CLI

macdoc 的 Sources/MacDocCLI/ 全部基於 ArgumentParser。遇到奇怪行為(subcommand completion、async command、ValidationError 訊息控制)時查:

  • swift-argument-parser/Sources/ArgumentParser/Parsable Types/ — ParsableCommand / AsyncParsableCommand
  • swift-argument-parser/Sources/ArgumentParser/Parsable Properties/ — @Option / @Argument / @Flag

textutil-manpage → CLI 語法對齊

macdoc 的 convert 子命令語法刻意跟 macOS 內建 textutil 靠攏,為的是讓「已經會 textutil」的使用者零學習成本。改 convert 入口前對照這份 man page 確認語義一致:

  • -convert <format> ↔ macdoc convert --to <format>
  • -output <file> ↔ macdoc convert --output <file>
  • -stdout ↔ macdoc convert --stdout
  • -cat ↔(不支援,合併多檔不在 scope 內)

詳見 .claude/rules/cli-design/textutil-compat.md。

外部官方規範連結(非本地 clone)

實作 OOXML / OMML / DrawingML 時常查的官方規範,集中列這裡方便開新視窗。

OOXML 規範

Microsoft 文件

Office.js:Word 物件模型對照

Office.js 是 Word 本體暴露的 JavaScript API,直接反映 OOXML 的能力面。che-word-mcp 的功能擴充 roadmap(見 PsychQuant/che-word-mcp#43)就是以 Office.js 為鏡整理出 20 項可擴充 OOXML 功能——實作新功能前先查 Office.js 對應的物件,對照 Word 本體如何暴露該能力再決定 Swift API 設計。

Office.js vs Common API:Office.js 其實是兩個 object model——Word-specific(Word.*)+ Common API(Office.*)。macdoc 關心的只有前者(OOXML 功能),Common API(dialog、UI、settings)不對映 OOXML,不參考。

核心參考

常用類別深入

實驗與範例

  • Script Lab — Word 內建的互動式 Office.js playground。實作新功能前先在這裡跑 Office.js 看 Word 實際行為,再決定 Swift 怎麼做
  • Office Add-ins 範例程式庫 — Script Lab 可直接 import 的 snippets,找 Word/ 資料夾
  • Word add-in 教學 — 官方 hands-on tutorial

Issue #43 尚未納入 roadmap 但 Office.js 有暴露的類別(未來 sub-issue 候選)

  • Word.Annotation — 段落註記(Word 2021+,不是 Comment)
  • Word.Bibliography — 參考文獻源管理(跟 che-zotero-mcp 生態可能整合點)
  • Word.TableOfContents / Word.Index — 目錄與索引的專屬類別(issue #43 §5 只談 TOC field,沒涵蓋這層 API)
  • Word.Coauthor / Word.Conflict / Word.CoauthoringLock — 即時協作(Word Online,多半跟 macdoc headless 場景無關,優先級最低)

其他 OOXML 函式庫(非 clone,線上對照)

除錯工具

PDF / OCR / 其他

新增條目時的約定

把新東西加到這份 README 的同時:

  1. 是 git repo → cd reference && git clone <upstream> ,並在上方「快速安裝」與「索引」兩節補一行
  2. 是單檔 → 直接放 reference/ 根目錄(像 textutil-manpage.txt),索引補一行
  3. 是官方網頁連結 → 只更新「外部官方規範連結」那節,不用動 clone

記得 commit 的是 reference/README.md,不要把 clone 的 repo commit 進來(.gitignore 會擋,但加 -f 會繞過)。