mgubi/texmacs

TeXmacs 文件

給使用 GNU TeXmacs 的代理程式的實用指南，於轉換講義和演講、編寫樣式套件、審核長數學手稿時收集而來。請保持其活力：將新學到的知識附加到「陷阱」中，並保持 scripts/ 中的指令碼正常運作。專案特定的新增內容應歸入指向此處的獨立本地技能；「慣例（強制）」部分適用於所有情況。 來源：https://github.com/mgubi/texmacs-skill。最後更新：2026-11-04。

保持此技能最新

此技能應以 git clone 方式安裝（通常為 ~/.claude/skills/texmacs）。在處理 TeXmacs 文件前：

• 更新它： 執行 git -C <技能目錄> pull --ff-only（如果 SSH 連線 GitHub 失敗，則從 https://github.com/mgubi/texmacs-skill.git main 拉取）。如果 clone 有未推送的本地更改或提交，請告知使用者，而不是直接覆蓋拉取。
• 回饋貢獻： 當學到關於 TeXmacs 的新知識時，請將其新增於此（通常是「陷阱」，或修復一個指令碼），在 clone 中提交並推送至 GitHub（或若無法推送，則建立 pull request），以便每個安裝都能獲得。專案特定內容保留在專案中。

檔案格式

• .tm 檔案是序列化的樹：內聯 <tag|arg1|arg2>，區塊引數用 <\tag>…</tag>（參數間用 <|tag>），段落由空行分隔，縮排僅用於佈局。字串內部 \<alpha\> 是符號，<less>/<gtr> 是 </>，\| 是文字豎線，<#89AB…> 是十六進位原始資料（嵌入的圖像）。

• 編碼：字串是 Cork (T1) 編碼，而非 UTF-8。 帶重音的拉丁字母大多與 Latin-1 位元組一致（é = 0xE9, à = 0xE0, ö = 0xF6），但例如 en dash = 0x15, em dash = 0x16, § = 0x9F；任何其他 Unicode 字元寫為 <#XXXX>（十六進位碼點）。不要自行編寫 <#XX> 作為獨立標記：它會被讀取為原始資料（請參閱「編寫樣式套件」）。後果：永遠不要使用 UTF-8 工具編輯 .tm 檔案（編輯/寫入工具會拒絕或損壞它）。使用 Python 的 encoding='latin-1', newline='' 進行讀寫，或最好透過下面的 stree 路徑，讓 TeXmacs 寫入檔案。

• 手寫 .tm 檔案：完全複製此骨架。 頂層元素之間必須以空行分隔；沒有空行時，TeXmacs 只保留 <TeXmacs|…> 標頭並靜默丟棄所有其他內容（stree 轉儲是 (document (TeXmacs "2.1.5"))，PDF 是空的，且沒有錯誤）：

  <TeXmacs|2.1.5>
  
  <style|<tuple|article|british>>
  
  <\body>
    第一段包含 <math|x<rsup|2>>。
  
    第二段。
  </body>
  
  <\initial>
    <\collection>
      <associate|font|TeX Gyre Pagella>
    </collection>
  </initial>
  

  在 <\body> 內部，段落（以及任何 <\tag>…</tag> 的區塊）也由空行分隔；單一換行則繼續同一段落。每個區塊標籤獨佔一行關閉，將文字中的符號轉義為 \<alpha\>，文字 <、>、| 轉義為 <less>、<gtr>、\|，並保持檔案為 Cork/Latin-1 編碼（一旦包含非 ASCII 字元，就使用 Python 寫入，而非 printf 或寫入工具）。

• 優先選擇生成而非手寫。 對於超過幾行的內容，請在 Python 中建構 stree（scripts/latex2tm/stree.py）並讓 TeXmacs 序列化它（使用 dump.scm 中的 tm-undump）；或寫入片段，tm-dump 它，然後拼接樹。手寫時，在使用前檢查結果：tm-dump 它並確認 body 有預期數量的段落，或者排版它並確認 PDF 文字非空且完整（mutool draw -F txt）。空或短的 PDF，或包含一個巨大節點的轉儲，表示格式化錯誤，而非 TeXmacs 的錯誤。

• 大檔案：演講稿將圖像嵌入為原始資料（10+ MB）。在讀取前剝離 <#…> 序列：re.sub(r'<#[0-9A-F]{200,}>', '<#HEX>', s)。

無頭執行 TeXmacs

二進位檔 (macOS)：/Applications/TeXmacs.app/Contents/MacOS/TeXmacs；在 Linux 上為 texmacs。已在 2.1.4 和 2.1.5 上測試。scripts/latex2tm/run.sh 儲存路徑；請於該處調整。

• 轉換：TeXmacs -headless -c in.tex out.tm -q（LaTeX 匯入），-c in.tm out.pdf -q（當前緩衝區的 PDF）。
• Scheme：TeXmacs -headless -x "(begin (load \"/abs/dump.scm\") … (quit-TeXmacs))"。 始終將 body 包裹在 (catch #t (lambda () …) (lambda args (display args))) 中，並以 (quit-TeXmacs) 結尾：否則錯誤會使程序永久掛起。在背景執行它並輪詢其 PID（參見 scripts/latex2tm/run.sh）；僅 kill 該 PID — 永遠不要 pkill TeXmacs（使用者可能已開啟 TeXmacs）。
• 無頭執行會將 TeXmacs 自身的狀態寫入 ~/.TeXmacs/system；這是正常的。

可在無頭模式下運作的 Scheme API（scripts/latex2tm/dump.scm）

• (tree-import (string->url f) "texmacs") / "latex"，以及 (tree-export t (string->url f) "texmacs")：檔案 ↔ 樹，無需緩衝區。
• (tree->stree t) / (stree->tree s)：s‑表達式。使用 (call-with-output-file f (lambda (p) (write s p))) 寫入它們 — with-output-to-file 不能在 TeXmacs 的 Guile 中重定向。Guile 將控制字元寫為 \xHH 轉義（由 scripts/latex2tm/stree.py 處理）。
• 排版：(load-buffer u) (switch-to-buffer u) (export-buffer-main u (string->url pdf) "pdf" (list)) — PDF 匯出即是排版。(update-document "all") 在無頭模式下不起作用（它是延遲的空閒命令）；直接呼叫 (generate-all-aux) (update-current-buffer) 以填入目錄/參考文獻，再次匯出，然後 (buffer-pretend-modified u) (buffer-save u) 以儲存 <\references>。新檔案需要在所有參考解析之前，於不同程序中分別進行兩次排版執行，每次執行都需有實際的 PDF 匯出（scripts/latex2tm/typeset.sh）。 始終使用 (list :overwrite) 作為選項進行匯出：在無頭模式下，export-buffer-main 否則會要求確認是否取代現有檔案，無人回應，且匯出將被靜默跳過 (mgubi/texmacs#807)。dump.scm 中的 tm-typeset 和 tm-html 執行了此操作。
• 簡報（螢幕）僅匯出當前螢幕。若要進行視覺檢查，請建立一個預覽副本，將螢幕展平為由 new-page* 分隔的頁面（scripts/latex2tm/preview_slides.py）；交付螢幕版本。
• 使用 mutool draw -r 60 -o p%d.png file.pdf 和 magick montage … -tile 4x1 -geometry +4+4 檢查輸出；使用 mutool draw -F txt -o - file.pdf 檢查文字（計算 ? 以找出未解析的參考）。

HTML 匯出

在 TeXmacs 內部 進行 HTML 自訂：樣式套件（或外掛）設定匯出器的變數並為巨集提供 tmhtml- 渲染；網站透過匯出目錄（tmweb-convert-dir）建立，其中 TEXMACS_HOME_PATH 指向網站的外掛資料夾，並執行 (style-clear-cache)。不要使用指令碼後處理生成的 HTML。

將通用修復收集到一個外掛中（下面稱為 max-html，連結為 ~/.TeXmacs/plugins/max-html），並將文件特定的設定保留在文件的套件中。這樣的外掛包含：

• progs/max-html/fixes.scm，在啟動時載入，修復 MathJax 匯出。公式內的標籤獲取錨點 (#617)，\ring 被寫為 \mathring (#607)，並且 equations-base 被寫為 aligned (#611)。它替換了 (convert html tmhtml) 內部 tmhtml-mathjax-formula* 的綁定（使用 module-variable + variable-set!；內部的輔助函式如 cork->html 透過 module-ref）並使用 tm-define … (former x) 擴展 latex-mathjax。

• max-html 套件（文章）提供帶框定理、列表標籤和內容側面板 div.max-toc。max-html-slides 套件提供幻燈片檢視器和 tmhtml-mytitle/myframed/myframed-2。

• resources/ 包含 max-html.css/js 和 max-html-slides.css/js，以複製到頁面旁。文件套件 <use-package|max-html> 並再次指派整個 html-extra-css 元組（外掛檔案優先）：merge 不起作用，因為匯出器讀取未求值的變數。字型是 CSS 變數（--max-text-font、--max-slide-font）。

• HTML 匯出的通用修復歸入外掛。文件特定內容（字型、favicon、演講巨集）歸入文件的套件。

• 匯出：scripts/latex2tm/dump.scm 中的 (tm-html in out mathjax?)（偏好設定 texmacs->html:mathjax|css|images，然後 (export-buffer-main u (string->url "x.html") "html" (list))）。匯出已排版的 .tm 檔案（儲存的 <\references> 提供編號）。doc.tm#label 連結變為 doc.html#label；圖像變為頁面旁的 <base>-N.png；MathJax 3 來自 jsdelivr。

• 由匯出器讀取的樣式變數（在樣式套件中設定它們）：html-css（取代預設內聯 css），html-extra-css（額外樣式表的元組，保留預設 css），html-extra-javascript-src（元組，延遲），html-extra-javascript，html-head-javascript(-src)，html-head-favicon，html-title，html-doc-title，html-site-version。

• 巨集的 HTML 渲染：在 NAME 旁定義 tmhtml-NAME。 匯出器使用它而非 NAME。用於此的標記輔助函式：html-div-class|class|body（區塊），html-class|class|body（內聯 span），html-style，html-div-style，html-attr，html-tag，html-javascript。這僅適用於在樣式套件中定義的巨集：在文件的 hide-preamble 中指定的巨集在匯出前被展開，並且它們的 tmhtml- 變體被忽略。因此，請將簡報巨集放在套件中。

• 文件旁的套件 foo.ts 在樣式元組列出 foo 時被找到。編輯套件後，呼叫 (style-clear-cache)（TeXmacs 在 ~/.TeXmacs/system/cache 中快取樣式環境），否則將使用舊的定義。

• 目錄（和其他生成的列表）：條目已展開地寫入輔助資料（write 求值其引數），因此 toc-main-*/toc-1…5 周圍的包裝器消失，且它們的 tmhtml- 變體永遠不會被看到。只有外層的 table-of-contents 巨集可以有 tmhtml- 渲染。在展開和匯出後仍存在的標記：<b>（粗體章節），<with|font-size|…> → <font style=…>，font-shape → <i>/小型大寫，color → <font color>；par-left 縮排丟失。每個條目以 <a href="#auto-N">page</a> 結尾。側面板配方（外掛套件 max-html）：tmhtml-table-of-contents → div.max-toc 固定在左側；使用 .max-toc p a[href^="#auto-"] {position:absolute; inset:0; font-size:0} 隱藏並拉伸頁面連結（按 href 選擇：標題中的 eqref 也是連結）；透過使用巢狀 <with|font-size|0.92|…> 重新定義 toc-3…5 並選擇 p:has(> font) 來標記段落級條目。在更改 toc-* 巨集後重新生成目錄（兩次排版執行）。

• 在面板中反白顯示當前章節需要 JavaScript：max-html.js（外掛），透過套件中的 html-extra-javascript-src 附加；它將每個條目的 #auto-N 連結對應到具有該 id 的標題，標記視窗 25% 以上的最後一個標題（p.toc-current，及其粗體父元素 p.toc-current-section）並滾動面板以使其保持可見。

• 帶框定理（Joris van der Hoeven 的網路文章，例如 texmacs.org/joris/fftcomp；模型是 TeXmacs 中的 styles/article/texmacs/tmarticle.ts）：定義 tmhtml-render-theorem → <html-div-class|theorem|<render-enunciation|…>> 和 tmhtml-render-enunciation 搭配 <html-class|enunciation-name|which>；定理、命題、引理、推論和定義使用 render-theorem，而備註和證明使用 render-remark。Joris 的 css (texmacs.org/css/theme-dark-colored.css) 是 .theorem {border: 1px solid; border-left: 1em solid; padding: 0 1em}；柔和的顏色和 .5em 的橫條也效果良好（max-html.css）。這僅影響 HTML；PDF 保持不變。 顏色（也如 Joris 主題中）：h1…h6, strong, b, dt, .enunciation-name 使用柔和的深紅色，MathJax 輸出透過 mjx-container {color: …}；重置 TOC 面板內部的 b。

• HTML 匯出將每一個 enumerate-alpha|Alpha|roman 轉為普通 <ol>（十進位標籤）。修復：tmhtml-enumerate-alpha → <html-div-class|enum-alpha|<enumerate|…>> 加上 .enum-alpha > ol > li::marker {content: "(" counter(list-item, lower-alpha) ") "}。

• MathJax：轉換器將環狀重音符號 <abovering> 寫為 \ring{…}（LaTeX 套件 accents），MathJax 缺少它 (mgubi/texmacs#607)。由外掛修復。頁面級別的替代方案是在 html-extra-javascript 中內聯 MathJax 配置（它在 MathJax <script> 之前執行）：window.MathJax = {tex: {macros: {ring: [String.fromCharCode(92) + 'mathring{#1}', 1]}}}。

• MathJax：equation 內部的 aligned 被 HTML 匯出器預先展開為 equations-base，並作為 \begin{equationsbase} 到達 MathJax (mgubi/texmacs#611)。由外掛修復；頁面級別的替代方案是在該配置中使用 environments: {equationsbase: […aligned…]}。

• 使用 scripts/mathjax-check/ 檢查匯出的所有公式：在暫存 deps/ 資料夾中 npm install [email protected]，然後 python3 extract.py HTMLDIR formulas.json（使用 HTML 解析器：\(t < \infty\) 中的原始 < 是文字，如同在瀏覽器中）和 node check.js deps/node_modules formulas.json。它在不使用 noundefined 套件的情況下渲染每個公式（該套件在瀏覽器中會靜默地以紅色顯示未定義的巨集）並將錯誤分組。它看不到空公式（單獨計算 \(\displaystyle \)）或死連結：同時檢查每個內部 href="…x" 是否有匹配的 id="x"。

• 投影片：寬度為 100% 並由 css max-height 縮小的圖像停留在其段落的左側；使用 div.toggle img.image {display: block; margin: 0 auto} 將其置中。

• 無頭 Firefox：user.js 中的深色模式 content-override 偏好設定未生效；要 ch...

[因長度限制已截斷]