Communitygithub.com

scribus-sla

使用真實 Scribus 引擎建立、填充、編輯和匯出 Scribus .sla 檔案,使輸出(PDF、可填寫 PDF、PDF/X、PNG/JPG、SVG、EPS、PS)與桌面應用程式完全一致。適用於任何 .sla 或 Scribus 相關任務。

scribus-sla 是什麼?

這項技能提供了一個基於真實 Scribus 桌面引擎(預設 1.6.3)的命令列工具,用於處理 .sla 檔案。它會安裝完整的 Scribus 及一個輕量化的 `sla` 指令包裝器,讓您無需手動編寫或近似模擬 Scribus 文件。技能包含一個 `sla` 指令列工具,支援檢查(字型、圖片、佔位符、表單欄位)、匯出為多種格式(PDF、PNG、SVG 等)、填充範本、重新儲存檔案、執行 Scribus Python 腳本、比對 PDF 像素差異、以及管理字型。此工具經過測試,可在 Claude Code、Cursor、Codex 等平台上運作,其輸出的 PDF 與 Scribus 1.6.3 桌面應用程式所匯出的文件進行了逐像素比對,結果完全一致。它能確保逼真的版面呈現,避免因遺失字型或圖片而導致版面位移;處理可填寫 PDF 時,會完整嵌入欄位字型,以確保相容性。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/JessNco/scribus-sla/tree/HEAD

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Scribus .sla 檔案,使用真實 Scribus 處理

永遠不要手動渲染或近似 Scribus 文件,也不要手動編寫整個 .sla 檔案。 此技能會安裝真實的 Scribus(預設 1.6.3)以及一個小型的 sla 指令包裝器。 以這種方式匯出的檔案,已與 Scribus 1.6.3 桌面應用程式匯出的 PDF 進行比對: 11 份文件(純文字、含圖片、可填寫表單)逐像素完全匹配。

1. 安裝(每次連線一次,首次需 2-4 分鐘)

[ -d /opt/sla/kit/.git ] || git clone --depth 1 https://github.com/JessNco/scribus-sla /opt/sla/kit
bash /opt/sla/kit/scripts/setup.sh
  • 其他 Scribus 版本:bash /opt/sla/kit/scripts/setup.sh 1.6.5(也支援 1.6.1、native)。 請比對使用者執行的版本;由引擎儲存的檔案會帶有該引擎的版本編號。
  • 需要 root 權限、apt,以及對 github.com 和 archive.ubuntu.com 的網路存取權。安裝完成時會顯示一行 以 [sla-setup] ready: 開頭的訊息。如果它警告已降級使用其他版本,請告知使用者。
  • 引擎只能存取 /home、/tmp、/mnt、/root 目錄下的檔案。請在這些目錄中操作。

2. 指令

sla inspect FILE.sla -v            # 頁面、字型(已安裝?)、圖片(已找到?)、具名項目、{{佔位符}}、表單欄位
sla export FILE.sla                # 在 .sla 旁產生 PDF,使用文件本身儲存的 PDF 設定
sla export FILE.sla -f pdf,png,svg,eps,ps,jpg --dpi 300 -d OUTDIR --pages 1,3-5
sla export FILE.sla --pdf-version x4 --crop-marks --bleed 8.5      # 印刷用 PDF(x1a, x3, x4;--cmyk;--profile)
sla fill TEMPLATE.sla OUT.sla --set name=Value --text frame_name="New text" --image frame_name=new.png
sla resave IN.sla OUT.sla          # 在 Scribus 中開啟並儲存:證明檔案可載入,並將其標準化
sla run SCRIPT.py [args]           # 執行 Scribus Python(scripter)腳本;這是建立新文件的方式
sla compare A.pdf B.pdf --out DIR  # 像素比對,使用相同的渲染器和 DPI;寫出差異圖片
sla fonts --grep sans              # Scribus 拼寫的精確字型名稱
sla fonts --add FILE_OR_DIR        # 安裝使用者的字型檔案
sla fonts --google "Comic Relief"  # 從 Google Fonts 取得開放授權的字型系列

<指令> -h 可列出所有選項。

3. 確保輸出與桌面應用程式完全相同的規則

  1. 缺少字型或圖片會停止匯出。 Scribus 會靜默地替換缺少的字型,導致版面偏移。sla export 會拒絕並列出缺少的項目。 安裝字型(sla fonts --add/--google)或修正圖片路徑。僅在使用者接受時才傳遞 --allow-missing。 字型名稱必須完全匹配,例如 Latin Modern Sans 10 Bold、DejaVu Sans Book。
  2. 圖片連結是相對於 .sla 檔案的路徑。 確保存放文件及其素材的相對位置與使用者電腦上的一致,否則圖框會匯出為空白。
  3. 匯出使用文件儲存的 PDF 設定(壓縮、PDF 版本、字型)。僅在要求時覆蓋:--lossless、--outline-fonts、--pdf-version、--pdf-option KEY=VALUE。
  4. 可填寫 PDF 可直接運作。 對於含有表單欄位的文件,此工具會完整嵌入欄位字型,就像桌面匯出對話框所做的一樣。(單純以腳本匯出會在此處崩潰;請勿使用外框字型來繞過此問題。)
  5. 檢查結果。 在任何建立/填充/編輯之後:sla export FILE.sla -f png --dpi 72 -d /tmp/preview 並檢視 PNG。如果存在參考 PDF,則執行 sla compare 並預期在 0.0000% 時顯示 MATCH。
  6. 格式說明。 PNG/JPG 來自 Scribus 自己的「儲存為圖片」(使用 --raster-via pdf 來改為從 PDF 點陣化;尺寸可能相差一個像素)。SVG 和 PS 是從匯出的 PDF 轉換而來(SVG 中的文字會變成外框)。EPS 是 Scribus 自己的格式,每頁一個檔案。

4. 填充範本

  • 在範本文字中放置 {{name}};--set name=value 會取代所有出現的地方。一個佔位符必須位於同一個格式區塊中(一次輸入完成,字型和大小保持一致)。
  • --text ITEM=value 會取代名為 ITEM 的框架的整個文字,保留其第一個區塊的格式;\n 表示開始新段落。名稱是 sla inspect -v 顯示的項目名稱(Scribus:屬性 > 名稱)。
  • --image ITEM_OR_OLD_FILENAME=new.png 會重新連結圖片並使其符合圖框大小。加上 --keep-image-scale 則保留舊的比例。
  • --data file.json 接受 {"placeholders": {}, "text": {}, "images": {}}。使用 --strict 會在某個鍵未匹配任何項目時失敗。
  • 結果會由 Scribus 重新儲存,因此是真正的 Scribus 檔案。

5. 建立新文件

編寫一個 scripter 腳本並使用 sla run 執行。一個完整且經過測試的範例已安裝在 /opt/sla/kit/examples/new_document.py(頁面設定、顏色、樣式、文字、形狀、線條、圖片、儲存)。複製並修改。要點:

  • 將腳本包裝在 try: ... finally: os._exit(0) 中,否則 Scribus 永遠不會結束。
  • 先定義顏色和樣式;為每個物件命名(createText(x, y, w, h, "name"))。
  • \r 在 setText 中分隔段落。單位取決於 newDocument 的設定(建議使用點)。
  • setScaleImageToFrame(True, True, name) 會將圖片符合圖框大小,並保持比例。
  • 使用 saveDocAs(path) 儲存,然後執行 sla inspect 並預覽(規則 5)。
  • 若要符合現有的風格指南,請先對使用者的一份文件執行 sla inspect -v,然後重複使用其頁面大小、字型、顏色和線條粗細。

6. 編輯現有文件

偏好使用 scripter 腳本(openDoc,依名稱修改物件,saveDocAs)。在 XML 中進行小屬性的編輯也可以;事後執行 sla resave 並預覽。Scribus 1.6 的實用 XML 知識:

  • 根元素為 SCRIBUSUTF8NEW,內含一個 DOCUMENT。物件為 PAGEOBJECT(頁面)、MASTEROBJECT(主版頁面)、FRAMEOBJECT(內嵌)。PTYPE:2 為圖片,4 為文字,5 為線條,6 為形狀,7 為折線,12 為群組。
  • 頁面堆疊在一個畫布上:物件的 XPOS/YPOS 包含其所屬頁面的 PAGEXPOS/PAGEYPOS。
  • 文字存在於 StoryText 中:ITEXT CH="..." 區塊、para、trail。字型為 FONT="..." 屬性。
  • 圖片:PFILE(相對於 .sla 檔案的路徑)。SCALETYPE="0" 為符合圖框(Scribus 會在載入時重新計算縮放比例),SCALETYPE="1" 為自由縮放(使用 LOCALSCX/LOCALSCY/LOCALX/LOCALY);RATIO="1" 表示保持比例。
  • 文字框架的 path/copath 屬性包含其形狀;同時修改它們以及 WIDTH/HEIGHT(或使用 scripter 腳本中的 sizeObject 來調整大小,它會自動處理)。
  • 表單欄位:ANNOTATION="1" 的文字框架,ANTYPE 3 為文字,4 為核取方塊,5 為下拉式清單,6 為清單。
  • 除非被要求,否則不要覆蓋使用者的原始檔案;改為寫入新檔案。

7. 如果發生錯誤

  • 顯示「Scribus exited ... crashed」:執行 sla inspect,修正缺少的字型/圖片,嘗試 sla resave 查看檔案是否能載入,然後逐頁匯出(--pages N)以找出問題物件。
  • 引擎建置失敗:執行 bash /opt/sla/kit/scripts/setup.sh native 安裝發行版的 Scribus(測試中,其匯出也與參考檔案相符;儲存的檔案會帶有該版本資訊)。
  • 使用者文件所需的字型並非開放授權(例如 Arial、Calibri):向使用者索取字型檔案。

相關技能